@weborigami/async-tree 0.0.66-beta.2 → 0.0.66

package/main.js

@@ -6,9 +6,9 @@ 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 ExplorableSiteTree } from "./src/ExplorableSiteTree.js";
 export { DeepObjectTree, ObjectTree, Tree } from "./src/internal.js";
 export * as jsonKeys from "./src/jsonKeys.js";
-export { default as OpenSiteTree } from "./src/OpenSiteTree.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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.66-beta.2",
+  "version": "0.0.66",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
@@ -11,7 +11,7 @@
     "typescript": "5.6.2"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.66-beta.2"
+    "@weborigami/types": "0.0.66"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/DeferredTree.js

@@ -14,12 +14,14 @@ import { Tree } from "./internal.js";
 export default class DeferredTree {
   /**
    * @param {Function|Promise<any>} loader
+   * @param {{ deep?: boolean }} [options]
    */
-  constructor(loader) {
+  constructor(loader, options) {
     this.loader = loader;
     this.treePromise = null;
     this._tree = null;
     this._parentUntilLoaded = null;
+    this._deep = options?.deep ?? false;
   }
 
   async get(key) {
@@ -60,7 +62,7 @@ export default class DeferredTree {
 
     // Use a promise to ensure the treelike is only converted to a tree once.
     this.treePromise ??= this.loadResult().then((treelike) => {
-      this._tree = Tree.from(treelike);
+      this._tree = Tree.from(treelike, { deep: this._deep });
       if (this._parentUntilLoaded) {
         // Now that the tree has been loaded, we can set its parent if it hasn't
         // already been set.

package/src/{OpenSiteTree.js → ExplorableSiteTree.js}

@@ -1,6 +1,11 @@
 import SiteTree from "./SiteTree.js";
 
-export default class OpenSiteTree extends SiteTree {
+/**
+ * A [SiteTree](SiteTree.html) that implements the [JSON Keys](jsonKeys.html)
+ * protocol. This enables a `keys()` method that can return the keys of a site
+ * route even though such a mechanism is not built into the HTTP protocol.
+ */
+export default class ExplorableSiteTree extends SiteTree {
   constructor(...args) {
     super(...args);
     this.serverKeysPromise = undefined;
@@ -24,6 +29,12 @@ export default class OpenSiteTree extends SiteTree {
     return this.serverKeysPromise;
   }
 
+  /**
+   * Returns the keys of the site route. For this to work, the route must have a
+   * `.keys.json` file that contains a JSON array of string keys.
+   *
+   * @returns {Promise<Iterable<string>>}
+   */
   async keys() {
     const serverKeys = await this.getServerKeys();
     return serverKeys ?? [];

package/src/SiteTree.js

@@ -56,6 +56,14 @@ export default class SiteTree {
     return this.processResponse(response);
   }
 
+  /**
+   * Returns an empty set of keys.
+   *
+   * For a variation of `SiteTree` that can return the keys for a site route,
+   * see [ExplorableSiteTree](ExplorableSiteTree.html).
+   *
+   * @returns {Promise<Iterable<string>>}
+   */
   async keys() {
     return [];
   }

package/src/Tree.js

@@ -110,10 +110,11 @@ export async function forEach(tree, callbackFn) {
  * parent of the new tree.
  *
  * @param {Treelike | Object} object
- * @param {{ deep?: true, parent?: AsyncTree|null }} [options]
+ * @param {{ deep?: boolean, parent?: AsyncTree|null }} [options]
  * @returns {AsyncTree}
  */
 export function from(object, options = {}) {
+  const deep = options.deep ?? false;
   let tree;
   if (isAsyncTree(object)) {
     // Argument already supports the tree interface.
@@ -126,13 +127,13 @@ export function from(object, options = {}) {
   } else if (object instanceof Set) {
     tree = new SetTree(object);
   } else if (isPlainObject(object) || object instanceof Array) {
-    tree = options.deep ? new DeepObjectTree(object) : new ObjectTree(object);
+    tree = deep ? new DeepObjectTree(object) : new ObjectTree(object);
   } else if (isUnpackable(object)) {
     async function AsyncFunction() {} // Sample async function
     tree =
       object.unpack instanceof AsyncFunction.constructor
         ? // Async unpack: return a deferred tree.
-          new DeferredTree(object.unpack)
+          new DeferredTree(object.unpack, { deep })
         : // Synchronous unpack: cast the result of unpack() to a tree.
           from(object.unpack());
   } else if (object && typeof object === "object") {
@@ -320,6 +321,8 @@ export async function paths(treelike, base = "") {
  * The result's keys will be the tree's keys cast to strings. Any tree value
  * that is itself a tree will be similarly converted to a plain object.
  *
+ * Any trailing slashes in keys will be removed.
+ *
  * @param {Treelike} treelike
  * @returns {Promise<PlainObject|Array>}
  */

package/test/{OpenSiteTree.test.js → ExplorableSiteTree.test.js}

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { beforeEach, describe, mock, test } from "node:test";
-import OpenSiteTree from "../src/OpenSiteTree.js";
+import ExplorableSiteTree from "../src/ExplorableSiteTree.js";
 import { Tree } from "../src/internal.js";
 
 const textDecoder = new TextDecoder();
@@ -34,31 +34,31 @@ const mockResponses = {
   },
 };
 
-describe("OpenSiteTree", () => {
+describe("ExplorableSiteTree", () => {
   beforeEach(() => {
     mock.method(global, "fetch", mockFetch);
   });
 
   test("can get the keys of a tree", async () => {
-    const fixture = new OpenSiteTree(mockHost);
+    const fixture = new ExplorableSiteTree(mockHost);
     const keys = await fixture.keys();
     assert.deepEqual(Array.from(keys), ["about/", "index.html"]);
   });
 
   test("can get a plain value for a key", async () => {
-    const fixture = new OpenSiteTree(mockHost);
+    const fixture = new ExplorableSiteTree(mockHost);
     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 OpenSiteTree(mockHost);
+    const fixture = new ExplorableSiteTree(mockHost);
     assert.equal(await fixture.get("xyz"), undefined);
   });
 
   test("getting a null/undefined key throws an exception", async () => {
-    const fixture = new OpenSiteTree(mockHost);
+    const fixture = new ExplorableSiteTree(mockHost);
     await assert.rejects(async () => {
       await fixture.get(null);
     });
@@ -68,14 +68,14 @@ describe("OpenSiteTree", () => {
   });
 
   test("can return a new tree for a key that redirects", async () => {
-    const fixture = new OpenSiteTree(mockHost);
+    const fixture = new ExplorableSiteTree(mockHost);
     const about = await fixture.get("about");
-    assert(about instanceof OpenSiteTree);
+    assert(about instanceof ExplorableSiteTree);
     assert.equal(about.href, "https://mock/about/");
   });
 
   test("can convert a site to a plain object", async () => {
-    const fixture = new OpenSiteTree(mockHost);
+    const fixture = new ExplorableSiteTree(mockHost);
     // Convert buffers to strings.
     const strings = Tree.map(fixture, (value) => textDecoder.decode(value));
     assert.deepEqual(await Tree.plain(strings), {