@weborigami/async-tree 0.5.4 → 0.5.5

package/src/operations/plain.js

@@ -0,0 +1,34 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import toPlainValue from "../utilities/toPlainValue.js";
+
+/**
+ * Converts an asynchronous tree into a synchronous plain JavaScript object.
+ *
+ * The result's keys will be the tree's keys cast to strings. Any trailing
+ * slashes in keys will be removed.
+ *
+ * Any tree value that is itself a tree will be recursively converted to a plain
+ * object.
+ *
+ * If the tree is array-like (its keys are integers and fill the range
+ * 0..length-1), then the result will be an array. The order of the keys will
+ * determine the order of the values in the array -- but the numeric value of
+ * the keys will be ignored.
+ *
+ * For example, a tree like `{ 1: "b", 0: "a", 2: "c" }` is array-like because
+ * its keys are all integers and fill the range 0..2. The result will be the
+ * array `["b", "a", "c" ]` because the tree has the keys in that order. The
+ * specific values of the keys (0, 1, and 2) are ignored.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").PlainObject} PlainObject
+ *
+ * @param {Treelike} treelike
+ */
+export default async function plain(treelike) {
+  if (treelike instanceof Function) {
+    throw new TypeError("plain: can't convert a function to a plain object");
+  }
+  const tree = await getTreeArgument(treelike, "plain");
+  return toPlainValue(tree);
+}

package/src/operations/regExpKeys.js

@@ -1,6 +1,6 @@
-import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import isAsyncTree from "./isAsyncTree.js";
 
 /**
  * A tree whose keys are strings interpreted as regular expressions.
@@ -13,8 +13,7 @@ import { assertIsTreelike } from "../utilities.js";
  * @type {import("../../index.ts").TreeTransform}
  */
 export default async function regExpKeys(treelike) {
-  assertIsTreelike(treelike, "regExpKeys");
-  const tree = Tree.from(treelike);
+  const tree = await getTreeArgument(treelike, "regExpKeys");
 
   const map = new Map();
 
@@ -57,7 +56,7 @@ export default async function regExpKeys(treelike) {
     let value = await tree.get(key);
 
     let regExp;
-    if (trailingSlash.has(key) || Tree.isAsyncTree(value)) {
+    if (trailingSlash.has(key) || isAsyncTree(value)) {
       const baseKey = trailingSlash.remove(key);
       regExp = new RegExp("^" + baseKey + "/?$");
       // Subtree

package/src/operations/remove.js

@@ -0,0 +1,14 @@
+import { default as del } from "./delete.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
+ */
+export default async function remove(tree, key) {
+  console.warn("`Tree.remove` is deprecated. Use `Tree.delete` instead.");
+  return del(tree, key);
+}

package/src/operations/reverse.js

@@ -1,5 +1,4 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
 
 /**
  * Reverse the order of the top-level keys in the tree.
@@ -8,11 +7,10 @@ import { assertIsTreelike } from "../utilities.js";
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
  * @param {Treelike} treelike
- * @returns {AsyncTree}
+ * @returns {Promise<AsyncTree>}
  */
-export default function reverse(treelike) {
-  assertIsTreelike(treelike, "reverse");
-  const tree = Tree.from(treelike);
+export default async function reverse(treelike) {
+  const tree = await getTreeArgument(treelike, "reverse");
 
   return {
     async get(key) {

package/src/operations/root.js

@@ -0,0 +1,17 @@
+import * as symbols from "../symbols.js";
+import from from "./from.js";
+
+/**
+ * Walk up the `parent` chain to find the root of the tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+export default function root(treelike) {
+  let current = from(treelike);
+  while (current.parent || current[symbols.parent]) {
+    current = current.parent || current[symbols.parent];
+  }
+  return current;
+}

package/src/operations/scope.js

@@ -1,5 +1,4 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
 
 /**
  * A tree's "scope" is the collection of everything in that tree and all of its
@@ -9,11 +8,10 @@ import { assertIsTreelike } from "../utilities.js";
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
  * @param {Treelike} treelike
- * @returns {AsyncTree & {trees: AsyncTree[]}}
+ * @returns {Promise<AsyncTree & {trees: AsyncTree[]}>}
  */
-export default function scope(treelike) {
-  assertIsTreelike(treelike, "scope");
-  const tree = Tree.from(treelike);
+export default async function scope(treelike) {
+  const tree = await getTreeArgument(treelike, "scope");
 
   return {
     // Starting with this tree, search up the parent hierarchy.

package/src/operations/setDeep.js

@@ -0,0 +1,50 @@
+import from from "./from.js";
+import isAsyncTree from "./isAsyncTree.js";
+
+/**
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @param {Treelike} target
+ * @param {Treelike} source
+ */
+export default async function setDeep(target, source) {
+  console.warn("Tree.setDeep is deprecated, use Tree.assign instead.");
+  const targetTree = from(target);
+  const sourceTree = from(source);
+  await applyUpdates(sourceTree, targetTree);
+}
+
+// Apply all updates from the source to the target.
+async function applyUpdates(source, target) {
+  // Fire off requests to update all keys, then wait for all of them to finish.
+  const promises = [];
+  for (const key of await source.keys()) {
+    const updateKeyPromise = applyUpdateForKey(source, target, key);
+    promises.push(updateKeyPromise);
+  }
+  await Promise.all(promises);
+
+  // HACK: Transforms like KeysTransform that maintain caches will need to
+  // recalculate things now that updates have been applied. This should be an
+  // automatic part of calling set() -- but triggering those changes inside
+  // set() produces cases where set() and get() calls can be interleaved. The
+  // atomicity of set() needs to be reconsidered. For now, we work around the
+  // problem by triggering `onChange` after the updates have been applied.
+  target.onChange?.();
+}
+
+// Copy the value for the given key from the source to the target.
+async function applyUpdateForKey(source, target, key) {
+  const sourceValue = await source.get(key);
+  if (isAsyncTree(sourceValue)) {
+    const targetValue = await target.get(key);
+    if (isAsyncTree(targetValue)) {
+      // Both source and target are async dictionaries; recurse.
+      await applyUpdates(sourceValue, targetValue);
+      return;
+    }
+  }
+
+  // Copy the value from the source to the target.
+  await target.set(key, sourceValue);
+}

package/src/operations/shuffle.js

@@ -0,0 +1,46 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+
+/**
+ * Return a new tree with the original's keys shuffled
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @param {boolean?} reshuffle
+ * @returns {Promise<AsyncTree>}
+ */
+export default async function shuffle(treelike, reshuffle = false) {
+  const tree = await getTreeArgument(treelike, "shuffle");
+
+  let keys;
+
+  return {
+    async get(key) {
+      return tree.get(key);
+    },
+
+    async keys() {
+      if (!keys || reshuffle) {
+        keys = Array.from(await tree.keys());
+        shuffleArray(keys);
+      }
+      return keys;
+    },
+  };
+}
+
+/*
+ * Shuffle an array.
+ *
+ * Performs a Fisher-Yates shuffle. From http://sedition.com/perl/javascript-fy.html
+ */
+export function shuffleArray(array) {
+  let i = array.length;
+  while (--i >= 0) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const temp = array[i];
+    array[i] = array[j];
+    array[j] = temp;
+  }
+}

package/src/operations/sort.js

@@ -1,5 +1,4 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
 
 /**
  * Return a new tree with the original's keys sorted. A comparison function can
@@ -8,18 +7,25 @@ import { assertIsTreelike } from "../utilities.js";
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {(key: any, tree: AsyncTree) => any} SortKeyFn
- * @typedef {{ compare?: (a: any, b: any) => number, sortKey?: SortKeyFn }}
- * SortOptions
+ * @typedef {{ compare?: (a: any, b: any) => number, sortKey?: SortKeyFn }} SortOptions
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
- * @param {import("../../index.ts").Treelike} treelike
- * @param {SortOptions} [options]
+ * @param {Treelike} treelike
+ * @param {SortOptions|ValueKeyFn} [options]
  */
-export default function sort(treelike, options) {
-  assertIsTreelike(treelike, "sort");
-  const tree = Tree.from(treelike);
+export default async function sort(treelike, options) {
+  const tree = await getTreeArgument(treelike, "sort");
 
-  const sortKey = options?.sortKey;
-  let compare = options?.compare;
+  let sortKey;
+  let compare;
+  if (options instanceof Function) {
+    // Take the function as the `sortKey` option
+    sortKey = options;
+  } else {
+    compare = options?.compare;
+    sortKey = options?.sortKey;
+  }
 
   const transformed = Object.create(tree);
   transformed.keys = async () => {
@@ -30,7 +36,8 @@ export default function sort(treelike, options) {
       // Create { key, sortKey } tuples.
       const tuples = await Promise.all(
         keys.map(async (key) => {
-          const sort = await sortKey(key, tree);
+          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}`

package/src/operations/take.js

@@ -1,5 +1,4 @@
-import { Tree } from "../internal.js";
-import { assertIsTreelike } from "../utilities.js";
+import getTreeArgument from "../utilities/getTreeArgument.js";
 
 /**
  * Returns a new tree with the number of keys limited to the indicated count.
@@ -7,9 +6,8 @@ import { assertIsTreelike } from "../utilities.js";
  * @param {import("../../index.ts").Treelike} treelike
  * @param {number} count
  */
-export default function take(treelike, count) {
-  assertIsTreelike(treelike, "take");
-  const tree = Tree.from(treelike);
+export default async function take(treelike, count) {
+  const tree = await getTreeArgument(treelike, "take");
 
   return {
     async keys() {

package/src/operations/text.js

@@ -1,6 +1,6 @@
-import { Tree } from "../internal.js";
-import { toString } from "../utilities.js";
+import toString from "../utilities/toString.js";
 import deepText from "./deepText.js";
+import isTreelike from "./isTreelike.js";
 
 /**
  * A tagged template literal function that concatenate the deep text values in a
@@ -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) =>
-      Tree.isTreelike(value) ? deepText(value) : toString(value)
+      isTreelike(value) ? deepText(value) : toString(value)
     )
   );
   // Splice all the strings together

package/src/operations/toFunction.js

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

package/src/operations/traverse.js

@@ -0,0 +1,25 @@
+import TraverseError from "../TraverseError.js";
+import traverseOrThrow from "./traverseOrThrow.js";
+
+/**
+ * Return the value at the corresponding path of keys.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @this {any}
+ * @param {Treelike} treelike
+ * @param {...any} keys
+ */
+export default async function traverse(treelike, ...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.call(this, treelike, ...keys);
+  } catch (/** @type {any} */ error) {
+    if (error instanceof TraverseError) {
+      return undefined;
+    } else {
+      throw error;
+    }
+  }
+}

package/src/operations/traverseOrThrow.js

@@ -0,0 +1,64 @@
+import TraverseError from "../TraverseError.js";
+import isUnpackable from "../utilities/isUnpackable.js";
+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
+ *
+ * @this {any}
+ * @param {Treelike} treelike
+ * @param  {...any} keys
+ */
+export default async function traverseOrThrow(treelike, ...keys) {
+  // Start our traversal at the root of the tree.
+  /** @type {any} */
+  let value = treelike;
+  let position = 0;
+
+  // If traversal operation was called with a `this` context, use that as the
+  // target for function calls.
+  const target = this;
+
+  // Process all the keys.
+  const remainingKeys = keys.slice();
+  let key;
+  while (remainingKeys.length > 0) {
+    if (value == null) {
+      throw new TraverseError("A null or undefined value can't be traversed", {
+        tree: treelike,
+        keys,
+        position,
+      });
+    }
+
+    // If the value is packed and can be unpacked, unpack it.
+    if (isUnpackable(value)) {
+      value = await value.unpack();
+    }
+
+    if (value instanceof Function) {
+      // Value is a function: call it with the remaining keys.
+      const fn = value;
+      // We'll take as many keys as the function's length, but at least one.
+      let fnKeyCount = Math.max(fn.length, 1);
+      const args = remainingKeys.splice(0, fnKeyCount);
+      key = null;
+      value = await fn.call(target, ...args);
+    } else {
+      // Cast value to a tree.
+      const tree = from(value);
+      // Get the next key.
+      key = remainingKeys.shift();
+      // Get the value for the key.
+      value = await tree.get(key);
+    }
+
+    position++;
+  }
+
+  return value;
+}

package/src/operations/traversePath.js

@@ -0,0 +1,16 @@
+import keysFromPath from "../utilities/keysFromPath.js";
+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
+ *
+ * @param {Treelike} tree
+ * @param {string} path
+ */
+export default async function traversePath(tree, path) {
+  const keys = keysFromPath(path);
+  return traverse(tree, ...keys);
+}

package/src/operations/values.js

@@ -0,0 +1,15 @@
+import from from "./from.js";
+
+/**
+ * Return the values in the specific node of the tree.
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ */
+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);
+}

package/src/operations/withKeys.js

@@ -0,0 +1,33 @@
+import getTreeArgument from "../utilities/getTreeArgument.js";
+import values from "./values.js";
+
+/**
+ * Return a tree whose keys are provided by the _values_ of a second tree (e.g.,
+ * an array of keys).
+ *
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {Treelike} treelike
+ * @param {Treelike} keysTreelike
+ * @returns {Promise<AsyncTree>}
+ */
+export default async function withKeys(treelike, keysTreelike) {
+  const tree = await getTreeArgument(treelike, "withKeys", { position: 0 });
+  const keysTree = await getTreeArgument(keysTreelike, "withKeys", {
+    position: 1,
+  });
+
+  let keys;
+
+  return {
+    async get(key) {
+      return tree.get(key);
+    },
+
+    async keys() {
+      keys ??= await values(keysTree);
+      return keys;
+    },
+  };
+}

package/src/utilities/TypedArray.js

@@ -0,0 +1,2 @@
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+export default TypedArray;

package/src/utilities/box.js

@@ -0,0 +1,20 @@
+/**
+ * Return the value as an object. If the value is already an object it will be
+ * returned as is. If the value is a primitive, it will be wrapped in an object:
+ * a string will be wrapped in a String object, a number will be wrapped in a
+ * Number object, and a boolean will be wrapped in a Boolean object.
+ *
+ * @param {any} value
+ */
+export default function box(value) {
+  switch (typeof value) {
+    case "string":
+      return new String(value);
+    case "number":
+      return new Number(value);
+    case "boolean":
+      return new Boolean(value);
+    default:
+      return value;
+  }
+}

package/src/utilities/castArraylike.js

@@ -0,0 +1,38 @@
+/**
+ * Create an array or plain object from the given keys and values.
+ *
+ * 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
+ */
+export default function castArraylike(keys, values) {
+  if (keys.length === 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) {
+      onlyNumericKeys = false;
+      break;
+    } else {
+      numberSeen[n] = true;
+    }
+  }
+
+  // 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;
+  } else {
+    // Return a plain object with the (key, value) pairs
+    return Object.fromEntries(keys.map((key, i) => [key, values[i]]));
+  }
+}

package/src/utilities/getParent.js

@@ -0,0 +1,33 @@
+import * as symbols from "../symbols.js";
+
+/**
+ * Return a suitable parent for the packed file.
+ *
+ * This is intended to be called by unpack functions.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @param {any} packed
+ * @param {any} [options]
+ * @returns {AsyncTree|null}
+ */
+export default function getParent(packed, options = {}) {
+  // Prefer parent set on options
+  if (options?.parent) {
+    return options.parent;
+  }
+
+  // If the packed object has a `parent` property, use that. Exception: Node
+  // Buffer objects have a `parent` property that we ignore.
+  if (packed.parent && !(packed instanceof Buffer)) {
+    return packed.parent;
+  }
+
+  // If the packed object has a parent symbol, use that.
+  if (packed[symbols.parent]) {
+    return packed[symbols.parent];
+  }
+
+  // Otherwise, return null.
+  return null;
+}

package/src/utilities/getRealmObjectPrototype.js

@@ -0,0 +1,19 @@
+/**
+ * Return the Object prototype at the root of the object's prototype chain.
+ *
+ * This is used by functions like isPlainObject() to handle cases where the
+ * `Object` at the root prototype chain is in a different realm.
+ *
+ * @param {any} object
+ */
+export default function getRealmObjectPrototype(object) {
+  if (Object.getPrototypeOf(object) === null) {
+    // The object has no prototype.
+    return null;
+  }
+  let proto = object;
+  while (Object.getPrototypeOf(proto) !== null) {
+    proto = Object.getPrototypeOf(proto);
+  }
+  return proto;
+}

package/src/utilities/getTreeArgument.js

@@ -0,0 +1,43 @@
+import from from "../operations/from.js";
+import isUnpackable from "./isUnpackable.js";
+
+/**
+ * Convert the indicated argument to a tree, or throw an exception.
+ *
+ * Tree operations can use this to validate the tree argument and provide more
+ * helpful error messages. This also unpacks a unpackable tree argument so that
+ * the caller can work with a simpler tree instead of a DeferredTree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Unpackable} Unpackable
+ *
+ * @param {Treelike|Unpackable} treelike
+ * @param {string} operation
+ * @param {{ deep?: boolean, position?: number }} [options]
+ * @returns {Promise<AsyncTree>}
+ */
+export default async function getTreeArgument(
+  treelike,
+  operation,
+  options = {}
+) {
+  const deep = options.deep;
+  const position = options.position ?? 0;
+
+  if (isUnpackable(treelike)) {
+    treelike = await treelike.unpack();
+  }
+
+  let tree;
+  try {
+    tree = from(treelike, { 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 tree;
+}