@weborigami/async-tree 0.0.60 → 0.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.60",
+  "version": "0.0.62",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
@@ -11,7 +11,7 @@
     "typescript": "5.5.3"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.60"
+    "@weborigami/types": "0.0.62"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/BrowserFileTree.js

@@ -1,5 +1,10 @@
 import { Tree } from "./internal.js";
-import { hiddenFileNames, isStringLike, naturalOrder } from "./utilities.js";
+import {
+  hiddenFileNames,
+  isStringLike,
+  naturalOrder,
+  setParent,
+} from "./utilities.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
@@ -34,7 +39,9 @@ export default class BrowserFileTree {
     // Try the key as a subfolder name.
     try {
       const subfolderHandle = await directory.getDirectoryHandle(key);
-      return Reflect.construct(this.constructor, [subfolderHandle]);
+      const value = Reflect.construct(this.constructor, [subfolderHandle]);
+      setParent(value, this);
+      return value;
     } catch (error) {
       if (
         !(
@@ -50,7 +57,9 @@ export default class BrowserFileTree {
     try {
       const fileHandle = await directory.getFileHandle(key);
       const file = await fileHandle.getFile();
-      return file.arrayBuffer();
+      const buffer = file.arrayBuffer();
+      setParent(buffer, this);
+      return buffer;
     } catch (error) {
       if (!(error instanceof DOMException && error.name === "NotFoundError")) {
         throw error;

package/src/DeepObjectTree.js

@@ -12,15 +12,11 @@ export default class DeepObjectTree extends ObjectTree {
       value = Reflect.construct(this.constructor, [value]);
     }
 
-    if (Tree.isAsyncTree(value) && !value.parent) {
-      value.parent = this;
-    }
-
     return value;
   }
 
   async isKeyForSubtree(key) {
-    const value = this.object[key];
+    const value = await this.object[key];
     return isPlainObject(value) || Tree.isAsyncTree(value);
   }
 }

package/src/FileTree.js

@@ -8,6 +8,7 @@ import {
   isPacked,
   isPlainObject,
   naturalOrder,
+  setParent,
 } from "./utilities.js";
 
 /**
@@ -65,16 +66,18 @@ export default class FileTree {
       throw error;
     }
 
+    let value;
     if (stats.isDirectory()) {
       // Return subdirectory as a tree
-      const subtree = Reflect.construct(this.constructor, [filePath]);
-      subtree.parent = this;
-      return subtree;
+      value = Reflect.construct(this.constructor, [filePath]);
     } else {
       // Return file contents as a standard Uint8Array.
       const buffer = await fs.readFile(filePath);
-      return Uint8Array.from(buffer);
+      value = Uint8Array.from(buffer);
     }
+
+    setParent(value, this);
+    return value;
   }
 
   async isKeyForSubtree(key) {

package/src/FunctionTree.js

@@ -1,3 +1,5 @@
+import { setParent } from "./utilities.js";
+
 /**
  * A tree defined by a function and an optional domain.
  *
@@ -30,7 +32,7 @@ export default class FunctionTree {
           // 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)]);
-
+    setParent(value, this);
     return value;
   }
 

package/src/MapTree.js

@@ -1,4 +1,5 @@
 import { Tree } from "./internal.js";
+import { setParent } from "./utilities.js";
 
 /**
  * A tree backed by a JavaScript `Map` object.
@@ -22,12 +23,8 @@ export default class MapTree {
   }
 
   async get(key) {
-    let value = this.map.get(key);
-
-    if (Tree.isAsyncTree(value) && !value.parent) {
-      value.parent = this;
-    }
-
+    const value = this.map.get(key);
+    setParent(value, this);
     return value;
   }
 

package/src/ObjectTree.js

@@ -1,5 +1,6 @@
 import { Tree } from "./internal.js";
-import { getRealmObjectPrototype } from "./utilities.js";
+import * as symbols from "./symbols.js";
+import { getRealmObjectPrototype, setParent } from "./utilities.js";
 
 /**
  * A tree defined by a plain object or array.
@@ -15,7 +16,7 @@ export default class ObjectTree {
    */
   constructor(object) {
     this.object = object;
-    this.parent = null;
+    this.parent = object[symbols.parent] ?? null;
   }
 
   /**
@@ -35,11 +36,8 @@ export default class ObjectTree {
       return undefined;
     }
 
-    let value = this.object[key];
-
-    if (Tree.isAsyncTree(value) && !value.parent) {
-      value.parent = this;
-    }
+    let value = await this.object[key];
+    setParent(value, this);
 
     if (typeof value === "function" && !Object.hasOwn(this.object, key)) {
       // Value is an inherited method; bind it to the object.

package/src/SetTree.js

@@ -1,4 +1,5 @@
 import { Tree } from "./internal.js";
+import { setParent } from "./utilities.js";
 
 /**
  * A tree of Set objects.
@@ -16,12 +17,8 @@ export default class SetTree {
   }
 
   async get(key) {
-    let value = this.values[key];
-
-    if (Tree.isAsyncTree(value) && !value.parent) {
-      value.parent = this;
-    }
-
+    const value = this.values[key];
+    setParent(value, this);
     return value;
   }
 

package/src/SiteTree.js

@@ -1,5 +1,6 @@
 import { Tree } from "./internal.js";
 import * as keysJson from "./keysJson.js";
+import { setParent } from "./utilities.js";
 
 /**
  * A tree of values obtained via HTTP/HTTPS calls. These values will be strings
@@ -44,7 +45,9 @@ export default class SiteTree {
     // If the (possibly adjusted) route ends with a slash and the site is an
     // explorable site, we return a tree for the indicated route.
     if (href.endsWith("/") && (await this.hasKeysJson())) {
-      return Reflect.construct(this.constructor, [href]);
+      const value = Reflect.construct(this.constructor, [href]);
+      setParent(value, this);
+      return value;
     }
 
     // Fetch the data at the given route.
@@ -67,9 +70,13 @@ export default class SiteTree {
     }
 
     const mediaType = response.headers?.get("Content-Type");
-    return SiteTree.mediaTypeIsText(mediaType)
-      ? response.text()
-      : response.arrayBuffer();
+    if (SiteTree.mediaTypeIsText(mediaType)) {
+      return response.text();
+    } else {
+      const buffer = response.arrayBuffer();
+      setParent(buffer, this);
+      return buffer;
+    }
   }
 
   async getKeyDictionary() {

package/src/Tree.d.ts

@@ -5,7 +5,7 @@ export function assign(target: Treelike, source: Treelike): Promise<AsyncTree>;
 export function clear(AsyncTree: AsyncMutableTree): Promise<void>;
 export function entries(AsyncTree: AsyncTree): Promise<IterableIterator<any>>;
 export function forEach(AsyncTree: AsyncTree, callbackfn: (value: any, key: any) => Promise<void>): Promise<void>;
-export function from(obj: any): AsyncTree;
+export function from(obj: any, options?: { deep: boolean }): AsyncTree;
 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;

package/src/Tree.js

@@ -103,32 +103,37 @@ export async function forEach(tree, callbackFn) {
 /**
  * Attempts to cast the indicated object to an async tree.
  *
- * @param {Treelike | Object} obj
+ * If the object is a plain object, it will be converted to an ObjectTree. The
+ * optional `deep` option can be set to `true` to convert a plain object to a
+ * DeepObjectTree.
+ *
+ * @param {Treelike | Object} object
+ * @param {{ deep?: true }} [options]
  * @returns {AsyncTree}
  */
-export function from(obj) {
-  if (isAsyncTree(obj)) {
+export function from(object, options = {}) {
+  if (isAsyncTree(object)) {
     // Argument already supports the tree interface.
     // @ts-ignore
-    return obj;
-  } else if (typeof obj === "function") {
-    return new FunctionTree(obj);
-  } else if (obj instanceof Map) {
-    return new MapTree(obj);
-  } else if (obj instanceof Set) {
-    return new SetTree(obj);
-  } else if (isPlainObject(obj)) {
-    return new DeepObjectTree(obj);
-  } else if (isUnpackable(obj)) {
+    return object;
+  } else if (typeof object === "function") {
+    return new FunctionTree(object);
+  } else if (object instanceof Map) {
+    return new MapTree(object);
+  } else if (object instanceof Set) {
+    return new SetTree(object);
+  } else if (isPlainObject(object) || object instanceof Array) {
+    return options.deep ? new DeepObjectTree(object) : new ObjectTree(object);
+  } else if (isUnpackable(object)) {
     async function AsyncFunction() {} // Sample async function
-    return obj.unpack instanceof AsyncFunction.constructor
+    return object.unpack instanceof AsyncFunction.constructor
       ? // Async unpack: return a deferred tree.
-        new DeferredTree(obj.unpack)
+        new DeferredTree(object.unpack)
       : // Synchronous unpack: cast the result of unpack() to a tree.
-        from(obj.unpack());
-  } else if (obj && typeof obj === "object") {
+        from(object.unpack());
+  } else if (object && typeof object === "object") {
     // An instance of some class.
-    return new ObjectTree(obj);
+    return new ObjectTree(object);
   }
 
   throw new TypeError("Couldn't convert argument to an async tree");

package/src/operations/deepMerge.js

@@ -8,7 +8,7 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree & { description: string }}
  */
 export default function deepMerge(...sources) {
-  let trees = sources.map((treelike) => Tree.from(treelike));
+  let trees = sources.map((treelike) => Tree.from(treelike, { deep: true }));
   let mergeParent;
   return {
     description: "deepMerge",

package/src/operations/deepTakeFn.js

@@ -11,7 +11,7 @@ export default function deepTakeFn(count) {
    * @param {import("../../index.ts").Treelike} treelike
    */
   return async function deepTakeFn(treelike) {
-    const tree = await Tree.from(treelike);
+    const tree = await Tree.from(treelike, { deep: true });
     const { values } = await traverse(tree, count);
     return Tree.from(values);
   };

package/src/operations/deepValuesIterator.js

@@ -14,7 +14,7 @@ export default async function* deepValuesIterator(
   treelike,
   options = { expand: false }
 ) {
-  const tree = Tree.from(treelike);
+  const tree = Tree.from(treelike, { deep: true });
   for (const key of await tree.keys()) {
     let value = await tree.get(key);
 

package/src/operations/merge.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import * as symbols from "../symbols.js";
 
 /**
  * Return a tree that performs a shallow merge of the given trees.
@@ -14,18 +15,24 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree & { description: string, trees: AsyncTree[]}}
  */
 export default function merge(...sources) {
+  const trees = sources.map((treelike) => Tree.from(treelike));
   return {
     description: "merge",
 
     async get(key) {
       // Check trees for the indicated key in reverse order.
-      for (let index = this.trees.length - 1; index >= 0; index--) {
-        const tree = this.trees[index];
+      for (let index = trees.length - 1; index >= 0; index--) {
+        const tree = trees[index];
         const value = await tree.get(key);
         if (value !== undefined) {
+          // Merged tree acts as parent instead of the source tree.
           if (Tree.isAsyncTree(value) && value.parent === tree) {
-            // Merged tree acts as parent instead of the source tree.
             value.parent = this;
+          } else if (
+            typeof value === "object" &&
+            value?.[symbols.parent] === tree
+          ) {
+            value[symbols.parent] = this;
           }
           return value;
         }
@@ -35,8 +42,8 @@ export default function merge(...sources) {
 
     async isKeyForSubtree(key) {
       // Check trees for the indicated key in reverse order.
-      for (let index = this.trees.length - 1; index >= 0; index--) {
-        if (await Tree.isKeyForSubtree(this.trees[index], key)) {
+      for (let index = trees.length - 1; index >= 0; index--) {
+        if (await Tree.isKeyForSubtree(trees[index], key)) {
           return true;
         }
       }
@@ -46,7 +53,7 @@ export default function merge(...sources) {
     async keys() {
       const keys = new Set();
       // Collect keys in the order the trees were provided.
-      for (const tree of this.trees) {
+      for (const tree of trees) {
         for (const key of await tree.keys()) {
           keys.add(key);
         }
@@ -54,6 +61,8 @@ export default function merge(...sources) {
       return keys;
     },
 
-    trees: sources.map((treelike) => Tree.from(treelike)),
+    get trees() {
+      return trees;
+    },
   };
 }

package/src/transforms/mapFn.js

@@ -1,5 +1,4 @@
-import { ObjectTree, Tree } from "../internal.js";
-import { isPlainObject } from "../utilities.js";
+import { Tree } from "../internal.js";
 
 /**
  * Return a transform function that maps the keys and/or values of a tree.
@@ -47,10 +46,7 @@ export default function createMapTransform(options = {}) {
    * @type {import("../../index.ts").TreeTransform}
    */
   return function map(treelike) {
-    const tree =
-      !deep && isPlainObject(treelike) && !Tree.isAsyncTree(treelike)
-        ? new ObjectTree(treelike)
-        : Tree.from(treelike);
+    const tree = Tree.from(treelike, { deep });
 
     // The transformed tree is actually an extension of the original tree's
     // prototype chain. This allows the transformed tree to inherit any

package/src/utilities.d.ts

@@ -1,5 +1,7 @@
+import { AsyncTree } from "@weborigami/types";
 import { Packed, PlainObject, StringLike } from "../index.ts";
 
+export function box(value: any): any;
 export function castArrayLike(object: any): any;
 export function getRealmObjectPrototype(object: any): any;
 export const hiddenFileNames: string[];
@@ -10,5 +12,6 @@ export function isStringLike(object: any): object is StringLike;
 export function keysFromPath(path: string): string[];
 export const naturalOrder: (a: string, b: string) => number;
 export function pipeline(start: any, ...functions: Function[]): Promise<any>;
+export function setParent(child: any, parent: AsyncTree): void;
 export function toPlainValue(object: any): Promise<any>;
-export function toString(object: any): string;
+export function toString(object: any): string;

package/src/utilities.js

@@ -1,8 +1,30 @@
 import { Tree } from "./internal.js";
+import * as symbols from "./symbols.js";
 
 const textDecoder = new TextDecoder();
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
+/**
+ * Return the value as an object. If the value is already an object it will be
+ * returned as is. If the value is a primitive, it will be wrapped in an object:
+ * a string will be wrapped in a String object, a number will be wrapped in a
+ * Number object, and a boolean will be wrapped in a Boolean object.
+ *
+ * @param {any} value
+ */
+export function box(value) {
+  switch (typeof value) {
+    case "string":
+      return new String(value);
+    case "number":
+      return new Number(value);
+    case "boolean":
+      return new Boolean(value);
+    default:
+      return value;
+  }
+}
+
 /**
  * If the given plain object has only sequential integer keys, return it as an
  * array. Otherwise return it as is.
@@ -170,6 +192,35 @@ export async function pipeline(start, ...fns) {
   return fns.reduce(async (acc, fn) => fn(await acc), start);
 }
 
+/**
+ * If the child object doesn't have a parent yet, set it to the indicated
+ * parent. If the child is an AsyncTree, set the `parent` property. Otherwise,
+ * set the `symbols.parent` property.
+ *
+ * @param {*} child
+ * @param {*} parent
+ */
+export function setParent(child, parent) {
+  if (Tree.isAsyncTree(child)) {
+    // Value is a subtree; set its parent to this tree.
+    if (!child.parent) {
+      child.parent = parent;
+    }
+  } else if (Object.isExtensible(child) && !child[symbols.parent]) {
+    // Add parent reference as a symbol to avoid polluting the object. This
+    // reference will be used if the object is later used as a tree. We set
+    // `enumerable` to false even thought this makes no practical difference
+    // (symbols are never enumerated) because it can provide a hint in the
+    // debugger that the property is for internal use.
+    Object.defineProperty(child, symbols.parent, {
+      configurable: true,
+      enumerable: false,
+      value: parent,
+      writable: true,
+    });
+  }
+}
+
 /**
  * Convert the given input to the plainest possible JavaScript value. This
  * helper is intended for functions that want to accept an argument from the ori

package/test/ObjectTree.test.js

@@ -1,6 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { ObjectTree, Tree } from "../src/internal.js";
+import * as symbols from "../src/symbols.js";
 
 describe("ObjectTree", () => {
   test("can get the keys of the tree", async () => {
@@ -76,6 +77,14 @@ describe("ObjectTree", () => {
     assert.equal(await fixture.get("prop"), "Goodbye");
   });
 
+  test("sets parent symbol on subobjects", async () => {
+    const fixture = new ObjectTree({
+      sub: {},
+    });
+    const sub = await fixture.get("sub");
+    assert.equal(sub[symbols.parent], fixture);
+  });
+
   test("sets parent on subtrees", async () => {
     const fixture = new ObjectTree({
       a: 1,

package/test/Tree.test.js

@@ -97,6 +97,16 @@ describe("Tree", () => {
     });
   });
 
+  test("from returns a deep object tree if deep option is true", async () => {
+    const obj = {
+      sub: {
+        a: 1,
+      },
+    };
+    const tree = Tree.from(obj, { deep: true });
+    assert(tree instanceof DeepObjectTree);
+  });
+
   test("from() creates a deferred tree if unpack() returns a promise", async () => {
     const obj = new String();
     /** @type {any} */ (obj).unpack = async () => ({
@@ -232,6 +242,15 @@ describe("Tree", () => {
     assert.deepEqual(plain, original);
   });
 
+  test("plain() awaits async properties", async () => {
+    const object = {
+      get name() {
+        return Promise.resolve("Alice");
+      },
+    };
+    assert.deepEqual(await Tree.plain(object), { name: "Alice" });
+  });
+
   test("remove method removes a value", async () => {
     const fixture = createFixture();
     await Tree.remove(fixture, "Alice.md");

package/test/operations/deepValues.test.js

@@ -19,4 +19,10 @@ describe("deepValues", () => {
     const values = await deepValues(tree);
     assert.deepEqual(values, [1, 2, 3, 4]);
   });
+
+  test("returns in-order array of values in nested arrays", async () => {
+    const tree = [1, [2, 3], 4];
+    const values = await deepValues(tree);
+    assert.deepEqual(values, [1, 2, 3, 4]);
+  });
 });

package/test/operations/merge.test.js

@@ -2,6 +2,7 @@ import assert from "node:assert";
 import { describe, test } from "node:test";
 import { Tree } from "../../src/internal.js";
 import merge from "../../src/operations/merge.js";
+import * as symbols from "../../src/symbols.js";
 
 describe("merge", () => {
   test("performs a shallow merge", async () => {
@@ -38,7 +39,7 @@ describe("merge", () => {
     assert.equal(c, undefined);
 
     // Parent of a subvalue is the merged tree
-    const b = await Tree.traverse(fixture, "b");
-    assert.equal(b.parent, fixture);
+    const b = await fixture.get("b");
+    assert.equal(b[symbols.parent], fixture);
   });
 });

package/test/utilities.test.js

@@ -1,8 +1,31 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { symbols } from "../main.js";
+import { ObjectTree } from "../src/internal.js";
 import * as utilities from "../src/utilities.js";
 
 describe("utilities", () => {
+  test("box returns a boxed value", () => {
+    const string = "string";
+    const stringObject = utilities.box(string);
+    assert(stringObject instanceof String);
+    assert.equal(stringObject, string);
+
+    const number = 1;
+    const numberObject = utilities.box(number);
+    assert(numberObject instanceof Number);
+    assert.equal(numberObject, number);
+
+    const boolean = true;
+    const booleanObject = utilities.box(boolean);
+    assert(booleanObject instanceof Boolean);
+    assert.equal(booleanObject, boolean);
+
+    const object = {};
+    const boxedObject = utilities.box(object);
+    assert.equal(boxedObject, object);
+  });
+
   test("getRealmObjectPrototype returns the object's root prototype", () => {
     const object = {};
     const proto = utilities.getRealmObjectPrototype(object);
@@ -36,6 +59,33 @@ describe("utilities", () => {
     assert.equal(result, 16);
   });
 
+  test("setParent sets a child's parent", () => {
+    const parent = new ObjectTree({});
+
+    // Set [symbols.parent] on a plain object.
+    const object = {};
+    utilities.setParent(object, parent);
+    assert.equal(object[symbols.parent], parent);
+
+    // Leave [symbols.parent] alone if it's already set.
+    const childWithParent = {
+      [symbols.parent]: "parent",
+    };
+    utilities.setParent(childWithParent, parent);
+    assert.equal(childWithParent[symbols.parent], "parent");
+
+    // Set `parent` on a tree.
+    const tree = new ObjectTree({});
+    utilities.setParent(tree, parent);
+    assert.equal(tree.parent, parent);
+
+    // Leave `parent` alone if it's already set.
+    const treeWithParent = new ObjectTree({});
+    treeWithParent.parent = "parent";
+    utilities.setParent(treeWithParent, parent);
+    assert.equal(treeWithParent.parent, "parent");
+  });
+
   test("toPlainValue returns the plainest representation of an object", async () => {
     class User {
       constructor(name) {