@weborigami/async-tree 0.5.7 → 0.6.0

package/src/operations/json.js

@@ -1,21 +1,13 @@
-/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
-import isUnpackable from "../utilities/isUnpackable.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import toPlainValue from "../utilities/toPlainValue.js";
-import from from "./from.js";
 
 /**
  * Render the given tree in JSON format.
  *
- * @param {import("../../index.ts").Treelike} [treelike]
+ * @param {import("../../index.ts").Maplike} maplike
  */
-export default async function json(treelike) {
-  let tree = from(treelike);
-  if (tree === undefined) {
-    return undefined;
-  }
-  if (isUnpackable(tree)) {
-    tree = await tree.unpack();
-  }
+export default async function json(maplike) {
+  const tree = await getMapArgument(maplike, "json");
   const value = await toPlainValue(tree);
   return JSON.stringify(value, null, 2);
 }

package/src/operations/keys.js

@@ -1,14 +1,23 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Return the top-level keys in the tree as an array.
+ * Return the keys of the map.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function keys(treelike) {
-  const tree = await getTreeArgument(treelike, "keys");
-  const keys = await tree.keys();
-  return Array.from(keys);
+export default async function keys(maplike) {
+  const map = await getMapArgument(maplike, "keys");
+  let keys;
+  let iterable = map.keys();
+  if (Symbol.asyncIterator in iterable) {
+    keys = [];
+    for await (const key of iterable) {
+      keys.push(key);
+    }
+  } else {
+    keys = Array.from(iterable);
+  }
+  return keys;
 }

package/src/operations/length.js

@@ -1,15 +1,16 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
  * Return the number of keys in the tree.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function length(treelike) {
-  const tree = await getTreeArgument(treelike, "length");
-  const keys = Array.from(await tree.keys());
-  return keys.length;
+export default async function length(maplike) {
+  console.warn("Tree.length() is deprecated. Use Tree.size() instead.");
+  const tree = await getMapArgument(maplike, "length");
+  const treeKeys = await keys(tree);
+  return treeKeys.length;
 }

package/src/operations/map.js

@@ -1,33 +1,34 @@
+import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.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 isMap from "./isMap.js";
+import keys from "./keys.js";
 import parseExtensions from "./parseExtensions.js";
 
 /**
  * Transform the keys and/or values of a tree.
  *
  * @typedef {import("../../index.ts").KeyFn} KeyFn
- * @typedef {import("../../index.ts").TreeMapOptions} MapOptions
+ * @typedef {import("../../index.ts").MapOptions} MapOptions
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  * @param {MapOptions|ValueKeyFn} options
- * @returns {Promise<AsyncTree>}
+ * @returns {Promise<AsyncMap>}
  */
-export default async function map(treelike, options = {}) {
+export default async function map(maplike, 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 });
+  const tree = await getMapArgument(maplike, "map", { deep: validated.deep });
   return mapFn(tree);
 }
 
@@ -47,9 +48,7 @@ function createGet(tree, options, mapFn) {
         // 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;
+        const resultValue = isMap(sourceValue) ? mapFn(sourceValue) : undefined;
         return resultValue;
       } else {
         // No inverseKeyFn, or it returned undefined; use resultKey
@@ -69,7 +68,7 @@ function createGet(tree, options, mapFn) {
     if (sourceValue === undefined) {
       // No source value means no result value
       resultValue = undefined;
-    } else if (deep && isAsyncTree(sourceValue)) {
+    } else if (deep && isMap(sourceValue)) {
       // We weren't expecting a subtree but got one; map it
       resultValue = mapFn(sourceValue);
     } else if (valueFn) {
@@ -87,9 +86,14 @@ function createGet(tree, options, mapFn) {
 // Create a keys() function for the map
 function createKeys(tree, options) {
   const { deep, keyFn, keyNeedsSourceValue } = options;
-  return async () => {
+  return async function* () {
     // Apply the keyFn to source keys for leaf values (not subtrees).
-    const sourceKeys = Array.from(await tree.keys());
+    const sourceKeys = await keys(tree);
+    if (!keyFn) {
+      // Return keys as is
+      yield* sourceKeys;
+      return;
+    }
     const sourceValues = keyNeedsSourceValue
       ? await Promise.all(sourceKeys.map((sourceKey) => tree.get(sourceKey)))
       : sourceKeys.map(() => null);
@@ -103,30 +107,23 @@ function createKeys(tree, options) {
     );
     // Filter out any cases where the keyFn returned undefined.
     const resultKeys = mapped.filter((key) => key !== undefined);
-    return resultKeys;
+    yield* resultKeys;
   };
 }
 
 // Create a map function for the given options
 function createMapFn(options) {
-  const { description, keyFn, valueFn } = options;
   /**
-   * @param {AsyncTree} tree
-   * @return {AsyncTree}
+   * @param {Map|AsyncMap} tree
+   * @return {AsyncMap}
    */
   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 = createGet(tree, options, mapFn);
-    }
-    if (keyFn) {
-      transformed.keys = createKeys(tree, options);
-    }
+    /** @type {any} */
+    const transformed = new AsyncMap();
+    transformed.description = options.description;
+    transformed.source = tree;
+    transformed.get = createGet(tree, options, mapFn);
+    transformed.keys = createKeys(tree, options);
     return transformed;
   };
 }

package/src/operations/mapExtension.js

@@ -3,48 +3,48 @@ import isUnpackable from "../utilities/isUnpackable.js";
 import map from "./map.js";
 
 /**
- * @typedef {import("../../index.ts").TreeMapExtensionOptions} TreeMapExtensionOptions
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").AsyncMap} AsyncMap
+ * @typedef {import("../../index.ts").MapExtensionOptions} MapExtensionOptions
+ * @typedef {import("../../index.ts").Maplike} Maplike
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  */
 
 /**
  * @overload
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {string} extension
  */
 
 /**
  * @overload
- * @param {Treelike} treelike
- * @param {TreeMapExtensionOptions} options
+ * @param {Maplike} maplike
+ * @param {MapExtensionOptions} options
  */
 
 /**
  * @overload
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {string} extension
  * @param {ValueKeyFn} fn
  */
 
 /**
  * @overload
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {string} extension
- * @param {TreeMapExtensionOptions} options
+ * @param {MapExtensionOptions} options
  */
 
 /**
  * Shorthand for calling `map` with the `deep: true` option.
  *
- * @param {Treelike} treelike
- * @param {string|TreeMapExtensionOptions} arg2
- * @param {ValueKeyFn|TreeMapExtensionOptions} [arg3]
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} maplike
+ * @param {string|MapExtensionOptions} arg2
+ * @param {ValueKeyFn|MapExtensionOptions} [arg3]
+ * @returns {Promise<AsyncMap>}
  */
-export default async function mapExtension(treelike, arg2, arg3) {
-  /** @type {TreeMapExtensionOptions} */
+export default async function mapExtension(maplike, arg2, arg3) {
+  /** @type {MapExtensionOptions} */
   // @ts-ignore
   let options = { _noExtensionWarning: true };
   if (arg3 === undefined) {
@@ -78,5 +78,9 @@ export default async function mapExtension(treelike, arg2, arg3) {
     }
   }
 
-  return map(treelike, options);
+  if (!options.description) {
+    options.description = `mapExtension ${options.extension}`;
+  }
+
+  return map(maplike, options);
 }

package/src/operations/mapReduce.js

@@ -1,44 +1,49 @@
-import from from "./from.js";
-import isAsyncTree from "./isAsyncTree.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.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
+ * will be requested in an asynchronous 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").Maplike} Maplike
  * @typedef {import("../../index.ts").ReduceFn} ReduceFn
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {ValueKeyFn|null} mapFn
  * @param {ReduceFn} reduceFn
  */
-export default async function mapReduce(treelike, mapFn, reduceFn) {
-  const tree = from(treelike);
+export default async function mapReduce(maplike, mapFn, reduceFn) {
+  const map = await getMapArgument(maplike, "mapReduce");
 
   // 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;
-  });
+  const treeKeys = [];
+  const promises = [];
+  for await (const key of map.keys()) {
+    treeKeys.push(key);
+    const promise = (async () => {
+      const value = await map.get(key);
+      return isMap(value)
+        ? mapReduce(value, mapFn, reduceFn) // subtree; recurse
+        : mapFn
+        ? mapFn(value, key, map)
+        : value;
+    })();
+    promises.push(promise);
+  }
 
   // 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);
+  return reduceFn(values, treeKeys, map);
 }

package/src/operations/mask.js

@@ -1,36 +1,39 @@
+import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import isAsyncTree from "./isAsyncTree.js";
-import isTreelike from "./isTreelike.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
+import keys from "./keys.js";
 
 /**
  * Given trees `a` and `b`, return a masked version of `a` where only the keys
  * that exist in `b` and have truthy values are kept. The filter operation is
  * deep: if a value from `a` is a subtree, it will be filtered recursively.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} aTreelike
- * @param {Treelike} bTreelike
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} aMaplike
+ * @param {Maplike} bMaplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function mask(aTreelike, bTreelike) {
-  const aTree = await getTreeArgument(aTreelike, "filter", { position: 0 });
-  const bTree = await getTreeArgument(bTreelike, "filter", {
+export default async function mask(aMaplike, bMaplike) {
+  const aMap = await getMapArgument(aMaplike, "filter", { position: 0 });
+  const bMap = await getMapArgument(bMaplike, "filter", {
     deep: true,
     position: 1,
   });
 
-  return {
+  return Object.assign(new AsyncMap(), {
+    description: "mask",
+
     async get(key) {
       // The key must exist in b and return a truthy value
-      const bValue = await bTree.get(key);
+      const bValue = await bMap.get(key);
       if (!bValue) {
         return undefined;
       }
-      let aValue = await aTree.get(key);
-      if (isTreelike(aValue)) {
+      let aValue = await aMap.get(key);
+      if (isMaplike(aValue)) {
         // Filter the subtree
         return mask(aValue, bValue);
       } else {
@@ -38,20 +41,26 @@ export default async function mask(aTreelike, bTreelike) {
       }
     },
 
-    async keys() {
+    async *keys() {
       // Use a's keys as the basis
-      const aKeys = [...(await aTree.keys())];
-      const bValues = await Promise.all(aKeys.map((key) => bTree.get(key)));
+      const aKeys = await keys(aMap);
+      const bValues = await Promise.all(aKeys.map((key) => bMap.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) || isAsyncTree(bValues[index])
+          trailingSlash.has(key) || isMap(bValues[index])
         )
       );
       // Remove keys that don't have values in b
-      const keys = aKeySlashes.filter((key, index) => bValues[index] ?? false);
-      return keys;
+      const treeKeys = aKeySlashes.filter(
+        (key, index) => bValues[index] ?? false
+      );
+      yield* treeKeys;
     },
-  };
+
+    source: aMap,
+
+    trailingSlashKeys: /** @type {any} */ (aMap).trailingSlashKeys,
+  });
 }

package/src/operations/match.js

@@ -1,4 +1,5 @@
-import isAsyncTree from "./isAsyncTree.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import isMap from "./isMap.js";
 
 /**
  * Return a tree with the indicated keys (if provided).
@@ -13,13 +14,12 @@ import isAsyncTree from "./isAsyncTree.js";
  * 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").Maplike} Maplike
  * @typedef {import("../../index.ts").Invocable} Invocable
  *
  * @param {string|RegExp} pattern
  * @param {Invocable} resultFn
- * @param {Treelike} [keys]
+ * @param {Maplike} [keys]
  */
 export default function match(pattern, resultFn, keys = []) {
   let regex;
@@ -36,7 +36,9 @@ export default function match(pattern, resultFn, keys = []) {
     throw new Error(`match(): Unsupported pattern`);
   }
 
-  const result = {
+  const result = Object.assign(new AsyncMap(), {
+    description: "match",
+
     async get(key) {
       const keyMatch = regex.exec(key);
       if (!keyMatch) {
@@ -45,7 +47,7 @@ export default function match(pattern, resultFn, keys = []) {
 
       if (
         typeof resultFn !== "function" &&
-        !(isAsyncTree(resultFn) && "parent" in resultFn)
+        !(isMap(resultFn) && "parent" in resultFn)
       ) {
         // Simple return value; return as is
         return resultFn;
@@ -65,10 +67,12 @@ export default function match(pattern, resultFn, keys = []) {
       return value;
     },
 
-    async keys() {
-      return typeof keys === "function" ? await keys() : keys;
+    async *keys() {
+      yield* typeof keys === "function" ? await keys() : keys;
     },
-  };
+
+    trailingSlashKeys: false,
+  });
 
   return result;
 }

package/src/operations/merge.js

@@ -1,51 +1,59 @@
+import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
 import isPlainObject from "../utilities/isPlainObject.js";
+import isUnpackable from "../utilities/isUnpackable.js";
 import from from "./from.js";
-import isAsyncTree from "./isAsyncTree.js";
+import isMap from "./isMap.js";
+import keys from "./keys.js";
 
 /**
  * Return a tree that performs a shallow merge of the given 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.
+ * This is similar to an object spread in JavaScript extended to asynchronous
+ * 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
  * @typedef {import("../../index.ts").PlainObject} PlainObject
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike[]} sources
- * @returns {(AsyncTree & { description?: string, trees?: AsyncTree[]}) | PlainObject}
+ * @param {Maplike[]} treelikes
+ * @returns {Promise}
  */
-export default function merge(...sources) {
-  const filtered = sources.filter((source) => source);
+export default async function merge(...treelikes) {
+  const filtered = treelikes.filter((source) => source);
+  const unpacked = await Promise.all(
+    filtered.map(async (source) =>
+      isUnpackable(source) ? await source.unpack() : 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 }), {});
+  if (unpacked.every((source) => !isMap(source) && isPlainObject(source))) {
+    return unpacked.reduce((acc, obj) => ({ ...acc, ...obj }), {});
   }
 
-  const trees = filtered.map((treelike) => from(treelike));
+  const sources = unpacked.map((maplike) => from(maplike));
 
-  if (trees.length === 0) {
+  if (sources.length === 0) {
     throw new TypeError("merge: all trees are null or undefined");
-  } else if (trees.length === 1) {
+  } else if (sources.length === 1) {
     // Only one tree, no need to merge
-    return trees[0];
+    return sources[0];
   }
 
-  return {
+  return Object.assign(new AsyncMap(), {
     description: "merge",
 
     async get(key) {
       // Check trees for the indicated key in reverse order.
-      for (let index = trees.length - 1; index >= 0; index--) {
-        const tree = trees[index];
-        const value = await tree.get(key);
+      for (let index = sources.length - 1; index >= 0; index--) {
+        const source = sources[index];
+        const normalized = /** @type {any} */ (source).trailingSlashKeys
+          ? key
+          : trailingSlash.remove(key);
+        const value = await source.get(normalized);
         if (value !== undefined) {
           return value;
         }
@@ -53,25 +61,25 @@ export default function merge(...sources) {
       return undefined;
     },
 
-    async keys() {
-      const keys = new Set();
+    async *keys() {
+      const treeKeys = new Set();
       // Collect keys in the order the trees were provided.
-      for (const tree of trees) {
-        for (const key of await tree.keys()) {
+      for (const tree of sources) {
+        for (const key of await keys(tree)) {
           // Remove the alternate form of the key (if it exists)
           const alternateKey = trailingSlash.toggle(key);
           if (alternateKey !== key) {
-            keys.delete(alternateKey);
+            treeKeys.delete(alternateKey);
           }
 
-          keys.add(key);
+          treeKeys.add(key);
         }
       }
-      return keys;
+      yield* treeKeys;
     },
 
-    get trees() {
-      return trees;
-    },
-  };
+    sources,
+
+    trailingSlashKeys: true,
+  });
 }