Robot Finite State Machine

An invoke state is a special type of state that immediately executes a Promise-returning function or another machine. It is used to handle asynchronous tasks or delegate logic to child machines.

When the invoked task completes, the service sends specific events (done or error) which you can capture using transition to move to new states and reduce to update the machine context.

Key characteristics:

• The argument passed to invoke must be a function that returns a Promise, not the Promise itself.
• If a Promise is already created, wrap it in a function: () => promise.
• Successful resolution triggers a done event with a data property.
• Rejection triggers an error event with an error property.

import { createMachine, immediate, invoke, reduce, state, transition } from 'robot3';

async function loadUsers() {
  return [ { id: 1, name: 'Wilbur' } ];
}

const machine = createMachine({
  idle: state(
    transition('load', 'loading')
  ),
  loading: invoke(loadUsers,
    transition('done', 'idle',
      reduce((ctx, ev) => ({ ...ctx, user: ev.data }))
    ),
    transition('error', 'error',
      reduce((ctx, ev) => ({ ...ctx, error: ev.error }))
    )
  ),
  error: state()
})

Transitions define the pathways between states in a finite state machine. Instead of allowing state changes to happen anywhere in your code (imperative programming), transitions explicitly declare how a machine moves from one state to another in response to specific events. This makes application behavior predictable and prevents invalid state changes.

Transitions are defined within a state using the transition function. A transition consists of:

1. Event name: A string identifying the trigger.
2. Target state: The name of the state to move to (must be a valid state defined in the machine).
3. Optional modifiers: Guards, actions, or reducers.

Self-Transitions

A transition can target its own state. This is a common pattern used to update context (data) without changing the current state of the machine.

import { createMachine, state, transition } from 'robot3';

const machine = createMachine({
  idle: state(
    transition('fetch', 'loading')
  ),
  loading: state(
    transition('success', 'loaded'),
    transition('error', 'error')
  ),
  loaded: state(),
  error: state(
    transition('retry', 'loading')
  )
});

Robot follows a 'composition over configuration' philosophy, allowing you to break down Finite State Machines into small, reusable functions rather than constructing a single large configuration object.

Instead of defining every state and transition inside a single createMachine call, you can create helper functions that return transition or state definitions. These helpers can be exported from separate modules and imported into different machines to maintain succinct and DRY (Don't Repeat Yourself) code.

Common patterns include creating generic field handlers that listen for specific events, run a reduce function to update the machine context, and return to a specific state.

import { createMachine, state, reduce, transition } from 'robot3';

// A reusable helper function that returns a transition
const field = (prop, state) => (
  transition(prop, state,
    reduce((ctx, ev) => ({ ...ctx, [prop]: ev.event.target.value }))
  )
);

// A specialized helper for a specific state
const formField = (prop) => field(prop, 'form');

const machine = createMachine({
  form: state(
    formField('first'),
    formField('last')
  )
});

Robot supports several ways for events to trigger transitions:

1. User Events: Explicitly sent via service.send(). These represent manual triggers like button clicks.
2. Immediate Transitions: Transitions that trigger automatically upon entering a state using the immediate() function, without requiring an external event.
3. Invoked Events: When using invoke for asynchronous operations, Robot automatically generates done and error events based on the outcome of the promise.

import { createMachine, state, transition, immediate, invoke } from 'robot3';

const machine = createMachine({
  // Immediate Transition
  validate: state(
    immediate('loaded', guard(isValid)),
    immediate('error', guard(isInvalid))
  ),
  
  // Invoked Events (automatic 'done' and 'error')
  loading: invoke(fetchUsers,
    transition('done', 'loaded'),
    transition('error', 'error')
  )
});