@doeixd/machine 0.0.7 → 0.0.8

package/dist/types/middleware.d.ts

@@ -0,0 +1,1048 @@
+/**
+ * @file Middleware/interception system for state machines
+ * @description Provides composable middleware for logging, analytics, validation, and more.
+ */
+import type { Context, BaseMachine } from './index';
+/**
+ * Context object passed to middleware hooks containing transition metadata.
+ * @template C - The context object type
+ */
+export interface MiddlewareContext<C extends object> {
+    /** The name of the transition being called */
+    transitionName: string;
+    /** The current machine context before the transition */
+    context: Readonly<C>;
+    /** Arguments passed to the transition function */
+    args: any[];
+}
+/**
+ * Result object passed to after hooks containing transition outcome.
+ * @template C - The context object type
+ */
+export interface MiddlewareResult<C extends object> {
+    /** The name of the transition that was called */
+    transitionName: string;
+    /** The context before the transition */
+    prevContext: Readonly<C>;
+    /** The context after the transition */
+    nextContext: Readonly<C>;
+    /** Arguments that were passed to the transition */
+    args: any[];
+}
+/**
+ * Error context passed to error hooks.
+ * @template C - The context object type
+ */
+export interface MiddlewareError<C extends object> {
+    /** The name of the transition that failed */
+    transitionName: string;
+    /** The context when the error occurred */
+    context: Readonly<C>;
+    /** Arguments that were passed to the transition */
+    args: any[];
+    /** The error that was thrown */
+    error: Error;
+}
+/**
+ * Configuration object for middleware hooks.
+ * All hooks are optional - provide only the ones you need.
+ * @template C - The context object type
+ */
+/**
+ * Strongly typed middleware hooks with precise context and return types.
+ * All hooks are optional - provide only the ones you need.
+ *
+ * @template C - The machine context type for precise type inference
+ */
+export interface MiddlewareHooks<C extends object> {
+    /**
+     * Called before a transition executes.
+     * Can be used for validation, logging, analytics, etc.
+     *
+     * @param ctx - Transition context with machine state and transition details
+     * @returns void to continue, CANCEL to abort silently, or Promise for async validation
+     *
+     * @example
+     * ```typescript
+     * before: ({ transitionName, args, context }) => {
+     *   if (transitionName === 'withdraw' && context.balance < args[0]) {
+     *     throw new Error('Insufficient funds');
+     *   }
+     * }
+     * ```
+     */
+    before?: (ctx: MiddlewareContext<C>) => void | typeof CANCEL | Promise<void | typeof CANCEL>;
+    /**
+     * Called after a transition successfully executes.
+     * Receives both the previous and next context.
+     * Cannot prevent the transition (it already happened).
+     *
+     * @param result - Transition result with before/after contexts and transition details
+     *
+     * @example
+     * ```typescript
+     * after: ({ transitionName, before, after }) => {
+     *   console.log(`${transitionName}: ${before.count} -> ${after.count}`);
+     * }
+     * ```
+     */
+    after?: (result: MiddlewareResult<C>) => void | Promise<void>;
+    /**
+     * Called if a transition throws an error.
+     * Can be used for error logging, Sentry reporting, fallback states, etc.
+     *
+     * @param error - Error context with transition details and the thrown error
+     * @returns
+     * - void/undefined/null: Re-throw the original error (default)
+     * - BaseMachine: Use this as fallback state instead of throwing
+     * - throw new Error: Transform the error
+     *
+     * @example
+     * ```typescript
+     * error: ({ transitionName, error, context }) => {
+     *   // Log to error reporting service
+     *   reportError(error, { transitionName, context });
+     *
+     *   // Return fallback state for recoverable errors
+     *   if (error.message.includes('network')) {
+     *     return createMachine({ ...context, error: 'offline' }, transitions);
+     *   }
+     * }
+     * ```
+     */
+    error?: (error: MiddlewareError<C>) => void | null | BaseMachine<C> | Promise<void | null | BaseMachine<C>>;
+}
+/**
+ * Options for middleware configuration.
+ */
+export interface MiddlewareOptions {
+    /**
+     * Execution mode for middleware hooks.
+     * - 'sync': Hooks must be synchronous, throws if hooks return Promise
+     * - 'async': Always await hooks and transition
+     * - 'auto' (default): Adaptive mode - starts synchronously, automatically handles async results if encountered
+     *
+     * Note: 'auto' mode provides the best of both worlds - zero overhead for sync transitions
+     * while seamlessly handling async ones when they occur.
+     * @default 'auto'
+     */
+    mode?: 'sync' | 'async' | 'auto';
+    /**
+     * Properties to exclude from middleware interception.
+     * Useful for excluding utility methods or getters.
+     * @default ['context']
+     */
+    exclude?: string[];
+}
+/**
+ * Special symbol that can be returned from before hooks to cancel a transition.
+ * When returned, the transition will not execute and the current machine state is preserved.
+ *
+ * @example
+ * createMiddleware(machine, {
+ *   before: ({ transitionName, context }) => {
+ *     if (shouldCancel(context)) {
+ *       return CANCEL; // Abort transition without throwing
+ *     }
+ *   }
+ * });
+ */
+export declare const CANCEL: unique symbol;
+/**
+ * Augmented machine type with history tracking capabilities.
+ * @template M - The base machine type
+ * @template C - The context type
+ */
+export type WithHistory<M extends BaseMachine<any>> = M & {
+    /** Array of recorded transition history entries */
+    history: HistoryEntry[];
+    /** Clear all history entries */
+    clearHistory: () => void;
+};
+/**
+ * Augmented machine type with snapshot tracking capabilities.
+ * @template M - The base machine type
+ * @template C - The context type
+ */
+export type WithSnapshot<M extends BaseMachine<any>, C extends object = Context<M>> = M & {
+    /** Array of recorded context snapshots */
+    snapshots: ContextSnapshot<C>[];
+    /** Clear all snapshots */
+    clearSnapshots: () => void;
+    /** Restore machine to a previous context state */
+    restoreSnapshot: (context: C) => M;
+};
+/**
+ * Augmented machine type with full time-travel debugging capabilities.
+ * Combines both history and snapshot tracking.
+ * @template M - The base machine type
+ * @template C - The context type
+ */
+export type WithTimeTravel<M extends BaseMachine<any>, C extends object = Context<M>> = M & {
+    /** Array of recorded transition history entries */
+    history: HistoryEntry[];
+    /** Array of recorded context snapshots */
+    snapshots: ContextSnapshot<C>[];
+    /** Clear all history and snapshots */
+    clearTimeTravel: () => void;
+    /** Restore machine to a previous context state */
+    restoreSnapshot: (context: C) => M;
+    /** Replay all transitions from a specific snapshot */
+    replayFrom: (snapshotIndex: number) => M;
+};
+/**
+ * Wraps a machine with middleware hooks that intercept all transitions.
+ * Uses direct property wrapping for optimal performance (3x faster than Proxy).
+ *
+ * The middleware preserves:
+ * - Full type safety (return type matches input machine)
+ * - `this` binding for transitions
+ * - Async and sync transitions
+ * - Machine immutability
+ *
+ * @template M - The machine type
+ * @param machine - The machine to wrap with middleware
+ * @param hooks - Middleware hooks (before, after, error)
+ * @param options - Configuration options
+ * @returns A new machine with middleware applied
+ *
+ * @example
+ * const instrumented = createMiddleware(counter, {
+ *   before: ({ transitionName, context, args }) => {
+ *     console.log(`→ ${transitionName}`, args);
+ *   },
+ *   after: ({ transitionName, prevContext, nextContext }) => {
+ *     console.log(`✓ ${transitionName}`, nextContext);
+ *   },
+ *   error: ({ transitionName, error }) => {
+ *     console.error(`✗ ${transitionName}:`, error);
+ *   }
+ * });
+ */
+export declare function createMiddleware<M extends BaseMachine<any>>(machine: M, hooks: MiddlewareHooks<Context<M>>, options?: MiddlewareOptions): M;
+/**
+ * Logging middleware that logs transition calls and results to console.
+ * Useful for debugging and development.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to add logging to
+ * @param options - Optional configuration for logging format
+ * @returns A new machine with logging middleware
+ *
+ * @example
+ * const logged = withLogging(counter);
+ * logged.increment(); // Console: "→ increment []" then "✓ increment { count: 1 }"
+ */
+export declare function withLogging<M extends BaseMachine<any>>(machine: M, options?: {
+    /** Custom logger function (default: console.log) */
+    logger?: (message: string, ...args: any[]) => void;
+    /** Include context in logs (default: true) */
+    includeContext?: boolean;
+    /** Include arguments in logs (default: true) */
+    includeArgs?: boolean;
+}): M;
+/**
+ * Analytics middleware that tracks state transitions.
+ * Compatible with any analytics service (Segment, Mixpanel, GA, etc.).
+ *
+ * @template M - The machine type
+ * @param machine - The machine to track
+ * @param track - Analytics tracking function
+ * @param options - Optional configuration for event naming
+ * @returns A new machine with analytics middleware
+ *
+ * @example
+ * const tracked = withAnalytics(machine, (event, props) => {
+ *   analytics.track(event, props);
+ * });
+ */
+export declare function withAnalytics<M extends BaseMachine<any>>(machine: M, track: (event: string, properties: Record<string, any>) => void | Promise<void>, options?: {
+    /** Prefix for event names (default: "state_transition") */
+    eventPrefix?: string;
+    /** Include previous context in properties (default: false) */
+    includePrevContext?: boolean;
+    /** Include arguments in properties (default: true) */
+    includeArgs?: boolean;
+}): M;
+/**
+ * Validation middleware that validates transitions before they execute.
+ * Throws an error if validation fails, preventing the transition.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to validate
+ * @param validate - Validation function that throws or returns false on invalid transitions
+ * @returns A new machine with validation middleware
+ *
+ * @example
+ * const validated = withValidation(counter, ({ transitionName, context, args }) => {
+ *   if (transitionName === 'decrement' && context.count === 0) {
+ *     throw new Error('Cannot decrement below zero');
+ *   }
+ * });
+ */
+export declare function withValidation<M extends BaseMachine<any>>(machine: M, validate: (ctx: MiddlewareContext<Context<M>>) => void | boolean | Promise<void | boolean>, options?: Pick<MiddlewareOptions, 'mode'>): M;
+/**
+ * Permission/authorization middleware that checks if a transition is allowed.
+ * Useful for implementing role-based access control (RBAC) in state machines.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to protect
+ * @param canPerform - Function that checks if the transition is allowed
+ * @returns A new machine with permission checks
+ *
+ * @example
+ * const protected = withPermissions(machine, (user) => ({ transitionName }) => {
+ *   if (transitionName === 'delete' && user.role !== 'admin') {
+ *     return false;
+ *   }
+ *   return true;
+ * });
+ */
+export declare function withPermissions<M extends BaseMachine<any>>(machine: M, canPerform: (ctx: MiddlewareContext<Context<M>>) => boolean | Promise<boolean>, options?: Pick<MiddlewareOptions, 'mode'>): M;
+/**
+ * Error reporting middleware that sends errors to an error tracking service.
+ * Compatible with Sentry, Bugsnag, Rollbar, etc.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to monitor
+ * @param captureError - Error capture function (e.g., Sentry.captureException)
+ * @param options - Optional configuration for error context
+ * @returns A new machine with error reporting
+ *
+ * @example
+ * const monitored = withErrorReporting(machine, (error, context) => {
+ *   Sentry.captureException(error, { extra: context });
+ * });
+ */
+export declare function withErrorReporting<M extends BaseMachine<any>>(machine: M, captureError: (error: Error, context: Record<string, any>) => void | Promise<void>, options?: {
+    /** Include machine context in error report (default: true) */
+    includeContext?: boolean;
+    /** Include arguments in error report (default: true) */
+    includeArgs?: boolean;
+    /** Middleware execution mode */
+    mode?: MiddlewareOptions['mode'];
+}): M;
+/**
+ * Performance monitoring middleware that tracks transition execution time.
+ * Useful for identifying slow transitions and performance bottlenecks.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to monitor
+ * @param onMetric - Callback to receive performance metrics
+ * @returns A new machine with performance monitoring
+ *
+ * @example
+ * const monitored = withPerformanceMonitoring(machine, ({ transition, duration }) => {
+ *   if (duration > 100) {
+ *     console.warn(`Slow transition: ${transition} took ${duration}ms`);
+ *   }
+ * });
+ */
+export declare function withPerformanceMonitoring<M extends BaseMachine<any>>(machine: M, onMetric: (metric: {
+    transitionName: string;
+    duration: number;
+    context: Readonly<Context<M>>;
+}) => void | Promise<void>): M;
+/**
+ * Retry middleware that automatically retries failed transitions.
+ * Uses direct property wrapping for optimal performance.
+ * Useful for handling transient failures in async operations.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to add retry logic to
+ * @param options - Retry configuration
+ * @returns A new machine with retry logic
+ *
+ * @example
+ * const resilient = withRetry(machine, {
+ *   maxRetries: 3,
+ *   delay: 1000,
+ *   shouldRetry: (error) => error.message.includes('network')
+ * });
+ */
+export declare function withRetry<M extends BaseMachine<any>>(machine: M, options?: {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    delay?: number;
+    /** Exponential backoff multiplier (default: 1, no backoff) */
+    backoffMultiplier?: number;
+    /** Function to determine if error should trigger retry (default: always retry) */
+    shouldRetry?: (error: Error) => boolean;
+    /** Callback when retry occurs */
+    onRetry?: (attempt: number, error: Error) => void;
+}): M;
+/**
+ * Guard configuration for a single transition.
+ */
+export interface GuardConfig<C extends object> {
+    /** Guard predicate function that returns true if transition is allowed */
+    guard: (ctx: MiddlewareContext<C>, ...args: any[]) => boolean | Promise<boolean>;
+    /**
+     * Action to take when guard fails.
+     * - 'throw': Throw an error (default)
+     * - 'ignore': Silently cancel the transition
+     *
+     * Note: For custom fallback machines, use the error hook in createMiddleware:
+     * @example
+     * createMiddleware(machine, {
+     *   error: ({ error, context }) => {
+     *     if (error.message.includes('Guard failed')) {
+     *       return createMachine({ ...context, error: 'Unauthorized' }, machine);
+     *     }
+     *   }
+     * });
+     */
+    onFail?: 'throw' | 'ignore';
+}
+/**
+ * Guard middleware that prevents transitions based on predicate functions.
+ * Implements fundamental FSM guard concept - transitions only occur when guards pass.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to protect with guards
+ * @param guards - Object mapping transition names to guard configurations
+ * @returns A new machine with guard checks
+ *
+ * @example
+ * const guarded = withGuards(counter, {
+ *   decrement: {
+ *     guard: ({ context }) => context.count > 0,
+ *     onFail: 'throw' // or 'ignore'
+ *   },
+ *   delete: {
+ *     guard: ({ context }) => context.user?.isAdmin === true,
+ *     onFail: 'throw'
+ *   }
+ * });
+ *
+ * guarded.decrement(); // Throws if count === 0
+ *
+ * // For custom fallback machines, combine with error middleware:
+ * const guardedWithFallback = createMiddleware(guarded, {
+ *   error: ({ error, context }) => {
+ *     if (error.message.includes('Guard failed')) {
+ *       return createMachine({ ...context, error: 'Unauthorized' }, machine);
+ *     }
+ *   }
+ * });
+ */
+export declare function withGuards<M extends BaseMachine<any>>(machine: M, guards: Record<string, GuardConfig<Context<M>> | ((ctx: MiddlewareContext<Context<M>>, ...args: any[]) => boolean | Promise<boolean>)>, options?: Pick<MiddlewareOptions, 'mode'>): M;
+/**
+ * Creates conditional middleware that only applies to specific transitions.
+ * Useful for targeted instrumentation without affecting all transitions.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to instrument
+ * @param config - Configuration specifying which transitions to instrument
+ * @returns A new machine with conditional middleware
+ *
+ * @example
+ * const conditional = createConditionalMiddleware(counter, {
+ *   only: ['delete', 'update'], // Only these transitions
+ *   hooks: {
+ *     before: ({ transitionName }) => console.log('Sensitive operation:', transitionName),
+ *     after: ({ transitionName }) => auditLog(transitionName)
+ *   }
+ * });
+ *
+ * @example
+ * const excluding = createConditionalMiddleware(counter, {
+ *   except: ['increment'], // All except these
+ *   hooks: {
+ *     before: ({ transitionName, args }) => validate(transitionName, args)
+ *   }
+ * });
+ */
+export declare function createConditionalMiddleware<M extends BaseMachine<any>>(machine: M, config: {
+    /** Only apply to these transitions (mutually exclusive with except) */
+    only?: string[];
+    /** Apply to all except these transitions (mutually exclusive with only) */
+    except?: string[];
+    /** Middleware hooks to apply */
+    hooks: MiddlewareHooks<Context<M>>;
+    /** Middleware options */
+    options?: MiddlewareOptions;
+}): M;
+/**
+ * Creates state-dependent middleware that only applies when a predicate is true.
+ * Allows middleware behavior to change based on current context/state.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to instrument
+ * @param config - Configuration with predicate and hooks
+ * @returns A new machine with state-dependent middleware
+ *
+ * @example
+ * const stateful = createStateMiddleware(counter, {
+ *   when: (ctx) => ctx.debugMode === true,
+ *   hooks: {
+ *     before: (ctx) => console.log('Debug:', ctx),
+ *     after: (result) => console.log('Debug result:', result)
+ *   }
+ * });
+ *
+ * // Logging only happens when context.debugMode === true
+ */
+export declare function createStateMiddleware<M extends BaseMachine<any>>(machine: M, config: {
+    /** Predicate that determines if middleware should apply */
+    when: (ctx: Context<M>) => boolean | Promise<boolean>;
+    /** Middleware hooks to apply when predicate is true */
+    hooks: MiddlewareHooks<Context<M>>;
+    /** Middleware options */
+    options?: MiddlewareOptions;
+}): M;
+/**
+ * Represents a recorded transition call in the history.
+ */
+export interface HistoryEntry {
+    /** Unique ID for this history entry */
+    id: string;
+    /** The transition that was called */
+    transitionName: string;
+    /** Arguments passed to the transition */
+    args: any[];
+    /** Timestamp when the transition was called */
+    timestamp: number;
+    /** Optional serialized version of args (if serializer provided) */
+    serializedArgs?: string;
+}
+/**
+ * Generic serializer/deserializer interface.
+ * Used for serializing history arguments, context snapshots, etc.
+ * @template T - The type being serialized
+ */
+export interface Serializer<T = any> {
+    /** Serialize data to a string */
+    serialize: (data: T) => string;
+    /** Deserialize string back to data */
+    deserialize: (serialized: string) => T;
+}
+/**
+ * History tracking middleware that records all transition calls.
+ * Useful for debugging, replay, undo/redo, and audit logging.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to track
+ * @param options - Configuration options
+ * @returns A new machine with history tracking and a history array
+ *
+ * Note: Arguments are shallow-cloned by default. If you need deep cloning or
+ * serialization for persistence, provide a serializer:
+ *
+ * @example
+ * const tracked = withHistory(counter, {
+ *   maxSize: 100,
+ *   serializer: {
+ *     serialize: (args) => JSON.stringify(args),  // For deep clone or persistence
+ *     deserialize: (str) => JSON.parse(str)
+ *   }
+ * });
+ *
+ * tracked.increment();
+ * tracked.add(5);
+ * console.log(tracked.history); // [{ transitionName: 'increment', args: [], ... }, ...]
+ * tracked.clearHistory(); // Clear history
+ */
+export declare function withHistory<M extends BaseMachine<any>>(machine: M, options?: {
+    /** Maximum number of entries to keep (default: unlimited) */
+    maxSize?: number;
+    /** Optional serializer for arguments */
+    serializer?: Serializer<any[]>;
+    /** Filter function to exclude certain transitions from history */
+    filter?: (transitionName: string, args: any[]) => boolean;
+    /** Callback when new entry is added */
+    onEntry?: (entry: HistoryEntry) => void;
+    /** Internal flag to prevent rewrapping */
+    _isRewrap?: boolean;
+}): WithHistory<M>;
+/**
+ * Represents a snapshot of context at a point in time.
+ * @template C - The context type
+ */
+export interface ContextSnapshot<C extends object = any> {
+    /** Unique ID for this snapshot */
+    id: string;
+    /** The transition that caused this change */
+    transitionName: string;
+    /** Context before the transition */
+    before: C;
+    /** Context after the transition */
+    after: C;
+    /** Timestamp of the snapshot */
+    timestamp: number;
+    /** Optional serialized version of contexts */
+    serializedBefore?: string;
+    serializedAfter?: string;
+    /** Optional diff information */
+    diff?: any;
+}
+/**
+ * Snapshot middleware that records context before/after each transition.
+ * Useful for time-travel debugging, undo/redo, and state inspection.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to track
+ * @param options - Configuration options
+ * @returns A new machine with snapshot tracking and snapshots array
+ *
+ * @example
+ * const tracked = withSnapshot(counter, {
+ *   maxSize: 50,
+ *   serializer: {
+ *     serialize: (ctx) => JSON.stringify(ctx),
+ *     deserialize: (str) => JSON.parse(str)
+ *   },
+ *   captureSnapshot: (before, after) => ({
+ *     changed: before.count !== after.count
+ *   })
+ * });
+ *
+ * tracked.increment();
+ * console.log(tracked.snapshots); // [{ before: { count: 0 }, after: { count: 1 }, ... }]
+ *
+ * // Time-travel: restore to previous state
+ * const previousState = tracked.restoreSnapshot(tracked.snapshots[0].before);
+ */
+export declare function withSnapshot<M extends BaseMachine<any>>(machine: M, options?: {
+    /** Maximum number of snapshots to keep (default: unlimited) */
+    maxSize?: number;
+    /** Optional serializer for context */
+    serializer?: Serializer<Context<M>>;
+    /** Custom function to capture additional snapshot data */
+    captureSnapshot?: (before: Context<M>, after: Context<M>) => any;
+    /** Only capture snapshots where context actually changed */
+    onlyIfChanged?: boolean;
+    /** Filter function to exclude certain transitions from snapshots */
+    filter?: (transitionName: string) => boolean;
+    /** Callback when new snapshot is taken */
+    onSnapshot?: (snapshot: ContextSnapshot<Context<M>>) => void;
+    /** Additional properties to exclude from middleware (for composition) */
+    _extraExclusions?: string[];
+    /** Internal flag to prevent rewrapping */
+    _isRewrap?: boolean;
+}): WithSnapshot<M, Context<M>>;
+/**
+ * Combined history and snapshot middleware for full time-travel debugging.
+ * Records both transition calls and context changes.
+ *
+ * @template M - The machine type
+ * @param machine - The machine to track
+ * @param options - Configuration options
+ * @returns Machine with both history and snapshot tracking
+ *
+ * @example
+ * const tracker = withTimeTravel(counter, {
+ *   maxSize: 100,
+ *   serializer: {
+ *     serialize: (data) => JSON.stringify(data),
+ *     deserialize: (str) => JSON.parse(str)
+ *   }
+ * });
+ *
+ * tracker.increment();
+ * tracker.add(5);
+ *
+ * console.log(tracker.history); // All transitions
+ * console.log(tracker.snapshots); // All state changes
+ *
+ * // Replay from a specific snapshot
+ * const replayed = tracker.replayFrom(0);
+ *
+ * // Restore to specific snapshot
+ * const restored = tracker.restoreSnapshot(tracker.snapshots[0].before);
+ *
+ * // Clear all tracking data
+ * tracker.clearTimeTravel();
+ */
+export declare function withTimeTravel<M extends BaseMachine<any>>(machine: M, options?: {
+    /** Maximum size for both history and snapshots */
+    maxSize?: number;
+    /** Serializer for both args and context */
+    serializer?: Serializer<any>;
+    /** Callback for each recorded action */
+    onRecord?: (type: 'history' | 'snapshot', data: any) => void;
+}): WithTimeTravel<M, Context<M>>;
+/**
+ * Compose multiple middleware functions into a single middleware stack.
+ * Middleware is applied left-to-right (first middleware wraps outermost).
+ *
+ * @template M - The machine type
+ * @param machine - The base machine
+ * @param middlewares - Array of middleware functions
+ * @returns A new machine with all middleware applied
+ *
+ * @example
+ * const instrumented = compose(
+ *   counter,
+ *   withLogging,
+ *   withAnalytics(analytics.track),
+ *   withValidation(validator),
+ *   withErrorReporting(Sentry.captureException)
+ * );
+ */
+export declare function compose<M extends BaseMachine<any>>(machine: M, ...middlewares: Array<(m: M) => M>): M;
+/**
+ * Create a reusable middleware function from hooks.
+ * Useful for defining custom middleware that can be applied to multiple machines.
+ *
+ * @template M - The machine type
+ * @param hooks - Middleware hooks configuration
+ * @param options - Middleware options
+ * @returns A middleware function that can be applied to machines
+ *
+ * @example
+ * const myMiddleware = createCustomMiddleware({
+ *   before: ({ transitionName }) => console.log('Before:', transitionName),
+ *   after: ({ transitionName }) => console.log('After:', transitionName)
+ * });
+ *
+ * const machine1 = myMiddleware(counter1);
+ * const machine2 = myMiddleware(counter2);
+ */
+export declare function createCustomMiddleware<M extends BaseMachine<any>>(hooks: MiddlewareHooks<Context<M>>, options?: MiddlewareOptions): (machine: M) => M;
+/**
+ * A middleware function that transforms a machine.
+ * @template M - The input machine type
+ * @template R - The output machine type (usually extends M)
+ */
+/**
+ * A middleware function that transforms a machine.
+ * @template M - Input machine type
+ * @template R - Output machine type (defaults to same as input if no augmentation)
+ */
+export type MiddlewareFn<M extends BaseMachine<any>, R extends BaseMachine<any> = M> = (machine: M) => R;
+/**
+ * A conditional middleware that may or may not be applied based on a predicate.
+ * @template M - The machine type
+ */
+export type ConditionalMiddleware<M extends BaseMachine<any>> = {
+    /** The middleware function to apply */
+    middleware: MiddlewareFn<M>;
+    /** Predicate function that determines if the middleware should be applied */
+    when: (machine: M) => boolean;
+};
+/**
+ * A named middleware entry for registry-based composition.
+ * @template M - The machine type
+ */
+export type NamedMiddleware<M extends BaseMachine<any>> = {
+    /** Unique name for the middleware */
+    name: string;
+    /** The middleware function */
+    middleware: MiddlewareFn<M>;
+    /** Optional description */
+    description?: string;
+    /** Optional priority for ordering (higher numbers = applied later) */
+    priority?: number;
+};
+/**
+ * Configuration for middleware pipeline execution.
+ */
+export interface PipelineConfig {
+    /** Whether to continue executing remaining middlewares if one fails */
+    continueOnError?: boolean;
+    /** Whether to log errors to console */
+    logErrors?: boolean;
+    /** Custom error handler */
+    onError?: (error: Error, middlewareName?: string) => void;
+}
+/**
+ * Result of pipeline execution.
+ */
+export interface PipelineResult<M extends BaseMachine<any>> {
+    /** The final machine after all middlewares */
+    machine: M;
+    /** Any errors that occurred during execution */
+    errors: Array<{
+        error: Error;
+        middlewareIndex: number;
+        middlewareName?: string;
+    }>;
+    /** Whether the pipeline completed successfully */
+    success: boolean;
+}
+/**
+ * Compose multiple middlewares with improved type inference.
+ * This is a more typesafe version of the basic compose function.
+ *
+ * @template M - The initial machine type
+ * @template Ms - Array of middleware functions
+ * @param machine - The initial machine
+ * @param middlewares - Array of middleware functions to apply
+ * @returns The machine with all middlewares applied
+ *
+ * @example
+ * const enhanced = composeTyped(
+ *   counter,
+ *   withHistory(),
+ *   withSnapshot(),
+ *   withTimeTravel()
+ * );
+ */
+/**
+ * Recursively applies middlewares to infer the final machine type.
+ * Provides precise type inference for middleware composition chains.
+ */
+type ComposeResult<M extends BaseMachine<any>, Ms extends readonly MiddlewareFn<any, any>[]> = Ms extends readonly [] ? M : Ms extends readonly [infer First, ...infer Rest] ? First extends MiddlewareFn<any, infer Output> ? Rest extends readonly MiddlewareFn<any, any>[] ? ComposeResult<Output, Rest> : Output : M : M;
+/**
+ * Type-safe middleware composition with perfect inference.
+ * Composes multiple middlewares into a single transformation chain.
+ *
+ * @template M - The input machine type
+ * @template Ms - Array of middleware functions
+ * @param machine - The machine to enhance
+ * @param middlewares - Middleware functions to apply in order
+ * @returns The machine with all middlewares applied, with precise type inference
+ *
+ * @example
+ * ```typescript
+ * const enhanced = composeTyped(
+ *   counter,
+ *   withHistory(),
+ *   withSnapshot(),
+ *   withTimeTravel()
+ * );
+ * // enhanced: WithTimeTravel<WithSnapshot<WithHistory<Counter>>>
+ * // Perfect IntelliSense for all methods and properties
+ * ```
+ */
+export declare function composeTyped<M extends BaseMachine<any>, Ms extends readonly MiddlewareFn<any, any>[]>(machine: M, ...middlewares: Ms): ComposeResult<M, Ms>;
+/**
+ * Type-safe middleware composition with fluent API.
+ * Allows building middleware chains with method chaining.
+ *
+ * @example
+ * ```typescript
+ * const enhanced = chain(counter)
+ *   .with(withHistory())
+ *   .with(withSnapshot())
+ *   .with(withTimeTravel())
+ *   .build();
+ * ```
+ */
+export declare function chain<M extends BaseMachine<any>>(machine: M): MiddlewareChainBuilder<M>;
+/**
+ * Fluent middleware composer for building complex middleware chains.
+ * Provides excellent TypeScript inference and IntelliSense.
+ */
+declare class MiddlewareChainBuilder<M extends BaseMachine<any>> {
+    private machine;
+    constructor(machine: M);
+    /**
+     * Add a middleware to the composition chain.
+     * @param middleware - The middleware function to add
+     * @returns A new composer with the middleware applied
+     */
+    with<M2 extends MiddlewareFn<any, any>>(middleware: M2): MiddlewareChainBuilder<ReturnType<M2> extends BaseMachine<any> ? ReturnType<M2> : M>;
+    /**
+     * Build the final machine with all middlewares applied.
+     */
+    build(): M;
+}
+/**
+ * Common middleware combination types for better DX.
+ * These types help with inference when using popular middleware combinations.
+ */
+export type WithDebugging<M extends BaseMachine<any>> = WithTimeTravel<WithSnapshot<WithHistory<M>>>;
+/**
+ * Convenience function for the most common debugging middleware stack.
+ * Combines history, snapshots, and time travel for full debugging capabilities.
+ *
+ * @example
+ * ```typescript
+ * const debugMachine = withDebugging(counter);
+ * debugMachine.increment();
+ * debugMachine.history; // Full transition history
+ * debugMachine.snapshots; // Context snapshots
+ * debugMachine.replayFrom(0); // Time travel
+ * ```
+ */
+export declare function withDebugging<M extends BaseMachine<any>>(machine: M): WithDebugging<M>;
+/**
+ * Create a middleware pipeline with error handling and conditional execution.
+ *
+ * @template M - The machine type
+ * @param config - Pipeline configuration
+ * @returns A function that executes middlewares in a pipeline
+ *
+ * @example
+ * const pipeline = createPipeline({ continueOnError: true });
+ *
+ * const result = pipeline(
+ *   counter,
+ *   withHistory(),
+ *   withSnapshot(),
+ *   { middleware: withLogging(), when: (m) => m.context.debug }
+ * );
+ */
+export declare function createPipeline<M extends BaseMachine<any>>(config?: PipelineConfig): {
+    <Ms extends Array<MiddlewareFn<M> | ConditionalMiddleware<M>>>(machine: M, ...middlewares: Ms): PipelineResult<M>;
+};
+/**
+ * Create a middleware registry for named middleware composition.
+ * Useful for building complex middleware stacks from reusable components.
+ *
+ * @template M - The machine type
+ *
+ * @example
+ * const registry = createMiddlewareRegistry<CounterMachine>()
+ *   .register('history', withHistory(), 'Track state changes')
+ *   .register('snapshot', withSnapshot(), 'Take context snapshots', 10)
+ *   .register('timeTravel', withTimeTravel(), 'Enable time travel debugging', 20);
+ *
+ * const machine = registry.apply(counter, ['history', 'snapshot', 'timeTravel']);
+ */
+export declare function createMiddlewareRegistry<M extends BaseMachine<any>>(): {
+    /**
+     * Register a middleware with a name and optional metadata.
+     */
+    register(name: string, middleware: MiddlewareFn<M>, description?: string, priority?: number): {
+        register(name: string, middleware: MiddlewareFn<M>, description?: string, priority?: number): /*elided*/ any;
+        /**
+         * Unregister a middleware by name.
+         */
+        unregister(name: string): boolean;
+        /**
+         * Check if a middleware is registered.
+         */
+        has(name: string): boolean;
+        /**
+         * Get a registered middleware by name.
+         */
+        get(name: string): NamedMiddleware<M> | undefined;
+        /**
+         * List all registered middlewares.
+         */
+        list(): NamedMiddleware<M>[];
+        /**
+         * Apply a selection of registered middlewares to a machine.
+         * Middlewares are applied in priority order (lowest to highest).
+         */
+        apply(machine: M, middlewareNames: string[]): M;
+        /**
+         * Apply all registered middlewares to a machine in priority order.
+         */
+        applyAll(machine: M): M;
+    };
+    /**
+     * Unregister a middleware by name.
+     */
+    unregister(name: string): boolean;
+    /**
+     * Check if a middleware is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get a registered middleware by name.
+     */
+    get(name: string): NamedMiddleware<M> | undefined;
+    /**
+     * List all registered middlewares.
+     */
+    list(): NamedMiddleware<M>[];
+    /**
+     * Apply a selection of registered middlewares to a machine.
+     * Middlewares are applied in priority order (lowest to highest).
+     */
+    apply(machine: M, middlewareNames: string[]): M;
+    /**
+     * Apply all registered middlewares to a machine in priority order.
+     */
+    applyAll(machine: M): M;
+};
+/**
+ * Create a conditional middleware that only applies when a predicate is true.
+ *
+ * @template M - The machine type
+ * @param middleware - The middleware to conditionally apply
+ * @param predicate - Function that determines when to apply the middleware
+ * @returns A conditional middleware that can be called directly or used in pipelines
+ *
+ * @example
+ * const debugMiddleware = when(
+ *   withTimeTravel(),
+ *   (machine) => machine.context.debugMode
+ * );
+ *
+ * // Can be called directly
+ * const machine = debugMiddleware(baseMachine);
+ *
+ * // Can also be used in pipelines
+ * const pipeline = createPipeline();
+ * const result = pipeline(machine, debugMiddleware);
+ */
+export declare function when<M extends BaseMachine<any>>(middleware: MiddlewareFn<M>, predicate: (machine: M) => boolean): ConditionalMiddleware<M> & MiddlewareFn<M>;
+/**
+ * Create a middleware that only applies in development mode.
+ *
+ * @template M - The machine type
+ * @param middleware - The middleware to apply in development
+ * @returns A conditional middleware for development mode
+ *
+ * @example
+ * const devMachine = composeTyped(
+ *   counter,
+ *   inDevelopment(withTimeTravel())
+ * );
+ */
+export declare function inDevelopment<M extends BaseMachine<any>>(middleware: MiddlewareFn<M>): ConditionalMiddleware<M> & MiddlewareFn<M>;
+/**
+ * Create a middleware that only applies when a context property matches a value.
+ *
+ * @template M - The machine type
+ * @template K - The context key
+ * @param key - The context property key
+ * @param value - The value to match
+ * @param middleware - The middleware to apply when the condition matches
+ * @returns A conditional middleware
+ *
+ * @example
+ * const adminMachine = composeTyped(
+ *   userMachine,
+ *   whenContext('role', 'admin', withAdminFeatures())
+ * );
+ */
+export declare function whenContext<M extends BaseMachine<any>, K extends keyof Context<M>>(key: K, value: Context<M>[K], middleware: MiddlewareFn<M>): ConditionalMiddleware<M> & MiddlewareFn<M>;
+/**
+ * Combine multiple middlewares with short-circuiting.
+ * If any middleware returns a different type, the composition stops.
+ *
+ * @template M - The machine type
+ * @param middlewares - Array of middlewares to combine
+ * @returns A combined middleware function
+ *
+ * @example
+ * const combined = combine(
+ *   withHistory(),
+ *   withSnapshot(),
+ *   withValidation()
+ * );
+ */
+export declare function combine<M extends BaseMachine<any>>(...middlewares: Array<MiddlewareFn<M>>): MiddlewareFn<M>;
+/**
+ * Create a middleware that applies different middlewares based on context.
+ *
+ * @template M - The machine type
+ * @param branches - Array of [predicate, middleware] pairs
+ * @param fallback - Optional fallback middleware if no predicates match
+ * @returns A branching middleware
+ *
+ * @example
+ * const smartMiddleware = branch(
+ *   [(m) => m.context.userType === 'admin', withAdminFeatures()],
+ *   [(m) => m.context.debug, withTimeTravel()],
+ *   withBasicLogging() // fallback
+ * );
+ */
+export declare function branch<M extends BaseMachine<any>>(branches: Array<[predicate: (machine: M) => boolean, middleware: MiddlewareFn<M>]>, fallback?: MiddlewareFn<M>): MiddlewareFn<M>;
+/**
+ * Type guard to check if a value is a middleware function.
+ */
+export declare function isMiddlewareFn<M extends BaseMachine<any>>(value: any): value is MiddlewareFn<M>;
+/**
+ * Type guard to check if a value is a conditional middleware.
+ */
+export declare function isConditionalMiddleware<M extends BaseMachine<any>>(value: any): value is ConditionalMiddleware<M>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map