@weborigami/async-tree 0.0.45 → 0.0.47

package/src/transforms/{keyMapsForExtensions.js → keyFunctionsForExtensions.js}

@@ -2,14 +2,14 @@
  * Given a source resultExtension and a result resultExtension, return a pair of key
  * functions that map between them.
  *
- * The resulting `inverseKeyMap` and `keyMap` functions are compatible with those
+ * The resulting `inverseKey` and `key` functions are compatible with those
  * expected by map and other transforms.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @param {{ resultExtension?: string, sourceExtension: string }}
  * options
  */
-export default function keyMapsForExtensions({
+export default function keyFunctionsForExtensions({
   resultExtension,
   sourceExtension,
 }) {
@@ -18,12 +18,12 @@ export default function keyMapsForExtensions({
   }
 
   return {
-    async inverseKeyMap(resultKey, tree) {
+    async inverseKey(resultKey, tree) {
       const basename = matchExtension(resultKey, resultExtension);
       return basename ? `${basename}${dotPrefix(sourceExtension)}` : undefined;
     },
 
-    async keyMap(sourceKey, tree) {
+    async key(sourceKey, tree) {
       const basename = matchExtension(sourceKey, sourceExtension);
       return basename ? `${basename}${dotPrefix(resultExtension)}` : undefined;
     },

package/src/transforms/map.js

@@ -1,4 +1,4 @@
-import * as Tree from "../Tree.js";
+import { Tree } from "../internal.js";
 
 /**
  * Return a transform function that maps the keys and/or values of a tree.
@@ -6,63 +6,64 @@ import * as Tree from "../Tree.js";
  * @typedef {import("../../index.ts").KeyFn} KeyFn
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
- * @param {ValueKeyFn|{ deep?: boolean, description?: string, needsSourceValue?: boolean, inverseKeyMap?: KeyFn, keyMap?: KeyFn, valueMap?: ValueKeyFn }} options
+ * @param {ValueKeyFn|{ deep?: boolean, description?: string, needsSourceValue?: boolean, inverseKey?: KeyFn, key?: KeyFn, value?: ValueKeyFn }} options
  */
-export default function createMapTransform(options) {
+export default function createMapTransform(options = {}) {
   let deep;
   let description;
-  let inverseKeyMap;
-  let keyMap;
+  let inverseKeyFn;
+  let keyFn;
   let needsSourceValue;
-  let valueMap;
+  let valueFn;
   if (typeof options === "function") {
-    // Take the single function argument as the valueMap
-    valueMap = options;
+    // Take the single function argument as the valueFn
+    valueFn = options;
   } else {
     deep = options.deep;
     description = options.description;
-    inverseKeyMap = options.inverseKeyMap;
-    keyMap = options.keyMap;
+    inverseKeyFn = options.inverseKey;
+    keyFn = options.key;
     needsSourceValue = options.needsSourceValue;
-    valueMap = options.valueMap;
+    valueFn = options.value;
   }
 
   deep ??= false;
   description ??= "key/value map";
   // @ts-ignore
-  inverseKeyMap ??= valueMap?.inverseKeyMap;
+  inverseKeyFn ??= valueFn?.inverseKey;
   // @ts-ignore
-  keyMap ??= valueMap?.keyMap;
+  keyFn ??= valueFn?.key;
   needsSourceValue ??= true;
 
-  if ((keyMap && !inverseKeyMap) || (!keyMap && inverseKeyMap)) {
+  if ((keyFn && !inverseKeyFn) || (!keyFn && inverseKeyFn)) {
     throw new TypeError(
-      `map: You must specify both keyMap and inverseKeyMap, or neither.`
+      `map: You must specify both key and inverseKey functions, or neither.`
     );
   }
 
   /**
    * @type {import("../../index.ts").TreeTransform}
    */
-  return function map(tree) {
+  return function map(treelike) {
+    const tree = Tree.from(treelike);
     // The transformed tree is actually an extension of the original tree's
     // prototype chain. This allows the transformed tree to inherit any
-    // properties/methods that do not need to be specified. For example, the
-    // `parent` of the transformed tree is the original tree's parent.
+    // properties/methods. For example, the `parent` of the transformed tree is
+    // the original tree's parent.
     const transformed = Object.create(tree);
 
     transformed.description = description;
 
-    if (keyMap || valueMap) {
+    if (keyFn || valueFn) {
       transformed.get = async (resultKey) => {
         // Step 1: Map the result key to the source key.
         const isSubtree = deep && (await Tree.isKeyForSubtree(tree, resultKey));
         const sourceKey =
-          !isSubtree && inverseKeyMap
-            ? await inverseKeyMap(resultKey, tree)
+          !isSubtree && inverseKeyFn
+            ? await inverseKeyFn(resultKey, tree)
             : resultKey;
 
-        if (!sourceKey) {
+        if (sourceKey == null) {
           // No source key means no value.
           return undefined;
         }
@@ -85,9 +86,9 @@ export default function createMapTransform(options) {
         } else if (deep && Tree.isAsyncTree(sourceValue)) {
           // Map a subtree.
           resultValue = map(sourceValue);
-        } else if (valueMap) {
+        } else if (valueFn) {
           // Map a single value.
-          resultValue = await valueMap(sourceValue, sourceKey, tree);
+          resultValue = await valueFn(sourceValue, sourceKey, tree);
         } else {
           // Return source value as is.
           resultValue = sourceValue;
@@ -97,9 +98,9 @@ export default function createMapTransform(options) {
       };
     }
 
-    if (keyMap) {
+    if (keyFn) {
       transformed.keys = async () => {
-        // Apply the keyMap to source keys for leaf values (not subtrees).
+        // Apply the keyFn to source keys for leaf values (not subtrees).
         const sourceKeys = Array.from(await tree.keys());
         const mapped = await Promise.all(
           sourceKeys.map(async (sourceKey) => {
@@ -107,12 +108,12 @@ export default function createMapTransform(options) {
             if (deep && (await Tree.isKeyForSubtree(tree, sourceKey))) {
               resultKey = sourceKey;
             } else {
-              resultKey = await keyMap(sourceKey, tree);
+              resultKey = await keyFn(sourceKey, tree);
             }
             return resultKey;
           })
         );
-        // Filter out any cases where the keyMap returned undefined.
+        // Filter out any cases where the keyFn returned undefined.
         const resultKeys = mapped.filter((key) => key !== undefined);
         return resultKeys;
       };

package/src/transforms/regExpKeys.js

@@ -1,4 +1,4 @@
-import * as Tree from "../Tree.js";
+import { Tree } from "../internal.js";
 
 /**
  * A tree whose keys are strings interpreted as regular expressions.
@@ -10,7 +10,8 @@ import * as Tree from "../Tree.js";
  *
  * @type {import("../../index.ts").TreeTransform}
  */
-export default async function regExpKeys(tree) {
+export default async function regExpKeys(treelike) {
+  const tree = Tree.from(treelike);
   const map = new Map();
 
   // We build the output tree first so that we can refer to it when setting

package/src/transforms/sort.js

@@ -1,3 +1,5 @@
+import { Tree } from "../internal.js";
+
 /**
  * Return a transform function that sorts a tree's keys.
  *
@@ -10,7 +12,8 @@ export default function createSortTransform(compareFn) {
   /**
    * @type {import("../../index.ts").TreeTransform}
    */
-  return function sortTransform(tree) {
+  return function sortTransform(treelike) {
+    const tree = Tree.from(treelike);
     const transform = Object.create(tree);
     transform.keys = async () => {
       const keys = Array.from(await tree.keys());

package/src/transforms/sortBy.js

@@ -1,3 +1,5 @@
+import { Tree } from "../internal.js";
+
 /**
  * Return a transform function that sorts a tree's keys.
  *
@@ -11,7 +13,8 @@ export default function createSortByTransform(sortKeyFn) {
   /**
    * @type {import("../../index.ts").TreeTransform}
    */
-  return function sortByTransform(tree) {
+  return function sortByTransform(treelike) {
+    const tree = Tree.from(treelike);
     const transform = Object.create(tree);
     transform.keys = async () => {
       const keysAndSortKeys = [];

package/src/utilities.d.ts

@@ -1,9 +1,11 @@
-import { PlainObject, StringLike } from "../index.ts";
+import { Packed, PlainObject, StringLike } from "../index.ts";
 
 export function castArrayLike(object: any): any;
 export function getRealmObjectPrototype(object: any): any;
 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 keysFromPath(path: string): string[];
 export const naturalSortCompareFn: (a: string, b: string) => number;

package/src/utilities.js

@@ -1,3 +1,5 @@
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
 /**
  * If the given plain object has only sequential integer keys, return it as an
  * array. Otherwise return it as is.
@@ -19,9 +21,6 @@ export function castArrayLike(object) {
   return hasKeys ? Object.values(object) : object;
 }
 
-// Names of OS-generated files that should not be enumerated
-export const hiddenFileNames = [".DS_Store"];
-
 /**
  * Return the Object prototype at the root of the object's prototype chain.
  *
@@ -38,6 +37,27 @@ export function getRealmObjectPrototype(object) {
   return proto;
 }
 
+// Names of OS-generated files that should not be enumerated
+export const hiddenFileNames = [".DS_Store"];
+
+/**
+ * Return true if the object is in a packed form (or can be readily packed into
+ * a form) that can be given to fs.writeFile or response.write().
+ *
+ * @param {any} object
+ * @returns {object is import("../index.ts").Packed}
+ */
+export function isPacked(object) {
+  return (
+    typeof object === "string" ||
+    object instanceof ArrayBuffer ||
+    object instanceof Buffer ||
+    object instanceof ReadableStream ||
+    object instanceof String ||
+    object instanceof TypedArray
+  );
+}
+
 /**
  * Return true if the object is a plain JavaScript object created by `{}`,
  * `new Object()`, or `Object.create(null)`.
@@ -46,6 +66,7 @@ export function getRealmObjectPrototype(object) {
  * `Module`) as plain objects.
  *
  * @param {any} object
+ * @returns {object is import("../index.ts").PlainObject}
  */
 export function isPlainObject(object) {
   // From https://stackoverflow.com/q/51722354/76472
@@ -67,15 +88,15 @@ export function isPlainObject(object) {
  * Return true if the object is a string or object with a non-trival `toString`
  * method.
  *
- * @param {any} obj
- * @returns {obj is import("@weborigami/async-tree").StringLike}
+ * @param {any} object
+ * @returns {obj is import("../index.ts").StringLike}
  */
-export function isStringLike(obj) {
-  if (typeof obj === "string") {
+export function isStringLike(object) {
+  if (typeof object === "string") {
     return true;
-  } else if (obj?.toString === undefined) {
+  } else if (object?.toString === undefined) {
     return false;
-  } else if (obj.toString === getRealmObjectPrototype(obj).toString) {
+  } else if (object.toString === getRealmObjectPrototype(object).toString) {
     // The stupid Object.prototype.toString implementation always returns
     // "[object Object]", so if that's the only toString method the object has,
     // we return false.
@@ -85,6 +106,13 @@ export function isStringLike(obj) {
   }
 }
 
+export function isUnpackable(object) {
+  return (
+    isPacked(object) &&
+    typeof (/** @type {any} */ (object).unpack) === "function"
+  );
+}
+
 /**
  * Given a path like "/foo/bar/baz", return an array of keys like ["foo", "bar",
  * "baz"].

package/test/BrowserFileTree.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import BrowserFileTree from "../src/BrowserFileTree.js";
-import * as Tree from "../src/Tree.js";
+import { Tree } from "../src/internal.js";
 
 // Skip these tests if we're not in a browser.
 const isBrowser = typeof window !== "undefined";

package/test/DeepObjectTree.test.js

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import DeepObjectTree from "../src/DeepObjectTree.js";
-import * as Tree from "../src/Tree.js";
+import { DeepObjectTree, Tree } from "../src/internal.js";
 
 describe("DeepObjectTree", () => {
   test("returns an ObjectTree for value that's a plain sub-object or sub-array", async () => {

package/test/DeferredTree.test.js

@@ -1,8 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import DeferredTree from "../src/DeferredTree.js";
-import ObjectTree from "../src/ObjectTree.js";
-import * as Tree from "../src/Tree.js";
+import { ObjectTree, Tree } from "../src/internal.js";
 
 describe("DeferredTree", () => {
   test("lazy-loads a treelike object", async () => {

package/test/FileTree.test.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import FileTree from "../src/FileTree.js";
-import * as Tree from "../src/Tree.js";
+import { Tree } from "../src/internal.js";
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 const tempDirectory = path.join(dirname, "fixtures/temp");

package/test/FunctionTree.test.js

@@ -18,12 +18,6 @@ describe("FunctionTree", async () => {
     assert.equal(alice, "Hello, **Alice**.");
   });
 
-  test("unpacking the tree returns the function itself", async () => {
-    const fn = () => true;
-    const fixture = new FunctionTree(fn);
-    assert.equal(await fixture.unpack(), fn);
-  });
-
   test("getting a value from function with multiple arguments curries the function", async () => {
     const fixture = new FunctionTree((a, b, c) => a + b + c);
     const fnA = await fixture.get(1);

package/test/ObjectTree.test.js

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import ObjectTree from "../src/ObjectTree.js";
-import * as Tree from "../src/Tree.js";
+import { ObjectTree, Tree } from "../src/internal.js";
 
 describe("ObjectTree", () => {
   test("can get the keys of the tree", async () => {

package/test/SetTree.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import ObjectTree from "../src/ObjectTree.js";
 import SetTree from "../src/SetTree.js";
+import { ObjectTree } from "../src/internal.js";
 
 describe("SetTree", () => {
   test("can get the keys of the tree", async () => {

package/test/SiteTree.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { beforeEach, describe, mock, test } from "node:test";
 import SiteTree from "../src/SiteTree.js";
-import * as Tree from "../src/Tree.js";
+import { Tree } from "../src/internal.js";
 
 const mockHost = "https://mock";
 

package/test/Tree.test.js

@@ -1,9 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import { DeepObjectTree } from "../main.js";
 import MapTree from "../src/MapTree.js";
-import ObjectTree from "../src/ObjectTree.js";
-import * as Tree from "../src/Tree.js";
+import { DeepObjectTree, ObjectTree, Tree } from "../src/internal.js";
 
 describe("Tree", () => {
   test("assign applies one tree to another", async () => {
@@ -89,13 +87,10 @@ describe("Tree", () => {
   });
 
   test("from() uses an object's unpack() method if defined", async () => {
-    const obj = {
-      unpack() {
-        return {
-          a: "Hello, a.",
-        };
-      },
-    };
+    const obj = new String();
+    /** @type {any} */ (obj).unpack = () => ({
+      a: "Hello, a.",
+    });
     const tree = Tree.from(obj);
     assert.deepEqual(await Tree.plain(tree), {
       a: "Hello, a.",
@@ -103,13 +98,10 @@ describe("Tree", () => {
   });
 
   test("from() creates a deferred tree if unpack() returns a promise", async () => {
-    const obj = {
-      async unpack() {
-        return {
-          a: "Hello, a.",
-        };
-      },
-    };
+    const obj = new String();
+    /** @type {any} */ (obj).unpack = async () => ({
+      a: "Hello, a.",
+    });
     const tree = Tree.from(obj);
     assert.deepEqual(await Tree.plain(tree), {
       a: "Hello, a.",
@@ -299,12 +291,10 @@ describe("Tree", () => {
   });
 
   test("traversing a final empty string can unpack the last value", async () => {
+    const unpackable = new String();
+    /** @type {any} */ (unpackable).unpack = () => "Content";
     const tree = {
-      unpackable: {
-        unpack() {
-          return "Content";
-        },
-      },
+      unpackable,
     };
     const result = await Tree.traverse(tree, "unpackable", "");
     assert.equal(result, "Content");

package/test/operations/cache.test.js

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import ObjectTree from "../../src/ObjectTree.js";
-import * as Tree from "../../src/Tree.js";
+import { ObjectTree, Tree } from "../../src/internal.js";
 import cache from "../../src/operations/cache.js";
 
 describe("cache", () => {

package/test/operations/merge.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import * as Tree from "../../src/Tree.js";
+import { Tree } from "../../src/internal.js";
 import merge from "../../src/operations/merge.js";
 
 describe("merge", () => {

package/test/operations/mergeDeep.test.js

@@ -1,7 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import DeepObjectTree from "../../src/DeepObjectTree.js";
-import * as Tree from "../../src/Tree.js";
+import { DeepObjectTree, Tree } from "../../src/internal.js";
 import mergeDeep from "../../src/operations/mergeDeep.js";
 
 describe("mergeDeep", () => {

package/test/transforms/cachedKeyMaps.test.js

@@ -1,9 +1,9 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import ObjectTree from "../../src/ObjectTree.js";
-import cachedKeyMaps from "../../src/transforms/cachedKeyMaps.js";
+import { ObjectTree } from "../../src/internal.js";
+import cachedKeyFunctions from "../../src/transforms/cachedKeyFunctions.js";
 
-describe("cachedKeyMaps", () => {
+describe("cachedKeyFunctions", () => {
   test("maps keys with caching", async () => {
     const tree = new ObjectTree({
       a: "letter a",
@@ -16,26 +16,26 @@ describe("cachedKeyMaps", () => {
       return `_${sourceKey}`;
     };
 
-    const { inverseKeyMap, keyMap } = cachedKeyMaps(underscoreKeys);
+    const { inverseKey, key } = cachedKeyFunctions(underscoreKeys);
 
-    assert.equal(await inverseKeyMap("_a", tree), "a"); // Cache miss
+    assert.equal(await inverseKey("_a", tree), "a"); // Cache miss
     assert.equal(callCount, 1);
-    assert.equal(await inverseKeyMap("_a", tree), "a");
+    assert.equal(await inverseKey("_a", tree), "a");
     assert.equal(callCount, 1);
-    assert.equal(await inverseKeyMap("_b", tree), "b"); // Cache miss
+    assert.equal(await inverseKey("_b", tree), "b"); // Cache miss
     assert.equal(callCount, 2);
 
-    assert.equal(await keyMap("a", tree), "_a");
-    assert.equal(await keyMap("a", tree), "_a");
-    assert.equal(await keyMap("b", tree), "_b");
+    assert.equal(await key("a", tree), "_a");
+    assert.equal(await key("a", tree), "_a");
+    assert.equal(await key("b", tree), "_b");
     assert.equal(callCount, 2);
 
     // `c` isn't in tree, so we should get undefined.
-    assert.equal(await inverseKeyMap("_c", tree), undefined);
+    assert.equal(await inverseKey("_c", tree), undefined);
     // But key mapping is still possible.
-    assert.equal(await keyMap("c", tree), "_c");
+    assert.equal(await key("c", tree), "_c");
     // And now we have a cache hit.
-    assert.equal(await inverseKeyMap("_c", tree), "c");
+    assert.equal(await inverseKey("_c", tree), "c");
     assert.equal(callCount, 3);
   });
 });

package/test/transforms/groupBy.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import * as Tree from "../../src/Tree.js";
+import { Tree } from "../../src/internal.js";
 import groupBy from "../../src/transforms/groupBy.js";
 
 describe("groupBy transform", () => {

package/test/transforms/keyMapsForExtensions.test.js

@@ -1,30 +1,29 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import ObjectTree from "../../src/ObjectTree.js";
-import * as Tree from "../../src/Tree.js";
-import keyMapsForExtensions from "../../src/transforms/keyMapsForExtensions.js";
+import { ObjectTree, Tree } from "../../src/internal.js";
+import keyFunctionsForExtensions from "../../src/transforms/keyFunctionsForExtensions.js";
 import map from "../../src/transforms/map.js";
 
 describe("keyMapsForExtensions", () => {
   test("returns key functions that pass a matching key through", async () => {
-    const { inverseKeyMap, keyMap } = keyMapsForExtensions({
+    const { inverseKey, key } = keyFunctionsForExtensions({
       sourceExtension: "txt",
     });
-    assert.equal(await inverseKeyMap("file.txt"), "file.txt");
-    assert.equal(await keyMap("file.txt"), "file.txt");
-    assert.equal(await inverseKeyMap("file.foo"), undefined);
-    assert.equal(await keyMap("file.foo"), undefined);
+    assert.equal(await inverseKey("file.txt"), "file.txt");
+    assert.equal(await key("file.txt"), "file.txt");
+    assert.equal(await inverseKey("file.foo"), undefined);
+    assert.equal(await key("file.foo"), undefined);
   });
 
   test("returns key functions that can map extensions", async () => {
-    const { inverseKeyMap, keyMap } = keyMapsForExtensions({
+    const { inverseKey, key } = keyFunctionsForExtensions({
       resultExtension: "html",
       sourceExtension: "md",
     });
-    assert.equal(await inverseKeyMap("file.html"), "file.md");
-    assert.equal(await keyMap("file.md"), "file.html");
-    assert.equal(await inverseKeyMap("file.foo"), undefined);
-    assert.equal(await keyMap("file.foo"), undefined);
+    assert.equal(await inverseKey("file.html"), "file.md");
+    assert.equal(await key("file.md"), "file.html");
+    assert.equal(await inverseKey("file.foo"), undefined);
+    assert.equal(await key("file.foo"), undefined);
   });
 
   test("works with map to handle keys that end in a given resultExtension", async () => {
@@ -33,13 +32,13 @@ describe("keyMapsForExtensions", () => {
       file2: "won't be mapped",
       "file3.foo": "won't be mapped",
     });
-    const { inverseKeyMap, keyMap } = keyMapsForExtensions({
+    const { inverseKey, key } = keyFunctionsForExtensions({
       sourceExtension: "txt",
     });
     const transform = map({
-      inverseKeyMap,
-      keyMap,
-      valueMap: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
+      inverseKey,
+      key,
+      value: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
     const fixture = transform(files);
     assert.deepEqual(await Tree.plain(fixture), {
@@ -53,14 +52,14 @@ describe("keyMapsForExtensions", () => {
       file2: "won't be mapped",
       "file3.foo": "won't be mapped",
     });
-    const { inverseKeyMap, keyMap } = keyMapsForExtensions({
+    const { inverseKey, key } = keyFunctionsForExtensions({
       resultExtension: "upper",
       sourceExtension: "txt",
     });
     const transform = map({
-      inverseKeyMap,
-      keyMap,
-      valueMap: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
+      inverseKey,
+      key,
+      value: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
     const fixture = transform(files);
     assert.deepEqual(await Tree.plain(fixture), {