@doeixd/machine 0.0.23 → 1.0.2

package/src/primitives.ts

@@ -354,6 +354,14 @@ export type GuardedTransition<
  * Creates a synchronous runtime guard that checks conditions before executing transitions.
  * This provides actual runtime protection with synchronous execution - use this for the majority of cases.
  *
+ * **IMPORTANT - Context-Bound Limitation:**
+ * Guards accept calls with either `this === machine` or `this === context`, but when called
+ * with context-only binding, the guard normalizes to `{ context }` before passing to the transition.
+ * This means:
+ * - ✅ Transitions can access `this.context`
+ * - ❌ Transitions CANNOT call `this.otherTransition()` (no transitions property)
+ * - Recommended: Use guards only with machine-bound transitions for full composition support
+ *
  * @template C - The context type
  * @template TSuccess - The transition return type when condition passes
  * @template TFailure - The fallback return type when condition fails (defaults to Machine<C>)
@@ -367,8 +375,10 @@ export type GuardedTransition<
  * const machine = createMachine({ balance: 100 }, {
  *   withdraw: guard(
  *     (ctx, amount) => ctx.balance >= amount,
- *     function(amount: number) {
- *       return createMachine({ balance: this.balance - amount }, this);
+ *     function(this: Machine<{balance: number}>, amount: number) {
+ *       // ✅ Can access this.context
+ *       return createMachine({ balance: this.context.balance - amount }, this);
+ *       // ❌ Cannot call this.otherTransition() if guard was called with context-only binding
  *     },
  *     { onFail: 'throw', errorMessage: 'Insufficient funds' }
  *   )
@@ -403,9 +413,9 @@ export function guard<
 
     if (conditionResult) {
       // Condition passed, execute the transition
-      // Transition functions expect 'this' to be the context
-      const contextForTransition = isMachine ? (this as Machine<C>).context : (this as C);
-      return transition.apply(contextForTransition, args);
+      // Transition functions expect 'this' to be the machine
+      const machineForTransition = isMachine ? (this as Machine<C>) : { context: this as C };
+      return transition.apply(machineForTransition, args);
     } else {
       // Condition failed, handle according to options
       if (onFail === 'throw') {
@@ -453,6 +463,14 @@ export function guard<
  * This provides actual runtime protection, unlike the `guarded` primitive which only adds metadata.
  * Use this when your condition or transition logic is asynchronous.
  *
+ * **IMPORTANT - Context-Bound Limitation:**
+ * Guards accept calls with either `this === machine` or `this === context`, but when called
+ * with context-only binding, the guard normalizes to `{ context }` before passing to the transition.
+ * This means:
+ * - ✅ Transitions can access `this.context`
+ * - ❌ Transitions CANNOT call `this.otherTransition()` (no transitions property)
+ * - Recommended: Use guards only with machine-bound transitions for full composition support
+ *
  * @template C - The context type
  * @template TSuccess - The transition return type when condition passes
  * @template TFailure - The fallback return type when condition fails (defaults to Machine<C>)
@@ -470,10 +488,12 @@ export function guard<
  *       await new Promise(resolve => setTimeout(resolve, 100));
  *       return ctx.balance >= amount;
  *     },
- *     async function(amount: number) {
+ *     async function(this: Machine<{balance: number}>, amount: number) {
  *       // Simulate API call to process withdrawal
  *       await new Promise(resolve => setTimeout(resolve, 100));
- *       return createMachine({ balance: this.balance - amount }, this);
+ *       // ✅ Can access this.context
+ *       return createMachine({ balance: this.context.balance - amount }, this);
+ *       // ❌ Cannot call this.otherTransition() if guard was called with context-only binding
  *     },
  *     { onFail: 'throw', errorMessage: 'Insufficient funds' }
  *   )
@@ -508,9 +528,9 @@ export function guardAsync<
 
     if (conditionResult) {
       // Condition passed, execute the transition
-      // Transition functions expect 'this' to be the context
-      const contextForTransition = isMachine ? (this as Machine<C>).context : (this as C);
-      return transition.apply(contextForTransition, args);
+      // Transition functions expect 'this' to be the machine
+      const machineForTransition = isMachine ? (this as Machine<C>) : { context: this as C };
+      return transition.apply(machineForTransition, args);
     } else {
       // Condition failed, handle according to options
       if (onFail === 'throw') {
@@ -571,7 +591,7 @@ export function guardAsync<
  *   withdraw: guardSync(
  *     (ctx, amount) => ctx.balance >= amount,
  *     function(amount: number) {
- *       return createMachine({ balance: this.balance - amount }, this);
+ *       return createMachine({ balance: this.context.balance - amount }, this);
  *     },
  *     { onFail: 'throw', errorMessage: 'Insufficient funds' }
  *   )
@@ -606,9 +626,9 @@ export function guardSync<
 
     if (conditionResult) {
       // Condition passed, execute the transition
-      // Transition functions expect 'this' to be the context
-      const contextForTransition = isMachine ? (this as Machine<C>).context : (this as C);
-      return transition.apply(contextForTransition, args);
+      // Transition functions expect 'this' to be the machine
+      const machineForTransition = isMachine ? (this as Machine<C>) : { context: this as C };
+      return transition.apply(machineForTransition, args);
     } else {
       // Condition failed, handle according to options
       if (onFail === 'throw') {

package/src/prototype_functional.ts

@@ -33,10 +33,10 @@ type Context = { count: number };
 const machine = createMachine({ count: 0 }, (transition) => ({
   inc() {
     // 'this' should be Context
-    return transition({ count: this.count + 1 });
+    return transition({ count: this.context.count + 1 });
   },
   add(n: number) {
-    return transition({ count: this.count + n });
+    return transition({ count: this.context.count + n });
   }
 }));
 

package/src/react.ts

@@ -302,7 +302,6 @@ export function useActorSelector<M extends BaseMachine<any>, T>(
   selector: (state: M) => T,
   isEqual: (a: T, b: T) => boolean = Object.is
 ): T {
-  const subscribe = useMemo(() => actor.subscribe.bind(actor), [actor]);
   const getSnapshot = useMemo(() => actor.getSnapshot.bind(actor), [actor]);
 
   const getSelection = () => selector(getSnapshot());
@@ -333,4 +332,4 @@ export function useActorSelector<M extends BaseMachine<any>, T>(
   }, [actor, selector, isEqual]);
 
   return selection;
-}
+}

package/src/test.ts

@@ -27,7 +27,7 @@ type AsyncFunctions<C extends object> =
  * const machine: Machine<{ count: number }> = {
  *   context: { count: 0 },
  *   increment: function() {
- *     return createMachine({ count: this.count + 1 }, this)
+ *     return createMachine({ count: this.context.count + 1 }, this)
  *   }
  * }
  */
@@ -57,10 +57,10 @@ export type AsyncMachine<C extends object> = { context: C } & AsyncFunctions<C>
  *   { count: 0 },
  *   {
  *     increment: function() {
- *       return createMachine({ count: this.count + 1 }, this)
+ *       return createMachine({ count: this.context.count + 1 }, this)
  *     },
  *     decrement: function() {
- *       return createMachine({ count: this.count - 1 }, this)
+ *       return createMachine({ count: this.context.count - 1 }, this)
  *     }
  *   }
  * )
@@ -147,7 +147,7 @@ export type Event<M> = {
  *   { count: 0 },
  *   {
  *     increment: async function() {
- *       return createAsyncMachine({ count: this.count + 1 }, this)
+ *       return createAsyncMachine({ count: this.context.count + 1 }, this)
  *     }
  *   }
  * )
@@ -164,7 +164,7 @@ export function runMachine<C extends object>(
   async function dispatch<E extends Event<typeof current>>(event: E) {
     const fn = current[event.type] as any
     if (!fn) throw new Error(`Unknown event: ${event.type}`)
-    const next = await fn.apply(current.context, event.args)
+    const next = await fn.apply(current as any, event.args)
     current = next
     onChange?.(current)
     return current
@@ -203,5 +203,5 @@ const counter = createMachine(
 );
 
 // Test by calling with proper context binding
-const result = counterFns.increment.call(counter.context);
-console.log('Result:', result.context.count);
+const result = counterFns.increment.call(counter);
+console.log('Result:', result.context.count);

package/src/utils.ts

@@ -231,7 +231,7 @@ export function createTransition<
   C extends object,
   TArgs extends any[]
 >(
-  getTransitions: () => Record<string, (this: C, ...args: any[]) => any>,
+  getTransitions: () => Record<string, (this: Machine<C, any>, ...args: any[]) => any>,
   transformer: (ctx: C, ...args: TArgs) => C
 ): (this: { context: C }, ...args: TArgs) => Machine<C> {
   return function (this: { context: C }, ...args: TArgs): Machine<C> {
@@ -245,50 +245,50 @@ export function createTransition<
 // =============================================================================
 
 /**
- * Calls a transition function with an explicit `this` context.
- * Useful for invoking transition methods with proper context binding.
+ * Calls a transition function with an explicit `this` binding.
+ * Useful for invoking transition methods with proper machine binding.
  *
- * @template C - The context type that the function expects as `this`.
+ * @template M - The machine type that the function expects as `this`.
  * @template F - The function type with a `this` parameter.
  * @template A - The argument types for the function.
  * @param fn - The transition function to call.
- * @param context - The context object to bind as `this`.
+ * @param machine - The machine object to bind as `this`.
  * @param args - Arguments to pass to the function.
- * @returns The result of calling the function with the given context and arguments.
+ * @returns The result of calling the function with the given machine and arguments.
  *
  * @example
- * type MyContext = { count: number };
- * const increment = function(this: MyContext) { return this.count + 1; };
- * const result = call(increment, { count: 5 }); // Returns 6
+ * type MyMachine = Machine<{ count: number }>;
+ * const increment = function(this: MyMachine) { return createMachine({ count: this.context.count + 1 }, this); };
+ * const result = call(increment, machine); // Returns new machine
  *
  * // Particularly useful with machine transitions:
  * import { call } from '@doeixd/machine/utils';
- * const nextMachine = yield* step(call(m.increment, m.context));
+ * const nextMachine = yield* step(call(m.increment, m));
  */
-export function call<C, F extends (this: C, ...args: any[]) => any>(
+export function call<M extends Machine<any>, F extends (this: M, ...args: any[]) => any>(
   fn: F,
-  context: C,
+  machine: M,
   ...args: Parameters<F> extends [any, ...infer Rest] ? Rest : never
 ): ReturnType<F> {
-  return fn.apply(context, args);
+  return fn.apply(machine, args);
 }
 
 /**
- * Binds all transition methods of a machine to its context automatically.
- * Returns a Proxy that intercepts method calls and binds them to `machine.context`.
- * This eliminates the need to use `.call(m.context, ...)` for every transition.
+ * Binds all transition methods of a machine to the machine itself automatically.
+ * Returns a Proxy that intercepts method calls and binds them to the full machine.
+ * This eliminates the need to use `.call(m, ...)` for every transition.
  *
  * Automatically recursively wraps returned machines, enabling seamless chaining
  * in generator-based flows.
  *
  * @template M - The machine type with a `context` property and transition methods.
  * @param machine - The machine instance to wrap.
- * @returns A Proxy of the machine where all callable properties (transitions) are automatically bound to the machine's context.
+ * @returns A Proxy of the machine where all callable properties (transitions) are automatically bound to the machine.
  *
  * @example
- * type CounterContext = { count: number };
+ * type CounterMachine = Machine<{ count: number }>;
  * const counter = bindTransitions(createMachine({ count: 0 }, {
- *   increment(this: CounterContext) { return createCounter(this.count + 1); }
+ *   increment(this: CounterMachine) { return createMachine({ count: this.context.count + 1 }, this); }
  * }));
  *
  * // Now you can call transitions directly without .call():
@@ -304,18 +304,18 @@ export function call<C, F extends (this: C, ...args: any[]) => any>(
  * @remarks
  * The Proxy preserves all original properties and methods. Non-callable properties
  * are accessed directly from the machine. Callable properties are wrapped to bind
- * them to `machine.context` before invocation. Returned machines are automatically
+ * them to the machine before invocation. Returned machines are automatically
  * re-wrapped to maintain binding across transition chains.
  */
 export function bindTransitions<M extends { context: any }>(machine: M): M {
   return new Proxy(machine, {
     get(target, prop) {
       const value = target[prop as keyof M];
-      
-      // If it's a callable property (transition method), bind it to context
+
+      // If it's a callable property (transition method), bind it to machine
       if (typeof value === 'function') {
         return function(...args: any[]) {
-          const result = value.apply(target.context, args);
+          const result = value.apply(target, args);
           // Recursively wrap returned machines to maintain binding
           if (result && typeof result === 'object' && 'context' in result) {
             return bindTransitions(result);
@@ -323,7 +323,7 @@ export function bindTransitions<M extends { context: any }>(machine: M): M {
           return result;
         };
       }
-      
+
       // Otherwise, return the value as-is
       return value;
     },
@@ -331,21 +331,21 @@ export function bindTransitions<M extends { context: any }>(machine: M): M {
 }
 
 /**
- * A strongly-typed wrapper class for binding transitions to machine context.
+ * A strongly-typed wrapper class for binding transitions to the machine.
  * Unlike the Proxy-based `bindTransitions`, this class preserves full type safety
  * and provides better IDE support through explicit property forwarding.
  *
  * @template M - The machine type with a `context` property and transition methods.
  *
  * @example
- * type CounterContext = { count: number };
+ * type CounterMachine = Machine<{ count: number }>;
  * const counter = createMachine({ count: 0 }, {
- *   increment(this: CounterContext) { return createCounter(this.count + 1); }
+ *   increment(this: CounterMachine) { return createMachine({ count: this.context.count + 1 }, this); }
  * });
  *
  * const bound = new BoundMachine(counter);
  *
- * // All transitions are automatically bound to context
+ * // All transitions are automatically bound to machine
  * const result = run(function* (m) {
  *   m = yield* step(m.increment());
  *   m = yield* step(m.add(5));
@@ -383,10 +383,10 @@ export class BoundMachine<M extends { context: any }> {
 
         const value = this.wrappedMachine[prop as keyof M];
 
-        // Bind transition methods to context
+        // Bind transition methods to machine
         if (typeof value === 'function') {
           return (...args: any[]) => {
-            const result = value.apply(this.wrappedMachine.context, args);
+            const result = value.apply(this.wrappedMachine, args);
             // Recursively wrap returned machines
             if (result && typeof result === 'object' && 'context' in result) {
               return new BoundMachine(result);
@@ -619,4 +619,4 @@ export function sequence3<
   isFinal: (machine: M1 | M2 | M3) => boolean
 ): M1 | M2 | M3 {
   return sequence([machine1, machine2, machine3], isFinal);
-}
+}