@weborigami/async-tree 0.3.3-jse.3 → 0.3.3

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.3.3-jse.3",
+  "version": "0.3.3",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "dependencies": {
-    "@weborigami/types": "0.3.3-jse.3"
+    "@weborigami/types": "0.3.3"
   },
   "devDependencies": {
     "@types/node": "22.13.13",

package/shared.js

@@ -14,6 +14,7 @@ export * as jsonKeys from "./src/jsonKeys.js";
 export { default as addNextPrevious } from "./src/operations/addNextPrevious.js";
 export { default as cache } from "./src/operations/cache.js";
 export { default as cachedKeyFunctions } from "./src/operations/cachedKeyFunctions.js";
+export { default as concat } from "./src/operations/concat.js";
 export { default as deepMerge } from "./src/operations/deepMerge.js";
 export { default as deepReverse } from "./src/operations/deepReverse.js";
 export { default as deepTake } from "./src/operations/deepTake.js";
@@ -33,7 +34,6 @@ export { default as reverse } from "./src/operations/reverse.js";
 export { default as scope } from "./src/operations/scope.js";
 export { default as sort } from "./src/operations/sort.js";
 export { default as take } from "./src/operations/take.js";
-export { default as text } from "./src/operations/text.js";
 export * as symbols from "./src/symbols.js";
 export * as trailingSlash from "./src/trailingSlash.js";
 export { default as TraverseError } from "./src/TraverseError.js";

package/src/Tree.d.ts

@@ -21,4 +21,4 @@ export function toFunction(tree: Treelike): Function;
 export function traverse(tree: Treelike, ...keys: any[]): Promise<any>;
 export function traverseOrThrow(tree: Treelike, ...keys: any[]): Promise<any>;
 export function traversePath(tree: Treelike, path: string): Promise<any>;
-export function values(tree: Treelike): Promise<IterableIterator<any>>;
+export function values(AsyncTree: AsyncTree): Promise<IterableIterator<any>>;

package/src/Tree.js

@@ -26,6 +26,8 @@ import {
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  */
 
+const treeModule = this;
+
 /**
  * Apply the key/values pairs from the source tree to the target tree.
  *
@@ -360,8 +362,8 @@ export async function remove(tree, key) {
  */
 export function root(tree) {
   let current = from(tree);
-  while (current.parent || current[symbols.parent]) {
-    current = current.parent || current[symbols.parent];
+  while (current.parent) {
+    current = current.parent;
   }
   return current;
 }
@@ -414,7 +416,7 @@ export async function traverseOrThrow(treelike, ...keys) {
 
   // If traversal operation was called with a `this` context, use that as the
   // target for function calls.
-  const target = this;
+  const target = this === treeModule ? undefined : this;
 
   // Process all the keys.
   const remainingKeys = keys.slice();
@@ -471,10 +473,9 @@ export async function traversePath(tree, path) {
 /**
  * Return the values in the specific node of the tree.
  *
- * @param {Treelike} treelike
+ * @param {AsyncTree} tree
  */
-export async function values(treelike) {
-  const tree = from(treelike);
+export async function values(tree) {
   const keys = Array.from(await tree.keys());
   const promises = keys.map(async (key) => tree.get(key));
   return Promise.all(promises);

package/src/drivers/FileTree.js

@@ -11,6 +11,13 @@ import {
   naturalOrder,
   setParent,
 } from "../utilities.js";
+import limitConcurrency from "./limitConcurrency.js";
+
+// As of July 2025, Node doesn't provide any way to limit the number of
+// concurrent calls to readFile, so we wrap readFile in a function that
+// arbitrarily limits the number of concurrent calls to it.
+const MAX_CONCURRENT_READS = 256;
+const limitReadFile = limitConcurrency(fs.readFile, MAX_CONCURRENT_READS);
 
 /**
  * A file system tree via the Node file system API.
@@ -81,16 +88,11 @@ export default class FileTree {
       value = Reflect.construct(this.constructor, [filePath]);
     } else {
       // Return file contents as a standard Uint8Array
-      const buffer = await fs.readFile(filePath);
+      const buffer = await limitReadFile(filePath);
       value = Uint8Array.from(buffer);
     }
 
-    const parent =
-      key === ".."
-        ? // Special case: ".." parent is the grandparent (if it exists)
-          this.parent?.parent
-        : this;
-    setParent(value, parent);
+    setParent(value, this);
     return value;
   }
 

package/src/drivers/limitConcurrency.js

@@ -0,0 +1,62 @@
+/**
+ * Wrap an async function with a function that limits the number of concurrent
+ * calls to that function.
+ */
+export default function limitConcurrency(fn, maxConcurrency) {
+  const queue = [];
+  const activeCallPool = new Set();
+
+  return async function limitedFunction(...args) {
+    // Our turn is represented by a promise that can be externally resolved
+    const turnWithResolvers = withResolvers();
+
+    // Construct a promise for the result of the function call
+    const resultPromise =
+      // Block until its our turn
+      turnWithResolvers.promise
+        .then(() => fn(...args)) // Call the function and return its result
+        .finally(() => {
+          // Remove the promise from the active pool
+          activeCallPool.delete(resultPromise);
+          // Tell the next call in the queue it can proceed
+          next();
+        });
+
+    // Join the queue
+    queue.push({
+      promise: resultPromise,
+      resolve: turnWithResolvers.resolve,
+    });
+
+    if (activeCallPool.size >= maxConcurrency) {
+      // The pool is full; wait for the next active call to complete. The call
+      // will remove its own completed promise from the active pool.
+      await Promise.any(activeCallPool);
+    } else {
+      next();
+    }
+
+    return resultPromise;
+  };
+
+  // If there are calls in the queue and the active pool is not full, resolve
+  // the next call in the queue and add it to the active pool.
+  function next() {
+    if (queue.length > 0 && activeCallPool.size < maxConcurrency) {
+      const { promise, resolve } = queue.shift();
+      activeCallPool.add(promise);
+      resolve();
+    }
+  }
+}
+
+// Polyfill Promise.withResolvers until Node LTS supports it
+function withResolvers() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}

package/src/operations/concat.js

@@ -0,0 +1,29 @@
+import { assertIsTreelike, toString } from "../utilities.js";
+import deepValuesIterator from "./deepValuesIterator.js";
+
+/**
+ * Concatenate the deep text values in a tree.
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ */
+export default async function concat(treelike) {
+  assertIsTreelike(treelike, "concat");
+
+  const strings = [];
+  for await (const value of deepValuesIterator(treelike, { expand: true })) {
+    let string;
+    if (value === null) {
+      string = "null";
+    } else if (value === undefined) {
+      string = "undefined";
+    } else {
+      string = toString(value);
+    }
+    if (value === null || value === undefined) {
+      const message = `Warning: Origami template encountered a ${string} value. To locate where this happened, build your project and search your build output for the text "${string}".`;
+      console.warn(message);
+    }
+    strings.push(string);
+  }
+  return strings.join("");
+}

package/src/operations/deepText.js

@@ -1,29 +1,25 @@
-import { assertIsTreelike, toString } from "../utilities.js";
-import deepValuesIterator from "./deepValuesIterator.js";
+import { Tree } from "../internal.js";
+import { toString } from "../utilities.js";
+import concat from "./concat.js";
 
 /**
- * Concatenate the deep text values in a tree.
+ * A tagged template literal function that concatenate the deep text values in a
+ * tree. Any treelike values will be concatenated using `concat`.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {TemplateStringsArray} strings
+ * @param  {...any} values
  */
-export default async function deepText(treelike) {
-  assertIsTreelike(treelike, "text");
-
-  const strings = [];
-  for await (const value of deepValuesIterator(treelike, { expand: true })) {
-    let string;
-    if (value === null) {
-      string = "null";
-    } else if (value === undefined) {
-      string = "undefined";
-    } else {
-      string = toString(value);
-    }
-    if (value === null || value === undefined) {
-      const message = `Warning: a template encountered a ${string} value. To locate where this happened, build your project and search your build output for the text "${string}".`;
-      console.warn(message);
-    }
-    strings.push(string);
+export default async function deepText(strings, ...values) {
+  // Convert all the values to strings
+  const valueTexts = await Promise.all(
+    values.map((value) =>
+      Tree.isTreelike(value) ? concat(value) : toString(value)
+    )
+  );
+  // Splice all the strings together
+  let result = strings[0];
+  for (let i = 0; i < valueTexts.length; i++) {
+    result += valueTexts[i] + strings[i + 1];
   }
-  return strings.join("");
+  return result;
 }

package/src/operations/merge.js

@@ -16,17 +16,7 @@ import * as trailingSlash from "../trailingSlash.js";
  * @returns {AsyncTree & { description: string, trees: AsyncTree[]}}
  */
 export default function merge(...sources) {
-  const trees = sources
-    .filter((source) => source)
-    .map((treelike) => Tree.from(treelike));
-
-  if (trees.length === 0) {
-    throw new TypeError("merge: all trees are null or undefined");
-  } else if (trees.length === 1) {
-    // Only one tree, no need to merge
-    return trees[0];
-  }
-
+  const trees = sources.map((treelike) => Tree.from(treelike));
   return {
     description: "merge",
 

package/test/drivers/limitConcurrency.test.js

@@ -0,0 +1,41 @@
+import assert from "node:assert";
+import { before, describe, test } from "node:test";
+import limitConcurrency from "../../src/drivers/limitConcurrency.js";
+
+describe("limitConcurrency", async () => {
+  before(async () => {
+    // Confirm our limited functions throws on too many calls
+    const fn = createFixture();
+    try {
+      const array = Array.from({ length: 10 }, (_, index) => index);
+      await Promise.all(array.map((index) => fn(index)));
+    } catch (/** @type {any} */ error) {
+      assert.equal(error.message, "Too many calls");
+    }
+  });
+
+  test("limits the number of concurrent calls", async () => {
+    const fn = createFixture();
+    const limitedFn = limitConcurrency(fn, 3);
+    const array = Array.from({ length: 10 }, (_, index) => index);
+    const result = await Promise.all(array.map((index) => limitedFn(index)));
+    assert.deepEqual(result, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+  });
+});
+
+// Return a function that only permits a limited number of concurrent calls and
+// simulates a delay for each request.
+function createFixture() {
+  let activeCalls = 0;
+  const maxActiveCalls = 3;
+
+  return async function (n) {
+    if (activeCalls >= maxActiveCalls) {
+      throw new Error("Too many calls");
+    }
+    activeCalls++;
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    activeCalls--;
+    return n;
+  };
+}

package/test/operations/concat.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import FunctionTree from "../../src/drivers/FunctionTree.js";
+import { Tree } from "../../src/internal.js";
+import concat from "../../src/operations/concat.js";
+
+describe("concat", () => {
+  test("concatenates deep tree values", async () => {
+    const tree = Tree.from({
+      a: "A",
+      b: "B",
+      c: "C",
+      more: {
+        d: "D",
+        e: "E",
+      },
+    });
+    const result = await concat.call(null, tree);
+    assert.equal(result, "ABCDE");
+  });
+
+  test("concatenates deep tree-like values", async () => {
+    const letters = ["a", "b", "c"];
+    const specimens = new FunctionTree(
+      (letter) => ({
+        lowercase: letter,
+        uppercase: letter.toUpperCase(),
+      }),
+      letters
+    );
+    const result = await concat.call(null, specimens);
+    assert.equal(result, "aAbBcC");
+  });
+});

package/test/operations/deepText.test.js

@@ -1,34 +1,12 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import FunctionTree from "../../src/drivers/FunctionTree.js";
-import { Tree } from "../../src/internal.js";
 import deepText from "../../src/operations/deepText.js";
 
 describe("deepText", () => {
-  test("concatenates deep tree values", async () => {
-    const tree = Tree.from({
-      a: "A",
-      b: "B",
-      c: "C",
-      more: {
-        d: "D",
-        e: "E",
-      },
-    });
-    const result = await deepText(tree);
-    assert.equal(result, "ABCDE");
-  });
-
-  test("concatenates deep tree-like values", async () => {
-    const letters = ["a", "b", "c"];
-    const specimens = new FunctionTree(
-      (letter) => ({
-        lowercase: letter,
-        uppercase: letter.toUpperCase(),
-      }),
-      letters
-    );
-    const result = await deepText(specimens);
-    assert.equal(result, "aAbBcC");
+  test("joins strings and values together", async () => {
+    const array = [1, 2, 3];
+    const object = { person1: "Alice", person2: "Bob" };
+    const result = await deepText`a ${array} b ${object} c`;
+    assert.equal(result, "a 123 b AliceBob c");
   });
 });

package/src/operations/text.js

@@ -1,25 +0,0 @@
-import { Tree } from "../internal.js";
-import { toString } from "../utilities.js";
-import deepText from "./deepText.js";
-
-/**
- * A tagged template literal function that concatenate the deep text values in a
- * tree. Any treelike values will be concatenated using `deepText`.
- *
- * @param {TemplateStringsArray} strings
- * @param  {...any} values
- */
-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)
-    )
-  );
-  // Splice all the strings together
-  let result = strings[0];
-  for (let i = 0; i < valueTexts.length; i++) {
-    result += valueTexts[i] + strings[i + 1];
-  }
-  return result;
-}

package/test/operations/text.test.js

@@ -1,12 +0,0 @@
-import assert from "node:assert";
-import { describe, test } from "node:test";
-import text from "../../src/operations/text.js";
-
-describe("text template literal function", () => {
-  test("joins strings and values together", async () => {
-    const array = [1, 2, 3];
-    const object = { person1: "Alice", person2: "Bob" };
-    const result = await text`a ${array} b ${object} c`;
-    assert.equal(result, "a 123 b AliceBob c");
-  });
-});