@weborigami/async-tree 0.5.8 → 0.6.1

package/src/operations/addNextPrevious.js

@@ -1,57 +1,56 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import entries from "./entries.js";
-import isTreelike from "./isTreelike.js";
-import plain from "./plain.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import keys from "./keys.js";
 
 /**
- * Add nextKey/previousKey properties to values.
+ * Return a map that adds nextKey/previousKey properties to values.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").PlainObject} PlainObject
- *
- * @param {import("../../index.ts").Treelike} treelike
- * @returns {Promise<PlainObject|Array>}
+ * @param {import("../../index.ts").Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function addNextPrevious(treelike) {
-  const tree = await getTreeArgument(treelike, "addNextPrevious");
+export default async function addNextPrevious(maplike) {
+  const source = await getMapArgument(maplike, "addNextPrevious");
+  let sourceKeys;
 
-  const treeEntries = [...(await entries(tree))];
-  const keys = treeEntries.map(([key]) => key);
+  return Object.assign(new AsyncMap(), {
+    async get(key) {
+      const sourceValue = await source.get(key);
+      if (sourceValue === undefined) {
+        return undefined;
+      }
 
-  // Map to an array of [key, result] pairs, where the result includes
-  // nextKey/previousKey properties.
-  const mappedEntries = await Promise.all(
-    treeEntries.map(async ([key, value], index) => {
-      let resultValue;
-      if (value === undefined) {
-        resultValue = undefined;
-      } else if (isTreelike(value)) {
-        resultValue = await plain(value);
-      } else if (typeof value === "object") {
-        // Clone value to avoid modifying the original object
-        resultValue = { ...value };
+      const resultValue = {};
+      if (typeof sourceValue === "object") {
+        // Copy to avoid modifying the original object
+        Object.assign(resultValue, sourceValue);
       } else {
         // Take the object as the `value` property
-        resultValue = { value };
+        resultValue.value = sourceValue;
       }
 
-      if (resultValue) {
+      // 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.
-        const nextKey = keys[index + 1];
+        const nextKey = sourceKeys[index + 1];
         if (nextKey) {
           resultValue.nextKey = nextKey;
         }
-        const previousKey = keys[index - 1];
+        const previousKey = sourceKeys[index - 1];
         if (previousKey) {
           resultValue.previousKey = previousKey;
         }
       }
 
-      return [key, resultValue];
-    })
-  );
+      return resultValue;
+    },
+
+    async *keys() {
+      sourceKeys ??= await keys(source);
+      yield* sourceKeys;
+    },
 
-  return treelike instanceof Array
-    ? mappedEntries.map(([_, value]) => value)
-    : Object.fromEntries(mappedEntries);
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/assign.js

@@ -1,6 +1,6 @@
-import from from "./from.js";
-import isAsyncMutableTree from "./isAsyncMutableTree.js";
-import isAsyncTree from "./isAsyncTree.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import child from "./child.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Apply the key/values pairs from the source tree to the target tree.
@@ -9,32 +9,36 @@ import isAsyncTree from "./isAsyncTree.js";
  * subtrees, then the subtrees will be merged recursively. Otherwise, the
  * value from the source tree will overwrite the value in the target tree.
  *
- * @typedef  {import("../../index.ts").Treelike} Treelike
+ * @typedef  {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} target
- * @param {Treelike} source
+ * @param {Maplike} target
+ * @param {Maplike} source
  */
 export default async function assign(target, source) {
-  const targetTree = from(target);
-  const sourceTree = from(source);
-  if (!isAsyncMutableTree(targetTree)) {
-    throw new TypeError("Target must be a mutable asynchronous tree");
+  const targetTree = await getMapArgument(target, "assign", { position: 0 });
+  const sourceTree = await getMapArgument(source, "assign", { position: 1 });
+  if ("readOnly" in targetTree && targetTree.readOnly) {
+    throw new TypeError("assign: Target must be a read/write map");
   }
+
   // Fire off requests to update all keys, then wait for all of them to finish.
-  const keys = Array.from(await sourceTree.keys());
-  const promises = keys.map(async (key) => {
-    const sourceValue = await sourceTree.get(key);
-    if (isAsyncTree(sourceValue)) {
-      const targetValue = await targetTree.get(key);
-      if (isAsyncMutableTree(targetValue)) {
-        // Both source and target are trees; recurse.
-        await assign(targetValue, sourceValue);
-        return;
+  const promises = [];
+  for await (const key of sourceTree.keys()) {
+    const promise = (async () => {
+      const sourceValue = await sourceTree.get(key);
+      if (isMaplike(sourceValue)) {
+        // Recurse to copy subtree
+        const targetChild = await child(targetTree, key);
+        await assign(targetChild, sourceValue);
+      } else {
+        // Copy the value from the source to the target.
+        await targetTree.set(key, sourceValue);
       }
-    }
-    // Copy the value from the source to the target.
-    await /** @type {any} */ (targetTree).set(key, sourceValue);
-  });
+    })();
+    promises.push(promise);
+  }
+
   await Promise.all(promises);
+
   return targetTree;
 }

package/src/operations/cache.js

@@ -1,8 +1,10 @@
-import ObjectTree from "../drivers/ObjectTree.js";
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import from from "./from.js";
-import isAsyncMutableTree from "./isAsyncMutableTree.js";
-import isAsyncTree from "./isAsyncTree.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import SyncMap from "../drivers/SyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import child from "./child.js";
+import isMap from "./isMap.js";
+import isReadOnlyMap from "./isReadOnlyMap.js";
+import keys from "./keys.js";
 
 /**
  * Caches values from a source tree in a second cache tree. Cache source tree
@@ -10,60 +12,50 @@ import isAsyncTree from "./isAsyncTree.js";
  *
  * If no second tree is supplied, an in-memory value cache is used.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} sourceTreelike
- * @param {AsyncMutableTree} [cacheTreelike]
- * @returns {Promise}
+ * @param {Maplike} sourceMaplike
+ * @param {Maplike} [cacheMaplike]
+ * @returns {Promise<SyncMap|AsyncMap>}
  */
-export default async function treeCache(sourceTreelike, cacheTreelike) {
-  const source = await getTreeArgument(sourceTreelike, "cache", {
+export default async function treeCache(sourceMaplike, cacheMaplike) {
+  const source = await getMapArgument(sourceMaplike, "cache", {
     position: 0,
   });
 
-  /** @type {AsyncMutableTree} */
   let cache;
-  if (cacheTreelike) {
+  if (cacheMaplike) {
     cache = /** @type {any} */ (
-      await getTreeArgument(cacheTreelike, "cache", { position: 1 })
+      await getMapArgument(cacheMaplike, "cache", { position: 1 })
     );
     // @ts-ignore
-    if (!isAsyncMutableTree(cache)) {
-      throw new Error("Cache tree must define a set() method.");
+    if (isReadOnlyMap(cache)) {
+      throw new Error("cache: Cache tree can't be read-only.");
     }
   } else {
-    cache = new ObjectTree({});
+    cache = new SyncMap();
   }
 
-  let keys;
-  return {
+  let sourceKeys;
+
+  return Object.assign(new AsyncMap(), {
     description: "cache",
 
     async get(key) {
       // Check cache tree first.
       let cacheValue = await cache.get(key);
-      if (cacheValue !== undefined && !isAsyncTree(cacheValue)) {
+      if (cacheValue !== undefined && !isMap(cacheValue)) {
         // Leaf node cache hit
         return cacheValue;
       }
 
       // Cache miss or interior node cache hit.
       let value = await source.get(key);
-      if (isAsyncTree(value)) {
+      if (isMap(value)) {
         // Construct merged tree for a tree result.
         if (cacheValue === undefined) {
           // Construct new empty container in cache
-          await cache.set(key, {});
-          cacheValue = await cache.get(key);
-          if (!isAsyncTree(cacheValue)) {
-            // Coerce to tree and then save it back to the cache. This is
-            // necessary, e.g., if cache is an ObjectTree; we want the
-            // subtree to also be an ObjectTree, not a plain object.
-            cacheValue = from(cacheValue);
-            await cache.set(key, cacheValue);
-          }
+          cacheValue = await child(cache, key);
         }
         value = treeCache(value, cacheValue);
       } else if (value !== undefined) {
@@ -74,9 +66,11 @@ export default async function treeCache(sourceTreelike, cacheTreelike) {
       return value;
     },
 
-    async keys() {
-      keys ??= await source.keys();
-      return keys;
+    async *keys() {
+      sourceKeys ??= await keys(source);
+      yield* sourceKeys;
     },
-  };
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/cachedKeyFunctions.js

@@ -35,7 +35,7 @@ export default function cachedKeyFunctions(keyFn, deep = false) {
       // final match. This is O(n), but we stop as soon as we find a match,
       // and subsequent calls will benefit from the intermediate results.
       const resultKeyWithoutSlash = trailingSlash.remove(resultKey);
-      for (const sourceKey of await tree.keys()) {
+      for await (const sourceKey of tree.keys()) {
         // Skip any source keys we already know about.
         if (sourceKeyToResultKey.has(sourceKey)) {
           continue;

package/src/operations/calendar.js

@@ -0,0 +1,5 @@
+import CalendarMap from "../drivers/CalendarMap.js";
+
+export default function calendar(...args) {
+  return new CalendarMap(...args);
+}

package/src/operations/child.js

@@ -0,0 +1,35 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+import setParent from "../utilities/setParent.js";
+import isMap from "./isMap.js";
+
+/**
+ * Return the child node with the indicated key, creating it if necessary.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ */
+export default async function child(maplike, key) {
+  const map = await getMapArgument(maplike, "assign", { position: 0 });
+
+  let result;
+
+  const hasChildMethod = "child" in map && typeof map.child === "function";
+  if (hasChildMethod) {
+    // Use tree's own child() method
+    result = map.child(key);
+  } else {
+    // Default implementation
+    result = await map.get(key);
+
+    // If child is already a map we can use it as is
+    if (!isMap(result)) {
+      // Create new child node using no-arg constructor
+      result = new /** @type {any} */ (map).constructor();
+      await map.set(key, result);
+      setParent(result, map);
+    }
+  }
+
+  return result;
+}

package/src/operations/clear.js

@@ -1,20 +1,21 @@
-import from from "./from.js";
-import isAsyncMutableTree from "./isAsyncMutableTree.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Remove all entries from the tree.
+ * Remove all entries from the map.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function clear(treelike) {
-  const tree = from(treelike);
-  if (!isAsyncMutableTree(tree)) {
-    throw new TypeError("clear: can't clear a read-only tree.");
+export default async function clear(maplike) {
+  const map = await getMapArgument(maplike, "clear");
+  if ("readOnly" in map && map.readOnly) {
+    throw new TypeError("clear: target map is read-only");
+  }
+  const promises = [];
+  for await (const key of map.keys()) {
+    promises.push(map.delete(key));
   }
-  const keys = Array.from(await tree.keys());
-  const promises = keys.map((key) => tree.set(key, undefined));
   await Promise.all(promises);
-  return tree;
+  return map;
 }

package/src/operations/constant.js

@@ -0,0 +1,5 @@
+import ConstantMap from "../drivers/ConstantMap.js";
+
+export default function constant(value) {
+  return new ConstantMap(value);
+}

package/src/operations/deepEntries.js

@@ -0,0 +1,23 @@
+import getMapArgument from "../utilities/getMapArgument.js";
+import entries from "./entries.js";
+import isMap from "./isMap.js";
+
+/**
+ * Return the deep nested entries in the tree as arrays of [key, value] pairs.
+ *
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ *
+ * @param {Maplike} maplike
+ */
+export default async function deepEntries(maplike) {
+  const tree = await getMapArgument(maplike, "deepEntries");
+
+  const treeEntries = await entries(tree);
+  const result = await Promise.all(
+    treeEntries.map(async ([key, value]) => {
+      const resolvedValue = isMap(value) ? await deepEntries(value) : value;
+      return [key, resolvedValue];
+    })
+  );
+  return result;
+}

package/src/operations/deepMap.js

@@ -1,21 +1,21 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import isPlainObject from "../utilities/isPlainObject.js";
 import map from "./map.js";
 
 /**
  * Shorthand for calling `map` with the `deep: true` option.
  *
- * @typedef {import("../../index.ts").TreeMapOptions} TreeMapOptions
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").MapOptions} MapOptions
+ * @typedef {import("../../index.ts").Maplike} Maplike
  * @typedef {import("../../index.ts").ValueKeyFn} ValueKeyFn
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").AsyncMap} AsyncMap
  *
- * @param {Treelike} treelike
- * @param {ValueKeyFn|TreeMapOptions} options
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} maplike
+ * @param {ValueKeyFn|MapOptions} options
+ * @returns {Promise<AsyncMap>}
  */
-export default async function deepMap(treelike, options) {
-  const tree = await getTreeArgument(treelike, "deepMap", { deep: true });
+export default async function deepMap(maplike, options) {
+  const tree = await getMapArgument(maplike, "deepMap", { deep: true });
   const withDeep = isPlainObject(options)
     ? // Dictionary
       { ...options, deep: true }

package/src/operations/deepMerge.js

@@ -1,35 +1,42 @@
+import AsyncMap from "../drivers/AsyncMap.js";
 import * as trailingSlash from "../trailingSlash.js";
+import isUnpackable from "../utilities/isUnpackable.js";
 import from from "./from.js";
-import isAsyncTree from "./isAsyncTree.js";
-import isTreelike from "./isTreelike.js";
+import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
+import keys from "./keys.js";
 
 /**
  * Return a tree that performs a deep merge of the given trees.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike[]} sources
- * @returns {AsyncTree & { description: string }}
+ * @param {Maplike[]} maplikes
+ * @returns {Promise<AsyncMap>}
  */
-export default function deepMerge(...sources) {
-  const filtered = sources.filter((source) => source);
-  let trees = filtered.map((treelike) => from(treelike, { deep: true }));
+export default async function deepMerge(...maplikes) {
+  const filtered = maplikes.filter((source) => source);
+  const unpacked = await Promise.all(
+    filtered.map(async (source) =>
+      isUnpackable(source) ? await source.unpack() : source
+    )
+  );
+  const sources = unpacked.map((maplike) => from(maplike, { deep: true }));
 
-  return {
+  return Object.assign(new AsyncMap(), {
     description: "deepMerge",
 
     async get(key) {
       const subtrees = [];
 
       // Check trees for the indicated key in reverse order.
-      for (let index = trees.length - 1; index >= 0; index--) {
-        const tree = trees[index];
-        const value = await tree.get(key);
-        if (
-          isAsyncTree(value) ||
-          (isTreelike(value) && trailingSlash.has(key))
-        ) {
+      for (let index = sources.length - 1; index >= 0; index--) {
+        const source = sources[index];
+        const normalized = /** @type {any} */ (source).trailingSlashKeys
+          ? key
+          : trailingSlash.remove(key);
+        const value = await source.get(normalized);
+        if (isMap(value) || (isMaplike(value) && trailingSlash.has(key))) {
           subtrees.unshift(value);
         } else if (value !== undefined) {
           return value;
@@ -46,21 +53,25 @@ export default function deepMerge(...sources) {
       }
     },
 
-    async keys() {
-      const keys = new Set();
+    async *keys() {
+      const treeKeys = new Set();
       // Collect keys in the order the trees were provided.
-      for (const tree of trees) {
-        for (const key of await tree.keys()) {
+      for (const tree of sources) {
+        for (const key of await keys(tree)) {
           // Remove the alternate form of the key (if it exists)
           const alternateKey = trailingSlash.toggle(key);
           if (alternateKey !== key) {
-            keys.delete(alternateKey);
+            treeKeys.delete(alternateKey);
           }
 
-          keys.add(key);
+          treeKeys.add(key);
         }
       }
-      return keys;
+      yield* treeKeys;
     },
-  };
+
+    sources,
+
+    trailingSlashKeys: true,
+  });
 }

package/src/operations/deepReverse.js

@@ -1,31 +1,38 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import isAsyncTree from "./isAsyncTree.js";
+import AsyncMap from "../drivers/AsyncMap.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
+import keys from "./keys.js";
 
 /**
  * Reverse the order of keys at all levels of the tree.
  *
- * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
- * @returns {Promise<AsyncTree>}
+ * @param {Maplike} maplike
+ * @returns {Promise<AsyncMap>}
  */
-export default async function deepReverse(treelike) {
-  const tree = await getTreeArgument(treelike, "deepReverse", { deep: true });
+export default async function deepReverse(maplike) {
+  const source = await getMapArgument(maplike, "deepReverse", { deep: true });
+
+  return Object.assign(new AsyncMap(), {
+    description: "deepReverse",
 
-  return {
     async get(key) {
-      let value = await tree.get(key);
-      if (isAsyncTree(value)) {
+      let value = await source.get(key);
+      if (isMap(value)) {
         value = deepReverse(value);
       }
       return value;
     },
 
-    async keys() {
-      const keys = Array.from(await tree.keys());
-      keys.reverse();
-      return keys;
+    async *keys() {
+      const treeKeys = await keys(source);
+      treeKeys.reverse();
+      yield* treeKeys;
     },
-  };
+
+    source,
+
+    trailingSlashKeys: /** @type {any} */ (source).trailingSlashKeys,
+  });
 }

package/src/operations/deepTake.js

@@ -1,6 +1,6 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import from from "./from.js";
-import isAsyncTree from "./isAsyncTree.js";
+import isMap from "./isMap.js";
 
 /**
  * Returns a function that traverses a tree deeply and returns the values of the
@@ -9,23 +9,23 @@ import isAsyncTree from "./isAsyncTree.js";
  * 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 {import("../../index.ts").Maplike} maplike
  * @param {number} count
  */
-export default async function deepTake(treelike, count) {
-  const tree = await getTreeArgument(treelike, "deepTake", { deep: true });
+export default async function deepTake(maplike, count) {
+  const tree = await getMapArgument(maplike, "deepTake", { deep: true });
   const { values } = await traverse(tree, count);
   return from(values, { deep: true });
 }
 
 async function traverse(tree, count) {
   const values = [];
-  for (const key of await tree.keys()) {
+  for await (const key of tree.keys()) {
     if (count <= 0) {
       break;
     }
     let value = await tree.get(key);
-    if (isAsyncTree(value)) {
+    if (isMap(value)) {
       const traversed = await traverse(value, count);
       values.push(...traversed.values);
       count = traversed.count;

package/src/operations/deepText.js

@@ -1,14 +1,14 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import toString from "../utilities/toString.js";
 import deepValuesIterator from "./deepValuesIterator.js";
 
 /**
  * Concatenate the deep text values in a tree.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  */
-export default async function deepText(treelike) {
-  const tree = await getTreeArgument(treelike, "deepText", { deep: true });
+export default async function deepText(maplike) {
+  const tree = await getMapArgument(maplike, "deepText", { deep: true });
   const strings = [];
   for await (const value of deepValuesIterator(tree, { expand: true })) {
     let string;

package/src/operations/deepValues.js

@@ -3,14 +3,11 @@ import deepValuesIterator from "./deepValuesIterator.js";
 /**
  * Return the in-order exterior values of a tree as a flat array.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  * @param {{ expand?: boolean }} [options]
  */
-export default async function deepValues(
-  treelike,
-  options = { expand: false }
-) {
-  const iterator = deepValuesIterator(treelike, options);
+export default async function deepValues(maplike, options = { expand: false }) {
+  const iterator = deepValuesIterator(maplike, options);
   const values = [];
   for await (const value of iterator) {
     values.push(value);