@weborigami/async-tree 0.6.9 → 0.6.11

package/src/operations/traverseOrThrow.js

@@ -1,7 +1,9 @@
 import * as trailingSlash from "../trailingSlash.js";
 import TraverseError from "../TraverseError.js";
+import isPacked from "../utilities/isPacked.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import from from "./from.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Return the value at the corresponding path of keys. Throw if any interior
@@ -11,11 +13,13 @@ import from from "./from.js";
  *
  * @param {Maplike} maplike
  * @param  {...any} keys
+ * @returns {Promise<any>}
  */
 export default async function traverseOrThrow(maplike, ...keys) {
-  // Start our traversal at the root of the tree.
-  /** @type {any} */
   let value = maplike;
+
+  // For error reporting
+  let lastValue = value;
   let position = 0;
 
   // Process all the keys.
@@ -23,16 +27,31 @@ export default async function traverseOrThrow(maplike, ...keys) {
   let key;
   while (remainingKeys.length > 0) {
     if (value == null) {
-      throw new TraverseError("A null or undefined value can't be traversed", {
-        tree: maplike,
+      throw new TraverseError("A path hit a null or undefined value.", {
+        head: maplike,
+        lastValue,
         keys,
         position,
       });
     }
 
+    lastValue = value;
+
     // If the value is packed and can be unpacked, unpack it.
-    if (isUnpackable(value)) {
-      value = await value.unpack();
+    if (isPacked(value)) {
+      if (typeof (/** @type {any} */ (value).unpack) === "function") {
+        value = await value.unpack();
+      } else {
+        throw new TraverseError(
+          "A path hit binary file data that can't be unpacked.",
+          {
+            head: maplike,
+            lastValue,
+            keys,
+            position,
+          },
+        );
+      }
     }
 
     if (value instanceof Function) {
@@ -60,8 +79,21 @@ export default async function traverseOrThrow(maplike, ...keys) {
   }
 
   // If last key ended in a slash and value is unpackable, unpack it.
-  if (key && trailingSlash.has(key) && isUnpackable(value)) {
-    value = await value.unpack();
+  if (key && trailingSlash.has(key) && !isMaplike(value)) {
+    if (isUnpackable(value)) {
+      value = await value.unpack();
+    } else {
+      const message =
+        value === undefined
+          ? "A path tried to unpack a value that doesn't exist."
+          : "A path tried to unpack data that's already unpacked.";
+      throw new TraverseError(message, {
+        head: maplike,
+        lastValue,
+        keys,
+        position,
+      });
+    }
   }
 
   return value;

package/src/operations/traversePath.js

@@ -1,3 +1,4 @@
+import * as args from "../utilities/args.js";
 import keysFromPath from "../utilities/keysFromPath.js";
 import traverse from "./traverse.js";
 
@@ -7,10 +8,11 @@ import traverse from "./traverse.js";
  *
  * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Maplike} tree
+ * @param {Maplike} maplike
  * @param {string} path
  */
-export default async function traversePath(tree, path) {
+export default async function traversePath(maplike, path) {
+  const map = await args.map(maplike, "Tree.traversePath");
   const keys = keysFromPath(path);
-  return traverse(tree, ...keys);
+  return traverse(map, ...keys);
 }

package/src/operations/values.js

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

package/src/operations/visit.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 visit(source) {
-  const tree = await getMapArgument(source, "visit", { deep: true });
+  const tree = await args.map(source, "Tree.visit", { deep: true });
   return reduce(tree, () => undefined);
 }

package/src/operations/withKeys.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 values from "./values.js";
 
 /**
@@ -13,10 +13,12 @@ import values from "./values.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function withKeys(maplike, keysMaplike) {
-  const source = await getMapArgument(maplike, "withKeys", { position: 0 });
-  const keysMap = await getMapArgument(keysMaplike, "withKeys", {
+  const source = await args.map(maplike, "Tree.withKeys", {
     position: 1,
   });
+  const keysMap = await args.map(keysMaplike, "Tree.withKeys", {
+    position: 2,
+  });
 
   let keys;
 

package/src/utilities/args.js

@@ -0,0 +1,128 @@
+import from from "../operations/from.js";
+import isUnpackable from "./isUnpackable.js";
+import toFunction from "./toFunction.js";
+import toString from "./toString.js";
+
+/**
+ * Runtime argument checking.
+ *
+ * These return a particular kind of argument or throw an error.
+ *
+ * Operations can use these to validate the arguments and provide more helpful
+ * error messages.
+ */
+
+/**
+ * Check a function argument.
+ */
+export function fn(arg, operation, options = {}) {
+  if (typeof arg !== "function") {
+    /** @type {any} */
+    const error = new TypeError(`${operation}: Expected a function argument.`);
+    error.position = options.position ?? 1;
+    throw error;
+  }
+  return arg;
+}
+
+/**
+ * Check an invocable argument and return it as a function.
+ *
+ * @param {import("../../index.ts").Invocable} arg
+ * @param {string} operation
+ * @returns {Function}
+ */
+export function invocable(arg, operation, options = {}) {
+  const fn = toFunction(arg);
+  if (!fn) {
+    /** @type {any} */
+    const error = new TypeError(`${operation}: Expected a function argument.`);
+    error.position = options.position ?? 1;
+    throw error;
+  }
+  return fn;
+}
+
+/**
+ * Check a maplike argument and return it as a Map or AsyncMap.
+ *
+ * @typedef {import("../../index.ts").AsyncMap} AsyncMap
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ * @typedef {import("../../index.ts").Unpackable} Unpackable
+ *
+ * @param {Maplike|Unpackable} arg
+ * @param {string} operation
+ * @param {{ deep?: boolean, position?: number }} [options]
+ * @returns {Promise<Map|AsyncMap>}
+ */
+export async function map(arg, operation, options = {}) {
+  const deep = options.deep;
+  const position = options.position ?? 1;
+
+  if (isUnpackable(arg)) {
+    arg = await arg.unpack();
+  }
+
+  let map;
+  try {
+    map = from(arg, { deep });
+  } catch (/** @type {any} */ error) {
+    let message = error.message ?? error;
+    message = `${operation}: ${message}`;
+    const newError = new error.constructor(message);
+    /** @type {any} */ (newError).position = position;
+    throw newError;
+  }
+  return map;
+}
+
+/**
+ * Check a number argument.
+ *
+ * @param {number} arg
+ * @param {string} operation
+ */
+export function number(arg, operation, options = {}) {
+  if (typeof arg !== "number" || Number.isNaN(arg)) {
+    /** @type {any} */
+    const error = new TypeError(`${operation}: Expected a number argument.`);
+    error.position = options.position ?? 1;
+    throw error;
+  }
+  return arg;
+}
+
+/**
+ * Check a string argument.
+ *
+ * @param {string} arg
+ * @param {string} operation
+ */
+export function string(arg, operation, options = {}) {
+  if (typeof arg !== "string") {
+    /** @type {any} */
+    const error = new TypeError(`${operation}: Expected a string argument.`);
+    error.position = options.position ?? 1;
+    throw error;
+  }
+  return arg;
+}
+
+/**
+ * Check a stringlike argument.
+ *
+ * @param {import("../../index.ts").Stringlike} arg
+ * @param {string} operation
+ */
+export function stringlike(arg, operation, options = {}) {
+  const result = toString(arg);
+  if (!result) {
+    /** @type {any} */
+    const error = new TypeError(
+      `${operation}: Expected a stringlike argument.`,
+    );
+    error.position = options.position ?? 1;
+    throw error;
+  }
+  return result;
+}

package/src/utilities/interop.js

@@ -0,0 +1,9 @@
+/**
+ * Functions that can be configured by async-tree consumers for interoperability.
+ */
+
+export default {
+  warn(...args) {
+    console.warn(...args);
+  },
+};

package/src/utilities/setParent.js

@@ -9,7 +9,7 @@ import * as symbols from "../symbols.js";
  * @typedef {import("../../index.ts").SyncOrAsyncMap} SyncOrAsyncMap
  *
  * @param {*} child
- * @param {SyncOrAsyncMap|null} parent
+ * @param {any} parent
  */
 export default function setParent(child, parent) {
   if (isMap(child)) {

package/test/operations/root.test.js

@@ -14,10 +14,10 @@ describe("root", () => {
           },
         },
       },
-      { deep: true }
+      { deep: true },
     );
     const c = await traverse(tree, "a", "b", "c");
-    const r = await root(c);
+    const r = c ? await root(c) : undefined;
     assert.strictEqual(r, tree);
   });
 });

package/test/operations/traverse.test.js

@@ -18,38 +18,7 @@ describe("traverse", () => {
     assert.equal(await traverse(tree), tree);
     assert.equal(await traverse(tree, "a1"), 1);
     assert.equal(await traverse(tree, "a2", "b2", "c2"), 4);
+    // Should return undefined instead of throwing
     assert.equal(await traverse(tree, "a2", "doesntexist", "c2"), undefined);
   });
-
-  test("traverses a function with fixed number of arguments", async () => {
-    const tree = (a, b) => ({
-      c: "Result",
-    });
-    assert.equal(await traverse(tree, "a", "b", "c"), "Result");
-  });
-
-  test("traverses from one tree into another", async () => {
-    const tree = new ObjectMap({
-      a: {
-        b: new Map([
-          ["c", "Hello"],
-          ["d", "Goodbye"],
-        ]),
-      },
-    });
-    assert.equal(await traverse(tree, "a", "b", "c"), "Hello");
-  });
-
-  test("unpacks last value if key ends in a slash", async () => {
-    const tree = new ObjectMap({
-      a: {
-        b: Object.assign(new String("packed"), {
-          unpack() {
-            return "unpacked";
-          },
-        }),
-      },
-    });
-    assert.equal(await traverse(tree, "a/", "b/"), "unpacked");
-  });
 });

package/test/operations/traverseOrThrow.test.js

@@ -0,0 +1,73 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectMap from "../../src/drivers/ObjectMap.js";
+import traverseOrThrow from "../../src/operations/traverseOrThrow.js";
+
+describe("traverseOrThrow", () => {
+  test("traverses a path of keys", async () => {
+    const tree = new ObjectMap({
+      a1: 1,
+      a2: {
+        b1: 2,
+        b2: {
+          c1: 3,
+          c2: 4,
+        },
+      },
+    });
+    assert.equal(await traverseOrThrow(tree), tree);
+    assert.equal(await traverseOrThrow(tree, "a1"), 1);
+    assert.equal(await traverseOrThrow(tree, "a2", "b2", "c2"), 4);
+    assert.rejects(
+      async () => await traverseOrThrow(tree, "a2", "doesntexist", "c2"),
+      {
+        name: "TraverseError",
+        message: "A path hit a null or undefined value.",
+      },
+    );
+  });
+
+  test("traverses a function with fixed number of arguments", async () => {
+    const tree = (a, b) => ({
+      c: "Result",
+    });
+    assert.equal(await traverseOrThrow(tree, "a", "b", "c"), "Result");
+  });
+
+  test("traverses from one tree into another", async () => {
+    const tree = new ObjectMap({
+      a: {
+        b: new Map([
+          ["c", "Hello"],
+          ["d", "Goodbye"],
+        ]),
+      },
+    });
+    assert.equal(await traverseOrThrow(tree, "a", "b", "c"), "Hello");
+  });
+
+  test("unpacks last value if key ends in a slash", async () => {
+    const tree = new ObjectMap({
+      a: {
+        b: Object.assign(new String("packed"), {
+          unpack() {
+            return "unpacked";
+          },
+        }),
+      },
+    });
+    assert.equal(await traverseOrThrow(tree, "a/", "b/"), "unpacked");
+  });
+
+  test("throws if the last key ends in a slash but the value can't be unpacked", async () => {
+    const tree = new ObjectMap({
+      a: {
+        b: 1,
+      },
+    });
+    await assert.rejects(async () => await traverseOrThrow(tree, "a/", "b/"), {
+      name: "TraverseError",
+      message: "A path tried to unpack data that's already unpacked.",
+    });
+  });
+});

package/src/utilities/getMapArgument.js

@@ -1,38 +0,0 @@
-import from from "../operations/from.js";
-import isUnpackable from "./isUnpackable.js";
-
-/**
- * Convert the indicated argument to a map, or throw an exception.
- *
- * Tree operations can use this to validate the map argument and provide more
- * helpful error messages. This also unpacks a unpackable map argument.
- *
- * @typedef {import("../../index.ts").AsyncMap} AsyncMap
- * @typedef {import("../../index.ts").Maplike} Maplike
- * @typedef {import("../../index.ts").Unpackable} Unpackable
- *
- * @param {Maplike|Unpackable} maplike
- * @param {string} operation
- * @param {{ deep?: boolean, position?: number }} [options]
- * @returns {Promise<Map|AsyncMap>}
- */
-export default async function getMapArgument(maplike, operation, options = {}) {
-  const deep = options.deep;
-  const position = options.position ?? 0;
-
-  if (isUnpackable(maplike)) {
-    maplike = await maplike.unpack();
-  }
-
-  let map;
-  try {
-    map = from(maplike, { deep });
-  } catch (/** @type {any} */ error) {
-    let message = error.message ?? error;
-    message = `${operation}: ${message}`;
-    const newError = new TypeError(message);
-    /** @type {any} */ (newError).position = position;
-    throw newError;
-  }
-  return map;
-}