@doeixd/machine 0.0.13 → 0.0.18

package/README.md

@@ -67,24 +67,24 @@ The library offers multiple patterns for different use cases. **📖 [Pattern De
 
 ## Quick Start
 
-### Basic Counter (Simple State)
+### Basic Counter (Functional Builder Pattern)
 
-**Immutable approach (recommended):**
+**Recommended approach (type-safe and ergonomic):**
 
 ```typescript
 import { createMachine } from "@doeixd/machine";
 
 const counter = createMachine(
   { count: 0 }, // Initial state (s₀)
-  {
-    // Transitions (δ)
-    increment: function() {
-      return createMachine({ count: this.count + 1 }, this);
+  (next) => ({
+    // Transitions (δ) - `this` is automatically typed
+    increment() {
+      return next({ count: this.count + 1 });
     },
-    add: function(n: number) {
-      return createMachine({ count: this.count + n }, this);
+    add(n: number) {
+      return next({ count: this.count + n });
     }
-  }
+  })
 );
 
 const next = counter.increment();
@@ -94,6 +94,26 @@ console.log(next.context.count); // 1
 console.log(counter.context.count); // 0
 ```
 
+**Benefits:**
+- **Type-safe**: Full TypeScript inference for `this` context
+- **Ergonomic**: No need to manually pass transition objects
+- **Clean**: Automatic binding and context inference
+- **Composable**: Transitions are automatically available on all returned machines
+
+**Traditional approach (also supported):**
+
+```typescript
+const transitions = {
+  increment: function() {
+    return createMachine({ count: this.count + 1 }, transitions);
+  },
+  add: function(n: number) {
+    return createMachine({ count: this.count + n }, transitions);
+  }
+};
+const counter = createMachine({ count: 0 }, transitions);
+```
+
 **Mutable approach (also supported):**
 
 ```typescript
@@ -145,11 +165,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;
 };
@@ -216,12 +236,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
 };
@@ -288,7 +308,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>;
 };
@@ -350,22 +370,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;
 };
@@ -413,9 +433,25 @@ This is the essence of Type-State Programming: **Make illegal states unrepresent
 
 ### Machine Creation
 
-#### `createMachine<C, T>(context, transitions)`
+#### `createMachine<C, T>(context, factory)`
 
-Creates a synchronous state machine.
+Creates a synchronous state machine using the **Functional Builder** pattern. This is the recommended approach for type safety and ergonomics, as it automatically infers `this` context and binds transitions.
+
+```typescript
+const machine = createMachine({ count: 0 }, (next) => ({
+  increment() {
+    // `this` is correctly inferred as Context
+    return next({ count: this.count + 1 });
+  },
+  add(n: number) {
+    return next({ count: this.count + n });
+  }
+}));
+```
+
+#### `createMachine<C, T>(context, transitions)` (Traditional)
+
+Creates a synchronous state machine from a context and transition functions.
 
 ```typescript
 const machine = createMachine(
@@ -428,6 +464,22 @@ const machine = createMachine(
 );
 ```
 
+#### `createMachine<C, T>(context, factory)`
+
+Creates a synchronous state machine using the **Functional Builder** pattern. This is the recommended approach for type safety and ergonomics, as it automatically infers `this` context and binds transitions.
+
+```typescript
+const machine = createMachine({ count: 0 }, (transition) => ({
+  increment() {
+    // `this` is correctly inferred as Context
+    return transition({ count: this.count + 1 });
+  },
+  add(n: number) {
+    return transition({ count: this.count + n });
+  }
+}));
+```
+
 #### `createAsyncMachine<C, T>(context, transitions)`
 
 Creates an async state machine (for side effects, API calls, etc.).
@@ -435,16 +487,16 @@ Creates an async state machine (for side effects, API calls, etc.).
 ```typescript
 const machine = createAsyncMachine(
   { status: "idle", data: null },
-  {
+  (next) => ({
     async fetch() {
       try {
         const data = await api.getData();
-        return createAsyncMachine({ status: "success", data }, this);
+        return next({ status: "success", data });
       } catch (error) {
-        return createAsyncMachine({ status: "error", data: null }, this);
+        return next({ status: "error", data: null });
       }
     }
-  }
+  })
 );
 ```
 
@@ -727,7 +779,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;
 };