[#46] Extract adventure embedded documents into folders by type (#68)

Co-authored-by: fyorl <kim.mantas@gmail.com>

Author: arbron

README.md

@@ -213,7 +213,7 @@ Extract the contents of a compendium pack into individual source files for each
     * **transformEntry:** *(entry: object): Promise<false|void>* A function that is called on every entry. Returning *false* indicates that the entry should be discarded.
     * **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 emebdded 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}`.
+    * **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.
     * **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.

lib/package.mjs

@@ -48,7 +48,8 @@ import { ClassicLevel } from "classic-level";
  * @property {boolean} [folders]                      Create a directory structure that matches the compendium folders.
  * @property {boolean} [expandAdventures]             Write documents embedded in Adventures to their own files. If the
  *                                                    folders option is also supplied, the Adventure is treated like a
- *                                                    folder.
+ *                                                    folder, and all its entries are grouped into sub-folders by
+ *                                                    Document type.
  * @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
@@ -486,22 +487,10 @@ async function extractClassicLevel(pack, dest, {
   const db = new ClassicLevel(pack, { keyEncoding: "utf8", valueEncoding: "json", createIfMissing: false });
 
   // Build up the folder structure
-  const folderMap = new Map();
+  let folderMap = new Map();
   if ( folders ) {
-    for await ( const [key, doc] of db.iterator() ) {
-      if ( !key.startsWith("!folders") ) continue;
-      let name = await transformFolderName?.(doc);
-      if ( !name ) name = doc.name ? `${getSafeFilename(doc.name)}_${doc._id}` : key;
-      folderMap.set(doc._id, { name, folder: doc.folder });
-    }
-    for ( const folder of folderMap.values() ) {
-      let parent = folderMap.get(folder.folder);
-      folder.path = folder.name;
-      while ( parent ) {
-        folder.path = path.join(parent.name, folder.path);
-        parent = folderMap.get(parent.folder);
-      }
-    }
+    const keys = (await db.keys().all()).filter(k => k.startsWith("!folders"));
+    folderMap = await buildFolderMap(await db.getMany(keys), { transformFolderName });
   }
 
   const unpackDoc = applyHierarchy(async (doc, collection, { sublevelPrefix, idPrefix }={}) => {
@@ -556,7 +545,7 @@ async function extractClassicLevel(pack, dest, {
  * @param {Partial<ExtractOptions>} [extractOptions]  Options to configure serialization behavior.
  */
 async function extractAdventure(doc, dest, { folderMap }={}, {
-  yaml, yamlOptions, jsonOptions, log, folders, transformEntry, transformName
+  yaml, yamlOptions, jsonOptions, log, folders, transformEntry, transformName, transformFolderName
 }={}) {
   let adventureFolder;
 
@@ -572,21 +561,32 @@ async function extractAdventure(doc, dest, { folderMap }={}, {
       if ( folder ) name = path.join(folder, name);
     }
   }
+  const context = { adventure: { doc, path: name } };
+
+  // Build up the folder structure
+  const embeddedFolderMap = folders
+    ? await buildFolderMap(doc.folders ?? [], { groupByType: true, transformFolderName })
+    : new Map();
 
   // Write all documents contained in the adventure
-  const context = { adventure: { doc, path: name } };
   for ( const embeddedCollectionName of ADVENTURE_DOCS ) {
     const paths = [];
     for ( const embeddedDoc of doc[embeddedCollectionName] ?? [] ) {
       if ( await transformEntry?.(embeddedDoc, context) === false ) continue;
-      let embeddedName = await transformName?.(embeddedDoc, context);
+      let embeddedFolder = path.join(adventureFolder ?? "", embeddedFolderMap.get(embeddedDoc.folder)?.path ?? "");
+      let embeddedName = await transformName?.(embeddedDoc, { ...context, folder: embeddedFolder });
       if ( !embeddedName ) {
         const { name, _id: id } = embeddedDoc;
-        embeddedName = `${name ? `${getSafeFilename(name)}_${id}` : doc._id}.${yaml ? "yml" : "json"}`;
-        if ( adventureFolder ) embeddedName = path.join(adventureFolder, embeddedName);
+        if ( (embeddedCollectionName === "folders") && embeddedFolderMap.has(embeddedDoc._id) ) {
+          embeddedFolder = adventureFolder;
+          embeddedName = path.join(embeddedFolderMap.get(embeddedDoc._id).path, `_Folder.${yaml ? "yml" : "json"}`);
+        } else {
+          embeddedName = `${name ? `${getSafeFilename(name)}_${id}` : doc._id}.${yaml ? "yml" : "json"}`;
+        }
+        if ( embeddedFolder ) embeddedName = path.join(embeddedFolder, embeddedName);
       }
       const filename = path.join(dest, embeddedName);
-      paths.push(path.basename(embeddedName));
+      paths.push(adventureFolder ? path.relative(adventureFolder, embeddedName) : path.basename(embeddedName));
       serializeDocument(embeddedDoc, filename, { yaml, yamlOptions, jsonOptions });
       if ( log ) console.log(`Wrote ${chalk.blue(embeddedName)}`);
     }
@@ -624,6 +624,35 @@ function applyHierarchy(fn) {
 
 /* -------------------------------------------- */
 
+/**
+ * Build up the folder structure used to extract files.
+ * @param {object[]} folders                               Folders to process.
+ * @param {object} [options={}]
+ * @param {boolean} [options.groupByType=false]            Should folders be in sub-folders based on document type?
+ * @param {NameTransformer} [options.transformFolderName]  Name transformer.
+ * @returns {Map<string, string>}                          Mapping of folder IDs to paths.
+ */
+async function buildFolderMap(folders, { groupByType=false, transformFolderName }={}) {
+  const folderMap = new Map();
+  for ( const doc of folders ) {
+    let name = await transformFolderName?.(doc);
+    if ( !name ) name = doc.name ? `${getSafeFilename(doc.name)}_${doc._id}` : doc._id;
+    folderMap.set(doc._id, { name, folder: doc.folder, type: doc.type });
+  }
+  for ( const folder of folderMap.values() ) {
+    let parent = folderMap.get(folder.folder);
+    folder.path = folder.name;
+    while ( parent ) {
+      folder.path = path.join(parent.name, folder.path);
+      parent = folderMap.get(parent.folder);
+    }
+    if ( groupByType ) folder.path = path.join(folder.type, folder.path);
+  }
+  return folderMap;
+}
+
+/* -------------------------------------------- */
+
 /**
  * Transform a Document's embedded collections by applying a function to them.
  * @param {object} doc               The Document being operated on.