@weborigami/async-tree 0.6.12 → 0.6.14

package/package.json

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

package/src/Tree.js

@@ -8,8 +8,11 @@ export { default as cache } from "./operations/cache.js";
 export { default as calendar } from "./operations/calendar.js";
 export { default as child } from "./operations/child.js";
 export { default as clear } from "./operations/clear.js";
+export { default as concat } from "./operations/concat.js";
 export { default as constant } from "./operations/constant.js";
+export { default as deepArrays } from "./operations/deepArrays.js";
 export { default as deepEntries } from "./operations/deepEntries.js";
+export { default as deepEntriesIterator } from "./operations/deepEntriesIterator.js";
 export { default as deepMap } from "./operations/deepMap.js";
 export { default as deepMerge } from "./operations/deepMerge.js";
 export { default as deepReverse } from "./operations/deepReverse.js";
@@ -21,6 +24,7 @@ export { default as delete } from "./operations/delete.js";
 export { default as entries } from "./operations/entries.js";
 export { default as filter } from "./operations/filter.js";
 export { default as first } from "./operations/first.js";
+export { default as flat } from "./operations/flat.js";
 export { default as forEach } from "./operations/forEach.js";
 export { default as from } from "./operations/from.js";
 export { default as globKeys } from "./operations/globKeys.js";

package/src/drivers/AsyncMap.js

@@ -106,6 +106,49 @@ export default class AsyncMap {
     throw new Error("get() not implemented");
   }
 
+  /**
+   * Returns the value associated with the key, or defaultValue if there is
+   * none. If defaultValue is returned, it is also inserted into the map for the
+   * given key. If the `readOnly` property is true, calling this method throws a
+   * `TypeError` if the key is not already present in the map.
+   */
+  async getOrInsert(key, defaultValue) {
+    let value = await this.get(key);
+    if (value === undefined) {
+      if (this.readOnly) {
+        throw new TypeError(
+          "getOrInsert() can't insert into a new value into a read-only map.",
+        );
+      }
+      await this.set(key, defaultValue);
+      value = defaultValue;
+    }
+    return value;
+  }
+
+  /**
+   * Returns the value associated with the key, or the result of calling
+   * `defaultValueFn` if there is none. If the `readOnly` property is true,
+   * calling this method throws a `TypeError` if the key is not already present
+   * in the map.
+   *
+   * @param {any} key
+   * @param {() => any} defaultValueFn
+   */
+  async getOrInsertComputed(key, defaultValueFn) {
+    let value = await this.get(key);
+    if (value === undefined) {
+      if (this.readOnly) {
+        throw new TypeError(
+          "getOrInsertComputed() can't insert into a new value into a read-only map.",
+        );
+      }
+      const defaultValue = await defaultValueFn();
+      await this.set(key, defaultValue);
+      value = defaultValue;
+    }
+    return value;
+  }
   /**
    * Groups items from an async iterable into an AsyncMap according to the keys
    * returned by the given function.

package/src/drivers/SyncMap.js

@@ -139,6 +139,50 @@ export default class SyncMap extends Map {
     return value;
   }
 
+  /**
+   * Returns the value associated with the key, or defaultValue if there is
+   * none. If defaultValue is returned, it is also inserted into the map for the
+   * given key. If the `readOnly` property is true, calling this method throws a
+   * `TypeError` if the key is not already present in the map.
+   */
+  getOrInsert(key, defaultValue) {
+    let value = this.get(key);
+    if (value === undefined) {
+      if (this.readOnly) {
+        throw new TypeError(
+          "getOrInsert() can't insert into a new value into a read-only map.",
+        );
+      }
+      this.set(key, defaultValue);
+      value = defaultValue;
+    }
+    return value;
+  }
+
+  /**
+   * Returns the value associated with the key, or the result of calling
+   * `defaultValueFn` if there is none. If the `readOnly` property is true,
+   * calling this method throws a `TypeError` if the key is not already present
+   * in the map.
+   *
+   * @param {any} key
+   * @param {() => any} defaultValueFn
+   */
+  getOrInsertComputed(key, defaultValueFn) {
+    let value = this.get(key);
+    if (value === undefined) {
+      if (this.readOnly) {
+        throw new TypeError(
+          "getOrInsertComputed() can't insert into a new value into a read-only map.",
+        );
+      }
+      const defaultValue = defaultValueFn();
+      this.set(key, defaultValue);
+      value = defaultValue;
+    }
+    return value;
+  }
+
   /**
    * Returns true if the given key appears in the set returned by keys().
    *

package/src/operations/addNextPrevious.js

@@ -51,6 +51,8 @@ export default async function addNextPrevious(maplike) {
       yield* sourceKeys;
     },
 
+    source,
+
     trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
   });
 }

package/src/operations/concat.js

@@ -0,0 +1,59 @@
+import SyncMap from "../drivers/SyncMap.js";
+import * as trailingSlash from "../trailingSlash.js";
+import isUnpackable from "../utilities/isUnpackable.js";
+import entries from "./entries.js";
+
+/**
+ * Concatenate the given trees. This is similar to a merge, but numeric keys
+ * will be renumbered starting with 0 and incrementing by 1.
+ *
+ * If the final result is array-like, returns an array, otherwise returns a map.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {(Maplike|null)[]} trees
+ */
+export default async function concat(...trees) {
+  // Filter out null or undefined trees.
+  /** @type {Maplike[]}
+   * @ts-ignore */
+  const filtered = trees.filter((tree) => tree);
+
+  // Unpack any packed objects.
+  const sources = await Promise.all(
+    filtered.map((obj) =>
+      isUnpackable(obj) ? /** @type {any} */ (obj).unpack() : obj,
+    ),
+  );
+
+  if (sources.length === 0) {
+    throw new TypeError("Tree.concat: all arguments are null or undefined");
+  }
+
+  let index = 0;
+  let onlyNumericKeys = true;
+  const map = new SyncMap();
+  for (const source of sources) {
+    const sourceEntries = await entries(source);
+    for (let [key, value] of sourceEntries) {
+      key = trailingSlash.remove(key);
+      if (typeof key === "number" || /^\d+$/.test(key)) {
+        // Numeric key, renumber it.
+        key = String(index);
+        index++;
+      } else {
+        // Non-numeric key, keep it as is.
+        onlyNumericKeys = false;
+      }
+      map.set(key, value);
+    }
+  }
+
+  if (onlyNumericKeys) {
+    // All keys are numeric, return an array.
+    return [...map.values()];
+  } else {
+    // Some keys are non-numeric, return a map.
+    return map;
+  }
+}

package/src/operations/deepArrays.js

@@ -0,0 +1,23 @@
+import * as args from "../utilities/args.js";
+import entries from "./entries.js";
+import isMap from "./isMap.js";
+
+/**
+ * Return the deep nested entries in the tree as arrays of [key, value] pairs.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ */
+export default async function deepEntries(maplike) {
+  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/deepEntries.js

@@ -1,6 +1,5 @@
 import * as args from "../utilities/args.js";
-import entries from "./entries.js";
-import isMap from "./isMap.js";
+import deepEntriesIterator from "./deepEntriesIterator.js";
 
 /**
  * Return the deep nested entries in the tree as arrays of [key, value] pairs.
@@ -12,12 +11,10 @@ import isMap from "./isMap.js";
 export default async function deepEntries(maplike) {
   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;
+  const iterator = deepEntriesIterator(tree, { depth: Infinity });
+  const entries = [];
+  for await (const entry of iterator) {
+    entries.push(entry);
+  }
+  return entries;
 }

package/src/operations/deepEntriesIterator.js

@@ -0,0 +1,45 @@
+import * as args from "../utilities/args.js";
+import isUnpackable from "../utilities/isUnpackable.js";
+import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
+/**
+ * Return an iterator that yields all entries in a tree, including nested trees.
+ *
+ * If the `expand` option is true, maplike values (but not functions) will be
+ * expanded into nested trees and their values will be yielded. Packed values
+ * will be unpacked before expanding.
+ *
+ * If the `depth` option is specified, the iterator will only descend to the
+ * specified depth. A depth of 0 will yield values only at the tree's top level.
+ *
+ * @param {import("../../index.ts").Maplike} maplike
+ * @param {{ depth?: number, expand?: boolean }} [options]
+ * @returns {AsyncGenerator<[any, any], void, undefined>}
+ */
+export default async function* deepEntriesIterator(maplike, options = {}) {
+  const tree = await args.map(maplike, "Tree.deepEntriesIterator", {
+    deep: !options.expand,
+  });
+
+  const depth = options.depth ?? Infinity;
+  const expand = options.expand ?? false;
+
+  for await (let [key, value] of tree.entries()) {
+    value = await value;
+
+    if (expand && isUnpackable(value)) {
+      value = await value.unpack();
+    }
+
+    // Recurse into child trees, but don't expand functions.
+    const recurse =
+      depth > 0 &&
+      (isMap(value) ||
+        (expand && typeof value !== "function" && isMaplike(value)));
+    if (recurse) {
+      yield* deepEntriesIterator(value, { depth: depth - 1, expand });
+    } else {
+      yield [key, value];
+    }
+  }
+}

package/src/operations/deepValuesIterator.js

@@ -1,4 +1,5 @@
 import * as args from "../utilities/args.js";
+import isUnpackable from "../utilities/isUnpackable.js";
 import isMap from "./isMap.js";
 import isMaplike from "./isMaplike.js";
 
@@ -6,29 +7,38 @@ import isMaplike from "./isMaplike.js";
  * Return an iterator that yields all values in a tree, including nested trees.
  *
  * If the `expand` option is true, maplike values (but not functions) will be
- * expanded into nested trees and their values will be yielded.
+ * expanded into nested trees and their values will be yielded. Packed values
+ * will be unpacked before expanding.
+ *
+ * If the `depth` option is specified, the iterator will only descend to the
+ * specified depth. A depth of 0 will yield values only at the tree's top level.
  *
  * @param {import("../../index.ts").Maplike} maplike
- * @param {{ expand?: boolean }} [options]
+ * @param {{ depth?: number, expand?: boolean }} [options]
  * @returns {AsyncGenerator<any, void, undefined>}
  */
-export default async function* deepValuesIterator(
-  maplike,
-  options = { expand: false },
-) {
+export default async function* deepValuesIterator(maplike, options = {}) {
   const tree = await args.map(maplike, "Tree.deepValuesIterator", {
-    deep: true,
+    deep: !options.expand,
   });
 
+  const depth = options.depth ?? Infinity;
+  const expand = options.expand ?? false;
+
   for await (const key of tree.keys()) {
-    const value = await tree.get(key);
+    let value = await tree.get(key);
+
+    if (expand && isUnpackable(value)) {
+      value = await value.unpack();
+    }
 
     // Recurse into child trees, but don't expand functions.
     const recurse =
-      isMap(value) ||
-      (options.expand && typeof value !== "function" && isMaplike(value));
+      depth > 0 &&
+      (isMap(value) ||
+        (expand && typeof value !== "function" && isMaplike(value)));
     if (recurse) {
-      yield* deepValuesIterator(value, options);
+      yield* deepValuesIterator(value, { depth: depth - 1, expand });
     } else {
       yield value;
     }

package/src/operations/flat.js

@@ -0,0 +1,45 @@
+import SyncMap from "../drivers/SyncMap.js";
+import * as trailingSlash from "../trailingSlash.js";
+import * as args from "../utilities/args.js";
+import deepEntriesIterator from "./deepEntriesIterator.js";
+
+/**
+ * Flatten the entries in the tree to the given depth. If the depth is omitted,
+ * the tree will be flattened one level.
+ *
+ * Numeric keys will be renumbered.
+ *
+ * If the final result is array-like, returns an array, otherwise returns a map.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ * @param {number} [depth] The maximum depth to flatten
+ */
+export default async function flat(maplike, depth = 1) {
+  const map = await args.map(maplike, "Tree.flat", { deep: true });
+
+  let index = 0;
+  let onlyNumericKeys = true;
+  const result = new SyncMap();
+  for await (let [key, value] of deepEntriesIterator(map, { depth })) {
+    key = trailingSlash.remove(key);
+    if (typeof key === "number" || /^\d+$/.test(key)) {
+      // Numeric key, renumber it.
+      key = String(index);
+      index++;
+    } else {
+      // Non-numeric key, keep it as is.
+      onlyNumericKeys = false;
+    }
+    result.set(key, value);
+  }
+
+  if (onlyNumericKeys) {
+    // All keys are numeric, return an array.
+    return [...result.values()];
+  } else {
+    // Some keys are non-numeric, return a map.
+    return result;
+  }
+}

package/src/operations/isMap.js

@@ -16,6 +16,7 @@ export default function isMap(object) {
   }
 
   // Check for Map-like interface
+  // Note: doesn't require the getOrInsert or getOrInsertComputed members.
   if (
     object &&
     object.clear instanceof Function &&

package/src/operations/merge.js

@@ -48,7 +48,7 @@ export default async function merge(...treelikes) {
   const sources = unpacked.map((maplike) => from(maplike));
 
   if (sources.length === 0) {
-    throw new TypeError("merge: all trees are null or undefined");
+    throw new TypeError("Tree.merge: all trees are null or undefined");
   } else if (sources.length === 1) {
     // Only one tree, no need to merge
     return sources[0];

package/src/utilities/getParent.js

@@ -19,7 +19,10 @@ export default function getParent(packed, options = {}) {
 
   // If the packed object has a `parent` property, use that. Exception: Node
   // Buffer objects have a `parent` property that we ignore.
-  if (packed.parent && !(packed instanceof Buffer)) {
+  if (
+    packed.parent &&
+    !(typeof Buffer !== "undefined" && packed instanceof Buffer)
+  ) {
     return packed.parent;
   }
 

package/test/drivers/AsyncMap.test.js

@@ -44,6 +44,55 @@ describe("AsyncMap", () => {
     ]);
   });
 
+  test("getOrInsert", async () => {
+    const map = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    assert.strictEqual(await map.getOrInsert("a", 100), 1);
+    assert.strictEqual(await map.getOrInsert("c", 3), 3);
+    assert.strictEqual(await map.get("c"), 3);
+  });
+
+  test("getOrInsert on read-only map throws if key doesn't exist", async () => {
+    class Fixture extends AsyncMap {
+      constructor(entries) {
+        super();
+        this.map = new Map(entries);
+      }
+
+      async get(key) {
+        let value = this.map.get(key);
+        if (value instanceof Array) {
+          value = Reflect.construct(this.constructor, [value]);
+        }
+        return value;
+      }
+    }
+
+    const map = new Fixture([
+      ["a", 1],
+      ["b", 2],
+    ]);
+
+    assert.strictEqual(await map.getOrInsert("a", 100), 1);
+    await assert.rejects(async () => await map.getOrInsert("c", 3), {
+      name: "TypeError",
+      message:
+        "getOrInsert() can't insert into a new value into a read-only map.",
+    });
+  });
+
+  test("getOrInsertComputed", async () => {
+    const map = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    assert.strictEqual(await map.getOrInsertComputed("a", async () => 100), 1);
+    assert.strictEqual(await map.getOrInsertComputed("c", async () => 3), 3);
+    assert.strictEqual(await map.get("c"), 3);
+  });
+
   test("static groupBy", async () => {
     const items = [
       { name: "apple", type: "fruit" },
@@ -52,7 +101,7 @@ describe("AsyncMap", () => {
     ];
     const map = await AsyncMap.groupBy(
       items,
-      async (element, index) => element.type
+      async (element, index) => element.type,
     );
     assert.deepStrictEqual(Array.from(map.entries()), [
       [

package/test/drivers/SyncMap.test.js

@@ -133,6 +133,50 @@ describe("SyncMap", () => {
     assert.strictEqual(map.get("c"), undefined);
   });
 
+  test("getOrInsert", () => {
+    const map = new SyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    assert.strictEqual(map.getOrInsert("a", 100), 1);
+    assert.strictEqual(map.getOrInsert("c", 3), 3);
+    assert.strictEqual(map.get("c"), 3);
+  });
+
+  test("getOrInsert on read-only map throws if key doesn't exist", () => {
+    class Fixture extends SyncMap {
+      get(key) {
+        return super.get(key);
+      }
+    }
+    const map = new Fixture([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    assert.strictEqual(map.getOrInsert("a", 100), 1);
+    assert.throws(() => map.getOrInsert("c", 3), {
+      name: "TypeError",
+      message:
+        "getOrInsert() can't insert into a new value into a read-only map.",
+    });
+  });
+
+  test("getOrInsertComputed", () => {
+    const map = new SyncMap([
+      ["a", 1],
+      ["b", 2],
+    ]);
+    assert.strictEqual(
+      map.getOrInsertComputed("a", () => 100),
+      1,
+    );
+    assert.strictEqual(
+      map.getOrInsertComputed("c", () => 3),
+      3,
+    );
+    assert.strictEqual(map.get("c"), 3);
+  });
+
   test("has returns true if key exists in keys()", () => {
     const map = new SyncMap();
     map.keys = () => {
@@ -321,7 +365,7 @@ describe("SyncMap", () => {
       ]);
       // @ts-ignore
       const grouped = Map.groupBy(map, ([key, value]) =>
-        value % 2 === 0 ? "even" : "odd"
+        value % 2 === 0 ? "even" : "odd",
       );
       assert(grouped instanceof Map);
       assert.strictEqual(grouped.size, 2);

package/test/operations/assign.test.js

@@ -3,8 +3,8 @@ import { describe, test } from "node:test";
 import ObjectMap from "../../src/drivers/ObjectMap.js";
 import SyncMap from "../../src/drivers/SyncMap.js";
 import assign from "../../src/operations/assign.js";
+import deepArrays from "../../src/operations/deepArrays.js";
 import plain from "../../src/operations/plain.js";
-import { deepEntries } from "../../src/Tree.js";
 import SampleAsyncMap from "../SampleAsyncMap.js";
 
 describe("assign", () => {
@@ -26,7 +26,7 @@ describe("assign", () => {
     const result = await assign(target, source);
 
     assert.equal(result, target);
-    assert.deepEqual(await deepEntries(target), [
+    assert.deepEqual(await deepArrays(target), [
       ["a", 4],
       ["b", 2],
       [

package/test/operations/concat.test.js

@@ -0,0 +1,66 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectMap from "../../src/drivers/ObjectMap.js";
+import concat from "../../src/operations/concat.js";
+
+describe("concat", () => {
+  test("concatenates arrays", async () => {
+    const result = await concat(["a", "b"], ["c", "d"]);
+    assert.deepEqual(result, ["a", "b", "c", "d"]);
+  });
+
+  test("concatenates maplike objects", async () => {
+    const result = await concat(
+      {
+        1: "a",
+        2: "b",
+      },
+      new ObjectMap({
+        0: "c",
+        1: "d",
+      }),
+      ["e", "f"],
+    );
+    assert.deepEqual(result, ["a", "b", "c", "d", "e", "f"]);
+  });
+
+  test("copes with mixture of numeric and non-numeric keys", async () => {
+    const result = await concat(
+      ["a", "b"],
+      {
+        x: 1,
+        y: 2,
+      },
+      ["c", "d"],
+    );
+    assert.deepEqual(
+      [...result.entries()],
+      [
+        ["0", "a"],
+        ["1", "b"],
+        ["x", 1],
+        ["y", 2],
+        ["2", "c"],
+        ["3", "d"],
+      ],
+    );
+  });
+
+  test("can unpack arguments", async () => {
+    /** @type {any} */
+    const packed1 = new String("Packed array");
+    packed1.unpack = async function () {
+      return ["a", "b"];
+    };
+    /** @type {any} */
+    const packed2 = new String("Packed object");
+    packed2.unpack = async function () {
+      return {
+        0: "c",
+        1: "d",
+      };
+    };
+    const result = await concat(packed1, packed2);
+    assert.deepEqual(result, ["a", "b", "c", "d"]);
+  });
+});

package/test/operations/deepArrays.test.js

@@ -0,0 +1,32 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import deepArrays from "../../src/operations/deepArrays.js";
+import SampleAsyncMap from "../SampleAsyncMap.js";
+
+describe("deepArrays", () => {
+  test("converts an async tree to an array of nested entries arrays", async () => {
+    const fixture = new SampleAsyncMap([
+      ["a", 1],
+      ["b", 2],
+      [
+        "more",
+        [
+          ["c", 3],
+          ["d", 4],
+        ],
+      ],
+    ]);
+    const result = await deepArrays(fixture);
+    assert.deepStrictEqual(result, [
+      ["a", 1],
+      ["b", 2],
+      [
+        "more",
+        [
+          ["c", 3],
+          ["d", 4],
+        ],
+      ],
+    ]);
+  });
+});

package/test/operations/deepEntries.test.js

@@ -4,7 +4,7 @@ import deepEntries from "../../src/operations/deepEntries.js";
 import SampleAsyncMap from "../SampleAsyncMap.js";
 
 describe("deepEntries", () => {
-  test("converts an async tree to an array of nested entries arrays", async () => {
+  test("returns an entry of the deep tree entries", async () => {
     const fixture = new SampleAsyncMap([
       ["a", 1],
       ["b", 2],
@@ -20,13 +20,8 @@ describe("deepEntries", () => {
     assert.deepStrictEqual(result, [
       ["a", 1],
       ["b", 2],
-      [
-        "more",
-        [
-          ["c", 3],
-          ["d", 4],
-        ],
-      ],
+      ["c", 3],
+      ["d", 4],
     ]);
   });
 });

package/test/operations/deepEntriesIterator.test.js

@@ -0,0 +1,78 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectMap from "../../src/drivers/ObjectMap.js";
+import deepEntriesIterator from "../../src/operations/deepEntriesIterator.js";
+
+describe("deepEntriesIterator", () => {
+  test("returns an iterator of a tree's deep entries", async () => {
+    const tree = new ObjectMap({
+      a: 1,
+      b: 2,
+      more: {
+        c: 3,
+        d: 4,
+      },
+    });
+    const entries = [];
+    // The tree will be shallow, but we'll ask to expand the entries.
+    for await (const entry of deepEntriesIterator(tree, { expand: true })) {
+      entries.push(entry);
+    }
+    assert.deepEqual(entries, [
+      ["a", 1],
+      ["b", 2],
+      ["c", 3],
+      ["d", 4],
+    ]);
+  });
+
+  test("if depth is specified, only descends to specified depth", async () => {
+    const tree = new ObjectMap({
+      a: 1,
+      sub: {
+        b: 2,
+        more: {
+          c: 3,
+          deeper: {
+            d: 4,
+          },
+        },
+      },
+    });
+    const entries = [];
+    for await (const entry of deepEntriesIterator(tree, {
+      depth: 2,
+      expand: true,
+    })) {
+      entries.push(entry);
+    }
+    assert.deepEqual(entries, [
+      ["a", 1],
+      ["b", 2],
+      ["c", 3],
+      ["deeper", { d: 4 }],
+    ]);
+  });
+
+  test("can optionally unpack a packed value", async () => {
+    /** @type {any} */
+    const packed = new String("String that unpacks to data");
+    packed.unpack = async function () {
+      return {
+        message: "Hello",
+      };
+    };
+    const tree = {
+      a: 1,
+      packed,
+    };
+    const entries = [];
+    for await (const entry of deepEntriesIterator(tree, { expand: true })) {
+      entries.push(entry);
+    }
+    assert.deepEqual(entries, [
+      ["a", 1],
+      ["message", "Hello"],
+    ]);
+  });
+});

package/test/operations/deepValuesIterator.test.js

@@ -20,4 +20,46 @@ describe("deepValuesIterator", () => {
     }
     assert.deepEqual(values, [1, 2, 3, 4]);
   });
+
+  test("if depth is specified, only descends to specified depth", async () => {
+    const tree = new ObjectMap({
+      a: 1,
+      sub: {
+        b: 2,
+        more: {
+          c: 3,
+          deeper: {
+            d: 4,
+          },
+        },
+      },
+    });
+    const values = [];
+    for await (const value of deepValuesIterator(tree, {
+      depth: 2,
+      expand: true,
+    })) {
+      values.push(value);
+    }
+    assert.deepEqual(values, [1, 2, 3, { d: 4 }]);
+  });
+
+  test("can optionally unpack a packed value", async () => {
+    /** @type {any} */
+    const packed = new String("String that unpacks to data");
+    packed.unpack = async function () {
+      return {
+        message: "Hello",
+      };
+    };
+    const tree = {
+      a: 1,
+      packed,
+    };
+    const values = [];
+    for await (const value of deepValuesIterator(tree, { expand: true })) {
+      values.push(value);
+    }
+    assert.deepEqual(values, [1, "Hello"]);
+  });
 });

package/test/operations/flat.test.js

@@ -0,0 +1,82 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import ObjectMap from "../../src/drivers/ObjectMap.js";
+import flat from "../../src/operations/flat.js";
+import plain from "../../src/operations/plain.js";
+
+describe("flat", () => {
+  test("flattens an array one level by default", async () => {
+    const result = await flat([1, 2, [3], [[4, [5]]]], 1);
+    assert.deepEqual(await plain(result), [1, 2, 3, [4, [5]]]);
+  });
+
+  test("flattens deep arrays", async () => {
+    assert.deepEqual(
+      await flat([1, 2, [3], [[4, [5]]]], Infinity),
+      [1, 2, 3, 4, 5],
+    );
+  });
+
+  test("flattens an object one level by default", async () => {
+    const fixture = {
+      a: 1,
+      sub: {
+        b: 2,
+        more: {
+          c: 3,
+        },
+      },
+    };
+    const result = await flat(fixture);
+    assert.deepEqual(await plain(result), {
+      a: 1,
+      b: 2,
+      more: {
+        c: 3,
+      },
+    });
+  });
+
+  test("flattens deep objects", async () => {
+    const fixture = {
+      a: 1,
+      sub: {
+        b: 2,
+        more: {
+          c: 3,
+        },
+      },
+    };
+    const result = await flat(fixture, Infinity);
+    assert.deepEqual(await plain(result), {
+      a: 1,
+      b: 2,
+      c: 3,
+    });
+  });
+
+  test("flattens maplike objects", async () => {
+    const result = await flat(
+      [
+        {
+          a: 1,
+          b: 2,
+        },
+        new ObjectMap({
+          c: 3,
+          d: 4,
+        }),
+        [5, 6],
+      ],
+      Infinity,
+    );
+    assert.deepEqual(await plain(result), {
+      a: 1,
+      b: 2,
+      c: 3,
+      d: 4,
+      0: 5,
+      1: 6,
+    });
+  });
+});