@doeixd/machine 0.0.23 → 1.0.1

package/src/entry-react.ts

@@ -5,5 +5,12 @@
 // Re-export core functionality
 export * from './core';
 
-// Re-export React-specific functionality
-export * from './react';
+// Re-export React-specific functionality (excluding duplicates like Runner)
+export {
+  useMachine,
+  useMachineSelector,
+  useEnsemble,
+  createMachineContext,
+  useActor,
+  useActorSelector,
+} from './react';

package/src/functional-combinators.ts

@@ -21,7 +21,7 @@ import { createMachine, Machine, BaseMachine, extendTransitions } from './index'
  * // Define your machine's transitions object
  * const counterTransitions = {
  *   increment: function(amount: number) {
- *     return createMachine({ count: this.count + amount }, counterTransitions);
+ *     return createMachine({ count: this.context.count + amount }, counterTransitions);
  *   }
  * };
  *
@@ -103,7 +103,7 @@ export function createTransitionFactory<C extends object>() {
  * // Start with a basic counter machine
  * const basicCounter = createMachine({ count: 0 }, {
  *   increment: function() {
- *     return createMachine({ count: this.count + 1 }, this);
+ *     return createMachine({ count: this.context.count + 1 }, this);
  *   }
  * });
  *
@@ -276,7 +276,7 @@ export function createFunctionalMachine<C extends object>(initialContext: C) {
  * 1. **Traditional Pattern** (with transitions object):
  *    ```typescript
  *    const machine = state({ count: 0 }, {
- *      increment() { return createMachine({ count: this.count + 1 }, this); }
+ *      increment() { return createMachine({ count: this.context.count + 1 }, this); }
  *    });
  *    ```
  *
@@ -308,8 +308,8 @@ export function createFunctionalMachine<C extends object>(initialContext: C) {
  * ```typescript
  * // Traditional pattern
  * const counter1 = state({ count: 0 }, {
- *   increment() { return createMachine({ count: this.count + 1 }, this); },
- *   decrement() { return createMachine({ count: this.count - 1 }, this); }
+ *   increment() { return createMachine({ count: this.context.count + 1 }, this); },
+ *   decrement() { return createMachine({ count: this.context.count - 1 }, this); }
  * });
  *
  * // Functional pattern

package/src/generators.ts

@@ -58,10 +58,10 @@
  * ```typescript
  * const counter = createMachine({ count: 0 }, {
  *   increment: function() {
- *     return createMachine({ count: this.count + 1 }, this);
+ *     return createMachine({ count: this.context.count + 1 }, this);
  *   },
  *   add: function(n: number) {
- *     return createMachine({ count: this.count + n }, this);
+ *     return createMachine({ count: this.context.count + n }, this);
  *   }
  * });
  *

package/src/higher-order.ts

@@ -333,7 +333,7 @@ export function createParallelMachine<
   for (const key in transitions1) {
     const transitionFn = (transitions1 as any)[key];
     combinedTransitions[key] = (...args: any[]) => {
-      const nextM1 = transitionFn.apply(m1.context, args);
+      const nextM1 = transitionFn.apply(m1, args);
       // Recursively create a new parallel machine with the new M1 state
       return createParallelMachine(nextM1, m2);
     };
@@ -343,7 +343,7 @@ export function createParallelMachine<
   for (const key in transitions2) {
     const transitionFn = (transitions2 as any)[key];
     combinedTransitions[key] = (...args: any[]) => {
-      const nextM2 = transitionFn.apply(m2.context, args);
+      const nextM2 = transitionFn.apply(m2, args);
       // Recursively create a new parallel machine with the new M2 state
       return createParallelMachine(m1, nextM2);
     };

package/src/index.ts

@@ -198,12 +198,12 @@ export type Event<M extends BaseMachine<any>> = {
  * const counterTransitions = {
  *   increment() {
  *     // `this` is now fully typed!
- *     // IntelliSense knows `this.count` is a number and
+ *     // IntelliSense knows `this.context.count` is a number and
  *     // `this.transitions.add` is a function.
- *     return createMachine({ count: this.count + 1 }, this.transitions);
+ *     return createMachine({ count: this.context.count + 1 }, this.transitions);
  *   },
  *   add(n: number) {
- *     return createMachine({ count: this.count + n }, this.transitions);
+ *     return createMachine({ count: this.context.count + n }, this.transitions);
  *   },
  *   // ❌ TypeScript will immediately throw a compile error on the next line
  *   //    because the return type 'string' does not satisfy 'Machine<any>'.
@@ -220,7 +220,7 @@ export type Event<M extends BaseMachine<any>> = {
  * }
  */
 export type TransitionsFor<C extends object, T extends Record<string, any>> = {
-  [K in keyof T]: (this: C & { transitions: T }, ...args: Parameters<T[K] extends (...a: infer A) => any ? (...a: A) => any : never>) => Machine<any, any>;
+  [K in keyof T]: (this: Machine<C, T>, ...args: Parameters<T[K] extends (...a: infer A) => any ? (...a: A) => any : never>) => Machine<any, any>;
 };
 
 /**
@@ -228,7 +228,7 @@ export type TransitionsFor<C extends object, T extends Record<string, any>> = {
  * type-checking for standalone asynchronous transition objects.
  */
 export type AsyncTransitionsFor<C extends object, T extends Record<string, any>> = {
-  [K in keyof T]: (this: C & { transitions: T }, ...args: Parameters<T[K] extends (...a: infer A) => any ? (...a: A) => any : never>) => MaybePromise<AsyncMachine<any, any>>;
+  [K in keyof T]: (this: Machine<C, T>, ...args: Parameters<T[K] extends (...a: infer A) => any ? (...a: A) => any : never>) => MaybePromise<AsyncMachine<any, any>>;
 };
 
 /**
@@ -345,24 +345,26 @@ export type BindTransitions<T> = {
  * @param factory - A function that receives a `transition` helper and returns the transitions object.
  * @returns A new machine instance.
  */
-export function createMachine<C extends object, T extends Record<string, (this: C, ...args: any[]) => any> = Record<string, (this: C, ...args: any[]) => any>>(
+export function createMachine<C extends object, T extends Record<string, (this: Machine<C, any>, ...args: any[]) => any> = Record<string, (this: Machine<C, any>, ...args: any[]) => any>>(
   context: C,
   factory: (transition: (newContext: C) => Machine<C, any>) => T
-): Machine<C, BindTransitions<T>>;
+): Machine<C, T>;
 
 /**
  * Creates a synchronous state machine from a context and transition functions.
  * This is the core factory for the functional approach.
+ * Transitions receive the full machine as `this`, allowing them to access
+ * `this.context` and call other transitions via `this.otherTransition()`.
  *
  * @template C - The context object type.
  * @param context - The initial state context.
  * @param fns - An object containing transition function definitions.
  * @returns A new machine instance.
  */
-export function createMachine<C extends object, T extends Record<string, (this: { context: C } & T, ...args: any[]) => any> & { context?: any }>(
+export function createMachine<C extends object, T extends Record<string, (this: Machine<C, T>, ...args: any[]) => any> & { context?: any }>(
   context: C,
   fns: T
-): { context: C } & T;
+): Machine<C, T>;
 
 /**
  * Creates a synchronous state machine by copying context and transitions from an existing machine.
@@ -379,45 +381,15 @@ export function createMachine<C extends object, M extends BaseMachine<C>>(
   machine: M
 ): Machine<C, Transitions<M>>;
 
-/**
- * Creates a synchronous state machine from a context and transition functions that expect `this` to be the context object.
- * This is used internally by utilities that need to bind transitions to context objects.
- *
- * @template C - The context object type.
- * @param context - The initial state context.
- * @param fns - An object containing transition function definitions that expect `this` to be the context.
- * @returns A new machine instance.
- */
-export function createMachine<C extends object, T extends Record<string, (this: C, ...args: any[]) => any>>(
-  context: C,
-  fns: T
-): Machine<C, T>;
-
 export function createMachine(context: any, fnsOrFactory: any): any {
   if (typeof fnsOrFactory === 'function') {
     let transitions: any;
     const transition = (newContext: any) => {
-      const machine = createMachine(newContext, transitions);
-      // Re-bind transitions to the new context
-      const boundTransitions = Object.fromEntries(
-        Object.entries(transitions).map(([key, fn]) => [
-          key,
-          (fn as Function).bind(newContext)
-        ])
-      );
-      return Object.assign(machine, boundTransitions);
+      return createMachine(newContext, transitions);
     };
     transitions = fnsOrFactory(transition);
 
-    // Bind transitions to initial context
-    const boundTransitions = Object.fromEntries(
-      Object.entries(transitions).map(([key, fn]) => [
-        key,
-        (fn as Function).bind(context)
-      ])
-    );
-
-    return Object.assign({ context }, boundTransitions);
+    return Object.assign({ context }, transitions);
   }
 
   // If fns is a machine (has context property), extract just the transition functions
@@ -425,10 +397,6 @@ export function createMachine(context: any, fnsOrFactory: any): any {
     Object.entries(fnsOrFactory).filter(([key]) => key !== 'context')
   ) : fnsOrFactory;
 
-  // For normal object transitions, we might also need binding if they use `this`
-  // But existing code expects `this` to be the machine (context + transitions).
-  // The new API expects `this` to be just context.
-
   const machine = Object.assign({ context }, transitions);
   return machine;
 }
@@ -481,27 +449,11 @@ export function createAsyncMachine(context: any, fnsOrFactory: any): any {
   if (typeof fnsOrFactory === 'function') {
     let transitions: any;
     const transition = (newContext: any) => {
-      const machine = createAsyncMachine(newContext, transitions);
-      // Re-bind transitions to the new context
-      const boundTransitions = Object.fromEntries(
-        Object.entries(transitions).map(([key, fn]) => [
-          key,
-          (fn as Function).bind(newContext)
-        ])
-      );
-      return Object.assign(machine, boundTransitions);
+      return createAsyncMachine(newContext, transitions);
     };
     transitions = fnsOrFactory(transition);
 
-    // Bind transitions to initial context
-    const boundTransitions = Object.fromEntries(
-      Object.entries(transitions).map(([key, fn]) => [
-        key,
-        (fn as Function).bind(context)
-      ])
-    );
-
-    return Object.assign({ context }, boundTransitions);
+    return Object.assign({ context }, transitions);
   }
 
   // If fns is a machine (has context property), extract just the transition functions
@@ -682,14 +634,14 @@ export function extendTransitions<
  * // Define two independent machines
  * const createCounter = (initial: number) =>
  *   createMachine({ count: initial }, {
- *     increment: function() { return createMachine({ count: this.count + 1 }, this); },
- *     decrement: function() { return createMachine({ count: this.count - 1 }, this); }
+ *     increment: function() { return createMachine({ count: this.context.count + 1 }, this); },
+ *     decrement: function() { return createMachine({ count: this.context.count - 1 }, this); }
  *   });
  *
  * const createLogger = () =>
  *   createMachine({ logs: [] as string[] }, {
  *     log: function(message: string) {
- *       return createMachine({ logs: [...this.logs, message] }, this);
+ *       return createMachine({ logs: [...this.context.logs, message] }, this);
  *     },
  *     clear: function() {
  *       return createMachine({ logs: [] }, this);
@@ -872,7 +824,7 @@ export function runMachine<M extends AsyncMachine<any>>(
 
     try {
       // 3. Pass the signal to the transition function.
-      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;
 
@@ -1164,4 +1116,15 @@ export {
   fromObservable,
   type ActorRef,
   type InspectionEvent
-} from './actor';
+} from './actor';
+
+// =============================================================================
+// SECTION: CONTEXT-BOUND UTILITIES
+// =============================================================================
+
+export {
+  createContextBoundMachine,
+  callWithContext,
+  isContextBound,
+  type ContextBoundMachine
+} from './context-bound';

package/src/middleware/time-travel.ts

@@ -211,7 +211,7 @@ export function withTimeTravel<M extends BaseMachine<any>>(
     for (const entry of transitionsToReplay) {
       const transitionFn = replayedMachine[entry.transitionName as keyof M] as Function;
       if (transitionFn) {
-        replayedMachine = transitionFn.apply(replayedMachine.context, entry.args);
+        replayedMachine = transitionFn.apply(replayedMachine, entry.args);
       }
     }
 
@@ -233,4 +233,4 @@ export function withTimeTravel<M extends BaseMachine<any>>(
     restoreSnapshot,
     replayFrom
   }) as WithTimeTravel<M>;
-}
+}

package/src/middleware.ts

@@ -976,7 +976,7 @@ export function withTimeTravel<M extends BaseMachine<any>>(
     for (const entry of transitionsToReplay) {
       const transitionFn = replayedMachine[entry.transitionName as keyof M] as Function;
       if (transitionFn) {
-        replayedMachine = transitionFn.apply(replayedMachine.context, entry.args);
+        replayedMachine = transitionFn.apply(replayedMachine, entry.args);
       }
     }
 
@@ -1443,4 +1443,4 @@ export type WithDebugging<M extends BaseMachine<any>> = WithTimeTravel<WithSnaps
  */
 export function withDebugging<M extends BaseMachine<any>>(machine: M): WithDebugging<M> {
   return withTimeTravel(withSnapshot(withHistory(machine)));
-}
+}

package/src/multi.ts

@@ -211,7 +211,7 @@ export function createRunner<M extends Machine<any>>(
       }
 
       return (...args: any[]) => {
-        const nextState = transition.apply(currentMachine.context, args);
+        const nextState = transition.apply(currentMachine, args);
         // Ensure the next state has all the original transitions
         // by reconstructing it with the original transition functions
         const nextStateWithTransitions = Object.assign(
@@ -498,7 +498,7 @@ export function createEnsemble<
       // Return a function that, when called, executes the transition.
       // The transition itself is responsible for calling `store.setContext`.
       return (...args: any[]) => {
-        return action.apply(currentMachine.context, args);
+        return action.apply(currentMachine, args);
       };
     },
   });
@@ -1153,7 +1153,7 @@ export function createMutableMachine<
       if (typeof transition === 'function') {
         return (...args: any[]) => {
           // This pattern requires transitions to be pure functions that return the next context.
-          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;
@@ -1178,4 +1178,4 @@ export function createMutableMachine<
       return prop in target || typeof (currentMachine as any)[prop] === 'function';
     }
   }) as MutableMachine<C, ReturnType<F[keyof F]>>;
-}
+}

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);