@weborigami/async-tree 0.5.4 → 0.5.5

package/src/drivers/DeferredTree.js

@@ -1,4 +1,4 @@
-import { Tree } from "../internal.js";
+import from from "../operations/from.js";
 
 /**
  * A tree that is loaded lazily.
@@ -64,7 +64,7 @@ export default class DeferredTree {
     this.treePromise ??= this.loadResult().then((treelike) => {
       const options =
         this._deep !== undefined ? { deep: this._deep } : undefined;
-      this._tree = Tree.from(treelike, options);
+      this._tree = from(treelike, options);
       if (this._parentUntilLoaded) {
         // Now that the tree has been loaded, we can set its parent if it hasn't
         // already been set.

package/src/drivers/FileTree.js

@@ -1,16 +1,15 @@
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { Tree } from "../internal.js";
+import { hiddenFileNames } from "../constants.js";
+import assign from "../operations/assign.js";
+import isTreelike from "../operations/isTreelike.js";
 import * as trailingSlash from "../trailingSlash.js";
-import {
-  getRealmObjectPrototype,
-  hiddenFileNames,
-  isPacked,
-  isPlainObject,
-  naturalOrder,
-  setParent,
-} from "../utilities.js";
+import isPacked from "../utilities/isPacked.js";
+import isPlainObject from "../utilities/isPlainObject.js";
+import isStringlike from "../utilities/isStringlike.js";
+import naturalOrder from "../utilities/naturalOrder.js";
+import setParent from "../utilities/setParent.js";
 import limitConcurrency from "./limitConcurrency.js";
 
 // As of July 2025, Node doesn't provide any way to limit the number of
@@ -188,7 +187,7 @@ export default class FileTree {
       // Pack the value for writing.
       value = await value.pack();
       packed = true;
-    } else if (isStringLike(value)) {
+    } else if (isStringlike(value)) {
       // Value has a meaningful `toString` method, use that.
       value = String(value);
       packed = true;
@@ -199,13 +198,13 @@ export default class FileTree {
     } else if (isPlainObject(value) && Object.keys(value).length === 0) {
       // Special case: empty object means create an empty directory.
       await fs.mkdir(destPath, { recursive: true });
-    } else if (Tree.isTreelike(value)) {
+    } else if (isTreelike(value)) {
       // Treat value as a subtree and write it out as a subdirectory.
       const destTree = Reflect.construct(this.constructor, [destPath]);
       // Create the directory here, even if the subtree is empty.
       await fs.mkdir(destPath, { recursive: true });
       // Write out the subtree.
-      await Tree.assign(destTree, value);
+      await assign(destTree, value);
     } else {
       const typeName = value?.constructor?.name ?? "unknown";
       throw new TypeError(
@@ -238,27 +237,6 @@ async function isDirectory(entry, dirname) {
   return entry.isDirectory();
 }
 
-/**
- * Return true if the object is a string or object with a non-trival `toString`
- * method.
- *
- * @param {any} obj
- */
-function isStringLike(obj) {
-  if (typeof obj === "string") {
-    return true;
-  } else if (obj?.toString === undefined) {
-    return false;
-  } else if (obj.toString === getRealmObjectPrototype(obj)?.toString) {
-    // The stupid Object.prototype.toString implementation always returns
-    // "[object Object]", so if that's the only toString method the object has,
-    // we return false.
-    return false;
-  } else {
-    return true;
-  }
-}
-
 // Return the file information for the file/folder at the given path.
 // If it does not exist, return undefined.
 async function stat(filePath) {

package/src/drivers/FunctionTree.js

@@ -1,4 +1,4 @@
-import { setParent } from "../utilities.js";
+import setParent from "../utilities/setParent.js";
 
 /**
  * A tree defined by a function and an optional domain.

package/src/drivers/MapTree.js

@@ -1,6 +1,6 @@
-import { Tree } from "../internal.js";
+import isAsyncTree from "../operations/isAsyncTree.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { setParent } from "../utilities.js";
+import setParent from "../utilities/setParent.js";
 
 /**
  * A tree backed by a JavaScript `Map` object.
@@ -19,10 +19,10 @@ export default class MapTree {
    * Constructs a new `MapTree` instance. This `iterable` parameter can be a
    * `Map` instance, or any other iterable of key-value pairs.
    *
-   * @param {Iterable} [iterable]
+   * @param {Iterable} [source]
    */
-  constructor(iterable = []) {
-    this.map = new Map(iterable);
+  constructor(source = []) {
+    this.map = source instanceof Map ? source : new Map(source);
     this.parent = null;
   }
 
@@ -52,7 +52,7 @@ export default class MapTree {
 
   /** @returns {boolean} */
   isSubtree(value) {
-    return Tree.isAsyncTree(value);
+    return isAsyncTree(value);
   }
 
   async keys() {

package/src/drivers/ObjectTree.js

@@ -1,7 +1,8 @@
-import { Tree } from "../internal.js";
+import isAsyncTree from "../operations/isAsyncTree.js";
 import * as symbols from "../symbols.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { getRealmObjectPrototype, setParent } from "../utilities.js";
+import getRealmObjectPrototype from "../utilities/getRealmObjectPrototype.js";
+import setParent from "../utilities/setParent.js";
 
 /**
  * A tree defined by a plain object or array.
@@ -72,7 +73,7 @@ export default class ObjectTree {
 
   /** @returns {boolean} */
   isSubtree(value) {
-    return Tree.isAsyncTree(value);
+    return isAsyncTree(value);
   }
 
   /**

package/src/drivers/SetTree.js

@@ -1,4 +1,4 @@
-import { setParent } from "../utilities.js";
+import setParent from "../utilities/setParent.js";
 
 /**
  * A tree of Set objects.

package/src/drivers/SiteTree.js

@@ -1,5 +1,5 @@
 import * as trailingSlash from "../trailingSlash.js";
-import { setParent } from "../utilities.js";
+import setParent from "../utilities/setParent.js";
 
 /**
  * A tree of values obtained via HTTP/HTTPS calls. These values will be strings

package/src/drivers/constantTree.js

@@ -1,4 +1,4 @@
-import { trailingSlash } from "../../main.js";
+import * as trailingSlash from "../trailingSlash.js";
 
 /**
  * A tree that returns a constant value for any key. If the key ends with a

package/src/extension.js

@@ -1,5 +1,6 @@
 import * as trailingSlash from "./trailingSlash.js";
-import { isStringLike, toString } from "./utilities.js";
+import isStringlike from "./utilities/isStringlike.js";
+import toString from "./utilities/toString.js";
 
 /**
  * Replicate the logic of Node POSIX path.extname at
@@ -78,7 +79,7 @@ export function extname(path) {
  * dot.
  */
 export function match(key, ext) {
-  if (!isStringLike(key)) {
+  if (!isStringlike(key)) {
     return null;
   }
   key = toString(key);
@@ -113,9 +114,10 @@ export function match(key, ext) {
  * @param {string} resultExtension
  */
 export function replace(key, sourceExtension, resultExtension) {
-  if (!isStringLike(key)) {
+  if (!isStringlike(key)) {
     return null;
   }
+  // @ts-ignore
   key = toString(key);
 
   if (!match(key, sourceExtension)) {

package/src/jsonKeys.js

@@ -1,6 +1,9 @@
-import { Tree } from "./internal.js";
+import from from "./operations/from.js";
 
 /**
+ * Given a tree node, return a JSON string that can be written to a .keys.json
+ * file.
+ *
  * The JSON Keys protocol lets a site expose the keys of a node in the site so
  * that they can be read by SiteTree.
  *
@@ -8,13 +11,8 @@ import { Tree } from "./internal.js";
  * "index.html" for a specific resource available at the node, or a string with
  * a trailing slash like "about/" for a subtree of that node.
  */
-
-/**
- * Given a tree node, return a JSON string that can be written to a .keys.json
- * file.
- */
 export async function stringify(treelike) {
-  const tree = Tree.from(treelike);
+  const tree = from(treelike);
   let keys = Array.from(await tree.keys());
   // Skip the key `.keys.json` if present.
   keys = keys.filter((key) => key !== ".keys.json");

package/src/operations/addNextPrevious.js

@@ -1,5 +1,7 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import entries from "./entries.js";
+import isTreelike from "./isTreelike.js";
+import plain from "./plain.js";
 
 /**
  * Add nextKey/previousKey properties to values.
@@ -11,21 +13,20 @@ import { assertIsTreelike } from "../utilities.js";
  * @returns {Promise<PlainObject|Array>}
  */
 export default async function addNextPrevious(treelike) {
-  assertIsTreelike(treelike, "addNextPrevious");
-  const tree = Tree.from(treelike);
+  const tree = await getTreeArgument(treelike, "addNextPrevious");
 
-  const entries = [...(await Tree.entries(tree))];
-  const keys = entries.map(([key]) => key);
+  const treeEntries = [...(await entries(tree))];
+  const keys = treeEntries.map(([key]) => key);
 
   // Map to an array of [key, result] pairs, where the result includes
   // nextKey/previousKey properties.
   const mappedEntries = await Promise.all(
-    entries.map(async ([key, value], index) => {
+    treeEntries.map(async ([key, value], index) => {
       let resultValue;
       if (value === undefined) {
         resultValue = undefined;
-      } else if (Tree.isTreelike(value)) {
-        resultValue = await Tree.plain(value);
+      } else if (isTreelike(value)) {
+        resultValue = await plain(value);
       } else if (typeof value === "object") {
         // Clone value to avoid modifying the original object
         resultValue = { ...value };

package/src/operations/assign.js

@@ -0,0 +1,40 @@
+import from from "./from.js";
+import isAsyncMutableTree from "./isAsyncMutableTree.js";
+import isAsyncTree from "./isAsyncTree.js";
+
+/**
+ * Apply the key/values pairs from the source tree to the target tree.
+ *
+ * If a key exists in both trees, and the values in both trees are
+ * subtrees, then the subtrees will be merged recursively. Otherwise, the
+ * value from the source tree will overwrite the value in the target tree.
+ *
+ * @typedef  {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} target
+ * @param {Treelike} source
+ */
+export default async function assign(target, source) {
+  const targetTree = from(target);
+  const sourceTree = from(source);
+  if (!isAsyncMutableTree(targetTree)) {
+    throw new TypeError("Target must be a mutable asynchronous tree");
+  }
+  // Fire off requests to update all keys, then wait for all of them to finish.
+  const keys = Array.from(await sourceTree.keys());
+  const promises = keys.map(async (key) => {
+    const sourceValue = await sourceTree.get(key);
+    if (isAsyncTree(sourceValue)) {
+      const targetValue = await targetTree.get(key);
+      if (isAsyncMutableTree(targetValue)) {
+        // Both source and target are trees; recurse.
+        await assign(targetValue, sourceValue);
+        return;
+      }
+    }
+    // Copy the value from the source to the target.
+    await /** @type {any} */ (targetTree).set(key, sourceValue);
+  });
+  await Promise.all(promises);
+  return targetTree;
+}

package/src/operations/cache.js

@@ -1,5 +1,8 @@
-import { ObjectTree, Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import ObjectTree from "../drivers/ObjectTree.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import from from "./from.js";
+import isAsyncMutableTree from "./isAsyncMutableTree.js";
+import isAsyncTree from "./isAsyncTree.js";
 
 /**
  * Caches values from a source tree in a second cache tree. Cache source tree
@@ -13,18 +16,21 @@ import { assertIsTreelike } from "../utilities.js";
  *
  * @param {Treelike} sourceTreelike
  * @param {AsyncMutableTree} [cacheTreelike]
- * @returns {AsyncTree & { description: string }}
+ * @returns {Promise}
  */
-export default function treeCache(sourceTreelike, cacheTreelike) {
-  assertIsTreelike(sourceTreelike, "cache");
-  const source = Tree.from(sourceTreelike);
+export default async function treeCache(sourceTreelike, cacheTreelike) {
+  const source = await getTreeArgument(sourceTreelike, "cache", {
+    position: 0,
+  });
 
   /** @type {AsyncMutableTree} */
   let cache;
   if (cacheTreelike) {
+    cache = /** @type {any} */ (
+      await getTreeArgument(cacheTreelike, "cache", { position: 1 })
+    );
     // @ts-ignore
-    cache = Tree.from(cacheTreelike);
-    if (!Tree.isAsyncMutableTree(cache)) {
+    if (!isAsyncMutableTree(cache)) {
       throw new Error("Cache tree must define a set() method.");
     }
   } else {
@@ -38,24 +44,24 @@ export default function treeCache(sourceTreelike, cacheTreelike) {
     async get(key) {
       // Check cache tree first.
       let cacheValue = await cache.get(key);
-      if (cacheValue !== undefined && !Tree.isAsyncTree(cacheValue)) {
+      if (cacheValue !== undefined && !isAsyncTree(cacheValue)) {
         // Leaf node cache hit
         return cacheValue;
       }
 
       // Cache miss or interior node cache hit.
       let value = await source.get(key);
-      if (Tree.isAsyncTree(value)) {
+      if (isAsyncTree(value)) {
         // Construct merged tree for a tree result.
         if (cacheValue === undefined) {
           // Construct new empty container in cache
           await cache.set(key, {});
           cacheValue = await cache.get(key);
-          if (!Tree.isAsyncTree(cacheValue)) {
+          if (!isAsyncTree(cacheValue)) {
             // Coerce to tree and then save it back to the cache. This is
             // necessary, e.g., if cache is an ObjectTree; we want the
             // subtree to also be an ObjectTree, not a plain object.
-            cacheValue = Tree.from(cacheValue);
+            cacheValue = from(cacheValue);
             await cache.set(key, cacheValue);
           }
         }

package/src/operations/cachedKeyFunctions.js

@@ -13,10 +13,11 @@ const treeMap = new Map();
  * are keys for subtrees, returning the source key unmodified.
  *
  * @typedef {import("../../index.ts").KeyFn} KeyFn
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
  * @param {KeyFn} keyFn
  * @param {boolean?} deep
- * @returns {{ key: KeyFn, inverseKey: KeyFn }}
+ * @returns {{ key: ValueKeyFn, inverseKey: KeyFn }}
  */
 export default function cachedKeyFunctions(keyFn, deep = false) {
   return {
@@ -40,10 +41,13 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
           continue;
         }
 
+        const sourceValue = await tree.get(sourceKey);
+
         const computedResultKey = await computeAndCacheResultKey(
           tree,
           keyFn,
           deep,
+          sourceValue,
           sourceKey
         );
 
@@ -59,7 +63,7 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
       return undefined;
     },
 
-    async key(sourceKey, tree) {
+    async key(sourceValue, sourceKey, tree) {
       const { sourceKeyToResultKey } = getKeyMapsForTreeKeyFn(tree, keyFn);
 
       const cachedResultKey = searchKeyMap(sourceKeyToResultKey, sourceKey);
@@ -71,6 +75,7 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
         tree,
         keyFn,
         deep,
+        sourceValue,
         sourceKey
       );
       return resultKey;
@@ -78,7 +83,13 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
   };
 }
 
-async function computeAndCacheResultKey(tree, keyFn, deep, sourceKey) {
+async function computeAndCacheResultKey(
+  tree,
+  keyFn,
+  deep,
+  sourceValue,
+  sourceKey
+) {
   const { resultKeyToSourceKey, sourceKeyToResultKey } = getKeyMapsForTreeKeyFn(
     tree,
     keyFn
@@ -87,7 +98,7 @@ async function computeAndCacheResultKey(tree, keyFn, deep, sourceKey) {
   const resultKey =
     deep && trailingSlash.has(sourceKey)
       ? sourceKey
-      : await keyFn(sourceKey, tree);
+      : await keyFn(sourceValue, sourceKey, tree);
 
   sourceKeyToResultKey.set(sourceKey, resultKey);
   resultKeyToSourceKey.set(resultKey, sourceKey);

package/src/operations/clear.js

@@ -0,0 +1,20 @@
+import from from "./from.js";
+import isAsyncMutableTree from "./isAsyncMutableTree.js";
+
+/**
+ * Remove all entries from the tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+export default async function clear(treelike) {
+  const tree = from(treelike);
+  if (!isAsyncMutableTree(tree)) {
+    throw new TypeError("clear: can't clear a read-only tree.");
+  }
+  const keys = Array.from(await tree.keys());
+  const promises = keys.map((key) => tree.set(key, undefined));
+  await Promise.all(promises);
+  return tree;
+}

package/src/operations/concat.js

@@ -0,0 +1,17 @@
+import deepText from "./deepText.js";
+import from from "./from.js";
+
+/**
+ * Concatenate the text content of objects or trees.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {any[]} args
+ */
+export default async function concat(...args) {
+  console.warn(
+    "Warning: the Tree.concat function is deprecated, use Tree.deepText instead."
+  );
+  const tree = from(args);
+  return deepText(tree);
+}

package/src/operations/deepMap.js

@@ -0,0 +1,25 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isPlainObject from "../utilities/isPlainObject.js";
+import map from "./map.js";
+
+/**
+ * Shorthand for calling `map` with the `deep: true` option.
+ *
+ * @typedef {import("../../index.ts").TreeMapOptions} TreeMapOptions
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {Treelike} treelike
+ * @param {ValueKeyFn|TreeMapOptions} options
+ * @returns {Promise<AsyncTree>}
+ */
+export default async function deepMap(treelike, options) {
+  const tree = await getTreeArgument(treelike, "deepMap", { deep: true });
+  const withDeep = isPlainObject(options)
+    ? // Dictionary
+      { ...options, deep: true }
+    : // Function
+      { deep: true, value: options };
+  return map(tree, withDeep);
+}

package/src/operations/deepMerge.js

@@ -1,16 +1,21 @@
-import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
+import from from "./from.js";
+import isAsyncTree from "./isAsyncTree.js";
+import isTreelike from "./isTreelike.js";
 
 /**
  * Return a tree that performs a deep merge of the given trees.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @param {import("../../index.ts").Treelike[]} sources
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike[]} sources
  * @returns {AsyncTree & { description: string }}
  */
 export default function deepMerge(...sources) {
-  let trees = sources.map((treelike) => Tree.from(treelike, { deep: true }));
-  let mergeParent;
+  const filtered = sources.filter((source) => source);
+  let trees = filtered.map((treelike) => from(treelike, { deep: true }));
+
   return {
     description: "deepMerge",
 
@@ -22,13 +27,9 @@ export default function deepMerge(...sources) {
         const tree = trees[index];
         const value = await tree.get(key);
         if (
-          Tree.isAsyncTree(value) ||
-          (Tree.isTreelike(value) && trailingSlash.has(key))
+          isAsyncTree(value) ||
+          (isTreelike(value) && trailingSlash.has(key))
         ) {
-          if (/** @type {any} */ (value).parent === tree) {
-            // Merged tree acts as parent instead of the source tree.
-            /** @type {any} */ (value).parent = this;
-          }
           subtrees.unshift(value);
         } else if (value !== undefined) {
           return value;
@@ -37,7 +38,6 @@ export default function deepMerge(...sources) {
 
       if (subtrees.length > 1) {
         const merged = deepMerge(...subtrees);
-        merged.parent = this;
         return merged;
       } else if (subtrees.length === 1) {
         return subtrees[0];
@@ -62,19 +62,5 @@ export default function deepMerge(...sources) {
       }
       return keys;
     },
-
-    get parent() {
-      return mergeParent;
-    },
-    set parent(parent) {
-      mergeParent = parent;
-      trees = sources.map((treelike) => {
-        const tree = Tree.isAsyncTree(treelike)
-          ? Object.create(treelike)
-          : Tree.from(treelike);
-        tree.parent = parent;
-        return tree;
-      });
-    },
   };
 }

package/src/operations/deepReverse.js

@@ -1,5 +1,5 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isAsyncTree from "./isAsyncTree.js";
 
 /**
  * Reverse the order of keys at all levels of the tree.
@@ -8,16 +8,15 @@ import { assertIsTreelike } from "../utilities.js";
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
  * @param {Treelike} treelike
- * @returns {AsyncTree}
+ * @returns {Promise<AsyncTree>}
  */
-export default function deepReverse(treelike) {
-  assertIsTreelike(treelike, "deepReverse");
+export default async function deepReverse(treelike) {
+  const tree = await getTreeArgument(treelike, "deepReverse", { deep: true });
 
-  const tree = Tree.from(treelike, { deep: true });
   return {
     async get(key) {
       let value = await tree.get(key);
-      if (Tree.isAsyncTree(value)) {
+      if (isAsyncTree(value)) {
         value = deepReverse(value);
       }
       return value;

package/src/operations/deepTake.js

@@ -1,5 +1,6 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import from from "./from.js";
+import isAsyncTree from "./isAsyncTree.js";
 
 /**
  * Returns a function that traverses a tree deeply and returns the values of the
@@ -12,11 +13,9 @@ import { assertIsTreelike } from "../utilities.js";
  * @param {number} count
  */
 export default async function deepTake(treelike, count) {
-  assertIsTreelike(treelike, "deepTake");
-  const tree = await Tree.from(treelike, { deep: true });
-
+  const tree = await getTreeArgument(treelike, "deepTake", { deep: true });
   const { values } = await traverse(tree, count);
-  return Tree.from(values, { deep: true });
+  return from(values, { deep: true });
 }
 
 async function traverse(tree, count) {
@@ -26,7 +25,7 @@ async function traverse(tree, count) {
       break;
     }
     let value = await tree.get(key);
-    if (Tree.isAsyncTree(value)) {
+    if (isAsyncTree(value)) {
       const traversed = await traverse(value, count);
       values.push(...traversed.values);
       count = traversed.count;

package/src/operations/deepText.js

@@ -1,4 +1,5 @@
-import { assertIsTreelike, toString } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import toString from "../utilities/toString.js";
 import deepValuesIterator from "./deepValuesIterator.js";
 
 /**
@@ -7,10 +8,9 @@ import deepValuesIterator from "./deepValuesIterator.js";
  * @param {import("../../index.ts").Treelike} treelike
  */
 export default async function deepText(treelike) {
-  assertIsTreelike(treelike, "text");
-
+  const tree = await getTreeArgument(treelike, "deepText", { deep: true });
   const strings = [];
-  for await (const value of deepValuesIterator(treelike, { expand: true })) {
+  for await (const value of deepValuesIterator(tree, { expand: true })) {
     let string;
     if (value === null) {
       string = "null";