@weborigami/async-tree 0.5.7 → 0.6.0

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,6 +1,6 @@
 import * as trailingSlash from "../trailingSlash.js";
-import from from "./from.js";
-import isAsyncTree from "./isAsyncTree.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
 
 /**
  * Returns slash-separated paths for all values in the tree.
@@ -10,17 +10,17 @@ import isAsyncTree from "./isAsyncTree.js";
  * 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").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {{ assumeSlashes?: boolean, 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;
@@ -38,7 +38,7 @@ export default async function paths(treelike, options = {}) {
     }
     if (value) {
       // If we got the value we can check if it's a subtree
-      isSubtree = isAsyncTree(value);
+      isSubtree = isMap(value);
     }
     if (isSubtree) {
       const subPaths = await paths(value, { assumeSlashes, base: 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/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/shuffle.js

@@ -1,33 +1,40 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
  * Return a new tree with the original's keys shuffled
  *
- * @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 {boolean?} reshuffle
- * @returns {Promise<AsyncTree>}
+ * @returns {Promise<AsyncMap>}
  */
-export default async function shuffle(treelike, reshuffle = false) {
-  const tree = await getTreeArgument(treelike, "shuffle");
+export default async function shuffle(maplike, reshuffle = false) {
+  const source = await getMapArgument(maplike, "shuffle");
 
-  let keys;
+  let mapKeys;
+
+  return Object.assign(new AsyncMap(), {
+    description: "shuffle",
 
-  return {
     async get(key) {
-      return tree.get(key);
+      return source.get(key);
     },
 
-    async keys() {
-      if (!keys || reshuffle) {
-        keys = Array.from(await tree.keys());
-        shuffleArray(keys);
+    async *keys() {
+      if (!mapKeys || reshuffle) {
+        mapKeys = await keys(source);
+        shuffleArray(mapKeys);
       }
-      return keys;
+      yield* mapKeys;
     },
-  };
+
+    source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }
 
 /*

package/src/operations/size.js

@@ -0,0 +1,13 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+
+/**
+ * Return the number of keys in the map.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ */
+export default async function size(maplike) {
+  const map = await getMapArgument(maplike, "size");
+  return map.size;
+}

package/src/operations/sort.js

@@ -1,21 +1,23 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
- * Return a new tree with the original's keys sorted. A comparison function can
+ * Return a new map with the original's keys sorted. A comparison function can
  * be provided; by default the keys will be sorted in [natural sort
  * order](https://en.wikipedia.org/wiki/Natural_sort_order).
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {(key: any, tree: AsyncTree) => any} SortKeyFn
+ * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
+ * @typedef {(key: any, map: SyncOrAsyncMap) => any} SortKeyFn
  * @typedef {{ compare?: (a: any, b: any) => number, sortKey?: SortKeyFn }} SortOptions
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {SortOptions|ValueKeyFn} [options]
  */
-export default async function sort(treelike, options) {
-  const tree = await getTreeArgument(treelike, "sort");
+export default async function sort(maplike, options) {
+  const source = await getMapArgument(maplike, "sort");
 
   let sortKey;
   let compare;
@@ -27,39 +29,52 @@ export default async function sort(treelike, options) {
     sortKey = options?.sortKey;
   }
 
-  const transformed = Object.create(tree);
-  transformed.keys = async () => {
-    const keys = Array.from(await tree.keys());
+  const transformed = Object.assign(new AsyncMap(), {
+    descriptor: "sort",
 
-    if (sortKey) {
-      // Invoke the async sortKey function to get sort keys.
-      // Create { key, sortKey } tuples.
-      const tuples = await Promise.all(
-        keys.map(async (key) => {
-          const value = await tree.get(key);
-          const sort = await sortKey(value, key, tree);
-          if (sort === undefined) {
-            throw new Error(
-              `sortKey function returned undefined for key ${key}`
-            );
-          }
-          return { key, sort };
-        })
-      );
+    async get(key) {
+      return source.get(key);
+    },
+
+    async *keys() {
+      const treeKeys = await keys(source);
+
+      let resultKeys;
+      if (sortKey) {
+        // Invoke the async sortKey function to get sort keys.
+        // Create { key, sortKey } tuples.
+        const tuples = await Promise.all(
+          treeKeys.map(async (key) => {
+            const value = await source.get(key);
+            const sort = await sortKey(value, key, source);
+            if (sort === undefined) {
+              throw new Error(
+                `sortKey function returned undefined for key ${key}`
+              );
+            }
+            return { key, sort };
+          })
+        );
+
+        // Wrap the comparison function so it applies to sort keys.
+        const defaultCompare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+        const originalCompare = compare ?? defaultCompare;
+        // Sort by the sort key.
+        tuples.sort((a, b) => originalCompare(a.sort, b.sort));
+        // Map back to the original keys.
+        resultKeys = tuples.map((pair) => pair.key);
+      } else {
+        // Use original keys as sort keys.
+        // If compare is undefined, this uses default sort order.
+        resultKeys = treeKeys.slice().sort(compare);
+      }
+      yield* resultKeys;
+    },
+
+    source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 
-      // Wrap the comparison function so it applies to sort keys.
-      const defaultCompare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-      const originalCompare = compare ?? defaultCompare;
-      // Sort by the sort key.
-      tuples.sort((a, b) => originalCompare(a.sort, b.sort));
-      // Map back to the original keys.
-      const sorted = tuples.map((pair) => pair.key);
-      return sorted;
-    } else {
-      // Use original keys as sort keys.
-      // If compare is undefined, this uses default sort order.
-      return keys.slice().sort(compare);
-    }
-  };
   return transformed;
 }

package/src/operations/sync.js

@@ -0,0 +1,21 @@
+import SyncMap from "../drivers/SyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import mapReduce from "./mapReduce.js";
+
+/**
+ * Resolve the async tree to a synchronous tree.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} source
+ */
+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);
+  });
+}

package/src/operations/take.js

@@ -1,22 +1,34 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Returns a new tree with the number of keys limited to the indicated count.
+ * Returns a new map with the number of keys limited to the indicated count.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  * @param {number} count
  */
-export default async function take(treelike, count) {
-  const tree = await getTreeArgument(treelike, "take");
+export default async function take(maplike, count) {
+  const source = await getMapArgument(maplike, "take");
+  return Object.assign(new AsyncMap(), {
+    description: `take ${count}`,
 
-  return {
-    async keys() {
-      const keys = Array.from(await tree.keys());
-      return keys.slice(0, count);
+    async *keys() {
+      let i = 0;
+      for await (const key of source.keys()) {
+        yield key;
+        i += 1;
+        if (i >= count) {
+          break;
+        }
+      }
     },
 
     async get(key) {
-      return tree.get(key);
+      return source.get(key);
     },
-  };
+
+    source: source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }