@weborigami/async-tree 0.2.11 → 0.3.0

package/package.json

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

package/shared.js

@@ -11,20 +11,24 @@ export { default as SetTree } from "./src/drivers/SetTree.js";
 export { default as SiteTree } from "./src/drivers/SiteTree.js";
 export { DeepObjectTree, ObjectTree, Tree } from "./src/internal.js";
 export * as jsonKeys from "./src/jsonKeys.js";
+export { default as addNextPrevious } from "./src/operations/addNextPrevious.js";
 export { default as cache } from "./src/operations/cache.js";
 export { default as cachedKeyFunctions } from "./src/operations/cachedKeyFunctions.js";
 export { default as concat } from "./src/operations/concat.js";
+export { default as concatTrees } from "./src/operations/concatTrees.js";
 export { default as deepMerge } from "./src/operations/deepMerge.js";
 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 extensionKeyFunctions } from "./src/operations/extensionKeyFunctions.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";
 export { default as map } from "./src/operations/map.js";
+export { default as mask } from "./src/operations/mask.js";
 export { default as merge } from "./src/operations/merge.js";
+export { default as paginate } from "./src/operations/paginate.js";
 export { default as reverse } from "./src/operations/reverse.js";
 export { default as scope } from "./src/operations/scope.js";
 export { default as sort } from "./src/operations/sort.js";

package/src/operations/addNextPrevious.js

@@ -0,0 +1,56 @@
+import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
+
+/**
+ * Add 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>}
+ */
+export default async function addNextPrevious(treelike) {
+  assertIsTreelike(treelike, "addNextPrevious");
+  const tree = Tree.from(treelike);
+
+  const entries = [...(await Tree.entries(tree))];
+  const keys = entries.map(([key]) => key);
+
+  // Map to an array of [key, result] pairs, where the result includes
+  // nextKey/previousKey properties.
+  const mappedEntries = await Promise.all(
+    entries.map(async ([key, value], index) => {
+      let resultValue;
+      if (value === undefined) {
+        resultValue = undefined;
+      } else if (Tree.isTreelike(value)) {
+        resultValue = await Tree.plain(value);
+      } else if (typeof value === "object") {
+        // Clone value to avoid modifying the original object
+        resultValue = { ...value };
+      } else {
+        // Take the object as the `value` property
+        resultValue = { value };
+      }
+
+      if (resultValue) {
+        // Extend result with nextKey/previousKey properties.
+        const nextKey = keys[index + 1];
+        if (nextKey) {
+          resultValue.nextKey = nextKey;
+        }
+        const previousKey = keys[index - 1];
+        if (previousKey) {
+          resultValue.previousKey = previousKey;
+        }
+      }
+
+      return [key, resultValue];
+    })
+  );
+
+  return treelike instanceof Array
+    ? mappedEntries.map(([_, value]) => value)
+    : Object.fromEntries(mappedEntries);
+}

package/src/operations/cache.js

@@ -1,4 +1,5 @@
 import { ObjectTree, Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Caches values from a source tree in a second cache tree. Cache source tree
@@ -15,12 +16,7 @@ import { ObjectTree, Tree } from "../internal.js";
  * @returns {AsyncTree & { description: string }}
  */
 export default function treeCache(sourceTreelike, cacheTreelike) {
-  if (!sourceTreelike) {
-    const error = new TypeError(`cache: The source tree isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(sourceTreelike, "cache");
   const source = Tree.from(sourceTreelike);
 
   /** @type {AsyncMutableTree} */

package/src/operations/cachedKeyFunctions.js

@@ -1,6 +1,9 @@
 import * as trailingSlash from "../trailingSlash.js";
 
-const treeToCaches = new Map();
+// For each (tree, keyFn) combination, we maintain a cache mapping a source key to
+// a result key and vice versa. We have to maintain three levels of Map: tree ->
+// keyFn -> sourceKey -> resultKey. This is the top level map.
+const treeMap = new Map();
 
 /**
  * Given a key function, return a new key function and inverse key function that
@@ -19,7 +22,7 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
   return {
     async inverseKey(resultKey, tree) {
       const { resultKeyToSourceKey, sourceKeyToResultKey } =
-        getKeyMapsForTree(tree);
+        getKeyMapsForTreeKeyFn(tree, keyFn);
 
       const cachedSourceKey = searchKeyMap(resultKeyToSourceKey, resultKey);
       if (cachedSourceKey !== undefined) {
@@ -57,7 +60,7 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
     },
 
     async key(sourceKey, tree) {
-      const { sourceKeyToResultKey } = getKeyMapsForTree(tree);
+      const { sourceKeyToResultKey } = getKeyMapsForTreeKeyFn(tree, keyFn);
 
       const cachedResultKey = searchKeyMap(sourceKeyToResultKey, sourceKey);
       if (cachedResultKey !== undefined) {
@@ -76,8 +79,10 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
 }
 
 async function computeAndCacheResultKey(tree, keyFn, deep, sourceKey) {
-  const { resultKeyToSourceKey, sourceKeyToResultKey } =
-    getKeyMapsForTree(tree);
+  const { resultKeyToSourceKey, sourceKeyToResultKey } = getKeyMapsForTreeKeyFn(
+    tree,
+    keyFn
+  );
 
   const resultKey =
     deep && trailingSlash.has(sourceKey)
@@ -90,17 +95,26 @@ async function computeAndCacheResultKey(tree, keyFn, deep, 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);
+// Maintain key->inverseKey and inverseKey->key mappings for each (tree, keyFn)
+// pair. These store subtree keys in either direction with a trailing slash.
+function getKeyMapsForTreeKeyFn(tree, keyFn) {
+  // Check if we already have a cache for this tree
+  let keyFnMap = treeMap.get(tree);
+  if (!keyFnMap) {
+    keyFnMap = new Map();
+    treeMap.set(tree, keyFnMap);
+  }
+
+  // Check if we have a cache for this keyFn
+  let keyMaps = keyFnMap.get(keyFn);
   if (!keyMaps) {
     keyMaps = {
       resultKeyToSourceKey: new Map(),
       sourceKeyToResultKey: new Map(),
     };
-    treeToCaches.set(tree, keyMaps);
+    keyFnMap.set(keyFn, keyMaps);
   }
+
   return keyMaps;
 }
 

package/src/operations/concat.js

@@ -1,20 +1,13 @@
-import { toString } from "../utilities.js";
+import { assertIsTreelike, toString } from "../utilities.js";
 import deepValuesIterator from "./deepValuesIterator.js";
 
 /**
  * Concatenate the deep text values in a tree.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- *
- * @this {AsyncTree|null}
  * @param {import("../../index.ts").Treelike} treelike
  */
-export default async function concatTreeValues(treelike) {
-  if (!treelike) {
-    const error = new TypeError(`concat: The tree isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
+export default async function concat(treelike) {
+  assertIsTreelike(treelike, "concat");
 
   const strings = [];
   for await (const value of deepValuesIterator(treelike, { expand: true })) {

package/src/operations/concatTrees.js

@@ -0,0 +1,25 @@
+import { Tree } from "../internal.js";
+import { toString } from "../utilities.js";
+import concat from "./concat.js";
+
+/**
+ * A tagged template literal function that concatenate the deep text values in a
+ * tree. Any treelike values will be concatenated using `concat`.
+ *
+ * @param {TemplateStringsArray} strings
+ * @param  {...any} values
+ */
+export default async function concatTrees(strings, ...values) {
+  // Convert all the values to strings
+  const valueTexts = await Promise.all(
+    values.map((value) =>
+      Tree.isTreelike(value) ? concat(value) : toString(value)
+    )
+  );
+  // Splice all the strings together
+  let result = strings[0];
+  for (let i = 0; i < valueTexts.length; i++) {
+    result += valueTexts[i] + strings[i + 1];
+  }
+  return result;
+}

package/src/operations/deepReverse.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Reverse the order of keys at all levels of the tree.
@@ -10,13 +11,7 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree}
  */
 export default function deepReverse(treelike) {
-  if (!treelike) {
-    const error = new TypeError(
-      `deepReverse: The tree to reverse isn't defined.`
-    );
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
+  assertIsTreelike(treelike, "deepReverse");
 
   const tree = Tree.from(treelike, { deep: true });
   return {

package/src/operations/deepTake.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Returns a function that traverses a tree deeply and returns the values of the
@@ -11,13 +12,9 @@ import { Tree } from "../internal.js";
  * @param {number} count
  */
 export default async function deepTake(treelike, count) {
-  if (!treelike) {
-    const error = new TypeError(`deepTake: The tree isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "deepTake");
   const tree = await Tree.from(treelike, { deep: true });
+
   const { values } = await traverse(tree, count);
   return Tree.from(values, { deep: true });
 }

package/src/operations/deepValuesIterator.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Return an iterator that yields all values in a tree, including nested trees.
@@ -14,13 +15,9 @@ export default async function* deepValuesIterator(
   treelike,
   options = { expand: false }
 ) {
-  if (!treelike) {
-    const error = new TypeError(`deepValues: The tree isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "deepValuesIterator");
   const tree = Tree.from(treelike, { deep: true });
+
   for (const key of await tree.keys()) {
     let value = await tree.get(key);
 

package/src/operations/{keyFunctionsForExtensions.js → extensionKeyFunctions.js}

@@ -8,13 +8,13 @@ import * as trailingSlash from "../trailingSlash.js";
  * The resulting `inverseKey` and `key` functions are compatible with those
  * expected by map and other transforms.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @param {{ resultExtension?: string, sourceExtension: string }} options
+ * @param {string} sourceExtension
+ * @param {string} [resultExtension]
  */
-export default function keyFunctionsForExtensions({
-  resultExtension,
+export default function extensionKeyFunctions(
   sourceExtension,
-}) {
+  resultExtension
+) {
   if (resultExtension === undefined) {
     resultExtension = sourceExtension;
   }

package/src/operations/filter.js

@@ -1,51 +1,39 @@
-import { trailingSlash, Tree } from "@weborigami/async-tree";
+import { assertIsTreelike } from "../utilities.js";
+import map from "./map.js";
 
 /**
- * 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.
+ * Given a tree an a test function, return a new tree whose keys correspond to
+ * the values that pass the test function.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("../../index.ts").Treelike} Treelike
  *
- * @param {Treelike} a
- * @param {Treelike} b
+ * @param {Treelike} treelike
+ * @param {function|any} options
  * @returns {AsyncTree}
  */
-export default function filter(a, b) {
-  a = Tree.from(a);
-  b = Tree.from(b, { deep: true });
+export default function filter(treelike, options) {
+  assertIsTreelike(treelike, "map");
+  let testFn;
+  let deep;
+  if (typeof options === "function") {
+    testFn = options;
+    deep = false;
+  } else {
+    testFn = options.test;
+    deep = options.deep ?? false;
+  }
 
-  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;
-      }
-    },
+  return map(treelike, {
+    deep,
+
+    // Assume source key is the same as result key
+    inverseKey: async (resultKey) => resultKey,
 
-    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;
+    key: async (sourceKey, tree) => {
+      const value = await tree.get(sourceKey);
+      const passes = await testFn(value, sourceKey, tree);
+      return passes ? sourceKey : undefined;
     },
-  };
+  });
 }

package/src/operations/globKeys.js

@@ -1,9 +1,13 @@
-import { ObjectTree, Tree, merge, trailingSlash } from "@weborigami/async-tree";
+import { ObjectTree, Tree } from "../internal.js";
+import * as trailingSlash from "../trailingSlash.js";
+import { assertIsTreelike } from "../utilities.js";
+import merge from "./merge.js";
 
 const globstar = "**";
 const globstarSlash = `${globstar}/`;
 
 export default function globKeys(treelike) {
+  assertIsTreelike(treelike, "globKeys");
   const globs = Tree.from(treelike, { deep: true });
   return {
     async get(key) {

package/src/operations/group.js

@@ -1,4 +1,5 @@
 import { ObjectTree, Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Given a function that returns a grouping key for a value, returns a transform
@@ -8,12 +9,7 @@ import { ObjectTree, Tree } from "../internal.js";
  * @param {import("../../index.ts").ValueKeyFn} groupKeyFn
  */
 export default async function group(treelike, groupKeyFn) {
-  if (!treelike) {
-    const error = new TypeError(`groupBy: The tree to group isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "group");
   const tree = Tree.from(treelike);
 
   const keys = Array.from(await tree.keys());

package/src/operations/map.js

@@ -1,5 +1,6 @@
 import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Transform the keys and/or values of a tree.
@@ -12,44 +13,9 @@ import * as trailingSlash from "../trailingSlash.js";
  * @param {MapOptions|ValueKeyFn} options
  */
 export default function map(treelike, options = {}) {
-  let deep;
-  let description;
-  let inverseKeyFn;
-  let keyFn;
-  let needsSourceValue;
-  let valueFn;
-
-  if (!treelike) {
-    const error = new TypeError(`map: The tree to map isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
-  if (typeof options === "function") {
-    // Take the single function argument as the valueFn
-    valueFn = options;
-  } else {
-    deep = options.deep;
-    description = options.description;
-    inverseKeyFn = options.inverseKey;
-    keyFn = options.key;
-    needsSourceValue = options.needsSourceValue;
-    valueFn = options.value;
-  }
-
-  deep ??= false;
-  description ??= "key/value map";
-  // @ts-ignore
-  inverseKeyFn ??= valueFn?.inverseKey;
-  // @ts-ignore
-  keyFn ??= valueFn?.key;
-  needsSourceValue ??= true;
-
-  if ((keyFn && !inverseKeyFn) || (!keyFn && inverseKeyFn)) {
-    throw new TypeError(
-      `map: You must specify both key and inverseKey functions, or neither.`
-    );
-  }
+  assertIsTreelike(treelike, "map");
+  const { deep, description, inverseKeyFn, keyFn, needsSourceValue, valueFn } =
+    validateOptions(options);
 
   /**
    * @param {import("@weborigami/types").AsyncTree} tree
@@ -144,3 +110,48 @@ export default function map(treelike, options = {}) {
   const tree = Tree.from(treelike, { deep });
   return mapFn(tree);
 }
+
+// Extract and validate options
+function validateOptions(options) {
+  let deep;
+  let description;
+  let inverseKeyFn;
+  let keyFn;
+  let needsSourceValue;
+  let valueFn;
+
+  if (typeof options === "function") {
+    // Take the single function argument as the valueFn
+    valueFn = options;
+  } else {
+    deep = options.deep;
+    description = options.description;
+    inverseKeyFn = options.inverseKey;
+    keyFn = options.key;
+    needsSourceValue = options.needsSourceValue;
+    valueFn = options.value;
+  }
+
+  deep ??= false;
+  description ??= "key/value map";
+  // @ts-ignore
+  inverseKeyFn ??= valueFn?.inverseKey;
+  // @ts-ignore
+  keyFn ??= valueFn?.key;
+  needsSourceValue ??= true;
+
+  if ((keyFn && !inverseKeyFn) || (!keyFn && inverseKeyFn)) {
+    throw new TypeError(
+      `map: You must specify both key and inverseKey functions, or neither.`
+    );
+  }
+
+  return {
+    deep,
+    description,
+    inverseKeyFn,
+    keyFn,
+    needsSourceValue,
+    valueFn,
+  };
+}

package/src/operations/mask.js

@@ -0,0 +1,55 @@
+import { Tree } from "../internal.js";
+import * as trailingSlash from "../trailingSlash.js";
+import { assertIsTreelike } from "../utilities.js";
+
+/**
+ * Given trees `a` and `b`, return a masked 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 mask(a, b) {
+  assertIsTreelike(a, "filter", 0);
+  assertIsTreelike(b, "filter", 1);
+  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 mask(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/paginate.js

@@ -0,0 +1,56 @@
+import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
+
+/**
+ * Return a new grouping of the treelike's values into chunks of the specified
+ * size.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} [treelike]
+ * @param {number} [size=10]
+ */
+export default async function paginate(treelike, size = 10) {
+  assertIsTreelike(treelike, "paginate");
+  const tree = Tree.from(treelike);
+
+  const keys = Array.from(await tree.keys());
+  const pageCount = Math.ceil(keys.length / size);
+
+  const paginated = {
+    async get(pageKey) {
+      // Note: page numbers are 1-based.
+      const pageNumber = Number(pageKey);
+      if (Number.isNaN(pageNumber)) {
+        return undefined;
+      }
+      const nextPage = pageNumber + 1 <= pageCount ? pageNumber + 1 : null;
+      const previousPage = pageNumber - 1 >= 1 ? pageNumber - 1 : null;
+      const items = {};
+      for (
+        let index = (pageNumber - 1) * size;
+        index < Math.min(keys.length, pageNumber * size);
+        index++
+      ) {
+        const key = keys[index];
+        items[key] = await tree.get(keys[index]);
+      }
+
+      return {
+        items,
+        nextPage,
+        pageCount,
+        pageNumber,
+        previousPage,
+      };
+    },
+
+    async keys() {
+      // Return an array from 1..totalPages
+      return Array.from({ length: pageCount }, (_, index) => index + 1);
+    },
+  };
+
+  return paginated;
+}

package/src/operations/regExpKeys.js

@@ -1,5 +1,6 @@
 import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * A tree whose keys are strings interpreted as regular expressions.
@@ -12,15 +13,9 @@ import * as trailingSlash from "../trailingSlash.js";
  * @type {import("../../index.ts").TreeTransform}
  */
 export default async function regExpKeys(treelike) {
-  if (!treelike) {
-    const error = new TypeError(
-      `regExpKeys: The tree of regular expressions isn't defined.`
-    );
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "regExpKeys");
   const tree = Tree.from(treelike);
+
   const map = new Map();
 
   // We build the output tree first so that we can refer to it when setting

package/src/operations/reverse.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Reverse the order of the top-level keys in the tree.
@@ -10,13 +11,9 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree}
  */
 export default function reverse(treelike) {
-  if (!treelike) {
-    const error = new TypeError(`reverse: The tree to reverse isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "reverse");
   const tree = Tree.from(treelike);
+
   return {
     async get(key) {
       return tree.get(key);

package/src/operations/scope.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * A tree's "scope" is the collection of everything in that tree and all of its
@@ -11,12 +12,7 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree & {trees: AsyncTree[]}}
  */
 export default function scope(treelike) {
-  if (!treelike) {
-    const error = new TypeError(`scope: The tree isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "scope");
   const tree = Tree.from(treelike);
 
   return {

package/src/operations/sort.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Return a new tree with the original's keys sorted. A comparison function can
@@ -14,16 +15,12 @@ import { Tree } from "../internal.js";
  * @param {SortOptions} [options]
  */
 export default function sort(treelike, options) {
-  if (!treelike) {
-    const error = new TypeError(`sort: The tree to sort isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
+  assertIsTreelike(treelike, "sort");
+  const tree = Tree.from(treelike);
 
   const sortKey = options?.sortKey;
   let compare = options?.compare;
 
-  const tree = Tree.from(treelike);
   const transformed = Object.create(tree);
   transformed.keys = async () => {
     const keys = Array.from(await tree.keys());

package/src/operations/take.js

@@ -1,4 +1,5 @@
 import { Tree } from "../internal.js";
+import { assertIsTreelike } from "../utilities.js";
 
 /**
  * Returns a new tree with the number of keys limited to the indicated count.
@@ -7,12 +8,7 @@ import { Tree } from "../internal.js";
  * @param {number} count
  */
 export default function take(treelike, count) {
-  if (!treelike) {
-    const error = new TypeError(`take: The tree to take from isn't defined.`);
-    /** @type {any} */ (error).position = 0;
-    throw error;
-  }
-
+  assertIsTreelike(treelike, "take");
   const tree = Tree.from(treelike);
 
   return {

package/src/utilities.d.ts

@@ -1,6 +1,7 @@
 import { AsyncTree } from "@weborigami/types";
 import { Packed, PlainObject, StringLike } from "../index.ts";
 
+export function assertIsTreelike(object: any, operation: string, position?: number): void;
 export function box(value: any): any;
 export function castArrayLike(keys: any[], values: any[]): any;
 export function getRealmObjectPrototype(object: any): any;

package/src/utilities.js

@@ -7,6 +7,30 @@ const TypedArray = Object.getPrototypeOf(Uint8Array);
 
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
 
+/**
+ * If the given object isn't treelike, throw an exception.
+ *
+ * @param {any} object
+ * @param {string} operation
+ * @param {number} [position]
+ */
+export function assertIsTreelike(object, operation, position = 0) {
+  let message;
+  if (!object) {
+    message = `${operation}: The tree argument wasn't defined.`;
+  } else if (object instanceof Promise) {
+    // A common mistake
+    message = `${operation}: The tree argument was a Promise. Did you mean to use await?`;
+  } else if (!Tree.isTreelike) {
+    message = `${operation}: The tree argument wasn't a treelike object.`;
+  }
+  if (message) {
+    const error = new TypeError(message);
+    /** @type {any} */ (error).position = position;
+    throw error;
+  }
+}
+
 /**
  * Return the value as an object. If the value is already an object it will be
  * returned as is. If the value is a primitive, it will be wrapped in an object:

package/test/drivers/constantTree.test.js

@@ -1,7 +1,7 @@
-import { Tree } from "@weborigami/async-tree";
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import constantTree from "../../src/drivers/constantTree.js";
+import { Tree } from "../../src/internal.js";
 
 describe("constantTree", () => {
   test("returns a deep tree that returns constant for all keys", async () => {

package/test/jsonKeys.test.js

@@ -1,6 +1,6 @@
-import { DeepObjectTree } from "@weborigami/async-tree";
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { DeepObjectTree } from "../src/internal.js";
 import * as jsonKeys from "../src/jsonKeys.js";
 
 describe("jsonKeys", () => {

package/test/operations/addNextPrevious.test.js

@@ -0,0 +1,55 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import addNextPrevious from "../../src/operations/addNextPrevious.js";
+
+describe("addNextPrevious", () => {
+  test("adds next/previous properties to values", async () => {
+    const tree = {
+      alice: {
+        name: "Alice",
+      },
+      bob: {
+        name: "Bob",
+      },
+      carol: {
+        name: "Carol",
+      },
+    };
+    const result = await addNextPrevious(tree);
+    assert.deepEqual(result, {
+      alice: {
+        name: "Alice",
+        nextKey: "bob",
+      },
+      bob: {
+        name: "Bob",
+        nextKey: "carol",
+        previousKey: "alice",
+      },
+      carol: {
+        name: "Carol",
+        previousKey: "bob",
+      },
+    });
+  });
+
+  test("returns a non-object value as a 'value' property", async () => {
+    const array = ["Alice", "Bob", "Carol"];
+    const result = await addNextPrevious(array);
+    assert.deepEqual(result, [
+      {
+        value: "Alice",
+        nextKey: 1,
+      },
+      {
+        value: "Bob",
+        nextKey: 2,
+        previousKey: 0,
+      },
+      {
+        value: "Carol",
+        previousKey: 1,
+      },
+    ]);
+  });
+});

package/test/operations/concatTrees.test.js

@@ -0,0 +1,12 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import concatTrees from "../../src/operations/concatTrees.js";
+
+describe("concatTrees", () => {
+  test("joins strings and values together", async () => {
+    const array = [1, 2, 3];
+    const object = { person1: "Alice", person2: "Bob" };
+    const result = await concatTrees`a ${array} b ${object} c`;
+    assert.equal(result, "a 123 b AliceBob c");
+  });
+});

package/test/operations/{keyFunctionsForExtensions.test.js → extensionKeyFunctions.test.js}

@@ -1,14 +1,12 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { ObjectTree, Tree } from "../../src/internal.js";
-import keyFunctionsForExtensions from "../../src/operations/keyFunctionsForExtensions.js";
+import extensionKeyFunctions from "../../src/operations/extensionKeyFunctions.js";
 import map from "../../src/operations/map.js";
 
 describe("keyMapsForExtensions", () => {
   test("returns key functions that pass a matching key through", async () => {
-    const { inverseKey, key } = keyFunctionsForExtensions({
-      sourceExtension: ".txt",
-    });
+    const { inverseKey, key } = extensionKeyFunctions(".txt");
     assert.equal(await inverseKey("file.txt"), "file.txt");
     assert.equal(await inverseKey("file.txt/"), "file.txt");
     assert.equal(await key("file.txt"), "file.txt");
@@ -18,10 +16,7 @@ describe("keyMapsForExtensions", () => {
   });
 
   test("returns key functions that can map extensions", async () => {
-    const { inverseKey, key } = keyFunctionsForExtensions({
-      resultExtension: ".json",
-      sourceExtension: ".md",
-    });
+    const { inverseKey, key } = extensionKeyFunctions(".md", ".json");
     assert.equal(await inverseKey("file.json"), "file.md");
     assert.equal(await inverseKey("file.json/"), "file.md");
     assert.equal(await key("file.md"), "file.json");
@@ -31,10 +26,7 @@ describe("keyMapsForExtensions", () => {
   });
 
   test("key functions can handle a slash as an explicit extension", async () => {
-    const { inverseKey, key } = keyFunctionsForExtensions({
-      resultExtension: ".html",
-      sourceExtension: "/",
-    });
+    const { inverseKey, key } = extensionKeyFunctions("/", ".html");
     assert.equal(await inverseKey("file.html"), "file/");
     assert.equal(await inverseKey("file.html/"), "file/");
     assert.equal(await key("file"), undefined);
@@ -47,9 +39,7 @@ describe("keyMapsForExtensions", () => {
       file2: "won't be mapped",
       "file3.foo": "won't be mapped",
     });
-    const { inverseKey, key } = keyFunctionsForExtensions({
-      sourceExtension: ".txt",
-    });
+    const { inverseKey, key } = extensionKeyFunctions(".txt");
     const fixture = map(files, {
       inverseKey,
       key,
@@ -66,10 +56,7 @@ describe("keyMapsForExtensions", () => {
       file2: "won't be mapped",
       "file3.foo": "won't be mapped",
     });
-    const { inverseKey, key } = keyFunctionsForExtensions({
-      resultExtension: ".upper",
-      sourceExtension: ".txt",
-    });
+    const { inverseKey, key } = extensionKeyFunctions(".txt", ".upper");
     const fixture = map(files, {
       inverseKey,
       key,

package/test/operations/filter.test.js

@@ -4,8 +4,24 @@ 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(
+  test("returns values that pass a filter function", async () => {
+    const result = await filter(
+      {
+        a: 1,
+        b: 2,
+        c: 3,
+        d: 4,
+      },
+      (value) => value % 2 === 1 // odd
+    );
+    assert.deepEqual(await Tree.plain(result), {
+      a: 1,
+      c: 3,
+    });
+  });
+
+  test("returns deep values that pass a filter function", async () => {
+    const result = await filter(
       {
         a: 1,
         b: 2,
@@ -15,13 +31,10 @@ describe("filter", () => {
         },
       },
       {
-        a: true,
-        c: {
-          d: true,
-        },
+        deep: true,
+        test: (value) => value % 2 === 1, // odd
       }
     );
-    assert.deepEqual(await result.keys(), ["a", "c/"]);
     assert.deepEqual(await Tree.plain(result), {
       a: 1,
       c: {

package/test/operations/globKeys.test.js

@@ -1,6 +1,6 @@
-import { Tree } from "@weborigami/async-tree";
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
 import globKeys from "../../src/operations/globKeys.js";
 
 describe("globKeys", () => {

package/test/operations/mask.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
+import mask from "../../src/operations/mask.js";
+
+describe("mask", () => {
+  test("removes keys and values whose mask values are falsy", async () => {
+    const result = mask(
+      {
+        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/paginate.test.js

@@ -0,0 +1,40 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
+import paginate from "../../src/operations/paginate.js";
+
+describe("paginate", () => {
+  test("divides tree keys into fixed-length chunks", async () => {
+    const treelike = {
+      a: 1,
+      b: 2,
+      c: 3,
+      d: 4,
+      e: 5,
+    };
+    const paginated = await paginate.call(null, treelike, 2);
+    assert.deepEqual(await Tree.plain(paginated), {
+      1: {
+        items: { a: 1, b: 2 },
+        nextPage: 2,
+        pageCount: 3,
+        pageNumber: 1,
+        previousPage: null,
+      },
+      2: {
+        items: { c: 3, d: 4 },
+        nextPage: 3,
+        pageCount: 3,
+        pageNumber: 2,
+        previousPage: 1,
+      },
+      3: {
+        items: { e: 5 },
+        nextPage: null,
+        pageCount: 3,
+        pageNumber: 3,
+        previousPage: 2,
+      },
+    });
+  });
+});