@weborigami/async-tree 0.6.0 → 0.6.2

package/src/operations/assign.js

@@ -1,4 +1,5 @@
 import getMapArgument from "../utilities/getMapArgument.js";
+import child from "./child.js";
 import isMaplike from "./isMaplike.js";
 
 /**
@@ -17,26 +18,18 @@ export default async function assign(target, source) {
   const targetTree = await getMapArgument(target, "assign", { position: 0 });
   const sourceTree = await getMapArgument(source, "assign", { position: 1 });
   if ("readOnly" in targetTree && targetTree.readOnly) {
-    throw new TypeError("Target must be a mutable asynchronous tree");
+    throw new TypeError("assign: Target must be a read/write map");
   }
+
   // Fire off requests to update all keys, then wait for all of them to finish.
   const promises = [];
   for await (const key of sourceTree.keys()) {
     const promise = (async () => {
       const sourceValue = await sourceTree.get(key);
-
       if (isMaplike(sourceValue)) {
-        let targetValue = await targetTree.get(key);
-        if (targetValue === undefined) {
-          // Target key doesn't exist; create empty subtree
-          /** @type {any} */
-          const targetClass = targetTree.constructor;
-          const empty = targetClass.EMPTY ?? new targetClass();
-          await targetTree.set(key, empty);
-          targetValue = await targetTree.get(key);
-        }
         // Recurse to copy subtree
-        await assign(targetValue, sourceValue);
+        const targetChild = await child(targetTree, key);
+        await assign(targetChild, sourceValue);
       } else {
         // Copy the value from the source to the target.
         await targetTree.set(key, sourceValue);
@@ -44,6 +37,8 @@ export default async function assign(target, source) {
     })();
     promises.push(promise);
   }
+
   await Promise.all(promises);
+
   return targetTree;
 }

package/src/operations/cache.js

@@ -1,6 +1,7 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import SyncMap from "../drivers/SyncMap.js";
 import getMapArgument from "../utilities/getMapArgument.js";
+import child from "./child.js";
 import isMap from "./isMap.js";
 import isReadOnlyMap from "./isReadOnlyMap.js";
 import keys from "./keys.js";
@@ -54,8 +55,7 @@ export default async function treeCache(sourceMaplike, cacheMaplike) {
         // Construct merged tree for a tree result.
         if (cacheValue === undefined) {
           // Construct new empty container in cache
-          await cache.set(key, cache.constructor.EMPTY);
-          cacheValue = await cache.get(key);
+          cacheValue = await child(cache, key);
         }
         value = treeCache(value, cacheValue);
       } else if (value !== undefined) {

package/src/operations/child.js

@@ -0,0 +1,35 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+import setParent from "../utilities/setParent.js";
+import isMap from "./isMap.js";
+
+/**
+ * Return the child node with the indicated key, creating it if necessary.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ */
+export default async function child(maplike, key) {
+  const map = await getMapArgument(maplike, "assign", { position: 0 });
+
+  let result;
+
+  const hasChildMethod = "child" in map && typeof map.child === "function";
+  if (hasChildMethod) {
+    // Use tree's own child() method
+    result = map.child(key);
+  } else {
+    // Default implementation
+    result = await map.get(key);
+
+    // If child is already a map we can use it as is
+    if (!isMap(result)) {
+      // Create new child node using no-arg constructor
+      result = new /** @type {any} */ (map).constructor();
+      await map.set(key, result);
+      setParent(result, map);
+    }
+  }
+
+  return result;
+}

package/src/operations/from.js

@@ -1,5 +1,4 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import DeepObjectMap from "../drivers/DeepObjectMap.js";
 import FunctionMap from "../drivers/FunctionMap.js";
 import ObjectMap from "../drivers/ObjectMap.js";
 import SetMap from "../drivers/SetMap.js";
@@ -14,7 +13,7 @@ import isMap from "./isMap.js";
  *
  * If the object is a plain object, it will be converted to an ObjectMap. The
  * optional `deep` option can be set to `true` to convert a plain object to a
- * DeepObjectMap. The optional `parent` parameter will be used as the default
+ * deep ObjectMap. The optional `parent` parameter will be used as the default
  * parent of the new tree.
  *
  * @typedef {import("../../index.ts").Maplike} Maplike
@@ -41,14 +40,14 @@ export default function from(object, options = {}) {
   } else if (object instanceof Set) {
     map = new SetMap(object);
   } else if (isPlainObject(object) || object instanceof Array) {
-    map = deep ? new DeepObjectMap(object) : new ObjectMap(object);
+    map = new ObjectMap(object, { deep });
     // @ts-ignore
-  } else if (object instanceof Iterator) {
+  } else if (globalThis.Iterator && object instanceof Iterator) {
     const array = Array.from(object);
-    map = new ObjectMap(array);
+    map = new ObjectMap(array, { deep });
   } else if (object && typeof object === "object") {
     // An instance of some class.
-    map = new ObjectMap(object);
+    map = new ObjectMap(object, { deep });
   } else if (
     typeof object === "string" ||
     typeof object === "number" ||

package/src/operations/globKeys.js

@@ -24,9 +24,8 @@ export default async function globKeys(maplike) {
     },
 
     async *keys() {
-      for await (const key of source.keys()) {
-        yield key;
-      }
+      // Don't return globstar keys. When used, e.g., with a Tree.mask, we don't
+      // want the globstar keys to appear in the result.
     },
 
     trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,

package/src/operations/isMaplike.js

@@ -26,7 +26,7 @@ export default function isMaplike(object) {
     object instanceof Array ||
     object instanceof Function ||
     // @ts-ignore
-    object instanceof Iterator ||
+    (globalThis.Iterator && object instanceof Iterator) ||
     object instanceof Set ||
     isMap(object) ||
     isPlainObject(object)

package/src/operations/map.js

@@ -124,6 +124,7 @@ function createMapFn(options) {
     transformed.source = tree;
     transformed.get = createGet(tree, options, mapFn);
     transformed.keys = createKeys(tree, options);
+    transformed.trailingSlashKeys = /** @type {any} */ (tree).trailingSlashKeys;
     return transformed;
   };
 }
@@ -166,9 +167,17 @@ function validateOptions(options) {
     valueFn = validateOption(options, "value");
 
     // Cast function options to functions
-    inverseKeyFn &&= toFunction(inverseKeyFn);
-    keyFn &&= toFunction(keyFn);
-    valueFn &&= toFunction(valueFn);
+    inverseKeyFn &&= castToFunction(inverseKeyFn, "inverseKey");
+    if (
+      typeof keyFn === "string" &&
+      (keyFn.includes("=>") || keyFn.includes("→"))
+    ) {
+      throw new TypeError(
+        `map: The key option appears to be an extension mapping. Did you mean to call Tree.mapExtension() ?`
+      );
+    }
+    keyFn &&= castToFunction(keyFn, "key");
+    valueFn &&= castToFunction(valueFn, "value");
   } else if (options === undefined) {
     /** @type {any} */
     const error = new TypeError(`map: The second parameter was undefined.`);
@@ -248,3 +257,13 @@ function validateOptions(options) {
     valueFn,
   };
 }
+
+function castToFunction(object, name) {
+  const fn = toFunction(object);
+  if (!fn) {
+    throw new TypeError(
+      `map: The ${name} option must be a function but couldn't be treated as one.`
+    );
+  }
+  return fn;
+}

package/src/operations/mapReduce.js

@@ -2,39 +2,42 @@ 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 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.
+ * 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.
+ *
+ * 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 {Maplike} maplike
- * @param {ValueKeyFn|null} mapFn
+ * @param {Maplike} source
+ * @param {ValueKeyFn|null} valueFn
  * @param {ReduceFn} reduceFn
  */
-export default async function mapReduce(maplike, mapFn, reduceFn) {
-  const map = await getMapArgument(maplike, "mapReduce");
+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 treeKeys = [];
+  const mapped = new Map();
   const promises = [];
-  for await (const key of map.keys()) {
-    treeKeys.push(key);
+  for await (const key of sourceMap.keys()) {
+    mapped.set(key, null); // placeholder
     const promise = (async () => {
-      const value = await map.get(key);
+      const value = await sourceMap.get(key);
       return isMap(value)
-        ? mapReduce(value, mapFn, reduceFn) // subtree; recurse
-        : mapFn
-        ? mapFn(value, key, map)
+        ? mapReduce(value, valueFn, reduceFn) // subtree; recurse
+        : valueFn
+        ? valueFn(value, key, sourceMap)
         : value;
     })();
     promises.push(promise);
@@ -44,6 +47,12 @@ export default async function mapReduce(maplike, mapFn, reduceFn) {
   // 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, treeKeys, map);
+  return reduceFn(mapped, sourceMap);
 }

package/src/operations/mask.js

@@ -1,7 +1,6 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
 import getMapArgument from "../utilities/getMapArgument.js";
-import isMap from "./isMap.js";
 import isMaplike from "./isMaplike.js";
 import keys from "./keys.js";
 
@@ -17,7 +16,10 @@ import keys from "./keys.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function mask(aMaplike, bMaplike) {
-  const aMap = await getMapArgument(aMaplike, "filter", { position: 0 });
+  const aMap = await getMapArgument(aMaplike, "filter", {
+    deep: true,
+    position: 0,
+  });
   const bMap = await getMapArgument(bMaplike, "filter", {
     deep: true,
     position: 1,
@@ -32,7 +34,10 @@ export default async function mask(aMaplike, bMaplike) {
       if (!bValue) {
         return undefined;
       }
-      let aValue = await aMap.get(key);
+      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);
@@ -42,25 +47,36 @@ export default async function mask(aMaplike, bMaplike) {
     },
 
     async *keys() {
-      // Use a's keys as the basis
-      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(
+      // 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) || isMap(bValues[index])
-        )
-      );
-      // Remove keys that don't have values in b
-      const treeKeys = aKeySlashes.filter(
-        (key, index) => bValues[index] ?? false
-      );
-      yield* treeKeys;
+          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: /** @type {any} */ (aMap).trailingSlashKeys,
+    trailingSlashKeys: true,
   });
 }

package/src/operations/paths.js

@@ -1,47 +1,45 @@
 import * as trailingSlash from "../trailingSlash.js";
 import getMapArgument from "../utilities/getMapArgument.js";
+import from from "./from.js";
 import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Returns slash-separated paths for all values in the tree.
  *
  * The `base` argument is prepended to all paths.
  *
- * If `assumeSlashes` is true, then keys are assumed to have trailing slashes to
- * indicate subtrees. The default value of this option is false.
- *
  * @typedef {import("../../index.ts").Maplike} Maplike
  *
  * @param {Maplike} maplike
- * @param {{ assumeSlashes?: boolean, base?: string }} options
+ * @param {{ base?: string }} options
  */
 export default async function paths(maplike, options = {}) {
   const tree = await getMapArgument(maplike, "paths");
   const base = options.base ?? "";
-  const assumeSlashes = options.assumeSlashes ?? false;
   const result = [];
   for await (const key of tree.keys()) {
     const separator = trailingSlash.has(base) ? "" : "/";
     const valuePath = base ? `${base}${separator}${key}` : key;
-    let isSubtree;
     let value;
-    if (assumeSlashes) {
+    if (/** @type {any} */ (tree).trailingSlashKeys) {
       // Subtree needs to have a trailing slash
-      isSubtree = trailingSlash.has(key);
-      if (isSubtree) {
+      if (trailingSlash.has(key)) {
         // We'll need the value to recurse
         value = await tree.get(key);
+        // If it's maplike, treat as subtree
+        if (isMaplike(value)) {
+          value = from(value);
+        }
       }
     } else {
-      // Get value and check
+      // Get value
       value = await tree.get(key);
     }
-    if (value) {
-      // If we got the value we can check if it's a subtree
-      isSubtree = isMap(value);
-    }
-    if (isSubtree) {
-      const subPaths = await paths(value, { assumeSlashes, base: valuePath });
+
+    if (isMap(value)) {
+      // Subtree; recurse
+      const subPaths = await paths(value, { base: valuePath });
       result.push(...subPaths);
     } else {
       result.push(valuePath);

package/src/operations/reduce.js

@@ -0,0 +1,16 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+import mapReduce from "./mapReduce.js";
+
+/**
+ * Reduce a tree by recursively applying a reducer function to its nodes.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ * @typedef {import("../../index.ts").ReduceFn} ReduceFn
+ *
+ * @param {Maplike} maplike
+ * @param {ReduceFn} reduceFn
+ */
+export default async function reduce(maplike, reduceFn) {
+  const map = await getMapArgument(maplike, "reduce");
+  return mapReduce(map, null, reduceFn);
+}

package/src/operations/root.js

@@ -8,9 +8,9 @@ import getMapArgument from "../utilities/getMapArgument.js";
  *
  * @param {Maplike} maplike
  */
-export default function root(maplike) {
+export default async function root(maplike) {
   /** @type {any} */
-  let current = getMapArgument(maplike, "root");
+  let current = await getMapArgument(maplike, "root");
   while (current.parent || current[symbols.parent]) {
     current = current.parent || current[symbols.parent];
   }

package/src/operations/set.js

@@ -0,0 +1,20 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+
+/**
+ * Set a key/value pair in a map.
+ *
+ * @typedef  {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ * @param {any} key
+ * @param {any} value
+ */
+export default async function set(maplike, key, value) {
+  const map = await getMapArgument(maplike, "set");
+  await map.set(key, value);
+
+  // Unlike Map.prototype.set, we return undefined. This is more useful when
+  // calling set in the console -- return the complete tree would result in it
+  // being dumped to the console.
+  return undefined;
+}

package/src/operations/sync.js

@@ -1,6 +1,5 @@
-import SyncMap from "../drivers/SyncMap.js";
 import getMapArgument from "../utilities/getMapArgument.js";
-import mapReduce from "./mapReduce.js";
+import reduce from "./reduce.js";
 
 /**
  * Resolve the async tree to a synchronous tree.
@@ -11,11 +10,5 @@ import mapReduce from "./mapReduce.js";
  */
 export default async function sync(source) {
   const tree = await getMapArgument(source, "sync");
-  return mapReduce(tree, null, (values, keys) => {
-    const entries = [];
-    for (let i = 0; i < keys.length; i++) {
-      entries.push([keys[i], values[i]]);
-    }
-    return new SyncMap(entries);
-  });
+  return reduce(tree, (mapped) => mapped);
 }

package/src/operations/traverseOrThrow.js

@@ -59,5 +59,10 @@ export default async function traverseOrThrow(maplike, ...keys) {
     position++;
   }
 
+  // If last key ended in a slash and value is unpackable, unpack it.
+  if (key && trailingSlash.has(key) && isUnpackable(value)) {
+    value = await value.unpack();
+  }
+
   return value;
 }

package/src/utilities/castArraylike.js

@@ -1,29 +1,30 @@
+import * as trailingSlash from "../trailingSlash.js";
+
 /**
- * Create an array or plain object from the given keys and values.
+ * Cast the given map to a plain object or array.
  *
  * If the given plain object has only integer keys, and the set of integers is
  * complete from 0 to length-1, assume the values are a result of array
  * transformations and the values are the desired result; return them as is.
- * Otherwise, create a plain object with the keys and values.
  *
- * @param {any[]} keys
- * @param {any[]} values
+ * Otherwise, call the createFn to create an object. By default, this will
+ * create a plain object from the map's entries.
+ *
+ * @param {Map} map
+ * @param {Function} [createFn]
  */
-export default function castArraylike(
-  keys,
-  values,
-  createFn = Object.fromEntries
-) {
-  if (keys.length === 0) {
+export default function castArraylike(map, createFn = Object.fromEntries) {
+  if (map.size === 0) {
     // Empty keys/values means an empty object, not an empty array
     return {};
   }
 
   let onlyNumericKeys = true;
-  const numberSeen = new Array(keys.length);
-  for (const key of keys) {
-    const n = Number(key);
-    if (isNaN(n) || !Number.isInteger(n) || n < 0 || n >= keys.length) {
+  const numberSeen = new Array(map.size).fill(false);
+  for (const key of map.keys()) {
+    const normalized = trailingSlash.remove(key);
+    const n = Number(normalized);
+    if (isNaN(n) || !Number.isInteger(n) || n < 0 || n >= map.size) {
       onlyNumericKeys = false;
       break;
     } else {
@@ -34,13 +35,15 @@ export default function castArraylike(
   // If any number from 0..length-1 is missing, we can't treat this as an array
   const allNumbersSeen = onlyNumericKeys && numberSeen.every((v) => v);
   if (allNumbersSeen) {
-    return values;
+    return Array.from(map.values());
   } else {
-    // Return a plain object with the (key, value) pairs
-    const entries = [];
-    for (let i = 0; i < keys.length; i++) {
-      entries.push([keys[i], values[i]]);
+    // Create a map with normalized keys, then call the createFn to build the
+    // result. By default this will create a plain object from the entries.
+    const normalizedMap = new Map();
+    for (const [key, value] of map.entries()) {
+      const normalized = trailingSlash.remove(key);
+      normalizedMap.set(normalized, value);
     }
-    return createFn(entries);
+    return createFn(normalizedMap);
   }
 }

package/src/utilities/toPlainValue.js

@@ -1,7 +1,6 @@
 import ObjectMap from "../drivers/ObjectMap.js";
 import isMaplike from "../operations/isMaplike.js";
 import mapReduce from "../operations/mapReduce.js";
-import * as trailingSlash from "../trailingSlash.js";
 import castArraylike from "./castArraylike.js";
 import isPrimitive from "./isPrimitive.js";
 import isStringlike from "./isStringlike.js";
@@ -72,14 +71,13 @@ export default async function toPlainValue(
   }
 }
 
-function reduceToPlainObject(values, keys, map) {
-  // Special case for an empty tree: if based on array, return array.
-  if (map instanceof ObjectMap && keys.length === 0) {
-    return /** @type {any} */ (map).object instanceof Array ? [] : {};
-  }
+function reduceToPlainObject(mapped, source) {
   // Normalize slashes in keys.
-  keys = keys.map(trailingSlash.remove);
-  return castArraylike(keys, values);
+  // Special case for an empty map: if based on array, return array.
+  if (mapped.size === 0 && source instanceof ObjectMap) {
+    return /** @type {any} */ (source).object instanceof Array ? [] : {};
+  }
+  return castArraylike(mapped);
 }
 
 function toBase64(object) {

package/test/browser/index.html

@@ -18,7 +18,6 @@
     <script type="module" src="../drivers/BrowserFileMap.test.js"></script>
     <script type="module" src="../drivers/CalendarMap.test.js"></script>
     <script type="module" src="../drivers/ConstantMap.test.js"></script>
-    <script type="module" src="../drivers/DeepObjectMap.test.js"></script>
     <script type="module" src="../drivers/FunctionMap.test.js"></script>
     <script type="module" src="../drivers/ObjectMap.test.js"></script>
     <script type="module" src="../drivers/SetMap.test.js"></script>