@weborigami/async-tree 0.0.59 → 0.0.60

package/main.js

@@ -21,6 +21,7 @@ export { default as group } from "./src/operations/group.js";
 export { default as groupFn } from "./src/operations/groupFn.js";
 export { default as map } from "./src/operations/map.js";
 export { default as merge } from "./src/operations/merge.js";
+export { default as scope } from "./src/operations/scope.js";
 export { default as sort } from "./src/operations/sort.js";
 export { default as take } from "./src/operations/take.js";
 export * as symbols from "./src/symbols.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.59",
+  "version": "0.0.60",
   "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.59"
+    "@weborigami/types": "0.0.60"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/DeferredTree.js

@@ -20,7 +20,6 @@ export default class DeferredTree {
     this.treePromise = null;
     this._tree = null;
     this._parentUntilLoaded = null;
-    this._scopeUntilLoaded = null;
   }
 
   async get(key) {
@@ -54,25 +53,6 @@ export default class DeferredTree {
     }
   }
 
-  // HACK: The concept of scope is defined in Origami, not at the AsyncTree
-  // level. If a DeferredTree is used to wrap an OrigamiTree, the inner
-  // OrigamiTree will have a `scope` but not a `parent`. If someone asks the
-  // outer deferrred tree for a scope, they'd otherwise get `undefined`, which
-  // is incorrect. As a workaround, we introduce a `scope` getter here that
-  // defers to the inner tree, but we need to find a way to avoid having to
-  // introduce the concept of scope here.
-  get scope() {
-    return /** @type {any} */ (this._tree)?.scope;
-  }
-  set scope(scope) {
-    // 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;
-    }
-  }
-
   async tree() {
     if (this._tree) {
       return this._tree;
@@ -82,18 +62,13 @@ export default class DeferredTree {
     this.treePromise ??= this.loadResult().then((treelike) => {
       this._tree = Tree.from(treelike);
       if (this._parentUntilLoaded) {
-        // Now that the tree has been loaded, we can set its parent.
+        // Now that the tree has been loaded, we can set its parent if it hasn't
+        // already been set.
         if (!this._tree.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._scopeUntilLoaded = null;
-      }
       return this._tree;
     });
 

package/src/operations/cache.js

@@ -68,7 +68,7 @@ export default function treeCache(sourceTreelike, cacheTree, filterTreelike) {
     },
 
     async keys() {
-      keys ??= source.keys();
+      keys ??= await source.keys();
       return keys;
     },
   };

package/src/operations/deepMerge.js

@@ -18,15 +18,28 @@ export default function deepMerge(...sources) {
 
       // Check trees for the indicated key in reverse order.
       for (let index = trees.length - 1; index >= 0; index--) {
-        const value = await trees[index].get(key);
+        const tree = trees[index];
+        const value = await tree.get(key);
         if (Tree.isAsyncTree(value)) {
+          if (value.parent === tree) {
+            // Merged tree acts as parent instead of the source tree.
+            value.parent = this;
+          }
           subtrees.unshift(value);
         } else if (value !== undefined) {
           return value;
         }
       }
 
-      return subtrees.length > 0 ? deepMerge(...subtrees) : undefined;
+      if (subtrees.length > 1) {
+        const merged = deepMerge(...subtrees);
+        merged.parent = this;
+        return merged;
+      } else if (subtrees.length === 1) {
+        return subtrees[0];
+      } else {
+        return undefined;
+      }
     },
 
     async isKeyForSubtree(key) {

package/src/operations/deepTakeFn.js

@@ -13,7 +13,7 @@ export default function deepTakeFn(count) {
   return async function deepTakeFn(treelike) {
     const tree = await Tree.from(treelike);
     const { values } = await traverse(tree, count);
-    return values;
+    return Tree.from(values);
   };
 }
 

package/src/operations/merge.js

@@ -11,19 +11,22 @@ import { Tree } from "../internal.js";
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @param {import("../../index.ts").Treelike[]} sources
- * @returns {AsyncTree & { description: string }}
+ * @returns {AsyncTree & { description: string, trees: AsyncTree[]}}
  */
 export default function merge(...sources) {
-  let trees = sources.map((treelike) => Tree.from(treelike));
-  let mergeParent;
   return {
     description: "merge",
 
     async get(key) {
       // Check trees for the indicated key in reverse order.
-      for (let index = trees.length - 1; index >= 0; index--) {
-        const value = await trees[index].get(key);
+      for (let index = this.trees.length - 1; index >= 0; index--) {
+        const tree = this.trees[index];
+        const value = await tree.get(key);
         if (value !== undefined) {
+          if (Tree.isAsyncTree(value) && value.parent === tree) {
+            // Merged tree acts as parent instead of the source tree.
+            value.parent = this;
+          }
           return value;
         }
       }
@@ -32,8 +35,8 @@ export default function merge(...sources) {
 
     async isKeyForSubtree(key) {
       // Check trees for the indicated key in reverse order.
-      for (let index = trees.length - 1; index >= 0; index--) {
-        if (await Tree.isKeyForSubtree(trees[index], key)) {
+      for (let index = this.trees.length - 1; index >= 0; index--) {
+        if (await Tree.isKeyForSubtree(this.trees[index], key)) {
           return true;
         }
       }
@@ -43,7 +46,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 trees) {
+      for (const tree of this.trees) {
         for (const key of await tree.keys()) {
           keys.add(key);
         }
@@ -51,18 +54,6 @@ export default function merge(...sources) {
       return keys;
     },
 
-    get parent() {
-      return mergeParent;
-    },
-    set parent(parent) {
-      mergeParent = parent;
-      trees = sources.map((treelike) => {
-        const tree = Tree.isAsyncTree(treelike)
-          ? Object.create(treelike)
-          : Tree.from(treelike);
-        tree.parent = parent;
-        return tree;
-      });
-    },
+    trees: sources.map((treelike) => Tree.from(treelike)),
   };
 }

package/src/operations/scope.js

@@ -0,0 +1,65 @@
+import { Tree } from "@weborigami/async-tree";
+
+/**
+ * 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
+ *
+ * @param {Treelike} treelike
+ * @returns {AsyncTree & {trees: AsyncTree[]}}
+ */
+export default function scope(treelike) {
+  const tree = Tree.from(treelike);
+
+  return {
+    // Starting with this tree, search up the parent hierarchy.
+    async get(key) {
+      /** @type {AsyncTree|null|undefined} */
+      let current = tree;
+      let value;
+      while (current) {
+        value = await current.get(key);
+        if (value !== undefined) {
+          break;
+        }
+        current = current.parent;
+      }
+      return value;
+    },
+
+    // Collect all keys for this tree and all parents
+    async keys() {
+      const keys = new Set();
+
+      /** @type {AsyncTree|null|undefined} */
+      let current = tree;
+      while (current) {
+        for (const key of await current.keys()) {
+          keys.add(key);
+        }
+        current = current.parent;
+      }
+
+      return keys;
+    },
+
+    // Collect all keys for this tree and all parents.
+    //
+    // This method exists for debugging purposes, as it's helpful to be able to
+    // quickly flatten and view the entire scope chain.
+    get trees() {
+      const result = [];
+
+      /** @type {AsyncTree|null|undefined} */
+      let current = tree;
+      while (current) {
+        result.push(current);
+        current = current.parent;
+      }
+
+      return result;
+    },
+  };
+}

package/src/transforms/regExpKeys.js

@@ -56,7 +56,9 @@ export default async function regExpKeys(treelike) {
     let value = await tree.get(key);
     if (Tree.isAsyncTree(value)) {
       value = regExpKeys(value);
-      value.parent = result;
+      if (!value.parent) {
+        value.parent = result;
+      }
     }
 
     map.set(regExp, value);

package/src/utilities.js

@@ -188,7 +188,8 @@ export async function pipeline(start, ...fns) {
  * If the input is stringlike, its text will be returned.
  *
  * If the input is a ArrayBuffer or typed array, it will be interpreted as UTF-8
- * text.
+ * text if it does not contain unprintable characters. If it does, it will be
+ * returned as a base64-encoded string.
  *
  * If the input has a custom class instance, its public properties will be
  * returned as a plain object.
@@ -213,6 +214,14 @@ export async function toPlainValue(input) {
     return Tree.plain(mapped);
   } else if (isStringLike(input)) {
     return toString(input);
+  } else if (input instanceof ArrayBuffer || input instanceof TypedArray) {
+    // Try to interpret the buffer as UTF-8 text, otherwise use base64.
+    const text = toString(input);
+    if (text !== null) {
+      return text;
+    } else {
+      return toBase64(input);
+    }
   } else {
     // Some other kind of class instance; return its public properties.
     const plain = {};
@@ -223,6 +232,10 @@ export async function toPlainValue(input) {
   }
 }
 
+function toBase64(object) {
+  return Buffer.from(object).toString("base64");
+}
+
 /**
  * Return a string form of the object, handling cases not generally handled by
  * the standard JavaScript `toString()` method:

package/test/DeepObjectTree.test.js

@@ -15,9 +15,11 @@ describe("DeepObjectTree", () => {
     const object = await tree.get("object");
     assert.equal(object instanceof DeepObjectTree, true);
     assert.deepEqual(await Tree.plain(object), { b: 2 });
+    assert.equal(object.parent, tree);
 
     const array = await tree.get("array");
     assert.equal(array instanceof DeepObjectTree, true);
     assert.deepEqual(await Tree.plain(array), [3]);
+    assert.equal(array.parent, tree);
   });
 });

package/test/operations/deepMerge.test.js

@@ -34,5 +34,9 @@ describe("mergeDeep", () => {
         f: 4,
       },
     });
+
+    // Parent of a subvalue is the merged tree
+    const a = await fixture.get("a");
+    assert.equal(a.parent, fixture);
   });
 });

package/test/operations/deepTakeFn.test.js

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
 import deepTakeFn from "../../src/operations/deepTakeFn.js";
 
 describe("deepTakeFn", () => {
@@ -16,6 +17,6 @@ describe("deepTakeFn", () => {
       g: 5,
     };
     const result = await deepTakeFn(4)(tree);
-    assert.deepEqual(result, [1, 2, 3, 4]);
+    assert.deepEqual(await Tree.plain(result), [1, 2, 3, 4]);
   });
 });

package/test/operations/merge.test.js

@@ -33,7 +33,12 @@ describe("merge", () => {
       },
     });
 
+    // Merge is shallow, and last tree wins, so `b/c` doesn't exist
     const c = await Tree.traverse(fixture, "b", "c");
     assert.equal(c, undefined);
+
+    // Parent of a subvalue is the merged tree
+    const b = await Tree.traverse(fixture, "b");
+    assert.equal(b.parent, fixture);
   });
 });

package/test/operations/scope.test.js

@@ -0,0 +1,25 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { ObjectTree } from "../../src/internal.js";
+import scope from "../../src/operations/scope.js";
+
+describe("scope", () => {
+  test("gets the first defined value from the scope trees", async () => {
+    const outer = new ObjectTree({
+      a: 1,
+      b: 2,
+    });
+    const inner = new ObjectTree({
+      a: 3,
+    });
+    inner.parent = outer;
+    const innerScope = scope(inner);
+    assert.deepEqual([...(await innerScope.keys())], ["a", "b"]);
+    // Inner tree has precedence
+    assert.equal(await innerScope.get("a"), 3);
+    // If tree doesn't have value, finds value from parent
+    assert.equal(await innerScope.get("b"), 2);
+    assert.equal(await innerScope.get("c"), undefined);
+    assert.deepEqual(innerScope.trees, [inner, outer]);
+  });
+});

package/test/utilities.test.js

@@ -50,6 +50,11 @@ describe("utilities", () => {
       await utilities.toPlainValue(new TextEncoder().encode("bytes")),
       "bytes"
     );
+    // ArrayBuffer with non-printable characters should be returned as base64
+    assert.equal(
+      await utilities.toPlainValue(new Uint8Array([1, 2, 3]).buffer),
+      "AQID"
+    );
     assert.equal(await utilities.toPlainValue(async () => "result"), "result");
     assert.deepEqual(await utilities.toPlainValue(new User("Alice")), {
       name: "Alice",