@weborigami/async-tree 0.3.0 → 0.3.2

package/index.ts

@@ -46,6 +46,7 @@ export type Treelike =
 export type TreeMapOptions = {
   deep?: boolean;
   description?: string;
+  extension?: string;
   needsSourceValue?: boolean;
   inverseKey?: KeyFn;
   key?: KeyFn;

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
+  "dependencies": {
+    "@weborigami/types": "0.3.2"
+  },
   "devDependencies": {
     "@types/node": "22.13.13",
+    "puppeteer": "24.6.1",
     "typescript": "5.8.2"
   },
-  "dependencies": {
-    "@weborigami/types": "0.3.0"
-  },
   "scripts": {
+    "headlessTest": "node test/browser/headlessTest.js",
     "test": "node --test --test-reporter=spec",
     "typecheck": "tsc"
   }

package/scripts/headlessTest.js

@@ -0,0 +1,26 @@
+import puppeteer from "puppeteer";
+
+let failed = false;
+
+const browser = await puppeteer.launch({
+  args: ["--allow-file-access-from-files", "--disable-web-security"],
+});
+const page = await browser.newPage();
+
+page.on("console", (msg) => {
+  const text = msg.text();
+  if (text.includes("❌")) {
+    console.error(text);
+    failed = true;
+  }
+});
+
+// load your local index.html
+// const url = new URL("index.html", import.meta.url);
+const url = "http://localhost:5000/test/browser/index.html";
+await page.goto(url);
+await browser.close();
+if (!failed) {
+  console.log("✅ All tests passed");
+}
+process.exit(failed ? 1 : 0);

package/shared.js

@@ -15,10 +15,10 @@ export { default as addNextPrevious } from "./src/operations/addNextPrevious.js"
 export { default as cache } from "./src/operations/cache.js";
 export { default as cachedKeyFunctions } from "./src/operations/cachedKeyFunctions.js";
 export { default as concat } from "./src/operations/concat.js";
-export { default as concatTrees } from "./src/operations/concatTrees.js";
 export { default as deepMerge } from "./src/operations/deepMerge.js";
 export { default as deepReverse } from "./src/operations/deepReverse.js";
 export { default as deepTake } from "./src/operations/deepTake.js";
+export { default as deepText } from "./src/operations/deepText.js";
 export { default as deepValues } from "./src/operations/deepValues.js";
 export { default as deepValuesIterator } from "./src/operations/deepValuesIterator.js";
 export { default as extensionKeyFunctions } from "./src/operations/extensionKeyFunctions.js";
@@ -29,6 +29,7 @@ export { default as map } from "./src/operations/map.js";
 export { default as mask } from "./src/operations/mask.js";
 export { default as merge } from "./src/operations/merge.js";
 export { default as paginate } from "./src/operations/paginate.js";
+export { default as parseExtensions } from "./src/operations/parseExtensions.js";
 export { default as reverse } from "./src/operations/reverse.js";
 export { default as scope } from "./src/operations/scope.js";
 export { default as sort } from "./src/operations/sort.js";

package/src/drivers/ExplorableSiteTree.js

@@ -6,11 +6,17 @@ import SiteTree from "./SiteTree.js";
  * route even though such a mechanism is not built into the HTTP protocol.
  */
 export default class ExplorableSiteTree extends SiteTree {
-  constructor(...args) {
-    super(...args);
+  /**
+   * @param {string} href
+   */
+  constructor(href) {
+    super(href);
     this.serverKeysPromise = undefined;
   }
 
+  /**
+   * @returns {Promise<string[]>}
+   */
   async getServerKeys() {
     // We use a promise to ensure we only check for keys once.
     const href = new URL(".keys.json", this.href).href;
@@ -32,8 +38,6 @@ export default class ExplorableSiteTree extends SiteTree {
   /**
    * Returns the keys of the site route. For this to work, the route must have a
    * `.keys.json` file that contains a JSON array of string keys.
-   *
-   * @returns {Promise<Iterable<string>>}
    */
   async keys() {
     const serverKeys = await this.getServerKeys();

package/src/drivers/FileTree.js

@@ -91,6 +91,8 @@ export default class FileTree {
 
   /**
    * Enumerate the names of the files/subdirectories in this directory.
+   *
+   * @returns {Promise<string[]>}
    */
   async keys() {
     let entries;

package/src/drivers/MapTree.js

@@ -16,6 +16,9 @@ import { setParent } from "../utilities.js";
  */
 export default class MapTree {
   /**
+   * Constructs a new `MapTree` instance. This `iterable` parameter can be a
+   * `Map` instance, or any other iterable of key-value pairs.
+   *
    * @param {Iterable} [iterable]
    */
   constructor(iterable = []) {

package/src/operations/{concatTrees.js → deepText.js}

@@ -9,7 +9,7 @@ import concat from "./concat.js";
  * @param {TemplateStringsArray} strings
  * @param  {...any} values
  */
-export default async function concatTrees(strings, ...values) {
+export default async function deepText(strings, ...values) {
   // Convert all the values to strings
   const valueTexts = await Promise.all(
     values.map((value) =>

package/src/operations/extensionKeyFunctions.js

@@ -19,8 +19,8 @@ export default function extensionKeyFunctions(
     resultExtension = sourceExtension;
   }
 
-  checkDeprecatedExtensionWithoutDot(resultExtension);
-  checkDeprecatedExtensionWithoutDot(sourceExtension);
+  checkExtension(resultExtension);
+  checkExtension(sourceExtension);
 
   return {
     async inverseKey(resultKey, tree) {
@@ -38,7 +38,7 @@ export default function extensionKeyFunctions(
   };
 }
 
-function checkDeprecatedExtensionWithoutDot(extension) {
+function checkExtension(extension) {
   if (extension && extension !== "/" && !extension.startsWith(".")) {
     throw new RangeError(
       `The extension "${extension}" must start with a period.`

package/src/operations/map.js

@@ -1,6 +1,9 @@
 import { Tree } from "../internal.js";
 import * as trailingSlash from "../trailingSlash.js";
 import { assertIsTreelike } from "../utilities.js";
+import cachedKeyFunctions from "./cachedKeyFunctions.js";
+import extensionKeyFunctions from "./extensionKeyFunctions.js";
+import parseExtensions from "./parseExtensions.js";
 
 /**
  * Transform the keys and/or values of a tree.
@@ -115,6 +118,7 @@ export default function map(treelike, options = {}) {
 function validateOptions(options) {
   let deep;
   let description;
+  let extension;
   let inverseKeyFn;
   let keyFn;
   let needsSourceValue;
@@ -126,26 +130,51 @@ function validateOptions(options) {
   } else {
     deep = options.deep;
     description = options.description;
+    extension = options.extension;
     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)) {
+  if (extension && (keyFn || inverseKeyFn)) {
     throw new TypeError(
-      `map: You must specify both key and inverseKey functions, or neither.`
+      `map: You can't specify extensions and also a key or inverseKey function`
     );
   }
 
+  if (extension) {
+    // Use the extension mapping to generate key and inverseKey functions
+    const parsed = parseExtensions(extension);
+    const keyFns = extensionKeyFunctions(
+      parsed.sourceExtension,
+      parsed.resultExtension
+    );
+    keyFn = keyFns.key;
+    inverseKeyFn = keyFns.inverseKey;
+  } else {
+    // If key or inverseKey weren't specified, look for sidecar functions
+    inverseKeyFn ??= valueFn?.inverseKey;
+    keyFn ??= valueFn?.key;
+
+    if (!keyFn && inverseKeyFn) {
+      throw new TypeError(
+        `map: You can't specify an inverseKey function without a key function`
+      );
+    }
+
+    if (keyFn && !inverseKeyFn) {
+      // Only keyFn was provided, so we need to generate the inverseKeyFn
+      const keyFns = cachedKeyFunctions(keyFn, deep);
+      keyFn = keyFns.key;
+      inverseKeyFn = keyFns.inverseKey;
+    }
+  }
+
+  deep ??= false;
+  description ??= "key/value map";
+  needsSourceValue ??= true;
+
   return {
     deep,
     description,

package/src/operations/parseExtensions.js

@@ -0,0 +1,44 @@
+/**
+ * Given a string specifying an extension or a mapping of one extension to another,
+ * return the source and result extensions.
+ *
+ * Syntax:
+ *   .foo           source and result extension are the same
+ *   .foo→.bar      Unicode Rightwards Arrow
+ *   .foo→          Unicode Rightwards Arrow, no result extension
+ *   →.bar          Unicode Rightwards Arrow, no source extension
+ *   .foo->.bar     hyphen and greater-than sign
+ *
+ * @param {string} specifier
+ */
+export default function parseExtensions(specifier) {
+  const lowercase = specifier?.toLowerCase() ?? "";
+  const extensionRegex =
+    /^((?<sourceExtension>\/|\.\S*)?\s*(→|->)\s*(?<resultExtension>\/|\.\S*)?)|(?<extension>\/|\.\S*)$/;
+  const match = lowercase.match(extensionRegex);
+  if (!match) {
+    throw new Error(`Invalid file extension specifier "${specifier}".`);
+  }
+
+  // @ts-ignore
+  let { extension, resultExtension, sourceExtension } = match.groups;
+  if (extension) {
+    // foo
+    return {
+      resultExtension: extension,
+      sourceExtension: extension,
+    };
+  } else {
+    // foo→bar
+
+    if (resultExtension === undefined && sourceExtension === undefined) {
+      throw new Error(
+        `A file extension mapping must indicate a source or result extension: "${specifier}".`
+      );
+    }
+
+    resultExtension ??= "";
+    sourceExtension ??= "";
+    return { resultExtension, sourceExtension };
+  }
+}

package/test/browser/index.html

@@ -13,22 +13,45 @@
     </script>
     <!-- Omit FileTree.test.js, which is Node.js only -->
     <!-- Omit SiteTree.test.js, which requires mocks -->
+
+    <!-- Unclear why drivers/constantTree.test.js won't load -->
+
     <script type="module" src="../Tree.test.js"></script>
     <script type="module" src="../drivers/BrowserFileTree.test.js"></script>
+    <script type="module" src="../drivers/DeepMapTree.test.js"></script>
+    <script type="module" src="../drivers/DeepObjectTree.test.js"></script>
     <script type="module" src="../drivers/DeferredTree.test.js"></script>
     <script type="module" src="../drivers/FunctionTree.test.js"></script>
     <script type="module" src="../drivers/MapTree.test.js"></script>
     <script type="module" src="../drivers/ObjectTree.test.js"></script>
     <script type="module" src="../drivers/SetTree.test.js"></script>
+    <script type="module" src="../drivers/calendarTree.test.js"></script>
+    <script type="module" src="../operations/addNextPrevious.test.js"></script>
+    <script type="module" src="../operations/cache.test.js"></script>
     <script type="module" src="../operations/cache.test.js"></script>
-    <script type="module" src="../operations/merge.test.js"></script>
-    <script type="module" src="../operations/deepMerge.test.js"></script>
     <script type="module" src="../operations/cachedKeyFunctions.test.js"></script>
-    <script
-      type="module"
-      src="../operations/keyFunctionsForExtensions.test.js"
-    ></script>
+    <script type="module" src="../operations/concat.test.js"></script>
+    <script type="module" src="../operations/deepMerge.test.js"></script>
+    <script type="module" src="../operations/deepReverse.test.js"></script>
+    <script type="module" src="../operations/deepTake.test.js"></script>
+    <script type="module" src="../operations/deepText.test.js"></script>
+    <script type="module" src="../operations/deepValues.test.js"></script>
+    <script type="module" src="../operations/deepValuesIterator.test.js"></script>
+    <script type="module" src="../operations/extensionKeyFunctions.test.js"></script>
+    <script type="module" src="../operations/filter.test.js"></script>
+    <script type="module" src="../operations/globKeys.test.js"></script>
+    <script type="module" src="../operations/group.test.js"></script>
+    <script type="module" src="../operations/invokeFunctions.test.js"></script>
     <script type="module" src="../operations/map.test.js"></script>
+    <script type="module" src="../operations/mask.test.js"></script>
+    <script type="module" src="../operations/merge.test.js"></script>
+    <script type="module" src="../operations/paginate.test.js"></script>
+    <script type="module" src="../operations/parseExtensions.test.js"></script>
+    <script type="module" src="../operations/regExpKeys.test.js"></script>
+    <script type="module" src="../operations/reverse.test.js"></script>
+    <script type="module" src="../operations/scope.test.js"></script>
+    <script type="module" src="../operations/sort.test.js"></script>
+    <script type="module" src="../operations/take.test.js"></script>
     <script type="module" src="../utilities.test.js"></script>
   </head>
   <body></body>

package/test/browser/testRunner.js

@@ -25,7 +25,8 @@ export async function describe(name, fn) {
     const name = result.name;
     const message = result.result === "fail" ? `: ${result.message}` : "";
     const skipped = result.result === "skipped" ? " [skipped]" : "";
-    console.log(`${marker} ${name}${message}${skipped}`);
+    const fn = result.result === "fail" ? "error" : "log";
+    console[fn](`${marker} ${name}${message}${skipped}`);
   }
   console.groupEnd();
 }

package/test/operations/addNextPrevious.test.js

@@ -39,16 +39,16 @@ describe("addNextPrevious", () => {
     assert.deepEqual(result, [
       {
         value: "Alice",
-        nextKey: 1,
+        nextKey: "1",
       },
       {
         value: "Bob",
-        nextKey: 2,
-        previousKey: 0,
+        nextKey: "2",
+        previousKey: "0",
       },
       {
         value: "Carol",
-        previousKey: 1,
+        previousKey: "1",
       },
     ]);
   });

package/test/operations/{concatTrees.test.js → deepText.test.js}

@@ -1,12 +1,12 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import concatTrees from "../../src/operations/concatTrees.js";
+import deepText from "../../src/operations/deepText.js";
 
-describe("concatTrees", () => {
+describe("deepText", () => {
   test("joins strings and values together", async () => {
     const array = [1, 2, 3];
     const object = { person1: "Alice", person2: "Bob" };
-    const result = await concatTrees`a ${array} b ${object} c`;
+    const result = await deepText`a ${array} b ${object} c`;
     assert.equal(result, "a 123 b AliceBob c");
   });
 });

package/test/operations/map.test.js

@@ -68,6 +68,20 @@ describe("map", () => {
     });
   });
 
+  test("if only given a key, will generate an inverseKey", async () => {
+    const tree = {
+      a: "letter a",
+      b: "letter b",
+    };
+    const underscoreKeys = map(tree, {
+      key: addUnderscore,
+    });
+    assert.deepEqual(await Tree.plain(underscoreKeys), {
+      _a: "letter a",
+      _b: "letter b",
+    });
+  });
+
   test("maps keys and values", async () => {
     const tree = {
       a: "letter a",
@@ -102,7 +116,7 @@ describe("map", () => {
     });
   });
 
-  test("value can provide a default key and inverse key functions", async () => {
+  test("value can provide a default key and inverse key sidecar functions", async () => {
     const uppercase = (s) => s.toUpperCase();
     uppercase.key = addUnderscore;
     uppercase.inverseKey = removeUnderscore;
@@ -177,6 +191,40 @@ describe("map", () => {
     });
   });
 
+  test("can change a key's extension", async () => {
+    const treelike = {
+      "file1.lower": "will be mapped",
+      file2: "won't be mapped",
+      "file3.foo": "won't be mapped",
+    };
+    const fixture = await map(treelike, {
+      extension: ".lower->.upper",
+      value: (sourceValue) => sourceValue.toUpperCase(),
+    });
+    assert.deepEqual(await Tree.plain(fixture), {
+      "file1.upper": "WILL BE MAPPED",
+    });
+  });
+
+  test("can manipulate extensions deeply", async () => {
+    const treelike = {
+      "file1.txt": 1,
+      more: {
+        "file2.txt": 2,
+      },
+    };
+    const fixture = await map(treelike, {
+      deep: true,
+      extension: ".txt->",
+    });
+    assert.deepEqual(await Tree.plain(fixture), {
+      file1: 1,
+      more: {
+        file2: 2,
+      },
+    });
+  });
+
   test("needsSourceValue can be set to false in cases where the value isn't necessary", async () => {
     let flag = false;
     const tree = new FunctionTree(() => {

package/test/operations/parseExtensions.test.js

@@ -0,0 +1,61 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import parseExtensions from "../../src/operations/parseExtensions.js";
+
+describe("keyMapsForExtensions", () => {
+  test("source and result extension are the same", async () => {
+    assert.deepEqual(parseExtensions(".foo"), {
+      sourceExtension: ".foo",
+      resultExtension: ".foo",
+    });
+  });
+
+  test("change extension", async () => {
+    assert.deepEqual(parseExtensions(".foo->.bar"), {
+      sourceExtension: ".foo",
+      resultExtension: ".bar",
+    });
+    // with Unicode Rightwards Arrow
+    assert.deepEqual(parseExtensions(".foo→.bar"), {
+      sourceExtension: ".foo",
+      resultExtension: ".bar",
+    });
+  });
+
+  test("add extension", async () => {
+    assert.deepEqual(parseExtensions("->.foo"), {
+      sourceExtension: "",
+      resultExtension: ".foo",
+    });
+    assert.deepEqual(parseExtensions("→.foo"), {
+      sourceExtension: "",
+      resultExtension: ".foo",
+    });
+  });
+
+  test("remove extension", async () => {
+    assert.deepEqual(parseExtensions(".foo->"), {
+      sourceExtension: ".foo",
+      resultExtension: "",
+    });
+    assert.deepEqual(parseExtensions(".foo→"), {
+      sourceExtension: ".foo",
+      resultExtension: "",
+    });
+  });
+
+  test("slash is a valid extension", async () => {
+    assert.deepEqual(parseExtensions("/"), {
+      sourceExtension: "/",
+      resultExtension: "/",
+    });
+    assert.deepEqual(parseExtensions(".foo->/"), {
+      sourceExtension: ".foo",
+      resultExtension: "/",
+    });
+    assert.deepEqual(parseExtensions("/->.bar"), {
+      sourceExtension: "/",
+      resultExtension: ".bar",
+    });
+  });
+});