@weborigami/async-tree 0.0.61 → 0.0.63

package/index.ts

@@ -29,7 +29,7 @@ export type ReduceFn = (values: any[], keys: any[]) => Promise<any>;
 
 export type StringLike = string | HasString;
 
-type NativeTreelike = 
+export type NativeTreelike = 
   any[] |
   AsyncTree |
   Function | 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.61",
+  "version": "0.0.63",
   "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.61"
+    "@weborigami/types": "0.0.63"
   },
   "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.
@@ -50,7 +48,7 @@ export default class ObjectTree {
   }
 
   async isKeyForSubtree(key) {
-    const value = this.object[key];
+    const value = await this.object[key];
     return Tree.isAsyncTree(value);
   }
 

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;
@@ -13,7 +13,8 @@ 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, valueFn: ValueKeyFn): AsyncTree;
-export function mapReduce(tree: Treelike, mapFn: ValueKeyFn|null, reduceFn: ReduceFn): Promise<any>;
+export function mapReduce(tree: Treelike, mapFn: ValueKeyFn | null, reduceFn: ReduceFn): Promise<any>;
+export function paths(tree: Treelike, base: string): string[];
 export function plain(tree: Treelike): Promise<PlainObject>;
 export function remove(AsyncTree: AsyncMutableTree, key: any): Promise<boolean>;
 export function toFunction(tree: Treelike): Function;

package/src/Tree.js

@@ -103,32 +103,45 @@ 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);
+  } else if (
+    typeof object === "string" ||
+    typeof object === "number" ||
+    typeof object === "boolean"
+  ) {
+    // A primitive value; box it into an object and construct a tree.
+    const boxed = utilities.box(object);
+    return new ObjectTree(boxed);
   }
 
   throw new TypeError("Couldn't convert argument to an async tree");
@@ -149,25 +162,23 @@ export async function has(tree, key) {
 /**
  * Return true if the indicated object is an async tree.
  *
- * @param {any} object
+ * @param {any} obj
  * @returns {obj is AsyncTree}
  */
-export function isAsyncTree(object) {
-  return (
-    object &&
-    typeof object.get === "function" &&
-    typeof object.keys === "function"
-  );
+export function isAsyncTree(obj) {
+  return obj && typeof obj.get === "function" && typeof obj.keys === "function";
 }
 
 /**
  * Return true if the indicated object is an async mutable tree.
  *
- * @param {any} object
+ * @param {any} obj
  * @returns {obj is AsyncMutableTree}
  */
-export function isAsyncMutableTree(object) {
-  return isAsyncTree(object) && typeof object.set === "function";
+export function isAsyncMutableTree(obj) {
+  return (
+    isAsyncTree(obj) && typeof (/** @type {any} */ (obj).set) === "function"
+  );
 }
 
 /**
@@ -214,16 +225,16 @@ export function isTraversable(object) {
  * 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
+ * @param {any} obj
  * @returns {obj is Treelike}
  */
-export function isTreelike(object) {
+export function isTreelike(obj) {
   return (
-    isAsyncTree(object) ||
-    object instanceof Function ||
-    object instanceof Array ||
-    object instanceof Set ||
-    isPlainObject(object)
+    isAsyncTree(obj) ||
+    obj instanceof Function ||
+    obj instanceof Array ||
+    obj instanceof Set ||
+    isPlainObject(obj)
   );
 }
 
@@ -278,6 +289,27 @@ export async function mapReduce(treelike, valueFn, reduceFn) {
   return reduceFn(values, keys);
 }
 
+/**
+ * Returns slash-separated paths for all values in the tree.
+ *
+ * @param {Treelike} treelike
+ * @param {string} base
+ */
+export async function paths(treelike, base = "") {
+  const tree = from(treelike);
+  const result = [];
+  for (const key of await tree.keys()) {
+    const valuePath = base ? `${base}/${key}` : key;
+    const value = await tree.get(key);
+    if (await isAsyncTree(value)) {
+      const subPaths = await paths(value, valuePath);
+      result.push(...subPaths);
+    } else {
+      result.push(valuePath);
+    }
+  }
+  return result;
+}
 /**
  * Converts an asynchronous tree into a synchronous plain JavaScript object.
  *

package/src/operations/concat.js

@@ -7,7 +7,7 @@ import deepValuesIterator from "./deepValuesIterator.js";
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  *
  * @this {AsyncTree|null}
- * @param {import("@weborigami/async-tree").Treelike} treelike
+ * @param {import("../../index.ts").Treelike} treelike
  */
 export default async function concatTreeValues(treelike) {
   const strings = [];

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/operations/scope.js

@@ -1,11 +1,11 @@
-import { Tree } from "@weborigami/async-tree";
+import { Tree } from "../internal.js";
 
 /**
  * A tree's "scope" is the collection of everything in that tree and all of its
  * ancestors.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../index.ts").Treelike} Treelike
  *
  * @param {Treelike} treelike
  * @returns {AsyncTree & {trees: AsyncTree[]}}

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/transforms/sortFn.js

@@ -50,16 +50,14 @@ export default function sortFn(options) {
         const defaultCompare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
         const originalCompare = compare ?? defaultCompare;
         // Sort by the sort key.
-        const sortedTuples = tuples.toSorted((a, b) =>
-          originalCompare(a.sort, b.sort)
-        );
+        tuples.sort((a, b) => originalCompare(a.sort, b.sort));
         // Map back to the original keys.
-        const sorted = sortedTuples.map((pair) => pair.key);
+        const sorted = tuples.map((pair) => pair.key);
         return sorted;
       } else {
         // Use original keys as sort keys.
         // If compare is undefined, this uses default sort order.
-        return keys.toSorted(compare);
+        return keys.slice().sort(compare);
       }
     };
     return transformed;

package/src/utilities.d.ts

@@ -1,14 +1,17 @@
+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[];
-export function isPacked(object: any): object is Packed;
-export function isPlainObject(object: any): object is PlainObject;
-export function isUnpackable(object): object is { unpack: () => any };
-export function isStringLike(object: any): object is StringLike;
+export function isPacked(obj: any): obj is Packed;
+export function isPlainObject(obj: any): obj is PlainObject;
+export function isStringLike(obj: any): obj is StringLike;
+export function isUnpackable(obj): obj is { unpack: () => any };
 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.
@@ -51,16 +73,16 @@ export const hiddenFileNames = [".DS_Store"];
  * Return true if the object is in a packed form (or can be readily packed into
  * a form) that can be given to fs.writeFile or response.write().
  *
- * @param {any} object
- * @returns {object is import("../index.ts").Packed}
+ * @param {any} obj
+ * @returns {obj is import("../index.ts").Packed}
  */
-export function isPacked(object) {
+export function isPacked(obj) {
   return (
-    typeof object === "string" ||
-    object instanceof ArrayBuffer ||
-    object instanceof ReadableStream ||
-    object instanceof String ||
-    object instanceof TypedArray
+    typeof obj === "string" ||
+    obj instanceof ArrayBuffer ||
+    obj instanceof ReadableStream ||
+    obj instanceof String ||
+    obj instanceof TypedArray
   );
 }
 
@@ -71,23 +93,23 @@ export function isPacked(object) {
  * This function also considers object-like things with no prototype (like a
  * `Module`) as plain objects.
  *
- * @param {any} object
- * @returns {object is import("../index.ts").PlainObject}
+ * @param {any} obj
+ * @returns {obj is import("../index.ts").PlainObject}
  */
-export function isPlainObject(object) {
+export function isPlainObject(obj) {
   // From https://stackoverflow.com/q/51722354/76472
-  if (typeof object !== "object" || object === null) {
+  if (typeof obj !== "object" || obj === null) {
     return false;
   }
 
   // We treat object-like things with no prototype (like a Module) as plain
   // objects.
-  if (Object.getPrototypeOf(object) === null) {
+  if (Object.getPrototypeOf(obj) === null) {
     return true;
   }
 
   // Do we inherit directly from Object in this realm?
-  return Object.getPrototypeOf(object) === getRealmObjectPrototype(object);
+  return Object.getPrototypeOf(obj) === getRealmObjectPrototype(obj);
 }
 
 /**
@@ -108,15 +130,15 @@ export function isPrimitive(value) {
  * Return true if the object is a string or object with a non-trival `toString`
  * method.
  *
- * @param {any} object
+ * @param {any} obj
  * @returns {obj is import("../index.ts").StringLike}
  */
-export function isStringLike(object) {
-  if (typeof object === "string") {
+export function isStringLike(obj) {
+  if (typeof obj === "string") {
     return true;
-  } else if (object?.toString === undefined) {
+  } else if (obj?.toString === undefined) {
     return false;
-  } else if (object.toString === getRealmObjectPrototype(object)?.toString) {
+  } 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.
@@ -126,10 +148,9 @@ export function isStringLike(object) {
   }
 }
 
-export function isUnpackable(object) {
+export function isUnpackable(obj) {
   return (
-    isPacked(object) &&
-    typeof (/** @type {any} */ (object).unpack) === "function"
+    isPacked(obj) && typeof (/** @type {any} */ (obj).unpack) === "function"
   );
 }
 
@@ -170,6 +191,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 () => ({
@@ -108,6 +118,13 @@ describe("Tree", () => {
     });
   });
 
+  test("from() autoboxes primitive values", async () => {
+    const tree = Tree.from("Hello, world.");
+    const slice = await tree.get("slice");
+    const result = await slice(0, 5);
+    assert.equal(result, "Hello");
+  });
+
   test("has returns true if the key exists", async () => {
     const fixture = createFixture();
     assert.equal(await Tree.has(fixture, "Alice.md"), true);
@@ -198,6 +215,18 @@ describe("Tree", () => {
     assert.deepEqual(reduced, "1234");
   });
 
+  test("paths returns an array of paths to the values in the tree", async () => {
+    const tree = new DeepObjectTree({
+      a: 1,
+      b: 2,
+      c: {
+        d: 3,
+        e: 4,
+      },
+    });
+    assert.deepEqual(await Tree.paths(tree), ["a", "b", "c/d", "c/e"]);
+  });
+
   test("plain() produces a plain object version of a tree", async () => {
     const original = {
       a: 1,
@@ -232,6 +261,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 { ObjectTree } from "../src/internal.js";
+import * as symbols from "../src/symbols.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) {