@weborigami/async-tree 0.6.17 → 0.7.0-beta.1

package/index.ts

@@ -27,7 +27,6 @@ export type MapExtensionOptions = {
   deep?: boolean;
   description?: string;
   extension?: string;
-  needsSourceValue?: boolean;
   value?: ValueKeyFn;
 };
 
@@ -46,6 +45,7 @@ export type MapOptions = {
   inverseKey?: KeyFn;
   key?: ValueKeyFn;
   keyNeedsSourceValue?: boolean;
+  needsSourceValue?: boolean;
   value?: ValueKeyFn;
 };
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.6.17",
+  "version": "0.7.0-beta.1",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
   "browser": "./browser.js",
   "types": "./index.ts",
   "devDependencies": {
-    "@types/node": "25.3.2",
-    "puppeteer": "24.37.5",
-    "typescript": "5.9.3"
+    "@types/node": "25.9.1",
+    "puppeteer": "25.1.0",
+    "typescript": "6.0.3"
   },
   "scripts": {
     "headlessTest": "node scripts/headlessTest.js",

package/shared.js

@@ -20,6 +20,7 @@ export * as trailingSlash from "./src/trailingSlash.js";
 export { default as TraverseError } from "./src/TraverseError.js";
 export * as Tree from "./src/Tree.js";
 export * as args from "./src/utilities/args.js";
+export { default as assignPropertyDescriptors } from "./src/utilities/assignPropertyDescriptors.js";
 export { default as box } from "./src/utilities/box.js";
 export { default as castArraylike } from "./src/utilities/castArraylike.js";
 export { default as getParent } from "./src/utilities/getParent.js";
@@ -38,61 +39,3 @@ export { default as toPlainValue } from "./src/utilities/toPlainValue.js";
 export { default as toString } from "./src/utilities/toString.js";
 
 export { ExplorableSiteMap, FileMap, FunctionMap, ObjectMap, SetMap, SiteMap };
-
-export class DeepObjectMap extends ObjectMap {
-  constructor(object) {
-    super(object, { deep: true });
-    console.warn("DeepObjectMap is deprecated. Please use ObjectMap instead.");
-  }
-}
-
-export class ObjectTree extends ObjectMap {
-  constructor(...args) {
-    super(...args);
-    console.warn("ObjectTree is deprecated. Please use ObjectMap instead.");
-  }
-}
-
-export class DeepObjectTree extends ObjectMap {
-  constructor(object) {
-    super(object, { deep: true });
-    console.warn("DeepObjectTree is deprecated. Please use ObjectMap instead.");
-  }
-}
-
-export class ExplorableSiteTree extends ExplorableSiteMap {
-  constructor(href) {
-    super(href);
-    console.warn(
-      "ExplorableSiteTree is deprecated. Please use ExplorableSiteMap instead.",
-    );
-  }
-}
-
-export class FileTree extends FileMap {
-  constructor(...args) {
-    super(...args);
-    console.warn("FileTree is deprecated. Please use FileMap instead.");
-  }
-}
-
-export class FunctionTree extends FunctionMap {
-  constructor(...args) {
-    super(...args);
-    console.warn("FunctionTree is deprecated. Please use FunctionMap instead.");
-  }
-}
-
-export class SetTree extends SetMap {
-  constructor(set) {
-    super(set);
-    console.warn("SetTree is deprecated. Please use SetMap instead.");
-  }
-}
-
-export class SiteTree extends SiteMap {
-  constructor(...args) {
-    super(...args);
-    console.warn("SiteTree is deprecated. Please use SiteMap instead.");
-  }
-}

package/src/Tree.js

@@ -30,23 +30,18 @@ export { default as flat } from "./operations/flat.js";
 export { default as forEach } from "./operations/forEach.js";
 export { default as from } from "./operations/from.js";
 export { default as globKeys } from "./operations/globKeys.js";
-export { default as group } from "./operations/group.js";
 export { default as groupBy } from "./operations/groupBy.js";
 export { default as has } from "./operations/has.js";
 export { default as indent } from "./operations/indent.js";
 export { default as inflatePaths } from "./operations/inflatePaths.js";
 export { default as inners } from "./operations/inners.js";
 export { default as invokeFunctions } from "./operations/invokeFunctions.js";
-export { default as isAsyncMutableTree } from "./operations/isAsyncMutableTree.js";
-export { default as isAsyncTree } from "./operations/isAsyncTree.js";
 export { default as isMap } from "./operations/isMap.js";
 export { default as isMaplike } from "./operations/isMaplike.js";
 export { default as isReadOnlyMap } from "./operations/isReadOnlyMap.js";
 export { default as isTraversable } from "./operations/isTraversable.js";
-export { default as isTreelike } from "./operations/isTreelike.js";
 export { default as json } from "./operations/json.js";
 export { default as keys } from "./operations/keys.js";
-export { default as length } from "./operations/length.js";
 export { default as map } from "./operations/map.js";
 export { default as mapExtension } from "./operations/mapExtension.js";
 export { default as mapReduce } from "./operations/mapReduce.js";

package/src/drivers/ObjectMap.js

@@ -20,7 +20,7 @@ export default class ObjectMap extends SyncMap {
     // objects such as Node's `Module` class for representing an ES module.
     if (typeof object !== "object" || object === null) {
       throw new TypeError(
-        `${this.constructor.name}: Expected an object or array.`
+        `${this.constructor.name}: Expected an object or array.`,
       );
     }
     this.object = object;
@@ -38,6 +38,13 @@ export default class ObjectMap extends SyncMap {
   }
 
   get(key) {
+    if (key == null) {
+      // Reject nullish key
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`,
+      );
+    }
+
     // Does the object have the key with or without a trailing slash?
     const existingKey = findExistingKey(this.object, key);
     if (existingKey === null) {
@@ -111,7 +118,8 @@ export default class ObjectMap extends SyncMap {
           ? name
           : trailingSlash.toggle(
               name,
-              descriptor.value !== undefined && this.isSubtree(descriptor.value)
+              descriptor.value !== undefined &&
+                this.isSubtree(descriptor.value),
             );
         result.add(key);
       }

package/src/drivers/SetMap.js

@@ -13,4 +13,15 @@ export default class SetMap extends SyncMap {
     const entries = Array.from(set).map((value, index) => [index, value]);
     super(entries);
   }
+
+  get(key) {
+    if (key == null) {
+      // Reject nullish key
+      throw new ReferenceError(
+        `${this.constructor.name}: Cannot get a null or undefined key.`,
+      );
+    }
+
+    return super.get(key);
+  }
 }

package/src/drivers/SyncMap.js

@@ -128,7 +128,7 @@ export default class SyncMap extends Map {
    */
   get(key) {
     let value = super.get.call(this._self, key);
-    if (value === undefined) {
+    if (value === undefined && this.trailingSlashKeys) {
       // Try alternate key with trailing slash added or removed
       value = super.get.call(this._self, trailingSlash.toggle(key));
     }

package/src/operations/addNextPrevious.js

@@ -10,7 +10,7 @@ import keys from "./keys.js";
  */
 export default async function addNextPrevious(maplike) {
   const source = await args.map(maplike, "Tree.addNextPrevious");
-  let sourceKeys;
+  const sourceKeys = await keys(source);
 
   return Object.assign(new AsyncMap(), {
     async get(key) {
@@ -29,7 +29,6 @@ export default async function addNextPrevious(maplike) {
       }
 
       // Find the index of the current key
-      sourceKeys ??= await keys(source);
       const index = sourceKeys.indexOf(key);
       if (index >= 0) {
         // Extend result with nextKey/previousKey properties.
@@ -47,7 +46,6 @@ export default async function addNextPrevious(maplike) {
     },
 
     async *keys() {
-      sourceKeys ??= await keys(source);
       yield* sourceKeys;
     },
 

package/src/operations/cache.js

@@ -67,6 +67,11 @@ export default async function treeCache(sourceMaplike, cacheMaplike) {
     },
 
     async *keys() {
+      // REVIEW: Saving our own copy of the source keys can create issues when
+      // this operation is applied in an Origami site. Because this keys() call
+      // happens outside of the language package's system cache, the system
+      // cache may not detect a dependency. If the underlying keys change, the
+      // keys obtained here won't be invalidated.
       sourceKeys ??= await keys(source);
       yield* sourceKeys;
     },

package/src/operations/combine.js

@@ -12,7 +12,7 @@ import keys from "./keys.js";
  * that were not `undefined`. If all results were `undefined`, the overall
  * result is itself `undefined`.
  *
- * @typedef {import("@weborigami/async-tree").Maplike} Maplike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
  * @param {Maplike} maplike1
  * @param {Maplike} maplike2

package/src/operations/deepEntriesIterator.js

@@ -2,6 +2,7 @@ import * as args from "../utilities/args.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import isMap from "./isMap.js";
 import isMaplike from "./isMaplike.js";
+
 /**
  * Return an iterator that yields all entries in a tree, including nested trees.
  *

package/src/operations/flat.js

@@ -17,7 +17,7 @@ import deepEntriesIterator from "./deepEntriesIterator.js";
  * @param {number} [depth] The maximum depth to flatten
  */
 export default async function flat(maplike, depth = 1) {
-  const map = await args.map(maplike, "Tree.flat", { deep: true });
+  const map = await args.map(maplike, "Tree.flat");
 
   let index = 0;
   let onlyNumericKeys = true;

package/src/operations/invokeFunctions.js

@@ -7,7 +7,7 @@ export default async function invokeFunctions(maplike) {
     deep: true,
   });
 
-  return Object.assign(new AsyncMap(), {
+  const result = Object.assign(new AsyncMap(), {
     description: "invokeFunctions",
 
     async get(key) {
@@ -30,4 +30,18 @@ export default async function invokeFunctions(maplike) {
 
     trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
   });
+
+  if (!(/** @type {any} */ (source).readOnly)) {
+    Object.assign(result, {
+      delete(key) {
+        return source.delete(key);
+      },
+
+      set(key, value) {
+        return source.set(key, value);
+      },
+    });
+  }
+
+  return result;
 }

package/src/operations/map.js

@@ -5,10 +5,8 @@ import isPlainObject from "../utilities/isPlainObject.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import toFunction from "../utilities/toFunction.js";
 import cachedKeyFunctions from "./cachedKeyFunctions.js";
-import extensionKeyFunctions from "./extensionKeyFunctions.js";
 import isMap from "./isMap.js";
 import keys from "./keys.js";
-import parseExtensions from "./parseExtensions.js";
 
 /**
  * Transform the keys and/or values of a tree.
@@ -147,7 +145,6 @@ function validateOption(options, key) {
 function validateOptions(options) {
   let deep;
   let description;
-  let extension;
   let inverseKeyFn;
   let keyFn;
   let keyNeedsSourceValue;
@@ -162,7 +159,6 @@ function validateOptions(options) {
 
     // Validate individual options
     deep = validateOption(options, "deep");
-    extension = validateOption(options, "extension");
     inverseKeyFn = validateOption(options, "inverseKey");
     keyFn = validateOption(options, "key");
     keyNeedsSourceValue = validateOption(options, "keyNeedsSourceValue");
@@ -196,49 +192,21 @@ function validateOptions(options) {
     throw error;
   }
 
-  if (extension && !options._noExtensionWarning) {
-    console.warn(
-      `Tree.map: The 'extension' option for Tree.map() is deprecated and will be removed in a future release. Use Tree.mapExtension() instead.`,
-    );
-  }
-  if (extension && (keyFn || inverseKeyFn)) {
-    throw new TypeError(
-      `Tree.map: You can't specify extensions and also a key or inverseKey function`,
-    );
-  }
-  if (extension && keyNeedsSourceValue === true) {
+  // If key or inverseKey weren't specified, look for sidecar functions
+  inverseKeyFn ??= valueFn?.inverseKey;
+  keyFn ??= valueFn?.key;
+
+  if (!keyFn && inverseKeyFn) {
     throw new TypeError(
-      `Tree.map: using extensions sets keyNeedsSourceValue to be false`,
+      `Tree.map: You can't specify an inverseKey function without a key function`,
     );
   }
 
-  if (extension) {
-    // Use the extension mapping to generate key and inverseKey functions
-    const parsed = parseExtensions(extension);
-    const keyFns = extensionKeyFunctions(
-      parsed.sourceExtension,
-      parsed.resultExtension,
-    );
+  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;
-    keyNeedsSourceValue = false;
-  } else {
-    // If key or inverseKey weren't specified, look for sidecar functions
-    inverseKeyFn ??= valueFn?.inverseKey;
-    keyFn ??= valueFn?.key;
-
-    if (!keyFn && inverseKeyFn) {
-      throw new TypeError(
-        `Tree.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;
-    }
   }
 
   if (!valueFn && !keyFn) {

package/src/operations/mapExtension.js

@@ -1,6 +1,8 @@
 import isPlainObject from "../utilities/isPlainObject.js";
 import isUnpackable from "../utilities/isUnpackable.js";
+import extensionKeyFunctions from "./extensionKeyFunctions.js";
 import map from "./map.js";
+import parseExtensions from "./parseExtensions.js";
 
 /**
  * @typedef {import("../../index.ts").AsyncMap} AsyncMap
@@ -44,14 +46,17 @@ import map from "./map.js";
  * @returns {Promise<AsyncMap>}
  */
 export default async function mapExtension(maplike, arg2, arg3) {
-  /** @type {MapExtensionOptions} */
-  // @ts-ignore
-  let options = { _noExtensionWarning: true };
+  let extension;
+
+  /** @type {import("../../index.ts").MapOptions} */
+  let options = { keyNeedsSourceValue: false };
+  let optionsArg;
   if (arg3 === undefined) {
     if (typeof arg2 === "string") {
-      options.extension = arg2;
+      extension = arg2;
     } else if (isPlainObject(arg2)) {
-      Object.assign(options, arg2);
+      extension = arg2.extension;
+      optionsArg = arg2;
     } else {
       throw new TypeError(
         "Tree.mapExtension: Expected a string or options object for the second argument.",
@@ -63,14 +68,14 @@ export default async function mapExtension(maplike, arg2, arg3) {
         "Tree.mapExtension: Expected a string for the second argument.",
       );
     }
-    options.extension = arg2;
+    extension = arg2;
     if (isUnpackable(arg3)) {
       arg3 = await arg3.unpack();
     }
     if (typeof arg3 === "function") {
       options.value = arg3;
     } else if (isPlainObject(arg3)) {
-      Object.assign(options, arg3);
+      optionsArg = arg3;
     } else {
       throw new TypeError(
         "Tree.mapExtension: Expected a function or options object for the third argument.",
@@ -78,9 +83,34 @@ export default async function mapExtension(maplike, arg2, arg3) {
     }
   }
 
+  if (!extension) {
+    throw new TypeError(
+      "Tree.mapExtension: An extension mapping string is required.",
+    );
+  }
+
+  if (optionsArg?.deep !== undefined) {
+    options.deep = optionsArg.deep;
+  }
+  if (optionsArg?.description !== undefined) {
+    options.description = optionsArg.description;
+  }
+  if (optionsArg?.value !== undefined) {
+    options.value = optionsArg.value;
+  }
+
   if (!options.description) {
-    options.description = `mapExtension ${options.extension}`;
+    options.description = `mapExtension ${extension}`;
   }
 
+  // Use the extension mapping to generate key and inverseKey functions
+  const parsed = parseExtensions(extension);
+  const keyFns = extensionKeyFunctions(
+    parsed.sourceExtension,
+    parsed.resultExtension,
+  );
+  options.key = keyFns.key;
+  options.inverseKey = keyFns.inverseKey;
+
   return map(maplike, options);
 }

package/src/operations/merge.js

@@ -1,5 +1,6 @@
 import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
+import assignPropertyDescriptors from "../utilities/assignPropertyDescriptors.js";
 import isPlainObject from "../utilities/isPlainObject.js";
 import isUnpackable from "../utilities/isUnpackable.js";
 import from from "./from.js";
@@ -42,7 +43,7 @@ export default async function merge(...treelikes) {
 
   // If all arguments are plain objects, return a plain object.
   if (unpacked.every((source) => !isMap(source) && isPlainObject(source))) {
-    return unpacked.reduce((acc, obj) => ({ ...acc, ...obj }), {});
+    return assignPropertyDescriptors({}, ...unpacked);
   }
 
   const sources = unpacked.map((maplike) => from(maplike));

package/src/operations/root.js

@@ -1,5 +1,5 @@
 import * as symbols from "../symbols.js";
-import * as args from "../utilities/args.js";
+import from from "./from.js";
 
 /**
  * Walk up the `parent` chain to find the root of the tree.
@@ -8,9 +8,9 @@ import * as args from "../utilities/args.js";
  *
  * @param {Maplike} maplike
  */
-export default async function root(maplike) {
+export default function root(maplike) {
   /** @type {any} */
-  let current = await args.map(maplike, "Tree.root");
+  let current = from(maplike);
   while (current.parent || current[symbols.parent]) {
     current = current.parent || current[symbols.parent];
   }

package/src/operations/traverseOrThrow.js

@@ -42,8 +42,12 @@ export default async function traverseOrThrow(maplike, ...keys) {
       if (typeof (/** @type {any} */ (value).unpack) === "function") {
         value = await value.unpack();
       } else {
+        const type =
+          typeof value === "string" || value instanceof String
+            ? "string"
+            : "binary";
         throw new TraverseError(
-          "A path hit binary file data that can't be unpacked.",
+          `A path hit ${type} data that can't be unpacked.`,
           {
             head: maplike,
             lastValue,
@@ -60,8 +64,9 @@ export default async function traverseOrThrow(maplike, ...keys) {
       // We'll take as many keys as the function's length, but at least one.
       let fnKeyCount = Math.max(fn.length, 1);
       const args = remainingKeys.splice(0, fnKeyCount);
+      const normalized = args.map((key) => trailingSlash.remove(key));
       key = null;
-      value = await fn(...args);
+      value = await fn(...normalized);
     } else {
       // Cast value to a map.
       const map = from(value);

package/src/utilities/args.js

@@ -69,7 +69,7 @@ export async function map(arg, operation, options = {}) {
   } catch (/** @type {any} */ error) {
     let message = error.message ?? error;
     message = `${operation}: ${message}`;
-    const newError = new error.constructor(message);
+    const newError = new TypeError(message);
     /** @type {any} */ (newError).position = position;
     throw newError;
   }

package/src/utilities/assignPropertyDescriptors.js

@@ -0,0 +1,26 @@
+/**
+ * This is an analogue of Object.assign that destructively copies properties to
+ * a target object -- but avoids invoking property getters. Instead, it copies
+ * property descriptors over to the target object.
+ *
+ * @param {any} target
+ * @param  {...any} sources
+ */
+export default function assignPropertyDescriptors(target, ...sources) {
+  for (const source of sources) {
+    if (!source) {
+      continue;
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(source);
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (descriptor.value !== undefined) {
+        // Simple value, copy it
+        target[key] = descriptor.value;
+      } else {
+        // Getter and/or setter, copy the descriptor
+        Object.defineProperty(target, key, descriptor);
+      }
+    }
+  }
+  return target;
+}

package/src/utilities/castArraylike.js

@@ -41,7 +41,10 @@ export default function castArraylike(map, createFn = Object.fromEntries) {
     // result. By default this will create a plain object from the entries.
     const normalizedMap = new Map();
     for (const [key, value] of map.entries()) {
-      const normalized = trailingSlash.remove(key);
+      // Normalize the key by stripping trailing slashes, but only if there
+      // aren't multiple keys that only differ by trailing slashes.
+      const normalize = !map.has(trailingSlash.toggle(key));
+      const normalized = normalize ? trailingSlash.remove(key) : key;
       normalizedMap.set(normalized, value);
     }
     return createFn(normalizedMap);

package/test/drivers/SyncMap.test.js

@@ -121,6 +121,7 @@ describe("SyncMap", () => {
       ["a", 1],
       ["b/", subMap],
     ]);
+    map.trailingSlashKeys = true;
     assert.strictEqual(map.get("a"), 1);
 
     const b = map.get("b/");

package/test/operations/{length.test.js → size.test.js}

@@ -1,15 +1,15 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import length from "../../src/operations/length.js";
+import size from "../../src/operations/size.js";
 
-describe("length", () => {
+describe("size", () => {
   test("returns the number of keys in the tree", async () => {
     const obj = {
       a: 1,
       b: 2,
       c: 3,
     };
-    const result = await length(obj);
+    const result = await size(obj);
     assert.equal(result, 3);
   });
 });

package/test/utilities/castArrayLike.test.js

@@ -50,4 +50,36 @@ describe("castArraylike", () => {
       3: "c",
     });
   });
+
+  test("strips trailing slashes if map only has one form of the key", () => {
+    const map = new /** @type {any} */ (Map)([
+      ["a/", 1],
+      ["b", 2],
+      ["c/", 3],
+    ]);
+    const result = castArraylike(map);
+    assert.deepEqual(result, {
+      a: 1,
+      b: 2,
+      c: 3,
+    });
+  });
+
+  test.only("preserves trailing slashes if map has both forms of the key", () => {
+    const map = new /** @type {any} */ (Map)([
+      ["a/", 1],
+      ["a", 2],
+      ["b", 3],
+      ["c/", 4],
+      ["c", 5],
+    ]);
+    const result = castArraylike(map);
+    assert.deepEqual(result, {
+      "a/": 1,
+      a: 2,
+      b: 3,
+      "c/": 4,
+      c: 5,
+    });
+  });
 });

package/src/operations/group.js

@@ -1,6 +0,0 @@
-import groupBy from "./groupBy.js";
-
-export default async function group(maplike, groupKeyFn) {
-  console.warn("Tree.group() is deprecated. Use Tree.groupBy() instead.");
-  return groupBy(maplike, groupKeyFn);
-}

package/src/operations/isAsyncMutableTree.js

@@ -1,8 +0,0 @@
-import isReadOnlyMap from "./isReadOnlyMap.js";
-
-export default function isAsyncMutableTree(treelike) {
-  console.warn(
-    "Tree.isAsyncMutableTree() is deprecated, use Tree.isReadOnlyMap() instead, which returns the inverse."
-  );
-  return !isReadOnlyMap(treelike);
-}

package/src/operations/isAsyncTree.js

@@ -1,6 +0,0 @@
-import isMap from "./isMap.js";
-
-export default function isAsyncTree(treelike) {
-  console.warn("Tree.isAsyncTree() is deprecated, use Tree.isMap() instead.");
-  return isMap(treelike);
-}

package/src/operations/isTreelike.js

@@ -1,8 +0,0 @@
-import isMaplike from "./isMaplike.js";
-
-export default function isTreelike(treelike) {
-  console.warn(
-    "Tree.isTreelike() is deprecated, use Tree.isMaplike() instead."
-  );
-  return isMaplike(treelike);
-}

package/src/operations/length.js

@@ -1,16 +0,0 @@
-import * as args from "../utilities/args.js";
-import keys from "./keys.js";
-
-/**
- * Return the number of keys in the tree.
- *
- * @typedef {import("../../index.ts").Maplike} Maplike
- *
- * @param {Maplike} maplike
- */
-export default async function length(maplike) {
-  console.warn("Tree.length() is deprecated. Use Tree.size() instead.");
-  const tree = await args.map(maplike, "Tree.length");
-  const treeKeys = await keys(tree);
-  return treeKeys.length;
-}