@weborigami/async-tree 0.5.4 → 0.5.6

package/src/operations/deepValuesIterator.js

@@ -1,5 +1,6 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isAsyncTree from "./isAsyncTree.js";
+import isTreelike from "./isTreelike.js";
 
 /**
  * Return an iterator that yields all values in a tree, including nested trees.
@@ -15,16 +16,17 @@ export default async function* deepValuesIterator(
   treelike,
   options = { expand: false }
 ) {
-  assertIsTreelike(treelike, "deepValuesIterator");
-  const tree = Tree.from(treelike, { deep: true });
+  const tree = await getTreeArgument(treelike, "deepValuesIterator", {
+    deep: true,
+  });
 
   for (const key of await tree.keys()) {
     let value = await tree.get(key);
 
     // Recurse into child trees, but don't expand functions.
     const recurse =
-      Tree.isAsyncTree(value) ||
-      (options.expand && typeof value !== "function" && Tree.isTreelike(value));
+      isAsyncTree(value) ||
+      (options.expand && typeof value !== "function" && isTreelike(value));
     if (recurse) {
       yield* deepValuesIterator(value, options);
     } else {

package/src/operations/delete.js

@@ -0,0 +1,20 @@
+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
+ *
+ * @param {AsyncMutableTree} tree
+ * @param {any} key
+ */
+// `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;
+  }
+}

package/src/operations/entries.js

@@ -0,0 +1,16 @@
+import getTreeArgument from "../utilities/getTreeArgument.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.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+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);
+}

package/src/operations/extensionKeyFunctions.js

@@ -30,7 +30,7 @@ export default function extensionKeyFunctions(
       return basename ? `${basename}${sourceExtension}` : undefined;
     },
 
-    async key(sourceKey, tree) {
+    async key(value, sourceKey, tree) {
       return extension.match(sourceKey, sourceExtension)
         ? extension.replace(sourceKey, sourceExtension, resultExtension)
         : undefined;

package/src/operations/filter.js

@@ -1,4 +1,4 @@
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
 import map from "./map.js";
 
 /**
@@ -10,10 +10,9 @@ import map from "./map.js";
  *
  * @param {Treelike} treelike
  * @param {function|any} options
- * @returns {AsyncTree}
+ * @returns {Promise<AsyncTree>}
  */
-export default function filter(treelike, options) {
-  assertIsTreelike(treelike, "map");
+export default async function filter(treelike, options) {
   let testFn;
   let deep;
   if (typeof options === "function") {
@@ -24,15 +23,15 @@ export default function filter(treelike, options) {
     deep = options.deep ?? false;
   }
 
-  return map(treelike, {
+  const tree = await getTreeArgument(treelike, "filter", { deep });
+  return map(tree, {
     deep,
 
     // Assume source key is the same as result key
     inverseKey: async (resultKey) => resultKey,
 
-    key: async (sourceKey, tree) => {
-      const value = await tree.get(sourceKey);
-      const passes = await testFn(value, sourceKey, tree);
+    key: async (sourceValue, sourceKey, tree) => {
+      const passes = await testFn(sourceValue, sourceKey, tree);
       return passes ? sourceKey : undefined;
     },
   });

package/src/operations/first.js

@@ -0,0 +1,18 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Return the first value in the tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+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;
+  }
+  return undefined;
+}

package/src/operations/forEach.js

@@ -0,0 +1,20 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Calls callbackFn once for each key-value pair present in the specific node of
+ * the tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @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);
+}

package/src/operations/from.js

@@ -0,0 +1,77 @@
+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 * 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";
+
+/**
+ * Attempts to cast the indicated object to an async tree.
+ *
+ * If the object is a plain object, it will be converted to an ObjectTree. 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
+ * parent of the new tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {Treelike | Object} object
+ * @param {{ deep?: boolean, parent?: AsyncTree|null }} [options]
+ * @returns {AsyncTree}
+ */
+export default function from(object, options = {}) {
+  const deep = options.deep ?? object[symbols.deep];
+  let tree;
+  if (object == null) {
+    throw new TypeError("The tree argument wasn't defined.");
+  } else if (object instanceof Promise) {
+    // A common mistake
+    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
+    return object;
+  } else if (typeof object === "function") {
+    tree = new FunctionTree(object);
+  } else if (object instanceof Map) {
+    tree = new MapTree(object);
+  } else if (object instanceof Set) {
+    tree = new SetTree(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());
+  } else if (object && typeof object === "object") {
+    // An instance of some class.
+    tree = new ObjectTree(object);
+  } else if (
+    typeof object === "string" ||
+    typeof object === "number" ||
+    typeof object === "boolean"
+  ) {
+    // A primitive value; box it into an object and construct a tree.
+    const boxed = box(object);
+    tree = new ObjectTree(boxed);
+  } else {
+    throw new TypeError("Couldn't convert argument to an async tree");
+  }
+
+  if (!tree.parent && options.parent) {
+    tree.parent = options.parent;
+  }
+  return tree;
+}

package/src/operations/globKeys.js

@@ -1,14 +1,14 @@
-import { ObjectTree, Tree } from "../internal.js";
+import ObjectTree from "../drivers/ObjectTree.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isAsyncTree from "./isAsyncTree.js";
 import merge from "./merge.js";
 
 const globstar = "**";
 const globstarSlash = `${globstar}/`;
 
-export default function globKeys(treelike) {
-  assertIsTreelike(treelike, "globKeys");
-  const globs = Tree.from(treelike, { deep: true });
+export default async function globKeys(treelike) {
+  const globs = await getTreeArgument(treelike, "globKeys", { deep: true });
   return {
     async get(key) {
       if (typeof key !== "string") {
@@ -16,7 +16,7 @@ export default function globKeys(treelike) {
       }
 
       let value = await matchGlobs(globs, key);
-      if (Tree.isAsyncTree(value)) {
+      if (isAsyncTree(value)) {
         value = globKeys(value);
       }
       return value;
@@ -57,7 +57,7 @@ async function matchGlobs(globs, key) {
       // Text matches glob, get value
       const globValue = await globs.get(glob);
       if (globValue !== undefined) {
-        if (!Tree.isAsyncTree(globValue)) {
+        if (!isAsyncTree(globValue)) {
           // Found a non-tree match, return immediately
           return globValue;
         }
@@ -75,7 +75,7 @@ async function matchGlobs(globs, key) {
     } else {
       // Try globstar
       const globstarValue = await matchGlobs(globstarGlobs, key);
-      if (!Tree.isAsyncTree(globstarValue)) {
+      if (!isAsyncTree(globstarValue)) {
         // Found a non-tree match, return immediately
         return globstarValue;
       } else if (trailingSlash.has(key)) {

package/src/operations/group.js

@@ -1,49 +1,6 @@
-import { ObjectTree, Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import groupBy from "./groupBy.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").ValueKeyFn} groupKeyFn
- */
 export default async function group(treelike, groupKeyFn) {
-  assertIsTreelike(treelike, "group");
-  const tree = Tree.from(treelike);
-
-  const keys = Array.from(await tree.keys());
-
-  // 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);
-
-    // Get the groups for this value.
-    let groups = await groupKeyFn(value, key, tree);
-    if (!groups) {
-      continue;
-    }
-
-    if (!Tree.isTreelike(groups)) {
-      // A single value was returned
-      groups = [groups];
-    }
-    groups = Tree.from(groups);
-
-    // Add the value to each group.
-    for (const group of await Tree.values(groups)) {
-      if (isArray) {
-        result[group] ??= [];
-        result[group].push(value);
-      } else {
-        result[group] ??= {};
-        result[group][key] = value;
-      }
-    }
-  }
-
-  return new ObjectTree(result);
+  console.warn("Tree.group() is deprecated. Use Tree.groupBy() instead.");
+  return groupBy(treelike, groupKeyFn);
 }

package/src/operations/groupBy.js

@@ -0,0 +1,51 @@
+import ObjectTree from "../drivers/ObjectTree.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import from from "./from.js";
+import isTreelike from "./isTreelike.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").ValueKeyFn} groupKeyFn
+ */
+export default async function groupBy(treelike, groupKeyFn) {
+  const tree = await getTreeArgument(treelike, "groupBy");
+
+  const keys = Array.from(await tree.keys());
+
+  // 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);
+
+    // Get the groups for this value.
+    let groups = await groupKeyFn(value, key, tree);
+    if (!groups) {
+      continue;
+    }
+
+    if (!isTreelike(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);
+      } else {
+        result[group] ??= {};
+        result[group][key] = value;
+      }
+    }
+  }
+
+  return new ObjectTree(result);
+}

package/src/operations/has.js

@@ -0,0 +1,16 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Returns a boolean indicating whether the specific node of the tree has a
+ * value for the given `key`.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @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;
+}

package/src/operations/indent.js

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

package/src/operations/inners.js

@@ -0,0 +1,29 @@
+import * as trailingSlash from "../trailingSlash.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isAsyncTree from "./isAsyncTree.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
+ *
+ * @param {Treelike} treelike
+ */
+export default async function inners(treelike) {
+  const tree = await getTreeArgument(treelike, "inners");
+
+  return {
+    async get(key) {
+      const value = await tree.get(key);
+      return isAsyncTree(value) ? inners(value) : undefined;
+    },
+
+    async keys() {
+      const keys = [...(await tree.keys())];
+      const subtreeKeys = keys.filter(trailingSlash.has);
+      return subtreeKeys;
+    },
+  };
+}

package/src/operations/invokeFunctions.js

@@ -1,13 +1,14 @@
-import { Tree } from "../internal.js";
+import from from "./from.js";
+import isAsyncTree from "./isAsyncTree.js";
 
-export default function invokeFunctions(treelike) {
-  const tree = Tree.from(treelike);
+export default async function invokeFunctions(treelike) {
+  const tree = from(treelike);
   return {
     async get(key) {
       let value = await tree.get(key);
       if (typeof value === "function") {
         value = value();
-      } else if (Tree.isAsyncTree(value)) {
+      } else if (isAsyncTree(value)) {
         value = invokeFunctions(value);
       }
       return value;

package/src/operations/isAsyncMutableTree.js

@@ -0,0 +1,15 @@
+import isAsyncTree from "./isAsyncTree.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"
+  );
+}

package/src/operations/isAsyncTree.js

@@ -0,0 +1,21 @@
+/**
+ * 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)
+  );
+}

package/src/operations/isTraversable.js

@@ -0,0 +1,15 @@
+import isPacked from "../utilities/isPacked.js";
+import isTreelike from "./isTreelike.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.
+ *
+ * @param {any} object
+ */
+export default function isTraversable(object) {
+  return (
+    isTreelike(object) ||
+    (isPacked(object) && /** @type {any} */ (object).unpack instanceof Function)
+  );
+}

package/src/operations/isTreelike.js

@@ -0,0 +1,33 @@
+import isPlainObject from "../utilities/isPlainObject.js";
+import isAsyncTree from "./isAsyncTree.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)
+  );
+}

package/src/operations/json.js

@@ -1,6 +1,7 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
-import { Tree } from "../internal.js";
-import { isUnpackable, toPlainValue } from "../utilities.js";
+import isUnpackable from "../utilities/isUnpackable.js";
+import toPlainValue from "../utilities/toPlainValue.js";
+import from from "./from.js";
 
 /**
  * Render the given tree in JSON format.
@@ -8,7 +9,7 @@ import { isUnpackable, toPlainValue } from "../utilities.js";
  * @param {import("../../index.ts").Treelike} [treelike]
  */
 export default async function json(treelike) {
-  let tree = Tree.from(treelike);
+  let tree = from(treelike);
   if (tree === undefined) {
     return undefined;
   }

package/src/operations/keys.js

@@ -0,0 +1,14 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Return the top-level keys in the tree as an array.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+export default async function keys(treelike) {
+  const tree = await getTreeArgument(treelike, "keys");
+  const keys = await tree.keys();
+  return Array.from(keys);
+}

package/src/operations/length.js

@@ -0,0 +1,15 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Return the number of keys in the tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+export default async function length(treelike) {
+  const tree = await getTreeArgument(treelike, "length");
+  const keys = Array.from(await tree.keys());
+  return keys.length;
+}