@weborigami/async-tree 0.0.53 → 0.0.55

package/main.js

@@ -23,8 +23,11 @@ export { default as sort } from "./src/operations/sort.js";
 export { default as take } from "./src/operations/take.js";
 export * as symbols from "./src/symbols.js";
 export { default as cachedKeyFunctions } from "./src/transforms/cachedKeyFunctions.js";
+export { default as deepReverse } from "./src/transforms/deepReverse.js";
+export { default as invokeFunctions } from "./src/transforms/invokeFunctions.js";
 export { default as keyFunctionsForExtensions } from "./src/transforms/keyFunctionsForExtensions.js";
 export { default as mapFn } from "./src/transforms/mapFn.js";
+export { default as reverse } from "./src/transforms/reverse.js";
 export { default as sortFn } from "./src/transforms/sortFn.js";
 export { default as takeFn } from "./src/transforms/takeFn.js";
 export * from "./src/utilities.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.53",
+  "version": "0.0.55",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
@@ -11,7 +11,7 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.53"
+    "@weborigami/types": "0.0.55"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/operations/deepMerge.js

@@ -16,10 +16,11 @@ export default function deepMerge(...sources) {
     async get(key) {
       const subtrees = [];
 
-      for (const tree of trees) {
-        const value = await tree.get(key);
+      // Check trees for the indicated key in reverse order.
+      for (let index = trees.length - 1; index >= 0; index--) {
+        const value = await trees[index].get(key);
         if (Tree.isAsyncTree(value)) {
-          subtrees.push(value);
+          subtrees.unshift(value);
         } else if (value !== undefined) {
           return value;
         }
@@ -29,8 +30,9 @@ export default function deepMerge(...sources) {
     },
 
     async isKeyForSubtree(key) {
-      for (const tree of trees) {
-        if (await Tree.isKeyForSubtree(tree, key)) {
+      // Check trees for the indicated key in reverse order.
+      for (let index = trees.length - 1; index >= 0; index--) {
+        if (await Tree.isKeyForSubtree(trees[index], key)) {
           return true;
         }
       }
@@ -39,6 +41,7 @@ export default function deepMerge(...sources) {
 
     async keys() {
       const keys = new Set();
+      // Collect keys in the order the trees were provided.
       for (const tree of trees) {
         for (const key of await tree.keys()) {
           keys.add(key);

package/src/operations/merge.js

@@ -20,8 +20,9 @@ export default function merge(...sources) {
     description: "merge",
 
     async get(key) {
-      for (const tree of trees) {
-        const value = await tree.get(key);
+      // Check trees for the indicated key in reverse order.
+      for (let index = trees.length - 1; index >= 0; index--) {
+        const value = await trees[index].get(key);
         if (value !== undefined) {
           return value;
         }
@@ -30,8 +31,9 @@ export default function merge(...sources) {
     },
 
     async isKeyForSubtree(key) {
-      for (const tree of trees) {
-        if (await Tree.isKeyForSubtree(tree, key)) {
+      // Check trees for the indicated key in reverse order.
+      for (let index = trees.length - 1; index >= 0; index--) {
+        if (await Tree.isKeyForSubtree(trees[index], key)) {
           return true;
         }
       }
@@ -40,6 +42,7 @@ export default function merge(...sources) {
 
     async keys() {
       const keys = new Set();
+      // Collect keys in the order the trees were provided.
       for (const tree of trees) {
         for (const key of await tree.keys()) {
           keys.add(key);

package/src/transforms/deepReverse.js

@@ -0,0 +1,29 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Reverse the order of keys at all levels of the tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @returns {AsyncTree}
+ */
+export default function deepReverse(treelike) {
+  const tree = Tree.from(treelike);
+  return {
+    async get(key) {
+      let value = await tree.get(key);
+      if (Tree.isAsyncTree(value)) {
+        value = deepReverse(value);
+      }
+      return value;
+    },
+
+    async keys() {
+      const keys = Array.from(await tree.keys());
+      keys.reverse();
+      return keys;
+    },
+  };
+}

package/src/transforms/invokeFunctions.js

@@ -0,0 +1,18 @@
+import { Tree } from "../internal.js";
+
+export default function invokeFunctions(treelike) {
+  const tree = Tree.from(treelike);
+  return {
+    async get(key) {
+      let value = await tree.get(key);
+      if (typeof value === "function") {
+        value = value();
+      }
+      return value;
+    },
+
+    async keys() {
+      return tree.keys();
+    },
+  };
+}

package/src/transforms/reverse.js

@@ -0,0 +1,25 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Reverse the order of the top-level keys in the tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").Treelike} Treelike
+ *
+ * @param {Treelike} treelike
+ * @returns {AsyncTree}
+ */
+export default function reverse(treelike) {
+  const tree = Tree.from(treelike);
+  return {
+    async get(key) {
+      return tree.get(key);
+    },
+
+    async keys() {
+      const keys = Array.from(await tree.keys());
+      keys.reverse();
+      return keys;
+    },
+  };
+}

package/src/utilities.d.ts

@@ -6,6 +6,8 @@ export const hiddenFileNames: string[];
 export function isPacked(object: any): object is Packed;
 export function isPlainObject(object: any): object is PlainObject;
 export function isUnpackable(object): object is { unpack: () => any };
-export function isStringLike(obj: any): obj is StringLike;
+export function isStringLike(object: any): object is StringLike;
 export function keysFromPath(path: string): string[];
 export const naturalOrder: (a: string, b: string) => number;
+export function pipeline(start: any, ...functions: Function[]): Promise<any>;
+export function toString(object: any): string;

package/src/utilities.js

@@ -1,3 +1,4 @@
+const textDecoder = new TextDecoder();
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
 /**
@@ -142,3 +143,42 @@ export function keysFromPath(pathname) {
 export const naturalOrder = new Intl.Collator(undefined, {
   numeric: true,
 }).compare;
+
+/**
+ * Apply a series of functions to a value, passing the result of each function
+ * to the next one.
+ *
+ * @param {any} start
+ * @param  {...Function} fns
+ */
+export async function pipeline(start, ...fns) {
+  return fns.reduce(async (acc, fn) => fn(await acc), start);
+}
+
+/**
+ * Return a string form of the object, handling cases not generally handled by
+ * the standard JavaScript `toString()` method:
+ *
+ * 1. If the object is an ArrayBuffer or TypedArray, decode the array as UTF-8.
+ * 2. If the object is otherwise a plain JavaScript object with the useless
+ *    default toString() method, return null instead of "[object Object]". In
+ *    practice, it's generally more useful to have this method fail than to
+ *    return a useless string.
+ *
+ * @param {any} object
+ * @returns {string|null}
+ */
+export function toString(object) {
+  if (object instanceof ArrayBuffer || object instanceof TypedArray) {
+    // Treat the buffer as UTF-8 text.
+    const decoded = textDecoder.decode(object);
+    // If the result appears to contain non-printable characters, it's probably not a string.
+    // https://stackoverflow.com/a/1677660/76472
+    const hasNonPrintableCharacters = /[\x00-\x08\x0E-\x1F]/.test(decoded);
+    return hasNonPrintableCharacters ? null : decoded;
+  } else if (isStringLike(object)) {
+    return String(object);
+  } else {
+    return null;
+  }
+}

package/test/operations/deepMerge.test.js

@@ -8,7 +8,7 @@ describe("mergeDeep", () => {
     const fixture = mergeDeep(
       new DeepObjectTree({
         a: {
-          b: 1,
+          b: 0, // Will be obscured by `b` below
           c: {
             d: 2,
           },
@@ -16,7 +16,7 @@ describe("mergeDeep", () => {
       }),
       new DeepObjectTree({
         a: {
-          b: 0, // Will be obscured by `b` above
+          b: 1,
           c: {
             e: 3,
           },

package/test/operations/merge.test.js

@@ -6,34 +6,34 @@ import merge from "../../src/operations/merge.js";
 describe("merge", () => {
   test("performs a shallow merge", async () => {
     const fixture = merge(
-      Tree.from({
+      {
         a: 1,
+        // Will be obscured by `b` that follows
         b: {
           c: 2,
         },
-      }),
-      Tree.from({
-        // Will be obscured by `b` above
+      },
+      {
         b: {
           d: 3,
         },
         e: {
           f: 4,
         },
-      })
+      }
     );
 
     assert.deepEqual(await Tree.plain(fixture), {
       a: 1,
       b: {
-        c: 2,
+        d: 3,
       },
       e: {
         f: 4,
       },
     });
 
-    const d = await Tree.traverse(fixture, "b", "d");
-    assert.equal(d, undefined);
+    const c = await Tree.traverse(fixture, "b", "c");
+    assert.equal(c, undefined);
   });
 });

package/test/transforms/deepReverse.test.js

@@ -0,0 +1,24 @@
+import { Tree } from "@weborigami/async-tree";
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import deepReverse from "../../src/transforms/deepReverse.js";
+
+describe("deepReverse", () => {
+  test("reverses keys at all levels of a tree", async () => {
+    const tree = {
+      a: 1,
+      b: {
+        c: 2,
+        d: 3,
+      },
+    };
+    const reversed = deepReverse.call(null, tree);
+    assert.deepEqual(await Tree.plain(reversed), {
+      b: {
+        d: 3,
+        c: 2,
+      },
+      a: 1,
+    });
+  });
+});

package/test/transforms/invokeFunctions.test.js

@@ -0,0 +1,17 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
+import invokeFunctions from "../../src/transforms/invokeFunctions.js";
+
+describe("invokeFunctions", () => {
+  test("invokes function values, leaves other values as is", async () => {
+    const fixture = invokeFunctions({
+      a: 1,
+      b: () => 2,
+    });
+    assert.deepEqual(await Tree.plain(fixture), {
+      a: 1,
+      b: 2,
+    });
+  });
+});

package/test/transforms/reverse.test.js

@@ -0,0 +1,23 @@
+import { Tree } from "@weborigami/async-tree";
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import reverse from "../../src/transforms/reverse.js";
+
+describe("reverse", () => {
+  test("reverses a tree's top-level keys", async () => {
+    const tree = {
+      a: "A",
+      b: "B",
+      c: "C",
+    };
+    const reversed = reverse.call(null, tree);
+    // @ts-ignore
+    assert.deepEqual(Array.from(await reversed.keys()), ["c", "b", "a"]);
+    // @ts-ignore
+    assert.deepEqual(await Tree.plain(reversed), {
+      c: "C",
+      b: "B",
+      a: "A",
+    });
+  });
+});

package/test/utilities.test.js

@@ -27,4 +27,29 @@ describe("utilities", () => {
     strings.sort(utilities.naturalOrder);
     assert.deepEqual(strings, ["file1", "file9", "file10"]);
   });
+
+  test("pipeline applies a series of functions to a value", async () => {
+    const addOne = (n) => n + 1;
+    const double = (n) => n * 2;
+    const square = (n) => n * n;
+    const result = await utilities.pipeline(1, addOne, double, square);
+    assert.equal(result, 16);
+  });
+
+  test("toString returns the value of an object's `toString` method", () => {
+    const object = {
+      toString: () => "text",
+    };
+    assert.equal(utilities.toString(object), "text");
+  });
+
+  test("toString returns null for an object with no useful `toString`", () => {
+    const object = {};
+    assert.equal(utilities.toString(object), null);
+  });
+
+  test("toString decodes an ArrayBuffer as UTF-8", () => {
+    const buffer = Buffer.from("text", "utf8");
+    assert.equal(utilities.toString(buffer), "text");
+  });
 });