@weborigami/async-tree 0.6.11 → 0.6.13

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.6.11",
+  "version": "0.6.13",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "24.10.1",
-    "puppeteer": "24.30.0",
+    "@types/node": "25.3.2",
+    "puppeteer": "24.37.5",
     "typescript": "5.9.3"
   },
   "scripts": {

package/src/Tree.js

@@ -8,6 +8,7 @@ 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 deepEntries } from "./operations/deepEntries.js";
 export { default as deepMap } from "./operations/deepMap.js";
@@ -21,6 +22,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/concat.js

@@ -0,0 +1,56 @@
+import { isUnpackable, SyncMap, Tree } from "@weborigami/async-tree";
+// import assignPropertyDescriptors from "./assignPropertyDescriptors.js";
+
+/**
+ * Concatenate the given trees. This is similar to a merge, but numeric keys
+ * will be renumbered starting with 0 and incrementing by 1.
+ *
+ * @typedef {import("@weborigami/async-tree").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 entries = await Tree.entries(source);
+    for (const [entryKey, entryValue] of entries) {
+      let key;
+      if (!isNaN(parseInt(entryKey))) {
+        // Numeric key, renumber it.
+        key = String(index);
+        index++;
+      } else {
+        // Non-numeric key, keep it as is.
+        key = entryKey;
+        onlyNumericKeys = false;
+      }
+      map.set(key, entryValue);
+    }
+  }
+
+  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/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 1 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 > 1 &&
+      (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,21 @@
+import * as args from "../utilities/args.js";
+import deepValuesIterator from "./deepValuesIterator.js";
+
+/**
+ * Flatten the values in the tree to the given depth.
+ *
+ * @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 });
+  /** @type {any} */
+  const iterator = deepValuesIterator(map, { depth, expand: true });
+  const result = [];
+  for await (const key of iterator) {
+    result.push(key);
+  }
+  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/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/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: 3,
+      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,58 @@
+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 the tree's values into an array", async () => {
+    const fixture = {
+      a: 1,
+      sub: {
+        b: 2,
+        more: {
+          c: 3,
+        },
+      },
+    };
+    assert.deepEqual(await flat(fixture, Infinity), [1, 2, 3]);
+  });
+
+  test("flattens one level by default", async () => {
+    const fixture = {
+      a: 1,
+      sub: {
+        b: 2,
+        more: {
+          c: 3,
+        },
+      },
+    };
+    assert.deepEqual(await plain(await flat(fixture)), [
+      1,
+      { b: 2, more: { c: 3 } },
+    ]);
+  });
+
+  test("flattens arrays", async () => {
+    assert.deepEqual(await flat([1, 2, [3]], Infinity), [1, 2, 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(result, [1, 2, 3, 4, 5, 6]);
+  });
+});