FiniteStateMachine class
A strongly-typed finite state machine with reactive state and context. It is a class because you drive it with methods, the way Svelte makes SvelteMap a class.
import { FiniteStateMachine } from 'kenspeckle'; Typed states and events
States are a string union. Events are a payload map — each event declares its argument tuple, and everything downstream is checked:
type States = 'idle' | 'searching' | 'done';
type Events = {
search: [query: string];
cancel: [];
};
const machine = new FiniteStateMachine<States, Events>('idle', {
idle: { search: 'searching' },
searching: { cancel: 'idle', search: 'searching' },
done: {}
});
// ok
machine.send('search', 'red');
// compile error: missing payload
machine.send('search');
// compile error: unknown event
machine.send('serach', 'red'); machine.current is $state-backed — read it in templates and deriveds and it updates reactively. _enter and _exit are reserved names (lifecycle slots); don’t use them as event names.
Sending and transitions
A handler is either a string target or a function. Functions receive a meta object and decide the transition by what they return:
searching: {
// string target: unconditional transition
cancel: 'idle',
// function: return a state to transition, undefined to stay
result: ({ from, event, args, context }) =>
args[0].length > 0 ? 'done' : undefined
} - Returning a state always transitions — returning the current state re-enters it, firing
_exitand_enteragain. (Replay flows work; there is no silent self-transition no-op.) - Returning
undefinedvetoes: the machine stays put and no lifecycle fires. Guards aren’t a separate concept — a handler that returnsundefinedis the guard. sendreturns the resulting state.
Meta fields are narrowed per state block: inside idle’s handlers, from is the literal type 'idle'; for the search handler, args is [query: string].
The '*' fallback
Events (and lifecycle functions) not found on the current state fall back to the '*' pseudo-state:
'*': {
// handled from any state that doesn't define its own
reset: 'idle'
} A state’s own handler always wins over '*'.
Lifecycle
Each state (and '*') may declare _enter and _exit. On a transition, the old state’s _exit fires, then current changes, then the new state’s _enter fires:
searching: {
_enter: ({ from, to, event, args, context }) => {
// to is narrowed to 'searching' here
},
_exit: ({ from, to, event, args, context }) => {
// from is narrowed to 'searching' here
}
} Construction fires a synthetic _enter for the initial state with { from: null, event: null, args: [] }.
One shared _enter on '*' observes every state that doesn’t define its own — no need to copy it into each state:
'*': {
_enter: ({ to }) => {
trackStep(to);
}
} Narrowing the meta’s event narrows its args (they’re a discriminated union).
Re-entry hazard. Because returned states always transition, a '*' catch-all like '*': { complete: 'complete' } means a second send('complete') re-enters complete and re-runs its _enter side effects. Declare the event on the target state as a no-op to ignore it instead:
complete: {
reset: 'idle',
// declared ignore — no re-entry, no dev warning
complete: () => {}
} Sends from inside lifecycle functions run synchronously (no queue). A send from _enter runs after the state is set, and the outer send returns the final state. A transition completed inside _exit supersedes the outer one — the outer transition aborts.
Context
The third generic adds typed, deeply reactive extended state. When you declare it, the constructor requires it — and when you don’t, the option can’t be passed:
type Ctx = { attempts: number; results: string[] };
const machine = new FiniteStateMachine<States, Events, Ctx>('idle', states, {
context: { attempts: 0, results: [] }
});
// reactive read
machine.context.attempts;
// whole-value reassignment, stays reactive
machine.context = { ... }; Handlers and lifecycle functions receive the live context in their meta and mutate it directly:
searching: {
result: ({ context, args: [query] }) => {
context.attempts++;
// deep mutation is reactive
context.results.push(query);
return context.attempts > 3 ? 'done' : undefined;
}
} Keep domain verbs out of the machine — wrap it in an app-facing class or factory when consumers need an API richer than send.
Debounce
The machine has no debounce of its own. Wrap send in the exported debounce:
import { debounce } from 'kenspeckle';
const search = debounce((q: string) => machine.send('search', q), 300); Calling search(query) on every keystroke sends once, with the last query, after 300ms of quiet. Each call’s promise resolves with the state the trailing send returns, so a superseded call never hangs. search.pending is reactive, so a $derived or the template can show that a send is waiting.
When a pending send must not land in a later state, cancel it on the way out:
const machine = new FiniteStateMachine<States, Events>('typing', {
typing: {
search: 'searching',
submit: 'submitted',
_exit: () => search.cancel()
},
searching: { search: 'searching', submit: 'submitted' },
submitted: {}
}); send is pre-bound; pass it as an event handler directly.
Dev warnings
In dev (via esm-env, stripped from production builds), sending an event with no handler in the current state or '*' warns:
kenspeckle: unhandled event 'keydown' in state 'idle' If ignoring is intentional — e.g. keyboard events fired at the machine in every state — declare a no-op handler where they should be dropped and the warning stays meaningful everywhere else.
Sharing a machine via context
No wrapper needed — Svelte ≥ 5.40’s createContext covers it. The factory recipe:
// wizard-machine.svelte.ts
import { createContext } from 'svelte';
import { FiniteStateMachine } from 'kenspeckle';
type WizardMachine = FiniteStateMachine<WizardStep, WizardEvents, WizardCtx>;
const [getWizard, setWizard] = createContext<WizardMachine>();
export function createWizard(initial: WizardStep = 'intro') {
const machine = new FiniteStateMachine<WizardStep, WizardEvents, WizardCtx>(initial, states, {
context: { attempts: 0, answers: [] }
});
setWizard(machine);
return machine;
}
export { getWizard }; The parent layout calls createWizard(); any descendant calls getWizard() and gets the fully-typed machine.
SSR
The machine is plain reactive state — no DOM access, constructible anywhere, including on the server and outside component initialization.