@weborigami/async-tree 0.0.65-beta.2 → 0.0.66-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/async-tree",
-  "version": "0.0.65-beta.2",
+  "version": "0.0.66-beta.1",
   "description": "Asynchronous tree drivers based on standard JavaScript classes",
   "type": "module",
   "main": "./main.js",
@@ -11,7 +11,7 @@
     "typescript": "5.5.4"
   },
   "dependencies": {
-    "@weborigami/types": "0.0.65-beta.2"
+    "@weborigami/types": "0.0.66-beta.1"
   },
   "scripts": {
     "test": "node --test --test-reporter=spec",

package/src/MapTree.js

@@ -23,13 +23,6 @@ export default class MapTree {
   }
 
   async get(key) {
-    if (key == null) {
-      // Reject nullish key.
-      throw new ReferenceError(
-        `${this.constructor.name}: Cannot get a null or undefined key.`
-      );
-    }
-
     const value = this.map.get(key);
     setParent(value, this);
     return value;

package/src/Tree.d.ts

@@ -5,7 +5,7 @@ export function assign(target: Treelike, source: Treelike): Promise<AsyncTree>;
 export function clear(AsyncTree: AsyncMutableTree): Promise<void>;
 export function entries(AsyncTree: AsyncTree): Promise<IterableIterator<any>>;
 export function forEach(AsyncTree: AsyncTree, callbackfn: (value: any, key: any) => Promise<void>): Promise<void>;
-export function from(obj: any, options?: { deep: boolean }): AsyncTree;
+export function from(obj: any, options?: { deep?: boolean, parent?: AsyncTree|null }): AsyncTree;
 export function has(AsyncTree: AsyncTree, key: any): Promise<boolean>;
 export function isAsyncMutableTree(obj: any): obj is AsyncMutableTree;
 export function isAsyncTree(obj: any): obj is AsyncTree;

package/src/Tree.js

@@ -105,35 +105,38 @@ export async function forEach(tree, callbackFn) {
  *
  * If the object is a plain object, it will be converted to an ObjectTree. The
  * optional `deep` option can be set to `true` to convert a plain object to a
- * DeepObjectTree.
+ * DeepObjectTree. The optional `parent` parameter will be used as the default
+ * parent of the new tree.
  *
  * @param {Treelike | Object} object
- * @param {{ deep?: true }} [options]
+ * @param {{ deep?: true, parent?: AsyncTree|null }} [options]
  * @returns {AsyncTree}
  */
 export function from(object, options = {}) {
+  let tree;
   if (isAsyncTree(object)) {
     // Argument already supports the tree interface.
     // @ts-ignore
     return object;
   } else if (typeof object === "function") {
-    return new FunctionTree(object);
+    tree = new FunctionTree(object);
   } else if (object instanceof Map) {
-    return new MapTree(object);
+    tree = new MapTree(object);
   } else if (object instanceof Set) {
-    return new SetTree(object);
+    tree = new SetTree(object);
   } else if (isPlainObject(object) || object instanceof Array) {
-    return options.deep ? new DeepObjectTree(object) : new ObjectTree(object);
+    tree = options.deep ? new DeepObjectTree(object) : new ObjectTree(object);
   } else if (isUnpackable(object)) {
     async function AsyncFunction() {} // Sample async function
-    return object.unpack instanceof AsyncFunction.constructor
-      ? // Async unpack: return a deferred tree.
-        new DeferredTree(object.unpack)
-      : // Synchronous unpack: cast the result of unpack() to a tree.
-        from(object.unpack());
+    tree =
+      object.unpack instanceof AsyncFunction.constructor
+        ? // Async unpack: return a deferred tree.
+          new DeferredTree(object.unpack)
+        : // Synchronous unpack: cast the result of unpack() to a tree.
+          from(object.unpack());
   } else if (object && typeof object === "object") {
     // An instance of some class.
-    return new ObjectTree(object);
+    tree = new ObjectTree(object);
   } else if (
     typeof object === "string" ||
     typeof object === "number" ||
@@ -141,10 +144,15 @@ export function from(object, options = {}) {
   ) {
     // A primitive value; box it into an object and construct a tree.
     const boxed = utilities.box(object);
-    return new ObjectTree(boxed);
+    tree = new ObjectTree(boxed);
+  } else {
+    throw new TypeError("Couldn't convert argument to an async tree");
   }
 
-  throw new TypeError("Couldn't convert argument to an async tree");
+  if (!tree.parent && options.parent) {
+    tree.parent = options.parent;
+  }
+  return tree;
 }
 
 /**
@@ -416,7 +424,7 @@ export async function traverseOrThrow(treelike, ...keys) {
   let key;
   while (remainingKeys.length > 0) {
     if (value === undefined) {
-      throw new TraverseError("Tried to traverse a null or undefined value", {
+      throw new TraverseError("A null or undefined value can't be traversed", {
         tree: treelike,
         keys,
         position,

package/src/operations/cache.js

@@ -23,6 +23,12 @@ export default function treeCache(
   cacheTreelike,
   filterTreelike
 ) {
+  if (!sourceTreelike) {
+    const error = new TypeError(`cache: The source tree isn't defined.`);
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const source = Tree.from(sourceTreelike);
   const filter = filterTreelike ? Tree.from(filterTreelike) : undefined;
 

package/src/operations/concat.js

@@ -10,6 +10,12 @@ import deepValuesIterator from "./deepValuesIterator.js";
  * @param {import("../../index.ts").Treelike} treelike
  */
 export default async function concatTreeValues(treelike) {
+  if (!treelike) {
+    const error = new TypeError(`concat: The tree isn't defined.`);
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const strings = [];
   for await (const value of deepValuesIterator(treelike, { expand: true })) {
     if (value) {

package/src/operations/deepTakeFn.js

@@ -11,6 +11,12 @@ 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);

package/src/operations/deepValuesIterator.js

@@ -14,6 +14,12 @@ export default async function* deepValuesIterator(
   treelike,
   options = { expand: false }
 ) {
+  if (!treelike) {
+    const error = new TypeError(`deepValues: The tree isn't defined.`);
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const tree = Tree.from(treelike, { deep: true });
   for (const key of await tree.keys()) {
     let value = await tree.get(key);

package/src/operations/groupFn.js

@@ -11,6 +11,12 @@ 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 result = {};
     for (const key of await tree.keys()) {

package/src/operations/scope.js

@@ -11,6 +11,12 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree & {trees: AsyncTree[]}}
  */
 export default function scope(treelike) {
+  if (!treelike) {
+    const error = new TypeError(`scope: The tree isn't defined.`);
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const tree = Tree.from(treelike);
 
   return {

package/src/transforms/deepReverse.js

@@ -10,6 +10,14 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree}
  */
 export default function deepReverse(treelike) {
+  if (!treelike) {
+    const error = new TypeError(
+      `deepReverse: The tree to reverse isn't defined.`
+    );
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const tree = Tree.from(treelike);
   return {
     async get(key) {

package/src/transforms/mapFn.js

@@ -46,6 +46,12 @@ export default function createMapTransform(options = {}) {
    * @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

package/src/transforms/regExpKeys.js

@@ -11,6 +11,14 @@ import { Tree } from "../internal.js";
  * @type {import("../../index.ts").TreeTransform}
  */
 export default async function regExpKeys(treelike) {
+  if (!treelike) {
+    const error = new TypeError(
+      `regExpKeys: The tree of regular expressions isn't defined.`
+    );
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const tree = Tree.from(treelike);
   const map = new Map();
 
@@ -21,6 +29,13 @@ export default async function regExpKeys(treelike) {
     description: "regExpKeys",
 
     async get(key) {
+      if (key == null) {
+        // Reject nullish key.
+        throw new ReferenceError(
+          `${this.constructor.name}: Cannot get a null or undefined key.`
+        );
+      }
+
       for (const [regExp, value] of map) {
         if (regExp.test(key)) {
           return value;

package/src/transforms/reverse.js

@@ -10,6 +10,12 @@ import { Tree } from "../internal.js";
  * @returns {AsyncTree}
  */
 export default function reverse(treelike) {
+  if (!treelike) {
+    const error = new TypeError(`reverse: The tree to reverse isn't defined.`);
+    /** @type {any} */ (error).position = 0;
+    throw error;
+  }
+
   const tree = Tree.from(treelike);
   return {
     async get(key) {

package/src/transforms/sortFn.js

@@ -26,6 +26,12 @@ export default function sortFn(options) {
    * @type {import("../../index.ts").TreeTransform}
    */
   return function sort(treelike) {
+    if (!treelike) {
+      const error = new TypeError(`sort: The tree to sort isn't defined.`);
+      /** @type {any} */ (error).position = 0;
+      throw error;
+    }
+
     const tree = Tree.from(treelike);
     const transformed = Object.create(tree);
     transformed.keys = async () => {

package/src/transforms/takeFn.js

@@ -10,6 +10,12 @@ export default function take(count) {
    * @type {import("../../index.ts").TreeTransform}
    */
   return (treelike) => {
+    if (!treelike) {
+      const error = new TypeError(`take: The tree to take from isn't defined.`);
+      /** @type {any} */ (error).position = 0;
+      throw error;
+    }
+
     const tree = Tree.from(treelike);
     return {
       async keys() {

package/test/MapTree.test.js

@@ -26,16 +26,6 @@ describe("MapTree", () => {
     const fixture = createFixture();
     assert.equal(await fixture.get("d"), undefined);
   });
-
-  test("getting a null/undefined key throws an exception", async () => {
-    const fixture = createFixture();
-    await assert.rejects(async () => {
-      await fixture.get(null);
-    });
-    await assert.rejects(async () => {
-      await fixture.get(undefined);
-    });
-  });
 });
 
 function createFixture() {