@weborigami/async-tree 0.5.8 → 0.6.1

package/src/utilities/setParent.js

@@ -1,21 +1,21 @@
-import isAsyncTree from "../operations/isAsyncTree.js";
+import isMap from "../operations/isMap.js";
 import * as symbols from "../symbols.js";
 
 /**
  * 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,
+ * parent. If the child is a map, set the `parent` property. Otherwise,
  * set the `symbols.parent` property.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
  *
  * @param {*} child
- * @param {AsyncTree|null} parent
+ * @param {SyncOrAsyncMap|null} parent
  */
 export default function setParent(child, parent) {
-  if (isAsyncTree(child)) {
+  if (isMap(child)) {
     // Value is a subtree; set its parent to this tree.
-    if (!child.parent) {
-      child.parent = parent;
+    if ("parent" in child && !child.parent) {
+      /** @type {any} */ (child).parent = parent;
     }
   } else if (Object.isExtensible(child) && !child[symbols.parent]) {
     try {

package/src/utilities/toFunction.js

@@ -1,5 +1,5 @@
 import from from "../operations/from.js";
-import isTreelike from "../operations/isTreelike.js";
+import isMaplike from "../operations/isMaplike.js";
 import isUnpackable from "./isUnpackable.js";
 
 /**
@@ -29,7 +29,7 @@ export default function toFunction(obj) {
       const fn = await fnPromise;
       return fn(...args);
     };
-  } else if (isTreelike(obj)) {
+  } else if (isMaplike(obj)) {
     // Return a function that invokes the tree's getter.
     const tree = from(obj);
     return tree.get.bind(tree);

package/src/utilities/toPlainValue.js

@@ -1,7 +1,6 @@
-import ObjectTree from "../drivers/ObjectTree.js";
-import isTreelike from "../operations/isTreelike.js";
+import ObjectMap from "../drivers/ObjectMap.js";
+import isMaplike from "../operations/isMaplike.js";
 import mapReduce from "../operations/mapReduce.js";
-import * as trailingSlash from "../trailingSlash.js";
 import castArraylike from "./castArraylike.js";
 import isPrimitive from "./isPrimitive.js";
 import isStringlike from "./isStringlike.js";
@@ -9,10 +8,8 @@ import toString from "./toString.js";
 import TypedArray from "./TypedArray.js";
 
 /**
- * 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
- * CLI, which could a string, a stream of data, or some other kind of JavaScript
- * object.
+ * Convert the given input to the plainest possible JavaScript value. This is
+ * useful for rendering data for display or serialization.
  *
  * If the input is a function, it will be invoked and its result will be
  * processed.
@@ -20,7 +17,7 @@ import TypedArray from "./TypedArray.js";
  * If the input is a promise, it will be resolved and its result will be
  * processed.
  *
- * If the input is treelike, it will be converted to a plain JavaScript object,
+ * If the input is maplike, it will be converted to a plain JavaScript object,
  * recursively traversing the tree and converting all values to plain types.
  *
  * If the input is stringlike, its text will be returned.
@@ -33,9 +30,13 @@ import TypedArray from "./TypedArray.js";
  * returned as a plain object.
  *
  * @param {any} input
+ * @param {import("../../index.ts").ReduceFn} [reduceFn]
  * @returns {Promise<any>}
  */
-export default async function toPlainValue(input) {
+export default async function toPlainValue(
+  input,
+  reduceFn = reduceToPlainObject
+) {
   if (input instanceof Function) {
     // Invoke function
     input = input();
@@ -47,17 +48,9 @@ export default async function toPlainValue(input) {
 
   if (isPrimitive(input) || input instanceof Date) {
     return input;
-  } else if (isTreelike(input)) {
+  } else if (isMaplike(input)) {
     // Recursively convert tree to plain object.
-    return mapReduce(input, toPlainValue, (values, keys, tree) => {
-      // Special case for an empty tree: if based on array, return array.
-      if (tree instanceof ObjectTree && keys.length === 0) {
-        return /** @type {any} */ (tree).object instanceof Array ? [] : {};
-      }
-      // Normalize slashes in keys.
-      keys = keys.map(trailingSlash.remove);
-      return castArraylike(keys, values);
-    });
+    return mapReduce(input, (value) => toPlainValue(value, reduceFn), reduceFn);
   } else if (input instanceof ArrayBuffer || input instanceof TypedArray) {
     // Try to interpret the buffer as UTF-8 text, otherwise use base64.
     const text = toString(input);
@@ -78,6 +71,15 @@ export default async function toPlainValue(input) {
   }
 }
 
+function reduceToPlainObject(mapped, source) {
+  // Normalize slashes in keys.
+  // Special case for an empty map: if based on array, return array.
+  if (mapped.size === 0 && source instanceof ObjectMap) {
+    return /** @type {any} */ (source).object instanceof Array ? [] : {};
+  }
+  return castArraylike(mapped);
+}
+
 function toBase64(object) {
   if (typeof Buffer !== "undefined") {
     // Node.js environment

package/test/SampleAsyncMap.js

@@ -0,0 +1,34 @@
+import AsyncMap from "../src/drivers/AsyncMap.js";
+import * as trailingSlash from "../src/trailingSlash.js";
+
+/**
+ * For testing AsyncMaps
+ */
+export default class SampleAsyncMap extends AsyncMap {
+  constructor(entries) {
+    super();
+    this.map = new Map(entries);
+  }
+
+  async delete(key) {
+    const normalized = trailingSlash.remove(key);
+    return this.map.delete(normalized);
+  }
+
+  async get(key) {
+    let value = this.map.get(key);
+    if (value instanceof Array) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+    return value;
+  }
+
+  async *keys() {
+    yield* this.map.keys();
+  }
+
+  async set(key, value) {
+    this.map.set(key, value);
+    return this;
+  }
+}

package/test/browser/assert.js

@@ -44,6 +44,10 @@ assert.deepEqual = (actual, expected) => {
   throw new Error(`Expected ${expected} but got ${actual}`);
 };
 
+// For browser testing purposes we treat these the same
+assert.strictEqual = assert.equal;
+assert.deepStrictEqual = assert.deepEqual;
+
 assert.rejects = async (fn) => {
   try {
     await fn();
@@ -52,3 +56,19 @@ assert.rejects = async (fn) => {
   }
   throw new Error("Expected promise to reject but it resolved");
 };
+
+assert.throws = (fn, expected) => {
+  try {
+    fn();
+  } catch (/** @type {any} */ error) {
+    if (expected) {
+      if (error.name !== expected.name || error.message !== expected.message) {
+        throw new Error(
+          `Expected error ${expected.name}: ${expected.message} but got ${error.name}: ${error.message}`
+        );
+      }
+    }
+    return;
+  }
+  throw new Error("Expected function to throw but it did not");
+};

package/test/browser/index.html

@@ -11,48 +11,80 @@
         }
       }
     </script>
-    <!-- Omit FileTree.test.js, which is Node.js only -->
-    <!-- Omit SiteTree.test.js, which requires mocks -->
+    <!-- Omit FileMap.test.js, which is Node.js only -->
+    <!-- Omit SiteMap.test.js, which requires mocks -->
 
-    <!-- Unclear why drivers/constantTree.test.js won't load -->
-
-    <script type="module" src="../Tree.test.js"></script>
-    <script type="module" src="../drivers/BrowserFileTree.test.js"></script>
-    <script type="module" src="../drivers/DeepMapTree.test.js"></script>
-    <script type="module" src="../drivers/DeepObjectTree.test.js"></script>
-    <script type="module" src="../drivers/DeferredTree.test.js"></script>
-    <script type="module" src="../drivers/FunctionTree.test.js"></script>
-    <script type="module" src="../drivers/MapTree.test.js"></script>
-    <script type="module" src="../drivers/ObjectTree.test.js"></script>
-    <script type="module" src="../drivers/SetTree.test.js"></script>
-    <script type="module" src="../drivers/calendarTree.test.js"></script>
+    <script type="module" src="../drivers/AsyncMap.test.js"></script>
+    <script type="module" src="../drivers/BrowserFileMap.test.js"></script>
+    <script type="module" src="../drivers/CalendarMap.test.js"></script>
+    <script type="module" src="../drivers/ConstantMap.test.js"></script>
+    <script type="module" src="../drivers/FunctionMap.test.js"></script>
+    <script type="module" src="../drivers/ObjectMap.test.js"></script>
+    <script type="module" src="../drivers/SetMap.test.js"></script>
+    <script type="module" src="../drivers/SyncMap.test.js"></script>
     <script type="module" src="../operations/addNextPrevious.test.js"></script>
+    <script type="module" src="../operations/assign.test.js"></script>
     <script type="module" src="../operations/cache.test.js"></script>
-    <script type="module" src="../operations/cache.test.js"></script>
-    <script type="module" src="../operations/cachedKeyFunctions.test.js"></script>
-    <script type="module" src="../operations/concat.test.js"></script>
+    <script
+      type="module"
+      src="../operations/cachedKeyFunctions.test.js"
+    ></script>
+    <script type="module" src="../operations/clear.test.js"></script>
+    <script type="module" src="../operations/deepEntries.test.js"></script>
     <script type="module" src="../operations/deepMerge.test.js"></script>
     <script type="module" src="../operations/deepReverse.test.js"></script>
     <script type="module" src="../operations/deepTake.test.js"></script>
     <script type="module" src="../operations/deepText.test.js"></script>
     <script type="module" src="../operations/deepValues.test.js"></script>
-    <script type="module" src="../operations/deepValuesIterator.test.js"></script>
-    <script type="module" src="../operations/extensionKeyFunctions.test.js"></script>
+    <script
+      type="module"
+      src="../operations/deepValuesIterator.test.js"
+    ></script>
+    <script type="module" src="../operations/delete.test.js"></script>
+    <script type="module" src="../operations/entries.test.js"></script>
+    <script
+      type="module"
+      src="../operations/extensionKeyFunctions.test.js"
+    ></script>
     <script type="module" src="../operations/filter.test.js"></script>
+    <script type="module" src="../operations/first.test.js"></script>
+    <script type="module" src="../operations/forEach.test.js"></script>
+    <script type="module" src="../operations/from.test.js"></script>
     <script type="module" src="../operations/globKeys.test.js"></script>
-    <script type="module" src="../operations/group.test.js"></script>
+    <script type="module" src="../operations/groupBy.test.js"></script>
+    <script type="module" src="../operations/groupBy.test.js"></script>
+    <script type="module" src="../operations/has.test.js"></script>
+    <script type="module" src="../operations/indent.test.js"></script>
+    <script type="module" src="../operations/inners.test.js"></script>
     <script type="module" src="../operations/invokeFunctions.test.js"></script>
+    <script type="module" src="../operations/isMap.test.js"></script>
+    <script type="module" src="../operations/isMaplike.test.js"></script>
+    <script type="module" src="../operations/json.test.js"></script>
+    <script type="module" src="../operations/keys.test.js"></script>
+    <script type="module" src="../operations/length.test.js"></script>
     <script type="module" src="../operations/map.test.js"></script>
+    <script type="module" src="../operations/mapExtension.test.js"></script>
+    <script type="module" src="../operations/mapReduce.test.js"></script>
     <script type="module" src="../operations/mask.test.js"></script>
+    <script type="module" src="../operations/match.test.js"></script>
     <script type="module" src="../operations/merge.test.js"></script>
     <script type="module" src="../operations/paginate.test.js"></script>
     <script type="module" src="../operations/parseExtensions.test.js"></script>
+    <script type="module" src="../operations/paths.test.js"></script>
+    <script type="module" src="../operations/plain.test.js"></script>
     <script type="module" src="../operations/regExpKeys.test.js"></script>
     <script type="module" src="../operations/reverse.test.js"></script>
     <script type="module" src="../operations/scope.test.js"></script>
+    <script type="module" src="../operations/shuffle.test.js"></script>
     <script type="module" src="../operations/sort.test.js"></script>
+    <script type="module" src="../operations/sync.test.js"></script>
     <script type="module" src="../operations/take.test.js"></script>
-    <script type="module" src="../utilities.test.js"></script>
+    <script type="module" src="../operations/text.test.js"></script>
+    <script type="module" src="../operations/toFunction.test.js"></script>
+    <script type="module" src="../operations/traverse.test.js"></script>
+    <script type="module" src="../operations/traversePath.test.js"></script>
+    <script type="module" src="../operations/values.test.js"></script>
+    <script type="module" src="../operations/withKeys.test.js"></script>
   </head>
   <body></body>
 </html>

package/test/drivers/AsyncMap.test.js

@@ -0,0 +1,119 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import AsyncMap from "../../src/drivers/AsyncMap.js";
+import SampleAsyncMap from "../SampleAsyncMap.js";
+
+describe("AsyncMap", () => {
+  test("clear", async () => {
+    const map = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    assert.strictEqual(await map.size, 2);
+    await map.clear();
+    assert.strictEqual(await map.size, 0);
+  });
+
+  test("entries invokes keys() and get()", async () => {
+    const map = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    const entries = [];
+    for await (const entry of map.entries()) {
+      entries.push(entry);
+    }
+    assert.deepStrictEqual(entries, [
+      ["a", 1],
+      ["b", 2],
+    ]);
+  });
+
+  test("forEach", async () => {
+    const map = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    const calls = [];
+    await map.forEach(async (value, key, theMap) => {
+      calls.push([key, value, theMap]);
+    });
+    assert.deepStrictEqual(calls, [
+      ["a", 1, map],
+      ["b", 2, map],
+    ]);
+  });
+
+  test("static groupBy", async () => {
+    const items = [
+      { name: "apple", type: "fruit" },
+      { name: "beet", type: "vegetable" },
+      { name: "cherry", type: "fruit" },
+    ];
+    const map = await AsyncMap.groupBy(
+      items,
+      async (element, index) => element.type
+    );
+    assert.deepStrictEqual(Array.from(map.entries()), [
+      [
+        "fruit",
+        [
+          { name: "apple", type: "fruit" },
+          { name: "cherry", type: "fruit" },
+        ],
+      ],
+      ["vegetable", [{ name: "beet", type: "vegetable" }]],
+    ]);
+  });
+
+  test("has returns true if key exists in keys()", async () => {
+    const map = new AsyncMap();
+    map.keys = async function* () {
+      yield* ["a", "b/"];
+    };
+    assert.strictEqual(await map.has("a"), true);
+    assert.strictEqual(await map.has("b"), true); // trailing slash optional
+    assert.strictEqual(await map.has("b/"), true);
+    assert.strictEqual(await map.has("c"), false);
+  });
+
+  test("readOnly if get() is overridden but not delete() and set()", () => {
+    const map1 = new AsyncMap();
+    assert.strictEqual(map1.readOnly, false);
+
+    const map2 = new AsyncMap();
+    map2.get = async (key) => null;
+    assert.strictEqual(map2.readOnly, true);
+
+    const map3 = new AsyncMap();
+    map3.delete = async (key) => false;
+    map3.get = async (key) => null;
+    map3.set = async (key, value) => map3;
+    assert.strictEqual(map3.readOnly, false);
+  });
+
+  test("size", async () => {
+    const map = new SampleAsyncMap();
+    assert.strictEqual(await map.size, 0);
+    await map.set("a", 1);
+    assert.strictEqual(await map.size, 1);
+    await map.set("b", 2);
+    assert.strictEqual(await map.size, 2);
+    await map.delete("a");
+    assert.strictEqual(await map.size, 1);
+    await map.clear();
+    assert.strictEqual(await map.size, 0);
+  });
+
+  test("values", async () => {
+    const map = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    const values = [];
+    for await (const value of map.values()) {
+      values.push(value);
+    }
+    assert.deepStrictEqual(values, [1, 2]);
+  });
+});

package/test/drivers/{BrowserFileTree.test.js → BrowserFileMap.test.js}

@@ -1,15 +1,17 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import BrowserFileTree from "../../src/drivers/BrowserFileTree.js";
-import { Tree } from "../../src/internal.js";
+import BrowserFileMap from "../../src/drivers/BrowserFileMap.js";
+import keys from "../../src/operations/keys.js";
+import map from "../../src/operations/map.js";
+import plain from "../../src/operations/plain.js";
 
 // Skip these tests if we're not in a browser.
 const isBrowser = typeof window !== "undefined";
 if (isBrowser) {
-  describe("BrowserFileTree", async () => {
+  describe("BrowserFileMap", async () => {
     test("can get the keys of the tree", async () => {
       const fixture = await createFixture();
-      assert.deepEqual(Array.from(await fixture.keys()), [
+      assert.deepEqual(await keys(fixture), [
         "Alice.md",
         "Bob.md",
         "Carol.md",
@@ -57,6 +59,24 @@ if (isBrowser) {
       assert(await fixture.get("subfolder/"));
     });
 
+    test("can delete a value", async () => {
+      const fixture = await createFixture();
+
+      // Delete existing key.
+      const deleted = await fixture.delete("Bob.md");
+      assert.equal(deleted, true);
+
+      // Delete non-existing key.
+      const deletedAgain = await fixture.delete("Bob.md");
+      assert.equal(deletedAgain, false);
+
+      assert.deepEqual(await strings(fixture), {
+        "Alice.md": "Hello, **Alice**.",
+        "Carol.md": "Hello, **Carol**.",
+        subfolder: {},
+      });
+    });
+
     test("can set a value", async () => {
       const fixture = await createFixture();
 
@@ -66,41 +86,38 @@ if (isBrowser) {
       // New key.
       await fixture.set("David.md", "Hello, **David**.");
 
-      // Delete key.
-      await fixture.set("Bob.md", undefined);
-
-      // Delete non-existent key.
-      await fixture.set("xyz", undefined);
-
       assert.deepEqual(await strings(fixture), {
         "Alice.md": "Goodbye, **Alice**.",
+        "Bob.md": "Hello, **Bob**.",
         "Carol.md": "Hello, **Carol**.",
         "David.md": "Hello, **David**.",
         subfolder: {},
       });
     });
 
-    test("can create a subfolder via set", async () => {
+    test("can return or create a subfolder via child", async () => {
       const fixture = await createFixture();
-      const tree = {
-        async get(key) {
-          const name = key.replace(/\.md$/, "");
-          return `Hello, **${name}**.`;
-        },
-        async keys() {
-          return ["Ellen.md"];
-        },
-      };
-      await fixture.set("more", tree);
-      assert.deepEqual(await strings(fixture), {
-        "Alice.md": "Hello, **Alice**.",
-        "Bob.md": "Hello, **Bob**.",
-        "Carol.md": "Hello, **Carol**.",
-        more: {
-          "Ellen.md": "Hello, **Ellen**.",
-        },
-        subfolder: {},
-      });
+
+      // Return existing subfolder
+      const subfolder = await fixture.get("subfolder");
+      const child = await fixture.child("subfolder");
+      assert.equal(child, subfolder);
+
+      // Create new subfolder
+      const newChild = await fixture.child("newSubfolder");
+      assert.equal(newChild, subfolder);
+
+      // Replace existing file with folder
+      const replacedChild = await fixture.child("Alice.md");
+      assert.equal(replacedChild.parent, fixture);
+
+      assert.deepEqual(await keys(fixture), [
+        "Alice.md/",
+        "Bob.md",
+        "Carol.md",
+        "subfolder/",
+        "newSubfolder/",
+      ]);
     });
   });
 }
@@ -141,12 +158,12 @@ async function createFixture() {
     create: true,
   });
 
-  return new BrowserFileTree(subdirectory);
+  return new BrowserFileMap(subdirectory);
 }
 
 async function strings(tree) {
-  return Tree.plain(
-    Tree.map(tree, {
+  return plain(
+    await map(tree, {
       deep: true,
       value: (value) => text(value),
     })

package/test/drivers/{calendarTree.test.js → CalendarMap.test.js}

@@ -1,14 +1,12 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import calendar from "../../src/drivers/calendarTree.js";
+import CalendarMap from "../../src/drivers/CalendarMap.js";
 import toPlainValue from "../../src/utilities/toPlainValue.js";
 
-describe("calendarTree", () => {
-  test("without a start or end, returns a tree for today", async () => {
-    const tree = calendar({
-      value: (year, month, day) => `${year}-${month}-${day}`,
-    });
-    const plain = await toPlainValue(tree);
+describe("CalendarMap", () => {
+  test("without a start or end, returns a map for today", async () => {
+    const map = new CalendarMap();
+    const plain = await toPlainValue(map);
     const today = new Date();
     const year = today.getFullYear();
     const month = (today.getMonth() + 1).toString().padStart(2, "0");
@@ -22,13 +20,12 @@ describe("calendarTree", () => {
     });
   });
 
-  test("returns a tree for a month range", async () => {
-    const tree = calendar({
+  test("returns a map for a month range", async () => {
+    const map = new CalendarMap({
       start: "2025-01",
       end: "2025-02",
-      value: (year, month, day) => `${year}-${month}-${day}`,
     });
-    const plain = await toPlainValue(tree);
+    const plain = await toPlainValue(map);
     assert.deepEqual(plain, {
       2025: {
         "01": {
@@ -98,22 +95,23 @@ describe("calendarTree", () => {
     });
   });
 
-  test("returns a tree for a day range", async () => {
-    const tree = calendar({
+  test("returns a map for a day range", async () => {
+    const map = new CalendarMap({
       start: "2025-02-27",
       end: "2025-03-02",
-      value: (year, month, day) => `${year}-${month}-${day}`,
+      // Exercise custom value function
+      value: (year, month, day) => `${year}.${month}.${day}`,
     });
-    const plain = await toPlainValue(tree);
+    const plain = await toPlainValue(map);
     assert.deepEqual(plain, {
       2025: {
         "02": {
-          27: "2025-02-27",
-          28: "2025-02-28",
+          27: "2025.02.27",
+          28: "2025.02.28",
         },
         "03": {
-          "01": "2025-03-01",
-          "02": "2025-03-02",
+          "01": "2025.03.01",
+          "02": "2025.03.02",
         },
       },
     });

package/test/drivers/ConstantMap.test.js

@@ -0,0 +1,15 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ConstantMap from "../../src/drivers/ConstantMap.js";
+import keys from "../../src/operations/keys.js";
+import traverse from "../../src/operations/traverse.js";
+
+describe("ConstantMap", () => {
+  test("returns a deep tree that returns constant for all keys", async () => {
+    const fixture = new ConstantMap(1);
+    assert.deepEqual(Array.from(await keys(fixture)), []);
+    assert.equal(fixture.get("a"), 1);
+    assert.equal(fixture.get("b"), 1);
+    assert.equal(await traverse(fixture, "c/", "d/", "e"), 1);
+  });
+});