@weborigami/async-tree 0.0.54 → 0.0.56

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.54",
+  "version": "0.0.56",
   "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.54"
+    "@weborigami/types": "0.0.56"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/FileTree.js

@@ -6,6 +6,7 @@ import {
   getRealmObjectPrototype,
   hiddenFileNames,
   isPacked,
+  isPlainObject,
   naturalOrder,
 } from "./utilities.js";
 
@@ -165,6 +166,9 @@ export default class FileTree {
       await fs.mkdir(this.dirname, { recursive: true });
       // Write out the value as the contents of a file.
       await fs.writeFile(destPath, value);
+    } else if (isPlainObject(value) && Object.keys(value).length === 0) {
+      // Special case: empty object means create an empty directory.
+      await fs.mkdir(destPath, { recursive: true });
     } else if (Tree.isTreelike(value)) {
       // Treat value as a tree and write it out as a subdirectory.
       const destTree = Reflect.construct(this.constructor, [destPath]);

package/src/operations/cache.js

@@ -1,8 +1,10 @@
 import { DeepObjectTree, Tree } from "../internal.js";
 
 /**
- * Caches values from a source tree in a second cache tree. If no second tree is
- * supplied, an in-memory cache is used.
+ * Caches values from a source tree in a second cache tree. Cache source tree
+ * keys in memory.
+ *
+ * If no second tree is supplied, an in-memory value cache is used.
  *
  * An optional third filter tree can be supplied. If a filter tree is supplied,
  * only values for keys that match the filter will be cached.
@@ -22,6 +24,7 @@ export default function treeCache(sourceTreelike, cacheTree, filterTreelike) {
 
   /** @type {AsyncMutableTree} */
   const cache = cacheTree ?? new DeepObjectTree({});
+  let keys;
   return {
     description: "cache",
 
@@ -65,14 +68,7 @@ export default function treeCache(sourceTreelike, cacheTree, filterTreelike) {
     },
 
     async keys() {
-      const keys = new Set(await source.keys());
-
-      // We also add the cache's keys in case the keys provided by the source
-      // tree have changed since the cache was updated.
-      for (const key of await cache.keys()) {
-        keys.add(key);
-      }
-
+      keys ??= source.keys();
       return keys;
     },
   };

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

@@ -9,7 +9,7 @@ import { Tree } from "../src/internal.js";
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const tempDirectory = path.join(dirname, "fixtures/temp");
 
-describe("FileTree", async () => {
+describe.only("FileTree", async () => {
   test("can get the keys of the tree", async () => {
     const fixture = createFixture("fixtures/markdown");
     assert.deepEqual(Array.from(await fixture.keys()), [
@@ -61,6 +61,23 @@ describe("FileTree", async () => {
     await removeTempDirectory();
   });
 
+  test.only("can create empty subfolder via set()", async () => {
+    await createTempDirectory();
+
+    // Write out new, empty folder called "empty".
+    const tempFiles = new FileTree(tempDirectory);
+    await tempFiles.set("empty", {});
+
+    // Verify folder exists and has no contents.
+    const folderPath = path.join(tempDirectory, "empty");
+    const stats = await fs.stat(folderPath);
+    assert(stats.isDirectory());
+    const files = await fs.readdir(folderPath);
+    assert.deepEqual(files, []);
+
+    await removeTempDirectory();
+  });
+
   test("can write out subfolder via set()", async () => {
     await createTempDirectory();
 

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