@weborigami/async-tree 0.6.16 → 0.6.17

package/package.json

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

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 combine } from "./operations/combine.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";

package/src/operations/combine.js

@@ -0,0 +1,59 @@
+import * as args from "../utilities/args.js";
+import isUnpackable from "../utilities/isUnpackable.js";
+import isMap from "./isMap.js";
+import keys from "./keys.js";
+
+/**
+ * Does a pairwise invocation of `combineFn` for each value in the two trees. If
+ * one tree has a key that the other doesn't, the  `combineFn` will be invoked
+ * with `undefined` for the missing value.
+ *
+ * This returns a new tree of all the results of the `combineFn` invocations
+ * that were not `undefined`. If all results were `undefined`, the overall
+ * result is itself `undefined`.
+ *
+ * @typedef {import("@weborigami/async-tree").Maplike} Maplike
+ *
+ * @param {Maplike} maplike1
+ * @param {Maplike} maplike2
+ * @param {function} combineFn
+ */
+export default async function combine(maplike1, maplike2, combineFn) {
+  const tree1 = await args.map(maplike1, "Tree.combine", {
+    deep: true,
+    position: 1,
+  });
+  const tree2 = await args.map(maplike2, "Tree.combine", {
+    deep: true,
+    position: 2,
+  });
+
+  if (isUnpackable(combineFn)) {
+    combineFn = await combineFn.unpack();
+  }
+  const fn = args.fn(combineFn, "Tree.combine", {
+    position: 3,
+  });
+
+  const keys1 = await keys(tree1);
+  const keys2 = await keys(tree2);
+  const combinedKeys = new Set([...keys1, ...keys2]);
+
+  const result = {};
+
+  for (const key of combinedKeys) {
+    const value1 = await tree1.get(key);
+    const value2 = await tree2.get(key);
+
+    const combination =
+      isMap(value1) && isMap(value2)
+        ? await combine(value1, value2, fn)
+        : await fn(value1, value2);
+
+    if (combination !== undefined) {
+      result[key] = combination;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}

package/src/operations/map.js

@@ -250,7 +250,7 @@ function validateOptions(options) {
   // Set defaults for options not specified. We don't set a default value for
   // `deep` because a false value is a stronger signal than undefined.
   description ??= "key/value map";
-  keyNeedsSourceValue ??= true;
+  keyNeedsSourceValue ??= keyFn?.needsSourceValue ?? true;
 
   return {
     deep,

package/src/operations/shuffle.js

@@ -3,16 +3,22 @@ import * as args from "../utilities/args.js";
 import keys from "./keys.js";
 
 /**
- * Return a new tree with the original's keys shuffled
+ * Return a new tree with the original's keys shuffled.
+ *
+ * The `randoms` option allows you to provide a function that either returns a
+ * random number between 0 and 1 (like `Math.random`) or a random integer. This
+ * can be used to create deterministic shuffling.
  *
  * @typedef {import("../../index.ts").Maplike} Maplike
+ * @typedef {import("../../index.ts").Stringlike} Stringlike
  *
  * @param {Maplike} maplike
- * @param {boolean?} reshuffle
+ * @param {{ randoms?: (() => number) }?} options
  * @returns {Promise<AsyncMap>}
  */
-export default async function shuffle(maplike, reshuffle = false) {
+export default async function shuffle(maplike, options = {}) {
   const source = await args.map(maplike, "Tree.shuffle");
+  const randoms = options?.randoms ?? Math.random;
 
   let mapKeys;
 
@@ -24,9 +30,9 @@ export default async function shuffle(maplike, reshuffle = false) {
     },
 
     async *keys() {
-      if (!mapKeys || reshuffle) {
+      if (!mapKeys) {
         mapKeys = await keys(source);
-        shuffleArray(mapKeys);
+        shuffleArray(mapKeys, randoms);
       }
       yield* mapKeys;
     },
@@ -42,10 +48,17 @@ export default async function shuffle(maplike, reshuffle = false) {
  *
  * Performs a Fisher-Yates shuffle. From http://sedition.com/perl/javascript-fy.html
  */
-export function shuffleArray(array) {
+export function shuffleArray(array, randoms) {
   let i = array.length;
   while (--i >= 0) {
-    const j = Math.floor(Math.random() * (i + 1));
+    const random = randoms();
+
+    const j =
+      random < 1
+        ? // Like Math.random
+          Math.floor(random * (i + 1))
+        : // Random number
+          Math.floor(random) % (i + 1);
     const temp = array[i];
     array[i] = array[j];
     array[j] = temp;

package/test/operations/combine.test.js

@@ -0,0 +1,35 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import combine from "../../src/operations/combine.js";
+
+describe("combine", () => {
+  test("combines two trees", async () => {
+    const oldTree = {
+      a: {
+        b: "old",
+        c: "old",
+        d: "old",
+      },
+    };
+    const newTree = {
+      a: {
+        b: "new",
+        c: "old",
+      },
+      e: "new",
+    };
+    const combination = await combine(oldTree, newTree, compareFn);
+    assert.deepEqual(combination, {
+      "a/": {
+        b: ["old", "new"],
+        c: ["old", "old"],
+        d: ["old", undefined],
+      },
+      e: [undefined, "new"],
+    });
+  });
+});
+
+function compareFn(a, b) {
+  return [a, b];
+}

package/test/operations/shuffle.test.js

@@ -16,4 +16,29 @@ describe("shuffle", () => {
     const treeKeys = await keys(result);
     assert.deepEqual(treeKeys.sort(), Object.keys(obj).sort());
   });
+
+  test("accepts a randoms function for deterministic shuffling", async () => {
+    const obj = {
+      a: 1,
+      b: 2,
+      c: 3,
+      d: 4,
+      e: 5,
+    };
+
+    function count() {
+      let index = 0;
+      return function () {
+        return index++;
+      };
+    }
+
+    const result1 = await shuffle(obj, { randoms: count() });
+    const keys1 = await keys(result1);
+
+    const result2 = await shuffle(obj, { randoms: count() });
+    const keys2 = await keys(result2);
+
+    assert.deepEqual(keys1, keys2);
+  });
 });