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

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.3.3-jse.3",
+  "version": "0.3.4-jse.4",
   "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.4-jse.4"
   },
   "devDependencies": {
     "@types/node": "22.13.13",

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,7 +88,7 @@ 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);
     }
 

package/src/drivers/limitConcurrency.js

@@ -0,0 +1,63 @@
+/**
+ * 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,
+      unblock: 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, start
+  // the next call in the queue.
+  function next() {
+    if (queue.length > 0 && activeCallPool.size < maxConcurrency) {
+      const { promise, unblock } = queue.shift();
+      activeCallPool.add(promise);
+      // Resolve the turn promise to allow the call to proceed
+      unblock();
+    }
+  }
+}
+
+// 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/utilities.js

@@ -279,17 +279,22 @@ export function setParent(child, parent) {
       child.parent = parent;
     }
   } else if (Object.isExtensible(child) && !child[symbols.parent]) {
-    // Add parent reference as a symbol to avoid polluting the object. This
-    // reference will be used if the object is later used as a tree. We set
-    // `enumerable` to false even thought this makes no practical difference
-    // (symbols are never enumerated) because it can provide a hint in the
-    // debugger that the property is for internal use.
-    Object.defineProperty(child, symbols.parent, {
-      configurable: true,
-      enumerable: false,
-      value: parent,
-      writable: true,
-    });
+    try {
+      // Add parent reference as a symbol to avoid polluting the object. This
+      // reference will be used if the object is later used as a tree. We set
+      // `enumerable` to false even thought this makes no practical difference
+      // (symbols are never enumerated) because it can provide a hint in the
+      // debugger that the property is for internal use.
+      Object.defineProperty(child, symbols.parent, {
+        configurable: true,
+        enumerable: false,
+        value: parent,
+        writable: true,
+      });
+    } catch (error) {
+      // Ignore exceptions. Some esoteric objects don't allow adding properties.
+      // We can still treat them as trees, but they won't have a parent.
+    }
   }
 }
 

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;
+  };
+}