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

package/main.js

@@ -6,6 +6,7 @@ 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 cache } from "./src/operations/cache.js";
@@ -25,6 +26,7 @@ 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 * as trailingSlash from "./src/trailingSlash.js";
 export { default as cachedKeyFunctions } from "./src/transforms/cachedKeyFunctions.js";
 export { default as deepReverse } from "./src/transforms/deepReverse.js";
 export { default as invokeFunctions } from "./src/transforms/invokeFunctions.js";

package/package.json

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

package/src/BrowserFileTree.js

@@ -1,3 +1,4 @@
+import * as trailingSlash from "../src/trailingSlash.js";
 import { Tree } from "./internal.js";
 import {
   hiddenFileNames,
@@ -40,10 +41,17 @@ export default class BrowserFileTree {
         `${this.constructor.name}: Cannot get a null or undefined key.`
       );
     }
+    if (key === "") {
+      // Can't have a file with no name
+      return undefined;
+    }
+
+    // Remove trailing slash if present
+    key = trailingSlash.remove(key);
 
     const directory = await this.getDirectory();
 
-    // Try the key as a subfolder name.
+    // Try the key as a subfolder name
     try {
       const subfolderHandle = await directory.getDirectoryHandle(key);
       const value = Reflect.construct(this.constructor, [subfolderHandle]);
@@ -60,7 +68,7 @@ export default class BrowserFileTree {
       }
     }
 
-    // Try the key as a file name.
+    // Try the key as a file name
     try {
       const fileHandle = await directory.getFileHandle(key);
       const file = await fileHandle.getFile();
@@ -76,6 +84,8 @@ export default class BrowserFileTree {
     return undefined;
   }
 
+  // Return the directory handle, creating it if necessary. We can't create the
+  // default value in the constructor because we need to await it.
   async getDirectory() {
     this.directory ??= await navigator.storage.getDirectory();
     return this.directory;
@@ -85,9 +95,18 @@ export default class BrowserFileTree {
     const directory = await this.getDirectory();
     let keys = [];
     // @ts-ignore
-    for await (const key of directory.keys()) {
+    for await (const entryKey of directory.keys()) {
+      // Check if the entry is a subfolder
+      const baseKey = trailingSlash.remove(entryKey);
+      const subfolderHandle = await directory
+        .getDirectoryHandle(baseKey)
+        .catch(() => null);
+      const isSubfolder = subfolderHandle !== null;
+
+      const key = trailingSlash.toggle(entryKey, isSubfolder);
       keys.push(key);
     }
+
     // Filter out unhelpful file names.
     keys = keys.filter((key) => !hiddenFileNames.includes(key));
     keys.sort(naturalOrder);
@@ -96,12 +115,13 @@ export default class BrowserFileTree {
   }
 
   async set(key, value) {
+    const baseKey = trailingSlash.remove(key);
     const directory = await this.getDirectory();
 
     if (value === undefined) {
       // Delete file.
       try {
-        await directory.removeEntry(key);
+        await directory.removeEntry(baseKey);
       } catch (error) {
         // If the file didn't exist, ignore the error.
         if (
@@ -133,13 +153,15 @@ export default class BrowserFileTree {
 
     if (isWriteable) {
       // Write file.
-      const fileHandle = await directory.getFileHandle(key, { create: true });
+      const fileHandle = await directory.getFileHandle(baseKey, {
+        create: true,
+      });
       const writable = await fileHandle.createWritable();
       await writable.write(value);
       await writable.close();
     } else if (Tree.isTreelike(value)) {
       // Treat value as a tree and write it out as a subdirectory.
-      const subdirectory = await directory.getDirectoryHandle(key, {
+      const subdirectory = await directory.getDirectoryHandle(baseKey, {
         create: true,
       });
       const destTree = Reflect.construct(this.constructor, [subdirectory]);

package/src/DeepMapTree.js

@@ -16,8 +16,8 @@ export default class DeepMapTree extends MapTree {
     return value;
   }
 
-  async isKeyForSubtree(key) {
-    const value = this.map.get[key];
+  /** @returns {boolean} */
+  isSubtree(value) {
     return value instanceof Map || Tree.isAsyncTree(value);
   }
 }

package/src/DeepObjectTree.js

@@ -4,19 +4,16 @@ import { isPlainObject } from "./utilities.js";
 export default class DeepObjectTree extends ObjectTree {
   async get(key) {
     let value = await super.get(key);
-
-    const isPlain =
-      value instanceof Array ||
-      (isPlainObject(value) && !Tree.isAsyncTree(value));
-    if (isPlain) {
+    if (value instanceof Array || isPlainObject(value)) {
       value = Reflect.construct(this.constructor, [value]);
     }
-
     return value;
   }
 
-  async isKeyForSubtree(key) {
-    const value = await this.object[key];
-    return isPlainObject(value) || Tree.isAsyncTree(value);
+  /** @returns {boolean} */
+  isSubtree(value) {
+    return (
+      value instanceof Array || isPlainObject(value) || Tree.isAsyncTree(value)
+    );
   }
 }

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/ExplorableSiteTree.js

@@ -0,0 +1,52 @@
+import SiteTree from "./SiteTree.js";
+
+/**
+ * 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;
+  }
+
+  async getServerKeys() {
+    // We use a promise to ensure we only check for keys once.
+    const href = new URL(".keys.json", this.href).href;
+    this.serverKeysPromise ??= fetch(href)
+      .then((response) => (response.ok ? response.text() : null))
+      .then((text) => {
+        try {
+          return text ? JSON.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,
+          // but hasn't set the correct 404 status code.
+          return null;
+        }
+      });
+    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 ?? [];
+  }
+
+  processResponse(response) {
+    // If the response was redirected to a route that ends with a slash, and the
+    // site is an explorable site, we return a tree for the new route.
+    if (response.ok && response.redirected && response.url.endsWith("/")) {
+      return Reflect.construct(this.constructor, [response.url]);
+    }
+
+    return super.processResponse(response);
+  }
+}

package/src/FileTree.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Tree } from "./internal.js";
+import * as trailingSlash from "./trailingSlash.js";
 import {
   getRealmObjectPrototype,
   hiddenFileNames,
@@ -50,12 +51,18 @@ export default class FileTree {
 
   async get(key) {
     if (key == null) {
-      // Reject nullish key.
+      // Reject nullish key
       throw new ReferenceError(
         `${this.constructor.name}: Cannot get a null or undefined key.`
       );
     }
+    if (key === "") {
+      // Can't have a file with no name
+      return undefined;
+    }
 
+    // Remove trailing slash if present
+    key = trailingSlash.remove(key);
     const filePath = path.resolve(this.dirname, key);
 
     let stats;
@@ -73,7 +80,7 @@ export default class FileTree {
       // Return subdirectory as a tree
       value = Reflect.construct(this.constructor, [filePath]);
     } else {
-      // Return file contents as a standard Uint8Array.
+      // Return file contents as a standard Uint8Array
       const buffer = await fs.readFile(filePath);
       value = Uint8Array.from(buffer);
     }
@@ -82,12 +89,6 @@ export default class FileTree {
     return value;
   }
 
-  async isKeyForSubtree(key) {
-    const filePath = path.join(this.dirname, key);
-    const stats = await stat(filePath);
-    return stats ? stats.isDirectory() : false;
-  }
-
   /**
    * Enumerate the names of the files/subdirectories in this directory.
    */
@@ -102,7 +103,9 @@ export default class FileTree {
       entries = [];
     }
 
-    let names = entries.map((entry) => entry.name);
+    let names = entries.map((entry) =>
+      trailingSlash.toggle(entry.name, entry.isDirectory())
+    );
 
     // Filter out unhelpful file names.
     names = names.filter((name) => !hiddenFileNames.includes(name));
@@ -121,7 +124,8 @@ export default class FileTree {
   async set(key, value) {
     // Where are we going to write this value?
     const stringKey = key != null ? String(key) : "";
-    const destPath = path.resolve(this.dirname, stringKey);
+    const baseKey = trailingSlash.remove(stringKey);
+    const destPath = path.resolve(this.dirname, baseKey);
 
     if (value === undefined) {
       // Delete the file or directory.

package/src/MapTree.js

@@ -1,4 +1,5 @@
 import { Tree } from "./internal.js";
+import * as trailingSlash from "./trailingSlash.js";
 import { setParent } from "./utilities.js";
 
 /**
@@ -23,18 +24,40 @@ export default class MapTree {
   }
 
   async get(key) {
-    const value = this.map.get(key);
+    // Try key as is
+    let value = this.map.get(key);
+    if (value === undefined) {
+      // Try the other variation of the key
+      const alternateKey = trailingSlash.toggle(key);
+      value = this.map.get(alternateKey);
+      if (value === undefined) {
+        // Key doesn't exist
+        return undefined;
+      }
+    }
+
+    value = await value;
+
+    if (value === undefined) {
+      // Key exists but value is undefined
+      return undefined;
+    }
+
     setParent(value, this);
     return value;
   }
 
-  async isKeyForSubtree(key) {
-    const value = this.map.get(key);
+  /** @returns {boolean} */
+  isSubtree(value) {
     return Tree.isAsyncTree(value);
   }
 
   async keys() {
-    return this.map.keys();
+    const keys = [];
+    for (const [key, value] of this.map.entries()) {
+      keys.push(trailingSlash.toggle(key, this.isSubtree(value)));
+    }
+    return keys;
   }
 
   async set(key, value) {

package/src/ObjectTree.js

@@ -1,5 +1,6 @@
 import { Tree } from "./internal.js";
 import * as symbols from "./symbols.js";
+import * as trailingSlash from "./trailingSlash.js";
 import { getRealmObjectPrototype, setParent } from "./utilities.js";
 
 /**
@@ -32,7 +33,20 @@ export default class ObjectTree {
       );
     }
 
-    let value = await this.object[key];
+    // Does the object have the key with or without a trailing slash?
+    const existingKey = findExistingKey(this.object, key);
+    if (existingKey === null) {
+      // Key doesn't exist
+      return undefined;
+    }
+
+    let value = await this.object[existingKey];
+
+    if (value === undefined) {
+      // Key exists but value is undefined
+      return undefined;
+    }
+
     setParent(value, this);
 
     if (typeof value === "function" && !Object.hasOwn(this.object, key)) {
@@ -43,8 +57,8 @@ export default class ObjectTree {
     return value;
   }
 
-  async isKeyForSubtree(key) {
-    const value = await this.object[key];
+  /** @returns {boolean} */
+  isSubtree(value) {
     return Tree.isAsyncTree(value);
   }
 
@@ -67,7 +81,17 @@ export default class ObjectTree {
             (descriptor.enumerable ||
               (descriptor.get !== undefined && descriptor.set !== undefined))
         )
-        .map(([name]) => name);
+        .map(([name, descriptor]) =>
+          trailingSlash.has(name)
+            ? // Preserve existing slash
+              name
+            : // Add a slash if the value is a plain property and a subtree
+              trailingSlash.toggle(
+                name,
+                descriptor.value !== undefined &&
+                  this.isSubtree(descriptor.value)
+              )
+        );
       for (const name of propertyNames) {
         result.add(name);
       }
@@ -83,13 +107,36 @@ export default class ObjectTree {
    * @param {any} value
    */
   async set(key, value) {
+    const existingKey = findExistingKey(this.object, key);
+
     if (value === undefined) {
-      // Delete the key.
-      delete this.object[key];
+      // Delete the key if it exists.
+      if (existingKey !== null) {
+        delete this.object[existingKey];
+      }
     } else {
+      // If the key exists under a different form, delete the existing key.
+      if (existingKey !== null && existingKey !== key) {
+        delete this.object[existingKey];
+      }
+
       // Set the value for the key.
       this.object[key] = value;
     }
+
     return this;
   }
 }
+
+function findExistingKey(object, key) {
+  // First try key as is
+  if (key in object) {
+    return key;
+  }
+  // Try alternate form
+  const alternateKey = trailingSlash.toggle(key);
+  if (alternateKey in object) {
+    return alternateKey;
+  }
+  return null;
+}

package/src/SetTree.js

@@ -1,4 +1,3 @@
-import { Tree } from "./internal.js";
 import { setParent } from "./utilities.js";
 
 /**
@@ -29,11 +28,6 @@ export default class SetTree {
     return value;
   }
 
-  async isKeyForSubtree(key) {
-    const value = this.values[key];
-    return Tree.isAsyncTree(value);
-  }
-
   async keys() {
     return this.values.keys();
   }

package/src/SiteTree.js

@@ -1,5 +1,4 @@
-import { Tree } from "./internal.js";
-import * as jsonKeys from "./jsonKeys.js";
+import * as trailingSlash from "./trailingSlash.js";
 import { setParent } from "./utilities.js";
 
 /**
@@ -20,16 +19,14 @@ export default class SiteTree {
       href = new URL(href, window.location.href).href;
     }
 
-    if (!href.endsWith("/")) {
-      // Add trailing slash; the URL is expected to represent a directory.
-      href += "/";
-    }
+    // Add trailing slash if not present; URL should represent a directory.
+    href = trailingSlash.add(href);
 
     this.href = href;
-    this.keysPromise = undefined;
     this.parent = null;
   }
 
+  /** @returns {Promise<any>} */
   async get(key) {
     if (key == null) {
       // Reject nullish key.
@@ -38,25 +35,16 @@ export default class SiteTree {
       );
     }
 
-    // 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
-    // that necessitates an extra network request per SiteTree instance. In many
-    // cases, that can be avoided.
-    if (key === "" && (await this.hasKeysJson())) {
-      key = "index.html";
-    }
-
-    const href = new URL(key, this.href).href;
-
-    // If the (possibly adjusted) route ends with a slash and the site is an
-    // explorable site, we return a tree for the indicated route.
-    if (href.endsWith("/") && (await this.hasKeysJson())) {
+    // If the keys ends with a slash, return a tree for the indicated route.
+    if (trailingSlash.has(key)) {
+      const href = new URL(key, this.href).href;
       const value = Reflect.construct(this.constructor, [href]);
       setParent(value, this);
       return value;
     }
 
+    const href = new URL(key, this.href).href;
+
     // Fetch the data at the given route.
     let response;
     try {
@@ -64,65 +52,20 @@ export default class SiteTree {
     } catch (error) {
       return undefined;
     }
-    if (!response.ok) {
-      return undefined;
-    }
-
-    if (response.redirected && response.url.endsWith("/")) {
-      // If the response is redirected to a route that ends with a slash, and
-      // the site is an explorable site, we return a tree for the new route.
-      if (await this.hasKeysJson()) {
-        return Reflect.construct(this.constructor, [response.url]);
-      }
-    }
-
-    const mediaType = response.headers?.get("Content-Type");
-    if (SiteTree.mediaTypeIsText(mediaType)) {
-      return response.text();
-    } else {
-      const buffer = response.arrayBuffer();
-      setParent(buffer, this);
-      return buffer;
-    }
-  }
-
-  async getKeyDictionary() {
-    // We use a promise to ensure we only check for keys once.
-    const href = new URL(".keys.json", this.href).href;
-    this.keysPromise ??= fetch(href)
-      .then((response) => (response.ok ? response.text() : null))
-      .then((text) => {
-        try {
-          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,
-          // but hasn't set the correct 404 status code.
-          return null;
-        }
-      });
-    return this.keysPromise;
-  }
 
-  async hasKeysJson() {
-    const keyDictionary = await this.getKeyDictionary();
-    return keyDictionary !== null;
-  }
-
-  async isKeyForSubtree(key) {
-    const keyDictionary = await this.getKeyDictionary();
-    if (keyDictionary) {
-      return keyDictionary[key];
-    } else {
-      // Expensive check, since this fetches the key's value.
-      const value = await this.get(key);
-      return Tree.isAsyncTree(value);
-    }
+    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() {
-    const keyDictionary = await this.getKeyDictionary();
-    return keyDictionary ? Object.keys(keyDictionary) : [];
+    return [];
   }
 
   // Return true if the given media type is a standard text type.
@@ -155,15 +98,19 @@ export default class SiteTree {
     return this.href;
   }
 
-  /**
-   * Returns a new `SiteTree` for the given relative route.
-   *
-   * @param {string} path
-   * @returns {SiteTree}
-   */
-  resolve(path) {
-    const href = new URL(path, this.href).href;
-    return Reflect.construct(this.constructor, [href]);
+  processResponse(response) {
+    if (!response.ok) {
+      return undefined;
+    }
+
+    const mediaType = response.headers?.get("Content-Type");
+    if (SiteTree.mediaTypeIsText(mediaType)) {
+      return response.text();
+    } else {
+      const buffer = response.arrayBuffer();
+      setParent(buffer, this);
+      return buffer;
+    }
   }
 
   get url() {

package/src/Tree.d.ts

@@ -9,7 +9,6 @@ export function from(obj: any, options?: { deep?: boolean, parent?: AsyncTree|nu
 export function has(AsyncTree: AsyncTree, key: any): Promise<boolean>;
 export function isAsyncMutableTree(obj: any): obj is AsyncMutableTree;
 export function isAsyncTree(obj: any): obj is AsyncTree;
-export function isKeyForSubtree(tree: AsyncTree, obj: any): Promise<boolean>;
 export function isTraversable(obj: any): boolean;
 export function isTreelike(obj: any): obj is Treelike;
 export function map(tree: Treelike, valueFn: ValueKeyFn): AsyncTree;