@weborigami/async-tree 0.0.66-beta.1 → 0.0.66

package/src/Tree.js

@@ -3,6 +3,7 @@ import FunctionTree from "./FunctionTree.js";
 import MapTree from "./MapTree.js";
 import SetTree from "./SetTree.js";
 import { DeepObjectTree, ObjectTree } from "./internal.js";
+import * as trailingSlash from "./trailingSlash.js";
 import mapTransform from "./transforms/mapFn.js";
 import * as utilities from "./utilities.js";
 import {
@@ -109,10 +110,11 @@ export async function forEach(tree, callbackFn) {
  * parent of the new tree.
  *
  * @param {Treelike | Object} object
- * @param {{ deep?: true, parent?: AsyncTree|null }} [options]
+ * @param {{ deep?: boolean, parent?: AsyncTree|null }} [options]
  * @returns {AsyncTree}
  */
 export function from(object, options = {}) {
+  const deep = options.deep ?? false;
   let tree;
   if (isAsyncTree(object)) {
     // Argument already supports the tree interface.
@@ -125,13 +127,13 @@ export function from(object, options = {}) {
   } else if (object instanceof Set) {
     tree = new SetTree(object);
   } else if (isPlainObject(object) || object instanceof Array) {
-    tree = options.deep ? new DeepObjectTree(object) : new ObjectTree(object);
+    tree = deep ? new DeepObjectTree(object) : new ObjectTree(object);
   } else if (isUnpackable(object)) {
     async function AsyncFunction() {} // Sample async function
     tree =
       object.unpack instanceof AsyncFunction.constructor
         ? // Async unpack: return a deferred tree.
-          new DeferredTree(object.unpack)
+          new DeferredTree(object.unpack, { deep })
         : // Synchronous unpack: cast the result of unpack() to a tree.
           from(object.unpack());
   } else if (object && typeof object === "object") {
@@ -175,7 +177,8 @@ export async function has(tree, key) {
  */
 export function isAsyncTree(obj) {
   return (
-    obj &&
+    obj !== null &&
+    typeof obj === "object" &&
     typeof obj.get === "function" &&
     typeof obj.keys === "function" &&
     // JavaScript Map look like trees but can't be extended the same way, so we
@@ -196,22 +199,6 @@ export function isAsyncMutableTree(obj) {
   );
 }
 
-/**
- * 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 true if the object can be traversed via the `traverse()` method. The
  * object must be either treelike or a packed object with an `unpack()` method.
@@ -315,7 +302,8 @@ export async function paths(treelike, base = "") {
   const tree = from(treelike);
   const result = [];
   for (const key of await tree.keys()) {
-    const valuePath = base ? `${base}/${key}` : key;
+    const separator = trailingSlash.has(base) ? "" : "/";
+    const valuePath = base ? `${base}${separator}${key}` : key;
     const value = await tree.get(key);
     if (await isAsyncTree(value)) {
       const subPaths = await paths(value, valuePath);
@@ -333,6 +321,8 @@ export async function paths(treelike, base = "") {
  * 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.
  *
+ * Any trailing slashes in keys will be removed.
+ *
  * @param {Treelike} treelike
  * @returns {Promise<PlainObject|Array>}
  */
@@ -344,7 +334,10 @@ export async function plain(treelike) {
     }
     const object = {};
     for (let i = 0; i < keys.length; i++) {
-      object[keys[i]] = values[i];
+      // Normalize slashes in keys.
+      const key = trailingSlash.remove(keys[i]);
+      const value = values[i];
+      object[key] = value;
     }
     return castArrayLike(object);
   });
@@ -436,15 +429,6 @@ export async function traverseOrThrow(treelike, ...keys) {
       value = await value.unpack();
     }
 
-    if (!isTreelike(value)) {
-      // Value isn't treelike, so can't be traversed except for a special case:
-      // if there's only one key left and it's an empty string, return the
-      // non-treelike value.
-      if (remainingKeys.length === 1 && remainingKeys[0] === "") {
-        return value;
-      }
-    }
-
     if (value instanceof Function) {
       // Value is a function: call it with the remaining keys.
       const fn = value;
@@ -453,21 +437,20 @@ export async function traverseOrThrow(treelike, ...keys) {
       const args = remainingKeys.splice(0, fnKeyCount);
       key = null;
       value = await fn.call(target, ...args);
-    } else {
-      const originalValue = value;
-
+    } else if (isTraversable(value) || typeof value === "object") {
       // 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);
-
-      // The empty key as the final key is a special case: if the tree doesn't
-      // have a value for the empty key, use the original value.
-      if (value === undefined && remainingKeys.length === 0 && key === "") {
-        value = originalValue;
-      }
+    } else {
+      // Value can't be traversed
+      throw new TraverseError("Tried to traverse a value that's not treelike", {
+        tree: treelike,
+        keys,
+        position,
+      });
     }
 
     position++;
@@ -477,7 +460,7 @@ export async function traverseOrThrow(treelike, ...keys) {
 }
 
 /**
- * Given a slash-separated path like "foo/bar", traverse the keys "foo" and
+ * Given a slash-separated path like "foo/bar", traverse the keys "foo/" and
  * "bar" and return the resulting value.
  *
  * @param {Treelike} tree

package/src/jsonKeys.js

@@ -9,48 +9,15 @@ import { Tree } from "./internal.js";
  * 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);
+  let keys = Array.from(await tree.keys());
+  // Skip the key `.keys.json` if present.
+  keys = keys.filter((key) => key !== ".keys.json");
+  const json = JSON.stringify(keys);
   return json;
 }

package/src/operations/cache.js

@@ -84,10 +84,6 @@ export default function treeCache(
       return undefined;
     },
 
-    async isKeyForSubtree(key) {
-      return Tree.isKeyForSubtree(source, key);
-    },
-
     async keys() {
       keys ??= await source.keys();
       return keys;

package/src/operations/deepMerge.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import * as trailingSlash from "../trailingSlash.js";
 
 /**
  * Return a tree that performs a deep merge of the given trees.
@@ -42,21 +43,17 @@ export default function deepMerge(...sources) {
       }
     },
 
-    async isKeyForSubtree(key) {
-      // Check trees for the indicated key in reverse order.
-      for (let index = trees.length - 1; index >= 0; index--) {
-        if (await Tree.isKeyForSubtree(trees[index], key)) {
-          return true;
-        }
-      }
-      return false;
-    },
-
     async keys() {
       const keys = new Set();
       // Collect keys in the order the trees were provided.
       for (const tree of trees) {
         for (const key of await tree.keys()) {
+          // Remove the alternate form of the key (if it exists)
+          const alternateKey = trailingSlash.toggle(key);
+          if (alternateKey !== key) {
+            keys.delete(alternateKey);
+          }
+
           keys.add(key);
         }
       }

package/src/operations/merge.js

@@ -1,5 +1,6 @@
 import { Tree } from "../internal.js";
 import * as symbols from "../symbols.js";
+import * as trailingSlash from "../trailingSlash.js";
 
 /**
  * Return a tree that performs a shallow merge of the given trees.
@@ -40,21 +41,17 @@ export default function merge(...sources) {
       return undefined;
     },
 
-    async isKeyForSubtree(key) {
-      // Check trees for the indicated key in reverse order.
-      for (let index = trees.length - 1; index >= 0; index--) {
-        if (await Tree.isKeyForSubtree(trees[index], key)) {
-          return true;
-        }
-      }
-      return false;
-    },
-
     async keys() {
       const keys = new Set();
       // Collect keys in the order the trees were provided.
       for (const tree of trees) {
         for (const key of await tree.keys()) {
+          // Remove the alternate form of the key (if it exists)
+          const alternateKey = trailingSlash.toggle(key);
+          if (alternateKey !== key) {
+            keys.delete(alternateKey);
+          }
+
           keys.add(key);
         }
       }

package/src/trailingSlash.js

@@ -0,0 +1,54 @@
+/**
+ * Add a trailing slash to a string key if the value is truthy. If the key
+ * is not a string, it will be returned as is.
+ *
+ * @param {any} key
+ */
+export function add(key) {
+  if (key == null) {
+    throw new ReferenceError("trailingSlash: key was undefined");
+  }
+  return typeof key === "string" && !key.endsWith("/") ? `${key}/` : key;
+}
+
+/**
+ * Return true if the indicated key is a string with a trailing slash,
+ * false otherwise.
+ *
+ * @param {any} key
+ */
+export function has(key) {
+  if (key == null) {
+    throw new ReferenceError("trailingSlash: key was undefined");
+  }
+  return typeof key === "string" && key.endsWith("/");
+}
+
+/**
+ * Remove a trailing slash from a string key.
+ *
+ * @param {any} key
+ */
+export function remove(key) {
+  if (key == null) {
+    throw new ReferenceError("trailingSlash: key was undefined");
+  }
+  return typeof key === "string" ? key.replace(/\/$/, "") : key;
+}
+
+/**
+ * If the key has a trailing slash, remove it; otherwise add it.
+ *
+ * @param {any} key
+ * @param {boolean} [force]
+ */
+export function toggle(key, force = undefined) {
+  if (key == null) {
+    throw new ReferenceError("trailingSlash: key was undefined");
+  }
+  if (typeof key !== "string") {
+    return key;
+  }
+  const addSlash = force ?? !has(key);
+  return addSlash ? add(key) : remove(key);
+}

package/src/transforms/cachedKeyFunctions.js

@@ -1,4 +1,4 @@
-import { Tree } from "../internal.js";
+import * as trailingSlash from "../trailingSlash.js";
 
 const treeToCaches = new WeakMap();
 
@@ -6,46 +6,50 @@ const treeToCaches = new WeakMap();
  * Given a key function, return a new key function and inverse key function that
  * cache the results of the original.
  *
+ * If `skipSubtrees` is true, the inverse key function will skip any source keys
+ * that are keys for subtrees, returning the source key unmodified.
+ *
  * @typedef {import("../../index.ts").KeyFn} KeyFn
  *
  * @param {KeyFn} keyFn
- * @param {boolean} [deep]
+ * @param {boolean?} skipSubtrees
  * @returns {{ key: KeyFn, inverseKey: KeyFn }}
  */
-export default function createCachedKeysTransform(keyFn, deep = false) {
+export default function cachedKeyFunctions(keyFn, skipSubtrees = false) {
   return {
     async inverseKey(resultKey, tree) {
-      const caches = getCachesForTree(tree);
+      const { resultKeyToSourceKey, sourceKeyToResultKey } =
+        getKeyMapsForTree(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);
+      const cachedSourceKey = searchKeyMap(resultKeyToSourceKey, resultKey);
+      if (cachedSourceKey !== undefined) {
+        return cachedSourceKey;
       }
 
       // 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.
+      const resultKeyWithoutSlash = trailingSlash.remove(resultKey);
       for (const sourceKey of await tree.keys()) {
         // Skip any source keys we already know about.
-        if (caches.sourceKeyToResultKey.has(sourceKey)) {
+        if (sourceKeyToResultKey.has(sourceKey)) {
           continue;
         }
 
-        let computedResultKey;
-        if (deep && (await Tree.isKeyForSubtree(tree, sourceKey))) {
-          computedResultKey = sourceKey;
-        } else {
-          computedResultKey = await keyFn(sourceKey, tree);
-        }
-
-        caches.sourceKeyToResultKey.set(sourceKey, computedResultKey);
-        caches.resultKeyToSourceKey.set(computedResultKey, sourceKey);
+        const computedResultKey = await computeAndCacheResultKey(
+          tree,
+          keyFn,
+          skipSubtrees,
+          sourceKey
+        );
 
-        if (computedResultKey === resultKey) {
-          // Match found.
-          return sourceKey;
+        if (
+          computedResultKey &&
+          trailingSlash.remove(computedResultKey) === resultKeyWithoutSlash
+        ) {
+          // Match found, match trailing slash and return
+          return trailingSlash.toggle(sourceKey, trailingSlash.has(resultKey));
         }
       }
 
@@ -53,27 +57,42 @@ export default function createCachedKeysTransform(keyFn, deep = false) {
     },
 
     async key(sourceKey, tree) {
-      const keyMaps = getCachesForTree(tree);
+      const { sourceKeyToResultKey } = getKeyMapsForTree(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 cachedResultKey = searchKeyMap(sourceKeyToResultKey, sourceKey);
+      if (cachedResultKey !== undefined) {
+        return cachedResultKey;
       }
 
-      const resultKey = await keyFn(sourceKey, tree);
-
-      // Cache the mappings from source key <-> result key for next time.
-      keyMaps.sourceKeyToResultKey.set(sourceKey, resultKey);
-      keyMaps.resultKeyToSourceKey.set(resultKey, sourceKey);
-
+      const resultKey = await computeAndCacheResultKey(
+        tree,
+        keyFn,
+        skipSubtrees,
+        sourceKey
+      );
       return resultKey;
     },
   };
 }
 
-function getCachesForTree(tree) {
+async function computeAndCacheResultKey(tree, keyFn, skipSubtrees, sourceKey) {
+  const { resultKeyToSourceKey, sourceKeyToResultKey } =
+    getKeyMapsForTree(tree);
+
+  const resultKey =
+    skipSubtrees && trailingSlash.has(sourceKey)
+      ? sourceKey
+      : await keyFn(sourceKey, tree);
+
+  sourceKeyToResultKey.set(sourceKey, resultKey);
+  resultKeyToSourceKey.set(resultKey, sourceKey);
+
+  return resultKey;
+}
+
+// Maintain key->inverseKey and inverseKey->key mappings for each tree. These
+// store subtree keys in either direction with a trailing slash.
+function getKeyMapsForTree(tree) {
   let keyMaps = treeToCaches.get(tree);
   if (!keyMaps) {
     keyMaps = {
@@ -84,3 +103,22 @@ function getCachesForTree(tree) {
   }
   return keyMaps;
 }
+
+// Search the given key map for the key. Ignore trailing slashes in the search,
+// but preserve them in the result.
+function searchKeyMap(keyMap, key) {
+  // Check key as is
+  let match;
+  if (keyMap.has(key)) {
+    match = keyMap.get(key);
+  } else if (!trailingSlash.has(key)) {
+    // Check key without trailing slash
+    const withSlash = trailingSlash.add(key);
+    if (keyMap.has(withSlash)) {
+      match = keyMap.get(withSlash);
+    }
+  }
+  return match
+    ? trailingSlash.toggle(match, trailingSlash.has(key))
+    : undefined;
+}

package/src/transforms/keyFunctionsForExtensions.js

@@ -1,3 +1,5 @@
+import * as trailingSlash from "../trailingSlash.js";
+
 /**
  * Given a source resultExtension and a result resultExtension, return a pair of key
  * functions that map between them.
@@ -19,13 +21,23 @@ export default function keyFunctionsForExtensions({
 
   return {
     async inverseKey(resultKey, tree) {
-      const basename = matchExtension(resultKey, resultExtension);
+      // Remove trailing slash so that mapFn won't inadvertently unpack files.
+      const baseKey = trailingSlash.remove(resultKey);
+      const basename = matchExtension(baseKey, resultExtension);
       return basename ? `${basename}${dotPrefix(sourceExtension)}` : undefined;
     },
 
     async key(sourceKey, tree) {
-      const basename = matchExtension(sourceKey, sourceExtension);
-      return basename ? `${basename}${dotPrefix(resultExtension)}` : undefined;
+      const hasSlash = trailingSlash.has(sourceKey);
+      const baseKey = trailingSlash.remove(sourceKey);
+      const basename = matchExtension(baseKey, sourceExtension);
+      return basename
+        ? // Preserve trailing slash
+          trailingSlash.toggle(
+            `${basename}${dotPrefix(resultExtension)}`,
+            hasSlash
+          )
+        : undefined;
     },
   };
 }
@@ -35,15 +47,17 @@ function dotPrefix(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.
+ * 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.
+ * A trailing slash in the key is ignored for purposes of comparison to comply
+ * with the way Origami can unpack files. Example: the keys "data.json" and
+ * "data.json/" are treated equally.
  *
- * 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.
+ * 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) {

package/src/transforms/mapFn.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import * as trailingSlash from "../trailingSlash.js";
 
 /**
  * Return a transform function that maps the keys and/or values of a tree.
@@ -65,13 +66,9 @@ export default function createMapTransform(options = {}) {
     if (keyFn || valueFn) {
       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 && inverseKeyFn
-            ? await inverseKeyFn(resultKey, tree)
-            : resultKey;
+        const sourceKey = (await inverseKeyFn?.(resultKey, tree)) ?? resultKey;
 
-        if (sourceKey == null) {
+        if (sourceKey === undefined) {
           // No source key means no value.
           return undefined;
         }
@@ -81,8 +78,8 @@ export default function createMapTransform(options = {}) {
         if (needsSourceValue) {
           // Normal case: get the value from the source tree.
           sourceValue = await tree.get(sourceKey);
-        } else if (deep && (await Tree.isKeyForSubtree(tree, sourceKey))) {
-          // Only get the source value if it's a subtree.
+        } else if (deep && trailingSlash.has(sourceKey)) {
+          // Only get the source value if it's expected to be a subtree.
           sourceValue = tree;
         }
 
@@ -111,15 +108,12 @@ export default function createMapTransform(options = {}) {
         // Apply the keyFn to source keys for leaf values (not subtrees).
         const sourceKeys = Array.from(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 keyFn(sourceKey, tree);
-            }
-            return resultKey;
-          })
+          sourceKeys.map(async (sourceKey) =>
+            // Deep maps leave source keys for subtrees alone
+            deep && trailingSlash.has(sourceKey)
+              ? sourceKey
+              : await keyFn(sourceKey, tree)
+          )
         );
         // Filter out any cases where the keyFn returned undefined.
         const resultKeys = mapped.filter((key) => key !== undefined);

package/src/transforms/regExpKeys.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import * as trailingSlash from "../trailingSlash.js";
 
 /**
  * A tree whose keys are strings interpreted as regular expressions.
@@ -57,25 +58,29 @@ export default async function regExpKeys(treelike) {
       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)) {
+
+    let regExp;
+    if (trailingSlash.has(key) || Tree.isAsyncTree(value)) {
+      const baseKey = trailingSlash.remove(key);
+      regExp = new RegExp("^" + baseKey + "/?$");
+      // Subtree
       value = regExpKeys(value);
       if (!value.parent) {
         value.parent = result;
       }
+    } else {
+      // Construct regular expression.
+      let text = key;
+      if (!text.startsWith("^")) {
+        text = "^" + text;
+      }
+      if (!text.endsWith("$")) {
+        text = text + "$";
+      }
+      regExp = new RegExp(text);
     }
-
     map.set(regExp, value);
   }