@doeixd/machine 0.0.7 → 0.0.9

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.
@@ -211,6 +228,7 @@ export function describe<
  * Annotates a transition with a Guard condition.
  * Note: This only adds metadata. You must still implement the `if` check inside your function.
  *
+ * @deprecated Use the runtime `guard()` primitive instead. Its `options.description` is used for static analysis.
  * @param guard - Object containing the name and optional description of the guard.
  * @param transition - The transition function to guard.
  * @example
@@ -236,17 +254,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 +310,436 @@ 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, TFailure extends Machine<any> = Machine<C>> {
+  /** What to do when guard fails */
+  onFail?: 'throw' | 'ignore' | GuardFallback<C, TFailure>;
+
+  /** 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, TFailure extends Machine<any> = Machine<C>> =
+  | ((this: Machine<C>, ...args: any[]) => TFailure)
+  | TFailure;
+
+/**
+ * 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,
+  TSuccess extends Machine<any>,
+  TFailure extends Machine<any> = Machine<C>
+> = {
+  (...args: any[]): TSuccess | TFailure | Promise<TSuccess | TFailure>;
+  readonly __guard: true;
+  readonly condition: (ctx: C, ...args: any[]) => boolean | Promise<boolean>;
+  readonly transition: (...args: any[]) => TSuccess;
+};
+
+/**
+ * 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.
+ *
+ * @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>)
+ * @param condition - Synchronous 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 synchronous 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 synchronously
+ * machine.withdraw(200); // ❌ Throws "Insufficient funds"
+ * ```
+ */
+export function guard<
+  C extends object,
+  TSuccess extends Machine<any>,
+  TFailure extends Machine<any> = Machine<C>
+>(
+  condition: (ctx: C, ...args: any[]) => boolean,
+  transition: (...args: any[]) => TSuccess,
+  options: GuardOptions<C, TFailure> = {}
+): (...args: any[]) => TSuccess | TFailure {
+  const { onFail = 'throw', errorMessage, description } = options;
+
+  // Merge defaults into options for the metadata
+  const fullOptions = { ...options, onFail, errorMessage, description };
+
+  // Create the guarded transition function (synchronous)
+  const guardedTransition = function(this: C | Machine<C>, ...args: any[]): TSuccess | TFailure {
+    // 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 (synchronously)
+    const conditionResult = 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 TSuccess | TFailure;
+        } 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) as TSuccess | TFailure;
+        } else {
+          throw new Error('Cannot use function fallback with context-only binding. Use full machine binding.');
+        }
+      } else {
+        // Static fallback machine
+        return onFail as TSuccess | TFailure;
+      }
+    }
+  };
+
+  // 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 || 'Synchronous guarded transition',
+    guards: [{ name: 'runtime_guard', description: description || 'Synchronous condition check' }]
+  });
+
+  return guardedTransition;
+}
+
+/**
+ * Creates a runtime guard that checks conditions before executing transitions.
+ * This provides actual runtime protection, unlike the `guarded` primitive which only adds metadata.
+ * Use this when your condition or transition logic is asynchronous.
+ *
+ * @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>)
+ * @param condition - Function that returns true if transition should proceed (can be async)
+ * @param transition - The transition function to execute if condition passes
+ * @param options - Configuration for guard failure behavior
+ * @returns A guarded transition function that returns a Promise
+ *
+ * @example
+ * ```typescript
+ * const machine = createMachine({ balance: 100 }, {
+ *   withdraw: guardAsync(
+ *     async (ctx, amount) => {
+ *       // Simulate API call to check balance
+ *       await new Promise(resolve => setTimeout(resolve, 100));
+ *       return ctx.balance >= amount;
+ *     },
+ *     async function(amount: number) {
+ *       // Simulate API call to process withdrawal
+ *       await new Promise(resolve => setTimeout(resolve, 100));
+ *       return createMachine({ balance: this.balance - amount }, this);
+ *     },
+ *     { onFail: 'throw', errorMessage: 'Insufficient funds' }
+ *   )
+ * });
+ *
+ * await machine.withdraw(50); // ✅ Works
+ * await machine.withdraw(200); // ❌ Throws "Insufficient funds"
+ * ```
+ */
+export function guardAsync<
+  C extends object,
+  TSuccess extends Machine<any>,
+  TFailure extends Machine<any> = Machine<C>
+>(
+  condition: (ctx: C, ...args: any[]) => boolean | Promise<boolean>,
+  transition: (...args: any[]) => TSuccess,
+  options: GuardOptions<C, TFailure> = {}
+): GuardedTransition<C, TSuccess, TFailure> {
+  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<TSuccess | TFailure> {
+    // 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 TSuccess | TFailure;
+        } 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) as TSuccess | TFailure;
+        } else {
+          throw new Error('Cannot use function fallback with context-only binding. Use full machine binding.');
+        }
+      } else {
+        // Static fallback machine
+        return onFail as TSuccess | TFailure;
+      }
+    }
+  };
+
+  // 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, TSuccess, TFailure>;
+}
+
+/**
+ * Creates a synchronous guard that checks conditions before executing transitions.
+ * This is the synchronous counterpart to `guard()` - use this when your machine
+ * doesn't need async transitions to avoid unnecessary Promise overhead.
+ *
+ * @template C - The context type
+ * @template T - The transition return type
+ * @param condition - Function that returns true if transition should proceed (must be synchronous)
+ * @param transition - The transition function to execute if condition passes (must be synchronous)
+ * @param options - Configuration for guard failure behavior
+ * @returns A synchronous guarded transition function
+ *
+ * @example
+ * ```typescript
+ * const machine = createMachine({ balance: 100 }, {
+ *   withdraw: guardSync(
+ *     (ctx, amount) => ctx.balance >= amount,
+ *     function(amount: number) {
+ *       return createMachine({ balance: this.balance - amount }, this);
+ *     },
+ *     { onFail: 'throw', errorMessage: 'Insufficient funds' }
+ *   )
+ * });
+ *
+ * machine.withdraw(50); // ✅ Works synchronously
+ * machine.withdraw(200); // ❌ Throws "Insufficient funds"
+ * ```
+ */
+export function guardSync<
+  C extends object,
+  TSuccess extends Machine<any>,
+  TFailure extends Machine<any> = Machine<C>
+>(
+  condition: (ctx: C, ...args: any[]) => boolean,
+  transition: (...args: any[]) => TSuccess,
+  options: GuardOptions<C, TFailure> = {}
+): GuardedTransition<C, TSuccess, TFailure> {
+  const { onFail = 'throw', errorMessage, description } = options;
+
+  // Merge defaults into options for the metadata
+  const fullOptions = { ...options, onFail, errorMessage, description };
+
+  // Create the guarded transition function (synchronous)
+  const guardedTransition = function(this: C | Machine<C>, ...args: any[]): TSuccess | TFailure {
+    // 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 (synchronously)
+    const conditionResult = 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 TSuccess | TFailure;
+        } 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) as TSuccess | TFailure;
+        } else {
+          throw new Error('Cannot use function fallback with context-only binding. Use full machine binding.');
+        }
+      } else {
+        // Static fallback machine
+        return onFail as TSuccess | TFailure;
+      }
+    }
+  };
+
+  // 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 || 'Synchronous guarded transition',
+    guards: [{ name: 'runtime_guard_sync', description: description || 'Synchronous condition check' }]
+  });
+
+  return guardedTransition as GuardedTransition<C, TSuccess, TFailure>;
+}
+
+/**
+ * Fluent API for creating synchronous guarded transitions.
+ * Provides a more readable way to define conditional transitions with synchronous execution.
+ *
+ * @template C - The context type
+ * @param condition - Synchronous 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
+) {
+  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;
+    }
+  };
+}
+
+/**
+ * Fluent API for creating asynchronous guarded transitions.
+ * Provides a more readable way to define conditional transitions with async execution.
+ *
+ * @template C - The context type
+ * @param condition - Function that returns true if transition should proceed (can be async)
+ * @returns A fluent interface for defining the guarded transition
+ *
+ * @example
+ * ```typescript
+ * const machine = createMachine({ isAdmin: false }, {
+ *   deleteUser: whenGuardAsync(async (ctx) => {
+ *     // Simulate API call
+ *     await checkPermissions(ctx.userId);
+ *     return ctx.isAdmin;
+ *   })
+ *     .do(async function(userId: string) {
+ *       await deleteUserFromDB(userId);
+ *       return createMachine({ ...this.context, deleted: userId }, this);
+ *     })
+ *     .else(function() {
+ *       return createMachine({ ...this.context, error: 'Unauthorized' }, this);
+ *     })
+ * });
+ * ```
+ */
+export function whenGuardAsync<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 = guardAsync(condition, transition);
+
+      // Add fluent else method to the guarded transition
+      (guarded as any).else = function<F extends Machine<any>>(fallback: (...args: any[]) => F) {
+        return guardAsync(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;
     }
   }