Handlers are functions executed when entering or exiting a state:
- onEnter: Runs when entering a state
- onExit: Runs when leaving a state

Both handlers receive the current context and optional payload data.

$3

Events provide a way to respond to external triggers without changing the state. Event handlers can modify the context.

API Reference

$3

`typescript
createMachine(
initialState: TState,
stateConfig: StateConfig,
initialContext?: TContext,
options?: MachineOptions
): ChainableStateMachine
`

Creates a new state machine instance.

#### Parameters:

- initialState: The starting state of the machine.
- stateConfig: Configuration object defining states, transitions, and handlers.
- initialContext: (Optional) Initial context data.
- options: (Optional) Machine configuration options.

#### Return value:

A chainable state machine instance.

$3

Configuration defining states, their allowed transitions, and handlers.

`typescript
type StateConfig = {
[key in TState]?: {
transitions: TState[];
onEnter?: (context: TContext, payload?: unknown) => void;
onExit?: (context: TContext, payload?: unknown) => void;
};
};
`

$3

Options for customizing the state machine.

`typescript
interface MachineOptions {
enableHistory?: boolean; // Whether to track transition history
historySize?: number; // Maximum size of history (default: 100)
onTransition?: TransitionListener; // Global transition listener
}
`

$3

The state machine instance returned by createMachine provides these methods:

#### State Management
- moveTo(state, payload?): Transitions to a new state with optional payload
- isIn(state): Checks if the machine is in a specific state
- canMoveTo(state): Checks if a transition to the given state is valid
- resetContext(): Resets context to initial values

#### Getters
- current: Current state value (readonly)
- context: Current context object (readonly)
- getStore(): Returns the Valtio store for use with useSnapshot

#### Listeners
- onTransition(listener): Registers a transition listener
- whenIn(state, callback): Registers a callback for a specific state
- onContextChange(listener): Registers a context change listener

#### History
- getHistory(): Returns the transition history
- clearHistory(): Clears the transition history
- enableHistory(enable?): Enables or disables history tracking
- setHistorySize(size): Sets the maximum history size

#### Dynamic Configuration
- setTransitions(state, transitions): Sets allowed transitions for a state
- addTransition(state, transition): Adds a single transition to a state
- removeTransition(state, transition): Removes a transition from a state
- setHandler(state, type, handler): Sets an onEnter or onExit handler

#### Event System
- on(eventName, handler): Registers an event handler
- once(eventName, handler): Registers a one-time event handler
- off(eventName, handler?): Removes an event handler
- fire(eventName, payload?): Fires an event

Advanced Examples

$3

`typescript
import { createMachine } from 'valtio-fsm';
import { snapshot } from 'valtio';

// Define a more complex context
type UserContext = {
isAuthenticated: boolean;
profile: {
name: string;
email: string;
preferences: {
theme: 'light' | 'dark';
notifications: boolean;
};
};
lastLogin: Date | null;
};

const authMachine = createMachine<'guest' | 'authenticated', UserContext>(
'guest',
{
guest: {
transitions: ['authenticated'],
onExit: (ctx, userData) => {
// Update context when transitioning from guest to authenticated
Object.assign(ctx.profile, userData);
ctx.isAuthenticated = true;
ctx.lastLogin = new Date();
}
},
authenticated: {
transitions: ['guest'],
onExit: (ctx) => {
// Clear sensitive data when logging out
ctx.isAuthenticated = false;
}
}
},
{
isAuthenticated: false,
profile: {
name: '',
email: '',
preferences: {
theme: 'light',
notifications: true
}
},
lastLogin: null
}
);

// Track context changes
authMachine.onContextChange((context, changes) => {
console.log('Context updated:', changes);

// You could persist changes to localStorage here
localStorage.setItem('userPreferences', JSON.stringify(context.profile.preferences));
});

// Login
authMachine.moveTo('authenticated', {
name: 'John Doe',
email: 'john@example.com'
});

// Update preferences - this will trigger the context change listener
authMachine.getStore().context.profile.preferences.theme = 'dark';

// Get an immutable snapshot for comparison or debugging
const currentSnapshot = snapshot(authMachine.getStore());
console.log(currentSnapshot);

// Reset to initial state and context
authMachine.moveTo('guest').resetContext();
`

$3

`typescript
import { createMachine } from 'valtio-fsm';

type TodoState = 'idle' | 'loading' | 'error';
type TodoContext = {
items: { id: number; text: string; completed: boolean }[];
error: string | null;
filter: 'all' | 'active' | 'completed';
};

const todoMachine = createMachine(
'idle',
{
idle: { transitions: ['loading', 'error'] },
loading: { transitions: ['idle', 'error'] },
error: { transitions: ['idle'] }
},
{
items: [],
error: null,
filter: 'all'
}
);

// Register event handlers
todoMachine
.on('add', (ctx, text) => {
ctx.items.push({
id: Date.now(),
text: String(text),
completed: false
});
})
.on('toggle', (ctx, id) => {
const item = ctx.items.find(item => item.id === id);
if (item) {
item.completed = !item.completed;
}
})
.on('remove', (ctx, id) => {
ctx.items = ctx.items.filter(item => item.id !== id);
})
.on('setFilter', (ctx, filter) => {
ctx.filter = filter;
})
.on('clearCompleted', (ctx) => {
ctx.items = ctx.items.filter(item => !item.completed);
});

// Register one-time event handler
todoMachine.once('initialize', (ctx, initialItems) => {
ctx.items = initialItems || [];
});

// Fire events
todoMachine.fire('add', 'Learn Valtio FSM');
todoMachine.fire('add', 'Build an awesome app');
todoMachine.fire('toggle', todoMachine.context.items[0].id);
todoMachine.fire('setFilter', 'active');
`

$3

`typescript
import { createMachine } from 'valtio-fsm';

type EditorState = 'view' | 'edit' | 'preview' | 'locked';
type EditorContext = {
content: string;
permissions: {
canEdit: boolean;
canDelete: boolean;
};
lastModified: Date | null;
};

// Create with minimal config, build it dynamically
const editorMachine = createMachine(
'view',
{
view: { transitions: ['edit'] }
},
{
content: '',
permissions: {
canEdit: false,
canDelete: false
},
lastModified: null
}
);

// Dynamically add states, transitions and handlers
editorMachine
.addTransition('view', 'locked')
.addTransition('edit', 'preview')
.addTransition('edit', 'view')
.addTransition('preview', 'edit')
.addTransition('preview', 'view')
.addTransition('locked', 'view')

.setHandler('edit', 'onEnter', (ctx) => {
// Save original content for undo
ctx._originalContent = ctx.content;
})

.setHandler('edit', 'onExit', (ctx) => {
// Update last modified timestamp
ctx.lastModified = new Date();
});

// Update transitions based on permissions
function updatePermissions(canEdit: boolean, canDelete: boolean) {
editorMachine.getStore().context.permissions = { canEdit, canDelete };

// If user can't edit, remove edit transition
if (!canEdit) {
editorMachine.removeTransition('view', 'edit');
} else {
editorMachine.addTransition('view', 'edit');
}
}
`

$3

`tsx
import { createMachine } from 'valtio-fsm';
import { useSnapshot } from 'valtio';
import { useState, useEffect } from 'react';

type WizardState = 'step1' | 'step2' | 'step3' | 'complete';
type WizardContext = {
formData: {
name: string;
email: string;
plan: string;
agreeToTerms: boolean;
};
validationErrors: Record;
};

const wizardMachine = createMachine(
'step1',
{
step1: {
transitions: ['step2'],
onExit: (ctx) => validateStep1(ctx)
},
step2: {
transitions: ['step1', 'step3'],
onExit: (ctx) => validateStep2(ctx)
},
step3: {
transitions: ['step2', 'complete'],
onExit: (ctx) => validateStep3(ctx)
},
complete: {
transitions: []
}
},
{
formData: {
name: '',
email: '',
plan: '',
agreeToTerms: false
},
validationErrors: {}
}
);

// Validation functions
function validateStep1(ctx) {
const errors = {};
if (!ctx.formData.name) errors.name = 'Name is required';
if (!ctx.formData.email) errors.email = 'Email is required';
ctx.validationErrors = errors;
return Object.keys(errors).length === 0;
}

function validateStep2(ctx) {
const errors = {};
if (!ctx.formData.plan) errors.plan = 'Please select a plan';
ctx.validationErrors = errors;
return Object.keys(errors).length === 0;
}

function validateStep3(ctx) {
const errors = {};
if (!ctx.formData.agreeToTerms) {
errors.agreeToTerms = 'You must agree to terms';
}
ctx.validationErrors = errors;
return Object.keys(errors).length === 0;
}

// React wizard component
function Wizard() {
const snap = useSnapshot(wizardMachine.getStore());

function handleNext() {
const currentState = wizardMachine.current;
if (currentState === 'step1') wizardMachine.moveTo('step2');
else if (currentState === 'step2') wizardMachine.moveTo('step3');
else if (currentState === 'step3') wizardMachine.moveTo('complete');
}

function handleBack() {
const currentState = wizardMachine.current;
if (currentState === 'step2') wizardMachine.moveTo('step1');
else if (currentState === 'step3') wizardMachine.moveTo('step2');
}

function updateFormData(field, value) {
wizardMachine.getStore().context.formData[field] = value;
}

return (