@doeixd/machine 0.0.8 → 0.0.9

package/src/primitives.ts

@@ -228,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
@@ -316,9 +317,9 @@ export function action<
 /**
  * Configuration options for guard behavior when conditions fail.
  */
-export interface GuardOptions<C extends object = any> {
+export interface GuardOptions<C extends object = any, TFailure extends Machine<any> = Machine<C>> {
   /** What to do when guard fails */
-  onFail?: 'throw' | 'ignore' | GuardFallback<C>;
+  onFail?: 'throw' | 'ignore' | GuardFallback<C, TFailure>;
 
   /** Custom error message for 'throw' mode */
   errorMessage?: string;
@@ -330,31 +331,36 @@ export interface GuardOptions<C extends object = any> {
 /**
  * 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>;
+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, T extends Machine<any>> = {
-  (...args: any[]): T | Machine<C> | Promise<T | Machine<C>>;
+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[]) => T;
+  readonly transition: (...args: any[]) => TSuccess;
 };
 
 /**
- * Creates a runtime guard that checks conditions before executing transitions.
- * This provides actual runtime protection, unlike the `guarded` primitive which only adds metadata.
+ * 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 T - The transition return type
- * @param condition - Function that returns true if transition should proceed
+ * @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 guarded transition function
+ * @returns A synchronous guarded transition function
  *
  * @example
  * ```typescript
@@ -368,22 +374,131 @@ export type GuardedTransition<C extends object, T extends Machine<any>> = {
  *   )
  * });
  *
- * machine.withdraw(50); // ✅ Works
+ * machine.withdraw(50); // ✅ Works synchronously
  * machine.withdraw(200); // ❌ Throws "Insufficient funds"
  * ```
  */
-export function guard<C extends object, T extends Machine<any>>(
+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[]) => T,
-  options: GuardOptions<C> = {}
-): GuardedTransition<C, T> {
+  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<T | Machine<C>> {
+  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);
@@ -404,7 +519,7 @@ export function guard<C extends object, T extends Machine<any>>(
       } else if (onFail === 'ignore') {
         if (isMachine) {
           // Return the current machine unchanged
-          return this as Machine<C>;
+          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.');
@@ -412,13 +527,13 @@ export function guard<C extends object, T extends Machine<any>>(
       } else if (typeof onFail === 'function') {
         // Custom fallback function - call with machine as 'this'
         if (isMachine) {
-          return onFail.apply(this as Machine<C>, args);
+          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;
+        return onFail as TSuccess | TFailure;
       }
     }
   };
@@ -435,15 +550,113 @@ export function guard<C extends object, T extends Machine<any>>(
     guards: [{ name: 'runtime_guard', description: description || 'Runtime condition check' }]
   });
 
-  return guardedTransition as GuardedTransition<C, T>;
+  return guardedTransition as GuardedTransition<C, TSuccess, TFailure>;
 }
 
 /**
- * Fluent API for creating guarded transitions.
- * Provides a more readable way to define conditional transitions.
+ * 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
- * @param condition - Function that returns true if transition should proceed
+ * @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
@@ -460,7 +673,7 @@ export function guard<C extends object, T extends Machine<any>>(
  * ```
  */
 export function whenGuard<C extends object>(
-  condition: (ctx: C, ...args: any[]) => boolean | Promise<boolean>
+  condition: (ctx: C, ...args: any[]) => boolean
 ) {
   return {
     /**
@@ -480,6 +693,53 @@ export function whenGuard<C extends object>(
   };
 }
 
+/**
+ * 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.
  *