@doeixd/machine 0.0.17 → 0.0.19

package/README.md

@@ -8,7 +8,6 @@ A minimal, type-safe state machine library for TypeScript.
 
 > **Philosophy**: Provide minimal primitives that capture the essence of finite state machines, with maximum type safety and flexibility. **Type-State Programming** is our core paradigm—we use TypeScript's type system itself to represent finite states, making illegal states unrepresentable and invalid transitions impossible to write. The compiler becomes your safety net, catching state-related bugs before your code ever runs.
 
-> **Middleware System**: For production-ready state machines, we provide a comprehensive middleware system for cross-cutting concerns like logging, analytics, validation, error handling, and debugging. **📖 [Read the Middleware Guide](./docs/middleware.md)**
 
 ## Installation
 
@@ -41,7 +40,7 @@ An FSM is a 5-tuple: **M = (S, Σ, δ, s₀, F)** where:
 3. **Finite States**: Only a limited number of discrete configurations exist
 
 ### How `@doeixd/machine` Implements These Tenets
-
+A smiplified version of the core type / primitive:
 ```typescript
 type Machine<C extends object> = {
   context: C;  // Encodes the current state (s ∈ S)
@@ -165,11 +164,11 @@ The most powerful pattern: different machine types represent different states.
 import { createMachine, Machine } from "@doeixd/machine";
 
 // Define distinct machine types for each state
-type LoggedOut = Machine<{ status: "loggedOut" }> & {
+type LoggedOut = Machine<{ status: "loggedOut" }, {
   login: (username: string) => LoggedIn;
 };
 
-type LoggedIn = Machine<{ status: "loggedIn"; username: string }> & {
+type LoggedIn = Machine<{ status: "loggedIn"; username: string }, {
   logout: () => LoggedOut;
   viewProfile: () => LoggedIn;
 };
@@ -236,12 +235,12 @@ logout(state); // Runtime error!
 **Type-State Approach (Compile-Time Enforcement):**
 ```typescript
 // ✅ States are distinct types - compiler enforces validity
-type LoggedOut = Machine<{ status: "loggedOut" }> & {
+type LoggedOut = Machine<{ status: "loggedOut" }, {
   login: (user: string) => LoggedIn;
   // No logout method - impossible to call
 };
 
-type LoggedIn = Machine<{ status: "loggedIn"; username: string }> & {
+type LoggedIn = Machine<{ status: "loggedIn"; username: string }, {
   logout: () => LoggedOut;
   // No login method - impossible to call
 };
@@ -308,7 +307,7 @@ if (hasState(machine, "status", "success")) {
 
 #### 5. Event Type Safety
 ```typescript
-type FetchMachine = AsyncMachine<{ status: string }> & {
+type FetchMachine = AsyncMachine<{ status: string }, {
   fetch: (id: number) => Promise<FetchMachine>;
   retry: () => Promise<FetchMachine>;
 };
@@ -370,22 +369,22 @@ This shows the full power of Type-State Programming:
 
 ```typescript
 // Define the states as distinct types
-type IdleState = Machine<{ status: "idle" }> & {
+type IdleState = Machine<{ status: "idle" }, {
   fetch: (url: string) => LoadingState;
 };
 
-type LoadingState = Machine<{ status: "loading"; url: string }> & {
+type LoadingState = Machine<{ status: "loading"; url: string }, {
   cancel: () => IdleState;
   // Note: No fetch - can't start new request while loading
 };
 
-type SuccessState = Machine<{ status: "success"; data: any }> & {
+type SuccessState = Machine<{ status: "success"; data: any }, {
   refetch: () => LoadingState;
   clear: () => IdleState;
   // Note: No cancel - nothing to cancel
 };
 
-type ErrorState = Machine<{ status: "error"; error: string }> & {
+type ErrorState = Machine<{ status: "error"; error: string }, {
   retry: () => LoadingState;
   clear: () => IdleState;
 };
@@ -779,7 +778,7 @@ const tracked = withAnalytics(machine, trackEvent);
 ```typescript
 import { Context, Transitions, Event, TransitionArgs } from "@doeixd/machine";
 
-type MyMachine = Machine<{ count: number }> & {
+type MyMachine = Machine<{ count: number }, {
   add: (n: number) => MyMachine;
 };
 
@@ -819,6 +818,160 @@ function enterState(): MachineResult<{ timer: number }> {
 }
 ```
 
+### Pattern Matching
+
+**NEW**: Advanced pattern matching utilities for type-safe discrimination between machine states.
+
+The `createMatcher` function provides three complementary APIs for matching and narrowing machine types:
+
+#### Quick Example
+
+```typescript
+import { createMatcher, classCase, MachineBase } from "@doeixd/machine";
+
+// Define state machines
+class IdleMachine extends MachineBase<{ status: 'idle' }> {
+  start() { return new LoadingMachine(); }
+}
+
+class LoadingMachine extends MachineBase<{ status: 'loading' }> {
+  success(data: string) { return new SuccessMachine(data); }
+  error(err: Error) { return new ErrorMachine(err); }
+}
+
+class SuccessMachine extends MachineBase<{ status: 'success'; data: string }> {
+  reset() { return new IdleMachine(); }
+}
+
+class ErrorMachine extends MachineBase<{ status: 'error'; error: Error }> {
+  retry() { return new LoadingMachine(); }
+}
+
+// Create reusable matcher
+const match = createMatcher(
+  classCase('idle', IdleMachine),
+  classCase('loading', LoadingMachine),
+  classCase('success', SuccessMachine),
+  classCase('error', ErrorMachine)
+);
+
+type FetchMachine = IdleMachine | LoadingMachine | SuccessMachine | ErrorMachine;
+
+const machine: FetchMachine = new LoadingMachine();
+```
+
+#### API 1: Type Guards
+
+Use `match.is.<case>()` for type narrowing in conditionals:
+
+```typescript
+if (match.is.loading(machine)) {
+  // ✓ machine is narrowed to LoadingMachine
+  console.log(machine.context.startTime);
+}
+
+if (match.is.success(machine)) {
+  // ✓ machine is narrowed to SuccessMachine
+  console.log(machine.context.data);
+}
+```
+
+#### API 2: Exhaustive Pattern Matching
+
+Use `match.when(...).is(...)` for complex branching with compile-time exhaustiveness checking:
+
+```typescript
+const message = match.when(machine).is<string>(
+  match.case.idle(() => 'Ready to start'),
+  match.case.loading(() => 'Loading...'),
+  match.case.success(m => `Done: ${m.context.data}`),
+  match.case.error(m => `Error: ${m.context.error.message}`),
+  match.exhaustive // ← TypeScript error if any case is missing
+);
+```
+
+**Benefits:**
+- **Compile-time exhaustiveness** - TypeScript catches missing cases
+- **Type narrowing** - Each handler receives the narrowed machine type
+- **Reusable** - Define matcher once, use everywhere
+
+#### API 3: Simple Match
+
+Use `match(machine)` to get the matched case name:
+
+```typescript
+const stateName = match(machine); // 'idle' | 'loading' | 'success' | 'error' | null
+
+switch (stateName) {
+  case 'idle': return 'Ready';
+  case 'loading': return 'In progress';
+  case 'success': return 'Complete';
+  case 'error': return 'Failed';
+  default: return 'Unknown';
+}
+```
+
+#### Helper Functions
+
+**`classCase`** - For class-based machines (most common):
+
+```typescript
+createMatcher(
+  classCase('idle', IdleMachine),
+  classCase('loading', LoadingMachine)
+);
+```
+
+**`discriminantCase`** - For discriminated unions:
+
+```typescript
+type Context =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: string };
+
+const match = createMatcher(
+  discriminantCase<'idle', Machine<Context>, 'status', 'idle'>('idle', 'status', 'idle'),
+  discriminantCase<'loading', Machine<Context>, 'status', 'loading'>('loading', 'status', 'loading'),
+  discriminantCase<'success', Machine<Context>, 'status', 'success'>('success', 'status', 'success')
+);
+
+const machine = createMachine<Context>({ status: 'success', data: 'test' }, {});
+
+if (match.is.success(machine)) {
+  console.log(machine.context.data); // ✓ TypeScript knows data exists
+}
+```
+
+**`customCase`** - For custom predicates:
+
+```typescript
+createMatcher(
+  customCase('complex', (m): m is ComplexMachine => {
+    return m.context.value > 10 && m.context.status === 'active';
+  })
+);
+```
+
+#### Comparison with Existing Utilities
+
+| Utility | Use Case | Type Narrowing | Reusable |
+|---------|----------|----------------|----------|
+| `hasState(m, key, value)` | Single discriminant check | ✅ | ❌ |
+| `isState(m, Class)` | Single class check | ✅ | ❌ |
+| `matchMachine(m, key, handlers)` | Exhaustive matching | ✅ | ❌ |
+| `createMatcher(...)` | All of the above | ✅ | ✅ |
+
+**When to use `createMatcher`:**
+- You need to match the same states in multiple places
+- You want exhaustive pattern matching with compile-time checking
+- You're working with union types of multiple machine classes
+- You need flexible type guards for conditionals
+
+**When to use simpler utilities:**
+- One-off checks: Use `hasState` or `isState`
+- Single location matching: Use `matchMachine`
+
 ## Advanced Features
 
 ### Ergonomic & Integration Patterns
@@ -1641,8 +1794,16 @@ The extraction system uses **AST-based static analysis**:
 
 ### Static Extraction API (Build-Time)
 
+> **Tree-Shaking**: Extraction tools are in a separate entry point (`@doeixd/machine/extract`) and are NOT included in your production bundle when you import from the main package. The heavy `ts-morph` dependency (used for AST parsing) will only be included if you explicitly import from `/extract`.
+>
+> **Type Imports**: Configuration types (`MachineConfig`, `ExtractionConfig`, etc.) are available from the main package for type safety without bundle impact:
+> ```typescript
+> import type { MachineConfig, ExtractionConfig } from '@doeixd/machine';
+> ```
+
 ```typescript
-import { extractMachine, extractMachines } from '@doeixd/machine';
+// Import from the separate extract entry point (NOT included in main bundle)
+import { extractMachine, extractMachines } from '@doeixd/machine/extract';
 import { Project } from 'ts-morph';
 
 // Extract single machine