@weborigami/async-tree 0.6.0 → 0.6.2

package/index.ts

@@ -43,6 +43,18 @@ export type MapOptions = {
   value?: ValueKeyFn;
 };
 
+export interface SyncTree<MapType> {
+  child(key: any): MapType;
+  parent: MapType | null;
+  trailingSlashKeys: boolean;
+}
+
+export interface AsyncTree<MapType> {
+  child(key: any): Promise<MapType>;
+  parent: MapType | null;
+  trailingSlashKeys: boolean;
+}
+
 /**
  * A packed value is one that can be written to a file via fs.writeFile or into
  * an HTTP response via response.write, or readily converted to such a form.
@@ -56,7 +68,7 @@ export type PlainObject = {
   [key: string]: any;
 };
 
-export type ReduceFn = (values: any[], keys: any[], map: SyncOrAsyncMap) => any | Promise<any>;
+export type ReduceFn = (mapped: Map<any, any>, source: SyncOrAsyncMap) => any | Promise<any>;
 
 export type Stringlike = string | HasString;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",

package/shared.js

@@ -1,6 +1,5 @@
 // Exports for both Node.js and browser
 
-import { default as DeepObjectMap } from "./src/drivers/DeepObjectMap.js";
 import { default as ExplorableSiteMap } from "./src/drivers/ExplorableSiteMap.js";
 import { default as FileMap } from "./src/drivers/FileMap.js";
 import { default as FunctionMap } from "./src/drivers/FunctionMap.js";
@@ -14,6 +13,7 @@ export { default as ConstantMap } from "./src/drivers/ConstantMap.js";
 export { default as SyncMap } from "./src/drivers/SyncMap.js";
 export * as extension from "./src/extension.js";
 export * as jsonKeys from "./src/jsonKeys.js";
+export { default as reduce } from "./src/operations/reduce.js";
 export { default as scope } from "./src/operations/scope.js";
 export * as symbols from "./src/symbols.js";
 export * as trailingSlash from "./src/trailingSlash.js";
@@ -35,15 +35,14 @@ export { default as setParent } from "./src/utilities/setParent.js";
 export { default as toPlainValue } from "./src/utilities/toPlainValue.js";
 export { default as toString } from "./src/utilities/toString.js";
 
-export {
-  DeepObjectMap,
-  ExplorableSiteMap,
-  FileMap,
-  FunctionMap,
-  ObjectMap,
-  SetMap,
-  SiteMap,
-};
+export { ExplorableSiteMap, FileMap, FunctionMap, ObjectMap, SetMap, SiteMap };
+
+export class DeepObjectMap extends ObjectMap {
+  constructor(object) {
+    super(object, { deep: true });
+    console.warn("DeepObjectMap is deprecated. Please use ObjectMap instead.");
+  }
+}
 
 export class ObjectTree extends ObjectMap {
   constructor(...args) {
@@ -52,12 +51,10 @@ export class ObjectTree extends ObjectMap {
   }
 }
 
-export class DeepObjectTree extends DeepObjectMap {
-  constructor(...args) {
-    super(...args);
-    console.warn(
-      "DeepObjectTree is deprecated. Please use DeepObjectMap instead."
-    );
+export class DeepObjectTree extends ObjectMap {
+  constructor(object) {
+    super(object, { deep: true });
+    console.warn("DeepObjectTree is deprecated. Please use ObjectMap instead.");
   }
 }
 

package/src/Tree.js

@@ -6,6 +6,7 @@ export { default as addNextPrevious } from "./operations/addNextPrevious.js";
 export { default as assign } from "./operations/assign.js";
 export { default as cache } from "./operations/cache.js";
 export { default as calendar } from "./operations/calendar.js";
+export { default as child } from "./operations/child.js";
 export { default as clear } from "./operations/clear.js";
 export { default as constant } from "./operations/constant.js";
 export { default as deepEntries } from "./operations/deepEntries.js";
@@ -49,10 +50,12 @@ export { default as paginate } from "./operations/paginate.js";
 export { default as parent } from "./operations/parent.js";
 export { default as paths } from "./operations/paths.js";
 export { default as plain } from "./operations/plain.js";
+export { default as reduce } from "./operations/reduce.js";
 export { default as regExpKeys } from "./operations/regExpKeys.js";
 export { default as reverse } from "./operations/reverse.js";
 export { default as root } from "./operations/root.js";
 export { default as scope } from "./operations/scope.js";
+export { default as set } from "./operations/set.js";
 export { default as shuffle } from "./operations/shuffle.js";
 export { default as size } from "./operations/size.js";
 export { default as sort } from "./operations/sort.js";

package/src/drivers/AsyncMap.js

@@ -1,5 +1,13 @@
+import isMap from "../operations/isMap.js";
 import * as trailingSlash from "../trailingSlash.js";
 
+/**
+ * Base class for asynchronous maps. These have the same interface as Map but the methods
+ * are asynchronous.
+ *
+ * @typedef {import("../../index.ts").AsyncTree<AsyncMap>} AsyncTree
+ * @implements {AsyncTree}
+ */
 export default class AsyncMap {
   /** @type {AsyncMap|null} */
   _parent = null;
@@ -10,15 +18,34 @@ export default class AsyncMap {
     return this.entries();
   }
 
+  /**
+   * Return the child node for the given key, creating it if necessary.
+   */
+  async child(key) {
+    let result = await this.get(key);
+
+    // If child is already a map we can use it as is
+    if (!isMap(result)) {
+      // Create new child node using no-arg constructor
+      result = new /** @type {any} */ (this.constructor)();
+      await this.set(key, result);
+    }
+
+    result.parent = this;
+    return result;
+  }
+
   /**
    * Remove all key/value entries from the map.
    *
    * This method invokes the `keys()` and `delete()` methods.
    */
   async clear() {
+    const promises = [];
     for await (const key of this.keys()) {
-      await this.delete(key);
+      promises.push(this.delete(key));
     }
+    await Promise.all(promises);
   }
 
   /**
@@ -32,8 +59,6 @@ export default class AsyncMap {
     throw new Error("delete() not implemented");
   }
 
-  static EMPTY = Symbol("EMPTY");
-
   /**
    * Returns a new `AsyncIterator` object that contains a two-member array of
    * [key, value] for each element in the map in insertion order.
@@ -191,6 +216,8 @@ export default class AsyncMap {
     })();
   }
 
+  trailingSlashKeys = false;
+
   /**
    * Returns a new `AsyncIterator` object that contains the values for each
    * element in the map in insertion order.

package/src/drivers/BrowserFileMap.js

@@ -1,6 +1,5 @@
 import { hiddenFileNames } from "../constants.js";
-import assign from "../operations/assign.js";
-import isMaplike from "../operations/isMaplike.js";
+import isMap from "../operations/isMap.js";
 import * as trailingSlash from "../trailingSlash.js";
 import isStringlike from "../utilities/isStringlike.js";
 import naturalOrder from "../utilities/naturalOrder.js";
@@ -30,13 +29,35 @@ export default class BrowserFileMap extends AsyncMap {
     this.directory = directoryHandle;
   }
 
+  async child(key) {
+    const normalized = trailingSlash.remove(key);
+    let result = await this.get(normalized);
+
+    // If child is already a map we can use it as is
+    if (!isMap(result)) {
+      // Create subfolder
+      const directory = await this.getDirectory();
+      if (result) {
+        // Delete existing file with same name
+        await directory.removeEntry(normalized);
+      }
+      const subfolderHandle = await directory.getDirectoryHandle(normalized, {
+        create: true,
+      });
+      result = Reflect.construct(this.constructor, [subfolderHandle]);
+      setParent(result, this);
+    }
+
+    return result;
+  }
+
   async delete(key) {
-    const baseKey = trailingSlash.remove(key);
+    const normalized = trailingSlash.remove(key);
     const directory = await this.getDirectory();
 
     // Delete file.
     try {
-      await directory.removeEntry(baseKey);
+      await directory.removeEntry(normalized);
     } catch (error) {
       // If the file didn't exist, ignore the error.
       if (error instanceof DOMException && error.name === "NotFoundError") {
@@ -111,9 +132,9 @@ export default class BrowserFileMap extends AsyncMap {
     // @ts-ignore
     for await (const entryKey of directory.keys()) {
       // Check if the entry is a subfolder
-      const baseKey = trailingSlash.remove(entryKey);
+      const normalized = trailingSlash.remove(entryKey);
       const subfolderHandle = await directory
-        .getDirectoryHandle(baseKey)
+        .getDirectoryHandle(normalized)
         .catch(() => null);
       const isSubfolder = subfolderHandle !== null;
 
@@ -129,7 +150,7 @@ export default class BrowserFileMap extends AsyncMap {
   }
 
   async set(key, value) {
-    const baseKey = trailingSlash.remove(key);
+    const normalized = trailingSlash.remove(key);
     const directory = await this.getDirectory();
 
     // Treat null value as empty string; will create an empty file.
@@ -152,24 +173,12 @@ export default class BrowserFileMap extends AsyncMap {
 
     if (isWriteable) {
       // Write file.
-      const fileHandle = await directory.getFileHandle(baseKey, {
+      const fileHandle = await directory.getFileHandle(normalized, {
         create: true,
       });
       const writable = await fileHandle.createWritable();
       await writable.write(value);
       await writable.close();
-    } else if (value === /** @type {any} */ (this.constructor).EMPTY) {
-      // Create empty subtree.
-      await directory.getDirectoryHandle(baseKey, {
-        create: true,
-      });
-    } else if (isMaplike(value)) {
-      // Treat value as a tree and write it out as a subdirectory.
-      const subdirectory = await directory.getDirectoryHandle(baseKey, {
-        create: true,
-      });
-      const destTree = Reflect.construct(this.constructor, [subdirectory]);
-      await assign(destTree, value);
     } else {
       const typeName = value?.constructor?.name ?? "unknown";
       throw new TypeError(`Cannot write a value of type ${typeName} as ${key}`);
@@ -178,7 +187,5 @@ export default class BrowserFileMap extends AsyncMap {
     return this;
   }
 
-  get trailingSlashKeys() {
-    return true;
-  }
+  trailingSlashKeys = true;
 }

package/src/drivers/CalendarMap.js

@@ -80,8 +80,6 @@ export default class CalendarMap extends SyncMap {
       (_, i) => this.start.year + i
     )[Symbol.iterator]();
   }
-
-  trailingSlashKeys = false;
 }
 
 function dateParts(date) {

package/src/drivers/ConstantMap.js

@@ -24,7 +24,5 @@ export default class ConstantTree extends SyncMap {
     return [][Symbol.iterator]();
   }
 
-  get trailingSlashKeys() {
-    return true;
-  }
+  trailingSlashKeys = true;
 }

package/src/drivers/ExplorableSiteMap.js

@@ -53,4 +53,6 @@ export default class ExplorableSiteMap extends SiteMap {
 
     return super.processResponse(response);
   }
+
+  trailingSlashKeys = true;
 }

package/src/drivers/FileMap.js

@@ -2,8 +2,6 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { hiddenFileNames } from "../constants.js";
-import from from "../operations/from.js";
-import isMaplike from "../operations/isMaplike.js";
 import * as trailingSlash from "../trailingSlash.js";
 import isPacked from "../utilities/isPacked.js";
 import isStringlike from "../utilities/isStringlike.js";
@@ -39,6 +37,26 @@ export default class FileMap extends SyncMap {
       : path.resolve(process.cwd(), location);
   }
 
+  // Return the (possibly new) subdirectory with the given key.
+  child(key) {
+    const stringKey = key != null ? String(key) : "";
+    const baseKey = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, baseKey);
+    const destTree = Reflect.construct(this.constructor, [destPath]);
+
+    const stats = getStats(destPath);
+    if (stats === null || !stats.isDirectory()) {
+      if (stats !== null) {
+        // File with the same name exists; delete it.
+        fs.rmSync(destPath);
+      }
+      // Ensure the directory exists.
+      fs.mkdirSync(destPath, { recursive: true });
+    }
+
+    return destTree;
+  }
+
   delete(key) {
     if (key === "" || key == null) {
       // Can't have a file with no name or a nullish name
@@ -76,14 +94,9 @@ export default class FileMap extends SyncMap {
     key = trailingSlash.remove(key); // normalize key
     const filePath = path.resolve(this.dirname, key);
 
-    let stats;
-    try {
-      stats = fs.statSync(filePath);
-    } catch (/** @type {any} */ error) {
-      if (error.code === "ENOENT" /* File not found */) {
-        return undefined;
-      }
-      throw error;
+    const stats = getStats(filePath);
+    if (stats === null) {
+      return undefined; // File or directory doesn't exist
     }
 
     let value;
@@ -140,13 +153,19 @@ export default class FileMap extends SyncMap {
   set(key, value) {
     // Where are we going to write this value?
     const stringKey = key != null ? String(key) : "";
-    const baseKey = trailingSlash.remove(stringKey);
-    const destPath = path.resolve(this.dirname, baseKey);
+    const normalized = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, normalized);
 
     // Ensure this directory exists.
     const dirname = path.dirname(destPath);
     fs.mkdirSync(dirname, { recursive: true });
 
+    if (value === undefined) {
+      // Special case: undefined value is equivalent to delete()
+      this.delete(normalized);
+      return this;
+    }
+
     if (typeof value === "function") {
       // Invoke function; write out the result.
       value = value();
@@ -179,10 +198,6 @@ export default class FileMap extends SyncMap {
 
     if (packed) {
       writeFile(value, destPath);
-    } else if (value === /** @type {any} */ (this.constructor).EMPTY) {
-      clearDirectory(destPath, this);
-    } else if (isMaplike(value)) {
-      writeDirectory(value, destPath, this);
     } else {
       const typeName = value?.constructor?.name ?? "unknown";
       throw new TypeError(
@@ -193,53 +208,31 @@ export default class FileMap extends SyncMap {
     return this;
   }
 
-  get trailingSlashKeys() {
-    return true;
-  }
-}
-
-// Create the indicated directory.
-function clearDirectory(destPath, parent) {
-  const destTree = Reflect.construct(parent.constructor, [destPath]);
-
-  // Ensure the directory exists.
-  fs.mkdirSync(destPath, { recursive: true });
-
-  // Clear any existing files
-  destTree.clear();
-
-  return destTree;
+  trailingSlashKeys = true;
 }
 
-/**
- * Treat value as a subtree and write it out as a subdirectory.
- *
- * @param {import("../../index.ts").Maplike} value
- */
-function writeDirectory(value, destPath, parent) {
-  // Since value is Maplike, result will be a Map
-  /** @type {Map} */
-  // @ts-ignore
-  const valueMap = from(value);
-  const destTree = clearDirectory(destPath, parent);
-
-  // Write out the subtree.
-  for (const key of valueMap.keys()) {
-    const childValue = valueMap.get(key);
-    destTree.set(key, childValue);
+// Return stats for the path, or null if it doesn't exist.
+function getStats(filePath) {
+  let stats;
+  try {
+    stats = fs.statSync(filePath);
+  } catch (/** @type {any} */ error) {
+    if (error.code === "ENOENT" /* File not found */) {
+      return null;
+    }
+    throw error;
   }
+  return stats;
 }
 
 // Write a value to a file.
 function writeFile(value, destPath) {
-  // Write out the value as the contents of a file.
-  try {
-    fs.writeFileSync(destPath, value);
-  } catch (/** @type {any} */ error) {
-    if (error.code === "EISDIR" /* Is a directory */) {
-      throw new Error(
-        `Tried to overwrite a directory with a single file: ${destPath}`
-      );
-    }
+  // If path exists and it's a directory, delete the directory first.
+  const stats = getStats(destPath);
+  if (stats !== null && stats.isDirectory()) {
+    fs.rmSync(destPath, { recursive: true });
   }
+
+  // Write out the value as the contents of a file.
+  fs.writeFileSync(destPath, value);
 }

package/src/drivers/ObjectMap.js

@@ -1,10 +1,20 @@
 import * as symbols from "../symbols.js";
 import * as trailingSlash from "../trailingSlash.js";
+import isPlainObject from "../utilities/isPlainObject.js";
 import setParent from "../utilities/setParent.js";
 import SyncMap from "./SyncMap.js";
 
+/**
+ * Map wrapper for a JavaScript object or array
+ */
 export default class ObjectMap extends SyncMap {
-  constructor(object = {}) {
+  /**
+   * Wrap the given object in a `Map`.
+   *
+   * @param {any} object
+   * @param {{ deep?: boolean }} [options]
+   */
+  constructor(object = {}, options = {}) {
     super();
     // Note: we use `typeof` here instead of `instanceof Object` to allow for
     // objects such as Node's `Module` class for representing an ES module.
@@ -15,6 +25,7 @@ export default class ObjectMap extends SyncMap {
     }
     this.object = object;
     this.parent = object[symbols.parent] ?? null;
+    this.deep = options.deep === true;
   }
 
   delete(key) {
@@ -51,12 +62,20 @@ export default class ObjectMap extends SyncMap {
       value = value.bind(this.object);
     }
 
+    if (this.deep && (value instanceof Array || isPlainObject(value))) {
+      // Construct submap for sub-objects and sub-arrays
+      value = Reflect.construct(this.constructor, [value, { deep: true }]);
+    }
+
     return value;
   }
 
   /** @returns {boolean} */
   isSubtree(value) {
-    return value instanceof Map;
+    if (value instanceof Map) {
+      return true;
+    }
+    return this.deep && (value instanceof Array || isPlainObject(value));
   }
 
   keys() {
@@ -109,20 +128,13 @@ export default class ObjectMap extends SyncMap {
       delete this.object[existingKey];
     }
 
-    if (value === /** @type {any} */ (this.constructor).EMPTY) {
-      // Create empty subtree
-      value = Reflect.construct(this.constructor, []);
-    }
-
     // Set the value for the key.
     this.object[key] = value;
 
     return this;
   }
 
-  get trailingSlashKeys() {
-    return true;
-  }
+  trailingSlashKeys = true;
 }
 
 function findExistingKey(object, key) {

package/src/drivers/SiteMap.js

@@ -34,9 +34,9 @@ export default class SiteMap extends AsyncMap {
       );
     }
 
-    // A key with a trailing slash and no extension is for a folder; return a
-    // subtree without making a network request.
-    if (trailingSlash.has(key) && !key.includes(".")) {
+    // A key with a trailing slash is for a folder; return a subtree without
+    // making a network request.
+    if (trailingSlash.has(key)) {
       const href = new URL(key, this.href).href;
       const value = Reflect.construct(this.constructor, [href]);
       setParent(value, this);
@@ -112,9 +112,7 @@ export default class SiteMap extends AsyncMap {
     }
   }
 
-  get trailingSlashKeys() {
-    return true;
-  }
+  trailingSlashKeys = true;
 
   get url() {
     return new URL(this.href);

package/src/drivers/SyncMap.js

@@ -17,6 +17,9 @@ const previewSymbol = Symbol("preview");
  * also indicate children subtrees using the trailing slash convention: a key
  * for a subtree may optionally end with a slash. The get() and has() methods
  * support optional trailing slashes on keys.
+ *
+ * @typedef {import("../../index.ts").SyncTree<SyncMap>} SyncTree
+ * @implements {SyncTree}
  */
 export default class SyncMap extends Map {
   _initialized = false;
@@ -36,6 +39,23 @@ export default class SyncMap extends Map {
     this._self = this;
   }
 
+  /**
+   * Return the child node for the given key, creating it if necessary.
+   */
+  child(key) {
+    let result = this.get(key);
+
+    // If child is already a map we can use it as is
+    if (!(result instanceof Map)) {
+      // Create new child node using no-arg constructor
+      result = new /** @type {any} */ (this.constructor)();
+      this.set(key, result);
+    }
+
+    result.parent = this;
+    return result;
+  }
+
   /**
    * Removes all key/value entries from the map.
    *
@@ -68,8 +88,6 @@ export default class SyncMap extends Map {
     return super.delete.call(this._self, key);
   }
 
-  static EMPTY = Symbol("EMPTY");
-
   /**
    * Returns a new `Iterator` object that contains a two-member array of [key,
    * value] for each element in the map in insertion order.
@@ -191,11 +209,6 @@ export default class SyncMap extends Map {
     // necessary to let the constructor call `super()`.
     const target = this._self ?? this;
 
-    // Support EMPTY symbol to create empty subtrees
-    if (value === /** @type {any} */ (this.constructor).EMPTY) {
-      value = Reflect.construct(this.constructor, []);
-    }
-
     return super.set.call(target, key, value);
   }
 
@@ -219,6 +232,8 @@ export default class SyncMap extends Map {
     return this.entries();
   }
 
+  trailingSlashKeys = false;
+
   /**
    * Returns a new `Iterator` object that contains the values for each element
    * in the map in insertion order.

package/src/jsonKeys.js

@@ -1,5 +1,8 @@
+import entries from "./operations/entries.js";
 import from from "./operations/from.js";
+import isMap from "./operations/isMap.js";
 import keys from "./operations/keys.js";
+import * as trailingSlash from "./trailingSlash.js";
 
 /**
  * Given a tree node, return a JSON string that can be written to a .keys.json
@@ -14,7 +17,18 @@ import keys from "./operations/keys.js";
  */
 export async function stringify(maplike) {
   const tree = from(maplike);
-  let treeKeys = await keys(tree);
+
+  let treeKeys;
+  if (/** @type {any} */ (tree).trailingSlashKeys) {
+    treeKeys = await keys(tree);
+  } else {
+    // Use entries() to determine which keys are subtrees.
+    const treeEntries = await entries(tree);
+    treeKeys = treeEntries.map(([key, value]) =>
+      trailingSlash.toggle(key, isMap(value))
+    );
+  }
+
   // Skip the key `.keys.json` if present.
   treeKeys = treeKeys.filter((key) => key !== ".keys.json");
   const json = JSON.stringify(treeKeys);