@weborigami/async-tree 0.5.8 → 0.6.0

package/browser.js

@@ -1,4 +1,4 @@
 // Exports for browser
 
 export * from "./shared.js";
-export { default as BrowserFileTree } from "./src/drivers/BrowserFileTree.js";
+export { default as BrowserFileMap } from "./src/drivers/BrowserFileMap.js";

package/index.ts

@@ -1,10 +1,10 @@
-import type { AsyncTree } from "@weborigami/types";
+import AsyncMap from "./src/drivers/AsyncMap.js";
 
 export * from "./main.js";
 
-export type Invocable = Function | Treelike | Unpackable;
+export type Invocable = Function | Maplike | Unpackable;
 
-export type KeyFn = (key: any, innerTree: AsyncTree) => any;
+export type KeyFn = (key: any, map: SyncOrAsyncMap) => any;
 
 /**
  * An object with a non-trivial `toString` method.
@@ -17,36 +17,23 @@ export type HasString = {
   toString(): string;
 };
 
-/**
- * A packed value is one that can be written to a file via fs.writeFile or into
- * an HTTP response via response.write, or readily converted to such a form.
- */
-export type Packed = (ArrayBuffer | Buffer | ReadableStream | string | String | TypedArray) & {
-  parent?: AsyncTree|null;
-  unpack?(): Promise<any>;
-};
-
-export type PlainObject = {
-  [key: string]: any;
+export type MapExtensionOptions = {
+  deep?: boolean;
+  description?: string;
+  extension?: string;
+  needsSourceValue?: boolean;
+  value?: ValueKeyFn;
 };
 
-export type ReduceFn = (values: any[], keys: any[], tree: AsyncTree) => Promise<any>;
-
-export type Stringlike = string | HasString;
-
-export type NativeTreelike = 
+export type Maplike =
   any[] |
-  AsyncTree |
+  Iterator<any> |
   Function | 
-  Map<any, any> | 
+  SyncOrAsyncMap |
   PlainObject | 
   Set<any>;
 
-export type Treelike =
-  NativeTreelike |
-  Unpackable;
-
-export type TreeMapOptions = {
+export type MapOptions = {
   deep?: boolean;
   description?: string;
   extension?: string;
@@ -56,15 +43,24 @@ export type TreeMapOptions = {
   value?: ValueKeyFn;
 };
 
-export type TreeMapExtensionOptions = {
-  deep?: boolean;
-  description?: string;
-  extension?: string;
-  needsSourceValue?: boolean;
-  value?: ValueKeyFn;
+/**
+ * A packed value is one that can be written to a file via fs.writeFile or into
+ * an HTTP response via response.write, or readily converted to such a form.
+ */
+export type Packed = (ArrayBuffer | Buffer | ReadableStream | string | String | TypedArray) & {
+  parent?: SyncOrAsyncMap|null;
+  unpack?(): Promise<any>;
+};
+
+export type PlainObject = {
+  [key: string]: any;
 };
-  
-export type TreeTransform = (treelike: Treelike) => AsyncTree;
+
+export type ReduceFn = (values: any[], keys: any[], map: SyncOrAsyncMap) => any | Promise<any>;
+
+export type Stringlike = string | HasString;
+
+export type SyncOrAsyncMap = Map<any, any> | AsyncMap;
 
 export type TypedArray =
   Float32Array |
@@ -86,4 +82,4 @@ export type Unpackable = {
  */
 export type UnpackFunction = (input: Packed, options?: any) => any;
 
-export type ValueKeyFn = (value: any, key: any, innerTree: AsyncTree) => any;
+export type ValueKeyFn = (value: any, key: any, map: SyncOrAsyncMap) => any;

package/main.js

@@ -1,5 +1,4 @@
 // Exports for Node.js
 
 export * from "./shared.js";
-export { default as FileTree } from "./src/drivers/FileTree.js";
-export * as extension from "./src/extension.js";
+export { default as FileMap } from "./src/drivers/FileMap.js";

package/package.json

@@ -1,18 +1,15 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
-  "dependencies": {
-    "@weborigami/types": "0.5.8"
-  },
   "devDependencies": {
-    "@types/node": "24.3.0",
-    "puppeteer": "24.17.0",
-    "typescript": "5.9.2"
+    "@types/node": "24.10.1",
+    "puppeteer": "24.30.0",
+    "typescript": "5.9.3"
   },
   "scripts": {
     "headlessTest": "node test/browser/headlessTest.js",

package/shared.js

@@ -1,16 +1,18 @@
 // Exports for both Node.js and browser
 
-export { default as calendar } from "./src/drivers/calendarTree.js";
-export { default as constant } from "./src/drivers/constantTree.js";
-export { default as DeepMapTree } from "./src/drivers/DeepMapTree.js";
-export { default as DeepObjectTree } from "./src/drivers/DeepObjectTree.js";
-export { default as DeferredTree } from "./src/drivers/DeferredTree.js";
-export { default as ExplorableSiteTree } from "./src/drivers/ExplorableSiteTree.js";
-export { default as FunctionTree } from "./src/drivers/FunctionTree.js";
-export { default as MapTree } from "./src/drivers/MapTree.js";
-export { default as ObjectTree } from "./src/drivers/ObjectTree.js";
-export { default as SetTree } from "./src/drivers/SetTree.js";
-export { default as SiteTree } from "./src/drivers/SiteTree.js";
+import { default as DeepObjectMap } from "./src/drivers/DeepObjectMap.js";
+import { default as ExplorableSiteMap } from "./src/drivers/ExplorableSiteMap.js";
+import { default as FileMap } from "./src/drivers/FileMap.js";
+import { default as FunctionMap } from "./src/drivers/FunctionMap.js";
+import { default as ObjectMap } from "./src/drivers/ObjectMap.js";
+import { default as SetMap } from "./src/drivers/SetMap.js";
+import { default as SiteMap } from "./src/drivers/SiteMap.js";
+
+export { default as AsyncMap } from "./src/drivers/AsyncMap.js";
+export { default as CalendarMap } from "./src/drivers/CalendarMap.js";
+export { default as ConstantMap } from "./src/drivers/ConstantMap.js";
+export { default as SyncMap } from "./src/drivers/SyncMap.js";
+export * as extension from "./src/extension.js";
 export * as jsonKeys from "./src/jsonKeys.js";
 export { default as scope } from "./src/operations/scope.js";
 export * as symbols from "./src/symbols.js";
@@ -19,9 +21,9 @@ export { default as TraverseError } from "./src/TraverseError.js";
 export * as Tree from "./src/Tree.js";
 export { default as box } from "./src/utilities/box.js";
 export { default as castArraylike } from "./src/utilities/castArraylike.js";
+export { default as getTreeArgument } from "./src/utilities/getMapArgument.js";
 export { default as getParent } from "./src/utilities/getParent.js";
 export { default as getRealmObjectPrototype } from "./src/utilities/getRealmObjectPrototype.js";
-export { default as getTreeArgument } from "./src/utilities/getTreeArgument.js";
 export { default as isPacked } from "./src/utilities/isPacked.js";
 export { default as isPlainObject } from "./src/utilities/isPlainObject.js";
 export { default as isStringlike } from "./src/utilities/isStringlike.js";
@@ -32,3 +34,66 @@ export { default as pathFromKeys } from "./src/utilities/pathFromKeys.js";
 export { default as setParent } from "./src/utilities/setParent.js";
 export { default as toPlainValue } from "./src/utilities/toPlainValue.js";
 export { default as toString } from "./src/utilities/toString.js";
+
+export {
+  DeepObjectMap,
+  ExplorableSiteMap,
+  FileMap,
+  FunctionMap,
+  ObjectMap,
+  SetMap,
+  SiteMap,
+};
+
+export class ObjectTree extends ObjectMap {
+  constructor(...args) {
+    super(...args);
+    console.warn("ObjectTree is deprecated. Please use ObjectMap instead.");
+  }
+}
+
+export class DeepObjectTree extends DeepObjectMap {
+  constructor(...args) {
+    super(...args);
+    console.warn(
+      "DeepObjectTree is deprecated. Please use DeepObjectMap instead."
+    );
+  }
+}
+
+export class ExplorableSiteTree extends ExplorableSiteMap {
+  constructor(href) {
+    super(href);
+    console.warn(
+      "ExplorableSiteTree is deprecated. Please use ExplorableSiteMap instead."
+    );
+  }
+}
+
+export class FileTree extends FileMap {
+  constructor(...args) {
+    super(...args);
+    console.warn("FileTree is deprecated. Please use FileMap instead.");
+  }
+}
+
+export class FunctionTree extends FunctionMap {
+  constructor(...args) {
+    super(...args);
+    console.warn("FunctionTree is deprecated. Please use FunctionMap instead.");
+  }
+}
+
+export class SetTree extends SetMap {
+  constructor(set) {
+    super(set);
+    console.warn("SetTree is deprecated. Please use SetMap instead.");
+  }
+}
+
+export class SiteTree extends SiteMap {
+  constructor(...args) {
+    super(...args);
+    console.warn("SiteTree is deprecated. Please use SiteMap instead.");
+  }
+}

package/src/Tree.js

@@ -2,12 +2,13 @@
  * Collection of functions for working with async trees
  */
 
-export { default as calendar } from "./drivers/calendarTree.js";
-export { default as constant } from "./drivers/constantTree.js";
 export { default as addNextPrevious } from "./operations/addNextPrevious.js";
 export { default as assign } from "./operations/assign.js";
 export { default as cache } from "./operations/cache.js";
+export { default as calendar } from "./operations/calendar.js";
 export { default as clear } from "./operations/clear.js";
+export { default as constant } from "./operations/constant.js";
+export { default as deepEntries } from "./operations/deepEntries.js";
 export { default as deepMap } from "./operations/deepMap.js";
 export { default as deepMerge } from "./operations/deepMerge.js";
 export { default as deepReverse } from "./operations/deepReverse.js";
@@ -30,6 +31,9 @@ export { default as inners } from "./operations/inners.js";
 export { default as invokeFunctions } from "./operations/invokeFunctions.js";
 export { default as isAsyncMutableTree } from "./operations/isAsyncMutableTree.js";
 export { default as isAsyncTree } from "./operations/isAsyncTree.js";
+export { default as isMap } from "./operations/isMap.js";
+export { default as isMaplike } from "./operations/isMaplike.js";
+export { default as isReadOnlyMap } from "./operations/isReadOnlyMap.js";
 export { default as isTraversable } from "./operations/isTraversable.js";
 export { default as isTreelike } from "./operations/isTreelike.js";
 export { default as json } from "./operations/json.js";
@@ -50,7 +54,9 @@ export { default as reverse } from "./operations/reverse.js";
 export { default as root } from "./operations/root.js";
 export { default as scope } from "./operations/scope.js";
 export { default as shuffle } from "./operations/shuffle.js";
+export { default as size } from "./operations/size.js";
 export { default as sort } from "./operations/sort.js";
+export { default as sync } from "./operations/sync.js";
 export { default as take } from "./operations/take.js";
 export { default as text } from "./operations/text.js";
 export { default as toFunction } from "./operations/toFunction.js";

package/src/drivers/AsyncMap.js

@@ -0,0 +1,210 @@
+import * as trailingSlash from "../trailingSlash.js";
+
+export default class AsyncMap {
+  /** @type {AsyncMap|null} */
+  _parent = null;
+
+  _readOnly;
+
+  [Symbol.asyncIterator]() {
+    return this.entries();
+  }
+
+  /**
+   * Remove all key/value entries from the map.
+   *
+   * This method invokes the `keys()` and `delete()` methods.
+   */
+  async clear() {
+    for await (const key of this.keys()) {
+      await this.delete(key);
+    }
+  }
+
+  /**
+   * Removes the entry for the given key, return true if an entry was removed
+   * and false if there was no entry for the key.
+   *
+   * @param {any} key
+   * @returns {Promise<boolean>}
+   */
+  async delete(key) {
+    throw new Error("delete() not implemented");
+  }
+
+  static EMPTY = Symbol("EMPTY");
+
+  /**
+   * Returns a new `AsyncIterator` object that contains a two-member array of
+   * [key, value] for each element in the map in insertion order.
+   *
+   * This method invokes the `keys()` and `get()` methods.
+   *
+   * @returns {AsyncIterableIterator<[any, any]>}
+   */
+  async *entries() {
+    const keys = [];
+    const valuePromises = [];
+    // Invoke get() calls without waiting; some may take longer than others
+    for await (const key of this.keys()) {
+      keys.push(key);
+      valuePromises.push(this.get(key));
+    }
+    // Now wait for all promises to resolve
+    const values = await Promise.all(valuePromises);
+    for (let i = 0; i < keys.length; i++) {
+      yield [keys[i], values[i]];
+    }
+  }
+
+  /**
+   * Calls `callback` once for each key/value pair in the map, in insertion order.
+   *
+   * This method invokes the `entries()` method.
+   *
+   * @param {(value: any, key: any, thisArg: any) => Promise<void>} callback
+   * @param {any?} thisArg
+   */
+  async forEach(callback, thisArg = this) {
+    for await (const [key, value] of this.entries()) {
+      await callback(value, key, thisArg);
+    }
+  }
+
+  /**
+   * Returns the value associated with the key, or undefined if there is none.
+   *
+   * @param {any} key
+   * @returns {Promise<any>}
+   */
+  async get(key) {
+    throw new Error("get() not implemented");
+  }
+
+  /**
+   * Groups items from an async iterable into an AsyncMap according to the keys
+   * returned by the given function.
+   *
+   * @param {Iterable<any>|AsyncIterable<any>} iterable
+   * @param {(element: any, index: any) => Promise<any>} keyFn
+   * @returns {Promise<Map>}
+   */
+  static async groupBy(iterable, keyFn) {
+    const map = new Map();
+    let index = 0;
+    for await (const element of iterable) {
+      const key = await keyFn(element, index);
+      if (!map.has(key)) {
+        map.set(key, []);
+      }
+      map.get(key).push(element);
+      index++;
+    }
+    return map;
+  }
+
+  /**
+   * Returns true if the given key appears in the set returned by keys().
+   *
+   * It doesn't matter whether the value returned by get() is defined or not.
+   *
+   * If the requested key has a trailing slash but has no associated value, but
+   * the alternate form with a slash does appear, this returns true.
+   *
+   * @param {any} key
+   */
+  async has(key) {
+    const alternateKey = !trailingSlash.has(key)
+      ? trailingSlash.add(key)
+      : null;
+    for await (const k of this.keys()) {
+      if (k === key) {
+        return true;
+      }
+      if (alternateKey && k === alternateKey) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Returns a new `AsyncIterator` object that contains the keys for each
+   * element in the map in insertion order.
+   *
+   * @returns {AsyncIterableIterator<any>}
+   */
+  async *keys() {
+    throw new Error("keys() not implemented");
+  }
+
+  /**
+   * The parent of this node in a tree.
+   */
+  get parent() {
+    return this._parent;
+  }
+  set parent(parent) {
+    this._parent = parent;
+  }
+
+  /**
+   * True if the object is read-only. This will be true if `get()` has been
+   * overridden but `set()` and `delete()` have not.
+   */
+  get readOnly() {
+    return (
+      this.get !== AsyncMap.prototype.get &&
+      (this.set === AsyncMap.prototype.set ||
+        this.delete === AsyncMap.prototype.delete)
+    );
+  }
+
+  /**
+   * Sets the value for the given key.
+   *
+   * @param {any} key
+   * @param {any} value
+   * @returns {Promise<AsyncMap>}
+   */
+  async set(key, value) {
+    throw new Error("set() not implemented");
+  }
+
+  /**
+   * Returns the number of keys in the map.
+   *
+   * The `size` property invokes an overridden `keys()` to ensure proper
+   * behavior in subclasses. Because a subclass may not enforce a direct
+   * correspondence between `keys()` and `get()`, the size may not reflect the
+   * number of values that can be retrieved.
+   *
+   * @type {Promise<number>}
+   */
+  get size() {
+    return (async () => {
+      let count = 0;
+      for await (const _ of this.keys()) {
+        count++;
+      }
+      return count;
+    })();
+  }
+
+  /**
+   * Returns a new `AsyncIterator` object that contains the values for each
+   * element in the map in insertion order.
+   *
+   * @returns {AsyncIterableIterator<any>}
+   */
+  async *values() {
+    const valuePromises = [];
+    // Invoke get() calls without waiting; some may take longer than others
+    for await (const key of this.keys()) {
+      valuePromises.push(this.get(key));
+    }
+    // Now wait for all promises to resolve
+    const values = await Promise.all(valuePromises);
+    yield* values;
+  }
+}

package/src/drivers/{BrowserFileTree.js → BrowserFileMap.js}

@@ -1,24 +1,22 @@
 import { hiddenFileNames } from "../constants.js";
 import assign from "../operations/assign.js";
-import isTreelike from "../operations/isTreelike.js";
+import isMaplike from "../operations/isMaplike.js";
 import * as trailingSlash from "../trailingSlash.js";
 import isStringlike from "../utilities/isStringlike.js";
 import naturalOrder from "../utilities/naturalOrder.js";
 import setParent from "../utilities/setParent.js";
+import AsyncMap from "./AsyncMap.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
 /**
- * A tree of files backed by a browser-hosted file system such as the standard
+ * A map 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 {
+export default class BrowserFileMap extends AsyncMap {
   /**
-   * Construct a tree of files backed by a browser-hosted file system.
+   * Construct a map 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).
@@ -28,11 +26,28 @@ export default class BrowserFileTree {
    * @param {FileSystemDirectoryHandle} [directoryHandle]
    */
   constructor(directoryHandle) {
-    /** @type {FileSystemDirectoryHandle}
-     * @ts-ignore */
+    super();
     this.directory = directoryHandle;
   }
 
+  async delete(key) {
+    const baseKey = trailingSlash.remove(key);
+    const directory = await this.getDirectory();
+
+    // Delete file.
+    try {
+      await directory.removeEntry(baseKey);
+    } catch (error) {
+      // If the file didn't exist, ignore the error.
+      if (error instanceof DOMException && error.name === "NotFoundError") {
+        return false;
+      }
+      throw error;
+    }
+
+    return true;
+  }
+
   async get(key) {
     if (key == null) {
       // Reject nullish key.
@@ -90,7 +105,7 @@ export default class BrowserFileTree {
     return this.directory;
   }
 
-  async keys() {
+  async *keys() {
     const directory = await this.getDirectory();
     let keys = [];
     // @ts-ignore
@@ -110,28 +125,13 @@ export default class BrowserFileTree {
     keys = keys.filter((key) => !hiddenFileNames.includes(key));
     keys.sort(naturalOrder);
 
-    return keys;
+    yield* keys;
   }
 
   async set(key, value) {
     const baseKey = trailingSlash.remove(key);
     const directory = await this.getDirectory();
 
-    if (value === undefined) {
-      // Delete file.
-      try {
-        await directory.removeEntry(baseKey);
-      } 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 = "";
@@ -158,7 +158,12 @@ export default class BrowserFileTree {
       const writable = await fileHandle.createWritable();
       await writable.write(value);
       await writable.close();
-    } else if (isTreelike(value)) {
+    } else if (value === /** @type {any} */ (this.constructor).EMPTY) {
+      // Create empty subtree.
+      await directory.getDirectoryHandle(baseKey, {
+        create: true,
+      });
+    } else if (isMaplike(value)) {
       // Treat value as a tree and write it out as a subdirectory.
       const subdirectory = await directory.getDirectoryHandle(baseKey, {
         create: true,
@@ -172,4 +177,8 @@ export default class BrowserFileTree {
 
     return this;
   }
+
+  get trailingSlashKeys() {
+    return true;
+  }
 }