@weborigami/async-tree 0.0.64-beta.2 → 0.0.65-beta.1

package/browser.js

@@ -4,10 +4,10 @@ export { default as DeferredTree } from "./src/DeferredTree.js";
 // Skip FileTree.js, which is Node.js only.
 export { default as BrowserFileTree } from "./src/BrowserFileTree.js";
 export { default as FunctionTree } from "./src/FunctionTree.js";
+export * as keysJson from "./src/jsonKeys.js";
 export { default as MapTree } from "./src/MapTree.js";
 export { default as ObjectTree } from "./src/ObjectTree.js";
 export { default as SetTree } from "./src/SetTree.js";
 export { default as SiteTree } from "./src/SiteTree.js";
 export * as Tree from "./src/Tree.js";
-export * as keysJson from "./src/keysJson.js";
 export * from "./src/utilities.js";

package/main.js

@@ -6,10 +6,8 @@ export { default as FunctionTree } from "./src/FunctionTree.js";
 export { default as MapTree } from "./src/MapTree.js";
 // Skip BrowserFileTree.js, which is browser-only.
 export { default as DeepMapTree } from "./src/DeepMapTree.js";
-export { default as SetTree } from "./src/SetTree.js";
-export { default as SiteTree } from "./src/SiteTree.js";
 export { DeepObjectTree, ObjectTree, Tree } from "./src/internal.js";
-export * as keysJson from "./src/keysJson.js";
+export * as jsonKeys from "./src/jsonKeys.js";
 export { default as cache } from "./src/operations/cache.js";
 export { default as concat } from "./src/operations/concat.js";
 export { default as deepMerge } from "./src/operations/deepMerge.js";
@@ -24,6 +22,8 @@ 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 { default as SetTree } from "./src/SetTree.js";
+export { default as SiteTree } from "./src/SiteTree.js";
 export * as symbols from "./src/symbols.js";
 export { default as cachedKeyFunctions } from "./src/transforms/cachedKeyFunctions.js";
 export { default as deepReverse } from "./src/transforms/deepReverse.js";

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.64-beta.2",
+  "version": "0.0.65-beta.1",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "20.14.9",
-    "typescript": "5.5.3"
+    "@types/node": "22.5.4",
+    "typescript": "5.5.4"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.64-beta.2"
+    "@weborigami/types": "0.0.65-beta.1"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/BrowserFileTree.js

@@ -34,6 +34,13 @@ export default class BrowserFileTree {
   }
 
   async get(key) {
+    if (key == null) {
+      // Reject nullish key.
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
+    }
+
     const directory = await this.getDirectory();
 
     // Try the key as a subfolder name.

package/src/FileTree.js

@@ -49,9 +49,11 @@ export default class FileTree {
   }
 
   async get(key) {
-    if (!key) {
-      // Undefined key or empty string key is invalid.
-      return undefined;
+    if (key == null) {
+      // Reject nullish key.
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
     }
 
     const filePath = path.resolve(this.dirname, key);

package/src/FunctionTree.js

@@ -27,11 +27,11 @@ export default class FunctionTree {
       this.fn.length <= 1
         ? // Function takes no arguments, one argument, or a variable number of
           // arguments: invoke it.
-          await this.fn.call(null, key)
+          await this.fn.call(this.parent, key)
         : // Bind the key to the first parameter. Subsequent get calls will
           // eventually bind all parameters until only one remains. At that point,
           // the above condition will apply and the function will be invoked.
-          Reflect.construct(this.constructor, [this.fn.bind(null, key)]);
+          Reflect.construct(this.constructor, [this.fn.bind(this.parent, key)]);
     setParent(value, this);
     return value;
   }

package/src/MapTree.js

@@ -23,6 +23,13 @@ export default class MapTree {
   }
 
   async get(key) {
+    if (key == null) {
+      // Reject nullish key.
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
+    }
+
     const value = this.map.get(key);
     setParent(value, this);
     return value;

package/src/ObjectTree.js

@@ -25,15 +25,11 @@ export default class ObjectTree {
    * @param {any} key
    */
   async get(key) {
-    // If the value is an array, we require that the key be one of its own
-    // properties: we don't want to return Array prototype methods like `map`
-    // and `find`.
-    if (
-      this.object instanceof Array &&
-      key &&
-      !this.object.hasOwnProperty(key)
-    ) {
-      return undefined;
+    if (key == null) {
+      // Reject nullish key.
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
     }
 
     let value = await this.object[key];

package/src/SetTree.js

@@ -17,6 +17,13 @@ export default class SetTree {
   }
 
   async get(key) {
+    if (key == null) {
+      // Reject nullish key.
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
+    }
+
     const value = this.values[key];
     setParent(value, this);
     return value;

package/src/SiteTree.js

@@ -1,5 +1,5 @@
 import { Tree } from "./internal.js";
-import * as keysJson from "./keysJson.js";
+import * as jsonKeys from "./jsonKeys.js";
 import { setParent } from "./utilities.js";
 
 /**
@@ -31,6 +31,13 @@ export default class SiteTree {
   }
 
   async get(key) {
+    if (key == null) {
+      // Reject nullish key.
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`
+      );
+    }
+
     // If there is only one key and it's the empty string, and the site is
     // explorable, we take the route as "index.html". With this and subsequent
     // checks, we try to avoid sniffing the site to see if it's explorable, as
@@ -86,7 +93,7 @@ export default class SiteTree {
       .then((response) => (response.ok ? response.text() : null))
       .then((text) => {
         try {
-          return text ? keysJson.parse(text) : null;
+          return text ? jsonKeys.parse(text) : null;
         } catch (error) {
           // Got a response, but it's not JSON. Most likely the site doesn't
           // actually have a .keys.json file, and is returning a Not Found page,

package/src/Tree.js

@@ -402,13 +402,10 @@ export async function traverse(treelike, ...keys) {
  * @param  {...any} keys
  */
 export async function traverseOrThrow(treelike, ...keys) {
-  if (!treelike) {
-    throw new TraverseError("Tried to traverse a null or undefined value");
-  }
-
   // Start our traversal at the root of the tree.
   /** @type {any} */
   let value = treelike;
+  let position = 0;
 
   // If traversal operation was called with a `this` context, use that as the
   // target for function calls.
@@ -419,13 +416,11 @@ export async function traverseOrThrow(treelike, ...keys) {
   let key;
   while (remainingKeys.length > 0) {
     if (value === undefined) {
-      // Attempted to traverse an undefined value
-      const message = key
-        ? `${key} does not exist`
-        : `Couldn't traverse the path: ${keys
-            .map((key) => String(key))
-            .join("/")}`;
-      throw new TraverseError(message, treelike, keys);
+      throw new TraverseError("Tried to traverse a null or undefined value", {
+        tree: treelike,
+        keys,
+        position,
+      });
     }
 
     // If the value is packed and can be unpacked, unpack it.
@@ -466,6 +461,8 @@ export async function traverseOrThrow(treelike, ...keys) {
         value = originalValue;
       }
     }
+
+    position++;
   }
 
   return value;
@@ -485,11 +482,10 @@ export async function traversePath(tree, path) {
 
 // Error class thrown by traverseOrThrow()
 class TraverseError extends ReferenceError {
-  constructor(message, tree, keys) {
+  constructor(message, options) {
     super(message);
-    this.tree = tree;
     this.name = "TraverseError";
-    this.keys = keys;
+    Object.assign(this, options);
   }
 }
 

package/src/calendarTree.js

@@ -0,0 +1,77 @@
+/**
+ * Return a tree of years, months, and days from a start date to an end date.
+ *
+ * Both the start and end date can be provided in "YYYY-MM-DD", "YYYY-MM", or
+ * "YYYY" format. If a start year is provided, but a month is not, then the
+ * first month of the year will be used; if a start month is provided, but a day
+ * is not, then the first day of that month will be used. Similar logic applies
+ * to the end date, using the last month of the year or the last day of the
+ * month.
+ *
+ * If a start date is omitted, today will be used, likewise for the end date.
+ *
+ * @param {string} [start] - Start date in "YYYY-MM-DD", "YYYY-MM", or "YYYY"
+ * format
+ * @param {string} [end] - End date in "YYYY-MM-DD", "YYYY-MM", or "YYYY" format
+ */
+export default function calendarTree(start, end) {
+  const startParts = start?.split("-") ?? [];
+  const endParts = end?.split("-") ?? [];
+
+  const today = new Date();
+
+  const startYear = startParts[0]
+    ? parseInt(startParts[0])
+    : today.getFullYear();
+  const startMonth = startParts[1]
+    ? parseInt(startParts[1])
+    : startParts[0]
+    ? 1
+    : today.getMonth() + 1;
+  const startDay = startParts[2]
+    ? parseInt(startParts[2])
+    : startParts[1]
+    ? 1
+    : today.getDate();
+
+  const endYear = endParts[0] ? parseInt(endParts[0]) : today.getFullYear();
+  const endMonth = endParts[1]
+    ? parseInt(endParts[1])
+    : endParts[0]
+    ? 12
+    : today.getMonth() + 1;
+  const endDay = endParts[2]
+    ? parseInt(endParts[2])
+    : endParts[1]
+    ? daysInMonth(endYear, endMonth)
+    : today.getDate();
+
+  let years = {};
+  for (let year = startYear; year <= endYear; year++) {
+    let months = new Map();
+    const firstMonth = year === startYear ? startMonth : 1;
+    const lastMonth = year === endYear ? endMonth : 12;
+    for (let month = firstMonth; month <= lastMonth; month++) {
+      const monthPadded = month.toString().padStart(2, "0");
+      let days = new Map();
+      const firstDay =
+        year === startYear && month === startMonth ? startDay : 1;
+      const lastDay =
+        year === endYear && month === endMonth
+          ? endDay
+          : daysInMonth(year, month);
+      for (let day = firstDay; day <= lastDay; day++) {
+        const dayPadded = day.toString().padStart(2, "0");
+        days.set(dayPadded, null);
+      }
+      months.set(monthPadded, days);
+    }
+    years[year] = months;
+  }
+
+  return years;
+}
+
+function daysInMonth(year, month) {
+  return new Date(year, month, 0).getDate();
+}

package/src/{keysJson.js → jsonKeys.js}

@@ -1,8 +1,8 @@
 import { Tree } from "./internal.js";
 
 /**
- * The .keys.json file format lets a site expose the keys of a node in the site
- * so that they can be read by SiteTree.
+ * The JSON Keys protocol lets a site expose the keys of a node in the site so
+ * that they can be read by SiteTree.
  *
  * This file format is a JSON array of key descriptors: a string like
  * "index.html" for a specific resource available at the node, or a string with

package/src/operations/cache.js

@@ -1,4 +1,4 @@
-import { DeepObjectTree, Tree } from "../internal.js";
+import { ObjectTree, Tree } from "../internal.js";
 
 /**
  * Caches values from a source tree in a second cache tree. Cache source tree
@@ -14,16 +14,30 @@ import { DeepObjectTree, Tree } from "../internal.js";
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
  * @param {Treelike} sourceTreelike
- * @param {AsyncMutableTree} [cacheTree]
+ * @param {AsyncMutableTree} [cacheTreelike]
  * @param {Treelike} [filterTreelike]
  * @returns {AsyncTree & { description: string }}
  */
-export default function treeCache(sourceTreelike, cacheTree, filterTreelike) {
+export default function treeCache(
+  sourceTreelike,
+  cacheTreelike,
+  filterTreelike
+) {
   const source = Tree.from(sourceTreelike);
   const filter = filterTreelike ? Tree.from(filterTreelike) : undefined;
 
   /** @type {AsyncMutableTree} */
-  const cache = cacheTree ?? new DeepObjectTree({});
+  let cache;
+  if (cacheTreelike) {
+    // @ts-ignore
+    cache = Tree.from(cacheTreelike);
+    if (!Tree.isAsyncMutableTree(cache)) {
+      throw new Error("Cache tree must define a set() method.");
+    }
+  } else {
+    cache = new ObjectTree({});
+  }
+
   let keys;
   return {
     description: "cache",
@@ -47,8 +61,9 @@ export default function treeCache(sourceTreelike, cacheTree, filterTreelike) {
             // Construct merged tree for a tree result.
             if (cacheValue === undefined) {
               // Construct new container in cache
-              await cache.set(key, {});
-              cacheValue = await cache.get(key);
+              cacheValue = new ObjectTree({});
+              cacheValue.parent = this;
+              await cache.set(key, cacheValue);
             }
             value = treeCache(value, cacheValue, filterValue);
           } else {

package/test/BrowserFileTree.test.js

@@ -30,6 +30,16 @@ if (isBrowser) {
       assert.equal(await fixture.get("xyz"), undefined);
     });
 
+    test("getting a null/undefined key throws an exception", async () => {
+      const fixture = await createFixture();
+      await assert.rejects(async () => {
+        await fixture.get(null);
+      });
+      await assert.rejects(async () => {
+        await fixture.get(undefined);
+      });
+    });
+
     test("can set a value", async () => {
       const fixture = await createFixture();
 

package/test/FileTree.test.js

@@ -11,7 +11,7 @@ const tempDirectory = path.join(dirname, "fixtures/temp");
 
 const textDecoder = new TextDecoder();
 
-describe.only("FileTree", async () => {
+describe("FileTree", async () => {
   test("can get the keys of the tree", async () => {
     const fixture = createFixture("fixtures/markdown");
     assert.deepEqual(Array.from(await fixture.keys()), [
@@ -33,6 +33,16 @@ describe.only("FileTree", async () => {
     assert.equal(await fixture.get("xyz"), 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("sets parent on subtrees", async () => {
     const fixture = createFixture("fixtures");
     const markdown = await fixture.get("markdown");
@@ -64,7 +74,7 @@ describe.only("FileTree", async () => {
     await removeTempDirectory();
   });
 
-  test.only("can create empty subfolder via set()", async () => {
+  test("can create empty subfolder via set()", async () => {
     await createTempDirectory();
 
     // Write out new, empty folder called "empty".

package/test/MapTree.test.js

@@ -26,6 +26,16 @@ describe("MapTree", () => {
     const fixture = createFixture();
     assert.equal(await fixture.get("d"), undefined);
   });
+
+  test("getting a null/undefined key throws an exception", async () => {
+    const fixture = createFixture();
+    await assert.rejects(async () => {
+      await fixture.get(null);
+    });
+    await assert.rejects(async () => {
+      await fixture.get(undefined);
+    });
+  });
 });
 
 function createFixture() {

package/test/ObjectTree.test.js

@@ -24,6 +24,16 @@ describe("ObjectTree", () => {
     assert.equal(await fixture.get("xyz"), undefined);
   });
 
+  test("getting a null/undefined key throws an exception", async () => {
+    const fixture = createFixture();
+    await assert.rejects(async () => {
+      await fixture.get(null);
+    });
+    await assert.rejects(async () => {
+      await fixture.get(undefined);
+    });
+  });
+
   test("can set a value", async () => {
     const tree = new ObjectTree({
       a: 1,

package/test/SetTree.test.js

@@ -23,6 +23,17 @@ describe("SetTree", () => {
     assert.equal(await fixture.get(3), undefined);
   });
 
+  test("getting a null/undefined key throws an exception", async () => {
+    const set = new Set(["a", "b", "c"]);
+    const fixture = new SetTree(set);
+    await assert.rejects(async () => {
+      await fixture.get(null);
+    });
+    await assert.rejects(async () => {
+      await fixture.get(undefined);
+    });
+  });
+
   test("sets parent on subtrees", async () => {
     const set = new Set();
     set.add(new ObjectTree({}));

package/test/SiteTree.test.js

@@ -66,6 +66,16 @@ describe("SiteTree", () => {
     assert.equal(await fixture.get("xyz"), undefined);
   });
 
+  test("getting a null/undefined key throws an exception", async () => {
+    const fixture = new SiteTree(mockHost);
+    await assert.rejects(async () => {
+      await fixture.get(null);
+    });
+    await assert.rejects(async () => {
+      await fixture.get(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");

package/test/calendarTree.test.js

@@ -0,0 +1,111 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { toPlainValue } from "../main.js";
+import calendarTree from "../src/calendarTree.js";
+
+describe("calendarTree", () => {
+  test("without a start or end, returns a tree for today", async () => {
+    const tree = calendarTree();
+    const plain = await toPlainValue(tree);
+    const today = new Date();
+    const year = today.getFullYear();
+    const month = (today.getMonth() + 1).toString().padStart(2, "0");
+    const day = today.getDate().toString().padStart(2, "0");
+    assert.deepEqual(plain, {
+      [year]: {
+        [month]: {
+          [day]: null,
+        },
+      },
+    });
+  });
+
+  test("returns a tree for a month range", async () => {
+    const tree = calendarTree("2025-01", "2025-02");
+    const plain = await toPlainValue(tree);
+    assert.deepEqual(plain, {
+      2025: {
+        "01": {
+          "01": null,
+          "02": null,
+          "03": null,
+          "04": null,
+          "05": null,
+          "06": null,
+          "07": null,
+          "08": null,
+          "09": null,
+          10: null,
+          11: null,
+          12: null,
+          13: null,
+          14: null,
+          15: null,
+          16: null,
+          17: null,
+          18: null,
+          19: null,
+          20: null,
+          21: null,
+          22: null,
+          23: null,
+          24: null,
+          25: null,
+          26: null,
+          27: null,
+          28: null,
+          29: null,
+          30: null,
+          31: null,
+        },
+        "02": {
+          "01": null,
+          "02": null,
+          "03": null,
+          "04": null,
+          "05": null,
+          "06": null,
+          "07": null,
+          "08": null,
+          "09": null,
+          10: null,
+          11: null,
+          12: null,
+          13: null,
+          14: null,
+          15: null,
+          16: null,
+          17: null,
+          18: null,
+          19: null,
+          20: null,
+          21: null,
+          22: null,
+          23: null,
+          24: null,
+          25: null,
+          26: null,
+          27: null,
+          28: null,
+        },
+      },
+    });
+  });
+
+  test("returns a tree for a day range", async () => {
+    const tree = calendarTree("2025-02-27", "2025-03-02");
+    const plain = await toPlainValue(tree);
+    assert.deepEqual(plain, {
+      2025: {
+        "02": {
+          27: null,
+          28: null,
+        },
+        "03": {
+          "01": null,
+          "02": null,
+        },
+      },
+    });
+  });
+});

package/test/jsonKeys.test.js

@@ -0,0 +1,24 @@
+import { DeepObjectTree } from "@weborigami/async-tree";
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import * as jsonKeys from "../src/jsonKeys.js";
+
+describe("jsonKeys", () => {
+  test("parses JSON Keys", async () => {
+    const json = '["index.html","about/"]';
+    const parsed = jsonKeys.parse(json);
+    assert.deepStrictEqual(parsed, {
+      "index.html": false,
+      about: true,
+    });
+  });
+
+  test("stringifies JSON Keys", async () => {
+    const tree = new DeepObjectTree({
+      about: {},
+      "index.html": "Home",
+    });
+    const json = await jsonKeys.stringify(tree);
+    assert.strictEqual(json, '["about/","index.html"]');
+  });
+});

package/test/operations/cache.test.js

@@ -1,13 +1,13 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import { ObjectTree, Tree } from "../../src/internal.js";
+import { DeepObjectTree, ObjectTree, Tree } from "../../src/internal.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({
+      new DeepObjectTree({
         a: 1,
         b: 2,
         c: 3,
@@ -18,7 +18,7 @@ describe("cache", () => {
       objectCache
     );
 
-    const keys = Array.from(await fixture.keys());
+    const keys = [...(await fixture.keys())];
     assert.deepEqual(keys, ["a", "b", "c", "more"]);
 
     assert.equal(await objectCache.get("a"), undefined);
@@ -28,6 +28,13 @@ describe("cache", () => {
     assert.equal(await objectCache.get("b"), undefined);
     assert.equal(await fixture.get("b"), 2);
     assert.equal(await objectCache.get("b"), 2);
+
+    assert.equal(await objectCache.get("more"), undefined);
+    const more = await fixture.get("more");
+    assert.deepEqual([...(await more.keys())], ["d"]);
+    assert.equal(await more.get("d"), 4);
+    const moreCache = await objectCache.get("more");
+    assert.equal(await moreCache.get("d"), 4);
   });
 
   test("if a cache filter is supplied, it only caches values whose keys match the filter", async () => {