@weborigami/async-tree 0.5.8 → 0.6.1

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,14 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+import reduce from "./reduce.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 reduce(tree, (mapped) => mapped);
+}

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

package/src/operations/text.js

@@ -1,10 +1,10 @@
 import toString from "../utilities/toString.js";
 import deepText from "./deepText.js";
-import isTreelike from "./isTreelike.js";
+import isMaplike from "./isMaplike.js";
 
 /**
- * A tagged template literal function that concatenate the deep text values in a
- * tree. Any treelike values will be concatenated using `deepText`.
+ * A tagged template literal function that concatenate the deep text values in
+ * any trees using `deepText`.
  *
  * @param {TemplateStringsArray} strings
  * @param  {...any} values
@@ -13,7 +13,7 @@ export default async function text(strings, ...values) {
   // Convert all the values to strings
   const valueTexts = await Promise.all(
     values.map((value) =>
-      isTreelike(value) ? deepText(value) : toString(value)
+      isMaplike(value) ? deepText(value) : toString(value)
     )
   );
   // Splice all the strings together

package/src/operations/toFunction.js

@@ -1,14 +1,14 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Returns a function that invokes the tree's `get` method.
+ * Returns a function that invokes the map's `get` method.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @returns {Promise<Function>}
  */
-export default async function toFunction(treelike) {
-  const tree = await getTreeArgument(treelike, "toFunction");
-  return tree.get.bind(tree);
+export default async function toFunction(maplike) {
+  const map = await getMapArgument(maplike, "toFunction");
+  return map.get.bind(map);
 }

package/src/operations/traverse.js

@@ -4,16 +4,16 @@ import traverseOrThrow from "./traverseOrThrow.js";
 /**
  * Return the value at the corresponding path of keys.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {...any} keys
  */
-export default async function traverse(treelike, ...keys) {
+export default async function traverse(maplike, ...keys) {
   try {
     // Await the result here so that, if the path doesn't exist, the catch
     // block below will catch the exception.
-    return await traverseOrThrow(treelike, ...keys);
+    return await traverseOrThrow(maplike, ...keys);
   } catch (/** @type {any} */ error) {
     if (error instanceof TraverseError) {
       return undefined;

package/src/operations/traverseOrThrow.js

@@ -1,3 +1,4 @@
+import * as trailingSlash from "../trailingSlash.js";
 import TraverseError from "../TraverseError.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import from from "./from.js";
@@ -6,16 +7,15 @@ import from from "./from.js";
  * Return the value at the corresponding path of keys. Throw if any interior
  * step of the path doesn't lead to a result.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param  {...any} keys
  */
-export default async function traverseOrThrow(treelike, ...keys) {
+export default async function traverseOrThrow(maplike, ...keys) {
   // Start our traversal at the root of the tree.
   /** @type {any} */
-  let value = treelike;
+  let value = maplike;
   let position = 0;
 
   // Process all the keys.
@@ -24,7 +24,7 @@ export default async function traverseOrThrow(treelike, ...keys) {
   while (remainingKeys.length > 0) {
     if (value == null) {
       throw new TraverseError("A null or undefined value can't be traversed", {
-        tree: treelike,
+        tree: maplike,
         keys,
         position,
       });
@@ -44,16 +44,25 @@ export default async function traverseOrThrow(treelike, ...keys) {
       key = null;
       value = await fn(...args);
     } else {
-      // Cast value to a tree.
-      const tree = from(value);
+      // Cast value to a map.
+      const map = from(value);
       // Get the next key.
       key = remainingKeys.shift();
+      // Remove trailing slash if not supported
+      const normalized = /** @type {any} */ (map).trailingSlashKeys
+        ? key
+        : trailingSlash.remove(key);
       // Get the value for the key.
-      value = await tree.get(key);
+      value = await map.get(normalized);
     }
 
     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/operations/traversePath.js

@@ -5,9 +5,9 @@ import traverse from "./traverse.js";
  * Given a slash-separated path like "foo/bar", traverse the keys "foo/" and
  * "bar" and return the resulting value.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} tree
+ * @param {Maplike} tree
  * @param {string} path
  */
 export default async function traversePath(tree, path) {

package/src/operations/values.js

@@ -1,15 +1,24 @@
-import from from "./from.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Return the values in the specific node of the tree.
+ * Return the values in the map.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function values(treelike) {
-  const tree = from(treelike);
-  const keys = Array.from(await tree.keys());
-  const promises = keys.map(async (key) => tree.get(key));
-  return Promise.all(promises);
+export default async function values(maplike) {
+  const map = await getMapArgument(maplike, "values");
+  let result;
+  /** @type {any} */
+  let iterable = map.values();
+  if (Symbol.asyncIterator in iterable) {
+    result = [];
+    for await (const key of iterable) {
+      result.push(key);
+    }
+  } else {
+    result = Array.from(iterable);
+  }
+  return result;
 }

package/src/operations/withKeys.js

@@ -1,33 +1,39 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import values from "./values.js";
 
 /**
- * Return a tree whose keys are provided by the _values_ of a second tree (e.g.,
+ * Return a map whose keys are provided by the _values_ of a second map (e.g.,
  * an array of keys).
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
- * @param {Treelike} keysTreelike
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} maplike
+ * @param {Maplike} keysMaplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function withKeys(treelike, keysTreelike) {
-  const tree = await getTreeArgument(treelike, "withKeys", { position: 0 });
-  const keysTree = await getTreeArgument(keysTreelike, "withKeys", {
+export default async function withKeys(maplike, keysMaplike) {
+  const source = await getMapArgument(maplike, "withKeys", { position: 0 });
+  const keysMap = await getMapArgument(keysMaplike, "withKeys", {
     position: 1,
   });
 
   let keys;
 
-  return {
+  return Object.assign(new AsyncMap(), {
+    description: "withKeys",
+
     async get(key) {
-      return tree.get(key);
+      return source.get(key);
     },
 
-    async keys() {
-      keys ??= await values(keysTree);
-      return keys;
+    async *keys() {
+      keys ??= await values(keysMap);
+      yield* keys;
     },
-  };
+
+    source: source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/symbols.js

@@ -1,3 +1,4 @@
+export const async = Symbol("async");
 export const deep = Symbol("deep");
 export const keys = Symbol("keys");
 export const parent = Symbol("parent");

package/src/utilities/castArraylike.js

@@ -1,25 +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) {
-  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 {
@@ -30,9 +35,15 @@ export default function castArraylike(keys, values) {
   // 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
-    return Object.fromEntries(keys.map((key, i) => [key, 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(normalizedMap);
   }
 }

package/src/utilities/getMapArgument.js

@@ -0,0 +1,38 @@
+import from from "../operations/from.js";
+import isUnpackable from "./isUnpackable.js";
+
+/**
+ * Convert the indicated argument to a map, or throw an exception.
+ *
+ * Tree operations can use this to validate the map argument and provide more
+ * helpful error messages. This also unpacks a unpackable map argument.
+ *
+ * @typedef {import("../../index.ts").AsyncMap} AsyncMap
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ * @typedef {import("../../index.ts").Unpackable} Unpackable
+ *
+ * @param {Maplike|Unpackable} maplike
+ * @param {string} operation
+ * @param {{ deep?: boolean, position?: number }} [options]
+ * @returns {Promise<Map|AsyncMap>}
+ */
+export default async function getMapArgument(maplike, operation, options = {}) {
+  const deep = options.deep;
+  const position = options.position ?? 0;
+
+  if (isUnpackable(maplike)) {
+    maplike = await maplike.unpack();
+  }
+
+  let map;
+  try {
+    map = from(maplike, { deep });
+  } catch (/** @type {any} */ error) {
+    let message = error.message ?? error;
+    message = `${operation}: ${message}`;
+    const newError = new TypeError(message);
+    /** @type {any} */ (newError).position = position;
+    throw newError;
+  }
+  return map;
+}

package/src/utilities/getParent.js

@@ -5,11 +5,11 @@ import * as symbols from "../symbols.js";
  *
  * This is intended to be called by unpack functions.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
  *
  * @param {any} packed
  * @param {any} [options]
- * @returns {AsyncTree|null}
+ * @returns {SyncOrAsyncMap|null}
  */
 export default function getParent(packed, options = {}) {
   // Prefer parent set on options

package/src/utilities/isStringlike.js

@@ -6,15 +6,17 @@ import getRealmObjectPrototype from "./getRealmObjectPrototype.js";
  *
  * @typedef {import("../../index.ts").Stringlike} Stringlike
  *
- * @param {any} obj
+ * @param {any} object
  * @returns {obj is Stringlike}
  */
-export default function isStringlike(obj) {
-  if (typeof obj === "string") {
+export default function isStringlike(object) {
+  if (typeof object === "string") {
     return true;
-  } else if (obj?.toString === undefined) {
+  } else if (typeof object === "symbol") {
     return false;
-  } else if (obj.toString === getRealmObjectPrototype(obj)?.toString) {
+  } else if (object?.toString === undefined) {
+    return false;
+  } else if (object.toString === getRealmObjectPrototype(object)?.toString) {
     // The stupid Object.prototype.toString implementation always returns
     // "[object Object]", so if that's the only toString method the object has,
     // we return false.