Overview

Relevant source files

• CHANGELOG.md
• CLAUDE.md
• README.md
• package-lock.json
• package.json
• src/matcher.ts
• test/matcher.test.ts

This document provides a high-level introduction to the @doeixd/machine library, its Type-State Programming philosophy, architectural organization, and core execution models. It covers the library's mathematical foundations, dual-API design, module structure, and how TypeScript's type system enforces state machine safety at compile-time.

Related Pages:

• For installation and first machine examples, see Getting Started
• For detailed API reference of the Main library, see Main Library API Reference
• For detailed API reference of the Minimal library, see Minimal Library API Reference
• For information about the Actor Model, see Actor Model
• For build system details, see Build System and Distribution

---

What is @doeixd/machine?

@doeixd/machine is a minimal, type-safe state machine library for TypeScript that leverages the type system to represent finite states as distinct types rather than string values. The library is built on formal FSM (Finite State Machine) theory and provides multiple APIs and patterns to suit different development preferences and use cases.

Key Characteristics:

• Type-State Programming: States are TypeScript types, not runtime strings
• Compile-time Safety: Invalid state transitions are caught by the compiler
• Dual-API Design: Choose between feature-rich Main library or zero-boilerplate Minimal API
• Mathematical Foundations: Implements formal FSM theory (5-tuple definition)
• Flexible Runtime Models: Direct usage, Actor Model (queue-based), or Runner Pattern (cancellation-based)
• Framework Integration: React and Solid.js bindings available

Package Information:

• Package: @doeixd/machine
• Version: 1.3.0
• License: MIT
• Repository: https://github.com/doeixd/machine

Sources: package.json1-178 README.md1-100 CLAUDE.md1-20

---

Core Philosophy: Type-State Programming

The fundamental paradigm of @doeixd/machine is Type-State Programming, where different states are represented as distinct TypeScript types rather than string literals or enums. This allows the compiler to enforce state validity at compile-time, making illegal states unrepresentable.

Traditional vs Type-State Approach

Aspect	Traditional (String-Based)	Type-State Programming
State Representation	"idle", "loading", "success"	IdleMachine, LoadingMachine, SuccessMachine
Validation	Runtime checks (if (state === "idle"))	Compile-time (type system)
Transition Safety	No enforcement	Compiler prevents invalid transitions
Available Actions	All methods available, must check state first	Only valid methods available per state type
Data Access	May access undefined properties	Type system ensures properties exist
Bug Detection	At runtime (production)	At compile-time (development)

How TypeScript Enforces Safety

The compiler prevents:

1. Invalid transitions: Can't call logout() on LoggedOut type
2. Invalid data access: Can't access username on LoggedOut type
3. Incomplete pattern matching: Must handle all states exhaustively
4. Wrong event arguments: Event types are inferred from machine definition

Sources: README.md249-467 CLAUDE.md512-533

---

Mathematical Foundations: Finite State Machines

The library implements formal FSM theory. A finite state machine is defined as a 5-tuple: M = (S, Σ, δ, s₀, F)

Formal Components:

Component	Mathematical Symbol	Implementation in @doeixd/machine
States	S (finite set)	Machine<C> types and context property
Input Alphabet	Σ (event set)	Transition method names (increment, login, fetch)
Transition Function	δ : S × Σ → S	Methods returning new Machine<C> instances
Initial State	s₀	Initial context passed to createMachine()
Accepting States	F (optional)	Not enforced, but representable via types

Core Type Definition

Key FSM Properties:

• Determinism: Each transition function yields exactly one next state
• Markov Property: Next state depends only on current context and input (no hidden state)
• Finite States: Only a defined set of configurations exist

Sources: README.md22-60 CLAUDE.md23-60

---

Dual-API Architecture: Main vs Minimal

The library provides two distinct APIs serving different developer preferences and use cases. Both share the same underlying type system and principles but differ in syntax, boilerplate, and feature richness.

Architectural Diagram

Sources: package.json100-155 Diagram 1, Diagram 4

Main Library Features

Purpose: Feature-rich API with utilities for composition, decoration, and advanced patterns.

Key Exports (from src/index.ts):

• createMachine<C, T>(context, transitions) - Primary factory function
• createAsyncMachine<C, T>(context, transitions) - For async state machines
• MachineBase<C> - OOP base class for Type-State machines
• createMachineFactory<C>() - Higher-order factory pattern
• Utilities: setContext(), overrideTransitions(), extendTransitions()
• Type extractors: Context<M>, Transitions<M>, Event<M>

Use When:

• You need composition utilities (override, extend, merge)
• You want OOP-style class-based machines
• You need async machines with side effects
• You want comprehensive utility functions

Sources: src/index.ts README.md469-869 CLAUDE.md85-95

Minimal API Features

Purpose: Zero-boilerplate functional API with perfect type inference and YAGNI philosophy.

Key Exports (from src/minimal.ts):

• machine(context, transitions) - One-off inline machines
• factory(context) - Single-state machine templates with inference
• union(factories) - Multi-state discriminated union machines
• tag(), tag.factory() - Tagged union helpers
• States<T> - Ergonomic type utility
• runnable(), run() - Lifecycle and effects

Use When:

• You want zero boilerplate and maximum inference
• You prefer functional, declarative style
• You don't need composition utilities (yet)
• Simplicity and directness are priorities

Sources: src/minimal.ts README.md1-100 Diagram 1

Comparison Table

Feature	Main Library	Minimal API
Entry Point	@doeixd/machine	@doeixd/machine/minimal
Boilerplate	Moderate	Zero (perfect inference)
Style	OOP + Functional	Pure Functional
Composition	Rich utilities	Manual or use withChildren
Async Support	createAsyncMachine()	Via runnable() pattern
Type Safety	Full	Full (equivalent)
Bundle Size Impact	Larger API surface	Smaller footprint

Sources: README.md1-100 CLAUDE.md85-110 Diagram 1

---

Module Structure and Entry Points

The library is organized into focused, tree-shakeable modules accessible via subpath exports. Each module serves a specific purpose and can be imported independently.

Entry Points Diagram

Sources: package.json100-177 Diagram 2

Module Purposes

Entry Point	Purpose	Key Exports	Import Cost
@doeixd/machine	Full Main library	createMachine, MachineBase, all utilities	~26 kB
@doeixd/machine/core	Core subset only	Machine<C> type, createMachine basic	Smaller
@doeixd/machine/minimal	Minimal API	machine(), factory(), union(), tag()	~8-12 kB
@doeixd/machine/delegate	Delegation pattern	delegate(), delegateAll()	Small
@doeixd/machine/react	React integration	useMachine(), useActor(), createMachineContext()	Depends on React
@doeixd/machine/extract	Statechart extraction	extractMachine(), extractMachines()	~8 kB (separate chunk)

Key Design Decision: The extraction tools (src/extract.ts) are not exported from the main entry point. They require the heavy ts-morph dependency (~200+ kB) and are only needed at build-time, not in production. This keeps the production bundle small.

Sources: package.json100-177 CLAUDE.md574-586

File Organization

Sources: CLAUDE.md80-179 Diagram 2

---

Runtime Execution Models

The library supports three distinct execution models for different use cases. Each model provides different semantics for how events are processed and state changes are managed.

Execution Models Comparison

Sources: Diagram 7, docs/actor.md CLAUDE.md550-570

Model Characteristics

Aspect	Direct Usage	Actor Model	Runner Pattern
Event Handling	Immediate call	Queued (FIFO)	Cancel + replace
Semantics	Synchronous	All complete	Latest-wins
Concurrency	None	Sequential	Cancellation-based
State Access	Via reference	actor.getSnapshot()	runner.state
Observers	Manual	actor.subscribe()	Single onChange
Async Support	Manual	Built-in	Built-in
Use Cases	Simple counters	Payments, persistence	Search, tab switching

Sources: Diagram 7, docs/actor.md src/actor.ts src/runner.ts

Direct Usage

Implementation: Simply call transition methods on the machine instance.

Example Pattern:

Use When:

• State changes are synchronous
• No external async operations
• Simple, predictable flows
• Testing (easy to mock/override)

Sources: README.md72-160

Actor Model (createActor)

Implementation: Wraps machine in actor runtime with mailbox queue (src/actor.ts).

Key Functions:

• createActor(machine) - Creates actor instance
• actor.send(event) - Enqueues event
• actor.subscribe(listener) - Observes changes
• actor.getSnapshot() - Gets current state
• Actor.inspect(callback) - Global debugging

Semantics:

• All events are processed sequentially
• Each event waits for previous to complete
• Observable pattern with multiple subscribers
• Guaranteed order of operations

Use When:

• All operations must complete (e.g., payment processing)
• Order of operations matters (e.g., audit logs)
• Multiple observers need notifications
• Need global inspection/debugging

Sources: src/actor.ts docs/actor.md Diagram 7

Runner Pattern (runMachine)

Implementation: Async machine runner with cancellation (src/runner.ts).

Key Functions:

• runMachine(machine, onChange) - Creates runner
• runner.dispatch(event) - Dispatches event (cancels previous)
• runner.state - Current context (readonly)

Semantics:

• Latest event wins (previous operations cancelled)
• Uses AbortSignal for cancellation
• Single onChange callback
• Optimized for UI scenarios

Use When:

• Only latest result matters (e.g., search autocomplete)
• Previous operations should be cancelled (e.g., tab switching)
• Simple callback-based updates
• UI state synchronization

Sources: src/runner.ts README.md565-585 Diagram 7

---

Type System Architecture

The library leverages TypeScript's advanced type features to provide compile-time safety. The type system is the core mechanism for enforcing state machine validity.

Type System Components

Sources: src/index.ts src/matcher.ts1-120 CLAUDE.md558-572

Core Type Definitions

Machine<C, T> (src/index.ts):

Context<M> - Extracts context type from machine:

Transitions<M> - Extracts transition methods:

Event<M> - Generates discriminated union of events:

This automatically creates type-safe event objects like:

Sources: src/index.ts README.md906-950 CLAUDE.md558-572

Type-Level Enforcement

The type system prevents these categories of errors at compile-time:

1. Invalid State Transitions: Can't call methods that don't exist on current state type
2. Invalid Data Access: Can't access properties that don't exist on current context
3. Non-Exhaustive Pattern Matching: Must handle all cases in match.when().is()
4. Wrong Event Arguments: Event types enforce correct argument types
5. Type Narrowing: Guards like hasState() narrow types automatically

Example from tests (test/matcher.test.ts100-112):

Sources: README.md249-467 test/matcher.test.ts1-730 src/matcher.ts1-561

---

Build System and Distribution

The library uses pridepack as its build tool, which provides zero-config bundling for TypeScript libraries. The build outputs multiple formats for maximum compatibility.

Build Configuration

Build Tool: pridepack (v2.6.4)

Output Formats:

• CommonJS: dist/cjs/production/*.js and dist/cjs/development/*.js
• ES Modules: dist/esm/production/*.js and dist/esm/development/*.js
• TypeScript Declarations: dist/types/*.d.ts

Entry Points Mapping (package.json100-155):

@doeixd/machine           → dist/{cjs,esm}/{dev,prod}/index.js
@doeixd/machine/core      → dist/{cjs,esm}/{dev,prod}/core.js
@doeixd/machine/extract   → dist/{cjs,esm}/{dev,prod}/extract.js
@doeixd/machine/minimal   → dist/{cjs,esm}/{dev,prod}/minimal.js
@doeixd/machine/delegate  → dist/{cjs,esm}/{dev,prod}/delegate.js
@doeixd/machine/react     → dist/{cjs,esm}/{dev,prod}/react.js

Sources: package.json96-155 CLAUDE.md568-586

Build Scripts

Command	Purpose	Implementation
npm run build	Build all formats	pridepack build
npm run watch	Development mode	pridepack watch
npm run type-check	Type checking only	pridepack check
npm run clean	Remove build artifacts	pridepack clean
npm test	Run test suite	vitest run

Sources: package.json67-81

Tree-Shaking Strategy

The library is marked as side-effect free ("sideEffects": false in package.json99) to enable aggressive tree-shaking. Key strategies:

1. Separate Extract Bundle: The heavy ts-morph dependency (~200+ kB) is isolated in @doeixd/machine/extract, not imported by the main bundle
2. Modular Entry Points: Each submodule can be imported independently
3. Type-Only Exports: Configuration types like MachineConfig are exported type-only from main entry

Bundle Sizes (approximate):

• Main library (@doeixd/machine): ~26 kB
• Minimal API (@doeixd/machine/minimal): ~8-12 kB
• Extract tools (@doeixd/machine/extract): ~8 kB + ts-morph (~200 kB, usually dev-only)

Sources: package.json99 CLAUDE.md574-586

Distribution

Sources: package.json67-81 package.json96-155 CLAUDE.md568-586

---

Summary

@doeixd/machine is a type-safe state machine library built on formal FSM theory and centered around Type-State Programming. Key takeaways:

1. Type-State Programming: States are types, compiler catches bugs at compile-time
2. Dual APIs: Choose between feature-rich Main library or zero-boilerplate Minimal API
3. Modular Architecture: Tree-shakeable submodules for different needs
4. Multiple Runtime Models: Direct usage, Actor (queue), or Runner (cancellation)
5. Advanced Type System: Full TypeScript inference and exhaustive checking
6. Production-Ready: Multiple output formats, framework integrations, and build-time tools

For detailed API documentation, see Main Library API Reference and Minimal Library API Reference. For framework-specific guides, see Framework Integrations.

Sources: README.md1-100 CLAUDE.md1-40 package.json1-178