@weborigami/async-tree 0.5.7 → 0.6.0

package/src/operations/cache.js

@@ -1,8 +1,9 @@
-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 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 +11,51 @@ 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, {});
+          await cache.set(key, cache.constructor.EMPTY);
           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);
-          }
         }
         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/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);

package/src/operations/deepValuesIterator.js

@@ -1,32 +1,32 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
-import isAsyncTree from "./isAsyncTree.js";
-import isTreelike from "./isTreelike.js";
+import getMapArgument from "../utilities/getMapArgument.js";
+import isMap from "./isMap.js";
+import isMaplike from "./isMaplike.js";
 
 /**
  * Return an iterator that yields all values in a tree, including nested trees.
  *
- * If the `expand` option is true, treelike values (but not functions) will be
+ * If the `expand` option is true, maplike values (but not functions) will be
  * expanded into nested trees and their values will be yielded.
  *
- * @param {import("../../index.ts").Treelike} treelike
+ * @param {import("../../index.ts").Maplike} maplike
  * @param {{ expand?: boolean }} [options]
  * @returns {AsyncGenerator<any, void, undefined>}
  */
 export default async function* deepValuesIterator(
-  treelike,
+  maplike,
   options = { expand: false }
 ) {
-  const tree = await getTreeArgument(treelike, "deepValuesIterator", {
+  const tree = await getMapArgument(maplike, "deepValuesIterator", {
     deep: true,
   });
 
-  for (const key of await tree.keys()) {
-    let value = await tree.get(key);
+  for await (const key of tree.keys()) {
+    const value = await tree.get(key);
 
     // Recurse into child trees, but don't expand functions.
     const recurse =
-      isAsyncTree(value) ||
-      (options.expand && typeof value !== "function" && isTreelike(value));
+      isMap(value) ||
+      (options.expand && typeof value !== "function" && isMaplike(value));
     if (recurse) {
       yield* deepValuesIterator(value, options);
     } else {

package/src/operations/delete.js

@@ -1,20 +1,16 @@
-import has from "./has.js";
-
 /**
  * Removes the value for the given key from the specific node of the tree.
  *
- * @typedef {import("@weborigami/types").AsyncMutableTree} AsyncMutableTree
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {AsyncMutableTree} tree
+ * @param {Maplike} maplike
  * @param {any} key
  */
+
+import getMapArgument from "../utilities/getMapArgument.js";
+
 // `delete` is a reserved word in JavaScript, so we use `del` instead.
-export default async function del(tree, key) {
-  const exists = await has(tree, key);
-  if (exists) {
-    await tree.set(key, undefined);
-    return true;
-  } else {
-    return false;
-  }
+export default async function del(maplike, key) {
+  const map = await getMapArgument(maplike, "delete");
+  return map.delete(key);
 }

package/src/operations/entries.js

@@ -1,16 +1,23 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
- * Returns a new `Iterator` object that contains a two-member array of `[key,
- * value]` for each element in the specific node of the tree.
+ * Returns an array of `[key, value]` for each entry in the map.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
+ * @returns {Promise<Array<[any, any]>>}
  */
-export default async function entries(treelike) {
-  const tree = await getTreeArgument(treelike, "entries");
-  const keys = Array.from(await tree.keys());
-  const promises = keys.map(async (key) => [key, await tree.get(key)]);
-  return Promise.all(promises);
+export default async function entries(maplike) {
+  const map = await getMapArgument(maplike, "entries");
+  if (map instanceof Map) {
+    return Array.from(map.entries());
+  } else {
+    // AsyncMap
+    const result = [];
+    for await (const entry of map) {
+      result.push(entry);
+    }
+    return result;
+  }
 }

package/src/operations/filter.js

@@ -1,18 +1,18 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 import map from "./map.js";
 
 /**
  * Given a tree an a test function, return a new tree whose keys correspond to
  * the values that pass the test function.
  *
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
+ * @typedef {import("../../index.ts").AsyncMap} AsyncMap
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  * @param {function|any} options
- * @returns {Promise<AsyncTree>}
+ * @returns {Promise<AsyncMap>}
  */
-export default async function filter(treelike, options) {
+export default async function filter(maplike, options) {
   let testFn;
   let deep;
   if (typeof options === "function") {
@@ -23,10 +23,12 @@ export default async function filter(treelike, options) {
     deep = options.deep ?? false;
   }
 
-  const tree = await getTreeArgument(treelike, "filter", { deep });
+  const tree = await getMapArgument(maplike, "filter", { deep });
   return map(tree, {
     deep,
 
+    description: "filter",
+
     // Assume source key is the same as result key
     inverseKey: async (resultKey) => resultKey,
 

package/src/operations/first.js

@@ -1,18 +1,20 @@
-import getTreeArgument from "../utilities/getTreeArgument.js";
+import getMapArgument from "../utilities/getMapArgument.js";
 
 /**
  * Return the first value in the tree.
  *
- * @typedef {import("../../index.ts").Treelike} Treelike
+ * @typedef {import("../../index.ts").Maplike} Maplike
  *
- * @param {Treelike} treelike
+ * @param {Maplike} maplike
  */
-export default async function first(treelike) {
-  const tree = await getTreeArgument(treelike, "first");
-  for (const key of await tree.keys()) {
-    // Just return first value immediately.
-    const value = await tree.get(key);
-    return value;
+export default async function first(maplike) {
+  const map = await getMapArgument(maplike, "first");
+  let firstKey;
+  for await (const key of map.keys()) {
+    // Just needed to get first key
+    firstKey = key;
+    break;
   }
-  return undefined;
+  const value = firstKey ? await map.get(firstKey) : undefined;
+  return value;
 }