@weborigami/async-tree 0.5.8 → 0.6.1

package/src/drivers/{FunctionTree.js → FunctionMap.js}

@@ -1,20 +1,14 @@
 import setParent from "../utilities/setParent.js";
+import SyncMap from "./SyncMap.js";
 
-/**
- * A tree defined by a function and an optional domain.
- *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @implements {AsyncTree}
- */
-export default class FunctionTree {
-  /**
-   * @param {function} fn the key->value function
-   * @param {Iterable<any>} [domain] optional domain of the function
-   */
+export default class FunctionMap extends SyncMap {
   constructor(fn, domain = []) {
+    if (typeof fn !== "function") {
+      throw new TypeError("FunctionMap: first argument must be a function");
+    }
+    super();
     this.fn = fn;
     this.domain = domain;
-    this.parent = null;
   }
 
   /**
@@ -22,25 +16,28 @@ export default class FunctionTree {
    *
    * @param {any} key
    */
-  async get(key) {
-    const value =
+  get(key) {
+    let value =
       this.fn.length <= 1
         ? // Function takes no arguments, one argument, or a variable number of
           // arguments: invoke it.
-          await this.fn(key)
+          this.fn(key)
         : // Bind the key to the first parameter. Subsequent get calls will
           // eventually bind all parameters until only one remains. At that point,
           // the above condition will apply and the function will be invoked.
           Reflect.construct(this.constructor, [this.fn.bind(null, key)]);
-    setParent(value, this);
+    if (value instanceof Promise) {
+      value = value.then((v) => {
+        setParent(v, this);
+        return v;
+      });
+    } else {
+      setParent(value, this);
+    }
     return value;
   }
 
-  /**
-   * Enumerates the function's domain (if defined) as the tree's keys. If no domain
-   * was defined, this returns an empty iterator.
-   */
-  async keys() {
-    return this.domain;
+  keys() {
+    return this.domain[Symbol.iterator]();
   }
 }

package/src/drivers/ObjectMap.js

@@ -0,0 +1,151 @@
+import * as symbols from "../symbols.js";
+import * as trailingSlash from "../trailingSlash.js";
+import isPlainObject from "../utilities/isPlainObject.js";
+import setParent from "../utilities/setParent.js";
+import SyncMap from "./SyncMap.js";
+
+/**
+ * Map wrapper for a JavaScript object or array
+ */
+export default class ObjectMap extends SyncMap {
+  /**
+   * Wrap the given object in a `Map`.
+   *
+   * @param {any} object
+   * @param {{ deep?: boolean }} [options]
+   */
+  constructor(object = {}, options = {}) {
+    super();
+    // Note: we use `typeof` here instead of `instanceof Object` to allow for
+    // objects such as Node's `Module` class for representing an ES module.
+    if (typeof object !== "object" || object === null) {
+      throw new TypeError(
+        `${this.constructor.name}: Expected an object or array.`
+      );
+    }
+    this.object = object;
+    this.parent = object[symbols.parent] ?? null;
+    this.deep = options.deep === true;
+  }
+
+  delete(key) {
+    const existingKey = findExistingKey(this.object, key);
+    if (existingKey === null) {
+      return false;
+    }
+    delete this.object[existingKey];
+    return true;
+  }
+
+  get(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 = this.object[existingKey];
+
+    if (value === undefined) {
+      // Key exists but value is undefined
+      return undefined;
+    }
+
+    setParent(value, this);
+
+    // Is value an instance method?
+    const isInstanceMethod =
+      value instanceof Function && !Object.hasOwn(this.object, key);
+    if (isInstanceMethod) {
+      // Bind it to the object
+      value = value.bind(this.object);
+    }
+
+    if (this.deep && (value instanceof Array || isPlainObject(value))) {
+      // Construct submap for sub-objects and sub-arrays
+      value = Reflect.construct(this.constructor, [value, { deep: true }]);
+    }
+
+    return value;
+  }
+
+  /** @returns {boolean} */
+  isSubtree(value) {
+    if (value instanceof Map) {
+      return true;
+    }
+    return this.deep && (value instanceof Array || isPlainObject(value));
+  }
+
+  keys() {
+    // Defer to symbols.keys if defined
+    if (typeof this.object[symbols.keys] === "function") {
+      return this.object[symbols.keys]();
+    }
+
+    const result = new Set();
+
+    // Walk up the prototype chain
+    for (
+      let current = this.object;
+      current !== null;
+      current = Object.getPrototypeOf(current)
+    ) {
+      // Look at all the properties at this level of the prototype chain
+      const descriptors = Object.getOwnPropertyDescriptors(current);
+      for (const [name, descriptor] of Object.entries(descriptors)) {
+        if (name === "constructor" || name === "__proto__") {
+          continue; // Uninteresting property
+        }
+        // Skip non-enumerable properties unless they have get/set
+        if (
+          !descriptor.enumerable &&
+          descriptor.get === undefined &&
+          descriptor.set === undefined
+        ) {
+          continue;
+        }
+        // Preserve existing slash; add slash for subtrees
+        const key = trailingSlash.has(name)
+          ? name
+          : trailingSlash.toggle(
+              name,
+              descriptor.value !== undefined && this.isSubtree(descriptor.value)
+            );
+        result.add(key);
+      }
+    }
+
+    return result[Symbol.iterator]();
+  }
+
+  set(key, value) {
+    const existingKey = findExistingKey(this.object, key);
+
+    // 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;
+  }
+
+  trailingSlashKeys = true;
+}
+
+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/drivers/SetMap.js

@@ -0,0 +1,13 @@
+import SyncMap from "./SyncMap.js";
+
+/**
+ * A map of Set objects.
+ */
+export default class SetMap extends SyncMap {
+  /**
+   * @param {Set} set
+   */
+  constructor(set) {
+    super(set.entries());
+  }
+}

package/src/drivers/{SiteTree.js → SiteMap.js}

@@ -1,19 +1,19 @@
 import * as trailingSlash from "../trailingSlash.js";
 import setParent from "../utilities/setParent.js";
+import AsyncMap from "./AsyncMap.js";
 
 /**
  * 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}
  */
-export default class SiteTree {
+export default class SiteMap extends AsyncMap {
   /**
    * @param {string} href
    */
   constructor(href = globalThis?.location.href) {
+    super();
+
     if (href?.startsWith(".") && globalThis?.location !== undefined) {
       // URL represents a relative path; concatenate with current location.
       href = new URL(href, globalThis.location.href).href;
@@ -23,10 +23,9 @@ export default class SiteTree {
     href = trailingSlash.add(href);
 
     this.href = href;
-    this.parent = null;
   }
 
-  /** @returns {Promise<any>} */
+  /** @returns {Promise<ArrayBuffer|string|undefined>} */
   async get(key) {
     if (key == null) {
       // Reject nullish key.
@@ -35,20 +34,15 @@ export default class SiteTree {
       );
     }
 
-    // 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(".")) {
+    // A key with a trailing slash is for a folder; return a subtree without
+    // making a network request.
+    if (trailingSlash.has(key)) {
       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.
@@ -65,13 +59,13 @@ export default class SiteTree {
   /**
    * Returns an empty set of keys.
    *
-   * For a variation of `SiteTree` that can return the keys for a site route,
-   * see [ExplorableSiteTree](ExplorableSiteTree.html).
+   * For a variation of `SiteMap` that can return the keys for a site route,
+   * see [ExplorableSiteMap](ExplorableSiteMap.html).
    *
-   * @returns {Promise<Iterable<string>>}
+   * @returns {AsyncIterableIterator<string>}
    */
-  async keys() {
-    return [];
+  async *keys() {
+    yield* [];
   }
 
   // Return true if the given media type is a standard text type.
@@ -102,13 +96,14 @@ export default class SiteTree {
     return this.href;
   }
 
+  /** @param {Response} response */
   processResponse(response) {
     if (!response.ok) {
       return undefined;
     }
 
     const mediaType = response.headers?.get("Content-Type");
-    if (SiteTree.mediaTypeIsText(mediaType)) {
+    if (SiteMap.mediaTypeIsText(mediaType)) {
       return response.text();
     } else {
       const buffer = response.arrayBuffer();
@@ -117,6 +112,8 @@ export default class SiteTree {
     }
   }
 
+  trailingSlashKeys = true;
+
   get url() {
     return new URL(this.href);
   }

package/src/drivers/SyncMap.js

@@ -0,0 +1,260 @@
+import * as trailingSlash from "../trailingSlash.js";
+import setParent from "../utilities/setParent.js";
+
+const previewSymbol = Symbol("preview");
+
+/**
+ * A base class for creating custom Map subclasses for use in trees.
+ *
+ * Instances of SyncMap (and its subclasses) pass `instanceof Map`, and all Map
+ * methods have compatible signatures.
+ *
+ * Subclasses may be read-only or read-write. A read-only subclass overrides
+ * get() but not set() or delete(). A read-write subclass overrides all three
+ * methods.
+ *
+ * For use in trees, SyncMap instances may indicate a `parent` node. They can
+ * also indicate children subtrees using the trailing slash convention: a key
+ * for a subtree may optionally end with a slash. The get() and has() methods
+ * support optional trailing slashes on keys.
+ *
+ * @typedef {import("../../index.ts").SyncTree<SyncMap>} SyncTree
+ * @implements {SyncTree}
+ */
+export default class SyncMap extends Map {
+  _initialized = false;
+
+  constructor(iterable) {
+    super(iterable);
+
+    /** @type {SyncMap|null} */
+    this._parent = null;
+
+    // Record self-reference for use in Map method calls that insist on the
+    // receiver being a Map instance. This allows method calls to work even when
+    // the prototype chain is extended via Object.create().
+    //
+    // We separately use this member to determine whether the constructor has
+    // been called to initialize the instance. See set().
+    this._self = this;
+  }
+
+  /**
+   * Return the child node for the given key, creating it if necessary.
+   */
+  child(key) {
+    let result = this.get(key);
+
+    // If child is already a map we can use it as is
+    if (!(result instanceof Map)) {
+      // Create new child node using no-arg constructor
+      result = new /** @type {any} */ (this.constructor)();
+      this.set(key, result);
+    }
+
+    result.parent = this;
+    return result;
+  }
+
+  /**
+   * Removes all key/value entries from the map.
+   *
+   * Unlike the standard `Map.prototype.clear()`, this method invokes an
+   * overridden `keys()` and `delete()` to ensure proper behavior in subclasses.
+   *
+   * If the `readOnly` property is true, calling this method throws a
+   * `TypeError`.
+   */
+  clear() {
+    if (this.readOnly) {
+      throw new TypeError("clear() can't be called on a read-only map");
+    }
+    for (const key of this.keys()) {
+      this.delete(key);
+    }
+  }
+
+  /**
+   * Removes the entry for the given key, return true if an entry was removed
+   * and false if there was no entry for the key.
+   *
+   * If the `readOnly` property is true, calling this method throws a
+   * `TypeError`.
+   */
+  delete(key) {
+    if (this.readOnly) {
+      throw new TypeError("delete() can't be called on a read-only map");
+    }
+    return super.delete.call(this._self, key);
+  }
+
+  /**
+   * Returns a new `Iterator` object that contains a two-member array of [key,
+   * value] for each element in the map in insertion order.
+   *
+   * Unlike the standard `Map.prototype.clear()`, this method invokes an
+   * overridden `keys()` and `get()` to ensure proper behavior in subclasses.
+   */
+  entries() {
+    // We'd like to just define entries() as a generator but TypeScript
+    // complains that it doesn't match the Map interface. We define the
+    // generator internally and then cast it to the expected type.
+    const self = this;
+    function* gen() {
+      for (const key of self.keys()) {
+        yield [key, self.get(key)];
+      }
+    }
+    return /** @type {MapIterator<[any, any]>} */ (gen());
+  }
+
+  /**
+   * Calls `callback` once for each key/value pair in the map, in insertion order.
+   *
+   * Unlike the standard `Map.prototype.forEach()`, this method invokes an
+   * overridden `entries()` to ensure proper behavior in subclasses.
+   *
+   * @param {(value: any, key: any, thisArg: any) => void} callback
+   * @param {any?} thisArg
+   */
+  forEach(callback, thisArg = this) {
+    for (const [key, value] of this.entries()) {
+      callback(value, key, thisArg);
+    }
+  }
+
+  /**
+   * Returns the value associated with the key, or undefined if there is none.
+   */
+  get(key) {
+    let value = super.get.call(this._self, key);
+    if (value === undefined) {
+      // Try alternate key with trailing slash added or removed
+      value = super.get.call(this._self, trailingSlash.toggle(key));
+    }
+    if (value === undefined) {
+      return undefined;
+    }
+    setParent(value, this);
+    return value;
+  }
+
+  /**
+   * Returns true if the given key appears in the set returned by keys().
+   *
+   * It doesn't matter whether the value returned by get() is defined or not.
+   *
+   * If the requested key has a trailing slash but has no associated value, but
+   * the alternate form with a slash does appear, this returns true.
+   *
+   * @param {any} key
+   */
+  has(key) {
+    const keys = Array.from(this.keys());
+    return (
+      keys.includes(key) ||
+      (!trailingSlash.has(key) && keys.includes(trailingSlash.add(key)))
+    );
+  }
+
+  /**
+   * Returns a new `Iterator` object that contains the keys for each element in
+   * the map in insertion order.
+   *
+   * @returns {MapIterator<any>}
+   */
+  keys() {
+    return super.keys.call(this._self);
+  }
+
+  /**
+   * The parent of this node in a tree.
+   */
+  get parent() {
+    return this._parent;
+  }
+  set parent(parent) {
+    this._parent = parent;
+  }
+
+  /**
+   * True if the object is read-only. This will be true if the `get()` method has
+   * been overridden but `set()` and `delete()` have not.
+   */
+  get readOnly() {
+    return (
+      this.get !== SyncMap.prototype.get &&
+      (this.set === SyncMap.prototype.set ||
+        this.delete === SyncMap.prototype.delete)
+    );
+  }
+
+  /**
+   * Adds a new entry with a specified key and value to this Map, or updates an
+   * existing entry if the key already exists.
+   *
+   * If the `readOnly` property is true, calling this method throws a `TypeError`.
+   */
+  set(key, value) {
+    // The Map constructor takes an optional `iterable` argument. If specified,
+    // then set() will be called during construction. We want to allow this to
+    // work even for read-only subclasses, so we allow set() to be called during
+    // initialization. Once the `_self` member is set, we know initialization is
+    // complete; after that point, calling set() on a read-only subclass will
+    // throw.
+    if (this._self !== undefined && this.readOnly) {
+      throw new TypeError("set() can't be called on a read-only map");
+    }
+    // If _self is not set, use the current instance as the receiver. This is
+    // necessary to let the constructor call `super()`.
+    const target = this._self ?? this;
+
+    return super.set.call(target, key, value);
+  }
+
+  /**
+   * Returns the number of keys in the map.
+   *
+   * The `size` property invokes an overridden `keys()` to ensure proper
+   * behavior in subclasses. Because a subclass may not enforce a direct
+   * correspondence between `keys()` and `get()`, the size may not reflect the
+   * number of values that can be retrieved.
+   */
+  get size() {
+    const keys = Array.from(this.keys());
+    return keys.length;
+  }
+
+  /**
+   * Returns the map's `entries()`.
+   */
+  [Symbol.iterator]() {
+    return this.entries();
+  }
+
+  trailingSlashKeys = false;
+
+  /**
+   * Returns a new `Iterator` object that contains the values for each element
+   * in the map in insertion order.
+   */
+  values() {
+    // See notes at entries()
+    const self = this;
+    function* gen() {
+      for (const key of self.keys()) {
+        yield self.get(key);
+      }
+    }
+    return /** @type {MapIterator<[any]>} */ (gen());
+  }
+}
+
+// For debugging we make entries() available as a gettable property.
+Object.defineProperty(SyncMap.prototype, previewSymbol, {
+  configurable: true,
+  enumerable: false,
+  get: function () {
+    return Array.from(this.entries());
+  },
+});

package/src/jsonKeys.d.ts

@@ -1,4 +1,4 @@
-import { Treelike } from "../index.ts";
+import { Maplike } from "../index.ts";
 
 export function parse(json: string): any;
-export function stringify(treelike: Treelike): Promise<string>;
+export function stringify(maplike: Maplike): Promise<string>;

package/src/jsonKeys.js

@@ -1,4 +1,8 @@
+import entries from "./operations/entries.js";
 import from from "./operations/from.js";
+import isMap from "./operations/isMap.js";
+import keys from "./operations/keys.js";
+import * as trailingSlash from "./trailingSlash.js";
 
 /**
  * Given a tree node, return a JSON string that can be written to a .keys.json
@@ -11,11 +15,22 @@ import from from "./operations/from.js";
  * "index.html" for a specific resource available at the node, or a string with
  * a trailing slash like "about/" for a subtree of that node.
  */
-export async function stringify(treelike) {
-  const tree = from(treelike);
-  let keys = Array.from(await tree.keys());
+export async function stringify(maplike) {
+  const tree = from(maplike);
+
+  let treeKeys;
+  if (/** @type {any} */ (tree).trailingSlashKeys) {
+    treeKeys = await keys(tree);
+  } else {
+    // Use entries() to determine which keys are subtrees.
+    const treeEntries = await entries(tree);
+    treeKeys = treeEntries.map(([key, value]) =>
+      trailingSlash.toggle(key, isMap(value))
+    );
+  }
+
   // Skip the key `.keys.json` if present.
-  keys = keys.filter((key) => key !== ".keys.json");
-  const json = JSON.stringify(keys);
+  treeKeys = treeKeys.filter((key) => key !== ".keys.json");
+  const json = JSON.stringify(treeKeys);
   return json;
 }