@doeixd/machine 0.0.12 → 0.0.17

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
@@ -112,6 +132,29 @@ counter.increment();
 console.log(counter.context.count); // 1 (mutated in place)
 ```
 
+### Smart State Creation with `state()`
+
+The `state()` function automatically chooses between traditional and functional patterns:
+
+```typescript
+import { state } from "@doeixd/machine";
+
+// Traditional pattern (like createMachine)
+const counter1 = state({ count: 0 }, {
+  increment() { return state({ count: this.context.count + 1 }, this); }
+});
+
+// Functional pattern (like createFunctionalMachine)
+const createCounter = state({ count: 0 });
+const counter2 = createCounter({
+  increment: ctx => ({ count: ctx.count + 1 }),
+  add: (ctx, n: number) => ({ count: ctx.count + n })
+});
+
+console.log(counter1.increment().context.count); // 1
+console.log(counter2.increment().add(5).context.count); // 6
+```
+
 This shows the **flexibility** of the library: immutability is the default pattern because it's safer, but you can choose mutability when it makes sense for your use case.
 
 ### Type-State Programming (Compile-Time State Safety)
@@ -390,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 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.
+Creates a synchronous state machine from a context and transition functions.
 
 ```typescript
 const machine = createMachine(
@@ -405,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.).
@@ -412,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 });
       }
     }
-  }
+  })
 );
 ```