A lightweight, educational implementation of finite state machines in TypeScript, inspired by XState v5. This library is designed to help developers understand the core principles of state machines while providing a stepping stone towards using XState in production.
~1KB gzipped - Tiny footprint, full state machine functionality.
Live Examples - Interactive demos showcasing state machine patterns.
While XState is an incredibly powerful state management solution, its extensive feature set can be overwhelming when you're just getting started with state machines. This library:
- Focuses on core state machine concepts
- Provides a similar API to XState v5
- Is lightweight and easy to understand
- Includes detailed documentation and examples
- Serves as a learning tool
State machines excel at modeling systems with clear, discrete states and well-defined transitions:
- UI components - Modals, dropdowns, tooltips (open/closed/loading states)
- Multi-step forms - Wizards, checkout flows, onboarding sequences
- Authentication flows - Login, logout, session expiry, password reset
- Media players - Play, pause, stop, buffering, seeking
- Data fetching - Idle, loading, success, error states
- Game logic - Character states, turn-based mechanics, level progression
- Workflows - Approval processes, document lifecycles, order status
State machines help prevent impossible states (like a form being both "submitting" and "submitted") and make complex logic easier to reason about, test, and debug.
# Using pnpm (recommended)
pnpm add @tinystack/machine
# Using npm
npm install @tinystack/machine
# Using yarn
yarn add @tinystack/machineimport { setup, Actor } from '@tinystack/machine';
// Define your types
interface ToggleContext {
count: number;
}
type ToggleEvent =
| { type: 'TOGGLE' }
| { type: 'INCREMENT' };
// Create a typed setup - this returns createMachine and assign with full type inference
const { createMachine, assign } = setup({
types: {} as {
context: ToggleContext;
events: ToggleEvent;
}
});
// Define your machine
const toggleMachine = createMachine({
id: 'toggle',
initial: 'inactive',
context: {
count: 0
},
states: {
inactive: {
on: {
TOGGLE: { target: 'active' }
}
},
active: {
on: {
TOGGLE: { target: 'inactive' },
INCREMENT: {
actions: [
assign((context) => ({
count: context.count + 1 // Full type inference!
}))
]
}
}
}
}
});
// Create an actor to run the machine
const actor = new Actor(toggleMachine);
// Subscribe to state changes
actor.subscribe((snapshot) => {
console.log('Current state:', snapshot.value);
console.log('Context:', snapshot.context);
});
// Send events
actor.send({ type: 'TOGGLE' });
actor.send({ type: 'INCREMENT' });A state machine is a model that describes all the possible states of your application and the ways it can transition between them. This makes your application's behavior predictable and easier to understand.
Actors are the running instances of your state machines. They can:
- Receive events via
send() - Execute actions during transitions
- Maintain their own context
- Notify subscribers of changes via
subscribe() - Check current state with
matches()
Actions are side effects that occur during state transitions. The most common action is assign, which updates the machine's context:
const { createMachine, assign } = setup({
types: {} as {
context: { count: number };
events: { type: 'INCREMENT' };
}
});
const counterMachine = createMachine({
id: 'counter',
initial: 'active',
context: { count: 0 },
states: {
active: {
on: {
INCREMENT: {
actions: [
assign((context) => ({
count: context.count + 1,
}))
]
},
},
},
},
});Guards are conditions that must be met for a transition to occur:
const { createMachine, assign } = setup({
types: {} as {
context: { coins: number };
events: { type: 'INSERT_COIN' } | { type: 'PUSH' };
}
});
const turnstileMachine = createMachine({
id: 'turnstile',
initial: 'locked',
context: { coins: 0 },
states: {
locked: {
on: {
INSERT_COIN: {
target: 'unlocked',
guards: [
{
type: 'hasEnoughCoins',
condition: (context) => context.coins >= 3,
},
],
},
},
},
unlocked: {
on: {
PUSH: { target: 'locked' }
}
},
},
});Actions can also be triggered when entering or exiting a state:
const { createMachine, assign } = setup({
types: {} as {
context: { elapsed: number };
events: { type: 'START' } | { type: 'STOP' };
}
});
const timerMachine = createMachine({
id: 'timer',
initial: 'idle',
context: { elapsed: 0 },
states: {
idle: {
on: { START: { target: 'running' } }
},
running: {
entry: [
{ type: 'startTimer', exec: () => console.log('Timer started') }
],
exit: [
{ type: 'stopTimer', exec: () => console.log('Timer stopped') }
],
on: { STOP: { target: 'idle' } }
},
},
});This library implements a subset of XState's features, focusing on the most important concepts:
✅ Included:
setup()pattern for type-safe machine creation- Basic state transitions
- Context management
- Actions (assign, entry, exit, transition actions)
- Guards
- Event handling
- State subscription
- Snapshot caching
❌ Not included (available in XState):
- Spawned actors / actor system
- Invoked services
- Delayed transitions
- Parallel states
- History states
- State visualization
- Development tools
Use this library when:
- Learning state machine concepts
- Building simple state-driven applications
- Teaching others about state machines
- Prototyping before moving to XState
Use XState when:
- Building production applications
- Needing advanced features
- Requiring visualization tools
- Working with complex state orchestration
- Needing actor model capabilities
Contributions are welcome! This library aims to be educational, so we prioritize:
- Clear, well-documented code
- Simple, focused features
- Educational examples
- Good test coverage
MIT
This library is inspired by XState and serves as an educational tool for understanding its concepts. Special thanks to the XState team for their excellent work in making state machines accessible to the JavaScript community.