@weborigami/async-tree 0.5.7 → 0.6.0

package/src/drivers/ObjectMap.js

@@ -0,0 +1,139 @@
+import * as symbols from "../symbols.js";
+import * as trailingSlash from "../trailingSlash.js";
+import setParent from "../utilities/setParent.js";
+import SyncMap from "./SyncMap.js";
+
+export default class ObjectMap extends SyncMap {
+  constructor(object = {}) {
+    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;
+  }
+
+  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);
+    }
+
+    return value;
+  }
+
+  /** @returns {boolean} */
+  isSubtree(value) {
+    return value instanceof Map;
+  }
+
+  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];
+    }
+
+    if (value === /** @type {any} */ (this.constructor).EMPTY) {
+      // Create empty subtree
+      value = Reflect.construct(this.constructor, []);
+    }
+
+    // Set the value for the key.
+    this.object[key] = value;
+
+    return this;
+  }
+
+  get trailingSlashKeys() {
+    return 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.
@@ -44,11 +43,6 @@ export default class SiteTree {
       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,10 @@ export default class SiteTree {
     }
   }
 
+  get trailingSlashKeys() {
+    return true;
+  }
+
   get url() {
     return new URL(this.href);
   }

package/src/drivers/SyncMap.js

@@ -0,0 +1,245 @@
+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.
+ */
+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;
+  }
+
+  /**
+   * 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);
+  }
+
+  static EMPTY = Symbol("EMPTY");
+
+  /**
+   * 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;
+
+    // Support EMPTY symbol to create empty subtrees
+    if (value === /** @type {any} */ (this.constructor).EMPTY) {
+      value = Reflect.construct(this.constructor, []);
+    }
+
+    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();
+  }
+
+  /**
+   * 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,5 @@
 import from from "./operations/from.js";
+import keys from "./operations/keys.js";
 
 /**
  * Given a tree node, return a JSON string that can be written to a .keys.json
@@ -11,11 +12,11 @@ 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 = await keys(tree);
   // 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;
 }

package/src/operations/addNextPrevious.js

@@ -1,57 +1,56 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import entries from "./entries.js";
-import isTreelike from "./isTreelike.js";
-import plain from "./plain.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
- * Add nextKey/previousKey properties to values.
+ * Return a map that adds nextKey/previousKey properties to values.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").PlainObject} PlainObject
- *
- * @param {import("../../index.ts").Treelike} treelike
- * @returns {Promise<PlainObject|Array>}
+ * @param {import("../../index.ts").Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function addNextPrevious(treelike) {
-  const tree = await getTreeArgument(treelike, "addNextPrevious");
+export default async function addNextPrevious(maplike) {
+  const source = await getMapArgument(maplike, "addNextPrevious");
+  let sourceKeys;
 
-  const treeEntries = [...(await entries(tree))];
-  const keys = treeEntries.map(([key]) => key);
+  return Object.assign(new AsyncMap(), {
+    async get(key) {
+      const sourceValue = await source.get(key);
+      if (sourceValue === undefined) {
+        return undefined;
+      }
 
-  // Map to an array of [key, result] pairs, where the result includes
-  // nextKey/previousKey properties.
-  const mappedEntries = await Promise.all(
-    treeEntries.map(async ([key, value], index) => {
-      let resultValue;
-      if (value === undefined) {
-        resultValue = undefined;
-      } else if (isTreelike(value)) {
-        resultValue = await plain(value);
-      } else if (typeof value === "object") {
-        // Clone value to avoid modifying the original object
-        resultValue = { ...value };
+      const resultValue = {};
+      if (typeof sourceValue === "object") {
+        // Copy to avoid modifying the original object
+        Object.assign(resultValue, sourceValue);
       } else {
         // Take the object as the `value` property
-        resultValue = { value };
+        resultValue.value = sourceValue;
       }
 
-      if (resultValue) {
+      // Find the index of the current key
+      sourceKeys ??= await keys(source);
+      const index = sourceKeys.indexOf(key);
+      if (index >= 0) {
         // Extend result with nextKey/previousKey properties.
-        const nextKey = keys[index + 1];
+        const nextKey = sourceKeys[index + 1];
         if (nextKey) {
           resultValue.nextKey = nextKey;
         }
-        const previousKey = keys[index - 1];
+        const previousKey = sourceKeys[index - 1];
         if (previousKey) {
           resultValue.previousKey = previousKey;
         }
       }
 
-      return [key, resultValue];
-    })
-  );
+      return resultValue;
+    },
+
+    async *keys() {
+      sourceKeys ??= await keys(source);
+      yield* sourceKeys;
+    },
 
-  return treelike instanceof Array
-    ? mappedEntries.map(([_, value]) => value)
-    : Object.fromEntries(mappedEntries);
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/assign.js

@@ -1,6 +1,5 @@
-import from from "./from.js";
-import isAsyncMutableTree from "./isAsyncMutableTree.js";
-import isAsyncTree from "./isAsyncTree.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Apply the key/values pairs from the source tree to the target tree.
@@ -9,32 +8,42 @@ import isAsyncTree from "./isAsyncTree.js";
  * subtrees, then the subtrees will be merged recursively. Otherwise, the
  * value from the source tree will overwrite the value in the target tree.
  *
- * @typedef  {import("../../index.ts").Treelike} Treelike
+ * @typedef  {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} target
- * @param {Treelike} source
+ * @param {Maplike} target
+ * @param {Maplike} source
  */
 export default async function assign(target, source) {
-  const targetTree = from(target);
-  const sourceTree = from(source);
-  if (!isAsyncMutableTree(targetTree)) {
+  const targetTree = await getMapArgument(target, "assign", { position: 0 });
+  const sourceTree = await getMapArgument(source, "assign", { position: 1 });
+  if ("readOnly" in targetTree && targetTree.readOnly) {
     throw new TypeError("Target must be a mutable asynchronous tree");
   }
   // Fire off requests to update all keys, then wait for all of them to finish.
-  const keys = Array.from(await sourceTree.keys());
-  const promises = keys.map(async (key) => {
-    const sourceValue = await sourceTree.get(key);
-    if (isAsyncTree(sourceValue)) {
-      const targetValue = await targetTree.get(key);
-      if (isAsyncMutableTree(targetValue)) {
-        // Both source and target are trees; recurse.
+  const promises = [];
+  for await (const key of sourceTree.keys()) {
+    const promise = (async () => {
+      const sourceValue = await sourceTree.get(key);
+
+      if (isMaplike(sourceValue)) {
+        let targetValue = await targetTree.get(key);
+        if (targetValue === undefined) {
+          // Target key doesn't exist; create empty subtree
+          /** @type {any} */
+          const targetClass = targetTree.constructor;
+          const empty = targetClass.EMPTY ?? new targetClass();
+          await targetTree.set(key, empty);
+          targetValue = await targetTree.get(key);
+        }
+        // Recurse to copy subtree
         await assign(targetValue, sourceValue);
-        return;
+      } else {
+        // Copy the value from the source to the target.
+        await targetTree.set(key, sourceValue);
       }
-    }
-    // Copy the value from the source to the target.
-    await /** @type {any} */ (targetTree).set(key, sourceValue);
-  });
+    })();
+    promises.push(promise);
+  }
   await Promise.all(promises);
   return targetTree;
 }