feat: add service.do() boolean return validation

State machine service now returns meaningful boolean feedback when executing actions.
Returns true for successful transitions, false when predicates fail or no valid transition exists.

This enables deterministic error handling - developers can now programmatically verify
whether state changes succeeded instead of guessing from side effects.

Author: yyxi

README.md

@@ -118,5 +118,41 @@ Creates an executable state machine instance.
 
 #### Methods
 
-- `.do(action, payload?)` - Dispatch an action
+- `.do(action, payload?)` - Dispatch an action, returns boolean indicating success
 - `.subscribe(callback)` - Subscribe to state changes
+
+### Action Dispatch Return Values
+
+The `.do()` method returns a boolean that indicates whether the action successfully triggered a state transition:
+
+**Returns `true` when:**
+
+- A valid transition exists for the current state + action combination
+- All transition predicates (if any) evaluate to `true`
+- The state transition executes successfully
+
+**Returns `false` when:**
+
+- No transition is defined for the current state + action combination
+- All transition predicates fail (return `false`)
+
+This return value enables precise control flow based on whether state changes actually occurred.
+
+```typescript
+const machine = stateMachine()
+  .state('idle')
+  .state('working')
+  .initial('idle')
+  .action('start')
+  .action('stop')
+  .transition('idle', 'start', 'working')
+// Note: no 'stop' transition from 'idle'
+
+const service = interpret(machine)
+
+const started = service.do('start') // true - transition succeeds
+console.log(service.state) // 'working'
+
+const stopped = service.do('stop') // false - no transition defined
+console.log(service.state) // still 'working'
+```

package.json

@@ -11,6 +11,7 @@
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
     "@escapace/pnpm-pack": "0.6.0",
+    "@escapace/sequentialize": "4.0.1",
     "@ls-lint/ls-lint": "2.3.1",
     "@types/lodash-es": "4.17.12",
     "@vitest/coverage-v8": "3.2.4",

pnpm-lock.yaml

@@ -481,6 +481,119 @@ describe('./src/index.spec.ts', () => {
     assert.equal(spyObservable.mock.calls.length, 7)
   })
 
+  it('service.do() boolean return values', () => {
+    // Create a focused state machine to test service.do() return values
+    // Based on interpret.ts logic:
+    // - Returns false: No transitions for state+action OR all predicates fail
+    // - Returns true: Valid transition found and executed
+
+    enum TestState {
+      StateA = 'STATE_A',
+      StateB = 'STATE_B',
+    }
+
+    enum TestAction {
+      Always = 'ALWAYS',
+      Conditional = 'CONDITIONAL',
+      Never = 'NEVER',
+      Undefined = 'UNDEFINED', // Won't be defined in machine
+    }
+
+    interface TestContext {
+      counter: number
+    }
+
+    const testMachine = stateMachine()
+      .state(TestState.StateA)
+      .state(TestState.StateB)
+      .initial(TestState.StateA)
+      .action<TestAction.Always>(TestAction.Always)
+      .action<TestAction.Never>(TestAction.Never)
+      .action<TestAction.Conditional, { shouldPass: boolean }>(TestAction.Conditional)
+      .context<TestContext>({ counter: 0 })
+      // Transition that always succeeds (no predicate)
+      .transition(TestState.StateA, TestAction.Always, TestState.StateB)
+      // Transition with predicate that always fails
+      .transition(
+        TestState.StateA,
+        [TestAction.Never, () => false], // Predicate always returns false
+        TestState.StateB,
+      )
+      // Transition with conditional predicate
+      .transition(
+        TestState.StateA,
+        [TestAction.Conditional, (_, action) => action.payload.shouldPass],
+        TestState.StateB,
+      )
+    // Note: No transition defined for TestAction.Undefined
+
+    const testService = interpret(testMachine)
+
+    // Test case 1: Valid transition with no predicate - should return true
+    assert.equal(testService.state, TestState.StateA)
+    const alwaysResult = testService.do(TestAction.Always)
+    assert.equal(alwaysResult, true, 'service.do() should return true for valid transition')
+    assert.equal(
+      testService.state,
+      TestState.StateB,
+      'State should change after successful transition',
+    )
+
+    // Reset to StateA for remaining tests
+    const resetMachine = interpret(testMachine)
+
+    // Test case 2: Transition with failing predicate - should return false
+    const neverResult = resetMachine.do(TestAction.Never)
+    assert.equal(neverResult, false, 'service.do() should return false when predicate fails')
+    assert.equal(
+      resetMachine.state,
+      TestState.StateA,
+      'State should not change when transition fails',
+    )
+
+    // Test case 3: Transition with passing predicate - should return true
+    const conditionalTrueResult = resetMachine.do(TestAction.Conditional, { shouldPass: true })
+    assert.equal(
+      conditionalTrueResult,
+      true,
+      'service.do() should return true when predicate passes',
+    )
+    assert.equal(resetMachine.state, TestState.StateB, 'State should change when predicate passes')
+
+    // Reset again for final test
+    const resetMachine2 = interpret(testMachine)
+
+    // Test case 4: Transition with failing predicate - should return false
+    const conditionalFalseResult = resetMachine2.do(TestAction.Conditional, { shouldPass: false })
+    assert.equal(
+      conditionalFalseResult,
+      false,
+      'service.do() should return false when predicate fails',
+    )
+    assert.equal(
+      resetMachine2.state,
+      TestState.StateA,
+      'State should not change when predicate fails',
+    )
+
+    // Test case 5: Action with no defined transitions - should return false
+    // From StateB, try an action that only has transitions from StateA
+    testService.do(TestAction.Always) // Move to StateB if not already there
+    assert.equal(testService.state, TestState.StateB)
+
+    const noTransitionResult = testService.do(TestAction.Never)
+    assert.equal(
+      noTransitionResult,
+      false,
+      'service.do() should return false when no transitions exist for state+action',
+    )
+    assert.equal(
+      testService.state,
+      TestState.StateB,
+      'State should not change when no transition exists',
+    )
+  })
+
   it('fff', () => {
     assert.throws(() =>
       // @ts-expect-error

src/index.spec.ts

@@ -67,7 +67,7 @@ export const interpret = <T extends InteropStateMachine>(
 
       if (transitions === undefined || transitions.length === 0) {
         // TODO: Strict mode? Silent mode?
-        return
+        return false
       }
 
       const _action: Partial<Action> = {
@@ -110,7 +110,7 @@ export const interpret = <T extends InteropStateMachine>(
 
       if (transition === undefined) {
         // TODO: Strict mode? Silent mode?
-        return
+        return false
       }
 
       state = transition.target
@@ -129,7 +129,7 @@ export const interpret = <T extends InteropStateMachine>(
       //   subscription({ action: _action, context, state } as Change)
       // )
 
-      return
+      return true
     },
     get state() {
       return state