@weborigami/async-tree 0.5.8 → 0.6.1

package/src/operations/deepValuesIterator.js

@@ -1,32 +1,32 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import isAsyncTree from "./isAsyncTree.js";
-import isTreelike from "./isTreelike.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Return an iterator that yields all values in a tree, including nested trees.
  *
- * If the `expand` option is true, treelike values (but not functions) will be
+ * If the `expand` option is true, maplike values (but not functions) will be
  * expanded into nested trees and their values will be yielded.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  * @param {{ expand?: boolean }} [options]
  * @returns {AsyncGenerator<any, void, undefined>}
  */
 export default async function* deepValuesIterator(
-  treelike,
+  maplike,
   options = { expand: false }
 ) {
-  const tree = await getTreeArgument(treelike, "deepValuesIterator", {
+  const tree = await getMapArgument(maplike, "deepValuesIterator", {
     deep: true,
   });
 
-  for (const key of await tree.keys()) {
-    let value = await tree.get(key);
+  for await (const key of tree.keys()) {
+    const value = await tree.get(key);
 
     // Recurse into child trees, but don't expand functions.
     const recurse =
-      isAsyncTree(value) ||
-      (options.expand && typeof value !== "function" && isTreelike(value));
+      isMap(value) ||
+      (options.expand && typeof value !== "function" && isMaplike(value));
     if (recurse) {
       yield* deepValuesIterator(value, options);
     } else {

package/src/operations/delete.js

@@ -1,20 +1,16 @@
-import has from "./has.js";
-
 /**
  * Removes the value for the given key from the specific node of the tree.
  *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {AsyncMutableTree} tree
+ * @param {Maplike} maplike
  * @param {any} key
  */
+
+import getMapArgument from "../utilities/getMapArgument.js";
+
 // `delete` is a reserved word in JavaScript, so we use `del` instead.
-export default async function del(tree, key) {
-  const exists = await has(tree, key);
-  if (exists) {
-    await tree.set(key, undefined);
-    return true;
-  } else {
-    return false;
-  }
+export default async function del(maplike, key) {
+  const map = await getMapArgument(maplike, "delete");
+  return map.delete(key);
 }

package/src/operations/entries.js

@@ -1,16 +1,23 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Returns a new `Iterator` object that contains a two-member array of `[key,
- * value]` for each element in the specific node of the tree.
+ * Returns an array of `[key, value]` for each entry in the map.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
+ * @returns {Promise<Array<[any, any]>>}
  */
-export default async function entries(treelike) {
-  const tree = await getTreeArgument(treelike, "entries");
-  const keys = Array.from(await tree.keys());
-  const promises = keys.map(async (key) => [key, await tree.get(key)]);
-  return Promise.all(promises);
+export default async function entries(maplike) {
+  const map = await getMapArgument(maplike, "entries");
+  if (map instanceof Map) {
+    return Array.from(map.entries());
+  } else {
+    // AsyncMap
+    const result = [];
+    for await (const entry of map) {
+      result.push(entry);
+    }
+    return result;
+  }
 }

package/src/operations/filter.js

@@ -1,18 +1,18 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import map from "./map.js";
 
 /**
  * Given a tree an a test function, return a new tree whose keys correspond to
  * the values that pass the test function.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ * @typedef {import("../../index.ts").AsyncMap} AsyncMap
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {function|any} options
- * @returns {Promise<AsyncTree>}
+ * @returns {Promise<AsyncMap>}
  */
-export default async function filter(treelike, options) {
+export default async function filter(maplike, options) {
   let testFn;
   let deep;
   if (typeof options === "function") {
@@ -23,10 +23,12 @@ export default async function filter(treelike, options) {
     deep = options.deep ?? false;
   }
 
-  const tree = await getTreeArgument(treelike, "filter", { deep });
+  const tree = await getMapArgument(maplike, "filter", { deep });
   return map(tree, {
     deep,
 
+    description: "filter",
+
     // Assume source key is the same as result key
     inverseKey: async (resultKey) => resultKey,
 

package/src/operations/first.js

@@ -1,18 +1,20 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
  * Return the first value in the tree.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function first(treelike) {
-  const tree = await getTreeArgument(treelike, "first");
-  for (const key of await tree.keys()) {
-    // Just return first value immediately.
-    const value = await tree.get(key);
-    return value;
+export default async function first(maplike) {
+  const map = await getMapArgument(maplike, "first");
+  let firstKey;
+  for await (const key of map.keys()) {
+    // Just needed to get first key
+    firstKey = key;
+    break;
   }
-  return undefined;
+  const value = firstKey ? await map.get(firstKey) : undefined;
+  return value;
 }

package/src/operations/forEach.js

@@ -1,20 +1,17 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Calls callbackFn once for each key-value pair present in the specific node of
- * the tree.
+ * Calls callbackFn once for each key-value pair present in the map.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {Function} callbackFn
  */
-export default async function forEach(treelike, callbackFn) {
-  const tree = await getTreeArgument(treelike, "forEach");
-  const keys = Array.from(await tree.keys());
-  const promises = keys.map(async (key) => {
-    const value = await tree.get(key);
-    return callbackFn(value, key, tree);
-  });
-  await Promise.all(promises);
+export default async function forEach(maplike, callbackFn) {
+  const map = await getMapArgument(maplike, "forEach");
+  for await (const key of map.keys()) {
+    const value = await map.get(key);
+    await callbackFn(value, key, map);
+  }
 }

package/src/operations/from.js

@@ -1,33 +1,30 @@
-import DeepObjectTree from "../drivers/DeepObjectTree.js";
-import DeferredTree from "../drivers/DeferredTree.js";
-import FunctionTree from "../drivers/FunctionTree.js";
-import MapTree from "../drivers/MapTree.js";
-import ObjectTree from "../drivers/ObjectTree.js";
-import SetTree from "../drivers/SetTree.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import FunctionMap from "../drivers/FunctionMap.js";
+import ObjectMap from "../drivers/ObjectMap.js";
+import SetMap from "../drivers/SetMap.js";
 import * as symbols from "../symbols.js";
 import box from "../utilities/box.js";
 import isPlainObject from "../utilities/isPlainObject.js";
-import isUnpackable from "../utilities/isUnpackable.js";
-import isAsyncTree from "./isAsyncTree.js";
+import setParent from "../utilities/setParent.js";
+import isMap from "./isMap.js";
 
 /**
- * Attempts to cast the indicated object to an async tree.
+ * Attempts to cast the indicated object to a map.
  *
- * If the object is a plain object, it will be converted to an ObjectTree. The
+ * 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
- * DeepObjectTree. 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").Treelike} Treelike
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike | Object} object
- * @param {{ deep?: boolean, parent?: AsyncTree|null }} [options]
- * @returns {AsyncTree}
+ * @param {Maplike | Object} object
+ * @param {{ deep?: boolean, parent?: Map|AsyncMap|null }} [options]
+ * @returns {Map|AsyncMap}
  */
 export default function from(object, options = {}) {
   const deep = options.deep ?? object[symbols.deep];
-  let tree;
+  let map;
   if (object == null) {
     throw new TypeError("The tree argument wasn't defined.");
   } else if (object instanceof Promise) {
@@ -35,29 +32,22 @@ export default function from(object, options = {}) {
     throw new TypeError(
       "The tree argument was a Promise. Did you mean to use await?"
     );
-  } else if (isAsyncTree(object)) {
-    // Argument already supports the tree interface.
-    // @ts-ignore
+  } else if (isMap(object)) {
+    // Already a map
     return object;
   } else if (typeof object === "function") {
-    tree = new FunctionTree(object);
-  } else if (object instanceof Map) {
-    tree = new MapTree(object);
+    map = new FunctionMap(object);
   } else if (object instanceof Set) {
-    tree = new SetTree(object);
+    map = new SetMap(object);
   } else if (isPlainObject(object) || object instanceof Array) {
-    tree = deep ? new DeepObjectTree(object) : new ObjectTree(object);
-  } else if (isUnpackable(object)) {
-    async function AsyncFunction() {} // Sample async function
-    tree =
-      object.unpack instanceof AsyncFunction.constructor
-        ? // Async unpack: return a deferred tree.
-          new DeferredTree(object.unpack, { deep })
-        : // Synchronous unpack: cast the result of unpack() to a tree.
-          from(object.unpack());
+    map = new ObjectMap(object, { deep });
+    // @ts-ignore
+  } else if (globalThis.Iterator && object instanceof Iterator) {
+    const array = Array.from(object);
+    map = new ObjectMap(array, { deep });
   } else if (object && typeof object === "object") {
     // An instance of some class.
-    tree = new ObjectTree(object);
+    map = new ObjectMap(object, { deep });
   } else if (
     typeof object === "string" ||
     typeof object === "number" ||
@@ -65,13 +55,14 @@ export default function from(object, options = {}) {
   ) {
     // A primitive value; box it into an object and construct a tree.
     const boxed = box(object);
-    tree = new ObjectTree(boxed);
+    map = new ObjectMap(boxed);
   } else {
-    throw new TypeError("Couldn't convert argument to an async tree");
+    throw new TypeError("Couldn't convert argument to a map");
   }
 
-  if (!tree.parent && options.parent) {
-    tree.parent = options.parent;
+  if (options.parent) {
+    setParent(map, options.parent);
   }
-  return tree;
+
+  return map;
 }

package/src/operations/globKeys.js

@@ -1,31 +1,36 @@
-import ObjectTree from "../drivers/ObjectTree.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import ObjectMap from "../drivers/ObjectMap.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";
 import merge from "./merge.js";
 
 const globstar = "**";
 const globstarSlash = `${globstar}/`;
 
-export default async function globKeys(treelike) {
-  const globs = await getTreeArgument(treelike, "globKeys", { deep: true });
-  return {
+export default async function globKeys(maplike) {
+  const source = await getMapArgument(maplike, "globKeys", { deep: true });
+  return Object.assign(new AsyncMap(), {
     async get(key) {
       if (typeof key !== "string") {
         return undefined;
       }
 
-      let value = await matchGlobs(globs, key);
-      if (isAsyncTree(value)) {
+      let value = await matchGlobs(source, key);
+      if (isMap(value)) {
         value = globKeys(value);
       }
       return value;
     },
 
-    async keys() {
-      return globs.keys();
+    async *keys() {
+      for await (const key of source.keys()) {
+        yield key;
+      }
     },
-  };
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }
 
 // Convert the glob to a regular expression
@@ -45,19 +50,19 @@ async function matchGlobs(globs, key) {
 
   // Collect all matches
   let matches = [];
-  for (let glob of await globs.keys()) {
-    if (glob === globstarSlash) {
+  for await (let glob of globs.keys()) {
+    if (glob === globstar || glob === globstarSlash) {
       // Remember for later
       globstarGlobs = await globs.get(glob);
       if (trailingSlash.has(key)) {
         // A key for a subtree matches the globstar
-        matches.push(new ObjectTree({ [globstar]: globstarGlobs }));
+        matches.push(new ObjectMap({ [globstar]: globstarGlobs }));
       }
     } else if (matchGlob(glob, key)) {
       // Text matches glob, get value
       const globValue = await globs.get(glob);
       if (globValue !== undefined) {
-        if (!isAsyncTree(globValue)) {
+        if (!isMap(globValue)) {
           // Found a non-tree match, return immediately
           return globValue;
         }
@@ -75,12 +80,12 @@ async function matchGlobs(globs, key) {
     } else {
       // Try globstar
       const globstarValue = await matchGlobs(globstarGlobs, key);
-      if (!isAsyncTree(globstarValue)) {
+      if (!isMap(globstarValue)) {
         // Found a non-tree match, return immediately
         return globstarValue;
       } else if (trailingSlash.has(key)) {
         // No match but key is for subtree, return globstar tree
-        return new ObjectTree({ [globstar]: globstarGlobs });
+        return new ObjectMap({ [globstar]: globstarGlobs });
       }
     }
   }

package/src/operations/group.js

@@ -1,6 +1,6 @@
 import groupBy from "./groupBy.js";
 
-export default async function group(treelike, groupKeyFn) {
+export default async function group(maplike, groupKeyFn) {
   console.warn("Tree.group() is deprecated. Use Tree.groupBy() instead.");
-  return groupBy(treelike, groupKeyFn);
+  return groupBy(maplike, groupKeyFn);
 }

package/src/operations/groupBy.js

@@ -1,51 +1,53 @@
-import ObjectTree from "../drivers/ObjectTree.js";
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import from from "./from.js";
-import isTreelike from "./isTreelike.js";
+import SyncMap from "../drivers/SyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import entries from "./entries.js";
+import isMaplike from "./isMaplike.js";
 import values from "./values.js";
 
 /**
  * Given a function that returns a grouping key for a value, returns a transform
  * that applies that grouping function to a tree.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  * @param {import("../../index.ts").ValueKeyFn} groupKeyFn
  */
-export default async function groupBy(treelike, groupKeyFn) {
-  const tree = await getTreeArgument(treelike, "groupBy");
+export default async function groupBy(maplike, groupKeyFn) {
+  const source = await getMapArgument(maplike, "groupBy");
 
-  const keys = Array.from(await tree.keys());
+  const result = new SyncMap();
+  const sourceEntries = await entries(source);
 
   // Are all the keys integers?
-  const isArray = keys.every((key) => !Number.isNaN(parseInt(key)));
-
-  const result = {};
-  for (const key of await tree.keys()) {
-    const value = await tree.get(key);
+  const integerKeys = sourceEntries.every(
+    ([key]) => !Number.isNaN(parseInt(key))
+  );
 
+  for (const [key, value] of sourceEntries) {
     // Get the groups for this value.
-    let groups = await groupKeyFn(value, key, tree);
+    let groups = await groupKeyFn(value, key, source);
     if (!groups) {
       continue;
     }
 
-    if (!isTreelike(groups)) {
+    if (!isMaplike(groups)) {
       // A single value was returned
       groups = [groups];
     }
-    groups = from(groups);
 
     // Add the value to each group.
     for (const group of await values(groups)) {
-      if (isArray) {
-        result[group] ??= [];
-        result[group].push(value);
+      let grouped = await result.get(group);
+      if (!grouped) {
+        grouped = integerKeys ? [] : new SyncMap();
+        result.set(group, grouped);
+      }
+      if (integerKeys) {
+        grouped.push(value);
       } else {
-        result[group] ??= {};
-        result[group][key] = value;
+        grouped.set(key, value);
       }
     }
   }
 
-  return new ObjectTree(result);
+  return result;
 }

package/src/operations/has.js

@@ -1,16 +1,14 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Returns a boolean indicating whether the specific node of the tree has a
- * value for the given `key`.
+ * Returns true if the map has the given key, false otherwise.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {any} key
  */
-export default async function has(treelike, key) {
-  const tree = await getTreeArgument(treelike, "has");
-  const value = await tree.get(key);
-  return value !== undefined;
+export default async function has(maplike, key) {
+  const map = await getMapArgument(maplike, "has");
+  return map.has(key);
 }

package/src/operations/indent.js

@@ -1,6 +1,6 @@
 import toString from "../utilities/toString.js";
 import deepText from "./deepText.js";
-import isTreelike from "./isTreelike.js";
+import isMaplike from "./isMaplike.js";
 
 const lastLineWhitespaceRegex = /\n(?<indent>[ \t]*)$/;
 
@@ -21,7 +21,7 @@ export default async function indent(strings, ...values) {
   }
   const { blockIndentations, strings: modifiedStrings } = modified;
   const valueTexts = await Promise.all(
-    values.map((value) => (isTreelike(value) ? deepText(value) : value))
+    values.map((value) => (isMaplike(value) ? deepText(value) : value))
   );
   return joinBlocks(modifiedStrings, valueTexts, blockIndentations);
 }

package/src/operations/inners.js

@@ -1,29 +1,33 @@
+import AsyncMap from "../drivers/AsyncMap.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";
 
 /**
  * Return the interior nodes of the tree. This relies on subtree keys having
  * trailing slashes.
  *
- * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function inners(treelike) {
-  const tree = await getTreeArgument(treelike, "inners");
+export default async function inners(maplike) {
+  const source = await getMapArgument(maplike, "inners");
 
-  return {
+  return Object.assign(new AsyncMap(), {
     async get(key) {
-      const value = await tree.get(key);
-      return isAsyncTree(value) ? inners(value) : undefined;
+      const value = await source.get(key);
+      return isMap(value) ? inners(value) : undefined;
     },
 
-    async keys() {
-      const keys = [...(await tree.keys())];
-      const subtreeKeys = keys.filter(trailingSlash.has);
-      return subtreeKeys;
+    async *keys() {
+      for await (const key of source.keys()) {
+        if (trailingSlash.has(key)) {
+          yield key;
+        }
+      }
     },
-  };
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/invokeFunctions.js

@@ -1,21 +1,33 @@
-import from from "./from.js";
-import isAsyncTree from "./isAsyncTree.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
+
+export default async function invokeFunctions(maplike) {
+  const source = await getMapArgument(maplike, "invokeFunctions", {
+    deep: true,
+  });
+
+  return Object.assign(new AsyncMap(), {
+    description: "invokeFunctions",
 
-export default async function invokeFunctions(treelike) {
-  const tree = from(treelike);
-  return {
     async get(key) {
-      let value = await tree.get(key);
+      let value = await source.get(key);
       if (typeof value === "function") {
         value = value();
-      } else if (isAsyncTree(value)) {
+      } else if (isMap(value)) {
         value = invokeFunctions(value);
       }
       return value;
     },
 
-    async keys() {
-      return tree.keys();
+    async *keys() {
+      for await (const key of source.keys()) {
+        yield key;
+      }
     },
-  };
+
+    source: source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/isAsyncMutableTree.js

@@ -1,15 +1,8 @@
-import isAsyncTree from "./isAsyncTree.js";
+import isReadOnlyMap from "./isReadOnlyMap.js";
 
-/**
- * Return true if the indicated object is an async mutable tree.
- *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
- *
- * @param {any} obj
- * @returns {obj is AsyncMutableTree}
- */
-export default function isAsyncMutableTree(obj) {
-  return (
-    isAsyncTree(obj) && typeof (/** @type {any} */ (obj).set) === "function"
+export default function isAsyncMutableTree(treelike) {
+  console.warn(
+    "Tree.isAsyncMutableTree() is deprecated, use Tree.isReadOnlyMap() instead, which returns the inverse."
   );
+  return !isReadOnlyMap(treelike);
 }