@quazardous/quarkernel 1.0.12 → 2.2.3

package/dist/create-machine-CYsscHPX.d.ts

@@ -0,0 +1,275 @@
+/**
+ * FSM Types for QuarKernel
+ *
+ * Flexible state machine layer built on quarkernel events.
+ * Prefixed events allow loose coupling and multi-machine orchestration.
+ */
+/**
+ * State name type
+ */
+type StateName = string;
+/**
+ * Transition event name type
+ */
+type TransitionEvent = string;
+/**
+ * Guard function - returns true to allow transition
+ */
+type GuardFunction<TContext = any> = (context: TContext, event: TransitionEvent, payload?: any) => boolean;
+/**
+ * Action function - side effect on transition
+ */
+type ActionFunction<TContext = any> = (context: TContext, event: TransitionEvent, payload?: any) => void | Promise<void>;
+/**
+ * Transition definition
+ */
+interface TransitionDef<TContext = any> {
+    /** Target state */
+    target: StateName;
+    /** Guard condition (optional) */
+    guard?: GuardFunction<TContext>;
+    /** Actions to run on transition (optional) */
+    actions?: ActionFunction<TContext> | ActionFunction<TContext>[];
+}
+/**
+ * Timer/after definition for auto-transitions
+ */
+interface AfterDef$1 {
+    /** Delay in milliseconds */
+    delay: number;
+    /** Event to send after delay */
+    send: string;
+}
+/**
+ * State node definition (state-centric format)
+ */
+interface StateNode<TContext = any> {
+    /** Transitions from this state: event -> target or TransitionDef */
+    on?: Record<TransitionEvent, StateName | TransitionDef<TContext>>;
+    /** Action on entering this state */
+    entry?: ActionFunction<TContext>;
+    /** Action on exiting this state */
+    exit?: ActionFunction<TContext>;
+    /** Auto-transition after delay: { delay: 3000, send: 'TIMER' } */
+    after?: AfterDef$1;
+}
+/**
+ * Machine configuration
+ */
+interface MachineConfig<TContext = any> {
+    /** Event prefix for this machine (e.g., 'order', 'player') */
+    prefix: string;
+    /** Initial state */
+    initial: StateName;
+    /** State definitions */
+    states: Record<StateName, StateNode<TContext>>;
+    /** Initial context (optional) */
+    context?: TContext;
+    /** Allow force transitions that bypass guards */
+    allowForce?: boolean;
+    /** Restore from snapshot (overrides initial/context) */
+    snapshot?: MachineSnapshot<TContext>;
+    /** Track transition history */
+    trackHistory?: boolean;
+    /** Max history entries (default: 100) */
+    maxHistory?: number;
+}
+/**
+ * Send options
+ */
+interface SendOptions<TContext = any> {
+    /** Force transition (bypass guards and undefined transitions) */
+    force?: boolean;
+    /** Target state for force transitions */
+    target?: StateName;
+    /** Inline guard (overrides state guard) */
+    guard?: GuardFunction<TContext>;
+    /** Fallback state if guard fails */
+    fallback?: StateName;
+}
+/**
+ * Serialized machine state (for persistence)
+ */
+interface MachineSnapshot<TContext = any> {
+    /** Current state */
+    state: StateName;
+    /** Machine context */
+    context: TContext;
+    /** Transition history (optional) */
+    history?: Array<{
+        from: StateName;
+        to: StateName;
+        event: TransitionEvent;
+        timestamp: number;
+    }>;
+}
+/**
+ * Machine instance returned by useMachine()
+ */
+interface Machine<TContext = any> {
+    /** Current state */
+    getState(): StateName;
+    /** Machine context */
+    getContext(): TContext;
+    /** Update context */
+    setContext(updater: Partial<TContext> | ((ctx: TContext) => TContext)): void;
+    /** Send transition event */
+    send(event: TransitionEvent, payload?: any, options?: SendOptions<TContext>): Promise<boolean>;
+    /** Check if transition is valid from current state */
+    can(event: TransitionEvent): boolean;
+    /** Get available transitions from current state */
+    transitions(): TransitionEvent[];
+    /** Machine prefix */
+    readonly prefix: string;
+    /** Serialize machine state to JSON */
+    toJSON(): MachineSnapshot<TContext>;
+    /** Restore machine state from snapshot */
+    restore(snapshot: MachineSnapshot<TContext>): void;
+    /** Cleanup listeners */
+    destroy(): void;
+}
+/**
+ * FSM event data emitted on kernel
+ */
+interface FSMEventData {
+    /** Machine prefix */
+    machine: string;
+    /** Current/new state */
+    state: StateName;
+    /** Previous state (for transition events) */
+    from?: StateName;
+    /** Target state (for transition events) */
+    to?: StateName;
+    /** Transition event name */
+    event?: TransitionEvent;
+    /** Event payload */
+    payload?: any;
+    /** Whether this was a forced transition */
+    forced?: boolean;
+}
+
+/**
+ * createMachine - High-level FSM factory
+ *
+ * Standalone state machine with declarative behaviors.
+ * Can work independently or connect to a kernel.
+ */
+
+/**
+ * Built-in helpers (always available)
+ */
+interface BuiltInHelpers<TContext = Record<string, unknown>> {
+    /** Merge into context */
+    set: (partial: Partial<TContext>) => void;
+    /** Trigger transition */
+    send: (event: string, payload?: unknown) => void;
+    /** Log message (default: console.log) */
+    log: (message: string) => void;
+}
+/**
+ * Behavior helpers passed to callbacks (built-ins + custom)
+ */
+type BehaviorHelpers<TContext = Record<string, unknown>, TCustom = Record<string, unknown>> = BuiltInHelpers<TContext> & TCustom;
+/**
+ * Behavior callback
+ */
+type BehaviorFn<TContext = Record<string, unknown>> = (ctx: TContext, helpers: BehaviorHelpers<TContext>) => void | Promise<void>;
+/**
+ * Timer/after definition
+ */
+interface AfterDef {
+    /** Event to send */
+    send: string;
+    /** Delay in ms */
+    delay: number;
+}
+/**
+ * State-centric state definition
+ */
+interface StateConfig<TContext = Record<string, unknown>> {
+    /** Transitions: { EVENT: 'target' } or { EVENT: { target: 'x', cond: 'guard' } } */
+    on?: Record<string, string | {
+        target: string;
+        cond?: string;
+    }>;
+    /** Action on entering this state */
+    entry?: BehaviorFn<TContext>;
+    /** Action on exiting this state */
+    exit?: BehaviorFn<TContext>;
+    /** Auto-transition after delay: { delay: 3000, send: 'TIMER' } */
+    after?: AfterDef;
+}
+/**
+ * High-level machine config (state-centric)
+ */
+interface CreateMachineConfig<TContext = Record<string, unknown>, THelpers = Record<string, unknown>> {
+    /** Machine identifier */
+    id: string;
+    /** Initial state */
+    initial: string;
+    /** Initial context */
+    context?: TContext;
+    /** State definitions with entry/exit/after inline */
+    states: Record<string, StateConfig<TContext>>;
+    /** Global event handlers: { EVENT_NAME: (ctx, helpers) => ... } */
+    on?: Record<string, BehaviorFn<TContext>>;
+    /** Custom helpers merged with built-ins (set, send) */
+    helpers?: THelpers;
+}
+/**
+ * Extended machine interface with behaviors
+ */
+interface BehaviorMachine<TContext = Record<string, unknown>> extends Machine<TContext> {
+    /** Machine ID */
+    readonly id: string;
+    /** Current state (getter) */
+    readonly state: string;
+    /** Current context (getter) */
+    readonly context: TContext;
+}
+/**
+ * Create a standalone state machine with behaviors (state-centric)
+ *
+ * @example
+ * ```ts
+ * const order = createMachine({
+ *   id: 'order',
+ *   initial: 'draft',
+ *   context: { items: 0, total: 0 },
+ *
+ *   states: {
+ *     draft: {
+ *       on: { ADD_ITEM: 'draft', SUBMIT: 'pending' }
+ *     },
+ *     pending: {
+ *       entry: (ctx, { log }) => log('Order pending...'),
+ *       on: { APPROVE: 'confirmed', REJECT: 'draft' }
+ *     },
+ *     confirmed: {
+ *       entry: (ctx, { log }) => log(`Order confirmed: ${ctx.items} items`),
+ *       on: { SHIP: 'shipped' }
+ *     },
+ *     processing: {
+ *       after: { delay: 2000, send: 'COMPLETE' },
+ *       on: { COMPLETE: 'done' }
+ *     },
+ *     shipped: {},
+ *   },
+ *
+ *   // Global event handlers (optional)
+ *   on: {
+ *     ADD_ITEM: (ctx, { set }) => {
+ *       set({ items: ctx.items + 1, total: ctx.total + 29.99 });
+ *     },
+ *   },
+ * });
+ *
+ * order.send('ADD_ITEM');
+ * order.send('SUBMIT');
+ * console.log(order.state);   // 'pending'
+ * console.log(order.context); // { items: 1, total: 29.99 }
+ * ```
+ */
+declare function createMachine<TContext = Record<string, unknown>>(config: CreateMachineConfig<TContext>): BehaviorMachine<TContext>;
+
+export { type ActionFunction as A, type BehaviorMachine as B, type CreateMachineConfig as C, type FSMEventData as F, type GuardFunction as G, type MachineConfig as M, type StateNode as S, type TransitionDef as T, type Machine as a, type MachineSnapshot as b, createMachine as c, type SendOptions as d, type StateName as e, type TransitionEvent as f, type StateConfig as g, type BehaviorFn as h, type BehaviorHelpers as i, type BuiltInHelpers as j, type AfterDef as k, type AfterDef$1 as l };