@weborigami/async-tree 0.5.8 → 0.6.0

package/src/drivers/FileTree.js

@@ -1,276 +0,0 @@
-import * as fs from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { hiddenFileNames } from "../constants.js";
-import assign from "../operations/assign.js";
-import isTreelike from "../operations/isTreelike.js";
-import * as trailingSlash from "../trailingSlash.js";
-import isPacked from "../utilities/isPacked.js";
-import isPlainObject from "../utilities/isPlainObject.js";
-import isStringlike from "../utilities/isStringlike.js";
-import naturalOrder from "../utilities/naturalOrder.js";
-import setParent from "../utilities/setParent.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 = 4096;
-const limitReadFile = limitConcurrency(fs.readFile, MAX_CONCURRENT_READS);
-
-/**
- * A file system tree via the Node file system API.
- *
- * File values are returned as Uint8Array instances. The underlying Node fs API
- * returns file contents as instances of the node-specific Buffer class, but
- * that class has some incompatible method implementations; see
- * https://nodejs.org/api/buffer.html#buffers-and-typedarrays. For greater
- * compatibility, files are returned as standard Uint8Array instances instead.
- *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
- * @implements {AsyncMutableTree}
- */
-export default class FileTree {
-  /**
-   * @param {string|URL} location
-   */
-  constructor(location) {
-    if (location instanceof URL) {
-      location = location.href;
-    } else if (
-      !(
-        typeof location === "string" ||
-        /** @type {any} */ (location) instanceof String
-      )
-    ) {
-      throw new TypeError(
-        `FileTree constructor needs a string or URL, received an instance of ${
-          /** @type {any} */ (location)?.constructor?.name
-        }`
-      );
-    }
-    this.dirname = location.startsWith("file://")
-      ? fileURLToPath(location)
-      : path.resolve(process.cwd(), location);
-    this.parent = null;
-  }
-
-  async get(key) {
-    if (key == null) {
-      // Reject nullish key
-      throw new ReferenceError(
-        `${this.constructor.name}: Cannot get a null or undefined key.`
-      );
-    }
-    if (key === "") {
-      // Can't have a file with no name
-      return undefined;
-    }
-
-    // Remove trailing slash if present
-    key = trailingSlash.remove(key);
-    const filePath = path.resolve(this.dirname, key);
-
-    let stats;
-    try {
-      stats = await fs.stat(filePath);
-    } catch (/** @type {any} */ error) {
-      if (error.code === "ENOENT" /* File not found */) {
-        return undefined;
-      }
-      throw error;
-    }
-
-    let value;
-    if (stats.isDirectory()) {
-      // Return subdirectory as a tree
-      value = Reflect.construct(this.constructor, [filePath]);
-    } else {
-      // Return file contents as a standard Uint8Array
-      const buffer = await limitReadFile(filePath);
-      // const buffer = await fs.readFile(filePath);
-      value = Uint8Array.from(buffer);
-    }
-
-    const parent =
-      key === ".."
-        ? // Special case: ".." parent is the grandparent (if it exists)
-          this.parent?.parent
-        : this;
-    setParent(value, parent);
-    return value;
-  }
-
-  /**
-   * Enumerate the names of the files/subdirectories in this directory.
-   *
-   * @returns {Promise<string[]>}
-   */
-  async keys() {
-    let entries;
-    try {
-      entries = await fs.readdir(this.dirname, { withFileTypes: true });
-    } catch (/** @type {any} */ error) {
-      if (error.code !== "ENOENT") {
-        throw error;
-      }
-      entries = [];
-    }
-
-    // Add slashes to directory names.
-    let names = await Promise.all(
-      entries.map(async (entry) =>
-        trailingSlash.toggle(entry.name, await isDirectory(entry, this.dirname))
-      )
-    );
-
-    // Filter out unhelpful file names.
-    names = names.filter((name) => !hiddenFileNames.includes(name));
-
-    // Node fs.readdir sort order appears to be unreliable; see, e.g.,
-    // https://github.com/nodejs/node/issues/3232.
-    names.sort(naturalOrder);
-
-    return names;
-  }
-
-  get path() {
-    return this.dirname;
-  }
-
-  async set(key, value) {
-    // Where are we going to write this value?
-    const stringKey = key != null ? String(key) : "";
-    const baseKey = trailingSlash.remove(stringKey);
-    const destPath = path.resolve(this.dirname, baseKey);
-
-    if (value === undefined) {
-      // Delete the file or directory.
-      let stats;
-      try {
-        stats = await stat(destPath);
-      } catch (/** @type {any} */ error) {
-        if (error.code === "ENOENT" /* File not found */) {
-          return this;
-        }
-        throw error;
-      }
-
-      if (stats?.isDirectory()) {
-        // Delete directory.
-        await fs.rm(destPath, { recursive: true });
-      } else if (stats) {
-        // Delete file.
-        await fs.unlink(destPath);
-      }
-
-      return this;
-    }
-
-    if (typeof value === "function") {
-      // Invoke function; write out the result.
-      value = await value();
-    }
-
-    let packed = false;
-    if (value === null) {
-      // Treat null value as empty string; will create an empty file.
-      value = "";
-      packed = true;
-    } else if (!(value instanceof String) && isPacked(value)) {
-      // As of Node 22, fs.writeFile is incredibly slow for large String
-      // instances. Instead of treating a String instance as a Packed value, we
-      // want to consider it as a stringlike below. That will convert it to a
-      // primitive string before writing — which is orders of magnitude faster.
-      packed = true;
-    } else if (typeof value.pack === "function") {
-      // Pack the value for writing.
-      value = await value.pack();
-      packed = true;
-    } else if (isStringlike(value)) {
-      // Value has a meaningful `toString` method, use that.
-      value = String(value);
-      packed = true;
-    }
-
-    if (packed) {
-      await writeFile(value, destPath);
-    } else if (isPlainObject(value) && Object.keys(value).length === 0) {
-      // Special case: empty object means create an empty directory.
-      await fs.mkdir(destPath, { recursive: true });
-    } else if (isTreelike(value)) {
-      // Treat value as a subtree and write it out as a subdirectory.
-      const destTree = Reflect.construct(this.constructor, [destPath]);
-      // Create the directory here, even if the subtree is empty.
-      await fs.mkdir(destPath, { recursive: true });
-      // Write out the subtree.
-      await assign(destTree, value);
-    } else {
-      const typeName = value?.constructor?.name ?? "unknown";
-      throw new TypeError(
-        `Cannot write a value of type ${typeName} as ${stringKey}`
-      );
-    }
-
-    return this;
-  }
-
-  get url() {
-    return pathToFileURL(this.dirname);
-  }
-}
-
-/**
- * Return true if the entry is a directory or is a symbolic link to a directory.
- */
-async function isDirectory(entry, dirname) {
-  if (entry.isSymbolicLink()) {
-    const entryPath = path.resolve(dirname, entry.name);
-    try {
-      const realPath = await fs.realpath(entryPath);
-      entry = await fs.stat(realPath);
-    } catch (error) {
-      // The slash isn't crucial, so if link doesn't work that's okay
-      return false;
-    }
-  }
-  return entry.isDirectory();
-}
-
-// Return the file information for the file/folder at the given path.
-// If it does not exist, return undefined.
-async function stat(filePath) {
-  try {
-    // Await the result here so that, if the file doesn't exist, the catch block
-    // below will catch the exception.
-    return await fs.stat(filePath);
-  } catch (/** @type {any} */ error) {
-    if (error.code === "ENOENT" /* File not found */) {
-      return undefined;
-    }
-    throw error;
-  }
-}
-
-// Write a value to a file.
-async function writeFile(value, destPath) {
-  // Single writeable value.
-  if (value instanceof ArrayBuffer) {
-    // Convert ArrayBuffer to Uint8Array, which Node.js can write directly.
-    value = new Uint8Array(value);
-  }
-  // Ensure this directory exists.
-  const dirname = path.dirname(destPath);
-  await fs.mkdir(dirname, { recursive: true });
-
-  // Write out the value as the contents of a file.
-  try {
-    await fs.writeFile(destPath, value);
-  } catch (/** @type {any} */ error) {
-    if (error.code === "EISDIR" /* Is a directory */) {
-      throw new Error(
-        `Tried to overwrite a directory with a single file: ${destPath}`
-      );
-    }
-  }
-}

package/src/drivers/MapTree.js

@@ -1,70 +0,0 @@
-import isAsyncTree from "../operations/isAsyncTree.js";
-import * as trailingSlash from "../trailingSlash.js";
-import setParent from "../utilities/setParent.js";
-
-/**
- * A tree backed by a JavaScript `Map` object.
- *
- * Note: By design, the standard `Map` class already complies with the
- * `AsyncTree` interface. This class adds some additional tree behavior, such as
- * constructing subtree instances and setting their `parent` property. While
- * we'd like to construct this by subclassing `Map`, that class appears
- * puzzingly and deliberately implemented to break subclasses.
- *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
- * @implements {AsyncMutableTree}
- */
-export default class MapTree {
-  /**
-   * Constructs a new `MapTree` instance. This `iterable` parameter can be a
-   * `Map` instance, or any other iterable of key-value pairs.
-   *
-   * @param {Iterable} [source]
-   */
-  constructor(source = []) {
-    this.map = source instanceof Map ? source : new Map(source);
-    this.parent = null;
-  }
-
-  async get(key) {
-    // Try key as is
-    let value = this.map.get(key);
-    if (value === undefined) {
-      // Try the other variation of the key
-      const alternateKey = trailingSlash.toggle(key);
-      value = this.map.get(alternateKey);
-      if (value === undefined) {
-        // Key doesn't exist
-        return undefined;
-      }
-    }
-
-    value = await value;
-
-    if (value === undefined) {
-      // Key exists but value is undefined
-      return undefined;
-    }
-
-    setParent(value, this);
-    return value;
-  }
-
-  /** @returns {boolean} */
-  isSubtree(value) {
-    return isAsyncTree(value);
-  }
-
-  async keys() {
-    const keys = [];
-    for (const [key, value] of this.map.entries()) {
-      keys.push(trailingSlash.toggle(key, this.isSubtree(value)));
-    }
-    return keys;
-  }
-
-  async set(key, value) {
-    this.map.set(key, value);
-    return this;
-  }
-}

package/src/drivers/ObjectTree.js

@@ -1,158 +0,0 @@
-import isAsyncTree from "../operations/isAsyncTree.js";
-import * as symbols from "../symbols.js";
-import * as trailingSlash from "../trailingSlash.js";
-import getRealmObjectPrototype from "../utilities/getRealmObjectPrototype.js";
-import setParent from "../utilities/setParent.js";
-
-/**
- * A tree defined by a plain object or array.
- *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
- * @implements {AsyncMutableTree}
- */
-export default class ObjectTree {
-  /**
-   * Create a tree wrapping a given plain object or array.
-   *
-   * @param {object|any[]} object The object/array to wrap.
-   */
-  constructor(object) {
-    // Note: we use `typeof` here instead of `instanceof Object` to allow for
-    // objects such as Node's `Module` class for representing an ES module.
-    if (typeof object !== "object" || object === null) {
-      throw new TypeError(
-        `${this.constructor.name}: Expected an object or array.`
-      );
-    }
-    this.object = object;
-    this.parent = object[symbols.parent] ?? null;
-  }
-
-  /**
-   * Return the value for the given key.
-   *
-   * @param {any} key
-   */
-  async get(key) {
-    if (key == null) {
-      // Reject nullish key.
-      throw new ReferenceError(
-        `${this.constructor.name}: Cannot get a null or undefined key.`
-      );
-    }
-
-    // Does the object have the key with or without a trailing slash?
-    const existingKey = findExistingKey(this.object, key);
-    if (existingKey === null) {
-      // Key doesn't exist
-      return undefined;
-    }
-
-    let value = await this.object[existingKey];
-
-    if (value === undefined) {
-      // Key exists but value is undefined
-      return undefined;
-    }
-
-    setParent(value, this);
-
-    // Is value an instance method?
-    const isInstanceMethod =
-      value instanceof Function && !Object.hasOwn(this.object, key);
-    if (isInstanceMethod) {
-      // Bind it to the object
-      value = value.bind(this.object);
-    }
-
-    return value;
-  }
-
-  /** @returns {boolean} */
-  isSubtree(value) {
-    return isAsyncTree(value);
-  }
-
-  /**
-   * Enumerate the object's keys.
-   */
-  async keys() {
-    // Defer to symbols.keys if defined
-    if (typeof this.object[symbols.keys] === "function") {
-      return this.object[symbols.keys]();
-    }
-
-    // Walk up the prototype chain to realm's Object.prototype.
-    let obj = this.object;
-    const objectPrototype = getRealmObjectPrototype(obj);
-
-    const result = new Set();
-    while (obj && obj !== objectPrototype) {
-      // Get the enumerable instance properties and the get/set properties.
-      const descriptors = Object.getOwnPropertyDescriptors(obj);
-      const propertyNames = Object.entries(descriptors)
-        .filter(
-          ([name, descriptor]) =>
-            name !== "constructor" &&
-            (descriptor.enumerable ||
-              (descriptor.get !== undefined && descriptor.set !== undefined))
-        )
-        .map(([name, descriptor]) =>
-          trailingSlash.has(name)
-            ? // Preserve existing slash
-              name
-            : // Add a slash if the value is a plain property and a subtree
-              trailingSlash.toggle(
-                name,
-                descriptor.value !== undefined &&
-                  this.isSubtree(descriptor.value)
-              )
-        );
-      for (const name of propertyNames) {
-        result.add(name);
-      }
-      obj = Object.getPrototypeOf(obj);
-    }
-    return result;
-  }
-
-  /**
-   * Set the value for the given key. If the value is undefined, delete the key.
-   *
-   * @param {any} key
-   * @param {any} value
-   */
-  async set(key, value) {
-    const existingKey = findExistingKey(this.object, key);
-
-    if (value === undefined) {
-      // Delete the key if it exists.
-      if (existingKey !== null) {
-        delete this.object[existingKey];
-      }
-    } else {
-      // If the key exists under a different form, delete the existing key.
-      if (existingKey !== null && existingKey !== key) {
-        delete this.object[existingKey];
-      }
-
-      // Set the value for the key.
-      this.object[key] = value;
-    }
-
-    return this;
-  }
-}
-
-function findExistingKey(object, key) {
-  // First try key as is
-  if (key in object) {
-    return key;
-  }
-  // Try alternate form
-  const alternateKey = trailingSlash.toggle(key);
-  if (alternateKey in object) {
-    return alternateKey;
-  }
-  return null;
-}

package/src/drivers/SetTree.js

@@ -1,34 +0,0 @@
-import setParent from "../utilities/setParent.js";
-
-/**
- * A tree of Set objects.
- *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @implements {AsyncTree}
- */
-export default class SetTree {
-  /**
-   * @param {Set} set
-   */
-  constructor(set) {
-    this.values = Array.from(set);
-    this.parent = null;
-  }
-
-  async get(key) {
-    if (key == null) {
-      // Reject nullish key.
-      throw new ReferenceError(
-        `${this.constructor.name}: Cannot get a null or undefined key.`
-      );
-    }
-
-    const value = this.values[key];
-    setParent(value, this);
-    return value;
-  }
-
-  async keys() {
-    return this.values.keys();
-  }
-}

package/src/drivers/constantTree.js

@@ -1,19 +0,0 @@
-import * as trailingSlash from "../trailingSlash.js";
-
-/**
- * A tree that returns a constant value for any key. If the key ends with a
- * slash, then the same type of subtree is returned.
- *
- * @param {any} constant
- */
-export default function constantTree(constant) {
-  return {
-    async get(key) {
-      return trailingSlash.has(key) ? constantTree(constant) : constant;
-    },
-
-    async keys() {
-      return [];
-    },
-  };
-}

package/src/drivers/limitConcurrency.js

@@ -1,63 +0,0 @@
-/**
- * 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/internal.js

@@ -1,16 +0,0 @@
-//
-// This library includes a number of modules with circular dependencies. This
-// module exists to explicitly set the loading order for those modules. To
-// enforce use of this loading order, other modules should only load the modules
-// below via this module.
-//
-// About this pattern:
-// https://medium.com/visual-development/how-to-fix-nasty-circular-dependency-issues-once-and-for-all-in-javascript-typescript-a04c987cf0de
-//
-// Note: to avoid having VS Code auto-sort the imports, keep lines between them.
-
-export * as Tree from "./Tree.js";
-
-export { default as ObjectTree } from "./drivers/ObjectTree.js";
-
-export { default as DeepObjectTree } from "./drivers/DeepObjectTree.js";

package/src/utilities/getTreeArgument.js

@@ -1,43 +0,0 @@
-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;
-}

package/test/drivers/DeepMapTree.test.js

@@ -1,17 +0,0 @@
-import assert from "node:assert";
-import { describe, test } from "node:test";
-import DeepMapTree from "../../src/drivers/DeepMapTree.js";
-import { Tree } from "../../src/internal.js";
-
-describe("DeepMapTree", () => {
-  test("returns a DeepMapTree for value that's a Map", async () => {
-    const tree = new DeepMapTree([
-      ["a", 1],
-      ["map", new Map([["b", 2]])],
-    ]);
-    const map = await tree.get("map");
-    assert.equal(map instanceof DeepMapTree, true);
-    assert.deepEqual(await Tree.plain(map), { b: 2 });
-    assert.equal(map.parent, tree);
-  });
-});