@weborigami/async-tree 0.5.8 → 0.6.1

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,
+  });
 }

package/src/operations/paginate.js

@@ -1,23 +1,27 @@
+import AsyncMap from "../drivers/AsyncMap.js";
+import SyncMap from "../drivers/SyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
- * Return a new grouping of the treelike's values into chunks of the specified
+ * Return a new grouping of the map's values into chunks of the specified
  * size.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {number} [size=10]
  */
-export default async function paginate(treelike, size = 10) {
-  const tree = await getTreeArgument(treelike, "paginate");
+export default async function paginate(maplike, size = 10) {
+  const source = await getMapArgument(maplike, "paginate");
 
-  const keys = Array.from(await tree.keys());
-  const pageCount = Math.ceil(keys.length / size);
+  const treeKeys = await keys(source);
+  const pageCount = Math.ceil(treeKeys.length / size);
+
+  const paginated = Object.assign(new AsyncMap(), {
+    description: "paginate",
 
-  const paginated = {
     async get(pageKey) {
       const normalized = trailingSlash.remove(pageKey);
       // Note: page numbers are 1-based.
@@ -27,14 +31,14 @@ export default async function paginate(treelike, size = 10) {
       }
       const nextPage = pageNumber + 1 <= pageCount ? pageNumber + 1 : null;
       const previousPage = pageNumber - 1 >= 1 ? pageNumber - 1 : null;
-      const items = new Map();
+      const items = new SyncMap();
       for (
         let index = (pageNumber - 1) * size;
-        index < Math.min(keys.length, pageNumber * size);
+        index < Math.min(treeKeys.length, pageNumber * size);
         index++
       ) {
-        const key = keys[index];
-        items.set(key, await tree.get(keys[index]));
+        const key = treeKeys[index];
+        items.set(key, await source.get(treeKeys[index]));
       }
 
       return {
@@ -46,11 +50,15 @@ export default async function paginate(treelike, size = 10) {
       };
     },
 
-    async keys() {
-      // Return an array from 1..totalPages
-      return Array.from({ length: pageCount }, (_, index) => index + 1);
+    async *keys() {
+      // Return from 1..totalPages
+      yield* Array.from({ length: pageCount }, (_, index) => index + 1);
     },
-  };
+
+    source: source,
+
+    trailingSlashKeys: false,
+  });
 
   return paginated;
 }

package/src/operations/parent.js

@@ -1,13 +1,13 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Returns the parent of the current tree.
+ * Returns the parent of the map, if any.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function parent(treelike) {
-  const tree = await getTreeArgument(treelike, "parent");
-  return tree.parent;
+export default async function parent(maplike) {
+  const map = await getMapArgument(maplike, "parent");
+  return "parent" in map ? map.parent : undefined;
 }

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 isAsyncTree from "./isAsyncTree.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
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
- *
- * @param {Treelike} treelike
- * @param {{ assumeSlashes?: boolean, base?: string }} options
+ * @param {Maplike} maplike
+ * @param {{ base?: string }} options
  */
-export default async function paths(treelike, options = {}) {
-  const tree = from(treelike);
+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 (const key of await tree.keys()) {
+  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 = isAsyncTree(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/plain.js

@@ -1,4 +1,4 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import toPlainValue from "../utilities/toPlainValue.js";
 
 /**
@@ -20,15 +20,15 @@ import toPlainValue from "../utilities/toPlainValue.js";
  * array `["b", "a", "c" ]` because the tree has the keys in that order. The
  * specific values of the keys (0, 1, and 2) are ignored.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  * @typedef {import("../../index.ts").PlainObject} PlainObject
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function plain(treelike) {
-  if (treelike instanceof Function) {
+export default async function plain(maplike) {
+  if (maplike instanceof Function) {
     throw new TypeError("plain: can't convert a function to a plain object");
   }
-  const tree = await getTreeArgument(treelike, "plain");
+  const tree = await getMapArgument(maplike, "plain");
   return toPlainValue(tree);
 }

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/regExpKeys.js

@@ -1,6 +1,8 @@
+import AsyncMap from "../drivers/AsyncMap.js";
+import SyncMap from "../drivers/SyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import isAsyncTree from "./isAsyncTree.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
 
 /**
  * A tree whose keys are strings interpreted as regular expressions.
@@ -10,16 +12,19 @@ import isAsyncTree from "./isAsyncTree.js";
  * taken to match the entire key -- if they do not already start and end with
  * `^` and `$` respectively, those are added.
  *
- * @type {import("../../index.ts").TreeTransform}
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function regExpKeys(treelike) {
-  const tree = await getTreeArgument(treelike, "regExpKeys");
+export default async function regExpKeys(maplike) {
+  const source = await getMapArgument(maplike, "regExpKeys", { deep: true });
 
-  const map = new Map();
+  const map = new SyncMap();
 
   // We build the output tree first so that we can refer to it when setting
   // `parent` on subtrees below.
-  let result = {
+  let result = Object.assign(new AsyncMap(), {
     // @ts-ignore
     description: "regExpKeys",
 
@@ -39,24 +44,28 @@ export default async function regExpKeys(treelike) {
       return undefined;
     },
 
-    async keys() {
+    async *keys() {
       return map.keys();
     },
-  };
+
+    source: source,
+
+    trailingSlashKeys: false,
+  });
 
   // Turn the input tree's string keys into regular expressions, then map those
   // to the corresponding values.
-  for (const key of await tree.keys()) {
+  for await (const key of source.keys()) {
     if (typeof key !== "string") {
       // Skip non-string keys.
       continue;
     }
 
     // Get value.
-    let value = await tree.get(key);
+    let value = await source.get(key);
 
     let regExp;
-    if (trailingSlash.has(key) || isAsyncTree(value)) {
+    if (trailingSlash.has(key) || isMap(value)) {
       const baseKey = trailingSlash.remove(key);
       regExp = new RegExp("^" + baseKey + "/?$");
       // Subtree

package/src/operations/reverse.js

@@ -1,26 +1,32 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
- * Reverse the order of the top-level keys in the tree.
+ * Return a new map with the keys reversed.
  *
- * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function reverse(treelike) {
-  const tree = await getTreeArgument(treelike, "reverse");
+export default async function reverse(maplike) {
+  const source = await getMapArgument(maplike, "reverse");
+  return Object.assign(new AsyncMap(), {
+    description: "reverse",
 
-  return {
     async get(key) {
-      return tree.get(key);
+      return source.get(key);
     },
 
-    async keys() {
-      const keys = Array.from(await tree.keys());
-      keys.reverse();
-      return keys;
+    async *keys() {
+      const treeKeys = await keys(source);
+      treeKeys.reverse();
+      yield* treeKeys;
     },
-  };
+
+    source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/root.js

@@ -1,15 +1,16 @@
 import * as symbols from "../symbols.js";
-import from from "./from.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
  * Walk up the `parent` chain to find the root of the tree.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default function root(treelike) {
-  let current = from(treelike);
+export default function root(maplike) {
+  /** @type {any} */
+  let current = getMapArgument(maplike, "root");
   while (current.parent || current[symbols.parent]) {
     current = current.parent || current[symbols.parent];
   }

package/src/operations/scope.js

@@ -1,48 +1,49 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * A tree's "scope" is the collection of everything in that tree and all of its
+ * A map's "scope" is the collection of everything in that map and all of its
  * ancestors.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
- * @returns {Promise<AsyncTree & {trees: AsyncTree[]}>}
+ * @param {Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function scope(treelike) {
-  const tree = await getTreeArgument(treelike, "scope");
+export default async function scope(maplike) {
+  const source = await getMapArgument(maplike, "scope");
 
-  return {
-    // Starting with this tree, search up the parent hierarchy.
+  return Object.assign(new AsyncMap(), {
+    description: "scope",
+
+    // Starting with this map, search up the parent hierarchy.
     async get(key) {
-      /** @type {AsyncTree|null|undefined} */
-      let current = tree;
+      /** @type {Map|AsyncMap|null} */
+      let current = source;
       let value;
       while (current) {
         value = await current.get(key);
         if (value !== undefined) {
           break;
         }
-        current = current.parent;
+        current = "parent" in current ? current.parent : null;
       }
       return value;
     },
 
     // Collect all keys for this tree and all parents
-    async keys() {
-      const keys = new Set();
-
-      /** @type {AsyncTree|null|undefined} */
-      let current = tree;
+    async *keys() {
+      const scopeKeys = new Set();
+      /** @type {Map|AsyncMap|null} */
+      let current = source;
       while (current) {
-        for (const key of await current.keys()) {
-          keys.add(key);
+        for await (const key of current.keys()) {
+          scopeKeys.add(key);
         }
-        current = current.parent;
+        current = "parent" in current ? current.parent : null;
       }
 
-      return keys;
+      yield* scopeKeys;
     },
 
     // Collect all keys for this tree and all parents.
@@ -52,14 +53,18 @@ export default async function scope(treelike) {
     get trees() {
       const result = [];
 
-      /** @type {AsyncTree|null|undefined} */
-      let current = tree;
+      /** @type {Map|AsyncMap|null} */
+      let current = source;
       while (current) {
         result.push(current);
-        current = current.parent;
+        current = "parent" in current ? current.parent : null;
       }
 
       return result;
     },
-  };
+
+    source: source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

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;
+}