@weborigami/async-tree 0.5.7 → 0.6.0

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,31 @@
-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 DeepObjectMap from "../drivers/DeepObjectMap.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
+ * DeepObjectMap. 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 +33,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 = deep ? new DeepObjectMap(object) : new ObjectMap(object);
+    // @ts-ignore
+  } else if (object instanceof Iterator) {
+    const array = Array.from(object);
+    map = new ObjectMap(array);
   } else if (object && typeof object === "object") {
     // An instance of some class.
-    tree = new ObjectTree(object);
+    map = new ObjectMap(object);
   } else if (
     typeof object === "string" ||
     typeof object === "number" ||
@@ -65,13 +56,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);
 }

package/src/operations/isAsyncTree.js

@@ -1,21 +1,6 @@
-/**
- * Return true if the indicated object is an async tree.
- *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- *
- * @param {any} obj
- * @returns {obj is AsyncTree}
- */
-export default function isAsyncTree(obj) {
-  return (
-    obj !== null &&
-    typeof obj === "object" &&
-    typeof obj.get === "function" &&
-    typeof obj.keys === "function" &&
-    // Regular JavaScript Map instances look like trees but can't have their
-    // prototype chains extended (the way map() does), so exclude them.
-    // Subclasses of Map that implement their own get() and keys() methods are
-    // allowed, because they shouldn't have the same limitations.
-    !(obj instanceof Map && Object.getPrototypeOf(obj) === Map.prototype)
-  );
+import isMap from "./isMap.js";
+
+export default function isAsyncTree(treelike) {
+  console.warn("Tree.isAsyncTree() is deprecated, use Tree.isMap() instead.");
+  return isMap(treelike);
 }

package/src/operations/isMap.js

@@ -0,0 +1,39 @@
+import AsyncMap from "../drivers/AsyncMap.js";
+
+/**
+ * Return true if the indicated object is a Map instance or supports
+ * a `Map` compatible interface.
+ *
+ * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
+ *
+ * @param {any} object
+ * @returns {object is Map|AsyncMap}
+ */
+export default function isMap(object) {
+  if (object instanceof Map || object instanceof AsyncMap) {
+    // Known positive cases
+    return true;
+  }
+
+  // Check for Map-like interface
+  if (
+    object &&
+    object.clear instanceof Function &&
+    object.delete instanceof Function &&
+    object.entries instanceof Function &&
+    object.forEach instanceof Function &&
+    object.get instanceof Function &&
+    object.has instanceof Function &&
+    object.keys instanceof Function &&
+    object.set instanceof Function &&
+    object.values instanceof Function &&
+    object.constructor.groupBy instanceof Function &&
+    "size" in object &&
+    (object[Symbol.iterator] instanceof Function ||
+      object[Symbol.asyncIterator] instanceof Function)
+  ) {
+    return true;
+  }
+
+  return false;
+}

package/src/operations/isMaplike.js

@@ -0,0 +1,34 @@
+import isPlainObject from "../utilities/isPlainObject.js";
+import isMap from "./isMap.js";
+
+/**
+ * Returns true if the indicated object can be directly treated like a Map. This
+ * includes:
+ *
+ * - A function
+ * - An `Array` instance
+ * - An `AsyncMap` instance
+ * - An `Iterator` instance
+ * - A `Map` instance
+ * - A `Set` instance
+ * - A plain object
+ *
+ * Note: the `from()` method accepts any JavaScript object, but `isMaplike`
+ * returns `false` for an object that isn't one of the above types.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {any} object
+ * @returns {obj is Maplike}
+ */
+export default function isMaplike(object) {
+  return (
+    object instanceof Array ||
+    object instanceof Function ||
+    // @ts-ignore
+    object instanceof Iterator ||
+    object instanceof Set ||
+    isMap(object) ||
+    isPlainObject(object)
+  );
+}

package/src/operations/isReadOnlyMap.js

@@ -0,0 +1,14 @@
+import isMap from "./isMap.js";
+
+/**
+ * Return true if the indicated object is a read-only map.
+ *
+ * @param {any} object
+ */
+export default function isReadOnlyMap(object) {
+  if (!isMap(object)) {
+    return false;
+  }
+  // Respect readOnly if defined, otherwise assume read/write
+  return "readOnly" in object ? object.readOnly : false;
+}

package/src/operations/isTraversable.js

@@ -1,15 +1,15 @@
 import isPacked from "../utilities/isPacked.js";
-import isTreelike from "./isTreelike.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Return true if the object can be traversed via the `traverse()` method. The
- * object must be either treelike or a packed object with an `unpack()` method.
+ * object must be either maplike or a packed object with an `unpack()` method.
  *
  * @param {any} object
  */
 export default function isTraversable(object) {
   return (
-    isTreelike(object) ||
+    isMaplike(object) ||
     (isPacked(object) && /** @type {any} */ (object).unpack instanceof Function)
   );
 }

package/src/operations/isTreelike.js

@@ -1,33 +1,8 @@
-import isPlainObject from "../utilities/isPlainObject.js";
-import isAsyncTree from "./isAsyncTree.js";
+import isMaplike from "./isMaplike.js";
 
-/**
- * Returns true if the indicated object can be directly treated as an
- * asynchronous tree. This includes:
- *
- * - An object that implements the AsyncTree interface (including
- *   AsyncTree instances)
- * - A function
- * - An `Array` instance
- * - A `Map` instance
- * - A `Set` instance
- * - A plain object
- *
- * Note: the `from()` method accepts any JavaScript object, but `isTreelike`
- * returns `false` for an object that isn't one of the above types.
- *
- * @typedef {import("../../index.ts").Treelike} Treelike
- *
- * @param {any} obj
- * @returns {obj is Treelike}
- */
-export default function isTreelike(obj) {
-  return (
-    isAsyncTree(obj) ||
-    obj instanceof Array ||
-    obj instanceof Function ||
-    obj instanceof Map ||
-    obj instanceof Set ||
-    isPlainObject(obj)
+export default function isTreelike(treelike) {
+  console.warn(
+    "Tree.isTreelike() is deprecated, use Tree.isMaplike() instead."
   );
+  return isMaplike(treelike);
 }