@weborigami/async-tree 0.0.39 → 0.0.41

package/main.js

@@ -6,6 +6,7 @@ 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 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";

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "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.3",
+    "@types/node": "20.11.7",
     "typescript": "5.3.3"
   },
   "dependencies": {
-    "@weborigami/types": "*"
+    "@weborigami/types": "0.0.41"
   },
   "scripts": {
-    "test": "node --test",
+    "test": "node --test --test-reporter=spec",
     "typecheck": "tsc"
   }
 }

package/src/DeepObjectTree.js

@@ -0,0 +1,27 @@
+import ObjectTree from "./ObjectTree.js";
+import * as Tree from "./Tree.js";
+import { isPlainObject } from "./utilities.js";
+
+export default class DeepObjectTree extends ObjectTree {
+  async get(key) {
+    let value = await super.get(key);
+
+    const isPlain =
+      value instanceof Array ||
+      (isPlainObject(value) && !Tree.isAsyncTree(value));
+    if (isPlain) {
+      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];
+    return isPlainObject(value) || Tree.isAsyncTree(value);
+  }
+}

package/src/FunctionTree.js

@@ -23,7 +23,8 @@ export default class FunctionTree {
   async get(key) {
     const value =
       this.fn.length <= 1
-        ? // Function takes no arguments or only one argument: invoke
+        ? // Function takes no arguments, one argument, or a variable number of
+          // arguments: invoke it.
           await this.fn.call(null, key)
         : // Bind the key to the first parameter. Subsequent get calls will
           // eventually bind all parameters until only one remains. At that point,

package/src/MapTree.js

@@ -24,10 +24,6 @@ export default class MapTree {
   async get(key) {
     let value = this.map.get(key);
 
-    if (value instanceof Map) {
-      value = Reflect.construct(this.constructor, [value]);
-    }
-
     if (Tree.isAsyncTree(value) && !value.parent) {
       value.parent = this;
     }
@@ -37,7 +33,7 @@ export default class MapTree {
 
   async isKeyForSubtree(key) {
     const value = this.map.get(key);
-    return value instanceof Map || Tree.isAsyncTree(value);
+    return Tree.isAsyncTree(value);
   }
 
   async keys() {

package/src/ObjectTree.js

@@ -1,5 +1,5 @@
 import * as Tree from "./Tree.js";
-import { getRealmObjectPrototype, isPlainObject } from "./utilities.js";
+import { getRealmObjectPrototype } from "./utilities.js";
 
 /**
  * A tree defined by a plain object or array.
@@ -37,13 +37,6 @@ export default class ObjectTree {
 
     let value = this.object[key];
 
-    const isPlain =
-      value instanceof Array ||
-      (isPlainObject(value) && !Tree.isAsyncTree(value));
-    if (isPlain) {
-      value = Reflect.construct(this.constructor, [value]);
-    }
-
     if (Tree.isAsyncTree(value) && !value.parent) {
       value.parent = this;
     }
@@ -53,7 +46,7 @@ export default class ObjectTree {
 
   async isKeyForSubtree(key) {
     const value = this.object[key];
-    return isPlainObject(value) || Tree.isAsyncTree(value);
+    return Tree.isAsyncTree(value);
   }
 
   /**

package/src/SetTree.js

@@ -18,10 +18,6 @@ export default class SetTree {
   async get(key) {
     let value = this.values[key];
 
-    if (value instanceof Set) {
-      value = Reflect.construct(this.constructor, [value]);
-    }
-
     if (Tree.isAsyncTree(value) && !value.parent) {
       value.parent = this;
     }
@@ -31,7 +27,7 @@ export default class SetTree {
 
   async isKeyForSubtree(key) {
     const value = this.values[key];
-    return value instanceof Set || Tree.isAsyncTree(value);
+    return Tree.isAsyncTree(value);
   }
 
   async keys() {

package/src/Tree.js

@@ -18,6 +18,8 @@ import { castArrayLike, isPlainObject } from "./utilities.js";
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  */
 
+const treeModule = this;
+
 /**
  * Apply the key/values pairs from the source tree to the target tree.
  *
@@ -111,9 +113,12 @@ export function from(obj) {
   } else if (obj instanceof Set) {
     return new SetTree(obj);
   } else if (obj && typeof obj === "object" && "unpack" in obj) {
-    // Invoke unpack and convert the result to a tree.
-    let result = obj.unpack();
-    return result instanceof Promise ? new DeferredTree(result) : from(result);
+    async function AsyncFunction() {} // Sample async function
+    return obj.unpack instanceof AsyncFunction.constructor
+      ? // Async unpack: return a deferred tree.
+        new DeferredTree(obj.unpack)
+      : // Synchronous unpack: cast the result of unpack() to a tree.
+        from(obj.unpack());
   } else if (obj && typeof obj === "object") {
     // An instance of some class.
     return new ObjectTree(obj);
@@ -328,6 +333,7 @@ export async function traverse(treelike, ...keys) {
  * Return the value at the corresponding path of keys. Throw if any interior
  * step of the path doesn't lead to a result.
  *
+ * @this {AsyncTree|null|undefined}
  * @param {Treelike} treelike
  * @param  {...any} keys
  */
@@ -336,11 +342,15 @@ export async function traverseOrThrow(treelike, ...keys) {
   /** @type {any} */
   let value = treelike;
 
-  // Process each key in turn.
-  // If the value is ever undefined, short-circuit the traversal.
+  // If traversal operation was called with a `this` context, use that as the
+  // target for function calls.
+  const target = this === treeModule ? undefined : this;
+
+  // Process all the keys.
   const remainingKeys = keys.slice();
   while (remainingKeys.length > 0) {
     if (value === undefined) {
+      // Attempted to traverse an undefined value
       const keyStrings = keys.map((key) => String(key));
       throw new TraverseError(
         `Couldn't traverse the path: ${keyStrings.join("/")}`,
@@ -349,24 +359,40 @@ export async function traverseOrThrow(treelike, ...keys) {
       );
     }
 
-    // Get the next key.
-    const key = remainingKeys.shift();
-
-    // An empty string as the last key is a special case.
-    if (key === "" && remainingKeys.length === 0) {
+    // 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.
-      value = typeof value.unpack === "function" ? await value.unpack() : value;
-      continue;
+      return typeof value.unpack === "function" ? await value.unpack() : value;
     }
 
-    // Someone is trying to traverse the value, so they mean to treat it as a
-    // tree. If it's not already a tree, cast it to one.
-    const tree = from(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
+    ) {
+      value = await value.unpack();
+    }
 
-    // Get the value for the key.
-    value = await tree.get(key);
+    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.
+      let fnKeyCount = Math.max(fn.length, 1);
+      const args = remainingKeys.splice(0, fnKeyCount);
+      value = await fn.call(target, ...args);
+    } else {
+      // Value is some other treelike object: cast it to a tree.
+      const tree = from(value);
+      // Get the next key.
+      const key = remainingKeys.shift();
+      // Get the value for the key.
+      value = await tree.get(key);
+    }
   }
+
   return value;
 }
 

package/src/transforms/groupBy.js

@@ -26,6 +26,7 @@ export default function createGroupByTransform(groupKeyFn) {
         // A single value was returned
         groups = [groups];
       }
+      groups = Tree.from(groups);
 
       // Add the value to each group.
       for (const groupKey of await groups.keys()) {

package/test/DeepObjectTree.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import DeepObjectTree from "../src/DeepObjectTree.js";
+import * as Tree from "../src/Tree.js";
+
+describe("DeepObjectTree", () => {
+  test("returns an ObjectTree for value that's a plain sub-object or sub-array", async () => {
+    const tree = new DeepObjectTree({
+      a: 1,
+      object: {
+        b: 2,
+      },
+      array: [3],
+    });
+
+    const object = await tree.get("object");
+    assert.equal(object instanceof DeepObjectTree, true);
+    assert.deepEqual(await Tree.plain(object), { b: 2 });
+
+    const array = await tree.get("array");
+    assert.equal(array instanceof DeepObjectTree, true);
+    assert.deepEqual(await Tree.plain(array), [3]);
+  });
+});

package/test/ObjectTree.test.js

@@ -76,28 +76,13 @@ describe("ObjectTree", () => {
     assert.equal(await fixture.get("prop"), "Goodbye");
   });
 
-  test("creates an ObjectTree for subtrees", async () => {
-    const object = {
-      a: 1,
-      more: {
-        b: 2,
-      },
-    };
-    const fixture = new ObjectTree(object);
-    const more = await fixture.get("more");
-    assert.equal(more.constructor, ObjectTree);
-    const b = await more.get("b");
-    assert.equal(b, 2);
-  });
-
   test("sets parent on subtrees", async () => {
-    const object = {
+    const fixture = new ObjectTree({
       a: 1,
-      more: {
+      more: new ObjectTree({
         b: 2,
-      },
-    };
-    const fixture = new ObjectTree(object);
+      }),
+    });
     const more = await fixture.get("more");
     assert.equal(more.parent, fixture);
   });
@@ -105,13 +90,13 @@ describe("ObjectTree", () => {
   test("isKeyForSubtree() indicates which values are subtrees", async () => {
     const tree = new ObjectTree({
       a1: 1,
-      a2: {
+      a2: new ObjectTree({
         b1: 2,
-      },
+      }),
       a3: 3,
-      a4: {
+      a4: new ObjectTree({
         b2: 4,
-      },
+      }),
     });
     const keys = Array.from(await tree.keys());
     const subtrees = await Promise.all(
@@ -120,24 +105,6 @@ describe("ObjectTree", () => {
     assert.deepEqual(subtrees, [false, true, false, true]);
   });
 
-  test("returns an ObjectTree for value that's a plain sub-object or sub-array", async () => {
-    const tree = new ObjectTree({
-      a: 1,
-      object: {
-        b: 2,
-      },
-      array: [3],
-    });
-
-    const object = await tree.get("object");
-    assert.equal(object instanceof ObjectTree, true);
-    assert.deepEqual(await Tree.plain(object), { b: 2 });
-
-    const array = await tree.get("array");
-    assert.equal(array instanceof ObjectTree, true);
-    assert.deepEqual(await Tree.plain(array), [3]);
-  });
-
   test("returns an async tree value as is", async () => {
     const subtree = {
       async get(key) {},

package/test/SetTree.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import ObjectTree from "../src/ObjectTree.js";
 import SetTree from "../src/SetTree.js";
 
 describe("SetTree", () => {
@@ -24,7 +25,7 @@ describe("SetTree", () => {
 
   test("sets parent on subtrees", async () => {
     const set = new Set();
-    set.add(new Set("a"));
+    set.add(new ObjectTree({}));
     const fixture = new SetTree(set);
     const subtree = await fixture.get(0);
     assert.equal(subtree.parent, fixture);

package/test/Tree.test.js

@@ -1,12 +1,13 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { DeepObjectTree } from "../main.js";
 import MapTree from "../src/MapTree.js";
 import ObjectTree from "../src/ObjectTree.js";
 import * as Tree from "../src/Tree.js";
 
 describe("Tree", () => {
   test("assign applies one tree to another", async () => {
-    const target = new ObjectTree({
+    const target = new DeepObjectTree({
       a: 1,
       b: 2,
       more: {
@@ -14,7 +15,7 @@ describe("Tree", () => {
       },
     });
 
-    const source = {
+    const source = new DeepObjectTree({
       a: 4, // Overwrite existing value
       b: undefined, // Delete
       c: 5, // Add
@@ -26,7 +27,7 @@ describe("Tree", () => {
       extra: {
         f: 7,
       },
-    };
+    });
 
     // Apply changes.
     const result = await Tree.assign(target, source);
@@ -165,7 +166,7 @@ describe("Tree", () => {
   });
 
   test("isKeyForSubtree() returns true if the key is for a subtree", async () => {
-    const tree = new ObjectTree({
+    const tree = new DeepObjectTree({
       a: 1,
       more: {
         b: 2,
@@ -176,12 +177,12 @@ describe("Tree", () => {
   });
 
   test("map() maps values", async () => {
-    const tree = {
+    const tree = new DeepObjectTree({
       a: "Alice",
       more: {
         b: "Bob",
       },
-    };
+    });
     const mapped = Tree.map(tree, (value) => value.toUpperCase());
     assert.deepEqual(await Tree.plain(mapped), {
       a: "ALICE",
@@ -192,14 +193,14 @@ describe("Tree", () => {
   });
 
   test("mapReduce() can map values and reduce them", async () => {
-    const tree = {
+    const tree = new DeepObjectTree({
       a: 1,
       b: 2,
       more: {
         c: 3,
       },
       d: 4,
-    };
+    });
     const reduced = await Tree.mapReduce(
       tree,
       (value) => value,
@@ -284,6 +285,13 @@ describe("Tree", () => {
     );
   });
 
+  test("traverse() a function with fixed number of arguments", async () => {
+    const tree = (a, b) => ({
+      c: "Result",
+    });
+    assert.equal(await Tree.traverse(tree, "a", "b", "c"), "Result");
+  });
+
   test("traverse() from one tree into another", async () => {
     const tree = new ObjectTree({
       a: {
@@ -297,15 +305,13 @@ describe("Tree", () => {
   });
 
   test("traversing a final empty string can unpack the last value", async () => {
-    class Unpackable {
-      unpack() {
-        return "Content";
-      }
-    }
-    const unpackable = new Unpackable();
-    const tree = new ObjectTree({
-      unpackable,
-    });
+    const tree = {
+      unpackable: {
+        unpack() {
+          return "Content";
+        },
+      },
+    };
     const result = await Tree.traverse(tree, "unpackable", "");
     assert.equal(result, "Content");
   });

package/test/operations/mergeDeep.test.js

@@ -1,12 +1,13 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import DeepObjectTree from "../../src/DeepObjectTree.js";
 import * as Tree from "../../src/Tree.js";
 import mergeDeep from "../../src/operations/mergeDeep.js";
 
 describe("mergeDeep", () => {
   test("can merge deep", async () => {
     const fixture = mergeDeep(
-      Tree.from({
+      new DeepObjectTree({
         a: {
           b: 1,
           c: {
@@ -14,7 +15,7 @@ describe("mergeDeep", () => {
           },
         },
       }),
-      Tree.from({
+      new DeepObjectTree({
         a: {
           b: 0, // Will be obscured by `b` above
           c: {

package/test/transforms/groupBy.test.js

@@ -12,9 +12,7 @@ describe("groupBy transform", () => {
       { name: "Work Sans", tags: ["Grotesque", "Sans Serif"] },
     ];
     const tree = Tree.from(fonts);
-    const grouped = await groupBy((value, key, tree) => value.get("tags"))(
-      tree
-    );
+    const grouped = await groupBy((value, key, tree) => value.tags)(tree);
     assert.deepEqual(await Tree.plain(grouped), {
       Geometric: [{ name: "Albert Sans", tags: ["Geometric", "Sans Serif"] }],
       Grotesque: [{ name: "Work Sans", tags: ["Grotesque", "Sans Serif"] }],

package/test/transforms/map.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import DeepObjectTree from "../../src/DeepObjectTree.js";
 import FunctionTree from "../../src/FunctionTree.js";
 import ObjectTree from "../../src/ObjectTree.js";
 import * as Tree from "../../src/Tree.js";
@@ -125,7 +126,7 @@ describe("map", () => {
   });
 
   test("deep maps values", async () => {
-    const tree = new ObjectTree({
+    const tree = new DeepObjectTree({
       a: "letter a",
       more: {
         b: "letter b",
@@ -145,7 +146,7 @@ describe("map", () => {
   });
 
   test("deep maps leaf keys", async () => {
-    const tree = new ObjectTree({
+    const tree = new DeepObjectTree({
       a: "letter a",
       more: {
         b: "letter b",
@@ -166,7 +167,7 @@ describe("map", () => {
   });
 
   test("deep maps leaf keys and values", async () => {
-    const tree = new ObjectTree({
+    const tree = new DeepObjectTree({
       a: "letter a",
       more: {
         b: "letter b",

package/test/transforms/regExpKeys.test.js

@@ -1,12 +1,13 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import DeepObjectTree from "../../src/DeepObjectTree.js";
 import * as Tree from "../../src/Tree.js";
 import regExpKeys from "../../src/transforms/regExpKeys.js";
 
 describe("regExpKeys", () => {
   test("matches keys using regular expressions", async () => {
     const fixture = await regExpKeys(
-      Tree.from({
+      new DeepObjectTree({
         a: true,
         "b.*": true,
         c: {