@weborigami/async-tree 0.2.4 → 0.2.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Jan Miksovsky and other contributors
+Copyright (c) 2025 Jan Miksovsky and other contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
@@ -11,7 +11,7 @@
     "typescript": "5.7.2"
   },
   "dependencies": {
-    "@weborigami/types": "0.2.4"
+    "@weborigami/types": "0.2.6"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/shared.js

@@ -1,6 +1,7 @@
 // Exports for both Node.js and browser
 
 export { default as calendarTree } from "./src/drivers/calendarTree.js";
+export { default as constantTree } from "./src/drivers/constantTree.js";
 export { default as DeepMapTree } from "./src/drivers/DeepMapTree.js";
 export { default as DeferredTree } from "./src/drivers/DeferredTree.js";
 export { default as ExplorableSiteTree } from "./src/drivers/ExplorableSiteTree.js";
@@ -18,6 +19,7 @@ export { default as deepReverse } from "./src/operations/deepReverse.js";
 export { default as deepTake } from "./src/operations/deepTake.js";
 export { default as deepValues } from "./src/operations/deepValues.js";
 export { default as deepValuesIterator } from "./src/operations/deepValuesIterator.js";
+export { default as filter } from "./src/operations/filter.js";
 export { default as group } from "./src/operations/group.js";
 export { default as invokeFunctions } from "./src/operations/invokeFunctions.js";
 export { default as keyFunctionsForExtensions } from "./src/operations/keyFunctionsForExtensions.js";

package/src/Tree.js

@@ -422,7 +422,7 @@ export async function traverseOrThrow(treelike, ...keys) {
   const remainingKeys = keys.slice();
   let key;
   while (remainingKeys.length > 0) {
-    if (value === undefined) {
+    if (value == null) {
       throw new TraverseError("A null or undefined value can't be traversed", {
         tree: treelike,
         keys,
@@ -443,20 +443,13 @@ export async function traverseOrThrow(treelike, ...keys) {
       const args = remainingKeys.splice(0, fnKeyCount);
       key = null;
       value = await fn.call(target, ...args);
-    } else if (isTraversable(value) || typeof value === "object") {
-      // Value is some other treelike object: cast it to a tree.
+    } else {
+      // Cast value 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);
-    } else {
-      // Value can't be traversed
-      throw new TraverseError("Tried to traverse a value that's not treelike", {
-        tree: treelike,
-        keys,
-        position,
-      });
     }
 
     position++;

package/src/drivers/constantTree.js

@@ -0,0 +1,19 @@
+import { trailingSlash } from "../../main.js";
+
+/**
+ * A tree that returns a constant value for any key. If the key ends with a
+ * slash, then the same type of subtree is returned.
+ *
+ * @param {any} constant
+ */
+export default function constantTree(constant) {
+  return {
+    async get(key) {
+      return trailingSlash.has(key) ? constantTree(constant) : constant;
+    },
+
+    async keys() {
+      return [];
+    },
+  };
+}

package/src/operations/cache.js

@@ -6,23 +6,15 @@ import { ObjectTree, Tree } from "../internal.js";
  *
  * If no second tree is supplied, an in-memory value 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
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
  * @param {Treelike} sourceTreelike
  * @param {AsyncMutableTree} [cacheTreelike]
- * @param {Treelike} [filterTreelike]
  * @returns {AsyncTree & { description: string }}
  */
-export default function treeCache(
-  sourceTreelike,
-  cacheTreelike,
-  filterTreelike
-) {
+export default function treeCache(sourceTreelike, cacheTreelike) {
   if (!sourceTreelike) {
     const error = new TypeError(`cache: The source tree isn't defined.`);
     /** @type {any} */ (error).position = 0;
@@ -30,7 +22,6 @@ export default function treeCache(
   }
 
   const source = Tree.from(sourceTreelike);
-  const filter = filterTreelike ? Tree.from(filterTreelike) : undefined;
 
   /** @type {AsyncMutableTree} */
   let cache;
@@ -58,36 +49,27 @@ export default function treeCache(
 
       // Cache miss or interior node cache hit.
       let value = await source.get(key);
-      if (value !== undefined) {
-        // If a filter is defined, does the key match the filter?
-        const filterValue = filter ? await filter.get(key) : undefined;
-        const filterMatch = !filter || filterValue !== undefined;
-        if (filterMatch) {
-          if (Tree.isAsyncTree(value)) {
-            // Construct merged tree for a tree result.
-            if (cacheValue === undefined) {
-              // Construct new empty container in cache
-              await cache.set(key, {});
-              cacheValue = await cache.get(key);
-              if (!Tree.isAsyncTree(cacheValue)) {
-                // Coerce to tree and then save it back to the cache. This is
-                // necessary, e.g., if cache is an ObjectTree; we want the
-                // subtree to also be an ObjectTree, not a plain object.
-                cacheValue = Tree.from(cacheValue);
-                await cache.set(key, cacheValue);
-              }
-            }
-            value = treeCache(value, cacheValue, filterValue);
-          } else {
-            // Save in cache before returning.
-            await cache.set(key, value);
+      if (Tree.isAsyncTree(value)) {
+        // Construct merged tree for a tree result.
+        if (cacheValue === undefined) {
+          // Construct new empty container in cache
+          await cache.set(key, {});
+          cacheValue = await cache.get(key);
+          if (!Tree.isAsyncTree(cacheValue)) {
+            // Coerce to tree and then save it back to the cache. This is
+            // necessary, e.g., if cache is an ObjectTree; we want the
+            // subtree to also be an ObjectTree, not a plain object.
+            cacheValue = Tree.from(cacheValue);
+            await cache.set(key, cacheValue);
           }
         }
-
-        return value;
+        value = treeCache(value, cacheValue);
+      } else if (value !== undefined) {
+        // Save in cache before returning.
+        await cache.set(key, value);
       }
 
-      return undefined;
+      return value;
     },
 
     async keys() {

package/src/operations/cachedKeyFunctions.js

@@ -1,6 +1,6 @@
 import * as trailingSlash from "../trailingSlash.js";
 
-const treeToCaches = new WeakMap();
+const treeToCaches = new Map();
 
 /**
  * Given a key function, return a new key function and inverse key function that
@@ -111,12 +111,10 @@ function searchKeyMap(keyMap, key) {
   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);
-    }
+  } else {
+    // Check alternative with/without slash
+    const alternativeKey = trailingSlash.toggle(key, !trailingSlash.has(key));
+    match = keyMap.get(alternativeKey);
   }
   return match
     ? trailingSlash.toggle(match, trailingSlash.has(key))

package/src/operations/concat.js

@@ -20,14 +20,16 @@ export default async function concatTreeValues(treelike) {
   for await (const value of deepValuesIterator(treelike, { expand: true })) {
     let string;
     if (value === null) {
-      console.warn("Warning: Origami template encountered a null value");
       string = "null";
     } else if (value === undefined) {
-      console.warn("Warning: Origami template encountered an undefined value");
       string = "undefined";
     } else {
       string = toString(value);
     }
+    if (value === null || value === undefined) {
+      const message = `Warning: Origami template encountered a ${string} value. To locate where this happened, build your project and search your build output for the text "${string}".`;
+      console.warn(message);
+    }
     strings.push(string);
   }
   return strings.join("");

package/src/operations/deepMerge.js

@@ -21,10 +21,13 @@ export default function deepMerge(...sources) {
       for (let index = trees.length - 1; index >= 0; index--) {
         const tree = trees[index];
         const value = await tree.get(key);
-        if (Tree.isAsyncTree(value)) {
-          if (value.parent === tree) {
+        if (
+          Tree.isAsyncTree(value) ||
+          (Tree.isTreelike(value) && trailingSlash.has(key))
+        ) {
+          if (/** @type {any} */ (value).parent === tree) {
             // Merged tree acts as parent instead of the source tree.
-            value.parent = this;
+            /** @type {any} */ (value).parent = this;
           }
           subtrees.unshift(value);
         } else if (value !== undefined) {

package/src/operations/filter.js

@@ -0,0 +1,51 @@
+import { trailingSlash, Tree } from "@weborigami/async-tree";
+
+/**
+ * Given trees `a` and `b`, return a filtered version of `a` where only the keys
+ * that exist in `b` and have truthy values are kept. The filter operation is
+ * deep: if a value from `a` is a subtree, it will be filtered recursively.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} a
+ * @param {Treelike} b
+ * @returns {AsyncTree}
+ */
+export default function filter(a, b) {
+  a = Tree.from(a);
+  b = Tree.from(b, { deep: true });
+
+  return {
+    async get(key) {
+      // The key must exist in b and return a truthy value
+      const bValue = await b.get(key);
+      if (!bValue) {
+        return undefined;
+      }
+      let aValue = await a.get(key);
+      if (Tree.isTreelike(aValue)) {
+        // Filter the subtree
+        return filter(aValue, bValue);
+      } else {
+        return aValue;
+      }
+    },
+
+    async keys() {
+      // Use a's keys as the basis
+      const aKeys = [...(await a.keys())];
+      const bValues = await Promise.all(aKeys.map((key) => b.get(key)));
+      // An async tree value in b implies that the a key should have a slash
+      const aKeySlashes = aKeys.map((key, index) =>
+        trailingSlash.toggle(
+          key,
+          trailingSlash.has(key) || Tree.isAsyncTree(bValues[index])
+        )
+      );
+      // Remove keys that don't have values in b
+      const keys = aKeySlashes.filter((key, index) => bValues[index] ?? false);
+      return keys;
+    },
+  };
+}

package/src/operations/globKeys.js

@@ -0,0 +1,87 @@
+import { ObjectTree, Tree, merge, trailingSlash } from "@weborigami/async-tree";
+
+const globstar = "**";
+const globstarSlash = `${globstar}/`;
+
+export default function globKeys(treelike) {
+  const globs = Tree.from(treelike, { deep: true });
+  return {
+    async get(key) {
+      if (typeof key !== "string") {
+        return undefined;
+      }
+
+      let value = await matchGlobs(globs, key);
+      if (Tree.isAsyncTree(value)) {
+        value = globKeys(value);
+      }
+      return value;
+    },
+
+    async keys() {
+      return globs.keys();
+    },
+  };
+}
+
+// Convert the glob to a regular expression
+function matchGlob(glob, key) {
+  const regexText = glob
+    // Escape special regex characters
+    .replace(/[+?^${}()|\.\[\]\\]/g, "\\$&")
+    // Replace the glob wildcards with regex wildcards
+    .replace(/\*/g, ".*")
+    .replace(/\?/g, ".");
+  const regex = new RegExp(`^${regexText}$`);
+  return regex.test(key);
+}
+
+async function matchGlobs(globs, key) {
+  let globstarGlobs;
+
+  // Collect all matches
+  let matches = [];
+  for (let glob of await globs.keys()) {
+    if (glob === globstarSlash) {
+      // Remember for later
+      globstarGlobs = await globs.get(glob);
+      if (trailingSlash.has(key)) {
+        // A key for a subtree matches the globstar
+        matches.push(new ObjectTree({ [globstar]: globstarGlobs }));
+      }
+    } else if (matchGlob(glob, key)) {
+      // Text matches glob, get value
+      const globValue = await globs.get(glob);
+      if (globValue !== undefined) {
+        if (!Tree.isAsyncTree(globValue)) {
+          // Found a non-tree match, return immediately
+          return globValue;
+        }
+        // Add to matches
+        matches.push(globValue);
+      }
+    }
+  }
+
+  // If we don't have a match yet, try globstar
+  if (matches.length === 0) {
+    if (!globstarGlobs) {
+      // No matches
+      return undefined;
+    } else {
+      // Try globstar
+      const globstarValue = await matchGlobs(globstarGlobs, key);
+      if (!Tree.isAsyncTree(globstarValue)) {
+        // Found a non-tree match, return immediately
+        return globstarValue;
+      } else if (trailingSlash.has(key)) {
+        // No match but key is for subtree, return globstar tree
+        return new ObjectTree({ [globstar]: globstarGlobs });
+      }
+    }
+  }
+
+  // Merge all matches
+  const value = matches.length === 1 ? matches[0] : merge(...matches);
+  return value;
+}

package/src/operations/map.js

@@ -65,37 +65,54 @@ export default function map(treelike, options = {}) {
 
     if (keyFn || valueFn) {
       transformed.get = async (resultKey) => {
-        // Step 1: Map the result key to the source key.
-        const sourceKey = (await inverseKeyFn?.(resultKey, tree)) ?? resultKey;
+        if (resultKey === undefined) {
+          throw new ReferenceError(`map: Cannot get an undefined key.`);
+        }
+
+        // Step 1: Map the result key to the source key
+        let sourceKey = await inverseKeyFn?.(resultKey, tree);
 
         if (sourceKey === undefined) {
-          // No source key means no value.
-          return undefined;
+          if (deep && trailingSlash.has(resultKey)) {
+            // Special case: deep tree and value is expected to be a subtree
+            const sourceValue = await tree.get(resultKey);
+            // If we did get a subtree, apply the map to it
+            const resultValue = Tree.isAsyncTree(sourceValue)
+              ? mapFn(sourceValue)
+              : undefined;
+            return resultValue;
+          } else {
+            // No inverseKeyFn, or it returned undefined; use resultKey
+            sourceKey = resultKey;
+          }
         }
 
-        // Step 2: Get the source value.
+        // Regular path: map a single value
+
+        // Step 2: Get the source value
         let sourceValue;
         if (needsSourceValue) {
-          // Normal case: get the value from the source tree.
+          // Normal case: get the value from the source tree
           sourceValue = await tree.get(sourceKey);
-        } else if (deep && trailingSlash.has(sourceKey)) {
-          // Only get the source value if it's expected to be a subtree.
-          sourceValue = tree;
+          if (deep && sourceValue === undefined) {
+            // Key might be for a subtree, see if original key exists
+            sourceValue = await tree.get(resultKey);
+          }
         }
 
-        // Step 3: Map the source value to the result value.
+        // Step 3: Map the source value to the result value
         let resultValue;
         if (needsSourceValue && sourceValue === undefined) {
-          // No source value means no result value.
+          // No source value means no result value
           resultValue = undefined;
         } else if (deep && Tree.isAsyncTree(sourceValue)) {
-          // Map a subtree.
+          // We weren't expecting a subtree but got one; map it
           resultValue = mapFn(sourceValue);
         } else if (valueFn) {
-          // Map a single value.
+          // Map a single value
           resultValue = await valueFn(sourceValue, sourceKey, tree);
         } else {
-          // Return source value as is.
+          // Return source value as is
           resultValue = sourceValue;
         }
 

package/src/operations/regExpKeys.js

@@ -33,7 +33,7 @@ export default async function regExpKeys(treelike) {
       if (key == null) {
         // Reject nullish key.
         throw new ReferenceError(
-          `${this.constructor.name}: Cannot get a null or undefined key.`
+          `regExpKeys: Cannot get a null or undefined key.`
         );
       }
 
@@ -72,14 +72,7 @@ export default async function regExpKeys(treelike) {
       }
     } else {
       // Construct regular expression.
-      let text = key;
-      if (!text.startsWith("^")) {
-        text = "^" + text;
-      }
-      if (!text.endsWith("$")) {
-        text = text + "$";
-      }
-      regExp = new RegExp(text);
+      regExp = new RegExp(key);
     }
     map.set(regExp, value);
   }

package/src/utilities.js

@@ -219,8 +219,12 @@ export const naturalOrder = new Intl.Collator(undefined, {
  * @param {string[]} keys
  */
 export function pathFromKeys(keys) {
-  const normalized = keys.map((key) => trailingSlash.remove(key));
-  return normalized.join("/");
+  // Ensure there's a slash between all keys. If the last key has a trailing
+  // slash, leave it there.
+  const normalized = keys.map((key, index) =>
+    index < keys.length - 1 ? trailingSlash.add(key) : key
+  );
+  return normalized.join("");
 }
 
 /**

package/test/drivers/constantTree.test.js

@@ -0,0 +1,13 @@
+import { Tree } from "@weborigami/async-tree";
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import constantTree from "../../src/drivers/constantTree.js";
+
+describe("constantTree", () => {
+  test("returns a deep tree that returns constant for all keys", async () => {
+    const fixture = constantTree(1);
+    assert.equal(await fixture.get("a"), 1);
+    assert.equal(await fixture.get("b"), 1);
+    assert.equal(await Tree.traverse(fixture, "c/", "d/", "e"), 1);
+  });
+});

package/test/operations/cache.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import { DeepObjectTree, ObjectTree, Tree } from "../../src/internal.js";
+import { DeepObjectTree, ObjectTree } from "../../src/internal.js";
 import cache from "../../src/operations/cache.js";
 
 describe("cache", () => {
@@ -36,28 +36,4 @@ describe("cache", () => {
     const moreCache = await objectCache.get("more");
     assert.equal(await moreCache.get("d"), 4);
   });
-
-  test("if a cache filter is supplied, it only caches values whose keys match the filter", async () => {
-    const objectCache = new ObjectTree({});
-    const fixture = cache(
-      Tree.from({
-        "a.txt": "a",
-        "b.txt": "b",
-      }),
-      objectCache,
-      Tree.from({
-        "a.txt": true,
-      })
-    );
-
-    // Access some values to populate the cache.
-    assert.equal(await fixture.get("a.txt"), "a");
-    assert.equal(await fixture.get("b.txt"), "b");
-
-    // The a.txt value should be cached because it matches the filter.
-    assert.equal(await objectCache.get("a.txt"), "a");
-
-    // The b.txt value should not be cached because it does not match the filter.
-    assert.equal(await objectCache.get("b.txt"), undefined);
-  });
 });

package/test/operations/filter.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
+import filter from "../../src/operations/filter.js";
+
+describe("filter", () => {
+  test("removes keys and values whose filter values are falsy", async () => {
+    const result = filter(
+      {
+        a: 1,
+        b: 2,
+        c: {
+          d: 3,
+          e: 4,
+        },
+      },
+      {
+        a: true,
+        c: {
+          d: true,
+        },
+      }
+    );
+    assert.deepEqual(await result.keys(), ["a", "c/"]);
+    assert.deepEqual(await Tree.plain(result), {
+      a: 1,
+      c: {
+        d: 3,
+      },
+    });
+  });
+});

package/test/operations/globKeys.test.js

@@ -0,0 +1,53 @@
+import { Tree } from "@weborigami/async-tree";
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import globKeys from "../../src/operations/globKeys.js";
+
+describe("globKeys", () => {
+  test("matches globs", async () => {
+    const globTree = globKeys({
+      "*.txt": true,
+      "*.js": false,
+      "*.jsx": true,
+      "foo*baz": true,
+    });
+    assert(await globTree.get("file.txt"));
+    assert(!(await globTree.get("script.js")));
+    assert(await globTree.get("component.jsx"));
+    assert(await globTree.get("foobarbaz"));
+    assert(await globTree.get("foobaz"));
+    assert(!(await globTree.get("foo")));
+  });
+
+  test("matches nested globs", async () => {
+    const globTree = globKeys({
+      sub: {
+        foo: "bar",
+        "*": "default",
+      },
+    });
+    assert.equal(await Tree.traverse(globTree, "sub/", "file"), "default");
+    assert.equal(await Tree.traverse(globTree, "sub/", "foo"), "bar");
+  });
+
+  test("supports deep matches with globstar", async () => {
+    const globTree = globKeys({
+      "**": {
+        "*.txt": true, // More specific glob pattern must come
+        "*": false,
+      },
+      sub: {
+        "*.md": true,
+      },
+      "s*": {
+        "*.html": true,
+      },
+    });
+    assert.equal(await Tree.traverse(globTree, "a/", "b/", "foo.txt"), true);
+    assert.equal(await Tree.traverse(globTree, "c/", "foo"), false);
+    assert.equal(await Tree.traverse(globTree, "sub/", "file.md"), true);
+    assert.equal(await Tree.traverse(globTree, "sub/", "file.txt"), true);
+    assert.equal(await Tree.traverse(globTree, "sub/", "file.html"), true);
+    assert.equal(await Tree.traverse(globTree, "sub/", "file"), false);
+  });
+});

package/test/operations/regExpKeys.test.js

@@ -7,19 +7,23 @@ describe("regExpKeys", () => {
   test("matches keys using regular expressions", async () => {
     const fixture = await regExpKeys(
       new DeepObjectTree({
-        a: true,
-        "b.*": true,
+        "^a$": true,
+        "^b.*": true,
         c: {
           d: true,
           "e*": true,
         },
+        f: true,
       })
     );
     assert(await Tree.traverse(fixture, "a"));
     assert(!(await Tree.traverse(fixture, "alice")));
     assert(await Tree.traverse(fixture, "bob"));
     assert(await Tree.traverse(fixture, "brenda"));
-    assert(await Tree.traverse(fixture, "c", "d"));
-    assert(await Tree.traverse(fixture, "c", "eee"));
+    assert(await Tree.traverse(fixture, "c/", "d"));
+    assert(await Tree.traverse(fixture, "c/", "eee"));
+    assert(await Tree.traverse(fixture, "f"));
+    assert(await Tree.traverse(fixture, "stef")); // contains "f"
+    assert(!(await Tree.traverse(fixture, "gail")));
   });
 });

package/test/utilities.test.js

@@ -59,6 +59,7 @@ describe("utilities", () => {
     assert.equal(utilities.pathFromKeys([]), "");
     assert.equal(utilities.pathFromKeys(["a", "b", "c"]), "a/b/c");
     assert.equal(utilities.pathFromKeys(["a/", "b/", "c"]), "a/b/c");
+    assert.equal(utilities.pathFromKeys(["a/", "b/", "c/"]), "a/b/c/");
   });
 
   test("pipeline applies a series of functions to a value", async () => {