@weborigami/async-tree 0.0.35

package/src/ObjectTree.js

@@ -0,0 +1,103 @@
+import * as Tree from "./Tree.js";
+import { getRealmObjectPrototype, isPlainObject } from "./utilities.js";
+
+/**
+ * A tree defined by a plain object or array.
+ *
+ * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @implements {AsyncMutableTree}
+ */
+export default class ObjectTree {
+  /**
+   * Create a tree wrapping a given plain object or array.
+   *
+   * @param {any} object The object/array to wrap.
+   */
+  constructor(object) {
+    this.object = object;
+    this.parent = null;
+  }
+
+  /**
+   * Return the value for the given key.
+   *
+   * @param {any} key
+   */
+  async get(key) {
+    // If the value is an array, we require that the key be one of its own
+    // properties: we don't want to return Array prototype methods like `map`
+    // and `find`.
+    if (
+      this.object instanceof Array &&
+      key &&
+      !this.object.hasOwnProperty(key)
+    ) {
+      return undefined;
+    }
+
+    let value = this.object[key];
+
+    const isPlain =
+      value instanceof Array ||
+      (isPlainObject(value) && !Tree.isAsyncTree(value));
+    if (isPlain) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+
+    if (Tree.isAsyncTree(value) && !value.parent) {
+      value.parent = this;
+    }
+
+    return value;
+  }
+
+  async isKeyForSubtree(key) {
+    const value = this.object[key];
+    return isPlainObject(value) || Tree.isAsyncTree(value);
+  }
+
+  /**
+   * Enumerate the object's keys.
+   */
+  async keys() {
+    // Walk up the prototype chain to realm's Object.prototype.
+    let obj = this.object;
+    const objectPrototype = getRealmObjectPrototype(obj);
+
+    const result = new Set();
+    while (obj && obj !== objectPrototype) {
+      // Get the enumerable instance properties and the get/set properties.
+      const descriptors = Object.getOwnPropertyDescriptors(obj);
+      const propertyNames = Object.entries(descriptors)
+        .filter(
+          ([name, descriptor]) =>
+            name !== "constructor" &&
+            (descriptor.enumerable ||
+              (descriptor.get !== undefined && descriptor.set !== undefined))
+        )
+        .map(([name]) => name);
+      for (const name of propertyNames) {
+        result.add(name);
+      }
+      obj = Object.getPrototypeOf(obj);
+    }
+    return result;
+  }
+
+  /**
+   * Set the value for the given key. If the value is undefined, delete the key.
+   *
+   * @param {any} key
+   * @param {any} value
+   */
+  async set(key, value) {
+    if (value === undefined) {
+      // Delete the key.
+      delete this.object[key];
+    } else {
+      // Set the value for the key.
+      this.object[key] = value;
+    }
+    return this;
+  }
+}

package/src/SetTree.js

@@ -0,0 +1,40 @@
+import * as Tree from "./Tree.js";
+
+/**
+ * A tree of Set objects.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class SetTree {
+  /**
+   * @param {Set} set
+   */
+  constructor(set) {
+    this.values = [...set];
+    this.parent = null;
+  }
+
+  async get(key) {
+    let value = this.values[key];
+
+    if (value instanceof Set) {
+      value = Reflect.construct(this.constructor, [value]);
+    }
+
+    if (Tree.isAsyncTree(value) && !value.parent) {
+      value.parent = this;
+    }
+
+    return value;
+  }
+
+  async isKeyForSubtree(key) {
+    const value = this.values[key];
+    return value instanceof Set || Tree.isAsyncTree(value);
+  }
+
+  async keys() {
+    return this.values.keys();
+  }
+}

package/src/SiteTree.js

@@ -0,0 +1,124 @@
+import * as Tree from "./Tree.js";
+import * as keysJson from "./keysJson.js";
+
+/**
+ * An HTTP/HTTPS site as a tree of ArrayBuffers.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @implements {AsyncTree}
+ */
+export default class SiteTree {
+  /**
+   * @param {string} href
+   */
+  constructor(href = window?.location.href) {
+    if (href?.startsWith(".") && window?.location !== undefined) {
+      // URL represents a relative path; concatenate with current location.
+      href = new URL(href, window.location.href).href;
+    }
+
+    if (!href.endsWith("/")) {
+      // Add trailing slash; the URL is expected to represent a directory.
+      href += "/";
+    }
+
+    this.href = href;
+    this.keysPromise = undefined;
+    this.parent = null;
+  }
+
+  async get(key) {
+    // 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())) {
+      return Reflect.construct(this.constructor, [href]);
+    }
+
+    // Fetch the data at the given route.
+    let response;
+    try {
+      response = await fetch(href);
+    } 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]);
+      }
+    }
+
+    return response.arrayBuffer();
+  }
+
+  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 ? keysJson.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);
+    }
+  }
+
+  async keys() {
+    const keyDictionary = await this.getKeyDictionary();
+    return keyDictionary ? Object.keys(keyDictionary) : [];
+  }
+
+  /**
+   * 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]);
+  }
+
+  async unpack() {
+    const response = await fetch(this.href);
+    return response.ok ? response.arrayBuffer() : undefined;
+  }
+}

package/src/Tree.d.ts

@@ -0,0 +1,22 @@
+import type { AsyncMutableTree, AsyncTree } from "@weborigami/types";
+import { PlainObject, ReduceFn, Treelike, ValueKeyFn } from "../index.ts";
+
+export function assign(target: Treelike, source: Treelike): Promise<AsyncTree>;
+export function clear(AsyncTree: AsyncMutableTree): Promise<void>;
+export function entries(AsyncTree: AsyncTree): Promise<IterableIterator<any>>;
+export function forEach(AsyncTree: AsyncTree, callbackfn: (value: any, key: any) => Promise<void>): Promise<void>;
+export function from(obj: any): AsyncTree;
+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 isTreelike(obj: any): obj is Treelike;
+export function map(tree: Treelike, valueMap: ValueKeyFn): AsyncTree;
+export function mapReduce(tree: Treelike, mapFn: ValueKeyFn|null, reduceFn: ReduceFn): Promise<any>;
+export function plain(tree: Treelike): Promise<PlainObject>;
+export function remove(AsyncTree: AsyncMutableTree, key: any): Promise<boolean>;
+export function toFunction(tree: Treelike): Function;
+export function traverse(tree: Treelike, ...keys: any[]): Promise<any>;
+export function traverseOrThrow(tree: Treelike, ...keys: any[]): Promise<any>;
+export function traversePath(tree: Treelike, path: string): Promise<any>;
+export function values(AsyncTree: AsyncTree): Promise<IterableIterator<any>>;

package/src/Tree.js

@@ -0,0 +1,404 @@
+import DeferredTree from "./DeferredTree.js";
+import FunctionTree from "./FunctionTree.js";
+import MapTree from "./MapTree.js";
+import ObjectTree from "./ObjectTree.js";
+import SetTree from "./SetTree.js";
+import mapTransform from "./transforms/map.js";
+import * as utilities from "./utilities.js";
+import { castArrayLike, isPlainObject } from "./utilities.js";
+
+/**
+ * Helper functions for working with async trees
+ *
+ * @typedef {import("../index.ts").PlainObject} PlainObject
+ * @typedef {import("../index.ts").ReduceFn} ReduceFn
+ * @typedef {import("../index.ts").Treelike} Treelike
+ * @typedef {import("../index.ts").ValueKeyFn} ValueKeyFn
+ * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ */
+
+/**
+ * Apply the key/values pairs from the source tree to the target tree.
+ *
+ * If a key exists in both trees, and the values in both trees are
+ * subtrees, then the subtrees will be merged recursively. Otherwise, the
+ * value from the source tree will overwrite the value in the target tree.
+ *
+ * @param {AsyncMutableTree} target
+ * @param {AsyncTree} source
+ */
+export async function assign(target, source) {
+  const targetTree = from(target);
+  const sourceTree = from(source);
+  if (!isAsyncMutableTree(targetTree)) {
+    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.
+        await assign(targetValue, sourceValue);
+        return;
+      }
+    }
+    // Copy the value from the source to the target.
+    await /** @type {any} */ (targetTree).set(key, sourceValue);
+  });
+  await Promise.all(promises);
+  return targetTree;
+}
+
+/**
+ * Removes all entries from the tree.
+ *
+ * @param {AsyncMutableTree} tree
+ */
+export async function clear(tree) {
+  // @ts-ignore
+  for (const key of await tree.keys()) {
+    await tree.set(key, undefined);
+  }
+}
+
+/**
+ * Returns a new `Iterator` object that contains a two-member array of `[key,
+ * value]` for each element in the specific node of the tree.
+ *
+ * @param {AsyncTree} tree
+ */
+export async function entries(tree) {
+  const keys = [...(await tree.keys())];
+  const promises = keys.map(async (key) => [key, await tree.get(key)]);
+  return Promise.all(promises);
+}
+
+/**
+ * Calls callbackFn once for each key-value pair present in the specific node of
+ * the tree.
+ *
+ * @param {AsyncTree} tree
+ * @param {Function} callbackFn
+ */
+export async function forEach(tree, callbackFn) {
+  const keys = [...(await tree.keys())];
+  const promises = keys.map(async (key) => {
+    const value = await tree.get(key);
+    return callbackFn(value, key);
+  });
+  await Promise.all(promises);
+}
+
+/**
+ * Attempts to cast the indicated object to an async tree.
+ *
+ * @param {Treelike | Object} obj
+ * @returns {AsyncTree}
+ */
+export function from(obj) {
+  if (isAsyncTree(obj)) {
+    // Argument already supports the tree interface.
+    // @ts-ignore
+    return obj;
+  } else if (typeof obj === "function") {
+    return new FunctionTree(obj);
+  } else if (obj instanceof Map) {
+    return new MapTree(obj);
+  } else if (obj instanceof Set) {
+    return new SetTree(obj);
+  } else if (obj && typeof obj === "object" && "unpack" in obj) {
+    // Invoke unpack and convert the result to a tree.
+    let result = obj.unpack();
+    return result instanceof Promise ? new DeferredTree(result) : from(result);
+  } else if (obj && typeof obj === "object") {
+    // An instance of some class.
+    return new ObjectTree(obj);
+  }
+
+  throw new TypeError("Couldn't convert argument to an async tree");
+}
+
+/**
+ * Returns a boolean indicating whether the specific node of the tree has a
+ * value for the given `key`.
+ *
+ * @param {AsyncTree} tree
+ * @param {any} key
+ */
+export async function has(tree, key) {
+  const value = await tree.get(key);
+  return value !== undefined;
+}
+
+/**
+ * Return true if the indicated object is an async tree.
+ *
+ * @param {any} object
+ * @returns {obj is AsyncTree}
+ */
+export function isAsyncTree(object) {
+  return (
+    object &&
+    typeof object.get === "function" &&
+    typeof object.keys === "function"
+  );
+}
+
+/**
+ * Return true if the indicated object is an async mutable tree.
+ *
+ * @param {any} object
+ * @returns {obj is AsyncMutableTree}
+ */
+export function isAsyncMutableTree(object) {
+  return isAsyncTree(object) && typeof object.set === "function";
+}
+
+/**
+ * Returns true if the indicated object can be directly treated as an
+ * asynchronous tree. This includes:
+ *
+ * - An object that implements the AsyncTree interface (including
+ *   AsyncTree instances)
+ * - An object that implements the `unpack()` method
+ * - A function
+ * - An `Array` instance
+ * - A `Map` instance
+ * - A `Set` instance
+ * - A plain object
+ *
+ * Note: the `from()` method accepts any JavaScript object, but `isTreeable`
+ * returns `false` for an object that isn't one of the above types.
+ *
+ * @param {any} object
+ */
+export function isTreelike(object) {
+  return (
+    isAsyncTree(object) ||
+    object instanceof Function ||
+    object instanceof Array ||
+    object instanceof Set ||
+    object?.unpack instanceof Function ||
+    isPlainObject(object)
+  );
+}
+
+/**
+ * Return true if the indicated key produces or is expected to produce an
+ * async tree.
+ *
+ * This defers to the tree's own isKeyForSubtree method. If not found, this
+ * gets the value of that key and returns true if the value is an async
+ * tree.
+ */
+export async function isKeyForSubtree(tree, key) {
+  if (tree.isKeyForSubtree) {
+    return tree.isKeyForSubtree(key);
+  }
+  const value = await tree.get(key);
+  return isAsyncTree(value);
+}
+
+/**
+ * Return a new tree with deeply-mapped values of the original tree.
+ *
+ * @param {Treelike} treelike
+ * @param {ValueKeyFn} valueMap
+ */
+export function map(treelike, valueMap) {
+  const tree = from(treelike);
+  return mapTransform({ deep: true, valueMap })(tree);
+}
+
+/**
+ * Map and reduce a tree.
+ *
+ * This is done in as parallel fashion as possible. Each of the tree's values
+ * will be requested in an async call, then those results will be awaited
+ * collectively. If a mapFn is provided, it will be invoked to convert each
+ * value to a mapped value; otherwise, values will be used as is. When the
+ * values have been obtained, all the values and keys will be passed to the
+ * reduceFn, which should consolidate those into a single result.
+ *
+ * @param {Treelike} treelike
+ * @param {ValueKeyFn|null} valueMap
+ * @param {ReduceFn} reduceFn
+ */
+export async function mapReduce(treelike, valueMap, reduceFn) {
+  const tree = from(treelike);
+
+  // We're going to fire off all the get requests in parallel, as quickly as
+  // the keys come in. We call the tree's `get` method for each key, but
+  // *don't* wait for it yet.
+  const keys = Array.from(await tree.keys());
+  const promises = keys.map((key) =>
+    tree.get(key).then((value) =>
+      // If the value is a subtree, recurse.
+      isAsyncTree(value)
+        ? mapReduce(value, valueMap, reduceFn)
+        : valueMap
+        ? valueMap(value, key, tree)
+        : value
+    )
+  );
+
+  // Wait for all the promises to resolve. Because the promises were captured
+  // in the same order as the keys, the values will also be in the same order.
+  const values = await Promise.all(promises);
+
+  // Reduce the values to a single result.
+  return reduceFn(values, keys);
+}
+
+/**
+ * Converts an asynchronous tree into a synchronous plain JavaScript object.
+ *
+ * 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.
+ *
+ * @param {Treelike} treelike
+ * @returns {Promise<PlainObject|Array>}
+ */
+export async function plain(treelike) {
+  return mapReduce(treelike, null, (values, keys) => {
+    const object = {};
+    for (let i = 0; i < keys.length; i++) {
+      object[keys[i]] = values[i];
+    }
+    return castArrayLike(object);
+  });
+}
+
+/**
+ * Removes the value for the given key from the specific node of the tree.
+ *
+ * Note: The corresponding `Map` method is `delete`, not `remove`. However,
+ * `delete` is a reserved word in JavaScript, so this uses `remove` instead.
+ *
+ * @param {AsyncMutableTree} tree
+ * @param {any} key
+ */
+export async function remove(tree, key) {
+  const exists = await has(tree, key);
+  if (exists) {
+    await tree.set(key, undefined);
+    return true;
+  } else {
+    return false;
+  }
+}
+
+/**
+ * Returns a function that invokes the tree's `get` method.
+ *
+ * @param {Treelike} treelike
+ * @returns {Function}
+ */
+export function toFunction(treelike) {
+  const tree = from(treelike);
+  return tree.get.bind(tree);
+}
+
+/**
+ * Return the value at the corresponding path of keys.
+ *
+ * @this {any}
+ * @param {Treelike} treelike
+ * @param {...any} keys
+ */
+export async function traverse(treelike, ...keys) {
+  try {
+    // Await the result here so that, if the path doesn't exist, the catch
+    // block below will catch the exception.
+    return await traverseOrThrow.call(this, treelike, ...keys);
+  } catch (/** @type {any} */ error) {
+    if (error instanceof TraverseError) {
+      return undefined;
+    } else {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Return the value at the corresponding path of keys. Throw if any interior
+ * step of the path doesn't lead to a result.
+ *
+ * @param {Treelike} treelike
+ * @param  {...any} keys
+ */
+export async function traverseOrThrow(treelike, ...keys) {
+  // 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.
+  const remainingKeys = keys.slice();
+  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
+      );
+    }
+
+    // Get the next key.
+    const key = remainingKeys.shift();
+
+    // An empty string as the last key is a special case.
+    if (key === "" && remainingKeys.length === 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;
+    }
+
+    // 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);
+
+    // Get the value for the key.
+    value = await tree.get(key);
+  }
+  return value;
+}
+
+/**
+ * Given a slash-separated path like "foo/bar", traverse the keys "foo" and
+ * "bar" and return the resulting value.
+ *
+ * @param {Treelike} tree
+ * @param {string} path
+ */
+export async function traversePath(tree, path) {
+  const keys = utilities.keysFromPath(path);
+  return traverse(tree, ...keys);
+}
+
+// Error class thrown by traverseOrThrow()
+class TraverseError extends ReferenceError {
+  constructor(message, tree, keys) {
+    super(message);
+    this.tree = tree;
+    this.name = "TraverseError";
+    this.keys = keys;
+  }
+}
+
+/**
+ * Return the values in the specific node of the tree.
+ *
+ * @param {AsyncTree} tree
+ */
+export async function values(tree) {
+  const keys = [...(await tree.keys())];
+  const promises = keys.map(async (key) => tree.get(key));
+  return Promise.all(promises);
+}

package/src/keysJson.d.ts

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