@weborigami/async-tree 0.0.73 → 0.2.0

package/test/{transforms/groupFn.test.js → operations/group.test.js}

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

package/test/{transforms → operations}/invokeFunctions.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { Tree } from "../../src/internal.js";
-import invokeFunctions from "../../src/transforms/invokeFunctions.js";
+import invokeFunctions from "../../src/operations/invokeFunctions.js";
 
 describe("invokeFunctions", () => {
   test("invokes function values, leaves other values as is", async () => {

package/test/{transforms → operations}/keyFunctionsForExtensions.test.js

@@ -1,13 +1,13 @@
 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/mapFn.js";
+import keyFunctionsForExtensions from "../../src/operations/keyFunctionsForExtensions.js";
+import map from "../../src/operations/map.js";
 
 describe("keyMapsForExtensions", () => {
   test("returns key functions that pass a matching key through", async () => {
     const { inverseKey, key } = keyFunctionsForExtensions({
-      sourceExtension: "txt",
+      sourceExtension: ".txt",
     });
     assert.equal(await inverseKey("file.txt"), "file.txt");
     assert.equal(await inverseKey("file.txt/"), "file.txt");
@@ -19,8 +19,8 @@ describe("keyMapsForExtensions", () => {
 
   test("returns key functions that can map extensions", async () => {
     const { inverseKey, key } = keyFunctionsForExtensions({
-      resultExtension: "json",
-      sourceExtension: "md",
+      resultExtension: ".json",
+      sourceExtension: ".md",
     });
     assert.equal(await inverseKey("file.json"), "file.md");
     assert.equal(await inverseKey("file.json/"), "file.md");
@@ -30,6 +30,17 @@ describe("keyMapsForExtensions", () => {
     assert.equal(await key("file.foo"), undefined);
   });
 
+  test("key functions can handle a slash as an explicit extension", async () => {
+    const { inverseKey, key } = keyFunctionsForExtensions({
+      resultExtension: ".html",
+      sourceExtension: "/",
+    });
+    assert.equal(await inverseKey("file.html"), "file/");
+    assert.equal(await inverseKey("file.html/"), "file/");
+    assert.equal(await key("file"), undefined);
+    assert.equal(await key("file/"), "file.html");
+  });
+
   test("works with map to handle keys that end in a given resultExtension", async () => {
     const files = new ObjectTree({
       "file1.txt": "will be mapped",
@@ -37,14 +48,13 @@ describe("keyMapsForExtensions", () => {
       "file3.foo": "won't be mapped",
     });
     const { inverseKey, key } = keyFunctionsForExtensions({
-      sourceExtension: "txt",
+      sourceExtension: ".txt",
     });
-    const transform = map({
+    const fixture = map(files, {
       inverseKey,
       key,
       value: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
-    const fixture = transform(files);
     assert.deepEqual(await Tree.plain(fixture), {
       "file1.txt": "WILL BE MAPPED",
     });
@@ -57,15 +67,14 @@ describe("keyMapsForExtensions", () => {
       "file3.foo": "won't be mapped",
     });
     const { inverseKey, key } = keyFunctionsForExtensions({
-      resultExtension: "upper",
-      sourceExtension: "txt",
+      resultExtension: ".upper",
+      sourceExtension: ".txt",
     });
-    const transform = map({
+    const fixture = map(files, {
       inverseKey,
       key,
       value: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
-    const fixture = transform(files);
     assert.deepEqual(await Tree.plain(fixture), {
       "file1.upper": "WILL BE MAPPED",
     });

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

@@ -1,17 +1,17 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import FunctionTree from "../../src/FunctionTree.js";
+import FunctionTree from "../../src/drivers/FunctionTree.js";
 import { DeepObjectTree, ObjectTree, Tree } from "../../src/internal.js";
+import map from "../../src/operations/map.js";
 import * as trailingSlash from "../../src/trailingSlash.js";
-import mapFn from "../../src/transforms/mapFn.js";
 
-describe("mapFn", () => {
-  test("returns identity graph if no key or value", async () => {
+describe("map", () => {
+  test("returns identity graph if no key or value function is supplied", async () => {
     const tree = {
       a: "letter a",
       b: "letter b",
     };
-    const mapped = mapFn()(tree);
+    const mapped = map(tree, {});
     assert.deepEqual(await Tree.plain(mapped), {
       a: "letter a",
       b: "letter b",
@@ -24,14 +24,13 @@ describe("mapFn", () => {
       b: "letter b",
       c: undefined, // Won't be mapped
     });
-    const uppercaseValues = mapFn({
+    const mapped = map(tree, {
       value: (sourceValue, sourceKey, innerTree) => {
         assert(sourceKey === "a" || sourceKey === "b");
         assert.equal(innerTree, tree);
         return sourceValue.toUpperCase();
       },
     });
-    const mapped = uppercaseValues(tree);
     assert.deepEqual(await Tree.plain(mapped), {
       a: "LETTER A",
       b: "LETTER B",
@@ -44,12 +43,11 @@ describe("mapFn", () => {
       a: "letter a",
       b: "letter b",
     };
-    const uppercaseValues = mapFn((sourceValue, sourceKey, tree) => {
+    const uppercaseValues = map(tree, (sourceValue, sourceKey, tree) => {
       assert(sourceKey === "a" || sourceKey === "b");
       return sourceValue.toUpperCase();
     });
-    const mapped = uppercaseValues(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(uppercaseValues), {
       a: "LETTER A",
       b: "LETTER B",
     });
@@ -60,12 +58,11 @@ describe("mapFn", () => {
       a: "letter a",
       b: "letter b",
     };
-    const underscopeKeys = mapFn({
+    const underscoreKeys = map(tree, {
       key: addUnderscore,
       inverseKey: removeUnderscore,
     });
-    const mapped = underscopeKeys(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(underscoreKeys), {
       _a: "letter a",
       _b: "letter b",
     });
@@ -76,13 +73,12 @@ describe("mapFn", () => {
       a: "letter a",
       b: "letter b",
     };
-    const underscoreKeysUppercaseValues = mapFn({
+    const underscoreKeysUppercaseValues = map(tree, {
       key: addUnderscore,
       inverseKey: removeUnderscore,
       value: async (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
-    const mapped = underscoreKeysUppercaseValues(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(underscoreKeysUppercaseValues), {
       _a: "LETTER A",
       _b: "LETTER B",
     });
@@ -95,13 +91,12 @@ describe("mapFn", () => {
         b: "letter b",
       },
     };
-    const underscopeKeys = mapFn({
+    const underscoreKeys = map(tree, {
       key: async (sourceKey, tree) => `_${sourceKey}`,
       inverseKey: async (resultKey, tree) => resultKey.slice(1),
       value: async (sourceValue, sourceKey, tree) => sourceKey,
     });
-    const mapped = underscopeKeys(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(underscoreKeys), {
       _a: "a",
       _more: "more",
     });
@@ -115,7 +110,7 @@ describe("mapFn", () => {
       a: "letter a",
       b: "letter b",
     };
-    const mapped = mapFn(uppercase)(tree);
+    const mapped = map(tree, uppercase);
     assert.deepEqual(await Tree.plain(mapped), {
       _a: "LETTER A",
       _b: "LETTER B",
@@ -129,12 +124,11 @@ describe("mapFn", () => {
         b: "letter b",
       },
     });
-    const uppercaseValues = mapFn({
+    const uppercaseValues = map(tree, {
       deep: true,
       value: (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
-    const mapped = uppercaseValues(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(uppercaseValues), {
       a: "LETTER A",
       more: {
         b: "LETTER B",
@@ -149,13 +143,12 @@ describe("mapFn", () => {
         b: "letter b",
       },
     });
-    const underscoreKeys = mapFn({
+    const underscoreKeys = map(tree, {
       deep: true,
       key: addUnderscore,
       inverseKey: removeUnderscore,
     });
-    const mapped = underscoreKeys(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(underscoreKeys), {
       _a: "letter a",
       more: {
         _b: "letter b",
@@ -170,14 +163,13 @@ describe("mapFn", () => {
         b: "letter b",
       },
     });
-    const underscoreKeysUppercaseValues = mapFn({
+    const underscoreKeysUppercaseValues = map(tree, {
       deep: true,
       key: addUnderscore,
       inverseKey: removeUnderscore,
       value: async (sourceValue, sourceKey, tree) => sourceValue.toUpperCase(),
     });
-    const mapped = underscoreKeysUppercaseValues(tree);
-    assert.deepEqual(await Tree.plain(mapped), {
+    assert.deepEqual(await Tree.plain(underscoreKeysUppercaseValues), {
       _a: "LETTER A",
       more: {
         _b: "LETTER B",
@@ -190,10 +182,10 @@ describe("mapFn", () => {
     const tree = new FunctionTree(() => {
       flag = true;
     }, ["a", "b", "c"]);
-    const mapped = mapFn({
+    const mapped = map(tree, {
       needsSourceValue: false,
       value: () => "X",
-    })(tree);
+    });
     assert.deepEqual(await Tree.plain(mapped), {
       a: "X",
       b: "X",

package/test/{transforms → operations}/regExpKeys.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 regExpKeys from "../../src/transforms/regExpKeys.js";
+import regExpKeys from "../../src/operations/regExpKeys.js";
 
 describe("regExpKeys", () => {
   test("matches keys using regular expressions", async () => {

package/test/{transforms → operations}/reverse.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import { Tree } from "../../src/internal.js";
-import reverse from "../../src/transforms/reverse.js";
+import reverse from "../../src/operations/reverse.js";
 
 describe("reverse", () => {
   test("reverses a tree's top-level keys", async () => {

package/test/{transforms/sortFn.test.js → operations/sort.test.js}

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

package/test/{transforms/takeFn.test.js → operations/take.test.js}

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

package/src/operations/deepTakeFn.js

@@ -1,43 +0,0 @@
-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) {
-    if (!treelike) {
-      const error = new TypeError(`deepTake: The tree isn't defined.`);
-      /** @type {any} */ (error).position = 0;
-      throw error;
-    }
-
-    const tree = await Tree.from(treelike, { deep: true });
-    const { values } = await traverse(tree, count);
-    return Tree.from(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/groupFn.js

@@ -1,57 +0,0 @@
-import { ObjectTree, Tree } from "../internal.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").ValueKeyFn} groupKeyFn
- */
-export default function createGroupByTransform(groupKeyFn) {
-  /**
-   * @type {import("../../index.ts").TreeTransform}
-   */
-  return async function groupByTransform(treelike) {
-    if (!treelike) {
-      const error = new TypeError(`groupBy: The tree to group isn't defined.`);
-      /** @type {any} */ (error).position = 0;
-      throw error;
-    }
-
-    const tree = Tree.from(treelike);
-
-    const keys = Array.from(await tree.keys());
-
-    // Are all the keys integers?
-    const isArray = keys.every((key) => !Number.isNaN(parseInt(key)));
-
-    const result = {};
-    for (const key of await tree.keys()) {
-      const value = await tree.get(key);
-
-      // Get the groups for this value.
-      let groups = await groupKeyFn(value, key, tree);
-      if (!groups) {
-        continue;
-      }
-
-      if (!Tree.isTreelike(groups)) {
-        // A single value was returned
-        groups = [groups];
-      }
-      groups = Tree.from(groups);
-
-      // Add the value to each group.
-      for (const group of await Tree.values(groups)) {
-        if (isArray) {
-          result[group] ??= [];
-          result[group].push(value);
-        } else {
-          result[group] ??= {};
-          result[group][key] = value;
-        }
-      }
-    }
-
-    return new ObjectTree(result);
-  };
-}

package/src/transforms/keyFunctionsForExtensions.js

@@ -1,78 +0,0 @@
-import * as trailingSlash from "../trailingSlash.js";
-
-/**
- * Given a source resultExtension and a result resultExtension, return a pair of key
- * functions that map between them.
- *
- * 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 keyFunctionsForExtensions({
-  resultExtension,
-  sourceExtension,
-}) {
-  if (resultExtension === undefined) {
-    resultExtension = sourceExtension;
-  }
-
-  return {
-    async inverseKey(resultKey, tree) {
-      // Remove trailing slash so that mapFn won't inadvertently unpack files.
-      const baseKey = trailingSlash.remove(resultKey);
-      const basename = matchExtension(baseKey, resultExtension);
-      return basename ? `${basename}${dotPrefix(sourceExtension)}` : undefined;
-    },
-
-    async key(sourceKey, tree) {
-      const hasSlash = trailingSlash.has(sourceKey);
-      const baseKey = trailingSlash.remove(sourceKey);
-      const basename = matchExtension(baseKey, sourceExtension);
-      return basename
-        ? // Preserve trailing slash
-          trailingSlash.toggle(
-            `${basename}${dotPrefix(resultExtension)}`,
-            hasSlash
-          )
-        : undefined;
-    },
-  };
-}
-
-function dotPrefix(resultExtension) {
-  return resultExtension ? `.${resultExtension}` : "";
-}
-
-/**
- * See if the key ends with the given resultExtension. If it does, return the
- * base name without the resultExtension; if it doesn't return null.
- *
- * A trailing slash in the key is ignored for purposes of comparison to comply
- * with the way Origami can unpack files. Example: the keys "data.json" and
- * "data.json/" are treated equally.
- *
- * This uses a different, more general interpretation of "resultExtension" to
- * mean any suffix, rather than Node's interpretation `path.extname`. In
- * particular, this will match an "resultExtension" like ".foo.bar" that
- * contains more than one dot.
- */
-function matchExtension(key, resultExtension) {
-  if (resultExtension) {
-    // Key matches if it ends with the same resultExtension
-    const dotExtension = dotPrefix(resultExtension);
-    if (
-      key.length > dotExtension.length &&
-      key.toLowerCase().endsWith(dotExtension)
-    ) {
-      return key.substring(0, key.length - dotExtension.length);
-    }
-  } else if (!key.includes?.(".")) {
-    // Key matches if it has no resultExtension
-    return key;
-  }
-  // Didn't match
-  return null;
-}

package/src/transforms/mapFn.js

@@ -1,126 +0,0 @@
-import { Tree } from "../internal.js";
-import * as trailingSlash from "../trailingSlash.js";
-
-/**
- * Return a transform function that maps the keys and/or values of a tree.
- *
- * @typedef {import("../../index.ts").KeyFn} KeyFn
- * @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;
-  let description;
-  let inverseKeyFn;
-  let keyFn;
-  let needsSourceValue;
-  let valueFn;
-  if (typeof options === "function") {
-    // Take the single function argument as the valueFn
-    valueFn = options;
-  } else {
-    deep = options.deep;
-    description = options.description;
-    inverseKeyFn = options.inverseKey;
-    keyFn = options.key;
-    needsSourceValue = options.needsSourceValue;
-    valueFn = options.value;
-  }
-
-  deep ??= false;
-  description ??= "key/value map";
-  // @ts-ignore
-  inverseKeyFn ??= valueFn?.inverseKey;
-  // @ts-ignore
-  keyFn ??= valueFn?.key;
-  needsSourceValue ??= true;
-
-  if ((keyFn && !inverseKeyFn) || (!keyFn && inverseKeyFn)) {
-    throw new TypeError(
-      `map: You must specify both key and inverseKey functions, or neither.`
-    );
-  }
-
-  /**
-   * @type {import("../../index.ts").TreeTransform}
-   */
-  return function map(treelike) {
-    if (!treelike) {
-      const error = new TypeError(`map: The tree to map isn't defined.`);
-      /** @type {any} */ (error).position = 0;
-      throw error;
-    }
-
-    const tree = Tree.from(treelike, { deep });
-
-    // 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
-    // the original tree's parent.
-    const transformed = Object.create(tree);
-
-    transformed.description = description;
-
-    if (keyFn || valueFn) {
-      transformed.get = async (resultKey) => {
-        // Step 1: Map the result key to the source key.
-        const sourceKey = (await inverseKeyFn?.(resultKey, tree)) ?? resultKey;
-
-        if (sourceKey === undefined) {
-          // No source key means no value.
-          return undefined;
-        }
-
-        // Step 2: Get the source value.
-        let sourceValue;
-        if (needsSourceValue) {
-          // Normal case: get the value from the source tree.
-          sourceValue = await tree.get(sourceKey);
-        } else if (deep && trailingSlash.has(sourceKey)) {
-          // Only get the source value if it's expected to be a subtree.
-          sourceValue = tree;
-        }
-
-        // Step 3: Map the source value to the result value.
-        let resultValue;
-        if (needsSourceValue && sourceValue === undefined) {
-          // No source value means no result value.
-          resultValue = undefined;
-        } else if (deep && Tree.isAsyncTree(sourceValue)) {
-          // Map a subtree.
-          resultValue = map(sourceValue);
-        } else if (valueFn) {
-          // Map a single value.
-          resultValue = await valueFn(sourceValue, sourceKey, tree);
-        } else {
-          // Return source value as is.
-          resultValue = sourceValue;
-        }
-
-        return resultValue;
-      };
-    }
-
-    if (keyFn) {
-      transformed.keys = async () => {
-        // 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) =>
-            // Deep maps leave source keys for subtrees alone
-            deep && trailingSlash.has(sourceKey)
-              ? sourceKey
-              : await keyFn(sourceKey, tree)
-          )
-        );
-        // Filter out any cases where the keyFn returned undefined.
-        const resultKeys = mapped.filter((key) => key !== undefined);
-        return resultKeys;
-      };
-    }
-
-    return transformed;
-  };
-}