feat: .can() API (#74)

Matches xstate more closely and it's useful.

Author: tivac

.changeset/fair-ligers-move.md

@@ -0,0 +1,11 @@
+---
+"xstate-component-tree": minor
+---
+
+Adding `.can()` API from XState
+
+The `.can()` 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.
+
+From the XState docs on `.can()`:
+
+> Determines whether sending the event will cause a non-forbidden transition to be selected, even if the transitions have no actions nor change the state value.

src/component-tree.js

@@ -87,6 +87,7 @@ class ComponentTree {
         this._boundApis = {
             matches   : this.matches.bind(this),
             hasTag    : this.hasTag.bind(this),
+            can       : this.can.bind(this),
             broadcast : this.broadcast.bind(this),
         };
 
@@ -501,6 +502,16 @@ class ComponentTree {
         return [ ...this._services.values() ].some(({ state }) => state.hasTag(tag));
     }
 
+    /**
+     * Check if the current state or any child states can make a transition
+     *
+     * @param {Event | string} event
+     * @returns boolean
+     */
+     can(event) {
+        return [ ...this._services.values() ].some(({ state }) => state.can(event));
+    }
+
     /**
      * Check if the current state or any child states match a path
      *

tests/api/can.test.js

@@ -0,0 +1,62 @@
+import * as assert from "uvu/assert";
+
+import describe from "../util/describe.js";
+import { createTree } from "../util/trees.js";
+import { treeTeardown } from "../util/context.js";
+
+import single from "./specimens/single.js";
+import child from "./specimens/child.js";
+import noComponents from "./specimens/no-components.js";
+
+describe("can", (it) => {
+    it.after.each(treeTeardown);
+    
+    it("should check the root tree", async (context) => {
+        const tree = context.tree = createTree(single);
+
+        let { extra } = await tree();
+
+        assert.ok(tree.builder.can("NEXT"));
+        assert.ok(extra.can("NEXT"));
+
+        assert.not.ok(tree.builder.can("NOPE"));
+        assert.not.ok(extra.can("NOPE"));
+
+        tree.service.send("NEXT");
+
+        ({ extra } = await tree());
+
+        assert.ok(tree.builder.can("NEXT"));
+        assert.ok(extra.can("NEXT"));
+
+        assert.not.ok(tree.builder.can("NOPE"));
+        assert.not.ok(extra.can("NOPE"));
+    });
+
+    it("should check child trees", async (context) => {
+        const tree = context.tree = createTree(child);
+
+        const { extra } = await tree();
+
+        assert.ok(tree.builder.can("NEXT"));
+        assert.ok(tree.builder.can("CHILD_NEXT"));
+        assert.ok(extra.can("NEXT"));
+        assert.ok(extra.can("CHILD_NEXT"));
+    });
+
+    it("should work without components", async (context) => {
+        const tree = context.tree = createTree(noComponents);
+
+        let { extra } = await tree();
+
+        assert.ok(tree.builder.can("NEXT"));
+        assert.ok(extra.can("NEXT"));
+
+        tree.service.send("NEXT");
+
+        ({ extra } = await tree());
+
+        assert.ok(tree.builder.can("NEXT"));
+        assert.ok(extra.can("NEXT"));
+    });
+});

tests/api/specimens/child.js

@@ -19,7 +19,8 @@ const child = createMachine({
                     tags : "child-one",
 
                     on : {
-                        NEXT : "two",
+                        NEXT       : "two",
+                        CHILD_NEXT : "two",
                     },
                 },