0
# XState
1

2
XState is a comprehensive state management and orchestration library for JavaScript and TypeScript applications that enables developers to model complex application logic using finite state machines, statecharts, and the actor model. Built with zero dependencies, it provides predictable, robust, and visual ways to handle application workflow state through event-driven programming paradigms.
3

4
## Package Information
5

6
- **Package Name**: xstate
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install xstate`
10

11
## Core Imports
12

13
```typescript
14
import { createMachine, createActor, setup } from "xstate";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createMachine, createActor, setup } = require("xstate");
21
```
22

23
Entry point specific imports:
24

25
```typescript
26
// Actions
27
import { assign, raise, sendTo, spawnChild } from "xstate/actions";
28

29
// Actors  
30
import { fromCallback, fromPromise, fromObservable } from "xstate/actors";
31

32
// Guards
33
import { and, or, not, stateIn } from "xstate/guards";
34

35
// Graph utilities
36
import { createTestModel, getShortestPaths } from "xstate/graph";
37

38
// Development tools
39
import { devToolsAdapter } from "xstate/dev";
40
```
41

42
## Basic Usage
43

44
```typescript
45
import { createMachine, createActor, assign } from "xstate";
46

47
// Define a state machine
48
const toggleMachine = createMachine({
49
  id: "toggle",
50
  initial: "inactive", 
51
  context: { count: 0 },
52
  states: {
53
    inactive: {
54
      on: {
55
        TOGGLE: {
56
          target: "active",
57
          actions: assign({ count: ({ context }) => context.count + 1 })
58
        }
59
      }
60
    },
61
    active: {
62
      on: {
63
        TOGGLE: {
64
          target: "inactive", 
65
          actions: assign({ count: ({ context }) => context.count + 1 })
66
        }
67
      }
68
    }
69
  }
70
});
71

72
// Create and start an actor
73
const actor = createActor(toggleMachine);
74
actor.start();
75

76
// Subscribe to state changes
77
actor.subscribe((snapshot) => {
78
  console.log("State:", snapshot.value);
79
  console.log("Context:", snapshot.context);
80
});
81

82
// Send events
83
actor.send({ type: "TOGGLE" });
84
```
85

86
## Architecture
87

88
XState is built around several key architectural patterns:
89

90
- **State Machines**: Finite state machines and statecharts for modeling application logic with explicit states and transitions
91
- **Actor Model**: Self-contained actors that encapsulate state and behavior, communicating through message passing
92
- **Event-Driven Programming**: All state changes happen through discrete events, ensuring predictable state transitions
93
- **Type Safety**: Full TypeScript integration with static type checking for states, events, context, and actions
94
- **Zero Dependencies**: Self-contained library with no external runtime dependencies
95

96
## Capabilities
97

98
### State Machine Creation
99

100
Core functionality for creating and configuring state machines with states, transitions, guards, and actions.
101

102
```typescript { .api }
103
function createMachine<
104
  TContext,
105
  TEvent extends { type: string },
106
  TActor = any,
107
  TAction = any,
108
  TGuard = any,
109
  TDelay = string,
110
  TTag = string,
111
  TInput = any,
112
  TOutput = any
113
>(
114
  config: MachineConfig<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag, TInput, TOutput>
115
): StateMachine<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag, TInput, TOutput>;
116

117
function setup<T extends SetupTypes>(
118
  implementations: T
119
): {
120
  createMachine<TConfig extends MachineConfig<any, any>>(
121
    config: TConfig
122
  ): StateMachine</* type parameters */>;
123
};
124
```
125

126
[State Machines](./state-machines.md)
127

128
### Actor Management  
129

130
Actor system for creating, managing, and communicating with stateful actors that run state machines and other logic.
131

132
```typescript { .api }
133
function createActor<TLogic extends AnyActorLogic>(
134
  logic: TLogic,
135
  options?: ActorOptions<TLogic>
136
): Actor<TLogic>;
137

138
class Actor<TLogic extends AnyActorLogic> {
139
  start(): void;
140
  stop(): void;
141
  send(event: EventFromLogic<TLogic>): void;
142
  subscribe(observer: Observer<SnapshotFrom<TLogic>>): Subscription;
143
  getSnapshot(): SnapshotFrom<TLogic>;
144
}
145
```
146

147
[Actors](./actors.md)
148

149
### Built-in Actions
150

151
Comprehensive set of built-in actions for context assignment, event handling, actor communication, and lifecycle management.
152

153
```typescript { .api }
154
function assign<TContext, TExpressionEvent extends { type: string }>(
155
  assignment: Assigner<TContext, TExpressionEvent> | PartialAssigner<TContext, TExpressionEvent>
156
): ActionFunction<TContext, TExpressionEvent>;
157

158
function raise<TEvent extends { type: string }>(
159
  eventOrExpr: TEvent | ((args: ActionArgs<any, any>) => TEvent),
160
  options?: { id?: string; delay?: number }
161
): ActionFunction<any, any>;
162

163
function sendTo<TTargetActor extends AnyActorRef, TEvent extends { type: string }>(
164
  actor: TTargetActor | string | ((args: ActionArgs<any, any>) => TTargetActor | string),
165
  eventOrExpr: TEvent | ((args: ActionArgs<any, any>) => TEvent),
166
  options?: { id?: string; delay?: number }
167
): ActionFunction<any, any>;
168
```
169

170
[Actions](./actions.md)
171

172
### Guard Predicates
173

174
Guard functions and combinators for conditional logic in state machine transitions and actions.
175

176
```typescript { .api }
177
function and<TContext, TExpressionEvent extends { type: string }>(
178
  guards: Guard<TContext, TExpressionEvent>[]
179
): GuardPredicate<TContext, TExpressionEvent>;
180

181
function or<TContext, TExpressionEvent extends { type: string }>(
182
  guards: Guard<TContext, TExpressionEvent>[]
183
): GuardPredicate<TContext, TExpressionEvent>;
184

185
function not<TContext, TExpressionEvent extends { type: string }>(
186
  guard: Guard<TContext, TExpressionEvent>
187
): GuardPredicate<TContext, TExpressionEvent>;
188

189
function stateIn<TContext, TExpressionEvent extends { type: string }>(
190
  stateValue: StateValue
191
): GuardPredicate<TContext, TExpressionEvent>;
192
```
193

194
[Guards](./guards.md)
195

196
### Graph Utilities
197

198
Testing, visualization, and analysis tools for state machines including model-based testing and path generation.
199

200
```typescript { .api }
201
function createTestModel<TLogic extends AnyActorLogic>(
202
  logic: TLogic,
203
  options?: TestModelOptions
204
): TestModel<TLogic>;
205

206
class TestModel<TLogic extends AnyActorLogic> {
207
  getShortestPaths(options?: TraversalOptions): StatePath[];
208
  getSimplePaths(options?: TraversalOptions): StatePath[]; 
209
  testPath(path: TestPath, params: TestParam): void;
210
}
211

212
function getShortestPaths<TLogic extends AnyActorLogic>(
213
  logic: TLogic,
214
  options?: TraversalOptions  
215
): StatePath[];
216
```
217

218
[Graph Utilities](./graph-utilities.md)
219

220
## Core Types
221

222
```typescript { .api }
223
interface MachineConfig<
224
  TContext,
225
  TEvent extends { type: string },
226
  TActor = any,
227
  TAction = any,
228
  TGuard = any,
229
  TDelay = string,
230
  TTag = string,
231
  TInput = any,
232
  TOutput = any
233
> {
234
  id?: string;
235
  initial?: string | InitialTransitionConfig<TContext, TEvent>;
236
  context?: TContext | ContextFactory<TContext, TEvent>;
237
  states?: StatesConfig<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag>;
238
  on?: TransitionsConfig<TContext, TEvent, TAction, TGuard, TDelay>;
239
  entry?: Actions<TContext, TEvent, TAction>;
240
  exit?: Actions<TContext, TEvent, TAction>;
241
  after?: DelayedTransitions<TContext, TEvent, TAction, TGuard, TDelay>;
242
  always?: TransitionConfigOrTarget<TContext, TEvent, TAction, TGuard>[];
243
  invoke?: InvokeConfig<TContext, TEvent, TActor>[];
244
  onDone?: TransitionConfigOrTarget<TContext, DoneStateEvent<TOutput>, TAction, TGuard>[];
245
  tags?: TTag[];
246
  description?: string;
247
  type?: "atomic" | "compound" | "parallel" | "final" | "history";
248
  output?: Mapper<TContext, TEvent, TOutput> | TOutput;
249
  meta?: MetaObject;
250
}
251

252
interface StateMachine<
253
  TContext,
254
  TEvent extends { type: string },
255
  TActor = any,
256
  TAction = any,
257
  TGuard = any,
258
  TDelay = string,
259
  TTag = string,
260
  TInput = any,
261
  TOutput = any
262
> {
263
  id: string;
264
  config: MachineConfig<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag, TInput, TOutput>;
265
  implementations: MachineImplementations<TContext, TEvent, TActor, TAction, TGuard, TDelay>;
266
  getInitialSnapshot(input?: TInput): MachineSnapshot<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag>;
267
  transition(snapshot: MachineSnapshot<any, any>, event: TEvent): MachineSnapshot<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag>;
268
}
269

270
interface MachineSnapshot<
271
  TContext,
272
  TEvent extends { type: string },
273
  TActor = any,
274
  TAction = any,
275
  TGuard = any,
276
  TDelay = string,
277
  TTag = string
278
> extends Snapshot<any> {
279
  context: TContext;
280
  value: StateValue;
281
  machine: StateMachine<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag>;
282
  matches(stateValue: StateValue): boolean;
283
  hasTag(tag: TTag): boolean;
284
  can(event: TEvent): boolean;
285
}
286

287
interface ActorRef<TSnapshot extends Snapshot<unknown>, TEvent extends { type: string }> {
288
  id: string;
289
  send(event: TEvent): void;
290
  subscribe(observer: Observer<TSnapshot>): Subscription;
291
  getSnapshot(): TSnapshot;
292
  getPersistedSnapshot(): Snapshot<unknown>;
293
}
294

295
type StateValue = string | { [key: string]: StateValue };
296

297
interface EventObject {
298
  type: string;
299
}
300

301
interface AnyEventObject extends EventObject {
302
  [key: string]: any;
303
}
304

305
type MachineContext = Record<string, any>;
306

307
interface MetaObject {
308
  [key: string]: any;
309
}
310
```
311

312
## Type Extraction Utilities
313

314
```typescript { .api }
315
type InputFrom<T> = T extends StateMachine<any, any, any, any, any, any, any, infer TInput, any> ? TInput : never;
316
type OutputFrom<T> = T extends StateMachine<any, any, any, any, any, any, any, any, infer TOutput> ? TOutput : never;
317
type StateFrom<T> = T extends StateMachine<infer TContext, infer TEvent, infer TActor, infer TAction, infer TGuard, infer TDelay, infer TTag, any, any> 
318
  ? MachineSnapshot<TContext, TEvent, TActor, TAction, TGuard, TDelay, TTag> : never;
319
type ContextFrom<T> = T extends StateMachine<infer TContext, any, any, any, any, any, any, any, any> ? TContext : never;
320
type EventFrom<T> = T extends StateMachine<any, infer TEvent, any, any, any, any, any, any, any> ? TEvent : never;
321
type SnapshotFrom<T> = T extends ActorLogic<infer TSnapshot, any, any, any, any> ? TSnapshot : never;
322
```