@doeixd/machine 0.0.23 → 1.0.1

package/README.md

@@ -76,12 +76,12 @@ import { createMachine } from "@doeixd/machine";
 const counter = createMachine(
   { count: 0 }, // Initial state (s₀)
   (next) => ({
-    // Transitions (δ) - `this` is automatically typed
+    // Transitions (δ) - access state via this.context
     increment() {
-      return next({ count: this.count + 1 });
+      return next({ count: this.context.count + 1 });
     },
     add(n: number) {
-      return next({ count: this.count + n });
+      return next({ count: this.context.count + n });
     }
   })
 );
@@ -104,10 +104,10 @@ console.log(counter.context.count); // 0
 ```typescript
 const transitions = {
   increment: function() {
-    return createMachine({ count: this.count + 1 }, transitions);
+    return createMachine({ count: this.context.count + 1 }, transitions);
   },
   add: function(n: number) {
-    return createMachine({ count: this.count + n }, transitions);
+    return createMachine({ count: this.context.count + n }, transitions);
   }
 };
 const counter = createMachine({ count: 0 }, transitions);
@@ -161,49 +161,84 @@ This shows the **flexibility** of the library: immutability is the default patte
 The most powerful pattern: different machine types represent different states.
 
 ```typescript
-import { createMachine, Machine } from "@doeixd/machine";
+import { MachineBase } from "@doeixd/machine";
 
-// Define distinct machine types for each state
-type LoggedOut = Machine<{ status: "loggedOut" }, {
-  login: (username: string) => LoggedIn;
-};
+/**
+ * Type-State Programming with classes:
+ * - Each distinct class *is* a distinct state.
+ * - The methods on that class are the only valid transitions from that state.
+ * - Returning a different class type moves you to a different state (at compile time).
+ */
 
-type LoggedIn = Machine<{ status: "loggedIn"; username: string }, {
-  logout: () => LoggedOut;
-  viewProfile: () => LoggedIn;
-};
+/** "LoggedOut" state: only transitions available are methods on this class. */
+class LoggedOut extends MachineBase<{ status: "loggedOut" }> {
+  constructor() {
+    // MachineBase stores state data in `this.context`
+    super({ status: "loggedOut" });
+  }
 
-// Create factory functions
-const createLoggedOut = (): LoggedOut => {
-  return createMachine({ status: "loggedOut" }, {
-    login: function(username: string): LoggedIn {
-      return createLoggedIn(username);
-    }
-  });
-};
+  /**
+   * Transition: LoggedOut -> LoggedIn
+   * Notice: there's no `logout()` method here, so you literally cannot call it.
+   */
+  login(username: string): LoggedIn {
+    return new LoggedIn(username);
+  }
+}
 
-const createLoggedIn = (username: string): LoggedIn => {
-  return createMachine({ status: "loggedIn", username }, {
-    logout: function(): LoggedOut {
-      return createLoggedOut();
-    },
-    viewProfile: function(): LoggedIn {
-      console.log(`Viewing ${this.username}'s profile`);
-      return this;
-    }
-  });
-};
+/** "LoggedIn" state: different data + different allowed transitions. */
+class LoggedIn extends MachineBase<{ status: "loggedIn"; username: string }> {
+  constructor(username: string) {
+    // Context shape changes in this state (now includes `username`)
+    super({ status: "loggedIn", username });
+  }
+
+  /**
+   * Transition: LoggedIn -> LoggedOut
+   * This exists only on LoggedIn, so you cannot log out unless you're logged in.
+   */
+  logout(): LoggedOut {
+    return new LoggedOut();
+  }
 
-// Usage
-const machine = createLoggedOut();
+  /**
+   * Transition: LoggedIn -> LoggedIn (self-transition)
+   * Returning `this` means "stay in the same state".
+   */
+  viewProfile(): LoggedIn {
+    // With MachineBase, context lives under `this.context`
+    console.log(`Viewing ${this.context.username}'s profile`);
+    return this;
+  }
+}
+
+// -------------------- Usage --------------------
 
-// TypeScript prevents invalid transitions at compile time!
-// machine.logout(); // ❌ Error: Property 'logout' does not exist on type 'LoggedOut'
+const machine = new LoggedOut();
+
+/**
+ * ✅ Compiler-enforced validity:
+ * LoggedOut has only `.login()`, so calling `.logout()` is a type error.
+ */
+// machine.logout(); // ❌ Property 'logout' does not exist on type 'LoggedOut'
 
 const loggedIn = machine.login("alice");
-// loggedIn.login("bob"); // ❌ Error: Property 'login' does not exist on type 'LoggedIn'
 
-const loggedOut = loggedIn.logout(); // ✅ Valid
+/**
+ * LoggedIn has `.logout()` and `.viewProfile()`.
+ * It does NOT have `.login()`, so calling it is a compile-time error.
+ */
+// loggedIn.login("bob"); // ❌ Property 'login' does not exist on type 'LoggedIn'
+
+const stillLoggedIn = loggedIn.viewProfile(); // ✅ OK (self-transition)
+const loggedOut = loggedIn.logout();          // ✅ OK (LoggedIn -> LoggedOut)
+
+/**
+ * The key idea:
+ * - You never check `status` at runtime to know what you can do.
+ * - The *type* tells you what transitions are available.
+ * - Autocomplete only offers valid transitions for the current state.
+ */
 ```
 
 This pattern makes **illegal states unrepresentable** in your type system.
@@ -439,11 +474,11 @@ Creates a synchronous state machine using the **Functional Builder** pattern. Th
 ```typescript
 const machine = createMachine({ count: 0 }, (next) => ({
   increment() {
-    // `this` is correctly inferred as Context
-    return next({ count: this.count + 1 });
+    // `this` points at the machine; read state via this.context
+    return next({ count: this.context.count + 1 });
   },
   add(n: number) {
-    return next({ count: this.count + n });
+    return next({ count: this.context.count + n });
   }
 }));
 ```
@@ -457,7 +492,7 @@ const machine = createMachine(
   { count: 0 },  // Context (state data)
   {              // Transitions (state transformations)
     increment: function() {
-      return createMachine({ count: this.count + 1 }, this);
+      return createMachine({ count: this.context.count + 1 }, this);
     }
   }
 );
@@ -470,11 +505,11 @@ Creates a synchronous state machine using the **Functional Builder** pattern. Th
 ```typescript
 const machine = createMachine({ count: 0 }, (transition) => ({
   increment() {
-    // `this` is correctly inferred as Context
-    return transition({ count: this.count + 1 });
+    // `this` points at the machine; read state via this.context
+    return transition({ count: this.context.count + 1 });
   },
   add(n: number) {
-    return transition({ count: this.count + n });
+    return transition({ count: this.context.count + n });
   }
 }));
 ```
@@ -581,45 +616,46 @@ const updated = next(counter, (ctx) => ({ count: ctx.count + 1 }));
 
 ### Transition Binding Helpers
 
-These utilities eliminate the need for `.call(m.context, ...)` boilerplate when invoking transitions.
+These utilities eliminate the need for `.call(m, ...)` boilerplate when invoking transitions.
 
-#### `call<C, F>(fn, context, ...args)`
+#### `call<M, F>(fn, machine, ...args)`
 
-Explicitly binds a transition function to a context and invokes it. Useful when you need to call a transition with proper `this` binding.
+Explicitly binds a transition function to a machine and invokes it. Useful when you need to call a transition with proper `this` binding.
 
 ```typescript
-import { call } from "@doeixd/machine";
+import { call, Machine } from "@doeixd/machine";
 
-type MyContext = { count: number };
-const increment = function(this: MyContext) { 
-  return { count: this.count + 1 }; 
+type MyMachine = Machine<{ count: number }>;
+const increment = function(this: MyMachine) { 
+  return { count: this.context.count + 1 }; 
 };
 
-const result = call(increment, { count: 5 }); // Returns { count: 6 }
+const machine = { context: { count: 5 } } as MyMachine;
+const result = call(increment, machine); // Returns { count: 6 }
 
 // Particularly useful with generator-based flows:
 const result = run(function* (m) {
-  m = yield* step(call(m.increment, m.context));
-  m = yield* step(call(m.add, m.context, 5));
+  m = yield* step(call(m.increment, m));
+  m = yield* step(call(m.add, m, 5));
   return m;
 }, counter);
 ```
 
 #### `bindTransitions<M>(machine)`
 
-Returns a Proxy that automatically binds all transition methods to the machine's context. Eliminates `.call(m.context, ...)` boilerplate entirely.
+Returns a Proxy that automatically binds all transition methods to the machine. Eliminates `.call(m, ...)` boilerplate entirely.
 
 ```typescript
-import { bindTransitions } from "@doeixd/machine";
+import { bindTransitions, Machine } from "@doeixd/machine";
 
 const counter = bindTransitions(createMachine(
   { count: 0 },
   {
-    increment(this: { count: number }) {
-      return createMachine({ count: this.count + 1 }, this);
+    increment(this: Machine<{ count: number }>) {
+      return createMachine({ count: this.context.count + 1 }, this);
     },
-    add(this: { count: number }, n: number) {
-      return createMachine({ count: this.count + n }, this);
+    add(this: Machine<{ count: number }>, n: number) {
+      return createMachine({ count: this.context.count + n }, this);
     }
   }
 ));
@@ -637,7 +673,7 @@ const result = run(function* (m) {
 ```
 
 **How it works:**
-The Proxy intercepts all property access on the machine. When a property is a function (transition method), it wraps it to automatically call `.apply(machine.context, args)` before invoking. Non-callable properties are returned as-is.
+The Proxy intercepts all property access on the machine. When a property is a function (transition method), it wraps it to automatically call `.apply(machine, args)` before invoking. Non-callable properties are returned as-is.
 
 **Note:** The Proxy preserves type safety while providing ergonomic syntax. Use this when writing generator-based flows or any code that frequently calls transitions.
 
@@ -761,7 +797,7 @@ const mocked = overrideTransitions(counter, {
 // Decorate with logging
 const logged = overrideTransitions(counter, {
   increment: function() {
-    console.log("Before:", this.count);
+    console.log("Before:", this.context.count);
     const next = counter.increment.call(this);
     console.log("After:", next.context.count);
     return next;
@@ -2104,7 +2140,7 @@ We avoid magic strings wherever possible. Instead, we use **typed object referen
 // ✅ Good: Typed method reference
 const counter = createMachine({ count: 0 }, {
   increment: function() {
-    return createMachine({ count: this.count + 1 }, this);
+    return createMachine({ count: this.context.count + 1 }, this);
   }
 });
 

package/dist/cjs/development/core.js

@@ -246,8 +246,8 @@ function guard(condition, transition, options = {}) {
     const ctx = isMachine ? this.context : this;
     const conditionResult = condition(ctx, ...args);
     if (conditionResult) {
-      const contextForTransition = isMachine ? this.context : this;
-      return transition.apply(contextForTransition, args);
+      const machineForTransition = isMachine ? this : { context: this };
+      return transition.apply(machineForTransition, args);
     } else {
       if (onFail === "throw") {
         const message = errorMessage || "Guard condition failed";
@@ -287,8 +287,8 @@ function guardAsync(condition, transition, options = {}) {
     const ctx = isMachine ? this.context : this;
     const conditionResult = await Promise.resolve(condition(ctx, ...args));
     if (conditionResult) {
-      const contextForTransition = isMachine ? this.context : this;
-      return transition.apply(contextForTransition, args);
+      const machineForTransition = isMachine ? this : { context: this };
+      return transition.apply(machineForTransition, args);
     } else {
       if (onFail === "throw") {
         const message = errorMessage || "Guard condition failed";
@@ -369,7 +369,7 @@ function createRunner(initialMachine, onChange) {
         return void 0;
       }
       return (...args) => {
-        const nextState = transition.apply(currentMachine.context, args);
+        const nextState = transition.apply(currentMachine, args);
         const nextStateWithTransitions = Object.assign(
           { context: nextState.context },
           originalTransitions
@@ -412,7 +412,7 @@ function createEnsemble(store, factories, getDiscriminant) {
         );
       }
       return (...args) => {
-        return action2.apply(currentMachine.context, args);
+        return action2.apply(currentMachine, args);
       };
     }
   });
@@ -563,7 +563,7 @@ function createMutableMachine(sharedContext, factories, getDiscriminant) {
       const transition = currentMachine[prop];
       if (typeof transition === "function") {
         return (...args) => {
-          const nextContext = transition.apply(currentMachine.context, args);
+          const nextContext = transition.apply(currentMachine, args);
           if (typeof nextContext !== "object" || nextContext === null) {
             console.warn(`[MutableMachine] Transition "${String(prop)}" did not return a valid context object. State may be inconsistent.`);
             return;
@@ -685,14 +685,14 @@ function createParallelMachine(m1, m2) {
   for (const key in transitions1) {
     const transitionFn = transitions1[key];
     combinedTransitions[key] = (...args) => {
-      const nextM1 = transitionFn.apply(m1.context, args);
+      const nextM1 = transitionFn.apply(m1, args);
       return createParallelMachine(nextM1, m2);
     };
   }
   for (const key in transitions2) {
     const transitionFn = transitions2[key];
     combinedTransitions[key] = (...args) => {
-      const nextM2 = transitionFn.apply(m2.context, args);
+      const nextM2 = transitionFn.apply(m2, args);
       return createParallelMachine(m1, nextM2);
     };
   }
@@ -1163,7 +1163,7 @@ function withTimeTravel(machine, options = {}) {
     for (const entry of transitionsToReplay) {
       const transitionFn = replayedMachine[entry.transitionName];
       if (transitionFn) {
-        replayedMachine = transitionFn.apply(replayedMachine.context, entry.args);
+        replayedMachine = transitionFn.apply(replayedMachine, entry.args);
       }
     }
     return replayedMachine;
@@ -1583,8 +1583,8 @@ function createTransition(getTransitions, transformer) {
     return createMachine(nextContext, getTransitions());
   };
 }
-function call(fn, context, ...args) {
-  return fn.apply(context, args);
+function call(fn, machine, ...args) {
+  return fn.apply(machine, args);
 }
 function bindTransitions(machine) {
   return new Proxy(machine, {
@@ -1592,7 +1592,7 @@ function bindTransitions(machine) {
       const value = target[prop];
       if (typeof value === "function") {
         return function(...args) {
-          const result = value.apply(target.context, args);
+          const result = value.apply(target, args);
           if (result && typeof result === "object" && "context" in result) {
             return bindTransitions(result);
           }
@@ -1617,7 +1617,7 @@ var BoundMachine = class _BoundMachine {
         const value = this.wrappedMachine[prop];
         if (typeof value === "function") {
           return (...args) => {
-            const result = value.apply(this.wrappedMachine.context, args);
+            const result = value.apply(this.wrappedMachine, args);
             if (result && typeof result === "object" && "context" in result) {
               return new _BoundMachine(result);
             }
@@ -1680,23 +1680,10 @@ function createMachine(context, fnsOrFactory) {
   if (typeof fnsOrFactory === "function") {
     let transitions2;
     const transition = (newContext) => {
-      const machine2 = createMachine(newContext, transitions2);
-      const boundTransitions2 = Object.fromEntries(
-        Object.entries(transitions2).map(([key, fn]) => [
-          key,
-          fn.bind(newContext)
-        ])
-      );
-      return Object.assign(machine2, boundTransitions2);
+      return createMachine(newContext, transitions2);
     };
     transitions2 = fnsOrFactory(transition);
-    const boundTransitions = Object.fromEntries(
-      Object.entries(transitions2).map(([key, fn]) => [
-        key,
-        fn.bind(context)
-      ])
-    );
-    return Object.assign({ context }, boundTransitions);
+    return Object.assign({ context }, transitions2);
   }
   const transitions = "context" in fnsOrFactory ? Object.fromEntries(
     Object.entries(fnsOrFactory).filter(([key]) => key !== "context")
@@ -1708,23 +1695,10 @@ function createAsyncMachine(context, fnsOrFactory) {
   if (typeof fnsOrFactory === "function") {
     let transitions2;
     const transition = (newContext) => {
-      const machine2 = createAsyncMachine(newContext, transitions2);
-      const boundTransitions2 = Object.fromEntries(
-        Object.entries(transitions2).map(([key, fn]) => [
-          key,
-          fn.bind(newContext)
-        ])
-      );
-      return Object.assign(machine2, boundTransitions2);
+      return createAsyncMachine(newContext, transitions2);
     };
     transitions2 = fnsOrFactory(transition);
-    const boundTransitions = Object.fromEntries(
-      Object.entries(transitions2).map(([key, fn]) => [
-        key,
-        fn.bind(context)
-      ])
-    );
-    return Object.assign({ context }, boundTransitions);
+    return Object.assign({ context }, transitions2);
   }
   const transitions = "context" in fnsOrFactory ? Object.fromEntries(
     Object.entries(fnsOrFactory).filter(([key]) => key !== "context")
@@ -1806,7 +1780,7 @@ function runMachine(initial, onChange) {
     const controller = new AbortController();
     activeController = controller;
     try {
-      const nextStatePromise = fn.apply(current.context, [...event.args, { signal: controller.signal }]);
+      const nextStatePromise = fn.apply(current, [...event.args, { signal: controller.signal }]);
       const nextState = await nextStatePromise;
       if (controller.signal.aborted) {
         return current;