@weborigami/async-tree 0.5.4 → 0.5.6

package/src/operations/map.js

@@ -1,8 +1,11 @@
-import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isPlainObject from "../utilities/isPlainObject.js";
+import isUnpackable from "../utilities/isUnpackable.js";
+import toFunction from "../utilities/toFunction.js";
 import cachedKeyFunctions from "./cachedKeyFunctions.js";
 import extensionKeyFunctions from "./extensionKeyFunctions.js";
+import isAsyncTree from "./isAsyncTree.js";
 import parseExtensions from "./parseExtensions.js";
 
 /**
@@ -11,107 +14,133 @@ import parseExtensions from "./parseExtensions.js";
  * @typedef {import("../../index.ts").KeyFn} KeyFn
  * @typedef {import("../../index.ts").TreeMapOptions} MapOptions
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @param {import("../../index.ts").Treelike} treelike
  * @param {MapOptions|ValueKeyFn} options
+ * @returns {Promise<AsyncTree>}
  */
-export default function map(treelike, options = {}) {
-  assertIsTreelike(treelike, "map");
-  const { deep, description, inverseKeyFn, keyFn, needsSourceValue, valueFn } =
-    validateOptions(options);
+export default async function map(treelike, options = {}) {
+  if (isUnpackable(options)) {
+    options = await options.unpack();
+  }
+  const validated = validateOptions(options);
+  const mapFn = createMapFn(validated);
+
+  const tree = await getTreeArgument(treelike, "map", { deep: validated.deep });
+  return mapFn(tree);
+}
+
+// Create a get() function for the map
+function createGet(tree, options, mapFn) {
+  const { inverseKeyFn, deep, valueFn } = options;
+  return async (resultKey) => {
+    if (resultKey === undefined) {
+      throw new ReferenceError(`map: Cannot get an undefined key.`);
+    }
+
+    // Step 1: Map the result key to the source key
+    let sourceKey = await inverseKeyFn?.(resultKey, tree);
+
+    if (sourceKey === undefined) {
+      if (deep && trailingSlash.has(resultKey)) {
+        // Special case: deep tree and value is expected to be a subtree
+        const sourceValue = await tree.get(resultKey);
+        // If we did get a subtree, apply the map to it
+        const resultValue = isAsyncTree(sourceValue)
+          ? mapFn(sourceValue)
+          : undefined;
+        return resultValue;
+      } else {
+        // No inverseKeyFn, or it returned undefined; use resultKey
+        sourceKey = resultKey;
+      }
+    }
+
+    // Step 2: Get the source value
+    let sourceValue = await tree.get(sourceKey);
+    if (deep && sourceValue === undefined) {
+      // Key might be for a subtree, see if original key exists
+      sourceValue = await tree.get(resultKey);
+    }
+
+    // Step 3: Map the source value to the result value
+    let resultValue;
+    if (sourceValue === undefined) {
+      // No source value means no result value
+      resultValue = undefined;
+    } else if (deep && isAsyncTree(sourceValue)) {
+      // We weren't expecting a subtree but got one; map it
+      resultValue = mapFn(sourceValue);
+    } else if (valueFn) {
+      // Map a single value
+      resultValue = await valueFn(sourceValue, sourceKey, tree);
+    } else {
+      // Return source value as is
+      resultValue = sourceValue;
+    }
+
+    return resultValue;
+  };
+}
+
+// Create a keys() function for the map
+function createKeys(tree, options) {
+  const { deep, keyFn, keyNeedsSourceValue } = options;
+  return async () => {
+    // Apply the keyFn to source keys for leaf values (not subtrees).
+    const sourceKeys = Array.from(await tree.keys());
+    const sourceValues = keyNeedsSourceValue
+      ? await Promise.all(sourceKeys.map((sourceKey) => tree.get(sourceKey)))
+      : sourceKeys.map(() => null);
+    const mapped = await Promise.all(
+      sourceKeys.map(async (sourceKey, index) =>
+        // Deep maps leave source keys for subtrees alone
+        deep && trailingSlash.has(sourceKey)
+          ? sourceKey
+          : await keyFn(sourceValues[index], sourceKey, tree)
+      )
+    );
+    // Filter out any cases where the keyFn returned undefined.
+    const resultKeys = mapped.filter((key) => key !== undefined);
+    return resultKeys;
+  };
+}
 
+// Create a map function for the given options
+function createMapFn(options) {
+  const { description, keyFn, valueFn } = options;
   /**
-   * @param {import("@weborigami/types").AsyncTree} tree
+   * @param {AsyncTree} tree
+   * @return {AsyncTree}
    */
-  function mapFn(tree) {
+  return function mapFn(tree) {
     // The transformed tree is actually an extension of the original tree's
     // prototype chain. This allows the transformed tree to inherit any
     // properties/methods. For example, the `parent` of the transformed tree is
     // the original tree's parent.
     const transformed = Object.create(tree);
-
     transformed.description = description;
-
     if (keyFn || valueFn) {
-      transformed.get = async (resultKey) => {
-        if (resultKey === undefined) {
-          throw new ReferenceError(`map: Cannot get an undefined key.`);
-        }
-
-        // Step 1: Map the result key to the source key
-        let sourceKey = await inverseKeyFn?.(resultKey, tree);
-
-        if (sourceKey === undefined) {
-          if (deep && trailingSlash.has(resultKey)) {
-            // Special case: deep tree and value is expected to be a subtree
-            const sourceValue = await tree.get(resultKey);
-            // If we did get a subtree, apply the map to it
-            const resultValue = Tree.isAsyncTree(sourceValue)
-              ? mapFn(sourceValue)
-              : undefined;
-            return resultValue;
-          } else {
-            // No inverseKeyFn, or it returned undefined; use resultKey
-            sourceKey = resultKey;
-          }
-        }
-
-        // Regular path: map a single value
-
-        // Step 2: Get the source value
-        let sourceValue;
-        if (needsSourceValue) {
-          // Normal case: get the value from the source tree
-          sourceValue = await tree.get(sourceKey);
-          if (deep && sourceValue === undefined) {
-            // Key might be for a subtree, see if original key exists
-            sourceValue = await tree.get(resultKey);
-          }
-        }
-
-        // Step 3: Map the source value to the result value
-        let resultValue;
-        if (needsSourceValue && sourceValue === undefined) {
-          // No source value means no result value
-          resultValue = undefined;
-        } else if (deep && Tree.isAsyncTree(sourceValue)) {
-          // We weren't expecting a subtree but got one; map it
-          resultValue = mapFn(sourceValue);
-        } else if (valueFn) {
-          // Map a single value
-          resultValue = await valueFn(sourceValue, sourceKey, tree);
-        } else {
-          // Return source value as is
-          resultValue = sourceValue;
-        }
-
-        return resultValue;
-      };
+      transformed.get = createGet(tree, options, mapFn);
     }
-
     if (keyFn) {
-      transformed.keys = async () => {
-        // Apply the keyFn to source keys for leaf values (not subtrees).
-        const sourceKeys = Array.from(await tree.keys());
-        const mapped = await Promise.all(
-          sourceKeys.map(async (sourceKey) =>
-            // Deep maps leave source keys for subtrees alone
-            deep && trailingSlash.has(sourceKey)
-              ? sourceKey
-              : await keyFn(sourceKey, tree)
-          )
-        );
-        // Filter out any cases where the keyFn returned undefined.
-        const resultKeys = mapped.filter((key) => key !== undefined);
-        return resultKeys;
-      };
+      transformed.keys = createKeys(tree, options);
     }
-
     return transformed;
-  }
+  };
+}
 
-  const tree = Tree.from(treelike, { deep });
-  return mapFn(tree);
+// Return the indicated option, throwing if it's specified but not defined;
+// that's probably an accident.
+function validateOption(options, key) {
+  const value = options[key];
+  if (key in options && value === undefined) {
+    throw new TypeError(
+      `map: The ${key} option is given but its value is undefined.`
+    );
+  }
+  return value;
 }
 
 // Extract and validate options
@@ -121,27 +150,57 @@ function validateOptions(options) {
   let extension;
   let inverseKeyFn;
   let keyFn;
-  let needsSourceValue;
+  let keyNeedsSourceValue;
   let valueFn;
 
   if (typeof options === "function") {
     // Take the single function argument as the valueFn
     valueFn = options;
+  } else if (isPlainObject(options)) {
+    // Extract options from the dictionary
+    description = options.description; // fine if it's undefined
+
+    // Validate individual options
+    deep = validateOption(options, "deep");
+    extension = validateOption(options, "extension");
+    inverseKeyFn = validateOption(options, "inverseKey");
+    keyFn = validateOption(options, "key");
+    keyNeedsSourceValue = validateOption(options, "keyNeedsSourceValue");
+    valueFn = validateOption(options, "value");
+
+    // Cast function options to functions
+    inverseKeyFn &&= toFunction(inverseKeyFn);
+    keyFn &&= toFunction(keyFn);
+    valueFn &&= toFunction(valueFn);
+  } else if (options === undefined) {
+    /** @type {any} */
+    const error = new TypeError(`map: The second parameter was undefined.`);
+    error.position = 1;
+    throw error;
   } else {
-    deep = options.deep;
-    description = options.description;
-    extension = options.extension;
-    inverseKeyFn = options.inverseKey;
-    keyFn = options.key;
-    needsSourceValue = options.needsSourceValue;
-    valueFn = options.value;
+    /** @type {any} */
+    const error = new TypeError(
+      `map: You must specify a value function or options dictionary as the second parameter.`
+    );
+    error.position = 1;
+    throw error;
   }
 
+  if (extension && !options._noExtensionWarning) {
+    console.warn(
+      `map: The 'extension' option for Tree.map() is deprecated and will be removed in a future release. Use Tree.mapExtension() instead.`
+    );
+  }
   if (extension && (keyFn || inverseKeyFn)) {
     throw new TypeError(
       `map: You can't specify extensions and also a key or inverseKey function`
     );
   }
+  if (extension && keyNeedsSourceValue === true) {
+    throw new TypeError(
+      `map: using extensions sets keyNeedsSourceValue to be false`
+    );
+  }
 
   if (extension) {
     // Use the extension mapping to generate key and inverseKey functions
@@ -152,6 +211,7 @@ function validateOptions(options) {
     );
     keyFn = keyFns.key;
     inverseKeyFn = keyFns.inverseKey;
+    keyNeedsSourceValue = false;
   } else {
     // If key or inverseKey weren't specified, look for sidecar functions
     inverseKeyFn ??= valueFn?.inverseKey;
@@ -177,16 +237,17 @@ function validateOptions(options) {
     );
   }
 
-  deep ??= false;
+  // Set defaults for options not specified. We don't set a default value for
+  // `deep` because a false value is a stronger signal than undefined.
   description ??= "key/value map";
-  needsSourceValue ??= true;
+  keyNeedsSourceValue ??= true;
 
   return {
     deep,
     description,
     inverseKeyFn,
     keyFn,
-    needsSourceValue,
+    keyNeedsSourceValue,
     valueFn,
   };
 }

package/src/operations/mapExtension.js

@@ -0,0 +1,78 @@
+import isPlainObject from "../utilities/isPlainObject.js";
+import map from "./map.js";
+
+/**
+ * @typedef {import("../../index.ts").TreeMapExtensionOptions} TreeMapExtensionOptions
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ */
+
+/**
+ * @overload
+ * @param {Treelike} treelike
+ * @param {string} extension
+ */
+
+/**
+ * @overload
+ * @param {Treelike} treelike
+ * @param {TreeMapExtensionOptions} options
+ */
+
+/**
+ * @overload
+ * @param {Treelike} treelike
+ * @param {string} extension
+ * @param {ValueKeyFn} fn
+ */
+
+/**
+ * @overload
+ * @param {Treelike} treelike
+ * @param {string} extension
+ * @param {TreeMapExtensionOptions} options
+ */
+
+/**
+ * Shorthand for calling `map` with the `deep: true` option.
+ *
+ * @param {Treelike} treelike
+ * @param {string|TreeMapExtensionOptions} arg2
+ * @param {ValueKeyFn|TreeMapExtensionOptions} [arg3]
+ * @returns {Promise<AsyncTree>}
+ */
+export default async function mapExtension(treelike, arg2, arg3) {
+  /** @type {TreeMapExtensionOptions} */
+  // @ts-ignore
+  let options = { _noExtensionWarning: true };
+  if (arg3 === undefined) {
+    if (typeof arg2 === "string") {
+      options.extension = arg2;
+    } else if (isPlainObject(arg2)) {
+      Object.assign(options, arg2);
+    } else {
+      throw new TypeError(
+        "mapExtension: Expected a string or options object for the second argument."
+      );
+    }
+  } else {
+    if (typeof arg2 !== "string") {
+      throw new TypeError(
+        "mapExtension: Expected a string for the second argument."
+      );
+    }
+    options.extension = arg2;
+    if (typeof arg3 === "function") {
+      options.value = arg3;
+    } else if (isPlainObject(arg3)) {
+      Object.assign(options, arg3);
+    } else {
+      throw new TypeError(
+        "mapExtension: Expected a function or options object for the third argument."
+      );
+    }
+  }
+
+  return map(treelike, options);
+}

package/src/operations/mapReduce.js

@@ -0,0 +1,44 @@
+import from from "./from.js";
+import isAsyncTree from "./isAsyncTree.js";
+
+/**
+ * Map and reduce a tree.
+ *
+ * This is done in as parallel fashion as possible. Each of the tree's values
+ * will be requested in an async call, then those results will be awaited
+ * collectively. If a mapFn is provided, it will be invoked to convert each
+ * value to a mapped value; otherwise, values will be used as is. When the
+ * values have been obtained, all the values and keys will be passed to the
+ * reduceFn, which should consolidate those into a single result.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").ReduceFn} ReduceFn
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
+ *
+ * @param {Treelike} treelike
+ * @param {ValueKeyFn|null} mapFn
+ * @param {ReduceFn} reduceFn
+ */
+export default async function mapReduce(treelike, mapFn, reduceFn) {
+  const tree = from(treelike);
+
+  // We're going to fire off all the get requests in parallel, as quickly as
+  // the keys come in. We call the tree's `get` method for each key, but
+  // *don't* wait for it yet.
+  const keys = Array.from(await tree.keys());
+  const promises = keys.map(async (key) => {
+    const value = await tree.get(key);
+    return isAsyncTree(value)
+      ? mapReduce(value, mapFn, reduceFn) // subtree; recurse
+      : mapFn
+      ? mapFn(value, key, tree)
+      : value;
+  });
+
+  // Wait for all the promises to resolve. Because the promises were captured
+  // in the same order as the keys, the values will also be in the same order.
+  const values = await Promise.all(promises);
+
+  // Reduce the values to a single result.
+  return reduceFn(values, keys, tree);
+}

package/src/operations/mask.js

@@ -1,6 +1,7 @@
-import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isAsyncTree from "./isAsyncTree.js";
+import isTreelike from "./isTreelike.js";
 
 /**
  * Given trees `a` and `b`, return a masked version of `a` where only the keys
@@ -10,25 +11,26 @@ import { assertIsTreelike } from "../utilities.js";
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
- * @param {Treelike} a
- * @param {Treelike} b
- * @returns {AsyncTree}
+ * @param {Treelike} aTreelike
+ * @param {Treelike} bTreelike
+ * @returns {Promise<AsyncTree>}
  */
-export default function mask(a, b) {
-  assertIsTreelike(a, "filter", 0);
-  assertIsTreelike(b, "filter", 1);
-  a = Tree.from(a);
-  b = Tree.from(b, { deep: true });
+export default async function mask(aTreelike, bTreelike) {
+  const aTree = await getTreeArgument(aTreelike, "filter", { position: 0 });
+  const bTree = await getTreeArgument(bTreelike, "filter", {
+    deep: true,
+    position: 1,
+  });
 
   return {
     async get(key) {
       // The key must exist in b and return a truthy value
-      const bValue = await b.get(key);
+      const bValue = await bTree.get(key);
       if (!bValue) {
         return undefined;
       }
-      let aValue = await a.get(key);
-      if (Tree.isTreelike(aValue)) {
+      let aValue = await aTree.get(key);
+      if (isTreelike(aValue)) {
         // Filter the subtree
         return mask(aValue, bValue);
       } else {
@@ -38,13 +40,13 @@ export default function mask(a, b) {
 
     async keys() {
       // Use a's keys as the basis
-      const aKeys = [...(await a.keys())];
-      const bValues = await Promise.all(aKeys.map((key) => b.get(key)));
+      const aKeys = [...(await aTree.keys())];
+      const bValues = await Promise.all(aKeys.map((key) => bTree.get(key)));
       // An async tree value in b implies that the a key should have a slash
       const aKeySlashes = aKeys.map((key, index) =>
         trailingSlash.toggle(
           key,
-          trailingSlash.has(key) || Tree.isAsyncTree(bValues[index])
+          trailingSlash.has(key) || isAsyncTree(bValues[index])
         )
       );
       // Remove keys that don't have values in b

package/src/operations/match.js

@@ -0,0 +1,74 @@
+import isAsyncTree from "./isAsyncTree.js";
+
+/**
+ * Return a tree with the indicated keys (if provided).
+ *
+ * The pattern can a string with a simplified pattern syntax that tries to match
+ * against the entire key and uses brackets to identify named wildcard values.
+ * E.g. `[name].html` will match `Alice.html` with wildcard values { name:
+ * "Alice" }.
+ *
+ * The pattern can also be a JavaScript regular expression.
+ *
+ * If a key is requested, match against the given pattern and, if matches,
+ * invokes the given function with an object containing the matched values.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @param {string|RegExp} pattern
+ * @param {Invocable} resultFn
+ * @param {Treelike} [keys]
+ */
+export default function match(pattern, resultFn, keys = []) {
+  let regex;
+  if (typeof pattern === "string") {
+    // Convert the simple pattern format into a regular expression.
+    const regexText = pattern.replace(
+      /\[(?<variable>.+)\]/g,
+      (match, p1, offset, string, groups) => `(?<${groups.variable}>.+)`
+    );
+    regex = new RegExp(`^${regexText}$`);
+  } else if (pattern instanceof RegExp) {
+    regex = pattern;
+  } else {
+    throw new Error(`match(): Unsupported pattern`);
+  }
+
+  const result = {
+    async get(key) {
+      const keyMatch = regex.exec(key);
+      if (!keyMatch) {
+        return undefined;
+      }
+
+      if (
+        typeof resultFn !== "function" &&
+        !(isAsyncTree(resultFn) && "parent" in resultFn)
+      ) {
+        // Simple return value; return as is
+        return resultFn;
+      }
+
+      // Copy the `groups` property to a real object
+      const matches = { ...keyMatch.groups };
+
+      // Invoke the result function with the extended scope.
+      let value;
+      if (typeof resultFn === "function") {
+        value = await resultFn(matches);
+      } else {
+        value = Object.create(resultFn);
+      }
+
+      return value;
+    },
+
+    async keys() {
+      return typeof keys === "function" ? await keys() : keys;
+    },
+  };
+
+  return result;
+}

package/src/operations/merge.js

@@ -1,24 +1,35 @@
-import { Tree } from "../internal.js";
-import * as symbols from "../symbols.js";
 import * as trailingSlash from "../trailingSlash.js";
+import isPlainObject from "../utilities/isPlainObject.js";
+import from from "./from.js";
+import isAsyncTree from "./isAsyncTree.js";
 
 /**
  * Return a tree that performs a shallow merge of the given trees.
  *
- * Given a set of trees, the `get` method looks at each tree in turn. The first
- * tree is asked for the value with the key. If an tree returns a defined value
- * (i.e., not undefined), that value is returned. If the first tree returns
- * undefined, the second tree will be asked, and so on. If none of the trees
+ * This is similar to an object spread in JavaScript extended to async trees.
+ * Given a set of trees, the `get` method looks at each tree in turn, starting
+ * from the *last* tree and working backwards to the first. If a tree returns a
+ * defined value for the key, that value is returned. If none of the trees
  * return a defined value, the `get` method returns undefined.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @param {import("../../index.ts").Treelike[]} sources
- * @returns {AsyncTree & { description?: string, trees?: AsyncTree[]}}
+ * @typedef {import("../../index.ts").PlainObject} PlainObject
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike[]} sources
+ * @returns {(AsyncTree & { description?: string, trees?: AsyncTree[]}) | PlainObject}
  */
 export default function merge(...sources) {
-  const trees = sources
-    .filter((source) => source)
-    .map((treelike) => Tree.from(treelike));
+  const filtered = sources.filter((source) => source);
+
+  // If all arguments are plain objects, return a plain object.
+  if (
+    filtered.every((source) => !isAsyncTree(source) && isPlainObject(source))
+  ) {
+    return filtered.reduce((acc, obj) => ({ ...acc, ...obj }), {});
+  }
+
+  const trees = filtered.map((treelike) => from(treelike));
 
   if (trees.length === 0) {
     throw new TypeError("merge: all trees are null or undefined");
@@ -36,15 +47,6 @@ export default function merge(...sources) {
         const tree = trees[index];
         const value = await tree.get(key);
         if (value !== undefined) {
-          // Merged tree acts as parent instead of the source tree.
-          if (Tree.isAsyncTree(value) && value.parent === tree) {
-            value.parent = this;
-          } else if (
-            typeof value === "object" &&
-            value?.[symbols.parent] === tree
-          ) {
-            value[symbols.parent] = this;
-          }
           return value;
         }
       }

package/src/operations/paginate.js

@@ -1,6 +1,5 @@
-import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
 
 /**
  * Return a new grouping of the treelike's values into chunks of the specified
@@ -9,12 +8,11 @@ import { assertIsTreelike } from "../utilities.js";
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
- * @param {Treelike} [treelike]
+ * @param {Treelike} treelike
  * @param {number} [size=10]
  */
 export default async function paginate(treelike, size = 10) {
-  assertIsTreelike(treelike, "paginate");
-  const tree = Tree.from(treelike);
+  const tree = await getTreeArgument(treelike, "paginate");
 
   const keys = Array.from(await tree.keys());
   const pageCount = Math.ceil(keys.length / size);

package/src/operations/parent.js

@@ -0,0 +1,13 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Returns the parent of the current tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+export default async function parent(treelike) {
+  const tree = await getTreeArgument(treelike, "parent");
+  return tree.parent;
+}