@weborigami/async-tree 0.5.7 → 0.6.0

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,32 +86,31 @@ 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 an empty subfolder", async () => {
+      const fixture = await createFixture();
+      await fixture.set("emptyFolder", BrowserFileMap.EMPTY);
+      assert.deepEqual(await strings(fixture), {
+        "Alice.md": "Hello, **Alice**.",
+        "Bob.md": "Hello, **Bob**.",
+        "Carol.md": "Hello, **Carol**.",
+        emptyFolder: {},
+        subfolder: {},
+      });
+    });
+
     test("can create a subfolder via set", 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);
+      const more = new Map([["Ellen.md", "Hello, **Ellen**."]]);
+      await fixture.set("more", more);
       assert.deepEqual(await strings(fixture), {
         "Alice.md": "Hello, **Alice**.",
         "Bob.md": "Hello, **Bob**.",
@@ -141,12 +160,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);
+  });
+});

package/test/drivers/DeepObjectMap.test.js

@@ -0,0 +1,36 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import DeepObjectMap from "../../src/drivers/DeepObjectMap.js";
+import plain from "../../src/operations/plain.js";
+
+describe("DeepObjectMap", () => {
+  test("returns a map for a value that's a plain sub-object or sub-array", async () => {
+    const map = createFixture();
+
+    const object = await map.get("object");
+    assert.equal(object instanceof DeepObjectMap, true);
+    assert.deepEqual(await plain(object), { b: 2 });
+    assert.equal(object.parent, map);
+
+    const array = await map.get("array");
+    assert.equal(array instanceof DeepObjectMap, true);
+    assert.deepEqual(await plain(array), [3]);
+    assert.equal(array.parent, map);
+  });
+
+  test("adds trailing slashes to keys for submaps including plain objects or arrays", async () => {
+    const map = createFixture();
+    const keys = Array.from(await map.keys());
+    assert.deepEqual(keys, ["a", "object/", "array/"]);
+  });
+});
+
+function createFixture() {
+  return new DeepObjectMap({
+    a: 1,
+    object: {
+      b: 2,
+    },
+    array: [3],
+  });
+}

package/test/drivers/{ExplorableSiteTree.test.js → ExplorableSiteMap.test.js}

@@ -1,7 +1,9 @@
 import assert from "node:assert";
 import { beforeEach, describe, mock, test } from "node:test";
-import ExplorableSiteTree from "../../src/drivers/ExplorableSiteTree.js";
-import { Tree } from "../../src/internal.js";
+import ExplorableSiteMap from "../../src/drivers/ExplorableSiteMap.js";
+import isMap from "../../src/operations/isMap.js";
+import map from "../../src/operations/map.js";
+import * as trailingSlash from "../../src/trailingSlash.js";
 
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
@@ -34,31 +36,35 @@ const mockResponses = {
   },
 };
 
-describe("ExplorableSiteTree", () => {
+describe("ExplorableSiteMap", () => {
   beforeEach(() => {
     mock.method(global, "fetch", mockFetch);
   });
 
   test("can get the keys of a tree", async () => {
-    const fixture = new ExplorableSiteTree(mockHost);
-    const keys = await fixture.keys();
-    assert.deepEqual(Array.from(keys), ["about/", "index.html"]);
+    const fixture = new ExplorableSiteMap(mockHost);
+    const keys = [];
+    for await (const key of fixture.keys()) {
+      keys.push(key);
+    }
+    assert.deepEqual(keys, ["about/", "index.html"]);
   });
 
   test("can get a plain value for a key", async () => {
-    const fixture = new ExplorableSiteTree(mockHost);
+    const fixture = new ExplorableSiteMap(mockHost);
+    /** @type {any} */
     const arrayBuffer = await fixture.get("index.html");
     const text = textDecoder.decode(arrayBuffer);
     assert.equal(text, "Home page");
   });
 
   test("getting an unsupported key returns undefined", async () => {
-    const fixture = new ExplorableSiteTree(mockHost);
+    const fixture = new ExplorableSiteMap(mockHost);
     assert.equal(await fixture.get("xyz"), undefined);
   });
 
   test("getting a null/undefined key throws an exception", async () => {
-    const fixture = new ExplorableSiteTree(mockHost);
+    const fixture = new ExplorableSiteMap(mockHost);
     await assert.rejects(async () => {
       await fixture.get(null);
     });
@@ -68,20 +74,20 @@ describe("ExplorableSiteTree", () => {
   });
 
   test("can return a new tree for a key that redirects", async () => {
-    const fixture = new ExplorableSiteTree(mockHost);
+    const fixture = new ExplorableSiteMap(mockHost);
     const about = await fixture.get("about");
-    assert(about instanceof ExplorableSiteTree);
+    assert(about instanceof ExplorableSiteMap);
     assert.equal(about.href, "https://mock/about/");
   });
 
   test("can convert a site to a plain object", async () => {
-    const fixture = new ExplorableSiteTree(mockHost);
+    const fixture = new ExplorableSiteMap(mockHost);
     // Convert buffers to strings.
-    const strings = await Tree.map(fixture, {
+    const strings = await map(fixture, {
       deep: true,
       value: (value) => textDecoder.decode(value),
     });
-    assert.deepEqual(await Tree.plain(strings), {
+    assert.deepEqual(await plain(strings), {
       about: {
         "Alice.html": "Hello, Alice!",
         "Bob.html": "Hello, Bob!",
@@ -114,3 +120,12 @@ async function mockFetch(href) {
     status: 404,
   };
 }
+
+async function plain(tree) {
+  const result = {};
+  for await (const [key, value] of tree.entries()) {
+    const normalized = trailingSlash.remove(key);
+    result[normalized] = isMap(value) ? await plain(value) : value;
+  }
+  return result;
+}

package/test/drivers/FileMap.test.js

@@ -0,0 +1,185 @@
+import assert from "node:assert";
+import * as fs from "node:fs";
+import path from "node:path";
+import { describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import FileMap from "../../src/drivers/FileMap.js";
+import map from "../../src/operations/map.js";
+import plain from "../../src/operations/plain.js";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const tempDirectory = path.join(dirname, "fixtures/temp");
+
+const textDecoder = new TextDecoder();
+
+describe("FileMap", () => {
+  test("can get the keys of the tree", () => {
+    const fixture = createFixture("fixtures/markdown");
+    assert.deepEqual(Array.from(fixture.keys()), [
+      "Alice.md",
+      "Bob.md",
+      "Carol.md",
+      "subfolder/",
+    ]);
+  });
+
+  test("can get the value for a key", () => {
+    const fixture = createFixture("fixtures/markdown");
+    const buffer = fixture.get("Alice.md");
+    const text = textDecoder.decode(buffer);
+    assert.equal(text, "Hello, **Alice**.");
+  });
+
+  test("getting an unsupported key returns undefined", () => {
+    const fixture = createFixture("fixtures/markdown");
+    assert.equal(fixture.get("xyz"), undefined);
+  });
+
+  test("getting empty key returns undefined", () => {
+    const fixture = createFixture("fixtures/markdown");
+    assert.equal(fixture.get(""), undefined);
+  });
+
+  test("getting a null/undefined key throws an exception", async () => {
+    const fixture = createFixture("fixtures/markdown");
+    await assert.rejects(async () => {
+      await fixture.get(null);
+    });
+    await assert.rejects(async () => {
+      await fixture.get(undefined);
+    });
+  });
+
+  test("can retrieve values with optional trailing slash", () => {
+    const fixture = createFixture("fixtures/markdown");
+    assert(fixture.get("Alice.md"));
+    assert(fixture.get("Alice.md/"));
+    assert(fixture.get("subfolder"));
+    assert(fixture.get("subfolder/"));
+  });
+
+  test("sets parent on subtrees", () => {
+    const fixture = createFixture("fixtures");
+    const markdown = fixture.get("markdown");
+    assert.deepEqual(markdown.parent, fixture);
+  });
+
+  test("can write out a file via set()", () => {
+    createTempDirectory();
+
+    // Write out a file.
+    const fileName = "file1";
+    const fileText = "This is the first file.";
+    const tempFiles = new FileMap(tempDirectory);
+    tempFiles.set(fileName, fileText);
+
+    // Read it back in.
+    const filePath = path.join(tempDirectory, fileName);
+    const actualText = String(fs.readFileSync(filePath));
+
+    assert.equal(fileText, actualText);
+
+    removeTempDirectory();
+  });
+
+  test("create subfolder via set() with EMPTY", () => {
+    createTempDirectory();
+
+    // Write out new, empty folder called "empty".
+    const tempFiles = new FileMap(tempDirectory);
+    tempFiles.set("empty", FileMap.EMPTY);
+
+    // Verify folder exists and has no contents.
+    const folderPath = path.join(tempDirectory, "empty");
+    const stats = fs.statSync(folderPath);
+    assert(stats.isDirectory());
+    const files = fs.readdirSync(folderPath);
+    assert.deepEqual(files, []);
+
+    removeTempDirectory();
+  });
+
+  test("can write out subfolder via set()", async () => {
+    createTempDirectory();
+
+    // Create a tiny set of "files".
+    // @ts-ignore
+    const files = new Map([
+      ["file1", "This is the first file."],
+      ["subfolder", new Map([["file2", "This is the second file."]])],
+    ]);
+    const object = await plain(files);
+
+    // Write out files as a new folder called "folder".
+    const tempFiles = new FileMap(tempDirectory);
+    tempFiles.set("folder", files);
+
+    // Read them back in.
+    const actualFiles = tempFiles.get("folder");
+    const strings = await map(actualFiles, {
+      deep: true,
+      value: (buffer) => textDecoder.decode(buffer),
+    });
+    const result = await plain(strings);
+    assert.deepEqual(result, object);
+
+    removeTempDirectory();
+  });
+
+  test("can delete a file", () => {
+    createTempDirectory();
+    const tempFile = path.join(tempDirectory, "file");
+    fs.writeFileSync(tempFile, "");
+    const tempFiles = new FileMap(tempDirectory);
+    const deleted = tempFiles.delete("file");
+    assert(deleted);
+    let stats;
+    try {
+      stats = fs.statSync(tempFile);
+    } catch (/** @type {any} */ error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    assert(stats === undefined);
+    removeTempDirectory();
+  });
+
+  test("delete returns false if file does not exist", () => {
+    createTempDirectory();
+    const tempFiles = new FileMap(tempDirectory);
+    const deleted = tempFiles.delete("nonexistent-file");
+    assert(!deleted);
+    removeTempDirectory();
+  });
+
+  test("can delete a folder", () => {
+    createTempDirectory();
+    const folder = path.join(tempDirectory, "folder");
+    fs.mkdirSync(folder);
+    const tempFiles = new FileMap(tempDirectory);
+    tempFiles.delete("folder");
+    let stats;
+    try {
+      stats = fs.statSync(folder);
+    } catch (/** @type {any} */ error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    assert(stats === undefined);
+    removeTempDirectory();
+  });
+});
+
+function createFixture(fixturePath) {
+  return new FileMap(path.join(dirname, fixturePath));
+}
+
+function createTempDirectory() {
+  fs.mkdirSync(tempDirectory, { recursive: true });
+}
+
+function removeTempDirectory() {
+  fs.rmSync(tempDirectory, { force: true, recursive: true });
+}

package/test/drivers/FunctionMap.test.js

@@ -0,0 +1,56 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import FunctionMap from "../../src/drivers/FunctionMap.js";
+import * as symbols from "../../src/symbols.js";
+
+describe("FunctionMap", () => {
+  test("keys uses supplied domain", () => {
+    const map = createFixture();
+    assert.deepEqual(Array.from(map.keys()), [
+      "Alice.md",
+      "Bob.md",
+      "Carol.md",
+    ]);
+  });
+
+  test("can get the value for a key", () => {
+    const map = createFixture();
+    const alice = map.get("Alice.md");
+    assert.equal(alice, "Hello, **Alice**.");
+  });
+
+  test("can get the value for an async function", async () => {
+    const map = new FunctionMap(async (s) => ({ s }));
+    const result = await map.get("test");
+    assert.deepEqual(result, {
+      s: "test",
+    });
+    assert.equal(result[symbols.parent], map);
+  });
+
+  test("getting a value from function with multiple arguments curries the function", () => {
+    const map = new FunctionMap((a, b, c) => a + b + c);
+    const fnA = map.get(1);
+    const fnAB = fnA.get(2);
+    const result = fnAB.get(3);
+    assert.equal(result, 6);
+  });
+
+  test("getting an unsupported key returns undefined", () => {
+    const fixture = createFixture();
+    assert.equal(fixture.get("xyz"), undefined);
+  });
+});
+
+function createFixture() {
+  return new FunctionMap(
+    (key) => {
+      if (key?.endsWith?.(".md")) {
+        const name = key.slice(0, -3);
+        return `Hello, **${name}**.`;
+      }
+      return undefined;
+    },
+    ["Alice.md", "Bob.md", "Carol.md"]
+  );
+}