@weborigami/async-tree 0.0.35

package/ReadMe.md

@@ -0,0 +1 @@
+This library contains definitions for asynchronous trees backed by standard JavaScript classes like `Object` and `Map` and standard browser APIs such as the [Origin Private File System](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system). The library also includes collections of helpers for common tree operations.

package/browser.js

@@ -0,0 +1,13 @@
+// Exports for browser
+
+export { default as DeferredTree } from "./src/DeferredTree.js";
+// Skip FileTree.js, which is Node.js only.
+export { default as BrowserFileTree } from "./src/BrowserFileTree.js";
+export { default as FunctionTree } from "./src/FunctionTree.js";
+export { default as MapTree } from "./src/MapTree.js";
+export { default as ObjectTree } from "./src/ObjectTree.js";
+export { default as SetTree } from "./src/SetTree.js";
+export { default as SiteTree } from "./src/SiteTree.js";
+export * as Tree from "./src/Tree.js";
+export * as keysJson from "./src/keysJson.js";
+export * from "./src/utilities.js";

package/index.ts

@@ -0,0 +1,44 @@
+import type { AsyncTree } from "@weborigami/types";
+
+export * from "./main.js";
+
+export type KeyFn = (key: any, innerTree: AsyncTree) => any;
+
+/**
+ * An object with a non-trivial `toString` method.
+ *
+ * TODO: We want to deliberately exclude the base `Object` class because its
+ * `toString` method return non-useful strings like `[object Object]`. How can
+ * we declare that in TypeScript?
+ */
+export type HasString = {
+  toString(): string;
+};
+
+export type PlainObject = {
+  [key: string]: any;
+};
+
+export type ReduceFn = (values: any[], keys: any[]) => Promise<any>;
+
+export type StringLike = string | HasString;
+
+type NativeTreelike = 
+  any[] |
+  AsyncTree |
+  Function | 
+  Map<any, any> | 
+  PlainObject | 
+  Set<any>;
+
+export type Treelike =
+  NativeTreelike |
+  Unpackable<NativeTreelike>;
+
+export type TreeTransform = (tree: AsyncTree) => AsyncTree;
+
+export type Unpackable<T> = {
+  unpack(): Promise<T>
+};
+
+export type ValueKeyFn = (value: any, key: any, innerTree: AsyncTree) => any;

package/main.js

@@ -0,0 +1,23 @@
+// Exports for Node.js
+
+export { default as DeferredTree } from "./src/DeferredTree.js";
+export { default as FileTree } from "./src/FileTree.js";
+export { default as FunctionTree } from "./src/FunctionTree.js";
+export { default as MapTree } from "./src/MapTree.js";
+export { default as ObjectTree } from "./src/ObjectTree.js";
+// Skip BrowserFileTree.js, which is browser-only.
+export { default as SetTree } from "./src/SetTree.js";
+export { default as SiteTree } from "./src/SiteTree.js";
+export * as Tree from "./src/Tree.js";
+export * as keysJson from "./src/keysJson.js";
+export { default as cache } from "./src/operations/cache.js";
+export { default as merge } from "./src/operations/merge.js";
+export { default as mergeDeep } from "./src/operations/mergeDeep.js";
+export { default as cachedKeyMaps } from "./src/transforms/cachedKeyMaps.js";
+export { default as groupBy } from "./src/transforms/groupBy.js";
+export { default as keyMapsForExtensions } from "./src/transforms/keyMapsForExtensions.js";
+export { default as map } from "./src/transforms/map.js";
+export { default as sort } from "./src/transforms/sort.js";
+export { default as sortBy } from "./src/transforms/sortBy.js";
+export { default as sortNatural } from "./src/transforms/sortNatural.js";
+export * from "./src/utilities.js";

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@weborigami/async-tree",
+  "version": "0.0.35",
+  "description": "Asynchronous tree drivers based on standard JavaScript classes",
+  "type": "module",
+  "main": "./main.js",
+  "browser": "./browser.js",
+  "types": "./index.ts",
+  "devDependencies": {
+    "@types/node": "20.8.10",
+    "typescript": "5.2.2"
+  },
+  "dependencies": {
+    "@weborigami/types": "https://gitpkg.now.sh/GraphOrigami/origami/types?main"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc"
+  }
+}

package/src/BrowserFileTree.js

@@ -0,0 +1,137 @@
+import * as Tree from "./Tree.js";
+import { hiddenFileNames, isStringLike, sortNatural } from "./utilities.js";
+
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
+/**
+ * A tree of files backed by a browser-hosted file system such as the standard
+ * Origin Private File System or the (as of October 2023) experimental File
+ * System Access API.
+ *
+ * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @implements {AsyncMutableTree}
+ */
+export default class BrowserFileTree {
+  /**
+   * Construct a tree of files backed by a browser-hosted file system.
+   *
+   * The directory handle can be obtained via any of the [methods that return a
+   * FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle).
+   * If no directory is supplied, the tree is rooted at the Origin Private File
+   * System for the current site.
+   *
+   * @param {FileSystemDirectoryHandle} [directoryHandle]
+   */
+  constructor(directoryHandle) {
+    /** @type {FileSystemDirectoryHandle}
+     * @ts-ignore */
+    this.directory = directoryHandle;
+  }
+
+  async get(key) {
+    const directory = await this.getDirectory();
+
+    // Try the key as a subfolder name.
+    try {
+      const subfolderHandle = await directory.getDirectoryHandle(key);
+      return Reflect.construct(this.constructor, [subfolderHandle]);
+    } catch (error) {
+      if (
+        !(
+          error instanceof DOMException &&
+          (error.name === "NotFoundError" || error.name === "TypeMismatchError")
+        )
+      ) {
+        throw error;
+      }
+    }
+
+    // Try the key as a file name.
+    try {
+      const fileHandle = await directory.getFileHandle(key);
+      const file = await fileHandle.getFile();
+      return file.arrayBuffer();
+    } catch (error) {
+      if (!(error instanceof DOMException && error.name === "NotFoundError")) {
+        throw error;
+      }
+    }
+
+    return undefined;
+  }
+
+  async getDirectory() {
+    this.directory ??= await navigator.storage.getDirectory();
+    return this.directory;
+  }
+
+  async keys() {
+    const directory = await this.getDirectory();
+    let keys = [];
+    // @ts-ignore
+    for await (const key of directory.keys()) {
+      keys.push(key);
+    }
+    // Filter out unhelpful file names.
+    keys = keys.filter((key) => !hiddenFileNames.includes(key));
+    sortNatural(keys);
+    return keys;
+  }
+
+  async set(key, value) {
+    const directory = await this.getDirectory();
+
+    if (value === undefined) {
+      // Delete file.
+      try {
+        await directory.removeEntry(key);
+      } catch (error) {
+        // If the file didn't exist, ignore the error.
+        if (
+          !(error instanceof DOMException && error.name === "NotFoundError")
+        ) {
+          throw error;
+        }
+      }
+      return this;
+    }
+
+    // Treat null value as empty string; will create an empty file.
+    if (value === null) {
+      value = "";
+    }
+
+    // True if fs.writeFile can directly write the value to a file.
+    let isWriteable =
+      value instanceof ArrayBuffer ||
+      value instanceof TypedArray ||
+      value instanceof DataView ||
+      value instanceof Blob;
+
+    if (!isWriteable && isStringLike(value)) {
+      // Value has a meaningful `toString` method, use that.
+      value = String(value);
+      isWriteable = true;
+    }
+
+    if (isWriteable) {
+      // Write file.
+      const fileHandle = await directory.getFileHandle(key, { create: true });
+      const writable = await fileHandle.createWritable();
+      await writable.write(value);
+      await writable.close();
+    } else if (Tree.isTreelike(value)) {
+      // Treat value as a tree and write it out as a subdirectory.
+      const subdirectory = await directory.getDirectoryHandle(key, {
+        create: true,
+      });
+      const destTree = Reflect.construct(this.constructor, [subdirectory]);
+      await Tree.assign(destTree, value);
+    } else {
+      const typeName = value?.constructor?.name ?? "unknown";
+      throw new TypeError(`Cannot write a value of type ${typeName} as ${key}`);
+    }
+
+    return this;
+  }
+}

package/src/DeferredTree.js

@@ -0,0 +1,72 @@
+import * as Tree from "./Tree.js";
+
+/**
+ * A tree that is loaded lazily.
+ *
+ * This is useful in situations that must return a tree synchronously. If
+ * constructing the tree requires an asynchronous operation, this class can be
+ * used as a wrapper that can be returned immediately. The tree will be loaded
+ * the first time the keys() or get() functions are called.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class DeferredTree {
+  /**
+   * @param {Function|Promise<any>} loader
+   */
+  constructor(loader) {
+    this.loader = loader;
+    this.treePromise = null;
+    this._tree = null;
+    this._parent = null;
+  }
+
+  async get(key) {
+    const tree = await this.tree();
+    return tree.get(key);
+  }
+
+  async loadResult() {
+    if (!(this.loader instanceof Promise)) {
+      this.loader = this.loader();
+    }
+    return this.loader;
+  }
+
+  async keys() {
+    const tree = await this.tree();
+    return tree.keys();
+  }
+
+  get parent() {
+    return this._tree?.parent ?? this._parent;
+  }
+  set parent(parent) {
+    if (this._tree && !this._tree.parent) {
+      this._tree.parent = parent;
+    } else {
+      this._parent = parent;
+    }
+  }
+
+  async tree() {
+    if (this._tree) {
+      return this._tree;
+    }
+
+    // Use a promise to ensure the treelike is only converted to a tree once.
+    this.treePromise ??= this.loadResult().then((treelike) => {
+      this._tree = Tree.from(treelike);
+      if (this._parent) {
+        if (!this._tree.parent) {
+          this._tree.parent = this._parent;
+        }
+        this._parent = null;
+      }
+      return this._tree;
+    });
+
+    return this.treePromise;
+  }
+}

package/src/FileTree.js

@@ -0,0 +1,193 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as Tree from "./Tree.js";
+import {
+  getRealmObjectPrototype,
+  hiddenFileNames,
+  sortNatural,
+} from "./utilities.js";
+
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
+/**
+ * A file system tree via the Node file system API.
+ *
+ * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @implements {AsyncMutableTree}
+ */
+export default class FileTree {
+  /**
+   * @param {string} location
+   */
+  constructor(location) {
+    this.dirname = location.startsWith("file://")
+      ? path.dirname(fileURLToPath(location))
+      : path.resolve(process.cwd(), location);
+    this.parent = null;
+  }
+
+  async get(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;
+    }
+
+    if (stats.isDirectory()) {
+      // Return subdirectory as a tree
+      const subtree = Reflect.construct(this.constructor, [filePath]);
+      subtree.parent = this;
+      return subtree;
+    } else {
+      // Return file contents
+      return fs.readFile(filePath);
+    }
+  }
+
+  async isKeyForSubtree(key) {
+    const filePath = path.join(this.dirname, key);
+    const stats = await stat(filePath);
+    return stats ? stats.isDirectory() : false;
+  }
+
+  /**
+   * Enumerate the names of the files/subdirectories in this directory.
+   */
+  async keys() {
+    let entries;
+    try {
+      entries = await fs.readdir(this.dirname, { withFileTypes: true });
+    } catch (/** @type {any} */ error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+      entries = [];
+    }
+
+    let names = entries.map((entry) => entry.name);
+
+    // 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.
+    sortNatural(names);
+    return names;
+  }
+
+  get path() {
+    return this.dirname;
+  }
+
+  async set(key, value) {
+    // Where are we going to write this value?
+    const stringKey = key ? String(key) : "";
+    const destPath = path.resolve(this.dirname, stringKey);
+
+    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;
+    }
+
+    // Treat null value as empty string; will create an empty file.
+    if (value === null) {
+      value = "";
+    }
+
+    if (value instanceof ArrayBuffer) {
+      // Convert ArrayBuffer to Uint8Array, which Node.js can write directly.
+      value = new Uint8Array(value);
+    }
+
+    // True if fs.writeFile can directly write the value to a file.
+    let isWriteable =
+      value instanceof TypedArray ||
+      value instanceof DataView ||
+      (globalThis.ReadableStream && value instanceof ReadableStream);
+
+    if (!isWriteable && isStringLike(value)) {
+      // Value has a meaningful `toString` method, use that.
+      value = String(value);
+      isWriteable = true;
+    }
+
+    if (isWriteable) {
+      // Ensure this directory exists.
+      await fs.mkdir(this.dirname, { recursive: true });
+      // Write out the value as the contents of a file.
+      await fs.writeFile(destPath, value);
+    } else if (Tree.isTreelike(value)) {
+      // Treat value as a tree and write it out as a subdirectory.
+      const destTree = Reflect.construct(this.constructor, [destPath]);
+      await Tree.assign(destTree, value);
+    } else {
+      const typeName = value?.constructor?.name ?? "unknown";
+      throw new TypeError(
+        `Cannot write a value of type ${typeName} as ${stringKey}`
+      );
+    }
+
+    return this;
+  }
+}
+
+/**
+ * Return true if the object is a string or object with a non-trival `toString`
+ * method.
+ *
+ * @param {any} obj
+ */
+function isStringLike(obj) {
+  if (typeof obj === "string") {
+    return true;
+  } else if (obj?.toString === undefined) {
+    return false;
+  } else if (obj.toString === getRealmObjectPrototype(obj).toString) {
+    // The stupid Object.prototype.toString implementation always returns
+    // "[object Object]", so if that's the only toString method the object has,
+    // we return false.
+    return false;
+  } else {
+    return true;
+  }
+}
+
+// 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;
+  }
+}

package/src/FunctionTree.js

@@ -0,0 +1,47 @@
+/**
+ * A tree defined by a function and an optional domain.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class FunctionTree {
+  /**
+   * @param {function} fn the key->value function
+   * @param {Iterable<any>} [domain] optional domain of the function
+   */
+  constructor(fn, domain = []) {
+    this.fn = fn;
+    this.domain = domain;
+    this.parent = null;
+  }
+
+  /**
+   * Return the application of the function to the given key.
+   *
+   * @param {any} key
+   */
+  async get(key) {
+    const value =
+      this.fn.length <= 1
+        ? // Function takes no arguments or only one argument: invoke
+          await this.fn.call(null, key)
+        : // Bind the key to the first parameter. Subsequent get calls will
+          // eventually bind all parameters until only one remains. At that point,
+          // the above condition will apply and the function will be invoked.
+          Reflect.construct(this.constructor, [this.fn.bind(null, key)]);
+
+    return value;
+  }
+
+  /**
+   * Enumerates the function's domain (if defined) as the tree's keys. If no domain
+   * was defined, this returns an empty iterator.
+   */
+  async keys() {
+    return this.domain;
+  }
+
+  async unpack() {
+    return this.fn;
+  }
+}

package/src/MapTree.js

@@ -0,0 +1,51 @@
+import * as Tree from "./Tree.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 {
+  /**
+   * @param {Iterable} [iterable]
+   */
+  constructor(iterable = []) {
+    this.map = new Map(iterable);
+    this.parent = null;
+  }
+
+  async get(key) {
+    let value = this.map.get(key);
+
+    if (value instanceof Map) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+
+    if (Tree.isAsyncTree(value) && !value.parent) {
+      value.parent = this;
+    }
+
+    return value;
+  }
+
+  async isKeyForSubtree(key) {
+    const value = this.map.get(key);
+    return value instanceof Map || Tree.isAsyncTree(value);
+  }
+
+  async keys() {
+    return this.map.keys();
+  }
+
+  async set(key, value) {
+    this.map.set(key, value);
+    return this;
+  }
+}