@weborigami/async-tree 0.6.8 → 0.6.10

package/src/operations/map.js

@@ -1,6 +1,6 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isPlainObject from "../utilities/isPlainObject.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import toFunction from "../utilities/toFunction.js";
@@ -28,7 +28,9 @@ export default async function map(maplike, options = {}) {
   const validated = validateOptions(options);
   const mapFn = createMapFn(validated);
 
-  const tree = await getMapArgument(maplike, "map", { deep: validated.deep });
+  const tree = await args.map(maplike, "Tree.map", {
+    deep: validated.deep,
+  });
   return mapFn(tree);
 }
 
@@ -37,7 +39,7 @@ function createGet(tree, options, mapFn) {
   const { inverseKeyFn, deep, valueFn } = options;
   return async (resultKey) => {
     if (resultKey === undefined) {
-      throw new ReferenceError(`map: Cannot get an undefined key.`);
+      throw new ReferenceError(`Tree.map: Cannot get an undefined key.`);
     }
 
     // Step 1: Map the result key to the source key
@@ -102,8 +104,8 @@ function createKeys(tree, options) {
         // Deep maps leave source keys for subtrees alone
         deep && trailingSlash.has(sourceKey)
           ? sourceKey
-          : await keyFn(sourceValues[index], sourceKey, tree)
-      )
+          : await keyFn(sourceValues[index], sourceKey, tree),
+      ),
     );
     // Filter out any cases where the keyFn returned undefined.
     const resultKeys = mapped.filter((key) => key !== undefined);
@@ -135,7 +137,7 @@ function validateOption(options, key) {
   const value = options[key];
   if (key in options && value === undefined) {
     throw new TypeError(
-      `map: The ${key} option is given but its value is undefined.`
+      `Tree.map: The ${key} option is given but its value is undefined.`,
     );
   }
   return value;
@@ -173,38 +175,40 @@ function validateOptions(options) {
       (keyFn.includes("=>") || keyFn.includes("→"))
     ) {
       throw new TypeError(
-        `map: The key option appears to be an extension mapping. Did you mean to call Tree.mapExtension() ?`
+        `Tree.map: The key option appears to be an extension mapping. Did you mean to call Tree.mapExtension() ?`,
       );
     }
     keyFn &&= castToFunction(keyFn, "key");
     valueFn &&= castToFunction(valueFn, "value");
   } else if (options === undefined) {
     /** @type {any} */
-    const error = new TypeError(`map: The second parameter was undefined.`);
-    error.position = 1;
+    const error = new TypeError(
+      `Tree.map: The second parameter was undefined.`,
+    );
+    error.position = 2;
     throw error;
   } else {
     /** @type {any} */
     const error = new TypeError(
-      `map: You must specify a value function or options dictionary as the second parameter.`
+      `Tree.map: You must specify a value function or options dictionary as the second parameter.`,
     );
-    error.position = 1;
+    error.position = 2;
     throw error;
   }
 
   if (extension && !options._noExtensionWarning) {
     console.warn(
-      `map: The 'extension' option for Tree.map() is deprecated and will be removed in a future release. Use Tree.mapExtension() instead.`
+      `Tree.map: The 'extension' option for Tree.map() is deprecated and will be removed in a future release. Use Tree.mapExtension() instead.`,
     );
   }
   if (extension && (keyFn || inverseKeyFn)) {
     throw new TypeError(
-      `map: You can't specify extensions and also a key or inverseKey function`
+      `Tree.map: You can't specify extensions and also a key or inverseKey function`,
     );
   }
   if (extension && keyNeedsSourceValue === true) {
     throw new TypeError(
-      `map: using extensions sets keyNeedsSourceValue to be false`
+      `Tree.map: using extensions sets keyNeedsSourceValue to be false`,
     );
   }
 
@@ -213,7 +217,7 @@ function validateOptions(options) {
     const parsed = parseExtensions(extension);
     const keyFns = extensionKeyFunctions(
       parsed.sourceExtension,
-      parsed.resultExtension
+      parsed.resultExtension,
     );
     keyFn = keyFns.key;
     inverseKeyFn = keyFns.inverseKey;
@@ -225,7 +229,7 @@ function validateOptions(options) {
 
     if (!keyFn && inverseKeyFn) {
       throw new TypeError(
-        `map: You can't specify an inverseKey function without a key function`
+        `Tree.map: You can't specify an inverseKey function without a key function`,
       );
     }
 
@@ -239,7 +243,7 @@ function validateOptions(options) {
 
   if (!valueFn && !keyFn) {
     throw new TypeError(
-      `map: You must specify a value function or a key function`
+      `Tree.map: You must specify a value function or a key function`,
     );
   }
 
@@ -262,7 +266,7 @@ function castToFunction(object, name) {
   const fn = toFunction(object);
   if (!fn) {
     throw new TypeError(
-      `map: The ${name} option must be a function but couldn't be treated as one.`
+      `Tree.map: The ${name} option must be a function but couldn't be treated as one.`,
     );
   }
   return fn;

package/src/operations/mapExtension.js

@@ -54,13 +54,13 @@ export default async function mapExtension(maplike, arg2, arg3) {
       Object.assign(options, arg2);
     } else {
       throw new TypeError(
-        "mapExtension: Expected a string or options object for the second argument."
+        "Tree.mapExtension: Expected a string or options object for the second argument.",
       );
     }
   } else {
     if (typeof arg2 !== "string") {
       throw new TypeError(
-        "mapExtension: Expected a string for the second argument."
+        "Tree.mapExtension: Expected a string for the second argument.",
       );
     }
     options.extension = arg2;
@@ -73,7 +73,7 @@ export default async function mapExtension(maplike, arg2, arg3) {
       Object.assign(options, arg3);
     } else {
       throw new TypeError(
-        "mapExtension: Expected a function or options object for the third argument."
+        "Tree.mapExtension: Expected a function or options object for the third argument.",
       );
     }
   }

package/src/operations/mapReduce.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isMap from "./isMap.js";
 
 /**
@@ -23,7 +23,7 @@ import isMap from "./isMap.js";
  * @param {ReduceFn} reduceFn
  */
 export default async function mapReduce(source, valueFn, reduceFn) {
-  const sourceMap = await getMapArgument(source, "mapReduce");
+  const sourceMap = await args.map(source, "Tree.mapReduce");
 
   // We're going to fire off all the get requests in parallel, as quickly as
   // the keys come in. We call the tree's `get` method for each key, but
@@ -37,8 +37,8 @@ export default async function mapReduce(source, valueFn, reduceFn) {
       return isMap(value)
         ? mapReduce(value, valueFn, reduceFn) // subtree; recurse
         : valueFn
-        ? valueFn(value, key, sourceMap)
-        : value;
+          ? valueFn(value, key, sourceMap)
+          : value;
     })();
     promises.push(promise);
   }

package/src/operations/mask.js

@@ -1,6 +1,6 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isMaplike from "./isMaplike.js";
 import keys from "./keys.js";
 
@@ -16,13 +16,13 @@ import keys from "./keys.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function mask(aMaplike, bMaplike) {
-  const aMap = await getMapArgument(aMaplike, "filter", {
+  const aMap = await args.map(aMaplike, "Tree.mask", {
     deep: true,
-    position: 0,
+    position: 1,
   });
-  const bMap = await getMapArgument(bMaplike, "filter", {
+  const bMap = await args.map(bMaplike, "Tree.mask", {
     deep: true,
-    position: 1,
+    position: 2,
   });
 
   return Object.assign(new AsyncMap(), {
@@ -66,7 +66,7 @@ export default async function mask(aMaplike, bMaplike) {
         }
         return trailingSlash.toggle(
           key,
-          trailingSlash.has(key) || isMaplike(bValue)
+          trailingSlash.has(key) || isMaplike(bValue),
         );
       });
 

package/src/operations/match.js

@@ -1,5 +1,5 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import isMap from "./isMap.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Return a tree with the indicated keys (if provided).
@@ -27,15 +27,17 @@ export default function match(pattern, resultFn, keys = []) {
     // Convert the simple pattern format into a regular expression.
     const regexText = pattern.replace(
       /\[(?<variable>.+)\]/g,
-      (match, p1, offset, string, groups) => `(?<${groups.variable}>.+)`
+      (match, p1, offset, string, groups) => `(?<${groups.variable}>.+)`,
     );
     regex = new RegExp(`^${regexText}$`);
   } else if (pattern instanceof RegExp) {
     regex = pattern;
   } else {
-    throw new Error(`match(): Unsupported pattern`);
+    throw new Error(`Tree.match: Unsupported pattern`);
   }
 
+  const fn = args.invocable(resultFn, "Tree.match", { position: 2 });
+
   const result = Object.assign(new AsyncMap(), {
     description: "match",
 
@@ -45,24 +47,11 @@ export default function match(pattern, resultFn, keys = []) {
         return undefined;
       }
 
-      if (
-        typeof resultFn !== "function" &&
-        !(isMap(resultFn) && "parent" in resultFn)
-      ) {
-        // Simple return value; return as is
-        return resultFn;
-      }
-
       // Copy the `groups` property to a real object
       const matches = { ...keyMatch.groups };
 
-      // Invoke the result function with the extended scope.
-      let value;
-      if (typeof resultFn === "function") {
-        value = await resultFn(matches);
-      } else {
-        value = Object.create(resultFn);
-      }
+      // Invoke the result function
+      const value = await fn(matches);
 
       return value;
     },

package/src/operations/merge.js

@@ -4,6 +4,7 @@ import isPlainObject from "../utilities/isPlainObject.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import from from "./from.js";
 import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
 import keys from "./keys.js";
 
 /**
@@ -25,10 +26,20 @@ export default async function merge(...treelikes) {
   const filtered = treelikes.filter((source) => source);
   const unpacked = await Promise.all(
     filtered.map(async (source) =>
-      isUnpackable(source) ? await source.unpack() : source
-    )
+      isUnpackable(source) ? await source.unpack() : source,
+    ),
   );
 
+  // If any argument isn't maplike, throw an error.
+  for (const index in unpacked) {
+    if (!isMaplike(unpacked[index])) {
+      /** @type {any} */
+      const error = new TypeError(`Tree.merge: an argument wasn't maplike.`);
+      error.position = Number(index) + 1;
+      throw error;
+    }
+  }
+
   // If all arguments are plain objects, return a plain object.
   if (unpacked.every((source) => !isMap(source) && isPlainObject(source))) {
     return unpacked.reduce((acc, obj) => ({ ...acc, ...obj }), {});

package/src/operations/paginate.js

@@ -1,7 +1,7 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import SyncMap from "../drivers/SyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import keys from "./keys.js";
 
 /**
@@ -14,7 +14,8 @@ import keys from "./keys.js";
  * @param {number} [size=10]
  */
 export default async function paginate(maplike, size = 10) {
-  const source = await getMapArgument(maplike, "paginate");
+  const source = await args.map(maplike, "Tree.paginate");
+  size = args.number(size, "Tree.paginate", { position: 2 });
 
   const treeKeys = await keys(source);
   const pageCount = Math.ceil(treeKeys.length / size);

package/src/operations/parent.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Returns the parent of the map, if any.
@@ -8,6 +8,6 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {Maplike} maplike
  */
 export default async function parent(maplike) {
-  const map = await getMapArgument(maplike, "parent");
+  const map = await args.map(maplike, "Tree.parent");
   return "parent" in map ? map.parent : undefined;
 }

package/src/operations/paths.js

@@ -1,5 +1,5 @@
 import * as trailingSlash from "../trailingSlash.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import from from "./from.js";
 import isMap from "./isMap.js";
 import isMaplike from "./isMaplike.js";
@@ -15,7 +15,7 @@ import isMaplike from "./isMaplike.js";
  * @param {{ base?: string }} options
  */
 export default async function paths(maplike, options = {}) {
-  const tree = await getMapArgument(maplike, "paths");
+  const tree = await args.map(maplike, "Tree.paths");
   const base = options.base ?? "";
   const result = [];
   for await (const key of tree.keys()) {

package/src/operations/plain.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import toPlainValue from "../utilities/toPlainValue.js";
 
 /**
@@ -29,6 +29,6 @@ export default async function plain(maplike) {
   if (maplike instanceof Function) {
     throw new TypeError("plain: can't convert a function to a plain object");
   }
-  const tree = await getMapArgument(maplike, "plain");
+  const tree = await args.map(maplike, "Tree.plain");
   return toPlainValue(tree);
 }

package/src/operations/reduce.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import mapReduce from "./mapReduce.js";
 
 /**
@@ -11,6 +11,6 @@ import mapReduce from "./mapReduce.js";
  * @param {ReduceFn} reduceFn
  */
 export default async function reduce(maplike, reduceFn) {
-  const map = await getMapArgument(maplike, "reduce");
+  const map = await args.map(maplike, "Tree.reduce");
   return mapReduce(map, null, reduceFn);
 }

package/src/operations/regExpKeys.js

@@ -1,7 +1,7 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import SyncMap from "../drivers/SyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isMap from "./isMap.js";
 
 /**
@@ -18,7 +18,9 @@ import isMap from "./isMap.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function regExpKeys(maplike) {
-  const source = await getMapArgument(maplike, "regExpKeys", { deep: true });
+  const source = await args.map(maplike, "Tree.regExpKeys", {
+    deep: true,
+  });
 
   const map = new SyncMap();
 
@@ -32,7 +34,7 @@ export default async function regExpKeys(maplike) {
       if (key == null) {
         // Reject nullish key.
         throw new ReferenceError(
-          `regExpKeys: Cannot get a null or undefined key.`
+          `regExpKeys: Cannot get a null or undefined key.`,
         );
       }
 

package/src/operations/reverse.js

@@ -1,5 +1,5 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import keys from "./keys.js";
 
 /**
@@ -11,7 +11,7 @@ import keys from "./keys.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function reverse(maplike) {
-  const source = await getMapArgument(maplike, "reverse");
+  const source = await args.map(maplike, "Tree.reverse");
   return Object.assign(new AsyncMap(), {
     description: "reverse",
 

package/src/operations/root.js

@@ -1,5 +1,5 @@
 import * as symbols from "../symbols.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Walk up the `parent` chain to find the root of the tree.
@@ -10,7 +10,7 @@ import getMapArgument from "../utilities/getMapArgument.js";
  */
 export default async function root(maplike) {
   /** @type {any} */
-  let current = await getMapArgument(maplike, "root");
+  let current = await args.map(maplike, "Tree.root");
   while (current.parent || current[symbols.parent]) {
     current = current.parent || current[symbols.parent];
   }

package/src/operations/scope.js

@@ -1,5 +1,6 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
+import getParent from "../utilities/getParent.js";
 
 /**
  * A map's "scope" is the collection of everything in that map and all of its
@@ -11,7 +12,7 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function scope(maplike) {
-  const source = await getMapArgument(maplike, "scope");
+  const source = await args.map(maplike, "Tree.scope");
 
   return Object.assign(new AsyncMap(), {
     description: "scope",
@@ -26,7 +27,7 @@ export default async function scope(maplike) {
         if (value !== undefined) {
           break;
         }
-        current = "parent" in current ? current.parent : null;
+        current = getParent(current);
       }
       return value;
     },
@@ -40,7 +41,7 @@ export default async function scope(maplike) {
         for await (const key of current.keys()) {
           scopeKeys.add(key);
         }
-        current = "parent" in current ? current.parent : null;
+        current = getParent(current);
       }
 
       yield* scopeKeys;

package/src/operations/set.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Set a key/value pair in a map.
@@ -10,7 +10,7 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {any} value
  */
 export default async function set(maplike, key, value) {
-  const map = await getMapArgument(maplike, "set");
+  const map = await args.map(maplike, "Tree.set");
   await map.set(key, value);
 
   // Unlike Map.prototype.set, we return undefined. This is more useful when

package/src/operations/shuffle.js

@@ -1,5 +1,5 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import keys from "./keys.js";
 
 /**
@@ -12,7 +12,7 @@ import keys from "./keys.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function shuffle(maplike, reshuffle = false) {
-  const source = await getMapArgument(maplike, "shuffle");
+  const source = await args.map(maplike, "Tree.shuffle");
 
   let mapKeys;
 

package/src/operations/size.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Return the number of keys in the map.
@@ -8,6 +8,6 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {Maplike} maplike
  */
 export default async function size(maplike) {
-  const map = await getMapArgument(maplike, "size");
+  const map = await args.map(maplike, "Tree.size");
   return map.size;
 }

package/src/operations/sort.js

@@ -1,5 +1,5 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import keys from "./keys.js";
 
 /**
@@ -17,7 +17,7 @@ import keys from "./keys.js";
  * @param {SortOptions|ValueKeyFn} [options]
  */
 export default async function sort(maplike, options) {
-  const source = await getMapArgument(maplike, "sort");
+  const source = await args.map(maplike, "Tree.sort");
 
   let sortKey;
   let compare;
@@ -49,11 +49,11 @@ export default async function sort(maplike, options) {
             const sort = await sortKey(value, key, source);
             if (sort === undefined) {
               throw new Error(
-                `sortKey function returned undefined for key ${key}`
+                `sortKey function returned undefined for key ${key}`,
               );
             }
             return { key, sort };
-          })
+          }),
         );
 
         // Wrap the comparison function so it applies to sort keys.

package/src/operations/sync.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import reduce from "./reduce.js";
 
 /**
@@ -9,6 +9,6 @@ import reduce from "./reduce.js";
  * @param {Maplike} source
  */
 export default async function sync(source) {
-  const tree = await getMapArgument(source, "sync");
+  const tree = await args.map(source, "Tree.sync");
   return reduce(tree, (mapped) => mapped);
 }

package/src/operations/take.js

@@ -1,5 +1,5 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Returns a new map with the number of keys limited to the indicated count.
@@ -8,7 +8,8 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {number} count
  */
 export default async function take(maplike, count) {
-  const source = await getMapArgument(maplike, "take");
+  const source = await args.map(maplike, "Tree.take");
+  count = args.number(count, "Tree.take", { position: 2 });
   return Object.assign(new AsyncMap(), {
     description: `take ${count}`,
 

package/src/operations/toFunction.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Returns a function that invokes the map's `get` method.
@@ -9,6 +9,6 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @returns {Promise<Function>}
  */
 export default async function toFunction(maplike) {
-  const map = await getMapArgument(maplike, "toFunction");
+  const map = await args.map(maplike, "Tree.toFunction");
   return map.get.bind(map);
 }

package/src/operations/traverse.js

@@ -1,4 +1,5 @@
 import TraverseError from "../TraverseError.js";
+import * as args from "../utilities/args.js";
 import traverseOrThrow from "./traverseOrThrow.js";
 
 /**
@@ -10,10 +11,11 @@ import traverseOrThrow from "./traverseOrThrow.js";
  * @param {...any} keys
  */
 export default async function traverse(maplike, ...keys) {
+  const map = await args.map(maplike, "Tree.traverse");
   try {
     // Await the result here so that, if the path doesn't exist, the catch
     // block below will catch the exception.
-    return await traverseOrThrow(maplike, ...keys);
+    return await traverseOrThrow(map, ...keys);
   } catch (/** @type {any} */ error) {
     if (error instanceof TraverseError) {
       return undefined;