@weborigami/async-tree 0.5.8 → 0.6.1

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,36 @@ export type TreeMapOptions = {
   value?: ValueKeyFn;
 };
 
-export type TreeMapExtensionOptions = {
-  deep?: boolean;
-  description?: string;
-  extension?: string;
-  needsSourceValue?: boolean;
-  value?: ValueKeyFn;
+export interface SyncTree<MapType> {
+  child(key: any): MapType;
+  parent: MapType | null;
+  trailingSlashKeys: boolean;
+}
+
+export interface AsyncTree<MapType> {
+  child(key: any): Promise<MapType>;
+  parent: MapType | null;
+  trailingSlashKeys: boolean;
+}
+
+/**
+ * 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 = (mapped: Map<any, any>, source: SyncOrAsyncMap) => any | Promise<any>;
+
+export type Stringlike = string | HasString;
+
+export type SyncOrAsyncMap = Map<any, any> | AsyncMap;
 
 export type TypedArray =
   Float32Array |
@@ -86,4 +94,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.1",
   "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,17 +1,19 @@
 // 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 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 reduce } from "./src/operations/reduce.js";
 export { default as scope } from "./src/operations/scope.js";
 export * as symbols from "./src/symbols.js";
 export * as trailingSlash from "./src/trailingSlash.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,63 @@ 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 { ExplorableSiteMap, FileMap, FunctionMap, ObjectMap, SetMap, SiteMap };
+
+export class DeepObjectMap extends ObjectMap {
+  constructor(object) {
+    super(object, { deep: true });
+    console.warn("DeepObjectMap is deprecated. Please use ObjectMap instead.");
+  }
+}
+
+export class ObjectTree extends ObjectMap {
+  constructor(...args) {
+    super(...args);
+    console.warn("ObjectTree is deprecated. Please use ObjectMap instead.");
+  }
+}
+
+export class DeepObjectTree extends ObjectMap {
+  constructor(object) {
+    super(object, { deep: true });
+    console.warn("DeepObjectTree is deprecated. Please use ObjectMap 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,14 @@
  * 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 child } from "./operations/child.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 +32,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";
@@ -45,12 +50,16 @@ export { default as paginate } from "./operations/paginate.js";
 export { default as parent } from "./operations/parent.js";
 export { default as paths } from "./operations/paths.js";
 export { default as plain } from "./operations/plain.js";
+export { default as reduce } from "./operations/reduce.js";
 export { default as regExpKeys } from "./operations/regExpKeys.js";
 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 set } from "./operations/set.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,237 @@
+import isMap from "../operations/isMap.js";
+import * as trailingSlash from "../trailingSlash.js";
+
+/**
+ * Base class for asynchronous maps. These have the same interface as Map but the methods
+ * are asynchronous.
+ *
+ * @typedef {import("../../index.ts").AsyncTree<AsyncMap>} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class AsyncMap {
+  /** @type {AsyncMap|null} */
+  _parent = null;
+
+  _readOnly;
+
+  [Symbol.asyncIterator]() {
+    return this.entries();
+  }
+
+  /**
+   * Return the child node for the given key, creating it if necessary.
+   */
+  async child(key) {
+    let result = await this.get(key);
+
+    // If child is already a map we can use it as is
+    if (!isMap(result)) {
+      // Create new child node using no-arg constructor
+      result = new /** @type {any} */ (this.constructor)();
+      await this.set(key, result);
+    }
+
+    result.parent = this;
+    return result;
+  }
+
+  /**
+   * Remove all key/value entries from the map.
+   *
+   * This method invokes the `keys()` and `delete()` methods.
+   */
+  async clear() {
+    const promises = [];
+    for await (const key of this.keys()) {
+      promises.push(this.delete(key));
+    }
+    await Promise.all(promises);
+  }
+
+  /**
+   * 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");
+  }
+
+  /**
+   * 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;
+    })();
+  }
+
+  trailingSlashKeys = false;
+
+  /**
+   * 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;
+  }
+}