@weborigami/async-tree 0.5.7 → 0.6.0

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,12 +44,16 @@ 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++;

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

@@ -9,7 +9,11 @@
  * @param {any[]} keys
  * @param {any[]} values
  */
-export default function castArraylike(keys, values) {
+export default function castArraylike(
+  keys,
+  values,
+  createFn = Object.fromEntries
+) {
   if (keys.length === 0) {
     // Empty keys/values means an empty object, not an empty array
     return {};
@@ -33,6 +37,10 @@ export default function castArraylike(keys, values) {
     return values;
   } else {
     // Return a plain object with the (key, value) pairs
-    return Object.fromEntries(keys.map((key, i) => [key, values[i]]));
+    const entries = [];
+    for (let i = 0; i < keys.length; i++) {
+      entries.push([keys[i], values[i]]);
+    }
+    return createFn(entries);
   }
 }

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.

package/src/utilities/setParent.js

@@ -1,21 +1,21 @@
-import isAsyncTree from "../operations/isAsyncTree.js";
+import isMap from "../operations/isMap.js";
 import * as symbols from "../symbols.js";
 
 /**
  * If the child object doesn't have a parent yet, set it to the indicated
- * parent. If the child is an AsyncTree, set the `parent` property. Otherwise,
+ * parent. If the child is a map, set the `parent` property. Otherwise,
  * set the `symbols.parent` property.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
  *
  * @param {*} child
- * @param {AsyncTree|null} parent
+ * @param {SyncOrAsyncMap|null} parent
  */
 export default function setParent(child, parent) {
-  if (isAsyncTree(child)) {
+  if (isMap(child)) {
     // Value is a subtree; set its parent to this tree.
-    if (!child.parent) {
-      child.parent = parent;
+    if ("parent" in child && !child.parent) {
+      /** @type {any} */ (child).parent = parent;
     }
   } else if (Object.isExtensible(child) && !child[symbols.parent]) {
     try {

package/src/utilities/toFunction.js

@@ -1,5 +1,5 @@
 import from from "../operations/from.js";
-import isTreelike from "../operations/isTreelike.js";
+import isMaplike from "../operations/isMaplike.js";
 import isUnpackable from "./isUnpackable.js";
 
 /**
@@ -29,7 +29,7 @@ export default function toFunction(obj) {
       const fn = await fnPromise;
       return fn(...args);
     };
-  } else if (isTreelike(obj)) {
+  } else if (isMaplike(obj)) {
     // Return a function that invokes the tree's getter.
     const tree = from(obj);
     return tree.get.bind(tree);

package/src/utilities/toPlainValue.js

@@ -1,5 +1,5 @@
-import ObjectTree from "../drivers/ObjectTree.js";
-import isTreelike from "../operations/isTreelike.js";
+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";
@@ -9,10 +9,8 @@ import toString from "./toString.js";
 import TypedArray from "./TypedArray.js";
 
 /**
- * Convert the given input to the plainest possible JavaScript value. This
- * helper is intended for functions that want to accept an argument from the ori
- * CLI, which could a string, a stream of data, or some other kind of JavaScript
- * object.
+ * Convert the given input to the plainest possible JavaScript value. This is
+ * useful for rendering data for display or serialization.
  *
  * If the input is a function, it will be invoked and its result will be
  * processed.
@@ -20,7 +18,7 @@ import TypedArray from "./TypedArray.js";
  * If the input is a promise, it will be resolved and its result will be
  * processed.
  *
- * If the input is treelike, it will be converted to a plain JavaScript object,
+ * If the input is maplike, it will be converted to a plain JavaScript object,
  * recursively traversing the tree and converting all values to plain types.
  *
  * If the input is stringlike, its text will be returned.
@@ -33,9 +31,13 @@ import TypedArray from "./TypedArray.js";
  * returned as a plain object.
  *
  * @param {any} input
+ * @param {import("../../index.ts").ReduceFn} [reduceFn]
  * @returns {Promise<any>}
  */
-export default async function toPlainValue(input) {
+export default async function toPlainValue(
+  input,
+  reduceFn = reduceToPlainObject
+) {
   if (input instanceof Function) {
     // Invoke function
     input = input();
@@ -47,17 +49,9 @@ export default async function toPlainValue(input) {
 
   if (isPrimitive(input) || input instanceof Date) {
     return input;
-  } else if (isTreelike(input)) {
+  } else if (isMaplike(input)) {
     // Recursively convert tree to plain object.
-    return mapReduce(input, toPlainValue, (values, keys, tree) => {
-      // Special case for an empty tree: if based on array, return array.
-      if (tree instanceof ObjectTree && keys.length === 0) {
-        return /** @type {any} */ (tree).object instanceof Array ? [] : {};
-      }
-      // Normalize slashes in keys.
-      keys = keys.map(trailingSlash.remove);
-      return castArraylike(keys, values);
-    });
+    return mapReduce(input, (value) => toPlainValue(value, reduceFn), reduceFn);
   } else if (input instanceof ArrayBuffer || input instanceof TypedArray) {
     // Try to interpret the buffer as UTF-8 text, otherwise use base64.
     const text = toString(input);
@@ -78,6 +72,16 @@ export default async function toPlainValue(input) {
   }
 }
 
+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 ? [] : {};
+  }
+  // Normalize slashes in keys.
+  keys = keys.map(trailingSlash.remove);
+  return castArraylike(keys, values);
+}
+
 function toBase64(object) {
   if (typeof Buffer !== "undefined") {
     // Node.js environment

package/test/SampleAsyncMap.js

@@ -0,0 +1,34 @@
+import AsyncMap from "../src/drivers/AsyncMap.js";
+import * as trailingSlash from "../src/trailingSlash.js";
+
+/**
+ * For testing AsyncMaps
+ */
+export default class SampleAsyncMap extends AsyncMap {
+  constructor(entries) {
+    super();
+    this.map = new Map(entries);
+  }
+
+  async delete(key) {
+    const normalized = trailingSlash.remove(key);
+    return this.map.delete(normalized);
+  }
+
+  async get(key) {
+    let value = this.map.get(key);
+    if (value instanceof Array) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+    return value;
+  }
+
+  async *keys() {
+    yield* this.map.keys();
+  }
+
+  async set(key, value) {
+    this.map.set(key, value);
+    return this;
+  }
+}

package/test/browser/assert.js

@@ -44,6 +44,10 @@ assert.deepEqual = (actual, expected) => {
   throw new Error(`Expected ${expected} but got ${actual}`);
 };
 
+// For browser testing purposes we treat these the same
+assert.strictEqual = assert.equal;
+assert.deepStrictEqual = assert.deepEqual;
+
 assert.rejects = async (fn) => {
   try {
     await fn();
@@ -52,3 +56,19 @@ assert.rejects = async (fn) => {
   }
   throw new Error("Expected promise to reject but it resolved");
 };
+
+assert.throws = (fn, expected) => {
+  try {
+    fn();
+  } catch (/** @type {any} */ error) {
+    if (expected) {
+      if (error.name !== expected.name || error.message !== expected.message) {
+        throw new Error(
+          `Expected error ${expected.name}: ${expected.message} but got ${error.name}: ${error.message}`
+        );
+      }
+    }
+    return;
+  }
+  throw new Error("Expected function to throw but it did not");
+};

package/test/browser/index.html

@@ -11,48 +11,81 @@
         }
       }
     </script>
-    <!-- Omit FileTree.test.js, which is Node.js only -->
-    <!-- Omit SiteTree.test.js, which requires mocks -->
+    <!-- Omit FileMap.test.js, which is Node.js only -->
+    <!-- Omit SiteMap.test.js, which requires mocks -->
 
-    <!-- Unclear why drivers/constantTree.test.js won't load -->
-
-    <script type="module" src="../Tree.test.js"></script>
-    <script type="module" src="../drivers/BrowserFileTree.test.js"></script>
-    <script type="module" src="../drivers/DeepMapTree.test.js"></script>
-    <script type="module" src="../drivers/DeepObjectTree.test.js"></script>
-    <script type="module" src="../drivers/DeferredTree.test.js"></script>
-    <script type="module" src="../drivers/FunctionTree.test.js"></script>
-    <script type="module" src="../drivers/MapTree.test.js"></script>
-    <script type="module" src="../drivers/ObjectTree.test.js"></script>
-    <script type="module" src="../drivers/SetTree.test.js"></script>
-    <script type="module" src="../drivers/calendarTree.test.js"></script>
+    <script type="module" src="../drivers/AsyncMap.test.js"></script>
+    <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>
+    <script type="module" src="../drivers/SyncMap.test.js"></script>
     <script type="module" src="../operations/addNextPrevious.test.js"></script>
+    <script type="module" src="../operations/assign.test.js"></script>
     <script type="module" src="../operations/cache.test.js"></script>
-    <script type="module" src="../operations/cache.test.js"></script>
-    <script type="module" src="../operations/cachedKeyFunctions.test.js"></script>
-    <script type="module" src="../operations/concat.test.js"></script>
+    <script
+      type="module"
+      src="../operations/cachedKeyFunctions.test.js"
+    ></script>
+    <script type="module" src="../operations/clear.test.js"></script>
+    <script type="module" src="../operations/deepEntries.test.js"></script>
     <script type="module" src="../operations/deepMerge.test.js"></script>
     <script type="module" src="../operations/deepReverse.test.js"></script>
     <script type="module" src="../operations/deepTake.test.js"></script>
     <script type="module" src="../operations/deepText.test.js"></script>
     <script type="module" src="../operations/deepValues.test.js"></script>
-    <script type="module" src="../operations/deepValuesIterator.test.js"></script>
-    <script type="module" src="../operations/extensionKeyFunctions.test.js"></script>
+    <script
+      type="module"
+      src="../operations/deepValuesIterator.test.js"
+    ></script>
+    <script type="module" src="../operations/delete.test.js"></script>
+    <script type="module" src="../operations/entries.test.js"></script>
+    <script
+      type="module"
+      src="../operations/extensionKeyFunctions.test.js"
+    ></script>
     <script type="module" src="../operations/filter.test.js"></script>
+    <script type="module" src="../operations/first.test.js"></script>
+    <script type="module" src="../operations/forEach.test.js"></script>
+    <script type="module" src="../operations/from.test.js"></script>
     <script type="module" src="../operations/globKeys.test.js"></script>
-    <script type="module" src="../operations/group.test.js"></script>
+    <script type="module" src="../operations/groupBy.test.js"></script>
+    <script type="module" src="../operations/groupBy.test.js"></script>
+    <script type="module" src="../operations/has.test.js"></script>
+    <script type="module" src="../operations/indent.test.js"></script>
+    <script type="module" src="../operations/inners.test.js"></script>
     <script type="module" src="../operations/invokeFunctions.test.js"></script>
+    <script type="module" src="../operations/isMap.test.js"></script>
+    <script type="module" src="../operations/isMaplike.test.js"></script>
+    <script type="module" src="../operations/json.test.js"></script>
+    <script type="module" src="../operations/keys.test.js"></script>
+    <script type="module" src="../operations/length.test.js"></script>
     <script type="module" src="../operations/map.test.js"></script>
+    <script type="module" src="../operations/mapExtension.test.js"></script>
+    <script type="module" src="../operations/mapReduce.test.js"></script>
     <script type="module" src="../operations/mask.test.js"></script>
+    <script type="module" src="../operations/match.test.js"></script>
     <script type="module" src="../operations/merge.test.js"></script>
     <script type="module" src="../operations/paginate.test.js"></script>
     <script type="module" src="../operations/parseExtensions.test.js"></script>
+    <script type="module" src="../operations/paths.test.js"></script>
+    <script type="module" src="../operations/plain.test.js"></script>
     <script type="module" src="../operations/regExpKeys.test.js"></script>
     <script type="module" src="../operations/reverse.test.js"></script>
     <script type="module" src="../operations/scope.test.js"></script>
+    <script type="module" src="../operations/shuffle.test.js"></script>
     <script type="module" src="../operations/sort.test.js"></script>
+    <script type="module" src="../operations/sync.test.js"></script>
     <script type="module" src="../operations/take.test.js"></script>
-    <script type="module" src="../utilities.test.js"></script>
+    <script type="module" src="../operations/text.test.js"></script>
+    <script type="module" src="../operations/toFunction.test.js"></script>
+    <script type="module" src="../operations/traverse.test.js"></script>
+    <script type="module" src="../operations/traversePath.test.js"></script>
+    <script type="module" src="../operations/values.test.js"></script>
+    <script type="module" src="../operations/withKeys.test.js"></script>
   </head>
   <body></body>
 </html>