@weborigami/async-tree 0.0.40 → 0.0.42

package/main.js

@@ -6,6 +6,7 @@ export { default as FunctionTree } from "./src/FunctionTree.js";
 export { default as MapTree } from "./src/MapTree.js";
 export { default as ObjectTree } from "./src/ObjectTree.js";
 // Skip BrowserFileTree.js, which is browser-only.
+export { default as DeepMapTree } from "./src/DeepMapTree.js";
 export { default as DeepObjectTree } from "./src/DeepObjectTree.js";
 export { default as SetTree } from "./src/SetTree.js";
 export { default as SiteTree } from "./src/SiteTree.js";

package/package.json

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

package/src/DeepMapTree.js

@@ -0,0 +1,23 @@
+import MapTree from "./MapTree.js";
+import * as Tree from "./Tree.js";
+
+export default class DeepMapTree extends MapTree {
+  async get(key) {
+    let value = await super.get(key);
+
+    if (value instanceof Map) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+
+    if (Tree.isAsyncTree(value) && !value.parent) {
+      value.parent = this;
+    }
+
+    return value;
+  }
+
+  async isKeyForSubtree(key) {
+    const value = this.map.get[key];
+    return value instanceof Map || Tree.isAsyncTree(value);
+  }
+}

package/src/DeferredTree.js

@@ -50,6 +50,23 @@ export default class DeferredTree {
     }
   }
 
+  // HACK: The concept of scope is defined in Origami, not at the AsyncTree
+  // level. If a DeferredTree is used to wrap an OrigamiTree, the inner
+  // OrigamiTree will have a `scope` but not a `parent`. If someone asks the
+  // outer deferrred tree for a scope, they'd otherwise get `undefined`, which
+  // is incorrect. As a workaround, we introduce a `scope` getter here that
+  // defers to the inner tree, but we need to find a way to avoid having to
+  // introduce the concept of scope here.
+  get scope() {
+    return /** @type {any} */ (this._tree)?.scope;
+  }
+  set scope(scope) {
+    // If tree hasn't been loaded yet, setting scope has no effect.
+    if (this._tree) {
+      /** @type {any} */ (this._tree).scope = scope;
+    }
+  }
+
   async tree() {
     if (this._tree) {
       return this._tree;

package/src/FileTree.js

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import * as Tree from "./Tree.js";
 import {
   getRealmObjectPrototype,
@@ -18,11 +18,25 @@ const TypedArray = Object.getPrototypeOf(Uint8Array);
  */
 export default class FileTree {
   /**
-   * @param {string} location
+   * @param {string|URL} location
    */
   constructor(location) {
+    if (location instanceof URL) {
+      location = location.href;
+    } else if (
+      !(
+        typeof location === "string" ||
+        /** @type {any} */ (location) instanceof String
+      )
+    ) {
+      throw new TypeError(
+        `FileTree constructor needs a string or URL, received an instance of ${
+          /** @type {any} */ (location)?.constructor?.name
+        }`
+      );
+    }
     this.dirname = location.startsWith("file://")
-      ? path.dirname(fileURLToPath(location))
+      ? fileURLToPath(location)
       : path.resolve(process.cwd(), location);
     this.parent = null;
   }
@@ -154,6 +168,10 @@ export default class FileTree {
 
     return this;
   }
+
+  get url() {
+    return pathToFileURL(this.dirname);
+  }
 }
 
 /**

package/src/FunctionTree.js

@@ -23,7 +23,8 @@ export default class FunctionTree {
   async get(key) {
     const value =
       this.fn.length <= 1
-        ? // Function takes no arguments or only one argument: invoke
+        ? // Function takes no arguments, one argument, or a variable number of
+          // arguments: invoke it.
           await this.fn.call(null, key)
         : // Bind the key to the first parameter. Subsequent get calls will
           // eventually bind all parameters until only one remains. At that point,

package/src/SiteTree.js

@@ -2,7 +2,9 @@ import * as Tree from "./Tree.js";
 import * as keysJson from "./keysJson.js";
 
 /**
- * An HTTP/HTTPS site as a tree of ArrayBuffers.
+ * A tree of values obtained via HTTP/HTTPS calls. These values will be strings
+ * for HTTP responses with a MIME text type; otherwise they will be ArrayBuffer
+ * instances.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @implements {AsyncTree}
@@ -64,7 +66,10 @@ export default class SiteTree {
       }
     }
 
-    return response.arrayBuffer();
+    const mediaType = response.headers?.get("Content-Type");
+    return SiteTree.mediaTypeIsText(mediaType)
+      ? response.text()
+      : response.arrayBuffer();
   }
 
   async getKeyDictionary() {
@@ -106,6 +111,36 @@ export default class SiteTree {
     return keyDictionary ? Object.keys(keyDictionary) : [];
   }
 
+  // Return true if the given media type is a standard text type.
+  static mediaTypeIsText(mediaType) {
+    if (!mediaType) {
+      return false;
+    }
+    const regex = /^(?<type>[^/]+)\/(?<subtype>[^;]+)/;
+    const match = mediaType.match(regex);
+    if (!match) {
+      return false;
+    }
+    const { type, subtype } = match.groups;
+    if (type === "text") {
+      return true;
+    } else if (type === "application") {
+      return (
+        subtype === "json" ||
+        subtype.endsWith("+json") ||
+        subtype.endsWith(".json") ||
+        subtype === "xml" ||
+        subtype.endsWith("+xml") ||
+        subtype.endsWith(".xml")
+      );
+    }
+    return false;
+  }
+
+  get path() {
+    return this.href;
+  }
+
   /**
    * Returns a new `SiteTree` for the given relative route.
    *
@@ -121,4 +156,8 @@ export default class SiteTree {
     const response = await fetch(this.href);
     return response.ok ? response.arrayBuffer() : undefined;
   }
+
+  get url() {
+    return new URL(this.href);
+  }
 }

package/src/Tree.js

@@ -18,6 +18,8 @@ import { castArrayLike, isPlainObject } from "./utilities.js";
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  */
 
+const treeModule = this;
+
 /**
  * Apply the key/values pairs from the source tree to the target tree.
  *
@@ -331,45 +333,72 @@ export async function traverse(treelike, ...keys) {
  * Return the value at the corresponding path of keys. Throw if any interior
  * step of the path doesn't lead to a result.
  *
+ * @this {AsyncTree|null|undefined}
  * @param {Treelike} treelike
  * @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;
 
-  // Process each key in turn.
-  // If the value is ever undefined, short-circuit the traversal.
+  // If traversal operation was called with a `this` context, use that as the
+  // target for function calls.
+  const target = this === treeModule ? undefined : this;
+
+  // Process all the keys.
   const remainingKeys = keys.slice();
+  let key;
   while (remainingKeys.length > 0) {
     if (value === undefined) {
-      const keyStrings = keys.map((key) => String(key));
-      throw new TraverseError(
-        `Couldn't traverse the path: ${keyStrings.join("/")}`,
-        value,
-        keys
-      );
+      // 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);
     }
 
-    // Get the next key.
-    const key = remainingKeys.shift();
-
-    // An empty string as the last key is a special case.
-    if (key === "" && remainingKeys.length === 0) {
+    // Special case: one key left that's an empty string
+    if (remainingKeys.length === 1 && remainingKeys[0] === "") {
       // Unpack the value if it defines an `unpack` function, otherwise return
       // the value itself.
-      value = typeof value.unpack === "function" ? await value.unpack() : value;
-      continue;
+      return typeof value.unpack === "function" ? await value.unpack() : value;
     }
 
-    // Someone is trying to traverse the value, so they mean to treat it as a
-    // tree. If it's not already a tree, cast it to one.
-    const tree = from(value);
+    // If the value is not a function or async tree already, but can be
+    // unpacked, unpack it.
+    if (
+      !(value instanceof Function) &&
+      !isAsyncTree(value) &&
+      value.unpack instanceof Function
+    ) {
+      value = await value.unpack();
+    }
 
-    // Get the value for the key.
-    value = await tree.get(key);
+    if (value instanceof Function) {
+      // Value is a function: call it with the remaining keys.
+      const fn = value;
+      // We'll take as many keys as the function's length, but at least one.
+      let fnKeyCount = Math.max(fn.length, 1);
+      const args = remainingKeys.splice(0, fnKeyCount);
+      key = null;
+      value = await fn.call(target, ...args);
+    } else {
+      // Value is some other treelike object: cast it to a tree.
+      const tree = from(value);
+      // Get the next key.
+      key = remainingKeys.shift();
+      // Get the value for the key.
+      value = await tree.get(key);
+    }
   }
+
   return value;
 }
 

package/test/Tree.test.js

@@ -285,6 +285,13 @@ describe("Tree", () => {
     );
   });
 
+  test("traverse() a function with fixed number of arguments", async () => {
+    const tree = (a, b) => ({
+      c: "Result",
+    });
+    assert.equal(await Tree.traverse(tree, "a", "b", "c"), "Result");
+  });
+
   test("traverse() from one tree into another", async () => {
     const tree = new ObjectTree({
       a: {
@@ -298,15 +305,13 @@ describe("Tree", () => {
   });
 
   test("traversing a final empty string can unpack the last value", async () => {
-    class Unpackable {
-      unpack() {
-        return "Content";
-      }
-    }
-    const unpackable = new Unpackable();
-    const tree = new ObjectTree({
-      unpackable,
-    });
+    const tree = {
+      unpackable: {
+        unpack() {
+          return "Content";
+        },
+      },
+    };
     const result = await Tree.traverse(tree, "unpackable", "");
     assert.equal(result, "Content");
   });