feat: add .send() API (#67)

Author: tivac

.changeset/honest-singers-do.md

@@ -0,0 +1,9 @@
+---
+"xstate-component-tree": minor
+---
+
+Added `.send()` API
+
+The `.send()` API is a simple passthrough to the interpreter for the root statechart being managed by `xstate-component-tree`, and is intended as a convenience function to make it easier to interact with a `ComponentTree` instance instead of a direct XState `Interpreter` reference.
+
+[XState Docs on .send()](https://xstate.js.org/docs/guides/interpretation.html#sending-events)

src/component-tree.js

@@ -504,6 +504,16 @@ class ComponentTree {
         return [ ...this._services.values() ].some(({ state }) => state.matches(path));
     }
 
+    /**
+     * Send an event to the root machine only
+     *
+     * @param  {...any} event Event to send
+     * @returns Updated XState State object
+     */
+    send(...event) {
+        return this._services.get(this.id).interpreter.send(...event);
+    }
+
     /**
      * Provides an observable API, matches the svelte store contract
      * https://svelte.dev/docs#component-format-script-4-prefix-stores-with-$-to-access-their-values-store-contract

tests/api/send.test.js

@@ -0,0 +1,73 @@
+import * as assert from "uvu/assert";
+
+import describe from "../util/describe.js";
+import { createTree, waitForPath } from "../util/trees.js";
+import { treeTeardown } from "../util/context.js";
+import { diff } from "../util/snapshot.js";
+
+import single from "./specimens/single.js";
+import child from "./specimens/child.js";
+
+describe("send", (it) => {
+    it.after.each(treeTeardown);
+
+    it("should be a callable method", async (context) => {
+        const tree = context.tree = createTree(single);
+
+        assert.type(tree.builder.send, "function");
+    });
+
+    it("should send to the root tree", async (context) => {
+        const tree = context.tree = createTree(single);
+
+        const { tree : one } = await tree();
+        
+        tree.builder.send("NEXT");
+
+        const { tree : two } = await waitForPath(tree, "two");
+
+        diff(one, two, `
+        [
+            [Object: null prototype] {
+        Actual:
+        --        path: "one",
+        --        component: [Function: one],
+        Expected:
+        ++        path: "two",
+        ++        component: [Function: two],
+                props: false,
+                children: []
+            }
+        ]`);
+    });
+
+    it("should *not* send to child trees", async (context) => {
+        const tree = context.tree = createTree(child);
+
+        const { tree : one } = await tree();
+
+        tree.builder.send("NEXT");
+
+        const { tree : two } = await waitForPath(tree, "root.two");
+
+        diff(one, two, `
+        [
+            [Object: null prototype] {
+        Actual:
+        --        path: "root.one",
+        --        component: [Function: one],
+        Expected:
+        ++        path: "root.two",
+        ++        component: [Function: two],
+                props: false,
+                children: []
+            },
+            [Object: null prototype] {
+                path: "child.one",
+                component: [Function: child-one],
+                props: false,
+                children: []
+            }
+        ]`);
+    });
+});