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

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.67-beta.1",
   "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.67-beta.1"
   },
   "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/FileTree.js

@@ -190,8 +190,11 @@ export default class FileTree {
       // Special case: empty object means create an empty directory.
       await fs.mkdir(destPath, { recursive: true });
     } else if (Tree.isTreelike(value)) {
-      // Treat value as a tree and write it out as a subdirectory.
+      // Treat value as a subtree and write it out as a subdirectory.
       const destTree = Reflect.construct(this.constructor, [destPath]);
+      // Create the directory here, even if the subtree is empty.
+      await fs.mkdir(destPath, { recursive: true });
+      // Write out the subtree.
       await Tree.assign(destTree, value);
     } else {
       const typeName = value?.constructor?.name ?? "unknown";

package/src/SiteTree.js

@@ -35,14 +35,20 @@ export default class SiteTree {
       );
     }
 
-    // If the keys ends with a slash, return a tree for the indicated route.
-    if (trailingSlash.has(key)) {
+    // A key with a trailing slash and no extension is for a folder; return a
+    // subtree without making a network request.
+    if (trailingSlash.has(key) && !key.includes(".")) {
       const href = new URL(key, this.href).href;
       const value = Reflect.construct(this.constructor, [href]);
       setParent(value, this);
       return value;
     }
 
+    // HACK: For now we don't allow lookup of Origami extension handlers.
+    if (key.endsWith("_handler")) {
+      return undefined;
+    }
+
     const href = new URL(key, this.href).href;
 
     // Fetch the data at the given route.
@@ -56,6 +62,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/src/operations/cache.js

@@ -60,16 +60,22 @@ export default function treeCache(
       let value = await source.get(key);
       if (value !== undefined) {
         // If a filter is defined, does the key match the filter?
-        const filterValue = await filter?.get(key);
+        const filterValue = filter ? await filter.get(key) : undefined;
         const filterMatch = !filter || filterValue !== undefined;
         if (filterMatch) {
           if (Tree.isAsyncTree(value)) {
             // Construct merged tree for a tree result.
             if (cacheValue === undefined) {
-              // Construct new container in cache
-              cacheValue = new ObjectTree({});
-              cacheValue.parent = this;
-              await cache.set(key, cacheValue);
+              // Construct new empty container in cache
+              await cache.set(key, {});
+              cacheValue = await cache.get(key);
+              if (!Tree.isAsyncTree(cacheValue)) {
+                // Coerce to tree and then save it back to the cache. This is
+                // necessary, e.g., if cache is an ObjectTree; we want the
+                // subtree to also be an ObjectTree, not a plain object.
+                cacheValue = Tree.from(cacheValue);
+                await cache.set(key, cacheValue);
+              }
             }
             value = treeCache(value, cacheValue, filterValue);
           } else {

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), {

package/test/FileTree.test.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import FileTree from "../src/FileTree.js";
-import { Tree } from "../src/internal.js";
+import { ObjectTree, Tree } from "../src/internal.js";
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const tempDirectory = path.join(dirname, "fixtures/temp");
@@ -81,7 +81,7 @@ describe("FileTree", async () => {
     await removeTempDirectory();
   });
 
-  test("can create empty subfolder via set()", async () => {
+  test("create subfolder via set() with empty object value", async () => {
     await createTempDirectory();
 
     // Write out new, empty folder called "empty".
@@ -98,6 +98,23 @@ describe("FileTree", async () => {
     await removeTempDirectory();
   });
 
+  test("create subfolder via set() with empty tree value", async () => {
+    await createTempDirectory();
+
+    // Write out new, empty folder called "empty".
+    const tempFiles = new FileTree(tempDirectory);
+    await tempFiles.set("empty", new ObjectTree({}));
+
+    // Verify folder exists and has no contents.
+    const folderPath = path.join(tempDirectory, "empty");
+    const stats = await fs.stat(folderPath);
+    assert(stats.isDirectory());
+    const files = await fs.readdir(folderPath);
+    assert.deepEqual(files, []);
+
+    await removeTempDirectory();
+  });
+
   test("can write out subfolder via set()", async () => {
     await createTempDirectory();