@weborigami/async-tree 0.0.35

package/test/SiteTree.test.js

@@ -0,0 +1,110 @@
+import assert from "node:assert";
+import { beforeEach, describe, mock, test } from "node:test";
+import SiteTree from "../src/SiteTree.js";
+import * as Tree from "../src/Tree.js";
+
+const mockHost = "https://mock";
+
+const mockResponses = {
+  "/.keys.json": {
+    data: JSON.stringify(["about/"]),
+  },
+  "/about": {
+    redirected: true,
+    status: 301,
+    url: "https://mock/about/",
+  },
+  "/about/.keys.json": {
+    data: JSON.stringify(["Alice.html", "Bob.html", "Carol.html"]),
+  },
+  "/about/Alice.html": {
+    data: "Hello, Alice!",
+  },
+  "/about/Bob.html": {
+    data: "Hello, Bob!",
+  },
+  "/about/Carol.html": {
+    data: "Hello, Carol!",
+  },
+};
+
+describe("SiteTree", () => {
+  beforeEach(() => {
+    mock.method(global, "fetch", mockFetch);
+  });
+
+  test("resolve() returns a new SiteTree for the given relative route", () => {
+    const fixture = new SiteTree(mockHost);
+    const about = fixture.resolve("about");
+    assert.equal(about.href, "https://mock/about/");
+  });
+
+  test("can get the keys of the tree", async () => {
+    const fixture = new SiteTree(mockHost);
+    const about = fixture.resolve("about");
+    const keys = await about.keys();
+    assert.deepEqual([...keys], ["Alice.html", "Bob.html", "Carol.html"]);
+  });
+
+  test("can get the value for a key", async () => {
+    const fixture = new SiteTree(mockHost);
+    const about = fixture.resolve("about");
+    const alice = await about.get("Alice.html");
+    assert.equal(alice, "Hello, Alice!");
+  });
+
+  test("getting an unsupported key returns undefined", async () => {
+    const fixture = new SiteTree(mockHost);
+    assert.equal(await fixture.get("xyz"), undefined);
+  });
+
+  test("a redirect on a site with keys returns a SiteTree for the new URL", async () => {
+    const fixture = new SiteTree(mockHost);
+    const about = await fixture.get("about");
+    assert.equal(about.href, "https://mock/about/");
+  });
+
+  test("can determine whether a key is for a subtree", async () => {
+    const fixture = new SiteTree(mockHost);
+    assert.equal(await fixture.isKeyForSubtree("about"), true);
+    const about = fixture.resolve("about");
+    assert.equal(await about.isKeyForSubtree("Alice.html"), false);
+  });
+
+  test("can convert a SiteGraph to a plain object", async () => {
+    const fixture = new SiteTree(mockHost);
+    // Convert buffers to strings.
+    const strings = Tree.map(fixture, (value) => value.toString());
+    assert.deepEqual(await Tree.plain(strings), {
+      about: {
+        "Alice.html": "Hello, Alice!",
+        "Bob.html": "Hello, Bob!",
+        "Carol.html": "Hello, Carol!",
+      },
+    });
+  });
+});
+
+async function mockFetch(href) {
+  if (!href.startsWith(mockHost)) {
+    return { status: 404 };
+  }
+  const path = href.slice(mockHost.length);
+  const mockedResponse = mockResponses[path];
+  if (mockedResponse) {
+    return Object.assign(
+      {
+        // Returns a Buffer, not an ArrayBuffer
+        arrayBuffer: () => Buffer.from(mockedResponse.data),
+        ok: true,
+        status: 200,
+        text: () => mockedResponse.data,
+      },
+      mockedResponse
+    );
+  }
+  return {
+    ok: false,
+    status: 404,
+  };
+}

package/test/Tree.test.js

@@ -0,0 +1,347 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+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({
+      a: 1,
+      b: 2,
+      more: {
+        d: 3,
+      },
+    });
+
+    const source = {
+      a: 4, // Overwrite existing value
+      b: undefined, // Delete
+      c: 5, // Add
+      more: {
+        // Should leave existing `more` keys alone.
+        e: 6, // Add
+      },
+      // Add new subtree
+      extra: {
+        f: 7,
+      },
+    };
+
+    // Apply changes.
+    const result = await Tree.assign(target, source);
+
+    assert.equal(result, target);
+    assert.deepEqual(await Tree.plain(target), {
+      a: 4,
+      c: 5,
+      more: {
+        d: 3,
+        e: 6,
+      },
+      extra: {
+        f: 7,
+      },
+    });
+  });
+
+  test("assign() can apply updates to an array", async () => {
+    const target = new ObjectTree(["a", "b", "c"]);
+    await Tree.assign(target, ["d", "e"]);
+    assert.deepEqual(await Tree.plain(target), ["d", "e", "c"]);
+  });
+
+  test("clear() removes all values", async () => {
+    const fixture = createFixture();
+    await Tree.clear(fixture);
+    assert.deepEqual([...(await Tree.entries(fixture))], []);
+  });
+
+  test("entries() returns the [key, value] pairs", async () => {
+    const fixture = createFixture();
+    assert.deepEqual(
+      [...(await Tree.entries(fixture))],
+      [
+        ["Alice.md", "Hello, **Alice**."],
+        ["Bob.md", "Hello, **Bob**."],
+        ["Carol.md", "Hello, **Carol**."],
+      ]
+    );
+  });
+
+  test("forEach() invokes a callback for each entry", async () => {
+    const fixture = createFixture();
+    const results = {};
+    await Tree.forEach(fixture, async (value, key) => {
+      results[key] = value;
+    });
+    assert.deepEqual(results, {
+      "Alice.md": "Hello, **Alice**.",
+      "Bob.md": "Hello, **Bob**.",
+      "Carol.md": "Hello, **Carol**.",
+    });
+  });
+
+  test("from() returns an async tree as is", async () => {
+    const tree1 = new ObjectTree({
+      a: "Hello, a.",
+    });
+    const tree2 = Tree.from(tree1);
+    assert.equal(tree2, tree1);
+  });
+
+  test("from() uses an object's unpack() method if defined", async () => {
+    const obj = {
+      unpack() {
+        return {
+          a: "Hello, a.",
+        };
+      },
+    };
+    const tree = Tree.from(obj);
+    assert.deepEqual(await Tree.plain(tree), {
+      a: "Hello, a.",
+    });
+  });
+
+  test("from() creates a deferred tree if unpack() returns a promise", async () => {
+    const obj = {
+      async unpack() {
+        return {
+          a: "Hello, a.",
+        };
+      },
+    };
+    const tree = Tree.from(obj);
+    assert.deepEqual(await Tree.plain(tree), {
+      a: "Hello, a.",
+    });
+  });
+
+  test("has returns true if the key exists", async () => {
+    const fixture = createFixture();
+    assert.equal(await Tree.has(fixture, "Alice.md"), true);
+    assert.equal(await Tree.has(fixture, "David.md"), false);
+  });
+
+  test("isAsyncTree returns true if the object is a tree", () => {
+    const missingGetAndKeys = {};
+    assert(!Tree.isAsyncTree(missingGetAndKeys));
+
+    const missingIterator = {
+      async get() {},
+    };
+    assert(!Tree.isAsyncTree(missingIterator));
+
+    const missingGet = {
+      async keys() {},
+    };
+    assert(!Tree.isAsyncTree(missingGet));
+
+    const hasGetAndKeys = {
+      async get() {},
+      async keys() {},
+    };
+    assert(Tree.isAsyncTree(hasGetAndKeys));
+  });
+
+  test("isAsyncMutableTree returns true if the object is a mutable tree", () => {
+    assert.equal(
+      Tree.isAsyncMutableTree({
+        get() {},
+        keys() {},
+      }),
+      false
+    );
+    assert.equal(Tree.isAsyncMutableTree(createFixture()), true);
+  });
+
+  test("isTreelike() returns true if the argument can be cast to an async tree", () => {
+    assert(!Tree.isTreelike(null));
+    assert(Tree.isTreelike({}));
+    assert(Tree.isTreelike([]));
+    assert(Tree.isTreelike(new Map()));
+    assert(Tree.isTreelike(new Set()));
+  });
+
+  test("isKeyForSubtree() returns true if the key is for a subtree", async () => {
+    const tree = new ObjectTree({
+      a: 1,
+      more: {
+        b: 2,
+      },
+    });
+    assert(!(await Tree.isKeyForSubtree(tree, "a")));
+    assert(await Tree.isKeyForSubtree(tree, "more"));
+  });
+
+  test("map() maps values", async () => {
+    const tree = {
+      a: "Alice",
+      more: {
+        b: "Bob",
+      },
+    };
+    const mapped = Tree.map(tree, (value) => value.toUpperCase());
+    assert.deepEqual(await Tree.plain(mapped), {
+      a: "ALICE",
+      more: {
+        b: "BOB",
+      },
+    });
+  });
+
+  test("mapReduce() can map values and reduce them", async () => {
+    const tree = {
+      a: 1,
+      b: 2,
+      more: {
+        c: 3,
+      },
+      d: 4,
+    };
+    const reduced = await Tree.mapReduce(
+      tree,
+      (value) => value,
+      async (values) => String.prototype.concat(...values)
+    );
+    assert.deepEqual(reduced, "1234");
+  });
+
+  test("plain() produces a plain object version of a tree", async () => {
+    const original = {
+      a: 1,
+      b: 2,
+      c: 3,
+      more: {
+        d: 4,
+        e: 5,
+      },
+    };
+    const tree = new ObjectTree(original);
+    const plain = await Tree.plain(tree);
+    assert.deepEqual(plain, original);
+  });
+
+  test("plain() produces an array for an array-like tree", async () => {
+    const original = ["a", "b", "c"];
+    const tree = new ObjectTree(original);
+    const plain = await Tree.plain(tree);
+    assert.deepEqual(plain, original);
+  });
+
+  test("plain() leaves an array-like tree as an object if keys aren't consecutive", async () => {
+    const original = {
+      0: "a",
+      1: "b",
+      // missing
+      3: "c",
+    };
+    const tree = new ObjectTree(original);
+    const plain = await Tree.plain(tree);
+    assert.deepEqual(plain, original);
+  });
+
+  test("remove method removes a value", async () => {
+    const fixture = createFixture();
+    await Tree.remove(fixture, "Alice.md");
+    assert.deepEqual(
+      [...(await Tree.entries(fixture))],
+      [
+        ["Bob.md", "Hello, **Bob**."],
+        ["Carol.md", "Hello, **Carol**."],
+      ]
+    );
+  });
+
+  test("toFunction returns a function that invokes a tree's get() method", async () => {
+    const tree = new ObjectTree({
+      a: 1,
+      b: 2,
+    });
+    const fn = Tree.toFunction(tree);
+    assert.equal(await fn("a"), 1);
+    assert.equal(await fn("b"), 2);
+  });
+
+  test("traverse() a path of keys", async () => {
+    const tree = new ObjectTree({
+      a1: 1,
+      a2: {
+        b1: 2,
+        b2: {
+          c1: 3,
+          c2: 4,
+        },
+      },
+    });
+    assert.equal(await Tree.traverse(tree), tree);
+    assert.equal(await Tree.traverse(tree, "a1"), 1);
+    assert.equal(await Tree.traverse(tree, "a2", "b2", "c2"), 4);
+    assert.equal(
+      await Tree.traverse(tree, "a2", "doesntexist", "c2"),
+      undefined
+    );
+  });
+
+  test("traverse() from one tree into another", async () => {
+    const tree = new ObjectTree({
+      a: {
+        b: new MapTree([
+          ["c", "Hello"],
+          ["d", "Goodbye"],
+        ]),
+      },
+    });
+    assert.equal(await Tree.traverse(tree, "a", "b", "c"), "Hello");
+  });
+
+  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 result = await Tree.traverse(tree, "unpackable", "");
+    assert.equal(result, "Content");
+  });
+
+  test("traversing a final empty string returns a value as is if it's not unpackable", async () => {
+    const tree = new ObjectTree({
+      a: "Hello",
+    });
+    const result = await Tree.traverse(tree, "a", "");
+    assert.equal(result, "Hello");
+  });
+
+  test("traversePath() traverses a slash-separated path", async () => {
+    const tree = new ObjectTree({
+      a: {
+        b: {
+          c: "Hello",
+        },
+      },
+    });
+    assert.equal(await Tree.traversePath(tree, "a/b/c"), "Hello");
+  });
+
+  test("values() returns the store's values", async () => {
+    const fixture = createFixture();
+    assert.deepEqual(
+      [...(await Tree.values(fixture))],
+      ["Hello, **Alice**.", "Hello, **Bob**.", "Hello, **Carol**."]
+    );
+  });
+});
+
+function createFixture() {
+  return new ObjectTree({
+    "Alice.md": "Hello, **Alice**.",
+    "Bob.md": "Hello, **Bob**.",
+    "Carol.md": "Hello, **Carol**.",
+  });
+}

package/test/browser/assert.js

@@ -0,0 +1,45 @@
+/**
+ * A simple test runner for the browser to run the subset of the Node.s test
+ * runner used by the project.
+ */
+
+export default function assert(condition) {
+  if (!condition) {
+    throw new Error("Assertion failed");
+  }
+}
+
+assert.equal = (actual, expected) => {
+  if (Number.isNaN(actual) && Number.isNaN(expected)) {
+    return;
+  } else if (actual == expected) {
+    return;
+  } else {
+    throw new Error(`Expected ${expected} but got ${actual}`);
+  }
+};
+
+// This is a simplified deepEqual test that examines the conditions we care
+// about. For reference, the actual Node assert.deepEqual is much more complex:
+// see https://github.com/nodejs/node/blob/main/lib/internal/util/comparisons.js
+assert.deepEqual = (actual, expected) => {
+  if (actual === expected) {
+    return;
+  } else if (
+    typeof actual === "object" &&
+    actual != null &&
+    typeof expected === "object" &&
+    expected != null &&
+    Object.keys(actual).length === Object.keys(expected).length
+  ) {
+    for (const prop in actual) {
+      if (!expected.hasOwnProperty(prop)) {
+        break;
+      }
+      assert.deepEqual(actual[prop], expected[prop]);
+    }
+    return;
+  }
+
+  throw new Error(`Expected ${expected} but got ${actual}`);
+};

package/test/browser/index.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <script type="importmap">
+      {
+        "imports": {
+          "node:assert": "./assert.js",
+          "node:test": "./testRunner.js"
+        }
+      }
+    </script>
+    <!-- Omit FileTree.test.js, which is Node.js only -->
+    <!-- Omit SiteTree.test.js, which requires mocks -->
+    <script type="module" src="../BrowserFileTree.test.js"></script>
+    <script type="module" src="../DeferredTree.test.js"></script>
+    <script type="module" src="../FunctionTree.test.js"></script>
+    <script type="module" src="../MapTree.test.js"></script>
+    <script type="module" src="../ObjectTree.test.js"></script>
+    <script type="module" src="../SetTree.test.js"></script>
+    <script type="module" src="../Tree.test.js"></script>
+    <script type="module" src="../operations/cache.test.js"></script>
+    <script type="module" src="../operations/merge.test.js"></script>
+    <script type="module" src="../operations/mergeDeep.test.js"></script>
+    <script type="module" src="../transforms/cachedKeyFns.test.js"></script>
+    <script
+      type="module"
+      src="../transforms/keyMapsForExtensions.test.js"
+    ></script>
+    <script type="module" src="../transforms/map.test.js"></script>
+    <script type="module" src="../utilities.test.js"></script>
+  </head>
+  <body></body>
+</html>

package/test/browser/testRunner.js

@@ -0,0 +1,51 @@
+/**
+ * A simple test runner for the browser to run the subset of the Node.s test
+ * runner used by the project.
+ */
+
+let promises = {};
+let currentSuite;
+
+const markers = {
+  success: "✅",
+  skipped: "ー",
+  fail: "❌",
+};
+
+export async function describe(name, fn) {
+  promises[name] = [];
+  currentSuite = name;
+  await fn();
+  const results = await Promise.all(promises[name]);
+  const someFailed = results.some((result) => result.result === "fail");
+  const header = `${someFailed ? markers.fail : markers.success} ${name}`;
+  console[someFailed ? "group" : "groupCollapsed"](header);
+  for (const result of results) {
+    const marker = markers[result.result];
+    const name = result.name;
+    const message = result.result === "fail" ? `: ${result.message}` : "";
+    const skipped = result.result === "skipped" ? " [skipped]" : "";
+    console.log(`${marker} ${name}${message}${skipped}`);
+  }
+  console.groupEnd();
+}
+
+// Node test() calls can call an async function, but the test() function isn't
+// declared async. We implicitly wrap the test call with a Promise and add it to
+// the list of promises for the current suite.
+export async function test(name, fn) {
+  promises[currentSuite].push(runTest(name, fn));
+}
+
+test.skip = (name, fn) => {
+  promises[currentSuite].push(Promise.resolve({ result: "skipped", name }));
+};
+
+async function runTest(name, fn) {
+  try {
+    await fn();
+    return { result: "success", name };
+  } catch (/** @type {any} */ error) {
+    return { result: "fail", name, message: error.message };
+  }
+}

package/test/fixtures/markdown/Alice.md

@@ -0,0 +1 @@
+Hello, **Alice**.

package/test/fixtures/markdown/Bob.md

@@ -0,0 +1 @@
+Hello, **Bob**.

package/test/fixtures/markdown/Carol.md

@@ -0,0 +1 @@
+Hello, **Carol**.

package/test/operations/cache.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectTree from "../../src/ObjectTree.js";
+import * as Tree from "../../src/Tree.js";
+import cache from "../../src/operations/cache.js";
+
+describe("cache", () => {
+  test("caches reads of values from one tree into another", async () => {
+    const objectCache = new ObjectTree({});
+    const fixture = cache(
+      Tree.from({
+        a: 1,
+        b: 2,
+        c: 3,
+        more: {
+          d: 4,
+        },
+      }),
+      objectCache
+    );
+
+    const keys = Array.from(await fixture.keys());
+    assert.deepEqual(keys, ["a", "b", "c", "more"]);
+
+    assert.equal(await objectCache.get("a"), undefined);
+    assert.equal(await fixture.get("a"), 1);
+    assert.equal(await objectCache.get("a"), 1); // Now in cache
+
+    assert.equal(await objectCache.get("b"), undefined);
+    assert.equal(await fixture.get("b"), 2);
+    assert.equal(await objectCache.get("b"), 2);
+  });
+
+  test("if a cache filter is supplied, it only caches values whose keys match the filter", async () => {
+    const objectCache = new ObjectTree({});
+    const fixture = cache(
+      Tree.from({
+        "a.txt": "a",
+        "b.txt": "b",
+      }),
+      objectCache,
+      Tree.from({
+        "a.txt": true,
+      })
+    );
+
+    // Access some values to populate the cache.
+    assert.equal(await fixture.get("a.txt"), "a");
+    assert.equal(await fixture.get("b.txt"), "b");
+
+    // The a.txt value should be cached because it matches the filter.
+    assert.equal(await objectCache.get("a.txt"), "a");
+
+    // The b.txt value should not be cached because it does not match the filter.
+    assert.equal(await objectCache.get("b.txt"), undefined);
+  });
+});

package/test/operations/merge.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import * as Tree from "../../src/Tree.js";
+import merge from "../../src/operations/merge.js";
+
+describe("merge", () => {
+  test("performs a shallow merge", async () => {
+    const fixture = merge(
+      Tree.from({
+        a: 1,
+        b: {
+          c: 2,
+        },
+      }),
+      Tree.from({
+        // Will be obscured by `b` above
+        b: {
+          d: 3,
+        },
+        e: {
+          f: 4,
+        },
+      })
+    );
+
+    assert.deepEqual(await Tree.plain(fixture), {
+      a: 1,
+      b: {
+        c: 2,
+      },
+      e: {
+        f: 4,
+      },
+    });
+
+    const d = await Tree.traverse(fixture, "b", "d");
+    assert.equal(d, undefined);
+  });
+});