@doeixd/machine 0.0.7 → 0.0.8

package/src/primitives.ts

@@ -15,6 +15,14 @@
 // SECTION: CORE METADATA TYPES
 // =============================================================================
 
+/**
+ * Options passed to async transition functions, including cancellation support.
+ */
+export interface TransitionOptions {
+  /** AbortSignal for cancelling long-running async operations. */
+  signal: AbortSignal;
+}
+
 /**
  * A unique symbol used to "brand" a type with metadata.
  * This key allows the static analyzer to find the metadata within a complex type signature.
@@ -23,11 +31,20 @@ export const META_KEY = Symbol("MachineMeta");
 
 /**
  * Runtime metadata symbol.
+/**
  * Non-enumerable property key for storing metadata on function objects at runtime.
  * @internal
  */
 export const RUNTIME_META = Symbol('__machine_runtime_meta__');
 
+/**
+ * Local definition of Machine type to avoid circular imports.
+ * @internal
+ */
+type Machine<C extends object> = {
+  readonly context: C;
+} & Record<string, (...args: any[]) => Machine<any>>;
+
 /**
  * Helper type representing a Class Constructor.
  * Used to reference target states by their class definition rather than magic strings.
@@ -236,17 +253,20 @@ export function guarded<
  * Annotates a transition with an Invoked Service (asynchronous effect).
  *
  * @param service - configuration for the service (source, onDone target, onError target).
- * @param implementation - The async function implementation.
+ * @param implementation - The async function implementation that receives an AbortSignal.
  * @example
  * load = invoke(
  *   { src: "fetchData", onDone: LoadedMachine, onError: ErrorMachine },
- *   async () => { ... }
+ *   async ({ signal }) => {
+ *     const response = await fetch('/api/data', { signal });
+ *     return new LoadedMachine({ data: await response.json() });
+ *   }
  * );
  */
 export function invoke<
   D extends ClassConstructor,
   E extends ClassConstructor,
-  F extends (...args: any[]) => any
+  F extends (options: { signal: AbortSignal }) => any
 >(
   service: { src: string; onDone: D; onError: E; description?: string },
   implementation: F
@@ -289,6 +309,177 @@ export function action<
   return transition as any;
 }
 
+// =============================================================================
+// SECTION: RUNTIME GUARDS
+// =============================================================================
+
+/**
+ * Configuration options for guard behavior when conditions fail.
+ */
+export interface GuardOptions<C extends object = any> {
+  /** What to do when guard fails */
+  onFail?: 'throw' | 'ignore' | GuardFallback<C>;
+
+  /** Custom error message for 'throw' mode */
+  errorMessage?: string;
+
+  /** Additional metadata for statechart extraction */
+  description?: string;
+}
+
+/**
+ * A fallback machine or function that returns a machine when guard fails.
+ */
+export type GuardFallback<C extends object> =
+  | ((this: Machine<C>, ...args: any[]) => Machine<C>)
+  | Machine<C>;
+
+/**
+ * A guarded transition that checks conditions at runtime before executing.
+ * Can be called with either machine or context as 'this' binding.
+ */
+export type GuardedTransition<C extends object, T extends Machine<any>> = {
+  (...args: any[]): T | Machine<C> | Promise<T | Machine<C>>;
+  readonly __guard: true;
+  readonly condition: (ctx: C, ...args: any[]) => boolean | Promise<boolean>;
+  readonly transition: (...args: any[]) => T;
+};
+
+/**
+ * Creates a runtime guard that checks conditions before executing transitions.
+ * This provides actual runtime protection, unlike the `guarded` primitive which only adds metadata.
+ *
+ * @template C - The context type
+ * @template T - The transition return type
+ * @param condition - Function that returns true if transition should proceed
+ * @param transition - The transition function to execute if condition passes
+ * @param options - Configuration for guard failure behavior
+ * @returns A guarded transition function
+ *
+ * @example
+ * ```typescript
+ * const machine = createMachine({ balance: 100 }, {
+ *   withdraw: guard(
+ *     (ctx, amount) => ctx.balance >= amount,
+ *     function(amount: number) {
+ *       return createMachine({ balance: this.balance - amount }, this);
+ *     },
+ *     { onFail: 'throw', errorMessage: 'Insufficient funds' }
+ *   )
+ * });
+ *
+ * machine.withdraw(50); // ✅ Works
+ * machine.withdraw(200); // ❌ Throws "Insufficient funds"
+ * ```
+ */
+export function guard<C extends object, T extends Machine<any>>(
+  condition: (ctx: C, ...args: any[]) => boolean | Promise<boolean>,
+  transition: (...args: any[]) => T,
+  options: GuardOptions<C> = {}
+): GuardedTransition<C, T> {
+  const { onFail = 'throw', errorMessage, description } = options;
+
+  // Merge defaults into options for the metadata
+  const fullOptions = { ...options, onFail, errorMessage, description };
+
+  // Create the guarded transition function
+  const guardedTransition = async function(this: C | Machine<C>, ...args: any[]): Promise<T | Machine<C>> {
+    // Detect if 'this' is a machine or just context
+    const isMachine = typeof this === 'object' && 'context' in this;
+    const ctx = isMachine ? (this as Machine<C>).context : (this as C);
+
+    // Evaluate the condition
+    const conditionResult = await Promise.resolve(condition(ctx, ...args));
+
+    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);
+    } else {
+      // Condition failed, handle according to options
+      if (onFail === 'throw') {
+        const message = errorMessage || 'Guard condition failed';
+        throw new Error(message);
+      } else if (onFail === 'ignore') {
+        if (isMachine) {
+          // Return the current machine unchanged
+          return this as Machine<C>;
+        } else {
+          // Cannot ignore when called with context binding
+          throw new Error('Cannot use "ignore" mode with context-only binding. Use full machine binding or provide fallback.');
+        }
+      } else if (typeof onFail === 'function') {
+        // Custom fallback function - call with machine as 'this'
+        if (isMachine) {
+          return onFail.apply(this as Machine<C>, args);
+        } else {
+          throw new Error('Cannot use function fallback with context-only binding. Use full machine binding.');
+        }
+      } else {
+        // Static fallback machine
+        return onFail;
+      }
+    }
+  };
+
+  // Attach metadata for type branding and statechart extraction
+  Object.defineProperty(guardedTransition, '__guard', { value: true, enumerable: false });
+  Object.defineProperty(guardedTransition, 'condition', { value: condition, enumerable: false });
+  Object.defineProperty(guardedTransition, 'transition', { value: transition, enumerable: false });
+  Object.defineProperty(guardedTransition, 'options', { value: fullOptions, enumerable: false });
+
+  // Attach runtime metadata for statechart extraction
+  attachRuntimeMeta(guardedTransition, {
+    description: description || 'Runtime guarded transition',
+    guards: [{ name: 'runtime_guard', description: description || 'Runtime condition check' }]
+  });
+
+  return guardedTransition as GuardedTransition<C, T>;
+}
+
+/**
+ * Fluent API for creating guarded transitions.
+ * Provides a more readable way to define conditional transitions.
+ *
+ * @template C - The context type
+ * @param condition - Function that returns true if transition should proceed
+ * @returns A fluent interface for defining the guarded transition
+ *
+ * @example
+ * ```typescript
+ * const machine = createMachine({ isAdmin: false }, {
+ *   deleteUser: whenGuard((ctx) => ctx.isAdmin)
+ *     .do(function(userId: string) {
+ *       return createMachine({ ...this.context, deleted: userId }, this);
+ *     })
+ *     .else(function() {
+ *       return createMachine({ ...this.context, error: 'Unauthorized' }, this);
+ *     })
+ * });
+ * ```
+ */
+export function whenGuard<C extends object>(
+  condition: (ctx: C, ...args: any[]) => boolean | Promise<boolean>
+) {
+  return {
+    /**
+     * Define the transition to execute when the condition passes.
+     * Returns a guarded transition that can optionally have an else clause.
+     */
+    do<T extends Machine<any>>(transition: (...args: any[]) => T) {
+      const guarded = guard(condition, transition);
+
+      // Add fluent else method to the guarded transition
+      (guarded as any).else = function<F extends Machine<any>>(fallback: (...args: any[]) => F) {
+        return guard(condition, transition, { onFail: fallback });
+      };
+
+      return guarded;
+    }
+  };
+}
+
 /**
  * Flexible metadata wrapper for functional and type-state patterns.
  *

package/src/runtime-extract.ts

@@ -69,6 +69,21 @@ export function extractStateNode(stateInstance: any): any {
         transition.actions = meta.actions.map(a => a.name);
       }
 
+      stateNode.on[key] = transition;
+    }
+    // If has guards but no target, it's a guarded transition (runtime guard)
+    else if (meta.guards && meta.guards.length > 0) {
+      // For runtime guards, we can't determine the target statically
+      // So we create a transition with a placeholder target and guard condition
+      const transition: any = {
+        target: 'GuardedTransition', // Placeholder - actual target determined at runtime
+        cond: meta.guards.map(g => g.name).join(' && ')
+      };
+
+      if (meta.description) {
+        transition.description = meta.description;
+      }
+
       stateNode.on[key] = transition;
     }
   }

package/src/utils.ts

@@ -300,9 +300,12 @@ export class BoundMachine<M extends { context: any }> {
     return new Proxy(this, {
       get: (target, prop) => {
         // Handle direct property access to wrapped machine
-        if (prop === 'wrappedMachine' || prop === 'context') {
+        if (prop === 'wrappedMachine') {
           return Reflect.get(target, prop);
         }
+        if (prop === 'context') {
+          return this.wrappedMachine.context;
+        }
 
         const value = this.wrappedMachine[prop as keyof M];
 
@@ -323,11 +326,223 @@ export class BoundMachine<M extends { context: any }> {
       },
     }) as any;
   }
+}
 
-  /**
-   * Access the underlying machine's context directly.
-   */
-  get context(): M extends { context: infer C } ? C : never {
-    return this.wrappedMachine.context;
+/**
+ * Creates a sequence machine that orchestrates multi-step flows by automatically
+ * advancing through a series of machines. When the current machine reaches a "final"
+ * state (determined by the isFinal predicate), the sequence automatically transitions
+ * to the next machine in the sequence.
+ *
+ * This implementation uses a functional approach with object delegation rather than Proxy.
+ */
+function createSequenceMachine<
+  M extends readonly [Machine<any>, ...Machine<any>[]]
+>(
+  machines: M,
+  isFinal: (machine: M[number]) => boolean
+): M[number] {
+  if (machines.length === 0) {
+    throw new Error('Sequence must contain at least one machine');
   }
+
+  let currentIndex = 0;
+  let currentMachine = machines[0];
+
+  const createDelegationObject = (machine: M[number]) => {
+    const delegationObject = Object.create(machine);
+
+    // The context getter returns the machine's own context
+    // (machine is the specific machine instance this delegation object represents)
+    Object.defineProperty(delegationObject, 'context', {
+      get: () => machine.context,
+      enumerable: true,
+      configurable: true
+    });
+
+    // Override all methods to add advancement logic
+    const originalProto = Object.getPrototypeOf(machine);
+    const methodNames = Object.getOwnPropertyNames(originalProto).filter(name =>
+      name !== 'constructor' && name !== 'context' && typeof (machine as any)[name] === 'function'
+    );
+
+    for (const methodName of methodNames) {
+      const methodKey = methodName as keyof any;
+
+      (delegationObject as any)[methodKey] = (...args: unknown[]) => {
+        const result = (currentMachine as any)[methodKey](...args);
+
+        // Handle both sync and async results
+        const handleResult = (resultMachine: unknown) => {
+          return advanceIfNeeded(resultMachine as M[number]);
+        };
+
+        // If the result is a Promise, handle it asynchronously
+        if (result && typeof (result as any).then === 'function') {
+          return (result as Promise<unknown>).then(handleResult);
+        }
+
+        // Otherwise, handle synchronously
+        return handleResult(result);
+      };
+    }
+
+    return delegationObject;
+  };
+
+  const advanceIfNeeded = (machine: M[number]): M[number] => {
+    currentMachine = machine;
+
+    // Check if we should advance to the next machine
+    if (isFinal(currentMachine) && currentIndex < machines.length - 1) {
+      currentIndex++;
+      currentMachine = machines[currentIndex];
+      // Create a new delegation object for the new currentMachine
+      return createDelegationObject(currentMachine);
+    }
+
+    return machine;
+  };
+
+  return createDelegationObject(currentMachine);
+}
+/**
+ * Creates a sequence machine that orchestrates multi-step flows by automatically
+ * advancing through a series of machines. When the current machine reaches a "final"
+ * state (determined by the isFinal predicate), the sequence automatically transitions
+ * to the next machine in the sequence.
+ *
+ * This is perfect for wizard-style flows, multi-step processes, or any scenario where
+ * you need to chain machines together with automatic progression.
+ *
+ * @template M - The tuple of machine types in the sequence.
+ * @param machines - The machines to sequence, in order.
+ * @param isFinal - A predicate function that determines when a machine is in a final state.
+ *                  Called after each transition to check if the sequence should advance.
+ * @returns A new machine that wraps the sequence, delegating to the current machine
+ *          and automatically advancing when each machine reaches its final state.
+ *
+ * @example
+ * ```typescript
+ * // Define form machines with final states
+ * class NameForm extends MachineBase<{ name: string; valid: boolean }> {
+ *   submit = (name: string) => new NameForm({ name, valid: name.length > 0 });
+ * }
+ *
+ * class EmailForm extends MachineBase<{ email: string; valid: boolean }> {
+ *   submit = (email: string) => new EmailForm({ email, valid: email.includes('@') });
+ * }
+ *
+ * class PasswordForm extends MachineBase<{ password: string; valid: boolean }> {
+ *   submit = (password: string) => new PasswordForm({ password, valid: password.length >= 8 });
+ * }
+ *
+ * // Create sequence that advances when each form becomes valid
+ * const wizard = sequence(
+ *   [new NameForm({ name: '', valid: false }),
+ *    new EmailForm({ email: '', valid: false }),
+ *    new PasswordForm({ password: '', valid: false })],
+ *   (machine) => machine.context.valid // Advance when valid becomes true
+ * );
+ *
+ * // Usage - automatically advances through forms
+ * let current = wizard;
+ * current = current.submit('John');     // Still on NameForm (not valid yet)
+ * current = current.submit('John Doe'); // Advances to EmailForm (name is valid)
+ * current = current.submit('john@');    // Still on EmailForm (not valid yet)
+ * current = current.submit('john@example.com'); // Advances to PasswordForm
+ * current = current.submit('12345678'); // Advances to end of sequence
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async sequence with API calls
+ * const authSequence = sequence(
+ *   [new LoginForm(), new TwoFactorForm(), new Dashboard()],
+ *   (machine) => machine.context.authenticated === true
+ * );
+ *
+ * // The sequence handles async transitions automatically
+ * const finalState = await authSequence.login('user@example.com', 'password');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Complex predicate - advance based on multiple conditions
+ * const complexSequence = sequence(
+ *   [step1Machine, step2Machine, step3Machine],
+ *   (machine) => {
+ *     // Advance when all required fields are filled AND validated
+ *     return machine.context.requiredFields.every(f => f.filled) &&
+ *            machine.context.validationErrors.length === 0;
+ *   }
+ * );
+ * ```
+ *
+ * @remarks
+ * - The sequence maintains the union type of all machines in the sequence
+ * - Transitions are delegated to the current machine in the sequence
+ * - When a machine reaches a final state, the sequence automatically advances
+ * - If the sequence reaches the end, further transitions return the final machine
+ * - The isFinal predicate is called after every transition to check advancement
+ * - Works with both sync and async machines (returns MaybePromise)
+ */
+export function sequence<
+  M extends readonly [Machine<any>, ...Machine<any>[]]
+>(
+  machines: M,
+  isFinal: (machine: M[number]) => boolean
+): M[number] {
+  return createSequenceMachine(machines, isFinal);
+}
+
+/**
+ * Convenience overload for sequencing exactly 2 machines.
+ * Provides better type inference and IntelliSense for common 2-step flows.
+ *
+ * @example
+ * ```typescript
+ * const flow = sequence2(
+ *   new LoginForm(),
+ *   new Dashboard(),
+ *   (machine) => machine.context.authenticated
+ * );
+ * ```
+ */
+export function sequence2<
+  M1 extends Machine<any>,
+  M2 extends Machine<any>
+>(
+  machine1: M1,
+  machine2: M2,
+  isFinal: (machine: M1 | M2) => boolean
+): M1 | M2 {
+  return sequence([machine1, machine2], isFinal);
+}
+
+/**
+ * Convenience overload for sequencing exactly 3 machines.
+ * Provides better type inference and IntelliSense for common 3-step flows.
+ *
+ * @example
+ * ```typescript
+ * const wizard = sequence3(
+ *   new NameForm({ name: '', valid: false }),
+ *   new EmailForm({ email: '', valid: false }),
+ *   new PasswordForm({ password: '', valid: false }),
+ *   (machine) => machine.context.valid
+ * );
+ * ```
+ */
+export function sequence3<
+  M1 extends Machine<any>,
+  M2 extends Machine<any>,
+  M3 extends Machine<any>
+>(
+  machine1: M1,
+  machine2: M2,
+  machine3: M3,
+  isFinal: (machine: M1 | M2 | M3) => boolean
+): M1 | M2 | M3 {
+  return sequence([machine1, machine2, machine3], isFinal);
 }