@doeixd/machine 0.0.23 → 1.0.2

package/src/context-bound.ts

@@ -0,0 +1,160 @@
+import type { Machine, Transitions } from './index';
+import { attachTransitions } from './internal-transitions';
+
+/**
+ * Creates a machine where transformers receive context as `this` and return new contexts.
+ * The wrapper automatically converts these context-returning functions into proper
+ * machine-returning transitions.
+ *
+ * **Important Limitations:**
+ * - Transformers receive ONLY context as `this` (a lightweight `{ context }` object)
+ * - Cannot call other transitions via `this.otherTransition()`
+ * - Provides cleaner syntax for simple context transformations
+ *
+ * @template C - The context type
+ * @template T - The transformers record mapping transition names to context transformers
+ *
+ * @param initialContext - The initial context object
+ * @param transformers - Record of transition names to pure context transformers.
+ *                       Each transformer receives `this === context` and returns a new context.
+ *                       The public API returns machines, not contexts.
+ * @returns A context-bound machine where public transitions return machines,
+ *          but internal transformers work with contexts directly.
+ *
+ * @example
+ * ```typescript
+ * const machine = createContextBoundMachine({ count: 0 }, {
+ *   increment() {
+ *     // Inside: `this` is the context object, return new context
+ *     return { count: this.context.count + 1 };
+ *   },
+ *   add(amount: number) {
+ *     return { count: this.context.count + amount };
+ *   }
+ * });
+ *
+ * // Outside: returns a machine (not just context)
+ * const result = machine.increment();
+ * console.log(result.context.count); // 1
+ *
+ * // ❌ CANNOT do this inside transformers:
+ * // incrementTwice() { return this.increment().increment(); }
+ * // (this.increment doesn't exist - `this` is just the context)
+ * ```
+ */
+export function createContextBoundMachine<
+  C extends object,
+  T extends Record<string, (this: C, ...args: any[]) => C>
+>(
+  initialContext: C,
+  transformers: T
+): ContextBoundMachine<C, T> {
+  // Create a closure to hold the transformers for reuse
+  const savedTransformers = transformers;
+
+  // Create transition functions that bind to context
+  const boundTransitions = Object.fromEntries(
+    Object.entries(transformers).map(([key, transformer]) => [
+      key,
+      function (this: Machine<C>, ...args: any[]) {
+        // Bind transformer to a context-only object ({ context })
+        const contextOnly = { context: this.context } as Pick<Machine<C>, 'context'>;
+        const newContext = transformer.apply(contextOnly as any, args);
+        // Return new machine with same transformers
+        return createContextBoundMachine(newContext, savedTransformers);
+      },
+    ])
+  );
+
+  Object.values(boundTransitions).forEach((fn) => {
+    if (typeof fn === 'function') {
+      Object.defineProperty(fn, '__contextBound', {
+        value: true,
+        enumerable: false,
+      });
+    }
+  });
+
+  return attachTransitions(
+    Object.assign({ context: initialContext }, boundTransitions),
+    boundTransitions as any
+  ) as any;
+}
+
+/**
+ * Machine type where transitions receive context as `this`.
+ *
+ * @template C - The context type
+ * @template T - The transformers record type
+ */
+export type ContextBoundMachine<
+  C extends object,
+  T extends Record<string, any>
+> = Machine<
+  C,
+  {
+    [K in keyof T]: (
+      ...args: Parameters<T[K]>
+    ) => ContextBoundMachine<C, T>;
+  }
+>;
+
+
+/**
+ * Helper to call a transition with context binding.
+ * Equivalent to `fn.call({ context: machine.context }, ...args)`.
+ *
+ * @template M - The machine type
+ * @template K - The transition name (keyof the transitions)
+ *
+ * @param machine - The machine instance
+ * @param transitionName - The name of the transition to call
+ * @param args - Arguments to pass to the transition
+ * @returns The result of calling the transition
+ *
+ * @example
+ * ```typescript
+ * const machine = createMachine({ count: 0 }, {
+ *   increment(this: {count: number}) {
+ *     return { count: this.context.count + 1 };
+ *   }
+ * });
+ *
+ * // Instead of: machine.increment.call(machine.context)
+ * const result = callWithContext(machine, 'increment');
+ * ```
+ */
+export function callWithContext<M extends Machine<any>>(
+  machine: M,
+  transitionName: keyof Transitions<M>,
+  ...args: any[]
+): any {
+  const fn = (machine as any)[transitionName];
+  const contextOnly = { context: machine.context } as Pick<Machine<any>, 'context'>;
+  return fn.apply(contextOnly as any, args);
+}
+
+/**
+ * Type guard to check if a machine is context-bound.
+ *
+ * @param machine - The machine to check
+ * @returns True if the machine was created with createContextBoundMachine
+ *
+ * @example
+ * ```typescript
+ * const cbMachine = createContextBoundMachine({ count: 0 }, {...});
+ * const normalMachine = createMachine({ count: 0 }, {...});
+ *
+ * isContextBound(cbMachine);    // true
+ * isContextBound(normalMachine); // false
+ * ```
+ */
+export function isContextBound(machine: Machine<any>): boolean {
+  const firstTransition = Object.values(machine).find(
+    (v) => typeof v === 'function'
+  );
+  if (!firstTransition) return false;
+
+  // Context-bound machines have a marker property
+  return (firstTransition as any).__contextBound === true;
+}

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

@@ -3,6 +3,7 @@
  * @author doeixd
  * @version 1.0.0
  */
+import { attachTransitions, getStoredTransitions, snapshotOwnTransitions } from './internal-transitions';
 
 // =============================================================================
 // SECTION: CORE TYPES & INTERFACES
@@ -198,12 +199,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 +221,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 +229,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 +346,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,58 +382,25 @@ 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 attachTransitions(Object.assign({ context }, transitions), transitions);
   }
 
   // If fns is a machine (has context property), extract just the transition functions
-  const transitions = 'context' in fnsOrFactory ? Object.fromEntries(
-    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 stored = getStoredTransitions(fnsOrFactory);
+  const transitions = stored ?? ('context' in fnsOrFactory
+    ? snapshotOwnTransitions(fnsOrFactory)
+    : fnsOrFactory);
 
   const machine = Object.assign({ context }, transitions);
-  return machine;
+  return attachTransitions(machine, transitions);
 }
 
 /**
@@ -481,36 +451,21 @@ 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 attachTransitions(Object.assign({ context }, transitions), transitions);
   }
 
   // If fns is a machine (has context property), extract just the transition functions
-  const transitions = 'context' in fnsOrFactory ? Object.fromEntries(
-    Object.entries(fnsOrFactory).filter(([key]) => key !== 'context')
-  ) : fnsOrFactory;
+  const stored = getStoredTransitions(fnsOrFactory);
+  const transitions = stored ?? ('context' in fnsOrFactory
+    ? snapshotOwnTransitions(fnsOrFactory)
+    : fnsOrFactory);
 
   const machine = Object.assign({ context }, transitions);
-  return machine;
+  return attachTransitions(machine, transitions);
 }
 
 /**
@@ -575,10 +530,12 @@ export function setContext<M extends Machine<any>>(
   machine: M,
   newContextOrFn: Context<M> | ((ctx: Readonly<Context<M>>) => Context<M>)
 ): M {
-  const { context, ...transitions } = machine;
+  const currentContext = machine.context;
+  const transitions =
+    getStoredTransitions(machine) ?? snapshotOwnTransitions(machine);
   const newContext =
     typeof newContextOrFn === "function"
-      ? (newContextOrFn as (ctx: Readonly<Context<M>>) => Context<M>)(context)
+      ? (newContextOrFn as (ctx: Readonly<Context<M>>) => Context<M>)(currentContext)
       : newContextOrFn;
 
   return createMachine(newContext, transitions as any) as M;
@@ -682,14 +639,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 +829,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;
 
@@ -986,8 +943,7 @@ export function next<C extends object>(
   m: Machine<C>,
   update: (ctx: Readonly<C>) => C
 ): Machine<C> {
-  const { context, ...transitions } = m;
-  return createMachine(update(context), transitions as any) as Machine<C>;
+  return setContext(m, (ctx) => update(ctx)) as Machine<C>;
 }
 
 /**
@@ -1164,4 +1120,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/internal-transitions.ts

@@ -0,0 +1,32 @@
+const TRANSITIONS_SYMBOL = Symbol.for("__machine_transitions__");
+
+export type TransitionMap = Record<string, (...args: any[]) => any>;
+
+export function attachTransitions<T extends object>(
+  machine: T,
+  transitions: TransitionMap
+): T {
+  Object.defineProperty(machine, TRANSITIONS_SYMBOL, {
+    value: transitions,
+    enumerable: false,
+    configurable: false,
+  });
+  return machine;
+}
+
+export function getStoredTransitions(machine: any): TransitionMap | undefined {
+  if (!machine || typeof machine !== "object") {
+    return undefined;
+  }
+  return machine[TRANSITIONS_SYMBOL];
+}
+
+export function snapshotOwnTransitions(source: any): TransitionMap {
+  if (!source || typeof source !== "object") {
+    return {};
+  }
+  const entries = Object.entries(source).filter(
+    ([key, value]) => key !== "context" && typeof value === "function"
+  );
+  return Object.fromEntries(entries) as TransitionMap;
+}

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]>>;
-}
+}