@weborigami/async-tree 0.0.45 → 0.0.47

package/index.ts

@@ -15,6 +15,12 @@ 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;
+
 export type PlainObject = {
   [key: string]: any;
 };
@@ -35,7 +41,18 @@ export type Treelike =
   NativeTreelike |
   Unpackable<NativeTreelike>;
 
-export type TreeTransform = (tree: AsyncTree) => AsyncTree;
+export type TreeTransform = (treelike: Treelike) => AsyncTree;
+
+export type TypedArray =
+  Float32Array |
+  Float64Array |
+  Int8Array |
+  Int16Array |
+  Int32Array |
+  Uint8Array |
+  Uint8ClampedArray |
+  Uint16Array |
+  Uint32Array;
 
 export type Unpackable<T> = {
   unpack(): Promise<T>

package/main.js

@@ -4,20 +4,19 @@ 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 DeepMapTree } from "./src/DeepMapTree.js";
-export { default as DeepObjectTree } from "./src/DeepObjectTree.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 { DeepObjectTree, ObjectTree, Tree } from "./src/internal.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 * as symbols from "./src/symbols.js";
+export { default as cachedKeyFunctions } from "./src/transforms/cachedKeyFunctions.js";
 export { default as groupBy } from "./src/transforms/groupBy.js";
-export { default as keyMapsForExtensions } from "./src/transforms/keyMapsForExtensions.js";
+export { default as keyFunctionsForExtensions } from "./src/transforms/keyFunctionsForExtensions.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";

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.45",
+  "version": "0.0.47",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "20.11.7",
-    "typescript": "5.3.3"
+    "@types/node": "20.11.27",
+    "typescript": "5.4.2"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.45"
+    "@weborigami/types": "0.0.47"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/BrowserFileTree.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 import { hiddenFileNames, isStringLike, sortNatural } from "./utilities.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);

package/src/DeepMapTree.js

@@ -1,5 +1,5 @@
+import { Tree } from "./internal.js";
 import MapTree from "./MapTree.js";
-import * as Tree from "./Tree.js";
 
 export default class DeepMapTree extends MapTree {
   async get(key) {

package/src/DeepObjectTree.js

@@ -1,5 +1,4 @@
-import ObjectTree from "./ObjectTree.js";
-import * as Tree from "./Tree.js";
+import { ObjectTree, Tree } from "./internal.js";
 import { isPlainObject } from "./utilities.js";
 
 export default class DeepObjectTree extends ObjectTree {

package/src/DeferredTree.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 
 /**
  * A tree that is loaded lazily.
@@ -19,7 +19,8 @@ export default class DeferredTree {
     this.loader = loader;
     this.treePromise = null;
     this._tree = null;
-    this._parent = null;
+    this._parentUntilLoaded = null;
+    this._scopeUntilLoaded = null;
   }
 
   async get(key) {
@@ -39,14 +40,17 @@ export default class DeferredTree {
     return tree.keys();
   }
 
+  // A deferred tree's parent generally comes from the loaded tree. However, if
+  // someone tries to get or set the parent before the tree is loaded, we store
+  // that parent reference and apply it once the tree is loaded.
   get parent() {
-    return this._tree?.parent ?? this._parent;
+    return this._tree?.parent ?? this._parentUntilLoaded;
   }
   set parent(parent) {
     if (this._tree && !this._tree.parent) {
       this._tree.parent = parent;
     } else {
-      this._parent = parent;
+      this._parentUntilLoaded = parent;
     }
   }
 
@@ -61,9 +65,11 @@ export default class DeferredTree {
     return /** @type {any} */ (this._tree)?.scope;
   }
   set scope(scope) {
-    // If tree hasn't been loaded yet, setting scope has no effect.
-    if (this._tree) {
+    // As with `parent`, we can defer setting of scope.
+    if (this._tree && !(/** @type {any} */ (this._tree).scope)) {
       /** @type {any} */ (this._tree).scope = scope;
+    } else {
+      this._scopeUntilLoaded = scope;
     }
   }
 
@@ -75,11 +81,18 @@ export default class DeferredTree {
     // 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._parentUntilLoaded) {
+        // Now that the tree has been loaded, we can set its parent.
         if (!this._tree.parent) {
-          this._tree.parent = this._parent;
+          this._tree.parent = this._parentUntilLoaded;
+        }
+        this._parentUntilLoaded = null;
+      }
+      if (this._scopeUntilLoaded) {
+        if (!(/** @type {any} */ (this._tree).scope)) {
+          /** @type {any} */ (this._tree).scope = this._scopeUntilLoaded;
         }
-        this._parent = null;
+        this._scopeUntilLoaded = null;
       }
       return this._tree;
     });

package/src/FileTree.js

@@ -1,15 +1,14 @@
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 import {
   getRealmObjectPrototype,
   hiddenFileNames,
+  isPacked,
   sortNatural,
 } from "./utilities.js";
 
-const TypedArray = Object.getPrototypeOf(Uint8Array);
-
 /**
  * A file system tree via the Node file system API.
  *
@@ -128,29 +127,34 @@ export default class FileTree {
       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);
+    if (typeof value === "function") {
+      // Invoke function; write out the result.
+      value = await 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)) {
+    let packed = false;
+    if (value === null) {
+      // Treat null value as empty string; will create an empty file.
+      value = "";
+      packed = true;
+    } else if (isPacked(value)) {
+      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);
-      isWriteable = true;
+      packed = true;
     }
 
-    if (isWriteable) {
+    if (packed) {
+      // 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.
       await fs.mkdir(this.dirname, { recursive: true });
       // Write out the value as the contents of a file.

package/src/FunctionTree.js

@@ -41,8 +41,4 @@ export default class FunctionTree {
   async keys() {
     return this.domain;
   }
-
-  async unpack() {
-    return this.fn;
-  }
 }

package/src/MapTree.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 
 /**
  * A tree backed by a JavaScript `Map` object.

package/src/ObjectTree.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 import { getRealmObjectPrototype } from "./utilities.js";
 
 /**

package/src/SetTree.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 
 /**
  * A tree of Set objects.

package/src/SiteTree.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 import * as keysJson from "./keysJson.js";
 
 /**
@@ -152,11 +152,6 @@ export default class SiteTree {
     return Reflect.construct(this.constructor, [href]);
   }
 
-  async unpack() {
-    const response = await fetch(this.href);
-    return response.ok ? response.arrayBuffer() : undefined;
-  }
-
   get url() {
     return new URL(this.href);
   }

package/src/Tree.d.ts

@@ -10,8 +10,9 @@ export function has(AsyncTree: AsyncTree, key: any): Promise<boolean>;
 export function isAsyncMutableTree(obj: any): obj is AsyncMutableTree;
 export function isAsyncTree(obj: any): obj is AsyncTree;
 export function isKeyForSubtree(tree: AsyncTree, obj: any): Promise<boolean>;
+export function isTraversable(obj: any): boolean;
 export function isTreelike(obj: any): obj is Treelike;
-export function map(tree: Treelike, valueMap: ValueKeyFn): AsyncTree;
+export function map(tree: Treelike, valueFn: ValueKeyFn): AsyncTree;
 export function mapReduce(tree: Treelike, mapFn: ValueKeyFn|null, reduceFn: ReduceFn): Promise<any>;
 export function plain(tree: Treelike): Promise<PlainObject>;
 export function remove(AsyncTree: AsyncMutableTree, key: any): Promise<boolean>;

package/src/Tree.js

@@ -1,11 +1,16 @@
 import DeferredTree from "./DeferredTree.js";
 import FunctionTree from "./FunctionTree.js";
 import MapTree from "./MapTree.js";
-import ObjectTree from "./ObjectTree.js";
 import SetTree from "./SetTree.js";
+import { DeepObjectTree, ObjectTree } from "./internal.js";
 import mapTransform from "./transforms/map.js";
 import * as utilities from "./utilities.js";
-import { castArrayLike, isPlainObject } from "./utilities.js";
+import {
+  castArrayLike,
+  isPacked,
+  isPlainObject,
+  isUnpackable,
+} from "./utilities.js";
 
 /**
  * Helper functions for working with async trees
@@ -112,7 +117,9 @@ export function from(obj) {
     return new MapTree(obj);
   } else if (obj instanceof Set) {
     return new SetTree(obj);
-  } else if (obj && typeof obj === "object" && "unpack" in obj) {
+  } else if (isPlainObject(obj)) {
+    return new DeepObjectTree(obj);
+  } else if (isUnpackable(obj)) {
     async function AsyncFunction() {} // Sample async function
     return obj.unpack instanceof AsyncFunction.constructor
       ? // Async unpack: return a deferred tree.
@@ -163,23 +170,52 @@ export function isAsyncMutableTree(object) {
   return isAsyncTree(object) && typeof object.set === "function";
 }
 
+/**
+ * Return true if the indicated key produces or is expected to produce an
+ * async tree.
+ *
+ * This defers to the tree's own isKeyForSubtree method. If not found, this
+ * gets the value of that key and returns true if the value is an async
+ * tree.
+ */
+export async function isKeyForSubtree(tree, key) {
+  if (tree.isKeyForSubtree) {
+    return tree.isKeyForSubtree(key);
+  }
+  const value = await tree.get(key);
+  return isAsyncTree(value);
+}
+
+/**
+ * Return true if the object can be traversed via the `traverse()` method. The
+ * object must be either treelike or a packed object with an `unpack()` method.
+ *
+ * @param {any} object
+ */
+export function isTraversable(object) {
+  return (
+    isTreelike(object) ||
+    (isPacked(object) && /** @type {any} */ (object).unpack instanceof Function)
+  );
+}
+
 /**
  * Returns true if the indicated object can be directly treated as an
  * asynchronous tree. This includes:
  *
  * - An object that implements the AsyncTree interface (including
  *   AsyncTree instances)
- * - An object that implements the `unpack()` method
  * - A function
  * - An `Array` instance
  * - A `Map` instance
  * - A `Set` instance
  * - A plain object
  *
- * Note: the `from()` method accepts any JavaScript object, but `isTreeable`
+ * Note: the `from()` method accepts any JavaScript object, but `isTreelike`
  * returns `false` for an object that isn't one of the above types.
  *
  * @param {any} object
+ * @returns {obj is Treelike}
  */
 export function isTreelike(object) {
   return (
@@ -187,36 +223,19 @@ export function isTreelike(object) {
     object instanceof Function ||
     object instanceof Array ||
     object instanceof Set ||
-    object?.unpack instanceof Function ||
     isPlainObject(object)
   );
 }
 
-/**
- * Return true if the indicated key produces or is expected to produce an
- * async tree.
- *
- * This defers to the tree's own isKeyForSubtree method. If not found, this
- * gets the value of that key and returns true if the value is an async
- * tree.
- */
-export async function isKeyForSubtree(tree, key) {
-  if (tree.isKeyForSubtree) {
-    return tree.isKeyForSubtree(key);
-  }
-  const value = await tree.get(key);
-  return isAsyncTree(value);
-}
-
 /**
  * Return a new tree with deeply-mapped values of the original tree.
  *
  * @param {Treelike} treelike
- * @param {ValueKeyFn} valueMap
+ * @param {ValueKeyFn} valueFn
  */
-export function map(treelike, valueMap) {
+export function map(treelike, valueFn) {
   const tree = from(treelike);
-  return mapTransform({ deep: true, valueMap })(tree);
+  return mapTransform({ deep: true, value: valueFn })(tree);
 }
 
 /**
@@ -230,10 +249,10 @@ export function map(treelike, valueMap) {
  * reduceFn, which should consolidate those into a single result.
  *
  * @param {Treelike} treelike
- * @param {ValueKeyFn|null} valueMap
+ * @param {ValueKeyFn|null} valueFn
  * @param {ReduceFn} reduceFn
  */
-export async function mapReduce(treelike, valueMap, reduceFn) {
+export async function mapReduce(treelike, valueFn, reduceFn) {
   const tree = from(treelike);
 
   // We're going to fire off all the get requests in parallel, as quickly as
@@ -244,9 +263,9 @@ export async function mapReduce(treelike, valueMap, reduceFn) {
     tree.get(key).then((value) =>
       // If the value is a subtree, recurse.
       isAsyncTree(value)
-        ? mapReduce(value, valueMap, reduceFn)
-        : valueMap
-        ? valueMap(value, key, tree)
+        ? mapReduce(value, valueFn, reduceFn)
+        : valueFn
+        ? valueFn(value, key, tree)
         : value
     )
   );
@@ -364,24 +383,16 @@ export async function traverseOrThrow(treelike, ...keys) {
       throw new TraverseError(message, treelike, keys);
     }
 
-    // Special case: one key left that's an empty string
-    if (remainingKeys.length === 1 && remainingKeys[0] === "") {
-      // Unpack the value if it defines an `unpack` function, otherwise return
-      // the value itself.
-      return typeof value.unpack === "function" ? await value.unpack() : value;
-    }
-
-    // If the value is not a function or async tree already, but can be
-    // unpacked, unpack it.
-    if (
-      !(value instanceof Function) &&
-      !isAsyncTree(value) &&
-      value.unpack instanceof Function
-    ) {
+    // If the value is packed and can be unpacked, unpack it.
+    if (isUnpackable(value)) {
       value = await value.unpack();
     }
 
-    if (value instanceof Function) {
+    // Peek ahead: if there's only one key left and it's an empty string, return
+    // the value itself.
+    if (remainingKeys.length === 1 && remainingKeys[0] === "") {
+      return value;
+    } else if (value instanceof Function) {
       // Value is a function: call it with the remaining keys.
       const fn = value;
       // We'll take as many keys as the function's length, but at least one.

package/src/internal.js

@@ -0,0 +1,15 @@
+//
+// 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
+//
+
+export * as Tree from "./Tree.js";
+
+export { default as ObjectTree } from "./ObjectTree.js";
+
+export { default as DeepObjectTree } from "./DeepObjectTree.js";

package/src/keysJson.js

@@ -1,4 +1,4 @@
-import * as Tree from "./Tree.js";
+import { Tree } from "./internal.js";
 
 /**
  * The .keys.json file format lets a site expose the keys of a node in the site

package/src/operations/cache.js

@@ -1,4 +1,4 @@
-import { ObjectTree, Tree } from "@weborigami/async-tree";
+import { DeepObjectTree, Tree } from "../internal.js";
 
 /**
  * Caches values from a source tree in a second cache tree. If no second tree is
@@ -9,15 +9,19 @@ import { ObjectTree, Tree } from "@weborigami/async-tree";
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
  *
- * @param {AsyncTree} source
+ * @param {Treelike} sourceTreelike
  * @param {AsyncMutableTree} [cacheTree]
- * @param {AsyncTree} [filter]
+ * @param {Treelike} [filterTreelike]
  * @returns {AsyncTree & { description: string }}
  */
-export default function treeCache(source, cacheTree, filter) {
+export default function treeCache(sourceTreelike, cacheTree, filterTreelike) {
+  const source = Tree.from(sourceTreelike);
+  const filter = filterTreelike ? Tree.from(filterTreelike) : undefined;
+
   /** @type {AsyncMutableTree} */
-  const cache = cacheTree ?? new ObjectTree({});
+  const cache = cacheTree ?? new DeepObjectTree({});
   return {
     description: "cache",
 

package/src/operations/mergeDeep.js

@@ -1,4 +1,4 @@
-import * as Tree from "../Tree.js";
+import { Tree } from "../internal.js";
 
 /**
  * Return a tree that performs a deep merge of the given trees.

package/src/symbols.js

@@ -0,0 +1 @@
+export const parent = Symbol("parent");

package/src/transforms/{cachedKeyMaps.js → cachedKeyFunctions.js}

@@ -1,20 +1,20 @@
-import * as Tree from "../Tree.js";
+import { Tree } from "../internal.js";
 
 const treeToCaches = new WeakMap();
 
 /**
- * Given a keyMap, return a new keyMap and inverseKeyMap that cache the results of
- * the original keyMap.
+ * Given a key function, return a new key function and inverse key function that
+ * cache the results of the original.
  *
  * @typedef {import("../../index.ts").KeyFn} KeyFn
  *
- * @param {KeyFn} keyMap
+ * @param {KeyFn} keyFn
  * @param {boolean} [deep]
- * @returns {{ keyMap: KeyFn, inverseKeyMap: KeyFn }}
+ * @returns {{ key: KeyFn, inverseKey: KeyFn }}
  */
-export default function createCachedKeysTransform(keyMap, deep = false) {
+export default function createCachedKeysTransform(keyFn, deep = false) {
   return {
-    async inverseKeyMap(resultKey, tree) {
+    async inverseKey(resultKey, tree) {
       const caches = getCachesForTree(tree);
 
       // First check to see if we've already computed an source key for this
@@ -37,7 +37,7 @@ export default function createCachedKeysTransform(keyMap, deep = false) {
         if (deep && (await Tree.isKeyForSubtree(tree, sourceKey))) {
           computedResultKey = sourceKey;
         } else {
-          computedResultKey = await keyMap(sourceKey, tree);
+          computedResultKey = await keyFn(sourceKey, tree);
         }
 
         caches.sourceKeyToResultKey.set(sourceKey, computedResultKey);
@@ -52,7 +52,7 @@ export default function createCachedKeysTransform(keyMap, deep = false) {
       return undefined;
     },
 
-    async keyMap(sourceKey, tree) {
+    async key(sourceKey, tree) {
       const keyMaps = getCachesForTree(tree);
 
       // First check to see if we've already computed an result key for this
@@ -62,7 +62,7 @@ export default function createCachedKeysTransform(keyMap, deep = false) {
         return keyMaps.sourceKeyToResultKey.get(sourceKey);
       }
 
-      const resultKey = await keyMap(sourceKey, tree);
+      const resultKey = await keyFn(sourceKey, tree);
 
       // Cache the mappings from source key <-> result key for next time.
       keyMaps.sourceKeyToResultKey.set(sourceKey, resultKey);

package/src/transforms/groupBy.js

@@ -1,5 +1,4 @@
-import ObjectTree from "../ObjectTree.js";
-import * as Tree from "../Tree.js";
+import { DeepObjectTree, Tree } from "../internal.js";
 
 /**
  * Given a function that returns a grouping key for a value, returns a transform
@@ -11,7 +10,8 @@ export default function createGroupByTransform(groupKeyFn) {
   /**
    * @type {import("../../index.ts").TreeTransform}
    */
-  return async function groupByTransform(tree) {
+  return async function groupByTransform(treelike) {
+    const tree = Tree.from(treelike);
     const result = {};
     for (const key of await tree.keys()) {
       const value = await tree.get(key);
@@ -36,6 +36,6 @@ export default function createGroupByTransform(groupKeyFn) {
       }
     }
 
-    return new ObjectTree(result);
+    return new DeepObjectTree(result);
   };
 }