@weborigami/async-tree 0.0.58 → 0.0.59

package/main.js

@@ -11,10 +11,12 @@ export { default as SiteTree } from "./src/SiteTree.js";
 export { DeepObjectTree, ObjectTree, Tree } from "./src/internal.js";
 export * as keysJson from "./src/keysJson.js";
 export { default as cache } from "./src/operations/cache.js";
+export { default as concat } from "./src/operations/concat.js";
 export { default as deepMerge } from "./src/operations/deepMerge.js";
 export { default as deepTake } from "./src/operations/deepTake.js";
 export { default as deepTakeFn } from "./src/operations/deepTakeFn.js";
 export { default as deepValues } from "./src/operations/deepValues.js";
+export { default as deepValuesIterator } from "./src/operations/deepValuesIterator.js";
 export { default as group } from "./src/operations/group.js";
 export { default as groupFn } from "./src/operations/groupFn.js";
 export { default as map } from "./src/operations/map.js";

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.58",
+  "version": "0.0.59",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "20.12.8",
-    "typescript": "5.4.5"
+    "@types/node": "20.14.9",
+    "typescript": "5.5.3"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.58"
+    "@weborigami/types": "0.0.59"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/FileTree.js

@@ -13,6 +13,12 @@ import {
 /**
  * A file system tree via the Node file system API.
  *
+ * File values are returned as Uint8Array instances. The underlying Node fs API
+ * returns file contents as instances of the node-specific Buffer class, but
+ * that class has some incompatible method implementations; see
+ * https://nodejs.org/api/buffer.html#buffers-and-typedarrays. For greater
+ * compatibility, files are returned as standard Uint8Array instances instead.
+ *
  * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
  * @implements {AsyncMutableTree}
  */
@@ -65,8 +71,9 @@ export default class FileTree {
       subtree.parent = this;
       return subtree;
     } else {
-      // Return file contents
-      return fs.readFile(filePath);
+      // Return file contents as a standard Uint8Array.
+      const buffer = await fs.readFile(filePath);
+      return Uint8Array.from(buffer);
     }
   }
 

package/src/operations/concat.js

@@ -0,0 +1,20 @@
+import { toString } from "../utilities.js";
+import deepValuesIterator from "./deepValuesIterator.js";
+
+/**
+ * Concatenate the deep text values in a tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {import("@weborigami/async-tree").Treelike} treelike
+ */
+export default async function concatTreeValues(treelike) {
+  const strings = [];
+  for await (const value of deepValuesIterator(treelike, { expand: true })) {
+    if (value) {
+      strings.push(toString(value));
+    }
+  }
+  return strings.join("");
+}

package/src/operations/deepValues.js

@@ -1,10 +1,19 @@
-import { Tree } from "../internal.js";
+import deepValuesIterator from "./deepValuesIterator.js";
 
 /**
  * Return the in-order exterior values of a tree as a flat array.
  *
  * @param {import("../../index.ts").Treelike} treelike
+ * @param {{ expand?: boolean }} [options]
  */
-export default async function deepValues(treelike) {
-  return Tree.mapReduce(treelike, null, async (values) => values.flat());
+export default async function deepValues(
+  treelike,
+  options = { expand: false }
+) {
+  const iterator = deepValuesIterator(treelike, options);
+  const values = [];
+  for await (const value of iterator) {
+    values.push(value);
+  }
+  return values;
 }

package/src/operations/deepValuesIterator.js

@@ -0,0 +1,31 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Return an iterator that yields all values in a tree, including nested trees.
+ *
+ * If the `expand` option is true, treelike values (but not functions) will be
+ * expanded into nested trees and their values will be yielded.
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ * @param {{ expand?: boolean }} [options]
+ * @returns {AsyncGenerator<any, void, undefined>}
+ */
+export default async function* deepValuesIterator(
+  treelike,
+  options = { expand: false }
+) {
+  const tree = Tree.from(treelike);
+  for (const key of await tree.keys()) {
+    let value = await tree.get(key);
+
+    // Recurse into child trees, but don't expand functions.
+    const recurse =
+      Tree.isAsyncTree(value) ||
+      (options.expand && typeof value !== "function" && Tree.isTreelike(value));
+    if (recurse) {
+      yield* deepValuesIterator(value, options);
+    } else {
+      yield value;
+    }
+  }
+}

package/src/utilities.d.ts

@@ -10,4 +10,5 @@ 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;
+export function toPlainValue(object: any): Promise<any>;
+export function toString(object: any): string;

package/src/utilities.js

@@ -1,3 +1,5 @@
+import { Tree } from "./internal.js";
+
 const textDecoder = new TextDecoder();
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
@@ -56,7 +58,6 @@ export function isPacked(object) {
   return (
     typeof object === "string" ||
     object instanceof ArrayBuffer ||
-    object instanceof Buffer ||
     object instanceof ReadableStream ||
     object instanceof String ||
     object instanceof TypedArray
@@ -89,6 +90,20 @@ export function isPlainObject(object) {
   return Object.getPrototypeOf(object) === getRealmObjectPrototype(object);
 }
 
+/**
+ * Return true if the value is a primitive JavaScript value.
+ *
+ * @param {any} value
+ */
+export function isPrimitive(value) {
+  // Check for null first, since typeof null === "object".
+  if (value === null) {
+    return true;
+  }
+  const type = typeof value;
+  return type !== "object" && type !== "function";
+}
+
 /**
  * Return true if the object is a string or object with a non-trival `toString`
  * method.
@@ -155,6 +170,59 @@ export async function pipeline(start, ...fns) {
   return fns.reduce(async (acc, fn) => fn(await acc), start);
 }
 
+/**
+ * Convert the given input to the plainest possible JavaScript value. This
+ * helper is intended for functions that want to accept an argument from the ori
+ * CLI, which could a string, a stream of data, or some other kind of JavaScript
+ * object.
+ *
+ * If the input is a function, it will be invoked and its result will be
+ * processed.
+ *
+ * If the input is a promise, it will be resolved and its result will be
+ * processed.
+ *
+ * If the input is treelike, it will be converted to a plain JavaScript object,
+ * recursively traversing the tree and converting all values to plain types.
+ *
+ * If the input is stringlike, its text will be returned.
+ *
+ * If the input is a ArrayBuffer or typed array, it will be interpreted as UTF-8
+ * text.
+ *
+ * If the input has a custom class instance, its public properties will be
+ * returned as a plain object.
+ *
+ * @param {any} input
+ * @returns {Promise<any>}
+ */
+export async function toPlainValue(input) {
+  if (input instanceof Function) {
+    // Invoke function
+    input = input();
+  }
+  if (input instanceof Promise) {
+    // Resolve promise
+    input = await input;
+  }
+
+  if (isPrimitive(input) || input instanceof Date) {
+    return input;
+  } else if (Tree.isTreelike(input)) {
+    const mapped = await Tree.map(input, (value) => toPlainValue(value));
+    return Tree.plain(mapped);
+  } else if (isStringLike(input)) {
+    return toString(input);
+  } else {
+    // Some other kind of class instance; return its public properties.
+    const plain = {};
+    for (const [key, value] of Object.entries(input)) {
+      plain[key] = await toPlainValue(value);
+    }
+    return plain;
+  }
+}
+
 /**
  * Return a string form of the object, handling cases not generally handled by
  * the standard JavaScript `toString()` method:
@@ -164,6 +232,10 @@ export async function pipeline(start, ...fns) {
  *    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.
+ * 3. If the object is a defined primitive value, return the result of
+ *    String(object).
+ *
+ * Otherwise return null.
  *
  * @param {any} object
  * @returns {string|null}
@@ -176,7 +248,7 @@ export function toString(object) {
     // https://stackoverflow.com/a/1677660/76472
     const hasNonPrintableCharacters = /[\x00-\x08\x0E-\x1F]/.test(decoded);
     return hasNonPrintableCharacters ? null : decoded;
-  } else if (isStringLike(object)) {
+  } else if (isStringLike(object) || (object !== null && isPrimitive(object))) {
     return String(object);
   } else {
     return null;

package/test/FileTree.test.js

@@ -9,6 +9,8 @@ import { Tree } from "../src/internal.js";
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const tempDirectory = path.join(dirname, "fixtures/temp");
 
+const textDecoder = new TextDecoder();
+
 describe.only("FileTree", async () => {
   test("can get the keys of the tree", async () => {
     const fixture = createFixture("fixtures/markdown");
@@ -21,8 +23,9 @@ describe.only("FileTree", async () => {
 
   test("can get the value for a key", async () => {
     const fixture = createFixture("fixtures/markdown");
-    const alice = await fixture.get("Alice.md");
-    assert.equal(alice, "Hello, **Alice**.");
+    const buffer = await fixture.get("Alice.md");
+    const text = textDecoder.decode(buffer);
+    assert.equal(text, "Hello, **Alice**.");
   });
 
   test("getting an unsupported key returns undefined", async () => {
@@ -95,7 +98,9 @@ describe.only("FileTree", async () => {
 
     // Read them back in.
     const actualFiles = await tempFiles.get("folder");
-    const strings = Tree.map(actualFiles, (buffer) => String(buffer));
+    const strings = Tree.map(actualFiles, (buffer) =>
+      textDecoder.decode(buffer)
+    );
     const plain = await Tree.plain(strings);
     assert.deepEqual(plain, obj);
 

package/test/SiteTree.test.js

@@ -3,6 +3,9 @@ import { beforeEach, describe, mock, test } from "node:test";
 import SiteTree from "../src/SiteTree.js";
 import { Tree } from "../src/internal.js";
 
+const textDecoder = new TextDecoder();
+const textEncoder = new TextEncoder();
+
 const mockHost = "https://mock";
 
 const mockResponses = {
@@ -53,8 +56,9 @@ describe("SiteTree", () => {
   test("can get the value for a key", async () => {
     const fixture = new SiteTree(mockHost);
     const about = fixture.resolve("about");
-    const alice = await about.get("Alice.html");
-    assert.equal(alice, "Hello, Alice!");
+    const arrayBuffer = await about.get("Alice.html");
+    const text = textDecoder.decode(arrayBuffer);
+    assert.equal(text, "Hello, Alice!");
   });
 
   test("getting an unsupported key returns undefined", async () => {
@@ -78,7 +82,7 @@ describe("SiteTree", () => {
   test("can convert a SiteGraph to a plain object", async () => {
     const fixture = new SiteTree(mockHost);
     // Convert buffers to strings.
-    const strings = Tree.map(fixture, (value) => value.toString());
+    const strings = Tree.map(fixture, (value) => textDecoder.decode(value));
     assert.deepEqual(await Tree.plain(strings), {
       about: {
         "Alice.html": "Hello, Alice!",
@@ -98,8 +102,7 @@ async function mockFetch(href) {
   if (mockedResponse) {
     return Object.assign(
       {
-        // Returns a Buffer, not an ArrayBuffer
-        arrayBuffer: () => Buffer.from(mockedResponse.data),
+        arrayBuffer: () => textEncoder.encode(mockedResponse.data).buffer,
         ok: true,
         status: 200,
         text: () => mockedResponse.data,

package/test/operations/concat.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import FunctionTree from "../../src/FunctionTree.js";
+import { Tree } from "../../src/internal.js";
+import concat from "../../src/operations/concat.js";
+
+describe("concat", () => {
+  test("concatenates deep tree values", async () => {
+    const tree = Tree.from({
+      a: "A",
+      b: "B",
+      c: "C",
+      more: {
+        d: "D",
+        e: "E",
+      },
+    });
+    const result = await concat.call(null, tree);
+    assert.equal(result, "ABCDE");
+  });
+
+  test("concatenates deep tree-like values", async () => {
+    const letters = ["a", "b", "c"];
+    const specimens = new FunctionTree(
+      (letter) => ({
+        lowercase: letter,
+        uppercase: letter.toUpperCase(),
+      }),
+      letters
+    );
+    const result = await concat.call(null, specimens);
+    assert.equal(result, "aAbBcC");
+  });
+});

package/test/operations/deepValuesIterator.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { ObjectTree } from "../../src/internal.js";
+import deepValuesIterator from "../../src/operations/deepValuesIterator.js";
+
+describe("deepValuesIterator", () => {
+  test("returns an iterator of a tree's deep values", async () => {
+    const tree = new ObjectTree({
+      a: 1,
+      b: 2,
+      more: {
+        c: 3,
+        d: 4,
+      },
+    });
+    const values = [];
+    // The tree will be shallow, but we'll ask to expand the values.
+    for await (const value of deepValuesIterator(tree, { expand: true })) {
+      values.push(value);
+    }
+    assert.deepEqual(values, [1, 2, 3, 4]);
+  });
+});

package/test/transforms/deepReverse.test.js

@@ -1,6 +1,6 @@
-import { Tree } from "@weborigami/async-tree";
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
 import deepReverse from "../../src/transforms/deepReverse.js";
 
 describe("deepReverse", () => {

package/test/transforms/reverse.test.js

@@ -1,6 +1,6 @@
-import { Tree } from "@weborigami/async-tree";
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
 import reverse from "../../src/transforms/reverse.js";
 
 describe("reverse", () => {

package/test/utilities.test.js

@@ -36,6 +36,26 @@ describe("utilities", () => {
     assert.equal(result, 16);
   });
 
+  test("toPlainValue returns the plainest representation of an object", async () => {
+    class User {
+      constructor(name) {
+        this.name = name;
+      }
+    }
+
+    assert.equal(await utilities.toPlainValue(1), 1);
+    assert.equal(await utilities.toPlainValue("string"), "string");
+    assert.deepEqual(await utilities.toPlainValue({ a: 1 }), { a: 1 });
+    assert.equal(
+      await utilities.toPlainValue(new TextEncoder().encode("bytes")),
+      "bytes"
+    );
+    assert.equal(await utilities.toPlainValue(async () => "result"), "result");
+    assert.deepEqual(await utilities.toPlainValue(new User("Alice")), {
+      name: "Alice",
+    });
+  });
+
   test("toString returns the value of an object's `toString` method", () => {
     const object = {
       toString: () => "text",
@@ -49,7 +69,7 @@ describe("utilities", () => {
   });
 
   test("toString decodes an ArrayBuffer as UTF-8", () => {
-    const buffer = Buffer.from("text", "utf8");
-    assert.equal(utilities.toString(buffer), "text");
+    const arrayBuffer = new TextEncoder().encode("text").buffer;
+    assert.equal(utilities.toString(arrayBuffer), "text");
   });
 });