@weborigami/async-tree 0.0.48 → 0.0.50

package/main.js

@@ -11,14 +11,20 @@ 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 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 group } from "./src/operations/group.js";
+export { default as groupFn } from "./src/operations/groupFn.js";
+export { default as map } from "./src/operations/map.js";
 export { default as merge } from "./src/operations/merge.js";
-export { default as mergeDeep } from "./src/operations/mergeDeep.js";
+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 groupBy } from "./src/transforms/groupBy.js";
 export { default as keyFunctionsForExtensions } from "./src/transforms/keyFunctionsForExtensions.js";
-export { default as map } from "./src/transforms/map.js";
-export { default as sort } from "./src/transforms/sort.js";
-export { default as sortBy } from "./src/transforms/sortBy.js";
-export { default as sortNatural } from "./src/transforms/sortNatural.js";
+export { default as mapFn } from "./src/transforms/mapFn.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,17 +1,17 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.48",
+  "version": "0.0.50",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "20.11.27",
-    "typescript": "5.4.2"
+    "@types/node": "20.12.8",
+    "typescript": "5.4.5"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.48"
+    "@weborigami/types": "0.0.50"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/BrowserFileTree.js

@@ -1,5 +1,5 @@
 import { Tree } from "./internal.js";
-import { hiddenFileNames, isStringLike, sortNatural } from "./utilities.js";
+import { hiddenFileNames, isStringLike, naturalOrder } from "./utilities.js";
 
 const TypedArray = Object.getPrototypeOf(Uint8Array);
 
@@ -74,7 +74,8 @@ export default class BrowserFileTree {
     }
     // Filter out unhelpful file names.
     keys = keys.filter((key) => !hiddenFileNames.includes(key));
-    sortNatural(keys);
+    keys.sort(naturalOrder);
+
     return keys;
   }
 

package/src/FileTree.js

@@ -6,7 +6,7 @@ import {
   getRealmObjectPrototype,
   hiddenFileNames,
   isPacked,
-  sortNatural,
+  naturalOrder,
 } from "./utilities.js";
 
 /**
@@ -41,6 +41,11 @@ export default class FileTree {
   }
 
   async get(key) {
+    if (!key) {
+      // Undefined key or empty string key is invalid.
+      return undefined;
+    }
+
     const filePath = path.resolve(this.dirname, key);
 
     let stats;
@@ -91,7 +96,8 @@ export default class FileTree {
 
     // Node fs.readdir sort order appears to be unreliable; see, e.g.,
     // https://github.com/nodejs/node/issues/3232.
-    sortNatural(names);
+    names.sort(naturalOrder);
+
     return names;
   }
 
@@ -101,7 +107,7 @@ export default class FileTree {
 
   async set(key, value) {
     // Where are we going to write this value?
-    const stringKey = key ? String(key) : "";
+    const stringKey = key != null ? String(key) : "";
     const destPath = path.resolve(this.dirname, stringKey);
 
     if (value === undefined) {
@@ -189,7 +195,7 @@ function isStringLike(obj) {
     return true;
   } else if (obj?.toString === undefined) {
     return false;
-  } else if (obj.toString === getRealmObjectPrototype(obj).toString) {
+  } else if (obj.toString === getRealmObjectPrototype(obj)?.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.

package/src/Tree.js

@@ -3,7 +3,7 @@ import FunctionTree from "./FunctionTree.js";
 import MapTree from "./MapTree.js";
 import SetTree from "./SetTree.js";
 import { DeepObjectTree, ObjectTree } from "./internal.js";
-import mapTransform from "./transforms/map.js";
+import mapTransform from "./transforms/mapFn.js";
 import * as utilities from "./utilities.js";
 import {
   castArrayLike,
@@ -388,11 +388,16 @@ export async function traverseOrThrow(treelike, ...keys) {
       value = await value.unpack();
     }
 
-    // Peek ahead: if there's only one key left and it's an empty string, return
-    // the value itself.
-    if (remainingKeys.length === 1 && remainingKeys[0] === "") {
-      return value;
-    } else if (value instanceof Function) {
+    if (!isTreelike(value)) {
+      // Value isn't treelike, so can't be traversed except for a special case:
+      // if there's only one key left and it's an empty string, return the
+      // non-treelike value.
+      if (remainingKeys.length === 1 && remainingKeys[0] === "") {
+        return value;
+      }
+    }
+
+    if (value instanceof Function) {
       // Value is a function: call it with the remaining keys.
       const fn = value;
       // We'll take as many keys as the function's length, but at least one.
@@ -401,12 +406,20 @@ export async function traverseOrThrow(treelike, ...keys) {
       key = null;
       value = await fn.call(target, ...args);
     } else {
+      const originalValue = value;
+
       // Value is some other treelike object: cast it to a tree.
       const tree = from(value);
       // Get the next key.
       key = remainingKeys.shift();
       // Get the value for the key.
       value = await tree.get(key);
+
+      // The empty key as the final key is a special case: if the tree doesn't
+      // have a value for the empty key, use the original value.
+      if (value === undefined && remainingKeys.length === 0 && key === "") {
+        value = originalValue;
+      }
     }
   }
 

package/src/operations/{mergeDeep.js → deepMerge.js}

@@ -4,11 +4,14 @@ import { Tree } from "../internal.js";
  * Return a tree that performs a deep merge of the given trees.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @param {import("../../index.ts").Treelike[]} sources
  * @returns {AsyncTree & { description: string }}
  */
-export default function mergeDeep(...trees) {
+export default function deepMerge(...sources) {
+  let trees = sources.map((treelike) => Tree.from(treelike));
+  let mergeParent;
   return {
-    description: "mergeDeep",
+    description: "deepMerge",
 
     async get(key) {
       const subtrees = [];
@@ -22,12 +25,12 @@ export default function mergeDeep(...trees) {
         }
       }
 
-      return subtrees.length > 0 ? mergeDeep(...subtrees) : undefined;
+      return subtrees.length > 0 ? deepMerge(...subtrees) : undefined;
     },
 
     async isKeyForSubtree(key) {
       for (const tree of trees) {
-        if (await tree.isKeyForSubtree(key)) {
+        if (await Tree.isKeyForSubtree(tree, key)) {
           return true;
         }
       }
@@ -43,5 +46,19 @@ export default function mergeDeep(...trees) {
       }
       return keys;
     },
+
+    get parent() {
+      return mergeParent;
+    },
+    set parent(parent) {
+      mergeParent = parent;
+      trees = sources.map((treelike) => {
+        const tree = Tree.isAsyncTree(treelike)
+          ? Object.create(treelike)
+          : Tree.from(treelike);
+        tree.parent = parent;
+        return tree;
+      });
+    },
   };
 }

package/src/operations/deepTake.js

@@ -0,0 +1,15 @@
+import deepTakeFn from "./deepTakeFn.js";
+
+/**
+ * Returns a function that traverses a tree deeply and returns the values of the
+ * first `count` keys.
+ *
+ * This is similar to `deepValues`, but it is more efficient for large trees as
+ * stops after `count` values.
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ * @param {number} count
+ */
+export default function deepTake(treelike, count) {
+  return deepTakeFn(count)(treelike);
+}

package/src/operations/deepTakeFn.js

@@ -0,0 +1,37 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Returns a function that traverses a tree deeply and returns the values of the
+ * first `count` keys.
+ *
+ * @param {number} count
+ */
+export default function deepTakeFn(count) {
+  /**
+   * @param {import("../../index.ts").Treelike} treelike
+   */
+  return async function deepTakeFn(treelike) {
+    const tree = await Tree.from(treelike);
+    const { values } = await traverse(tree, count);
+    return values;
+  };
+}
+
+async function traverse(tree, count) {
+  const values = [];
+  for (const key of await tree.keys()) {
+    if (count <= 0) {
+      break;
+    }
+    let value = await tree.get(key);
+    if (Tree.isAsyncTree(value)) {
+      const traversed = await traverse(value, count);
+      values.push(...traversed.values);
+      count = traversed.count;
+    } else {
+      values.push(value);
+      count--;
+    }
+  }
+  return { count, values };
+}

package/src/operations/deepValues.js

@@ -0,0 +1,10 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Return the in-order exterior values of a tree as a flat array.
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ */
+export default async function deepValues(treelike) {
+  return Tree.mapReduce(treelike, null, async (values) => values.flat());
+}

package/src/operations/group.js

@@ -0,0 +1,12 @@
+import groupFn from "./groupFn.js";
+
+/**
+ * Given a function that returns a grouping key for a value, returns a transform
+ * that applies that grouping function to a tree.
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").ValueKeyFn} groupKeyFn
+ */
+export default function group(treelike, groupKeyFn) {
+  return groupFn(groupKeyFn)(treelike);
+}

package/src/{transforms/groupBy.js → operations/groupFn.js}

@@ -1,4 +1,4 @@
-import { DeepObjectTree, Tree } from "../internal.js";
+import { ObjectTree, Tree } from "../internal.js";
 
 /**
  * Given a function that returns a grouping key for a value, returns a transform
@@ -36,6 +36,6 @@ export default function createGroupByTransform(groupKeyFn) {
       }
     }
 
-    return new DeepObjectTree(result);
+    return new ObjectTree(result);
   };
 }

package/src/operations/map.js

@@ -0,0 +1,14 @@
+import mapFn from "../transforms/mapFn.js";
+
+/**
+ * Transform the keys and/or values of a tree.
+ *
+ * @typedef {import("../../index.ts").KeyFn} KeyFn
+ * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ * @param {ValueKeyFn|{ deep?: boolean, description?: string, needsSourceValue?: boolean, inverseKey?: KeyFn, key?: KeyFn, value?: ValueKeyFn }} options
+ */
+export default function map(treelike, options = {}) {
+  return mapFn(options)(treelike);
+}

package/src/operations/merge.js

@@ -1,3 +1,5 @@
+import { Tree } from "../internal.js";
+
 /**
  * Return a tree that performs a shallow merge of the given trees.
  *
@@ -8,10 +10,11 @@
  * return a defined value, the `get` method returns undefined.
  *
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @param {import("../../index.ts").Treelike[]} sources
  * @returns {AsyncTree & { description: string }}
  */
 export default function merge(...sources) {
-  let trees = sources;
+  let trees = sources.map((treelike) => Tree.from(treelike));
   let mergeParent;
   return {
     description: "merge",
@@ -28,7 +31,7 @@ export default function merge(...sources) {
 
     async isKeyForSubtree(key) {
       for (const tree of trees) {
-        if (await tree.isKeyForSubtree(key)) {
+        if (await Tree.isKeyForSubtree(tree, key)) {
           return true;
         }
       }
@@ -50,8 +53,10 @@ export default function merge(...sources) {
     },
     set parent(parent) {
       mergeParent = parent;
-      trees = sources.map((source) => {
-        const tree = Object.create(source);
+      trees = sources.map((treelike) => {
+        const tree = Tree.isAsyncTree(treelike)
+          ? Object.create(treelike)
+          : Tree.from(treelike);
         tree.parent = parent;
         return tree;
       });

package/src/operations/sort.js

@@ -0,0 +1,18 @@
+import sortFn from "../transforms/sortFn.js";
+
+/**
+ * Return a new tree with the original's keys sorted. A comparison function can
+ * be provided; by default the keys will be sorted in [natural sort
+ * order](https://en.wikipedia.org/wiki/Natural_sort_order).
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {(key: any, tree: AsyncTree) => any} SortKeyFn
+ * @typedef {{ compare?: (a: any, b: any) => number, sortKey?: SortKeyFn }}
+ * SortOptions
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ * @param {SortOptions} [options]
+ */
+export default function sort(treelike, options) {
+  return sortFn(options)(treelike);
+}

package/src/operations/take.js

@@ -0,0 +1,11 @@
+import takeFn from "../transforms/takeFn.js";
+
+/**
+ * Returns a new tree with the number of keys limited to the indicated count.
+ *
+ * @param {import("../../index.ts").Treelike} treelike
+ * @param {number} count
+ */
+export default function take(treelike, count) {
+  return takeFn(count)(treelike);
+}

package/src/transforms/{map.js → mapFn.js}

@@ -1,4 +1,5 @@
-import { Tree } from "../internal.js";
+import { ObjectTree, Tree } from "../internal.js";
+import { isPlainObject } from "../utilities.js";
 
 /**
  * Return a transform function that maps the keys and/or values of a tree.
@@ -7,6 +8,7 @@ import { Tree } from "../internal.js";
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
  *
  * @param {ValueKeyFn|{ deep?: boolean, description?: string, needsSourceValue?: boolean, inverseKey?: KeyFn, key?: KeyFn, value?: ValueKeyFn }} options
+ * @returns {import("../../index.ts").TreeTransform}
  */
 export default function createMapTransform(options = {}) {
   let deep;
@@ -45,7 +47,11 @@ export default function createMapTransform(options = {}) {
    * @type {import("../../index.ts").TreeTransform}
    */
   return function map(treelike) {
-    const tree = Tree.from(treelike);
+    const tree =
+      !deep && isPlainObject(treelike) && !Tree.isAsyncTree(treelike)
+        ? new ObjectTree(treelike)
+        : 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. For example, the `parent` of the transformed tree is

package/src/transforms/sortFn.js

@@ -0,0 +1,67 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Return a transform function that sorts a tree's keys using a comparison
+ * function.
+ *
+ * If the `options` include a `sortKey` function, that will be invoked for each
+ * key in the tree to produce a sort key. If no `sortKey` function is provided,
+ * the original keys will be used as sort keys.
+ *
+ * If the `options` include a `compare` function, that will be used to compare
+ * sort keys.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {(key: any, tree: AsyncTree) => any} SortKeyFn
+ * @typedef {{ compare?: (a: any, b: any) => number, sortKey?: SortKeyFn }}
+ * SortOptions
+ *
+ * @param {SortOptions} [options]
+ */
+export default function sortFn(options) {
+  const sortKey = options?.sortKey;
+  let compare = options?.compare;
+
+  /**
+   * @type {import("../../index.ts").TreeTransform}
+   */
+  return function sort(treelike) {
+    const tree = Tree.from(treelike);
+    const transformed = Object.create(tree);
+    transformed.keys = async () => {
+      const keys = Array.from(await tree.keys());
+
+      if (sortKey) {
+        // Invoke the async sortKey function to get sort keys.
+        // Create { key, sortKey } tuples.
+        const tuples = await Promise.all(
+          keys.map(async (key) => {
+            const sort = await sortKey(key, tree);
+            if (sort === undefined) {
+              throw new Error(
+                `sortKey function returned undefined for key ${key}`
+              );
+            }
+            return { key, sort };
+          })
+        );
+
+        // Wrap the comparison function so it applies to sort keys.
+        const defaultCompare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+        const originalCompare = compare ?? defaultCompare;
+        // Sort by the sort key.
+        const sortedTuples = tuples.toSorted((a, b) =>
+          originalCompare(a.sort, b.sort)
+        );
+        // Map back to the original keys.
+        const sorted = sortedTuples.map((pair) => pair.key);
+        return sorted;
+      } else {
+        // Use original keys as sort keys.
+        // If compare is undefined, this uses default sort order.
+        return keys.toSorted(compare);
+      }
+    };
+    return transformed;
+  };
+}

package/src/transforms/takeFn.js

@@ -0,0 +1,25 @@
+import { Tree } from "../internal.js";
+
+/**
+ * Limit the number of keys to the indicated count.
+ *
+ * @param {number} count
+ */
+export default function take(count) {
+  /**
+   * @type {import("../../index.ts").TreeTransform}
+   */
+  return (treelike) => {
+    const tree = Tree.from(treelike);
+    return {
+      async keys() {
+        const keys = Array.from(await tree.keys());
+        return keys.slice(0, count);
+      },
+
+      async get(key) {
+        return tree.get(key);
+      },
+    };
+  };
+}

package/src/utilities.d.ts

@@ -8,5 +8,4 @@ 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;
-export function sortNatural(array: string[]): void;
+export const naturalOrder: (a: string, b: string) => number;

package/src/utilities.js

@@ -30,6 +30,10 @@ export function castArrayLike(object) {
  * @param {any} object
  */
 export function getRealmObjectPrototype(object) {
+  if (Object.getPrototypeOf(object) === null) {
+    // The object has no prototype.
+    return null;
+  }
   let proto = object;
   while (Object.getPrototypeOf(proto) !== null) {
     proto = Object.getPrototypeOf(proto);
@@ -96,7 +100,7 @@ export function isStringLike(object) {
     return true;
   } else if (object?.toString === undefined) {
     return false;
-  } else if (object.toString === getRealmObjectPrototype(object).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.
@@ -131,22 +135,10 @@ export function keysFromPath(pathname) {
   return keys;
 }
 
-// Used for natural sort order
-export const naturalSortCompareFn = new Intl.Collator(undefined, {
-  numeric: true,
-}).compare;
-
 /**
- * Sort the given array using [natural sort
- * order](https://en.wikipedia.org/wiki/Natural_sort_order). Like the native
- * `Array` `sort` function, this operation destructively modifies the array in
- * place.
- *
- * The default sort order for some sources like operating system files can be
- * unpredictable. Since it's quite common for file names to include numbers, it
- * can helpful to use natural sort order instead: ["file1", "file9", "file10"]
- * instead of ["file1", "file10", "file9"].
+ * Compare two strings using [natural sort
+ * order](https://en.wikipedia.org/wiki/Natural_sort_order).
  */
-export function sortNatural(array) {
-  array.sort(naturalSortCompareFn);
-}
+export const naturalOrder = new Intl.Collator(undefined, {
+  numeric: true,
+}).compare;

package/test/operations/{mergeDeep.test.js → deepMerge.test.js}

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { DeepObjectTree, Tree } from "../../src/internal.js";
-import mergeDeep from "../../src/operations/mergeDeep.js";
+import mergeDeep from "../../src/operations/deepMerge.js";
 
 describe("mergeDeep", () => {
   test("can merge deep", async () => {

package/test/operations/deepTakeFn.test.js

@@ -0,0 +1,21 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import deepTakeFn from "../../src/operations/deepTakeFn.js";
+
+describe("deepTakeFn", () => {
+  test("traverses deeply and returns a limited number of items", async () => {
+    const tree = {
+      a: 1,
+      b: {
+        c: 2,
+        d: {
+          e: 3,
+        },
+        f: 4,
+      },
+      g: 5,
+    };
+    const result = await deepTakeFn(4)(tree);
+    assert.deepEqual(result, [1, 2, 3, 4]);
+  });
+});

package/test/operations/deepValues.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import deepValues from "../../src/operations/deepValues.js";
+
+describe("deepValues", () => {
+  test("returns in-order array of a tree's values", async () => {
+    const tree = {
+      a: 1,
+      b: {
+        c: 2,
+        d: {
+          e: 3,
+        },
+      },
+      f: {
+        g: 4,
+      },
+    };
+    const values = await deepValues(tree);
+    assert.deepEqual(values, [1, 2, 3, 4]);
+  });
+});

package/test/transforms/{groupBy.test.js → groupFn.test.js}

@@ -1,9 +1,9 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { Tree } from "../../src/internal.js";
-import groupBy from "../../src/transforms/groupBy.js";
+import groupFn from "../../src/operations/groupFn.js";
 
-describe("groupBy transform", () => {
+describe("groupFn transform", () => {
   test("groups using a group key function", async () => {
     const fonts = [
       { name: "Aboreto", tags: ["Sans Serif"] },
@@ -12,7 +12,7 @@ describe("groupBy transform", () => {
       { name: "Work Sans", tags: ["Grotesque", "Sans Serif"] },
     ];
     const tree = Tree.from(fonts);
-    const grouped = await groupBy((value, key, tree) => value.tags)(tree);
+    const grouped = await groupFn((value, key, tree) => value.tags)(tree);
     assert.deepEqual(await Tree.plain(grouped), {
       Geometric: [{ name: "Albert Sans", tags: ["Geometric", "Sans Serif"] }],
       Grotesque: [{ name: "Work Sans", tags: ["Grotesque", "Sans Serif"] }],

package/test/transforms/keyMapsForExtensions.test.js

@@ -2,7 +2,7 @@ import assert from "node:assert";
 import { describe, test } from "node:test";
 import { ObjectTree, Tree } from "../../src/internal.js";
 import keyFunctionsForExtensions from "../../src/transforms/keyFunctionsForExtensions.js";
-import map from "../../src/transforms/map.js";
+import map from "../../src/transforms/mapFn.js";
 
 describe("keyMapsForExtensions", () => {
   test("returns key functions that pass a matching key through", async () => {

package/test/transforms/{map.test.js → mapFn.test.js}

@@ -2,15 +2,15 @@ import assert from "node:assert";
 import { describe, test } from "node:test";
 import FunctionTree from "../../src/FunctionTree.js";
 import { DeepObjectTree, ObjectTree, Tree } from "../../src/internal.js";
-import map from "../../src/transforms/map.js";
+import mapFn from "../../src/transforms/mapFn.js";
 
-describe("map", () => {
+describe("mapFn", () => {
   test("returns identity graph if no key or value", async () => {
     const tree = {
       a: "letter a",
       b: "letter b",
     };
-    const mapped = map()(tree);
+    const mapped = mapFn()(tree);
     assert.deepEqual(await Tree.plain(mapped), {
       a: "letter a",
       b: "letter b",
@@ -23,7 +23,7 @@ describe("map", () => {
       b: "letter b",
       c: undefined, // Won't be mapped
     });
-    const uppercaseValues = map({
+    const uppercaseValues = mapFn({
       value: (sourceValue, sourceKey, innerTree) => {
         assert(sourceKey === "a" || sourceKey === "b");
         assert.equal(innerTree, tree);
@@ -43,7 +43,7 @@ describe("map", () => {
       a: "letter a",
       b: "letter b",
     };
-    const uppercaseValues = map((sourceValue, sourceKey, tree) => {
+    const uppercaseValues = mapFn((sourceValue, sourceKey, tree) => {
       assert(sourceKey === "a" || sourceKey === "b");
       return sourceValue.toUpperCase();
     });
@@ -59,7 +59,7 @@ describe("map", () => {
       a: "letter a",
       b: "letter b",
     };
-    const doubleKeys = map({
+    const doubleKeys = mapFn({
       key: async (sourceKey, tree) => `_${sourceKey}`,
       inverseKey: async (resultKey, tree) => resultKey.slice(1),
     });
@@ -75,7 +75,7 @@ describe("map", () => {
       a: "letter a",
       b: "letter b",
     };
-    const doubleKeysUppercaseValues = map({
+    const doubleKeysUppercaseValues = mapFn({
       key: async (sourceKey, tree) => `_${sourceKey}`,
       inverseKey: async (resultKey, tree) => resultKey.slice(1),
       value: async (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
@@ -94,7 +94,7 @@ describe("map", () => {
         b: "letter b",
       },
     };
-    const doubleKeys = map({
+    const doubleKeys = mapFn({
       key: async (sourceKey, tree) => `_${sourceKey}`,
       inverseKey: async (resultKey, tree) => resultKey.slice(1),
       value: async (sourceValue, sourceKey, tree) => sourceKey,
@@ -114,7 +114,7 @@ describe("map", () => {
       a: "letter a",
       b: "letter b",
     };
-    const mapped = map(uppercase)(tree);
+    const mapped = mapFn(uppercase)(tree);
     assert.deepEqual(await Tree.plain(mapped), {
       _a: "LETTER A",
       _b: "LETTER B",
@@ -128,7 +128,7 @@ describe("map", () => {
         b: "letter b",
       },
     });
-    const uppercaseValues = map({
+    const uppercaseValues = mapFn({
       deep: true,
       value: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
@@ -148,7 +148,7 @@ describe("map", () => {
         b: "letter b",
       },
     });
-    const doubleKeys = map({
+    const doubleKeys = mapFn({
       deep: true,
       key: async (sourceKey, tree) => `_${sourceKey}`,
       inverseKey: async (resultKey, tree) => resultKey.slice(1),
@@ -169,7 +169,7 @@ describe("map", () => {
         b: "letter b",
       },
     });
-    const doubleKeysUppercaseValues = map({
+    const doubleKeysUppercaseValues = mapFn({
       deep: true,
       key: async (sourceKey, tree) => `_${sourceKey}`,
       inverseKey: async (resultKey, tree) => resultKey.slice(1),
@@ -189,7 +189,7 @@ describe("map", () => {
     const tree = new FunctionTree(() => {
       flag = true;
     }, ["a", "b", "c"]);
-    const mapped = map({
+    const mapped = mapFn({
       needsSourceValue: false,
       value: () => "X",
     })(tree);

package/test/transforms/sortFn.test.js

@@ -0,0 +1,49 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
+import sortFn from "../../src/transforms/sortFn.js";
+
+describe("sortFn", () => {
+  test("sorts keys using default sort order", async () => {
+    const tree = Tree.from({
+      file10: null,
+      file1: null,
+      file9: null,
+    });
+    const sorted = sortFn()(tree);
+    assert.deepEqual(Array.from(await sorted.keys()), [
+      "file1",
+      "file10",
+      "file9",
+    ]);
+  });
+
+  test("invokes a comparison function", async () => {
+    const tree = Tree.from({
+      b: 2,
+      c: 3,
+      a: 1,
+    });
+    // Reverse order
+    const compare = (a, b) => (a > b ? -1 : a < b ? 1 : 0);
+    const sorted = sortFn({ compare })(tree);
+    assert.deepEqual(Array.from(await sorted.keys()), ["c", "b", "a"]);
+  });
+
+  test("invokes a sortKey function", async () => {
+    const tree = {
+      Alice: { age: 48 },
+      Bob: { age: 36 },
+      Carol: { age: 42 },
+    };
+    const transform = await sortFn({
+      sortKey: async (key, tree) => Tree.traverse(tree, key, "age"),
+    });
+    const result = transform(tree);
+    assert.deepEqual(Array.from(await result.keys()), [
+      "Bob",
+      "Carol",
+      "Alice",
+    ]);
+  });
+});

package/test/transforms/takeFn.test.js

@@ -0,0 +1,20 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { Tree } from "../../src/internal.js";
+import takeFn from "../../src/transforms/takeFn.js";
+
+describe("takeFn", () => {
+  test("limits the number of keys to the indicated count", async () => {
+    const tree = {
+      a: 1,
+      b: 2,
+      c: 3,
+      d: 4,
+    };
+    const result = await takeFn(2)(tree);
+    assert.deepEqual(await Tree.plain(result), {
+      a: 1,
+      b: 2,
+    });
+  });
+});

package/test/utilities.test.js

@@ -21,4 +21,10 @@ describe("utilities", () => {
     assert.deepEqual(utilities.keysFromPath("a/b/c"), ["a", "b", "c"]);
     assert.deepEqual(utilities.keysFromPath("foo/"), ["foo", ""]);
   });
+
+  test("naturalOrder compares strings in natural order", () => {
+    const strings = ["file10", "file1", "file9"];
+    strings.sort(utilities.naturalOrder);
+    assert.deepEqual(strings, ["file1", "file9", "file10"]);
+  });
 });

package/src/transforms/sort.js

@@ -1,25 +0,0 @@
-import { Tree } from "../internal.js";
-
-/**
- * Return a transform function that sorts a tree's keys.
- *
- * For sorting, the keys are converted to strings, then sorted according to each
- * character's Unicode code point value.
- *
- * @param {(a: any, b: any) => number} [compareFn]
- */
-export default function createSortTransform(compareFn) {
-  /**
-   * @type {import("../../index.ts").TreeTransform}
-   */
-  return function sortTransform(treelike) {
-    const tree = Tree.from(treelike);
-    const transform = Object.create(tree);
-    transform.keys = async () => {
-      const keys = Array.from(await tree.keys());
-      keys.sort(compareFn);
-      return keys;
-    };
-    return transform;
-  };
-}

package/src/transforms/sortBy.js

@@ -1,33 +0,0 @@
-import { Tree } from "../internal.js";
-
-/**
- * Return a transform function that sorts a tree's keys.
- *
- * The given `sortKeyFn` is invoked for each key/value pair in the tree, and
- * should produce a sort key for that pair. The sort keys are then compared to
- * determine the sort order for the tree's keys.
- *
- * @param {import("./map.js").KeyFn} sortKeyFn
- */
-export default function createSortByTransform(sortKeyFn) {
-  /**
-   * @type {import("../../index.ts").TreeTransform}
-   */
-  return function sortByTransform(treelike) {
-    const tree = Tree.from(treelike);
-    const transform = Object.create(tree);
-    transform.keys = async () => {
-      const keysAndSortKeys = [];
-      for (const key of await tree.keys()) {
-        const sortKey = await sortKeyFn(key, tree);
-        keysAndSortKeys.push({ key, sortKey });
-      }
-      keysAndSortKeys.sort((a, b) =>
-        a.sortKey < b.sortKey ? -1 : a.sortKey > b.sortKey ? 1 : 0
-      );
-      const sortedKeys = keysAndSortKeys.map(({ key }) => key);
-      return sortedKeys;
-    };
-    return transform;
-  };
-}

package/src/transforms/sortNatural.js

@@ -1,10 +0,0 @@
-import { naturalSortCompareFn } from "../utilities.js";
-import sort from "./sort.js";
-
-/**
- * Return a transform function that sorts a tree's keys using [natural sort
- * order](https://en.wikipedia.org/wiki/Natural_sort_order).
- */
-export default function sortNaturalTransform() {
-  return sort(naturalSortCompareFn);
-}

package/test/transforms/sort.test.js

@@ -1,30 +0,0 @@
-import assert from "node:assert";
-import { describe, test } from "node:test";
-import { Tree } from "../../src/internal.js";
-import sort from "../../src/transforms/sort.js";
-
-describe("sort transform", () => {
-  test("sorts keys", async () => {
-    const tree = Tree.from({
-      b: 2,
-      c: 3,
-      a: 1,
-    });
-    const sortTransform = sort();
-    const sorted = await sortTransform(tree);
-    assert.deepEqual(Array.from(await sorted.keys()), ["a", "b", "c"]);
-  });
-
-  test("sorts keys using a comparison function", async () => {
-    const tree = Tree.from({
-      b: 2,
-      c: 3,
-      a: 1,
-    });
-    // Reverse order
-    const compareFn = (a, b) => (a > b ? -1 : a < b ? 1 : 0);
-    const sortTransform = sort(compareFn);
-    const sorted = await sortTransform(tree);
-    assert.deepEqual(Array.from(await sorted.keys()), ["c", "b", "a"]);
-  });
-});

package/test/transforms/sortBy.test.js

@@ -1,22 +0,0 @@
-import assert from "node:assert";
-import { describe, test } from "node:test";
-import { Tree } from "../../src/internal.js";
-import sortBy from "../../src/transforms/sortBy.js";
-
-describe("sortBy transform", () => {
-  test("sorts keys using a provided sort key function", async () => {
-    const tree = Tree.from({
-      Alice: { age: 48 },
-      Bob: { age: 36 },
-      Carol: { age: 42 },
-    });
-    const sorted = await sortBy((key, tree) => Tree.traverse(tree, key, "age"))(
-      tree
-    );
-    assert.deepEqual(Array.from(await sorted.keys()), [
-      "Bob",
-      "Carol",
-      "Alice",
-    ]);
-  });
-});

package/test/transforms/sortNatural.test.js

@@ -1,21 +0,0 @@
-import assert from "node:assert";
-import { describe, test } from "node:test";
-import { Tree } from "../../src/internal.js";
-import sortNatural from "../../src/transforms/sortNatural.js";
-
-describe("sortNatural transform", () => {
-  test("sorts keys", async () => {
-    const tree = Tree.from({
-      file10: null,
-      file1: null,
-      file9: null,
-    });
-    const sortTransform = sortNatural();
-    const sorted = await sortTransform(tree);
-    assert.deepEqual(Array.from(await sorted.keys()), [
-      "file1",
-      "file9",
-      "file10",
-    ]);
-  });
-});