@weborigami/async-tree 0.0.64 → 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",
+  "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"
+    "@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/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/{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/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/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"]');
+  });
+});