@weborigami/async-tree 0.6.9 → 0.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",

package/shared.js

@@ -19,11 +19,12 @@ export * as symbols from "./src/symbols.js";
 export * as trailingSlash from "./src/trailingSlash.js";
 export { default as TraverseError } from "./src/TraverseError.js";
 export * as Tree from "./src/Tree.js";
+export * as args from "./src/utilities/args.js";
 export { default as box } from "./src/utilities/box.js";
 export { default as castArraylike } from "./src/utilities/castArraylike.js";
-export { default as getTreeArgument } from "./src/utilities/getMapArgument.js";
 export { default as getParent } from "./src/utilities/getParent.js";
 export { default as getRealmObjectPrototype } from "./src/utilities/getRealmObjectPrototype.js";
+export { default as interop } from "./src/utilities/interop.js";
 export { default as isPacked } from "./src/utilities/isPacked.js";
 export { default as isPlainObject } from "./src/utilities/isPlainObject.js";
 export { default as isPrimitive } from "./src/utilities/isPrimitive.js";

package/src/TraverseError.js

@@ -1,10 +1,13 @@
 /**
  * Error class thrown by Tree.traverseOrThrow()
  */
-export default class TraverseError extends ReferenceError {
-  constructor(message, options) {
+export default class TraverseError extends Error {
+  constructor(message, options = {}) {
     super(message);
     this.name = "TraverseError";
-    Object.assign(this, options);
+    this.head = options.head;
+    this.lastValue = options.lastValue;
+    this.keys = options.keys;
+    this.position = options.position;
   }
 }

package/src/drivers/CalendarMap.js

@@ -48,8 +48,8 @@ export default class CalendarMap extends SyncMap {
       end.day = end.month
         ? daysInMonth(end.year, end.month)
         : end.year
-        ? 31 // Last day of December
-        : today.getDate();
+          ? 31 // Last day of December
+          : today.getDate();
     }
     if (end.month === undefined) {
       end.month = end.year ? 12 : today.getMonth() + 1;
@@ -77,7 +77,7 @@ export default class CalendarMap extends SyncMap {
   keys() {
     return Array.from(
       { length: this.end.year - this.start.year + 1 },
-      (_, i) => this.start.year + i
+      (_, i) => this.start.year + i,
     )[Symbol.iterator]();
   }
 }
@@ -91,6 +91,14 @@ function dateParts(date) {
     year = parts[0] ? parseInt(parts[0]) : undefined;
     month = parts[1] ? parseInt(parts[1]) : undefined;
     day = parts[2] ? parseInt(parts[2]) : undefined;
+
+    if (
+      (year && isNaN(year)) ||
+      (month && isNaN(month)) ||
+      (day && isNaN(day))
+    ) {
+      throw new TypeError(`Tree.calendar: invalid date: ${date}`);
+    }
   }
   return { year, month, day };
 }
@@ -135,7 +143,7 @@ function daysForMonthMap(year, month, start, end, valueFn) {
     *keys() {
       const days = Array.from(
         { length: daysInMonth(year, month) },
-        (_, i) => i + 1
+        (_, i) => i + 1,
       );
       yield* days
         .filter((day) => this.inRange(day))

package/src/operations/addNextPrevious.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";
 
 /**
@@ -9,7 +9,7 @@ import keys from "./keys.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function addNextPrevious(maplike) {
-  const source = await getMapArgument(maplike, "addNextPrevious");
+  const source = await args.map(maplike, "Tree.addNextPrevious");
   let sourceKeys;
 
   return Object.assign(new AsyncMap(), {

package/src/operations/assign.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import child from "./child.js";
 import isMaplike from "./isMaplike.js";
 
@@ -15,8 +15,12 @@ import isMaplike from "./isMaplike.js";
  * @param {Maplike} source
  */
 export default async function assign(target, source) {
-  const targetTree = await getMapArgument(target, "assign", { position: 0 });
-  const sourceTree = await getMapArgument(source, "assign", { position: 1 });
+  const targetTree = await args.map(target, "Tree.assign", {
+    position: 1,
+  });
+  const sourceTree = await args.map(source, "Tree.assign", {
+    position: 2,
+  });
   if ("readOnly" in targetTree && targetTree.readOnly) {
     throw new TypeError("assign: Target must be a read/write map");
   }

package/src/operations/cache.js

@@ -1,6 +1,6 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import SyncMap from "../drivers/SyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import child from "./child.js";
 import isMap from "./isMap.js";
 import isReadOnlyMap from "./isReadOnlyMap.js";
@@ -19,14 +19,14 @@ import keys from "./keys.js";
  * @returns {Promise<SyncMap|AsyncMap>}
  */
 export default async function treeCache(sourceMaplike, cacheMaplike) {
-  const source = await getMapArgument(sourceMaplike, "cache", {
-    position: 0,
+  const source = await args.map(sourceMaplike, "Tree.cache", {
+    position: 1,
   });
 
   let cache;
   if (cacheMaplike) {
     cache = /** @type {any} */ (
-      await getMapArgument(cacheMaplike, "cache", { position: 1 })
+      await args.map(cacheMaplike, "Tree.cache", { position: 2 })
     );
     // @ts-ignore
     if (isReadOnlyMap(cache)) {

package/src/operations/child.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import setParent from "../utilities/setParent.js";
 import isMap from "./isMap.js";
 
@@ -10,7 +10,7 @@ import isMap from "./isMap.js";
  * @param {Maplike} maplike
  */
 export default async function child(maplike, key) {
-  const map = await getMapArgument(maplike, "assign", { position: 0 });
+  const map = await args.map(maplike, "Tree.child", { position: 0 });
 
   let result;
 

package/src/operations/clear.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Remove all entries from the map.
@@ -8,9 +8,9 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {Maplike} maplike
  */
 export default async function clear(maplike) {
-  const map = await getMapArgument(maplike, "clear");
+  const map = await args.map(maplike, "Tree.clear");
   if ("readOnly" in map && map.readOnly) {
-    throw new TypeError("clear: target map is read-only");
+    throw new TypeError("Tree.clear: target map is read-only");
   }
   const promises = [];
   for await (const key of map.keys()) {

package/src/operations/deepEntries.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import entries from "./entries.js";
 import isMap from "./isMap.js";
 
@@ -10,14 +10,14 @@ import isMap from "./isMap.js";
  * @param {Maplike} maplike
  */
 export default async function deepEntries(maplike) {
-  const tree = await getMapArgument(maplike, "deepEntries");
+  const tree = await args.map(maplike, "Tree.deepEntries");
 
   const treeEntries = await entries(tree);
   const result = await Promise.all(
     treeEntries.map(async ([key, value]) => {
       const resolvedValue = isMap(value) ? await deepEntries(value) : value;
       return [key, resolvedValue];
-    })
+    }),
   );
   return result;
 }

package/src/operations/deepMap.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isPlainObject from "../utilities/isPlainObject.js";
 import map from "./map.js";
 
@@ -15,7 +15,7 @@ import map from "./map.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function deepMap(maplike, options) {
-  const tree = await getMapArgument(maplike, "deepMap", { deep: true });
+  const tree = await args.map(maplike, "Tree.deepMap", { deep: true });
   const withDeep = isPlainObject(options)
     ? // Dictionary
       { ...options, deep: true }

package/src/operations/deepMerge.js

@@ -18,9 +18,22 @@ export default async function deepMerge(...maplikes) {
   const filtered = maplikes.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.deepMerge: an argument wasn't maplike.`,
+      );
+      error.position = Number(index) + 1;
+      throw error;
+    }
+  }
+
   const sources = unpacked.map((maplike) => from(maplike, { deep: true }));
 
   return Object.assign(new AsyncMap(), {

package/src/operations/deepReverse.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 isMap from "./isMap.js";
 import keys from "./keys.js";
 
@@ -12,7 +12,9 @@ import keys from "./keys.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function deepReverse(maplike) {
-  const source = await getMapArgument(maplike, "deepReverse", { deep: true });
+  const source = await args.map(maplike, "Tree.deepReverse", {
+    deep: true,
+  });
 
   return Object.assign(new AsyncMap(), {
     description: "deepReverse",

package/src/operations/deepTake.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import from from "./from.js";
 import isMap from "./isMap.js";
 
@@ -13,7 +13,8 @@ import isMap from "./isMap.js";
  * @param {number} count
  */
 export default async function deepTake(maplike, count) {
-  const tree = await getMapArgument(maplike, "deepTake", { deep: true });
+  const tree = await args.map(maplike, "Tree.deepTake", { deep: true });
+  count = args.number(count, "Tree.deepTake", { position: 2 });
   const { values } = await traverse(tree, count);
   return from(values, { deep: true });
 }

package/src/operations/deepText.js

@@ -1,4 +1,5 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
+import interop from "../utilities/interop.js";
 import toString from "../utilities/toString.js";
 import deepValuesIterator from "./deepValuesIterator.js";
 
@@ -8,7 +9,7 @@ import deepValuesIterator from "./deepValuesIterator.js";
  * @param {import("../../index.ts").Maplike} maplike
  */
 export default async function deepText(maplike) {
-  const tree = await getMapArgument(maplike, "deepText", { deep: true });
+  const tree = await args.map(maplike, "Tree.deepText", { deep: true });
   const strings = [];
   for await (const value of deepValuesIterator(tree, { expand: true })) {
     let string;
@@ -20,8 +21,8 @@ export default async function deepText(maplike) {
       string = toString(value);
     }
     if (value === null || value === undefined) {
-      const message = `Warning: a 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);
+      const message = `Warning: a template encountered a ${string} value.`;
+      interop.warn(message);
     }
     strings.push(string);
   }

package/src/operations/deepValuesIterator.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isMap from "./isMap.js";
 import isMaplike from "./isMaplike.js";
 
@@ -14,9 +14,9 @@ import isMaplike from "./isMaplike.js";
  */
 export default async function* deepValuesIterator(
   maplike,
-  options = { expand: false }
+  options = { expand: false },
 ) {
-  const tree = await getMapArgument(maplike, "deepValuesIterator", {
+  const tree = await args.map(maplike, "Tree.deepValuesIterator", {
     deep: true,
   });
 

package/src/operations/delete.js

@@ -1,3 +1,5 @@
+import * as args from "../utilities/args.js";
+
 /**
  * Removes the value for the given key from the specific node of the tree.
  *
@@ -6,11 +8,8 @@
  * @param {Maplike} maplike
  * @param {any} key
  */
-
-import getMapArgument from "../utilities/getMapArgument.js";
-
-// `delete` is a reserved word in JavaScript, so we use `del` instead.
 export default async function del(maplike, key) {
-  const map = await getMapArgument(maplike, "delete");
+  // `delete` is reserved word so can't use that as function name
+  const map = await args.map(maplike, "Tree.delete");
   return map.delete(key);
 }

package/src/operations/entries.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Returns an array of `[key, value]` for each entry in the map.
@@ -9,7 +9,7 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @returns {Promise<Array<[any, any]>>}
  */
 export default async function entries(maplike) {
-  const map = await getMapArgument(maplike, "entries");
+  const map = await args.map(maplike, "Tree.entries");
   if (map instanceof Map) {
     return Array.from(map.entries());
   } else {

package/src/operations/filter.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import map from "./map.js";
 
 /**
@@ -23,7 +23,7 @@ export default async function filter(maplike, options) {
     deep = options.deep ?? false;
   }
 
-  const tree = await getMapArgument(maplike, "filter", { deep });
+  const tree = await args.map(maplike, "Tree.filter", { deep });
   return map(tree, {
     deep,
 

package/src/operations/first.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Return the first value in the tree.
@@ -8,7 +8,7 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {Maplike} maplike
  */
 export default async function first(maplike) {
-  const map = await getMapArgument(maplike, "first");
+  const map = await args.map(maplike, "Tree.first");
   let firstKey;
   for await (const key of map.keys()) {
     // Just needed to get first key

package/src/operations/forEach.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Calls callbackFn once for each key-value pair present in the map.
@@ -9,7 +9,11 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {Function} callbackFn
  */
 export default async function forEach(maplike, callbackFn) {
-  const map = await getMapArgument(maplike, "forEach");
+  const map = await args.map(maplike, "Tree.forEach");
+  if (typeof callbackFn !== "function") {
+    throw new TypeError("Tree.forEach: Expected a function argument.");
+  }
+
   for await (const key of map.keys()) {
     const value = await map.get(key);
     await callbackFn(value, key, map);

package/src/operations/from.js

@@ -6,6 +6,7 @@ import * as symbols from "../symbols.js";
 import box from "../utilities/box.js";
 import isPlainObject from "../utilities/isPlainObject.js";
 import setParent from "../utilities/setParent.js";
+import TypedArray from "../utilities/TypedArray.js";
 import isMap from "./isMap.js";
 
 /**
@@ -26,11 +27,11 @@ export default function from(object, options = {}) {
   const deep = options.deep ?? object?.[symbols.deep];
   let map;
   if (object == null) {
-    throw new TypeError("The tree argument wasn't defined.");
+    throw new ReferenceError("The map argument wasn't defined.");
   } else if (object instanceof Promise) {
     // A common mistake
     throw new TypeError(
-      "The tree argument was a Promise. Did you mean to use await?"
+      "The map argument was a Promise. Did you mean to use await?",
     );
   } else if (isMap(object)) {
     // Already a map
@@ -39,6 +40,8 @@ export default function from(object, options = {}) {
     map = new FunctionMap(object);
   } else if (object instanceof Set) {
     map = new SetMap(object);
+  } else if (object instanceof ArrayBuffer || object instanceof TypedArray) {
+    throw new TypeError("Can't treat binary file data as a map.");
   } else if (isPlainObject(object) || object instanceof Array) {
     map = new ObjectMap(object, { deep });
     // @ts-ignore

package/src/operations/globKeys.js

@@ -1,7 +1,7 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import ObjectMap from "../drivers/ObjectMap.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";
 import merge from "./merge.js";
 
@@ -9,7 +9,7 @@ const globstar = "**";
 const globstarSlash = `${globstar}/`;
 
 export default async function globKeys(maplike) {
-  const source = await getMapArgument(maplike, "globKeys", { deep: true });
+  const source = await args.map(maplike, "Tree.globKeys", { deep: true });
   return Object.assign(new AsyncMap(), {
     async get(key) {
       if (typeof key !== "string") {

package/src/operations/groupBy.js

@@ -1,5 +1,5 @@
 import SyncMap from "../drivers/SyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import entries from "./entries.js";
 import isMaplike from "./isMaplike.js";
 import values from "./values.js";
@@ -12,19 +12,20 @@ import values from "./values.js";
  * @param {import("../../index.ts").ValueKeyFn} groupKeyFn
  */
 export default async function groupBy(maplike, groupKeyFn) {
-  const source = await getMapArgument(maplike, "groupBy");
+  const source = await args.map(maplike, "Tree.groupBy");
+  const fn = args.invocable(groupKeyFn, "Tree.groupBy", { position: 2 });
 
   const result = new SyncMap();
   const sourceEntries = await entries(source);
 
   // Are all the keys integers?
   const integerKeys = sourceEntries.every(
-    ([key]) => !Number.isNaN(parseInt(key))
+    ([key]) => !Number.isNaN(parseInt(key)),
   );
 
   for (const [key, value] of sourceEntries) {
     // Get the groups for this value.
-    let groups = await groupKeyFn(value, key, source);
+    let groups = await fn(value, key, source);
     if (!groups) {
       continue;
     }

package/src/operations/has.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 
 /**
  * Returns true if the map has the given key, false otherwise.
@@ -9,6 +9,6 @@ import getMapArgument from "../utilities/getMapArgument.js";
  * @param {any} key
  */
 export default async function has(maplike, key) {
-  const map = await getMapArgument(maplike, "has");
+  const map = await args.map(maplike, "Tree.has");
   return map.has(key);
 }

package/src/operations/indent.js

@@ -1,3 +1,4 @@
+import interop from "../utilities/interop.js";
 import toString from "../utilities/toString.js";
 import deepText from "./deepText.js";
 import isMaplike from "./isMaplike.js";
@@ -21,7 +22,7 @@ export default async function indent(strings, ...values) {
   }
   const { blockIndentations, strings: modifiedStrings } = modified;
   const valueTexts = await Promise.all(
-    values.map((value) => (isMaplike(value) ? deepText(value) : value))
+    values.map((value) => (isMaplike(value) ? deepText(value) : value)),
   );
   return joinBlocks(modifiedStrings, valueTexts, blockIndentations);
 }
@@ -31,7 +32,12 @@ export default async function indent(strings, ...values) {
 function joinBlocks(strings, values, blockIndentations) {
   let result = strings[0];
   for (let i = 0; i < values.length; i++) {
-    let text = toString(values[i]);
+    const value = values[i];
+    let text = toString(value);
+    if (value == null) {
+      const message = `Warning: a template encountered a ${text} value.`;
+      interop.warn(message);
+    }
     if (text) {
       const blockIndentation = blockIndentations[i];
       if (blockIndentation) {
@@ -77,7 +83,7 @@ function modifyStrings(strings) {
     const indentationRegex = new RegExp(`\n${indent}`, "g");
     // The `replaceAll` also converts strings to a real array.
     modified = strings.map((string) =>
-      string.replaceAll(indentationRegex, "\n")
+      string.replaceAll(indentationRegex, "\n"),
     );
     // Remove indentation from last line of last string
     modified[modified.length - 1] = modified

package/src/operations/inners.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 isMap from "./isMap.js";
 
 /**
@@ -12,7 +12,7 @@ import isMap from "./isMap.js";
  * @param {Maplike} maplike
  */
 export default async function inners(maplike) {
-  const source = await getMapArgument(maplike, "inners");
+  const source = await args.map(maplike, "Tree.inners");
 
   return Object.assign(new AsyncMap(), {
     async get(key) {

package/src/operations/invokeFunctions.js

@@ -1,9 +1,9 @@
 import AsyncMap from "../drivers/AsyncMap.js";
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import isMap from "./isMap.js";
 
 export default async function invokeFunctions(maplike) {
-  const source = await getMapArgument(maplike, "invokeFunctions", {
+  const source = await args.map(maplike, "Tree.invokeFunctions", {
     deep: true,
   });
 

package/src/operations/json.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import toPlainValue from "../utilities/toPlainValue.js";
 
 /**
@@ -7,7 +7,7 @@ import toPlainValue from "../utilities/toPlainValue.js";
  * @param {import("../../index.ts").Maplike} maplike
  */
 export default async function json(maplike) {
-  const tree = await getMapArgument(maplike, "json");
+  const tree = await args.map(maplike, "Tree.json");
   const value = await toPlainValue(tree);
   return JSON.stringify(value, null, 2);
 }

package/src/operations/keys.js

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

package/src/operations/length.js

@@ -1,4 +1,4 @@
-import getMapArgument from "../utilities/getMapArgument.js";
+import * as args from "../utilities/args.js";
 import keys from "./keys.js";
 
 /**
@@ -10,7 +10,7 @@ import keys from "./keys.js";
  */
 export default async function length(maplike) {
   console.warn("Tree.length() is deprecated. Use Tree.size() instead.");
-  const tree = await getMapArgument(maplike, "length");
+  const tree = await args.map(maplike, "Tree.length");
   const treeKeys = await keys(tree);
   return treeKeys.length;
 }