@weborigami/async-tree 0.0.35

package/src/keysJson.js

@@ -0,0 +1,56 @@
+import * as Tree from "./Tree.js";
+
+/**
+ * The .keys.json file format lets a site expose the keys of a node in the site
+ * so that they can be read by SiteTree.
+ *
+ * This file format is a JSON array of key descriptors: a string like
+ * "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.
+ */
+
+/**
+ * Parse the JSON in a .keys.json file.
+ *
+ * This returns a flat dictionary of flags which are true for subtrees and
+ * false otherwise.
+ *
+ * Example: the JSON `["index.html","about/"]` parses as:
+ *
+ *   {
+ *     "index.html": false,
+ *     about: true,
+ *   }
+ */
+export function parse(json) {
+  const descriptors = JSON.parse(json);
+  const result = {};
+  for (const descriptor of descriptors) {
+    if (descriptor.endsWith("/")) {
+      result[descriptor.slice(0, -1)] = true;
+    } else {
+      result[descriptor] = false;
+    }
+  }
+  return result;
+}
+
+/**
+ * Given a tree node, return a JSON string that can be written to a .keys.json
+ * file.
+ */
+export async function stringify(treelike) {
+  const tree = Tree.from(treelike);
+  const keyDescriptors = [];
+  for (const key of await tree.keys()) {
+    // Skip the key `.keys.json` if present.
+    if (key === ".keys.json") {
+      continue;
+    }
+    const isKeyForSubtree = await Tree.isKeyForSubtree(tree, key);
+    const keyDescriptor = isKeyForSubtree ? `${key}/` : key;
+    keyDescriptors.push(keyDescriptor);
+  }
+  const json = JSON.stringify(keyDescriptors);
+  return json;
+}

package/src/operations/cache.js

@@ -0,0 +1,75 @@
+import { ObjectTree, Tree } from "@weborigami/async-tree";
+
+/**
+ * Caches values from a source tree in a second cache tree. If no second tree is
+ * supplied, an in-memory cache is used.
+ *
+ * An optional third filter tree can be supplied. If a filter tree is supplied,
+ * only values for keys that match the filter will be cached.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ *
+ * @param {AsyncTree} source
+ * @param {AsyncMutableTree} [cacheTree]
+ * @param {AsyncTree} [filter]
+ * @returns {AsyncTree & { description: string }}
+ */
+export default function treeCache(source, cacheTree, filter) {
+  /** @type {AsyncMutableTree} */
+  const cache = cacheTree ?? new ObjectTree({});
+  return {
+    description: "cache",
+
+    async get(key) {
+      // Check cache tree first.
+      let cacheValue = await cache.get(key);
+      if (cacheValue !== undefined && !Tree.isAsyncTree(cacheValue)) {
+        // Leaf node cache hit
+        return cacheValue;
+      }
+
+      // Cache miss or interior node cache hit.
+      let value = await source.get(key);
+      if (value !== undefined) {
+        // Does this key match the filter?
+        const filterValue = filter ? await filter.get(key) : true;
+        const filterMatch = filterValue !== undefined;
+        if (filterMatch) {
+          if (Tree.isAsyncTree(value)) {
+            // Construct merged tree for a tree result.
+            if (cacheValue === undefined) {
+              // Construct new container in cache
+              await cache.set(key, {});
+              cacheValue = await cache.get(key);
+            }
+            value = treeCache(value, cacheValue, filterValue);
+          } else {
+            // Save in cache before returning.
+            await cache.set(key, value);
+          }
+        }
+
+        return value;
+      }
+
+      return undefined;
+    },
+
+    async isKeyForSubtree(key) {
+      return Tree.isKeyForSubtree(source, key);
+    },
+
+    async keys() {
+      const keys = new Set(await source.keys());
+
+      // We also add the cache's keys in case the keys provided by the source
+      // tree have changed since the cache was updated.
+      for (const key of await cache.keys()) {
+        keys.add(key);
+      }
+
+      return keys;
+    },
+  };
+}

package/src/operations/merge.js

@@ -0,0 +1,60 @@
+/**
+ * Return a tree that performs a shallow merge of the given trees.
+ *
+ * Given a set of trees, the `get` method looks at each tree in turn. The first
+ * tree is asked for the value with the key. If an tree returns a defined value
+ * (i.e., not undefined), that value is returned. If the first tree returns
+ * undefined, the second tree will be asked, and so on. If none of the trees
+ * return a defined value, the `get` method returns undefined.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @returns {AsyncTree & { description: string }}
+ */
+export default function merge(...sources) {
+  let trees = sources;
+  let mergeParent;
+  return {
+    description: "merge",
+
+    async get(key) {
+      for (const tree of trees) {
+        const value = await tree.get(key);
+        if (value !== undefined) {
+          return value;
+        }
+      }
+      return undefined;
+    },
+
+    async isKeyForSubtree(key) {
+      for (const tree of trees) {
+        if (await tree.isKeyForSubtree(key)) {
+          return true;
+        }
+      }
+      return false;
+    },
+
+    async keys() {
+      const keys = new Set();
+      for (const tree of trees) {
+        for (const key of await tree.keys()) {
+          keys.add(key);
+        }
+      }
+      return keys;
+    },
+
+    get parent() {
+      return mergeParent;
+    },
+    set parent(parent) {
+      mergeParent = parent;
+      trees = sources.map((source) => {
+        const tree = Object.create(source);
+        tree.parent = parent;
+        return tree;
+      });
+    },
+  };
+}

package/src/operations/mergeDeep.js

@@ -0,0 +1,47 @@
+import * as Tree from "../Tree.js";
+
+/**
+ * Return a tree that performs a deep merge of the given trees.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @returns {AsyncTree & { description: string }}
+ */
+export default function mergeDeep(...trees) {
+  return {
+    description: "mergeDeep",
+
+    async get(key) {
+      const subtrees = [];
+
+      for (const tree of trees) {
+        const value = await tree.get(key);
+        if (Tree.isAsyncTree(value)) {
+          subtrees.push(value);
+        } else if (value !== undefined) {
+          return value;
+        }
+      }
+
+      return subtrees.length > 0 ? mergeDeep(...subtrees) : undefined;
+    },
+
+    async isKeyForSubtree(key) {
+      for (const tree of trees) {
+        if (await tree.isKeyForSubtree(key)) {
+          return true;
+        }
+      }
+      return false;
+    },
+
+    async keys() {
+      const keys = new Set();
+      for (const tree of trees) {
+        for (const key of await tree.keys()) {
+          keys.add(key);
+        }
+      }
+      return keys;
+    },
+  };
+}

package/src/transforms/cachedKeyMaps.js

@@ -0,0 +1,86 @@
+import * as Tree from "../Tree.js";
+
+const treeToCaches = new WeakMap();
+
+/**
+ * Given a keyMap, return a new keyMap and inverseKeyMap that cache the results of
+ * the original keyMap.
+ *
+ * @typedef {import("../../index.ts").KeyFn} KeyFn
+ *
+ * @param {KeyFn} keyMap
+ * @param {boolean} [deep]
+ * @returns {{ keyMap: KeyFn, inverseKeyMap: KeyFn }}
+ */
+export default function createCachedKeysTransform(keyMap, deep = false) {
+  return {
+    async inverseKeyMap(resultKey, tree) {
+      const caches = getCachesForTree(tree);
+
+      // First check to see if we've already computed an source key for this
+      // result key. Again, we have to use `has()` for this check.
+      if (caches.resultKeyToSourceKey.has(resultKey)) {
+        return caches.resultKeyToSourceKey.get(resultKey);
+      }
+
+      // Iterate through the tree's keys, calculating source keys as we go,
+      // until we find a match. Cache all the intermediate results and the
+      // final match. This is O(n), but we stop as soon as we find a match,
+      // and subsequent calls will benefit from the intermediate results.
+      for (const sourceKey of await tree.keys()) {
+        // Skip any source keys we already know about.
+        if (caches.sourceKeyToResultKey.has(sourceKey)) {
+          continue;
+        }
+
+        let computedResultKey;
+        if (deep && (await Tree.isKeyForSubtree(tree, sourceKey))) {
+          computedResultKey = sourceKey;
+        } else {
+          computedResultKey = await keyMap(sourceKey, tree);
+        }
+
+        caches.sourceKeyToResultKey.set(sourceKey, computedResultKey);
+        caches.resultKeyToSourceKey.set(computedResultKey, sourceKey);
+
+        if (computedResultKey === resultKey) {
+          // Match found.
+          return sourceKey;
+        }
+      }
+
+      return undefined;
+    },
+
+    async keyMap(sourceKey, tree) {
+      const keyMaps = getCachesForTree(tree);
+
+      // First check to see if we've already computed an result key for this
+      // source key. The cached result key may be undefined, so we have to use
+      // `has()` instead of calling `get()` and checking for undefined.
+      if (keyMaps.sourceKeyToResultKey.has(sourceKey)) {
+        return keyMaps.sourceKeyToResultKey.get(sourceKey);
+      }
+
+      const resultKey = await keyMap(sourceKey, tree);
+
+      // Cache the mappings from source key <-> result key for next time.
+      keyMaps.sourceKeyToResultKey.set(sourceKey, resultKey);
+      keyMaps.resultKeyToSourceKey.set(resultKey, sourceKey);
+
+      return resultKey;
+    },
+  };
+}
+
+function getCachesForTree(tree) {
+  let keyMaps = treeToCaches.get(tree);
+  if (!keyMaps) {
+    keyMaps = {
+      resultKeyToSourceKey: new Map(),
+      sourceKeyToResultKey: new Map(),
+    };
+    treeToCaches.set(tree, keyMaps);
+  }
+  return keyMaps;
+}

package/src/transforms/groupBy.js

@@ -0,0 +1,40 @@
+import ObjectTree from "../ObjectTree.js";
+import * as Tree from "../Tree.js";
+
+/**
+ * Given a function that returns a grouping key for a value, returns a transform
+ * that applies that grouping function to a tree.
+ *
+ * @param {import("../../index.ts").ValueKeyFn} groupKeyFn
+ */
+export default function createGroupByTransform(groupKeyFn) {
+  /**
+   * @type {import("../../index.ts").TreeTransform}
+   */
+  return async function groupByTransform(tree) {
+    const result = {};
+    for (const key of await tree.keys()) {
+      const value = await tree.get(key);
+
+      // Get the groups for this value.
+      let groups = await groupKeyFn(value, key, tree);
+      if (!groups) {
+        continue;
+      }
+
+      if (!Tree.isTreelike(groups)) {
+        // A single value was returned
+        groups = [groups];
+      }
+
+      // Add the value to each group.
+      for (const groupKey of await groups.keys()) {
+        const group = await groups.get(groupKey);
+        result[group] ??= [];
+        result[group].push(value);
+      }
+    }
+
+    return new ObjectTree(result);
+  };
+}

package/src/transforms/keyMapsForExtensions.js

@@ -0,0 +1,64 @@
+/**
+ * Given a source resultExtension and a result resultExtension, return a pair of key
+ * functions that map between them.
+ *
+ * The resulting `inverseKeyMap` and `keyMap` functions are compatible with those
+ * expected by map and other transforms.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @param {{ resultExtension?: string, sourceExtension: string }}
+ * options
+ */
+export default function keyMapsForExtensions({
+  resultExtension,
+  sourceExtension,
+}) {
+  if (!resultExtension) {
+    resultExtension = sourceExtension;
+  }
+
+  return {
+    async inverseKeyMap(resultKey, tree) {
+      const basename = matchExtension(resultKey, resultExtension);
+      return basename ? `${basename}${dotPrefix(sourceExtension)}` : undefined;
+    },
+
+    async keyMap(sourceKey, tree) {
+      const basename = matchExtension(sourceKey, sourceExtension);
+      return basename ? `${basename}${dotPrefix(resultExtension)}` : undefined;
+    },
+  };
+}
+
+function dotPrefix(resultExtension) {
+  return resultExtension ? `.${resultExtension}` : "";
+}
+
+/**
+ * See if the key ends with the given resultExtension. If it does, return the base
+ * name without the resultExtension; if it doesn't return null.
+ *
+ * An empty/null resultExtension means: match any key that does *not* contain a
+ * period.
+ *
+ * This uses a different, more general interpretation of "resultExtension" to mean any
+ * suffix, rather than Node's interpretation `path.extname`. In particular, this
+ * will match an "resultExtension" like ".foo.bar" that contains more than one dot.
+ */
+function matchExtension(key, resultExtension) {
+  if (resultExtension) {
+    // Key matches if it ends with the same resultExtension
+    const dotExtension = dotPrefix(resultExtension);
+    if (
+      key.length > dotExtension.length &&
+      key.toLowerCase().endsWith(dotExtension)
+    ) {
+      return key.substring(0, key.length - dotExtension.length);
+    }
+  } else if (!key.includes?.(".")) {
+    // Key matches if it has no resultExtension
+    return key;
+  }
+  // Didn't match
+  return null;
+}

package/src/transforms/map.js

@@ -0,0 +1,106 @@
+import * as Tree from "../Tree.js";
+
+/**
+ * Return a transform function that maps the keys and/or values of a tree.
+ *
+ * @typedef {import("../../index.ts").KeyFn} KeyFn
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
+ *
+ * @param {ValueKeyFn|{ deep?: boolean, description?: string, inverseKeyMap?: KeyFn, keyMap?: KeyFn, valueMap?: ValueKeyFn }} options
+ */
+export default function createMapTransform(options) {
+  let deep;
+  let description;
+  let inverseKeyMap;
+  let keyMap;
+  let valueMap;
+  if (typeof options === "function") {
+    // Take the single function argument as the valueMap
+    valueMap = options;
+  } else {
+    deep = options.deep ?? false;
+    description = options.description ?? "key/value map";
+    inverseKeyMap = options.inverseKeyMap;
+    keyMap = options.keyMap;
+    valueMap = options.valueMap;
+  }
+
+  if ((keyMap && !inverseKeyMap) || (!keyMap && inverseKeyMap)) {
+    throw new TypeError(
+      `map: You must specify both keyMap and inverseKeyMap, or neither.`
+    );
+  }
+
+  /**
+   * @type {import("../../index.ts").TreeTransform}
+   */
+  return function map(tree) {
+    // The transformed tree is actually an extension of the original tree's
+    // prototype chain. This allows the transformed tree to inherit any
+    // properties/methods that do not need to be specified. For example, the
+    // `parent` of the transformed tree is the original tree's parent.
+    const transformed = Object.create(tree);
+
+    transformed.description = description;
+
+    if (keyMap || valueMap) {
+      transformed.get = async (resultKey) => {
+        // Step 1: Map the result key to the source key.
+        const isSubtree = deep && (await Tree.isKeyForSubtree(tree, resultKey));
+        const sourceKey =
+          !isSubtree && inverseKeyMap
+            ? await inverseKeyMap(resultKey, tree)
+            : resultKey;
+
+        if (!sourceKey) {
+          // No source key means no value.
+          return undefined;
+        }
+
+        // Step 2: Get the source value.
+        const sourceValue = await tree.get(sourceKey);
+
+        // Step 3: Map the source value to the result value.
+        let resultValue;
+        if (sourceValue === undefined) {
+          // No source value means no result value.
+          resultValue = undefined;
+        } else if (deep && Tree.isAsyncTree(sourceValue)) {
+          // Map a subtree.
+          resultValue = map(sourceValue);
+        } else if (valueMap) {
+          // Map a single value.
+          resultValue = await valueMap(sourceValue, sourceKey, tree);
+        } else {
+          // Return source value as is.
+          resultValue = sourceValue;
+        }
+
+        return resultValue;
+      };
+    }
+
+    if (keyMap) {
+      transformed.keys = async () => {
+        // Apply the keyMap to source keys for leaf values (not subtrees).
+        const sourceKeys = [...(await tree.keys())];
+        const mapped = await Promise.all(
+          sourceKeys.map(async (sourceKey) => {
+            let resultKey;
+            if (deep && (await Tree.isKeyForSubtree(tree, sourceKey))) {
+              resultKey = sourceKey;
+            } else {
+              resultKey = await keyMap(sourceKey, tree);
+            }
+            return resultKey;
+          })
+        );
+        // Filter out any cases where the keyMap returned undefined.
+        const resultKeys = mapped.filter((key) => key !== undefined);
+        return resultKeys;
+      };
+    }
+
+    return transformed;
+  };
+}

package/src/transforms/regExpKeys.js

@@ -0,0 +1,65 @@
+import * as Tree from "../Tree.js";
+
+/**
+ * A tree whose keys are strings interpreted as regular expressions.
+ *
+ * Requests to `get` a key are matched against the regular expressions, and the
+ * value for the first matching key is returned. The regular expresions are
+ * taken to match the entire key -- if they do not already start and end with
+ * `^` and `$` respectively, those are added.
+ *
+ * @type {import("../../index.ts").TreeTransform}
+ */
+export default async function regExpKeys(tree) {
+  const map = new Map();
+
+  // We build the output tree first so that we can refer to it when setting
+  // `parent` on subtrees below.
+  let result = {
+    // @ts-ignore
+    description: "regExpKeys",
+
+    async get(key) {
+      for (const [regExp, value] of map) {
+        if (regExp.test(key)) {
+          return value;
+        }
+      }
+      return undefined;
+    },
+
+    async keys() {
+      return [...map.keys()];
+    },
+  };
+
+  // Turn the input tree's string keys into regular expressions, then map those
+  // to the corresponding values.
+  for (const key of await tree.keys()) {
+    if (typeof key !== "string") {
+      // Skip non-string keys.
+      continue;
+    }
+
+    // Construct regular expression.
+    let text = key;
+    if (!text.startsWith("^")) {
+      text = "^" + text;
+    }
+    if (!text.endsWith("$")) {
+      text = text + "$";
+    }
+    const regExp = new RegExp(text);
+
+    // Get value.
+    let value = await tree.get(key);
+    if (Tree.isAsyncTree(value)) {
+      value = regExpKeys(value);
+      value.parent = result;
+    }
+
+    map.set(regExp, value);
+  }
+
+  return result;
+}

package/src/transforms/sort.js

@@ -0,0 +1,22 @@
+/**
+ * Return a transform function that sorts a tree's keys.
+ *
+ * For sorting, the keys are converted to strings, then sorted according to each
+ * character's Unicode code point value.
+ *
+ * @param {(a: any, b: any) => number} [compareFn]
+ */
+export default function createSortTransform(compareFn) {
+  /**
+   * @type {import("../../index.ts").TreeTransform}
+   */
+  return function sortTransform(tree) {
+    const transform = Object.create(tree);
+    transform.keys = async () => {
+      const keys = [...(await tree.keys())];
+      keys.sort(compareFn);
+      return keys;
+    };
+    return transform;
+  };
+}

package/src/transforms/sortBy.js

@@ -0,0 +1,29 @@
+/**
+ * Return a transform function that sorts a tree's keys.
+ *
+ * The given `sortKeyFn` is invoked for each key/value pair in the tree, and
+ * should produce a sort key for that pair. The sort keys are then compared to
+ * determine the sort order for the tree's keys.
+ *
+ * @param {import("./map.js").KeyFn} sortKeyFn
+ */
+export default function createSortByTransform(sortKeyFn) {
+  /**
+   * @type {import("../../index.ts").TreeTransform}
+   */
+  return function sortByTransform(tree) {
+    const transform = Object.create(tree);
+    transform.keys = async () => {
+      const keysAndSortKeys = [];
+      for (const key of await tree.keys()) {
+        const sortKey = await sortKeyFn(key, tree);
+        keysAndSortKeys.push({ key, sortKey });
+      }
+      keysAndSortKeys.sort((a, b) =>
+        a.sortKey < b.sortKey ? -1 : a.sortKey > b.sortKey ? 1 : 0
+      );
+      return keysAndSortKeys.map(({ key }) => key);
+    };
+    return transform;
+  };
+}

package/src/transforms/sortNatural.js

@@ -0,0 +1,10 @@
+import { naturalSortCompareFn } from "../utilities.js";
+import sort from "./sort.js";
+
+/**
+ * Return a transform function that sorts a tree's keys using [natural sort
+ * order](https://en.wikipedia.org/wiki/Natural_sort_order).
+ */
+export default function sortNaturalTransform() {
+  return sort(naturalSortCompareFn);
+}

package/src/utilities.d.ts

@@ -0,0 +1,10 @@
+import { PlainObject, StringLike } from "../index.ts";
+
+export function castArrayLike(object: any): any;
+export function getRealmObjectPrototype(object: any): any;
+export const hiddenFileNames: string[];
+export function isPlainObject(object: any): object is PlainObject;
+export function isStringLike(obj: any): obj is StringLike;
+export function keysFromPath(path: string): string[];
+export const naturalSortCompareFn: (a: string, b: string) => number;
+export function sortNatural(array: string[]): void;