@weborigami/async-tree 0.0.35

package/src/utilities.js

@@ -0,0 +1,124 @@
+/**
+ * If the given plain object has only sequential integer keys, return it as an
+ * array. Otherwise return it as is.
+ *
+ * @param {any} object
+ */
+export function castArrayLike(object) {
+  let hasKeys = false;
+  let expectedIndex = 0;
+  for (const key in object) {
+    hasKeys = true;
+    const index = Number(key);
+    if (key === "" || isNaN(index) || index !== expectedIndex) {
+      // Not an array-like object.
+      return object;
+    }
+    expectedIndex++;
+  }
+  return hasKeys ? Object.values(object) : object;
+}
+
+// Names of OS-generated files that should not be enumerated
+export const hiddenFileNames = [".DS_Store"];
+
+/**
+ * Return the Object prototype at the root of the object's prototype chain.
+ *
+ * This is used by functions like isPlainObject() to handle cases where the
+ * `Object` at the root prototype chain is in a different realm.
+ *
+ * @param {any} object
+ */
+export function getRealmObjectPrototype(object) {
+  let proto = object;
+  while (Object.getPrototypeOf(proto) !== null) {
+    proto = Object.getPrototypeOf(proto);
+  }
+  return proto;
+}
+
+/**
+ * Return true if the object is a plain JavaScript object created by `{}`,
+ * `new Object()`, or `Object.create(null)`.
+ *
+ * This function also considers object-like things with no prototype (like a
+ * `Module`) as plain objects.
+ *
+ * @param {any} object
+ */
+export function isPlainObject(object) {
+  // From https://stackoverflow.com/q/51722354/76472
+  if (typeof object !== "object" || object === null) {
+    return false;
+  }
+
+  // We treat object-like things with no prototype (like a Module) as plain
+  // objects.
+  if (Object.getPrototypeOf(object) === null) {
+    return true;
+  }
+
+  // Do we inherit directly from Object in this realm?
+  return Object.getPrototypeOf(object) === getRealmObjectPrototype(object);
+}
+
+/**
+ * Return true if the object is a string or object with a non-trival `toString`
+ * method.
+ *
+ * @param {any} obj
+ * @returns {obj is import("@weborigami/async-tree").StringLike}
+ */
+export function isStringLike(obj) {
+  if (typeof obj === "string") {
+    return true;
+  } else if (obj?.toString === undefined) {
+    return false;
+  } else if (obj.toString === getRealmObjectPrototype(obj).toString) {
+    // The stupid Object.prototype.toString implementation always returns
+    // "[object Object]", so if that's the only toString method the object has,
+    // we return false.
+    return false;
+  } else {
+    return true;
+  }
+}
+
+/**
+ * Given a path like "/foo/bar/baz", return an array of keys like ["foo", "bar",
+ * "baz"].
+ *
+ * Leading slashes are ignored. Consecutive slashes or a trailing slash will be
+ * represented by the empty string.
+ *
+ * @param {string} pathname
+ */
+export function keysFromPath(pathname) {
+  const keys = pathname.split("/");
+  if (keys[0] === "") {
+    // The path begins with a slash; drop that part.
+    keys.shift();
+  }
+  return keys;
+}
+
+// Used for natural sort order
+export const naturalSortCompareFn = new Intl.Collator(undefined, {
+  numeric: true,
+}).compare;
+
+/**
+ * Sort the given array using [natural sort
+ * order](https://en.wikipedia.org/wiki/Natural_sort_order). Like the native
+ * `Array` `sort` function, this operation destructively modifies the array in
+ * place.
+ *
+ * The default sort order for some sources like operating system files can be
+ * unpredictable. Since it's quite common for file names to include numbers, it
+ * can helpful to use natural sort order instead: ["file1", "file9", "file10"]
+ * instead of ["file1", "file10", "file9"].
+ */
+export function sortNatural(array) {
+  array.sort(naturalSortCompareFn);
+}

package/test/BrowserFileTree.test.js

@@ -0,0 +1,119 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import BrowserFileTree from "../src/BrowserFileTree.js";
+import * as Tree from "../src/Tree.js";
+
+// Skip these tests if we're not in a browser.
+const isBrowser = typeof window !== "undefined";
+if (isBrowser) {
+  describe("BrowserFileTree", async () => {
+    test("can get the keys of the tree", async () => {
+      const fixture = await createFixture();
+      assert.deepEqual(
+        [...(await fixture.keys())],
+        ["Alice.md", "Bob.md", "Carol.md"]
+      );
+    });
+
+    test("can get the value for a key", async () => {
+      const fixture = await createFixture();
+      assert.deepEqual(await strings(fixture), {
+        "Alice.md": "Hello, **Alice**.",
+        "Bob.md": "Hello, **Bob**.",
+        "Carol.md": "Hello, **Carol**.",
+      });
+    });
+
+    test("getting an unsupported key returns undefined", async () => {
+      const fixture = await createFixture();
+      assert.equal(await fixture.get("xyz"), undefined);
+    });
+
+    test("can set a value", async () => {
+      const fixture = await createFixture();
+
+      // Update existing key.
+      await fixture.set("Alice.md", "Goodbye, **Alice**.");
+
+      // 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**.",
+        "Carol.md": "Hello, **Carol**.",
+        "David.md": "Hello, **David**.",
+      });
+    });
+
+    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);
+      assert.deepEqual(await strings(fixture), {
+        "Alice.md": "Hello, **Alice**.",
+        "Bob.md": "Hello, **Bob**.",
+        "Carol.md": "Hello, **Carol**.",
+        more: {
+          "Ellen.md": "Hello, **Ellen**.",
+        },
+      });
+    });
+  });
+}
+
+async function createFile(directory, name, contents) {
+  const file = await directory.getFileHandle(name, { create: true });
+  const writable = await file.createWritable();
+  await writable.write(contents);
+  await writable.close();
+}
+
+let count = 0;
+async function createFixture() {
+  const root = await navigator.storage.getDirectory();
+  const directory = await root.getDirectoryHandle("async-tree", {
+    create: true,
+  });
+
+  // Create a new subdirectory for each test.
+  const subdirectoryName = `test${count++}`;
+
+  // Delete any pre-existing subdirectory with that name.
+  try {
+    await directory.removeEntry(subdirectoryName, { recursive: true });
+  } catch (e) {
+    // Ignore errors.
+  }
+
+  const subdirectory = await directory.getDirectoryHandle(subdirectoryName, {
+    create: true,
+  });
+
+  await createFile(subdirectory, "Alice.md", "Hello, **Alice**.");
+  await createFile(subdirectory, "Bob.md", "Hello, **Bob**.");
+  await createFile(subdirectory, "Carol.md", "Hello, **Carol**.");
+
+  return new BrowserFileTree(subdirectory);
+}
+
+async function strings(tree) {
+  return Tree.plain(Tree.map(tree, (value) => text(value)));
+}
+
+function text(arrayBuffer) {
+  return new TextDecoder().decode(arrayBuffer);
+}

package/test/DeferredTree.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import DeferredTree from "../src/DeferredTree.js";
+import ObjectTree from "../src/ObjectTree.js";
+import * as Tree from "../src/Tree.js";
+
+describe("DeferredTree", () => {
+  test("lazy-loads a treelike object", async () => {
+    const tree = new DeferredTree(async () => ({ a: 1, b: 2, c: 3 }));
+    assert.deepEqual(await Tree.plain(tree), { a: 1, b: 2, c: 3 });
+  });
+
+  test("sets parent on subtrees", async () => {
+    const object = {
+      a: 1,
+    };
+    const parent = new ObjectTree({});
+    const fixture = new DeferredTree(() => object);
+    fixture.parent = parent;
+    const tree = await fixture.tree();
+    assert.equal(tree.parent, parent);
+  });
+});

package/test/FileTree.test.js

@@ -0,0 +1,134 @@
+import assert from "node:assert";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import FileTree from "../src/FileTree.js";
+import * as Tree from "../src/Tree.js";
+
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+const tempDirectory = path.join(dirname, "fixtures/temp");
+
+describe("FileTree", async () => {
+  test("can get the keys of the tree", async () => {
+    const fixture = createFixture("fixtures/markdown");
+    assert.deepEqual(
+      [...(await fixture.keys())],
+      ["Alice.md", "Bob.md", "Carol.md"]
+    );
+  });
+
+  test("can get the value for a key", async () => {
+    const fixture = createFixture("fixtures/markdown");
+    const alice = await fixture.get("Alice.md");
+    assert.equal(alice, "Hello, **Alice**.");
+  });
+
+  test("getting an unsupported key returns undefined", async () => {
+    const fixture = createFixture("fixtures/markdown");
+    assert.equal(await fixture.get("xyz"), undefined);
+  });
+
+  test("sets parent on subtrees", async () => {
+    const fixture = createFixture("fixtures");
+    const markdown = await fixture.get("markdown");
+    assert.equal(markdown.parent, fixture);
+  });
+
+  test("can indicate which values are subtrees", async () => {
+    const fixture = createFixture("fixtures");
+    assert(await fixture.isKeyForSubtree("markdown"));
+    const markdown = await fixture.get("markdown");
+    assert(!(await markdown.isKeyForSubtree("a.txt")));
+  });
+
+  test("can write out a file via set()", async () => {
+    await createTempDirectory();
+
+    // Write out a file.
+    const fileName = "file1";
+    const fileText = "This is the first file.";
+    const tempFiles = new FileTree(tempDirectory);
+    await tempFiles.set(fileName, fileText);
+
+    // Read it back in.
+    const filePath = path.join(tempDirectory, fileName);
+    const actualText = String(await fs.readFile(filePath));
+
+    assert.equal(fileText, actualText);
+
+    await removeTempDirectory();
+  });
+
+  test("can write out subfolder via set()", async () => {
+    await createTempDirectory();
+
+    // Create a tiny set of "files".
+    const obj = {
+      file1: "This is the first file.",
+      subfolder: {
+        file2: "This is the second file.",
+      },
+    };
+
+    // Write out files as a new folder called "folder".
+    const tempFiles = new FileTree(tempDirectory);
+    await tempFiles.set("folder", obj);
+
+    // Read them back in.
+    const actualFiles = await tempFiles.get("folder");
+    const strings = Tree.map(actualFiles, (buffer) => String(buffer));
+    const plain = await Tree.plain(strings);
+    assert.deepEqual(plain, obj);
+
+    await removeTempDirectory();
+  });
+
+  test("can delete a file via set()", async () => {
+    await createTempDirectory();
+    const tempFile = path.join(tempDirectory, "file");
+    await fs.writeFile(tempFile, "");
+    const tempFiles = new FileTree(tempDirectory);
+    await tempFiles.set("file", undefined);
+    let stats;
+    try {
+      stats = await fs.stat(tempFile);
+    } catch (/** @type {any} */ error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    assert(stats === undefined);
+    await removeTempDirectory();
+  });
+
+  test("can delete a folder via set()", async () => {
+    await createTempDirectory();
+    const folder = path.join(tempDirectory, "folder");
+    await fs.mkdir(folder);
+    const tempFiles = new FileTree(tempDirectory);
+    await tempFiles.set("folder", undefined);
+    let stats;
+    try {
+      stats = await fs.stat(folder);
+    } catch (/** @type {any} */ error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+    assert(stats === undefined);
+    await removeTempDirectory();
+  });
+});
+
+function createFixture(fixturePath) {
+  return new FileTree(path.join(dirname, fixturePath));
+}
+
+async function createTempDirectory() {
+  await fs.mkdir(tempDirectory, { recursive: true });
+}
+
+async function removeTempDirectory() {
+  await fs.rm(tempDirectory, { recursive: true });
+}

package/test/FunctionTree.test.js

@@ -0,0 +1,51 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import FunctionTree from "../src/FunctionTree.js";
+
+describe("FunctionTree", async () => {
+  test("can get the keys of the tree", async () => {
+    const fixture = createFixture();
+    assert.deepEqual(
+      [...(await fixture.keys())],
+      ["Alice.md", "Bob.md", "Carol.md"]
+    );
+  });
+
+  test("can get the value for a key", async () => {
+    const fixture = createFixture();
+    const alice = await fixture.get("Alice.md");
+    assert.equal(alice, "Hello, **Alice**.");
+  });
+
+  test("unpacking the tree returns the function itself", async () => {
+    const fn = () => true;
+    const fixture = new FunctionTree(fn);
+    assert.equal(await fixture.unpack(), fn);
+  });
+
+  test("getting a value from function with multiple arguments curries the function", async () => {
+    const fixture = new FunctionTree((a, b, c) => a + b + c);
+    const fnA = await fixture.get(1);
+    const fnAB = await fnA.get(2);
+    const result = await fnAB.get(3);
+    assert.equal(result, 6);
+  });
+
+  test("getting an unsupported key returns undefined", async () => {
+    const fixture = createFixture();
+    assert.equal(await fixture.get("xyz"), undefined);
+  });
+});
+
+function createFixture() {
+  return new FunctionTree(
+    (key) => {
+      if (key?.endsWith?.(".md")) {
+        const name = key.slice(0, -3);
+        return `Hello, **${name}**.`;
+      }
+      return undefined;
+    },
+    ["Alice.md", "Bob.md", "Carol.md"]
+  );
+}

package/test/MapTree.test.js

@@ -0,0 +1,37 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import MapTree from "../src/MapTree.js";
+
+describe("MapTree", () => {
+  test("can get the keys of the tree", async () => {
+    const fixture = createFixture();
+    assert.deepEqual([...(await fixture.keys())], ["a", "b", "c"]);
+  });
+
+  test("can get the value for a key", async () => {
+    const fixture = createFixture();
+    const a = await fixture.get("a");
+    assert.equal(a, 1);
+  });
+
+  test("sets parent on subtrees", async () => {
+    const map = new Map([["more", new Map([["a", 1]])]]);
+    const fixture = new MapTree(map);
+    const more = await fixture.get("more");
+    assert.equal(more.parent, fixture);
+  });
+
+  test("getting an unsupported key returns undefined", async () => {
+    const fixture = createFixture();
+    assert.equal(await fixture.get("d"), undefined);
+  });
+});
+
+function createFixture() {
+  const map = new Map([
+    ["a", 1],
+    ["b", 2],
+    ["c", 3],
+  ]);
+  return new MapTree(map);
+}

package/test/ObjectTree.test.js

@@ -0,0 +1,159 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectTree from "../src/ObjectTree.js";
+import * as Tree from "../src/Tree.js";
+
+describe("ObjectTree", () => {
+  test("can get the keys of the tree", async () => {
+    const fixture = createFixture();
+    assert.deepEqual(
+      [...(await fixture.keys())],
+      ["Alice.md", "Bob.md", "Carol.md"]
+    );
+  });
+
+  test("can get the value for a key", async () => {
+    const fixture = createFixture();
+    const alice = await fixture.get("Alice.md");
+    assert.equal(alice, "Hello, **Alice**.");
+  });
+
+  test("getting an unsupported key returns undefined", async () => {
+    const fixture = createFixture();
+    assert.equal(await fixture.get("xyz"), undefined);
+  });
+
+  test("can set a value", async () => {
+    const tree = new ObjectTree({
+      a: 1,
+      b: 2,
+      c: 3,
+    });
+
+    // Update existing key.
+    await tree.set("a", 4);
+
+    // New key.
+    await tree.set("d", 5);
+
+    // Delete key.
+    await tree.set("b", undefined);
+
+    assert.deepEqual(await Tree.entries(tree), [
+      ["a", 4],
+      ["c", 3],
+      ["d", 5],
+    ]);
+  });
+
+  test("can wrap a class instance", async () => {
+    class Foo {
+      constructor() {
+        this.a = 1;
+      }
+
+      get prop() {
+        return this._prop;
+      }
+      set prop(prop) {
+        this._prop = prop;
+      }
+    }
+    class Bar extends Foo {
+      method() {}
+    }
+    const bar = new Bar();
+    /** @type {any} */ (bar).extra = "Hello";
+    const fixture = new ObjectTree(bar);
+    assert.deepEqual(await Tree.entries(fixture), [
+      ["a", 1],
+      ["extra", "Hello"],
+      ["prop", undefined],
+    ]);
+    assert.equal(await fixture.get("a"), 1);
+    await fixture.set("prop", "Goodbye");
+    assert.equal(bar.prop, "Goodbye");
+    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 = {
+      a: 1,
+      more: {
+        b: 2,
+      },
+    };
+    const fixture = new ObjectTree(object);
+    const more = await fixture.get("more");
+    assert.equal(more.parent, fixture);
+  });
+
+  test("isKeyForSubtree() indicates which values are subtrees", async () => {
+    const tree = new ObjectTree({
+      a1: 1,
+      a2: {
+        b1: 2,
+      },
+      a3: 3,
+      a4: {
+        b2: 4,
+      },
+    });
+    const keys = Array.from(await tree.keys());
+    const subtrees = await Promise.all(
+      keys.map(async (key) => await tree.isKeyForSubtree(key))
+    );
+    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) {},
+      async keys() {},
+    };
+    const tree = new ObjectTree({
+      subtree,
+    });
+    assert.equal(await tree.get("subtree"), subtree);
+  });
+});
+
+function createFixture() {
+  return new ObjectTree({
+    "Alice.md": "Hello, **Alice**.",
+    "Bob.md": "Hello, **Bob**.",
+    "Carol.md": "Hello, **Carol**.",
+  });
+}

package/test/SetTree.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import SetTree from "../src/SetTree.js";
+
+describe("SetTree", () => {
+  test("can get the keys of the tree", async () => {
+    const set = new Set(["a", "b", "c"]);
+    const fixture = new SetTree(set);
+    assert.deepEqual([...(await fixture.keys())], [0, 1, 2]);
+  });
+
+  test("can get the value for a key", async () => {
+    const set = new Set(["a", "b", "c"]);
+    const fixture = new SetTree(set);
+    const a = await fixture.get(0);
+    assert.equal(a, "a");
+  });
+
+  test("getting an unsupported key returns undefined", async () => {
+    const set = new Set(["a", "b", "c"]);
+    const fixture = new SetTree(set);
+    assert.equal(await fixture.get(3), undefined);
+  });
+
+  test("sets parent on subtrees", async () => {
+    const set = new Set();
+    set.add(new Set("a"));
+    const fixture = new SetTree(set);
+    const subtree = await fixture.get(0);
+    assert.equal(subtree.parent, fixture);
+  });
+});