@weborigami/async-tree 0.6.15 → 0.6.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.6.15",
+  "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/deepEntriesIterator.js

@@ -13,7 +13,7 @@ import isMaplike from "./isMaplike.js";
  * 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]
+ * @param {{ depth?: number, expand?: boolean, unpack?: boolean }} [options]
  * @returns {AsyncGenerator<[any, any], void, undefined>}
  */
 export default async function* deepEntriesIterator(maplike, options = {}) {
@@ -22,12 +22,13 @@ export default async function* deepEntriesIterator(maplike, options = {}) {
   });
 
   const depth = options.depth ?? Infinity;
-  const expand = options.expand ?? false;
+  const expand = options.expand ?? true;
+  const unpack = options.unpack ?? false;
 
   for await (let [key, value] of tree.entries()) {
     value = await value;
 
-    if (expand && isUnpackable(value)) {
+    if (unpack && isUnpackable(value)) {
       value = await value.unpack();
     }
 
@@ -37,7 +38,7 @@ export default async function* deepEntriesIterator(maplike, options = {}) {
       (isMap(value) ||
         (expand && typeof value !== "function" && isMaplike(value)));
     if (recurse) {
-      yield* deepEntriesIterator(value, { depth: depth - 1, expand });
+      yield* deepEntriesIterator(value, { depth: depth - 1, expand, unpack });
     } else {
       yield [key, value];
     }

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/src/operations/traverseOrThrow.js

@@ -86,7 +86,9 @@ export default async function traverseOrThrow(maplike, ...keys) {
       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.";
+          : isPacked(value)
+            ? "A path tried to unpack data but there's no unpack function."
+            : "A path tried to unpack data that's already unpacked.";
       throw new TraverseError(message, {
         head: maplike,
         lastValue,

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/deepEntriesIterator.test.js

@@ -67,7 +67,7 @@ describe("deepEntriesIterator", () => {
       packed,
     };
     const entries = [];
-    for await (const entry of deepEntriesIterator(tree, { expand: true })) {
+    for await (const entry of deepEntriesIterator(tree, { unpack: true })) {
       entries.push(entry);
     }
     assert.deepEqual(entries, [

package/test/operations/flat.test.js

@@ -6,7 +6,7 @@ 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);
+    const result = await flat([1, 2, [3], [[4, [5]]]]);
     assert.deepEqual(await plain(result), [1, 2, 3, [4, [5]]]);
   });
 

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);
+  });
 });