Merge branch 'parse-narrative-in-client'

* parse-narrative-in-client:
  [client-narratives] update bundlesize config
  [client-narratives] change bundle structure to accommodate YAML parsing
  [client-narratives] modify markdown parser settings
  [client narratives] update documentation
  [client-narratives] parse markdown client-side
  [client-narratives] Allow client to gracefully fall-back to JSON
  [client-narratives] Allow narrative API to return unmodified markdown file

bundlesize.config.json

@@ -9,12 +9,12 @@
       "maxSize": "75 kB"
     },
     {
-      "path": "./dist/auspice.chunk.core-vendors.bundle.9b6a9c4b675fe63ec02a.js",
+      "path": "./dist/auspice.chunk.core-vendors.bundle.*.js",
       "maxSize": "220 kB"
     },
     {
-      "path": "./dist/auspice.chunk.other-vendors.bundle.99f3458f271574f53feb.js",
-      "maxSize": "60 kB"
+      "path": "./dist/auspice.chunk.other-vendors.bundle.*.js",
+      "maxSize": "80 kB"
     },
     {
       "path": "./dist/auspice.chunk.locales.bundle.*.js",

cli/server/getNarrative.js

@@ -1,24 +1,48 @@
 const queryString = require("query-string");
-const parseNarrative = require('./parseNarrative').default;
 const path = require("path");
 const fs = require("fs");
 const utils = require("../utils");
+const marked = require('marked');
+const { parseMarkdownNarrativeFile } = require("../../src/util/parseNarrative");
+
+/**
+ * A thin wrapper around the client-side `parseMarkdownNarrativeFile` function.
+ * The main difference is that we pass in a different markdown parser
+ * than the client uses.
+ */
+const parseNarrative = (fileContents) => {
+  utils.verbose("Deprecation warning: Server-side parsing of narrative files is no longer needed!");
+  return parseMarkdownNarrativeFile(fileContents, marked);
+};
 
 const setUpGetNarrativeHandler = ({narrativesPath}) => {
   return async (req, res) => {
-    const prefix = queryString.parse(req.url.split('?')[1]).prefix || "";
+    const query = queryString.parse(req.url.split('?')[1]);
+    const prefix = query.prefix || "";
     const filename = prefix
       .replace(/.+narratives\//, "")  // remove the URL up to (& including) "narratives/"
       .replace(/\/$/, "")             // remove ending slash
       .replace(/\//g, "_")            // change slashes to underscores
       .concat(".md");                 // add .md suffix
 
+    // the type-query string dictates whether to parse into JSON on the server or not
+    // we default to JSON which was behavior before this argument existed
+    const type = query.type ? query.type.toLowerCase() : "json";
+
     const pathName = path.join(narrativesPath, filename);
     utils.log("trying to access & parse local narrative file: " + pathName);
     try {
       const fileContents = fs.readFileSync(pathName, 'utf8');
-      const blocks = parseNarrative(fileContents);
-      res.send(JSON.stringify(blocks).replace(/</g, '\\u003c'));
+      if (type === "md" || type === "markdown") {
+        // we could stream the response (as we sometimes do for getDataset) but narrative files are small
+        // so the expected time savings / server overhead is small.
+        res.send(fileContents);
+      } else if (type === "json") {
+        const blocks = parseNarrative(fileContents);
+        res.send(JSON.stringify(blocks).replace(/</g, '\\u003c'));
+      } else {
+        throw new Error(`Unknown format requested: ${type}`);
+      }
       utils.verbose("SUCCESS");
     } catch (err) {
       const errorMessage = `Narratives couldn't be served -- ${err.message}`;
@@ -29,5 +53,6 @@ const setUpGetNarrativeHandler = ({narrativesPath}) => {
 };
 
 module.exports = {
-  setUpGetNarrativeHandler
+  setUpGetNarrativeHandler,
+  parseNarrative
 };

docs-src/docs/server/api.md

@@ -72,18 +72,31 @@ Any other non-200 reponse behaves similarly but also displays a large "error" me
 **URL query arguments:**
 
 * `prefix` (required) - the pathname of the requesting page in Auspice. Use this to determine which narrative to return.
+* `type` (optional) - the format of the data returned (see below for more information).
+Current valid values are "json" and "md".
+If no type is specified the server will use "json" as a default (for backwards compatibility reasons).
+Requests to this API from the Auspice client are made with `type=md.
 
-**JSON Response (on success):**
+**Response (on success):**
+
+The response depends on the `type` specified in the query.
+
+If a markdown format is requested, then the narrative file is sent to the client unmodified to be parsed on the client.
+
+If a JSON is requested then the narrative file is parsed into JSON format by the server.
+For Auspice versions <=XXX this was the only expected behavior.
+The transformation from markdown (i.e. the narrative file itself) to JSON is via the `parseNarrativeFile()` function (see below for how this is exported from Auspice for use in other servers).
+Here, roughly, is the code we use in the auspice server for this transformation:
 
-The output from the [parseNarrativeFile](server/api.md#parsenarrativefile) function defined below.
-For instance, here is the code from the default Auspice handler:
 ```js
 const fileContents = fs.readFileSync(pathName, 'utf8');
-const blocks = parseNarrative(fileContents);
-res.send(JSON.stringify(blocks).replace(/</g, '\\u003c'));
+if (type === "json") {
+  const blocks = parseNarrative(fileContents);
+  res.send(JSON.stringify(blocks).replace(/</g, '\\u003c'));
+}
 ```
 
-> Note that in a future version of Auspice we plan to move the parsing of the narrative to the client.
+> While the Auspice client (from vXXX onwards) always requests the `type=md`, it will attempt to parse the response as JSON if markdown parsing fails, in an effort to remain backwards compatable with servers which may be using an earlier API.
 
 ---
 
@@ -147,6 +160,10 @@ An object representing the v2 JSON [defined by this schema](https://github.com/n
 
 ### `parseNarrativeFile`
 
+> This function is deprecated as of vXXX.
+You can now send the untransformed contents of the narrative file (markdown) for client-side parsing.
+See [above](#charon-getnarrative) for more details.
+
 **Signature:**
 
 ```js

index.js

@@ -8,7 +8,7 @@
 
 
 const convertFromV1 = require("./cli/server/convertJsonSchemas").convertFromV1;
-const parseNarrativeFile = require("./cli/server/parseNarrative").default;
+const parseNarrativeFile = require("./cli/server/getNarrative").parseNarrative;
 
 module.exports = {
   convertFromV1,