Force POSIX paths in extracted adventure entries. Add additional volatile fields. Ignore volatile fields on embedded children.

Author: Fyorl

CHANGELOG.md

@@ -1,3 +1,13 @@
+## 3.0.0
+
+### Breaking Changes
+ - (Jeff Hitchcock) Using the `--expandAdventures` option without `--folders` now adds the document type to the extracted entry's name to disambiguate it in cases where it shares a name and ID with another document in the adventure of a different type.
+ - File paths inside extracted adventure entries now always use POSIX delimiters, regardless of which OS the extraction occurs on.
+
+### Improvements
+ - Added `_stats.coreVersion` and `_stats.systemVersion` to the list of volatile fields ignored by the `--omitVolatile` flag.
+ - Volatile fields are now also ignored on embedded children.
+
 ## 2.0.0
 
 ### Fixes

README.md

@@ -214,7 +214,7 @@ Extract the contents of a compendium pack into individual source files for each
     * **transformName:** *(entry: object): Promise<string|void>* A function that is called on every entry. The value returned from this will be used as the entry's filename and must include the appropriate file extension. If nothing is returned, an auto-generated name will be used instead.
     * **transformFolderName:** *(entry: object): Promise<string|void>* A function used to generate a directory name for an extracted Folder document when the `folders` option is used.
     * **expandAdventures:** *boolean* Write documents embedded in Adventures to their own files. If the `folders` option is also supplied, the Adventure is treated like a folder, and written to `_Adventure.{yml|json}` instead of `_Folder.{yml|json}`. Additionally, all its entries are grouped into sub-folders by Document type.
-    * **omitVolatile:** *boolean* When unpacking, diff the candidate entry against an existing one and only write it if non-volatile fields have changed. Currently, `_stats.createdTime`, `_stats.modifiedTime`, and `_stats.lastModifiedBy` are considered volatile.
+    * **omitVolatile:** *boolean* When unpacking, diff the candidate entry against an existing one and only write it if non-volatile fields have changed. Currently, `_stats.createdTime`, `_stats.modifiedTime`, `_stats.lastModifiedBy`, `_stats.systemVersion`, and `_stats.coreVersion` are considered volatile.
     * **jsonOptions:** *object*
         * **replacer:** *(key: string, value: any): any|Array<string|number>* A replacer function or an array of property names in the object to include in the resulting string.
         * **space:** *string|number* A number of spaces or a string to use as indentation.

commands/package.mjs

@@ -32,8 +32,9 @@ import { compilePack, extractPack, TYPE_COLLECTION_MAP } from "../lib/package.mj
  *                                                      each contained document as its own entry in a folder.
  * @property {boolean} [omitVolatile]                   When unpacking, diff the candidate entry against an existing one
  *                                                      and only write it if non-volatile fields have changed.
- *                                                      Currently, _stats.createdTime, _stats.modifiedTime, and
- *                                                      _stats.lastModifiedBy are considered volatile.
+ *                                                      Currently, _stats.createdTime, _stats.modifiedTime,
+ *                                                      _stats.lastModifiedBy, _stats.systemVersion, and
+ *                                                      _stats.coreVersion are considered volatile.
  */
 
 /**
@@ -144,7 +145,7 @@ export function getCommand() {
       });
 
       yargs.option("omitVolatile", {
-        describe: "When unpacking, diff the candidate entry against an existing one and only write it if non-volatile fields have changed. Currently, _stats.createdTime, _stats.modifiedTime, and _stats.lastModifiedBy are considered volatile.",
+        describe: "When unpacking, diff the candidate entry against an existing one and only write it if non-volatile fields have changed. Currently, _stats.createdTime, _stats.modifiedTime, _stats.lastModifiedBy, _stats.systemVersion, and _stats.coreVersion are considered volatile.",
         type: "boolean"
       });
 

lib/package.mjs

@@ -53,8 +53,8 @@ import { ClassicLevel } from "classic-level";
  *                                                    Document type.
  * @property {boolean} [omitVolatile]                 Do not overwrite an existing entry if the new one has changes to
  *                                                    non-volatile fields. Currently, _stats.createdTime,
- *                                                    _stats.modifiedTime, and _stats.lastModifiedBy are considered
- *                                                    volatile.
+ *                                                    _stats.modifiedTime, _stats.lastModifiedBy, _stats.systemVersion,
+ *                                                    and _stats.coreVersion are considered volatile.
  * @property {DocumentCollection} [collection]        Required only for NeDB packs in order to generate a correct key.
  *                                                    Can be used instead of documentType if known.
  * @property {NameTransformer} [transformName]        A function that is used to generate a filename for the extracted
@@ -117,6 +117,15 @@ import { ClassicLevel } from "classic-level";
  * @returns {Promise<object|void>}  Options to supply to the next level of the hierarchy.
  */
 
+/**
+ * @callback HierarchyApplySyncCallback
+ * @param {object} doc         The Document being operated on.
+ * @param {string} collection  The Document's collection.
+ * @param {number|null} i      The Document's index in its parent collection.
+ * @param {object} [options]   Additional options supplied by the invocation on the level above this one.
+ * @returns {object|void}
+ */
+
 /**
  * @callback HierarchyMapCallback
  * @param {any} entry          The element stored in the collection.
@@ -213,6 +222,12 @@ export const TYPE_COLLECTION_MAP = {
  */
 export const COLLECTION_TYPE_MAP = Object.fromEntries(Object.entries(TYPE_COLLECTION_MAP).map(([k, v]) => [v, k]));
 
+/**
+ * When extracting an entry, if the newly-extracted entry has only these fields changed, then ignore it.
+ * @type {string[]}
+ */
+const VOLATILE_FIELDS = ["createdTime", "modifiedTime", "lastModifiedBy", "systemVersion", "coreVersion"];
+
 /* -------------------------------------------- */
 /*  Compiling                                   */
 /* -------------------------------------------- */
@@ -489,7 +504,7 @@ async function extractNedb(pack, dest, {
       name = `${doc.name ? `${getSafeFilename(doc.name)}_${doc._id}` : doc._id}.${yaml ? "yml" : "json"}`;
     }
     const filename = path.join(dest, name);
-    serializeDocument(checkVolatile(doc, name, { omitVolatile, existing, yaml }), filename, {
+    serializeDocument(checkVolatile(doc, name, { collection, omitVolatile, existing, yaml }), filename, {
       yaml, yamlOptions, jsonOptions
     });
     if ( log ) console.log(`Wrote ${chalk.blue(name)}`);
@@ -554,7 +569,7 @@ async function extractClassicLevel(pack, dest, {
       if ( folder ) name = path.join(folder, name);
     }
     const filename = path.join(dest, name);
-    serializeDocument(checkVolatile(doc, name, { omitVolatile, existing, yaml }), filename, {
+    serializeDocument(checkVolatile(doc, name, { collection, omitVolatile, existing, yaml }), filename, {
       yaml, yamlOptions, jsonOptions
     });
     if ( log ) console.log(`Wrote ${chalk.blue(name)}`);
@@ -617,8 +632,13 @@ async function extractAdventure(doc, dest, { folderMap }={}, {
         if ( embeddedFolder ) embeddedName = path.join(embeddedFolder, embeddedName);
       }
       const filename = path.join(dest, embeddedName);
-      paths.push(adventureFolder ? path.relative(adventureFolder, embeddedName) : path.basename(embeddedName));
-      serializeDocument(checkVolatile(embeddedDoc, embeddedName, { omitVolatile, existing, yaml }), filename, {
+      const embeddedPath =
+        adventureFolder ? path.relative(adventureFolder, embeddedName) : path.basename(embeddedName);
+      paths.push(path.posix.join(...embeddedPath.split(path.sep)));
+      serializeDocument(checkVolatile(embeddedDoc, embeddedName, {
+        omitVolatile, existing, yaml,
+        collection: embeddedCollectionName
+      }), filename, {
         yaml, yamlOptions, jsonOptions
       });
       if ( log ) console.log(`Wrote ${chalk.blue(embeddedName)}`);
@@ -659,6 +679,28 @@ function applyHierarchy(fn) {
 
 /* -------------------------------------------- */
 
+/**
+ * Wrap a synchronous function so that it can be applied recursively to a Document's hierarchy.
+ * @param {HierarchyApplySyncCallback} fn  The function to wrap.
+ * @returns {HierarchyApplySyncCallback}   The wrapped function.
+ */
+function applyHierarchySync(fn) {
+  return function apply(doc, collection, i, options={}) {
+    const newOptions = fn(doc, collection, i, options);
+    for ( const [embeddedCollectionName, type] of Object.entries(HIERARCHY[collection] ?? {}) ) {
+      const embeddedValue = doc[embeddedCollectionName];
+      if ( Array.isArray(type) && Array.isArray(embeddedValue) ) {
+        for ( let i = 0; i < embeddedValue.length; i++ ) {
+          apply(embeddedValue[i], embeddedCollectionName, i, newOptions);
+        }
+      }
+      else if ( embeddedValue ) apply(embeddedValue, embeddedCollectionName, -1, newOptions);
+    }
+  };
+}
+
+/* -------------------------------------------- */
+
 /**
  * Build up the folder structure used to extract files.
  * @param {object[]} folders                               Folders to process.
@@ -765,18 +807,25 @@ function serializeDocument(doc, filename, { yaml, yamlOptions, jsonOptions }={})
  * @param {boolean} [options.omitVolatile]  Only write changes if some non-volatile fields have changed.
  * @param {string} [options.existing]       The location of the existing file.
  * @param {boolean} [options.yaml]          Whether the existing files are formatted with YAML.
+ * @param {string} [options.collection]     The primaru Document collection, in order to perform hierarchical
+ *                                          operations.
  * @returns {object}                        The data to write. Either the candidate data, or the existing data.
  */
-function checkVolatile(doc, name, { omitVolatile, existing, yaml }={}) {
+function checkVolatile(doc, name, { omitVolatile, existing, yaml, collection }={}) {
   if ( !omitVolatile || !existing || !("_stats" in doc) ) return doc;
   const parse = yaml ? YAML.load : JSON.parse;
   try {
     const base = parse(fs.readFileSync(path.join(existing, name), { encoding: "utf8" }));
     if ( !base || !("_stats" in base) ) return doc;
     const copy = structuredClone(doc);
-    if ( "createdTime" in base._stats ) copy._stats.createdTime = base._stats.createdTime;
-    if ( "modifiedTime" in base._stats ) copy._stats.modifiedTime = base._stats.modifiedTime;
-    if ( "lastModifiedBy" in base._stats ) copy._stats.lastModifiedBy = base._stats.lastModifiedBy;
+    const apply = applyHierarchySync((a, collection, i) => {
+      const b = i === null ? base : i < 0 ? base[collection] : base[collection]?.[i];
+      if ( !b || !("_stats" in b) ) return;
+      for ( const p of VOLATILE_FIELDS ) {
+        if ( p in b._stats ) a._stats[p] = b._stats[p];
+      }
+    });
+    apply(copy, collection, null);
     return testEquality(base, copy) ? base : doc;
   } catch {
     return doc;