@weborigami/async-tree 0.5.8 → 0.6.1

package/src/operations/isAsyncTree.js

@@ -1,21 +1,6 @@
-/**
- * Return true if the indicated object is an async tree.
- *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- *
- * @param {any} obj
- * @returns {obj is AsyncTree}
- */
-export default function isAsyncTree(obj) {
-  return (
-    obj !== null &&
-    typeof obj === "object" &&
-    typeof obj.get === "function" &&
-    typeof obj.keys === "function" &&
-    // Regular JavaScript Map instances look like trees but can't have their
-    // prototype chains extended (the way map() does), so exclude them.
-    // Subclasses of Map that implement their own get() and keys() methods are
-    // allowed, because they shouldn't have the same limitations.
-    !(obj instanceof Map && Object.getPrototypeOf(obj) === Map.prototype)
-  );
+import isMap from "./isMap.js";
+
+export default function isAsyncTree(treelike) {
+  console.warn("Tree.isAsyncTree() is deprecated, use Tree.isMap() instead.");
+  return isMap(treelike);
 }

package/src/operations/isMap.js

@@ -0,0 +1,39 @@
+import AsyncMap from "../drivers/AsyncMap.js";
+
+/**
+ * Return true if the indicated object is a Map instance or supports
+ * a `Map` compatible interface.
+ *
+ * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
+ *
+ * @param {any} object
+ * @returns {object is Map|AsyncMap}
+ */
+export default function isMap(object) {
+  if (object instanceof Map || object instanceof AsyncMap) {
+    // Known positive cases
+    return true;
+  }
+
+  // Check for Map-like interface
+  if (
+    object &&
+    object.clear instanceof Function &&
+    object.delete instanceof Function &&
+    object.entries instanceof Function &&
+    object.forEach instanceof Function &&
+    object.get instanceof Function &&
+    object.has instanceof Function &&
+    object.keys instanceof Function &&
+    object.set instanceof Function &&
+    object.values instanceof Function &&
+    object.constructor.groupBy instanceof Function &&
+    "size" in object &&
+    (object[Symbol.iterator] instanceof Function ||
+      object[Symbol.asyncIterator] instanceof Function)
+  ) {
+    return true;
+  }
+
+  return false;
+}

package/src/operations/isMaplike.js

@@ -0,0 +1,34 @@
+import isPlainObject from "../utilities/isPlainObject.js";
+import isMap from "./isMap.js";
+
+/**
+ * Returns true if the indicated object can be directly treated like a Map. This
+ * includes:
+ *
+ * - A function
+ * - An `Array` instance
+ * - An `AsyncMap` instance
+ * - An `Iterator` instance
+ * - A `Map` instance
+ * - A `Set` instance
+ * - A plain object
+ *
+ * Note: the `from()` method accepts any JavaScript object, but `isMaplike`
+ * returns `false` for an object that isn't one of the above types.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {any} object
+ * @returns {obj is Maplike}
+ */
+export default function isMaplike(object) {
+  return (
+    object instanceof Array ||
+    object instanceof Function ||
+    // @ts-ignore
+    (globalThis.Iterator && object instanceof Iterator) ||
+    object instanceof Set ||
+    isMap(object) ||
+    isPlainObject(object)
+  );
+}

package/src/operations/isReadOnlyMap.js

@@ -0,0 +1,14 @@
+import isMap from "./isMap.js";
+
+/**
+ * Return true if the indicated object is a read-only map.
+ *
+ * @param {any} object
+ */
+export default function isReadOnlyMap(object) {
+  if (!isMap(object)) {
+    return false;
+  }
+  // Respect readOnly if defined, otherwise assume read/write
+  return "readOnly" in object ? object.readOnly : false;
+}

package/src/operations/isTraversable.js

@@ -1,15 +1,15 @@
 import isPacked from "../utilities/isPacked.js";
-import isTreelike from "./isTreelike.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Return true if the object can be traversed via the `traverse()` method. The
- * object must be either treelike or a packed object with an `unpack()` method.
+ * object must be either maplike or a packed object with an `unpack()` method.
  *
  * @param {any} object
  */
 export default function isTraversable(object) {
   return (
-    isTreelike(object) ||
+    isMaplike(object) ||
     (isPacked(object) && /** @type {any} */ (object).unpack instanceof Function)
   );
 }

package/src/operations/isTreelike.js

@@ -1,33 +1,8 @@
-import isPlainObject from "../utilities/isPlainObject.js";
-import isAsyncTree from "./isAsyncTree.js";
+import isMaplike from "./isMaplike.js";
 
-/**
- * Returns true if the indicated object can be directly treated as an
- * asynchronous tree. This includes:
- *
- * - An object that implements the AsyncTree interface (including
- *   AsyncTree instances)
- * - A function
- * - An `Array` instance
- * - A `Map` instance
- * - A `Set` instance
- * - A plain object
- *
- * Note: the `from()` method accepts any JavaScript object, but `isTreelike`
- * returns `false` for an object that isn't one of the above types.
- *
- * @typedef {import("../../index.ts").Treelike} Treelike
- *
- * @param {any} obj
- * @returns {obj is Treelike}
- */
-export default function isTreelike(obj) {
-  return (
-    isAsyncTree(obj) ||
-    obj instanceof Array ||
-    obj instanceof Function ||
-    obj instanceof Map ||
-    obj instanceof Set ||
-    isPlainObject(obj)
+export default function isTreelike(treelike) {
+  console.warn(
+    "Tree.isTreelike() is deprecated, use Tree.isMaplike() instead."
   );
+  return isMaplike(treelike);
 }

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,24 @@ 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);
+    transformed.trailingSlashKeys = /** @type {any} */ (tree).trailingSlashKeys;
     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,58 @@
-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.
+ * Map and reduce a `source` 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.
+ * Each of the tree's values will be requested in an asynchronous call, then
+ * those results will be awaited collectively. If a valueFn is provided, it will
+ * be invoked to convert each value to a mapped value; if the valueFn is null or
+ * undefined, values will be used as is, although any Promise values will be
+ * awaited.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * The resolved values will be added to a regular `Map` with the same keys as
+ * the source. This `Map` will be passed to the reduceFn, along with the
+ * original `source`.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
  * @typedef {import("../../index.ts").ReduceFn} ReduceFn
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
- * @param {Treelike} treelike
- * @param {ValueKeyFn|null} mapFn
+ * @param {Maplike} source
+ * @param {ValueKeyFn|null} valueFn
  * @param {ReduceFn} reduceFn
  */
-export default async function mapReduce(treelike, mapFn, reduceFn) {
-  const tree = from(treelike);
+export default async function mapReduce(source, valueFn, reduceFn) {
+  const sourceMap = await getMapArgument(source, "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 mapped = new Map();
+  const promises = [];
+  for await (const key of sourceMap.keys()) {
+    mapped.set(key, null); // placeholder
+    const promise = (async () => {
+      const value = await sourceMap.get(key);
+      return isMap(value)
+        ? mapReduce(value, valueFn, reduceFn) // subtree; recurse
+        : valueFn
+        ? valueFn(value, key, sourceMap)
+        : 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);
 
+  // Replace the placeholders with the actual values.
+  const keys = Array.from(mapped.keys());
+  for (let i = 0; i < values.length; i++) {
+    mapped.set(keys[i], values[i]);
+  }
+
   // Reduce the values to a single result.
-  return reduceFn(values, keys, tree);
+  return reduceFn(mapped, sourceMap);
 }

package/src/operations/mask.js

@@ -1,36 +1,44 @@
+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 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", {
+    deep: true,
+    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)) {
+      const normalized = /** @type {any} */ (aMap).trailingSlashKeys
+        ? key
+        : trailingSlash.remove(key);
+      let aValue = await aMap.get(normalized);
+      if (isMaplike(aValue)) {
         // Filter the subtree
         return mask(aValue, bValue);
       } else {
@@ -38,20 +46,37 @@ export default async function mask(aTreelike, bTreelike) {
       }
     },
 
-    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)));
-      // An async tree value in b implies that the a key should have a slash
-      const aKeySlashes = aKeys.map((key, index) =>
-        trailingSlash.toggle(
+    async *keys() {
+      // Get keys from a and b
+      const [aKeys, bKeys] = await Promise.all([keys(aMap), keys(bMap)]);
+
+      const combined = Array.from(new Set([...aKeys, ...bKeys]));
+
+      // Get all the values from b. Because a and b may be defined by functions,
+      // they might have values that are not represented in their own keys.
+      const bValues = await Promise.all(combined.map((key) => bMap.get(key)));
+
+      // Find keys that have truthy values in b. While we're at it, we can add
+      // slashes even if a or b didn't have them.
+      const withSlashes = combined.map((key, index) => {
+        const bValue = bValues[index];
+        if (!bValue) {
+          // Mark for removal
+          return undefined;
+        }
+        return trailingSlash.toggle(
           key,
-          trailingSlash.has(key) || isAsyncTree(bValues[index])
-        )
-      );
-      // Remove keys that don't have values in b
-      const keys = aKeySlashes.filter((key, index) => bValues[index] ?? false);
-      return keys;
+          trailingSlash.has(key) || isMaplike(bValue)
+        );
+      });
+
+      // Yield only the keys that have truthy values in b
+      const filtered = withSlashes.filter((value) => value !== undefined);
+      yield* new Set(filtered);
     },
-  };
+
+    source: aMap,
+
+    trailingSlashKeys: true,
+  });
 }