controlled-machine 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -1,118 +1,291 @@
 /**
  * Controlled Machine
  *
- * A controlled state machine where state lives outside the machine.
+ * A controlled state machine library where external state (input) is passed in
+ * and internal state is managed by the machine itself.
  *
- * - input: External data passed in
- * - computed: Derived values from input
- * - context: input + computed (full context available in handlers)
- * - on: Event → conditional actions
- * - effects: Watch-based side effects
- * - always: Auto-evaluated rules on context change
- */
-export type Rule<TContext, TPayload = undefined, TActions extends string = string, TGuards extends string = string> = {
-    when?: ((context: TContext, payload: TPayload) => boolean) | TGuards;
-    do: TActions | TActions[];
+ * Key Concepts:
+ * - input: External data passed in from outside (e.g., React state, props)
+ * - internal: Machine-managed state that persists across events
+ * - computed: Derived values calculated from input + internal
+ * - context: Flattened input + internal + computed (available in all handlers)
+ * - on: Event handlers with conditional rules and actions
+ * - states: FSM-style state-based event handlers
+ * - effects: Watch-based side effects with enter/exit/change callbacks
+ * - always: Auto-evaluated rules that run on every context change
+ * - actions: Named action functions (can be overridden in useMachine)
+ * - guards: Named guard functions for conditional logic
+ */
+/**
+ * Assign function type - updates internal state with partial updates
+ * Only allows modifying keys defined in Internal type
+ */
+export type AssignFn<TInternal> = (updates: Partial<TInternal>) => void;
+/**
+ * ActionItem - can be a named action string or inline function
+ * Inline functions receive (context, payload, assign)
+ */
+export type ActionItem<TContext, TPayload = undefined, TActions extends string = string, TInternal = unknown> = TActions | ((context: TContext, payload: TPayload, assign: AssignFn<TInternal>) => void);
+/**
+ * GuardItem - can be a named guard string or inline predicate function
+ */
+export type GuardItem<TContext, TPayload = undefined, TGuards extends string = string> = TGuards | ((context: TContext, payload: TPayload) => boolean);
+/**
+ * Rule - conditional action with optional guard(s)
+ * @property when - Guard(s) that must pass (AND logic for arrays)
+ * @property do - Action(s) to execute if guards pass
+ */
+export type Rule<TContext, TPayload = undefined, TActions extends string = string, TGuards extends string = string, TInternal = unknown> = {
+    when?: GuardItem<TContext, TPayload, TGuards> | GuardItem<TContext, TPayload, TGuards>[];
+    do: ActionItem<TContext, TPayload, TActions, TInternal> | ActionItem<TContext, TPayload, TActions, TInternal>[];
 };
-export type Handler<TContext, TPayload = undefined, TActions extends string = string, TGuards extends string = string> = TActions | TActions[] | Rule<TContext, TPayload, TActions, TGuards>[] | ((context: TContext, payload: TPayload) => void);
+/**
+ * Handler - event handler definition
+ * Can be: single action, action array, rule array, inline function, or function array
+ *
+ * @example
+ * on: { CLICK: 'handleClick' }                    // single action
+ * on: { SUBMIT: ['validate', 'save'] }           // action array
+ * on: { TOGGLE: [{ when: ctx => ctx.isOpen, do: 'close' }, { do: 'open' }] }  // rule array
+ * on: { INCREMENT: (ctx, _, assign) => assign({ count: ctx.count + 1 }) }     // inline function
+ * on: { SELECT: [(ctx, p) => ctx.onSelect(p), (_, __, a) => a({ isOpen: false })] }  // function array
+ */
+export type Handler<TContext, TPayload = undefined, TActions extends string = string, TGuards extends string = string, TInternal = unknown> = TActions | TActions[] | Rule<TContext, TPayload, TActions, TGuards, TInternal>[] | ((context: TContext, payload: TPayload, assign: AssignFn<TInternal>) => void) | ((context: TContext, payload: TPayload, assign: AssignFn<TInternal>) => void)[];
+/**
+ * EffectHelpers - utilities available in effect callbacks
+ */
 export type EffectHelpers<TEvents extends EventsConfig> = {
     send: Send<TEvents>;
 };
+/** Cleanup function returned from effect callbacks */
 export type Cleanup = () => void;
+/**
+ * Effect - watch-based side effect with lifecycle callbacks
+ * @property watch - Function that returns the value to watch (uses shallow comparison)
+ * @property enter - Called when watch value becomes truthy (can return cleanup)
+ * @property exit - Called when watch value becomes falsy (can return cleanup)
+ * @property change - Called on any value change with (prev, curr) (can return cleanup)
+ */
 export type Effect<TContext, TEvents extends EventsConfig, TWatched = unknown> = {
     watch: (context: TContext) => TWatched;
     enter?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup | Promise<void>;
     exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup;
     change?: (context: TContext, prev: TWatched | undefined, curr: TWatched, helpers: EffectHelpers<TEvents>) => void | Cleanup;
 };
-/** Helper for inferring prev/curr types from watch return type */
+/**
+ * Helper function for creating effects with proper type inference
+ * @example
+ * effects: [
+ *   effect({ watch: ctx => ctx.isOpen, enter: () => console.log('opened') })
+ * ]
+ */
 export declare function effect<TContext, TEvents extends EventsConfig, TWatched>(config: Effect<TContext, TEvents, TWatched>): Effect<TContext, TEvents, TWatched>;
+/** Event configuration - event name to payload type mapping */
 export type EventsConfig = Record<string, unknown>;
+/** Computed configuration - computed key to value type mapping */
 export type ComputedConfig = Record<string, unknown>;
 /**
- * Object-based generic types - specify only needed types in any order
+ * MachineTypes - object-based generic type parameter
+ * Specify only the types you need, in any order
  *
  * @example
  * createMachine<{
- *   input: MyInput
- *   events: MyEvents
- *   actions: 'foo' | 'bar'
+ *   input: { count: number; setCount: (c: number) => void }
+ *   internal: { isOpen: boolean }
+ *   events: { INCREMENT: undefined; SET: { value: number } }
+ *   computed: { doubled: number }
+ *   actions: 'increment' | 'set'
+ *   guards: 'isPositive'
+ *   state: 'idle' | 'loading'
  * }>({...})
  */
 export type MachineTypes = {
     input?: unknown;
+    internal?: unknown;
     events?: EventsConfig;
     computed?: ComputedConfig;
     actions?: string;
     guards?: string;
     state?: string;
 };
-export type Input<T extends MachineTypes> = T['input'];
+export type Input<T extends MachineTypes> = T['input'] extends object ? T['input'] : {};
+export type Internal<T extends MachineTypes> = T['internal'] extends object ? T['internal'] : {};
 export type Events<T extends MachineTypes> = T['events'] extends EventsConfig ? T['events'] : Record<string, undefined>;
-export type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig ? T['computed'] : Record<string, never>;
+export type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig ? T['computed'] : {};
 export type Actions<T extends MachineTypes> = T['actions'] extends string ? T['actions'] : string;
 export type Guards<T extends MachineTypes> = T['guards'] extends string ? T['guards'] : string;
 export type State<T extends MachineTypes> = T['state'] extends string ? T['state'] : string;
-export type Context<T extends MachineTypes> = Input<T> & Computed<T>;
-export type StateConfig<TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+/**
+ * Detects if two types have overlapping keys
+ * Returns true if any key exists in both A and B
+ */
+type HasOverlappingKeys<A, B> = keyof A & keyof B extends never ? false : true;
+/**
+ * Check all combinations of key overlaps between Input, Internal, Computed
+ * Uses conditional chain (not union) to ensure proper boolean result
+ */
+type HasAnyKeyOverlap<T extends MachineTypes> = HasOverlappingKeys<Input<T>, Internal<T>> extends true ? true : HasOverlappingKeys<Input<T>, Computed<T>> extends true ? true : HasOverlappingKeys<Internal<T>, Computed<T>> extends true ? true : false;
+/**
+ * Context = Input + Internal + Computed (flat structure)
+ * All properties are accessible at the same level in handlers
+ *
+ * If any pair has overlapping keys, Context becomes `never` (compile-time error)
+ */
+export type Context<T extends MachineTypes> = HasAnyKeyOverlap<T> extends true ? never : Input<T> & Internal<T> & Computed<T>;
+/** Configuration for handlers within a specific state */
+export type StateConfig<TContext, TEvents extends EventsConfig, TActions extends string = string, TGuards extends string = string, TInternal = unknown> = {
     on?: {
-        [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions>;
+        [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions, TGuards, TInternal>;
     };
 };
-export type StatesConfig<TState extends string, TContext, TEvents extends EventsConfig, TActions extends string = string> = {
-    [K in TState]?: StateConfig<TContext, TEvents, TActions>;
+/** Map of state names to their configurations */
+export type StatesConfig<TState extends string, TContext, TEvents extends EventsConfig, TActions extends string = string, TGuards extends string = string, TInternal = unknown> = {
+    [K in TState]?: StateConfig<TContext, TEvents, TActions, TGuards, TInternal>;
 };
+/** Base context (input + internal) before computed values are added */
+export type BaseContext<T extends MachineTypes> = Input<T> & Internal<T>;
+/**
+ * Machine - the configuration object for createMachine
+ */
 export type Machine<T extends MachineTypes> = {
+    internal?: Internal<T>;
     computed?: {
-        [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K];
+        [K in keyof Computed<T>]: (ctx: BaseContext<T>) => Computed<T>[K];
     };
     on?: {
-        [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>, Guards<T>>;
+        [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>, Guards<T>, Internal<T>>;
     };
-    states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>;
-    always?: Rule<Context<T>, undefined, Actions<T>, Guards<T>>[];
+    states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>, Guards<T>, Internal<T>>;
+    always?: Rule<Context<T>, undefined, Actions<T>, Guards<T>, Internal<T>>[];
     effects?: Effect<Context<T>, Events<T>, any>[];
     actions?: {
-        [K in Actions<T>]: (context: Context<T>, payload?: any) => void;
+        [K in Actions<T>]: (ctx: Context<T>, payload: any, assign: AssignFn<Internal<T>>) => void;
     };
     guards?: {
-        [K in Guards<T>]: (context: Context<T>, payload?: any) => boolean;
+        [K in Guards<T>]: (ctx: Context<T>, payload?: any) => boolean;
     };
 };
+/**
+ * Send - function type for dispatching events
+ * Events with undefined payload can be called without arguments
+ */
 export type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(event: K, ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]) => void;
+/**
+ * Snapshot = Internal + Computed + { state } (without Input)
+ * This is the value returned from getSnapshot() and useMachine()
+ *
+ * If Internal/Computed have overlapping keys, Snapshot becomes `never`
+ * If 'state' type param is defined and Internal/Computed already has 'state' key,
+ * we don't add { state } again (existing state is already included)
+ */
+export type Snapshot<T extends MachineTypes> = HasOverlappingKeys<Internal<T>, Computed<T>> extends true ? never : Internal<T> & Computed<T> & (T['state'] extends string ? 'state' extends keyof Internal<T> | keyof Computed<T> ? object : {
+    state: State<T>;
+} : object);
+/**
+ * MachineInstance - the return type of createMachine
+ * Includes all configuration plus runtime methods
+ */
 export type MachineInstance<T extends MachineTypes> = Machine<T> & {
+    /** Dispatch an event with input and optional payload */
     send: <K extends keyof Events<T>>(event: K, input: Input<T>, ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]) => void;
+    /** Evaluate always rules and effects (called automatically in React) */
     evaluate: (input: Input<T>) => void;
-    getComputed: (input: Input<T>) => Computed<T>;
+    /** Get current snapshot (internal + computed + state) */
+    getSnapshot: (input: Input<T>) => Snapshot<T>;
+    /** Get current internal state */
+    getInternal: () => Internal<T>;
+    /** Set internal state directly */
+    setInternal: (internal: Internal<T>) => void;
+    /** Get initial internal state (for reset) */
+    getInitialInternal: () => Internal<T>;
+    /** Clean up all effect callbacks */
     cleanup: () => void;
 };
-export declare function executeActions<TContext, TPayload>(actionNames: string | string[], actions: Record<string, (context: TContext, payload?: TPayload) => void>, context: TContext, payload: TPayload): void;
+/**
+ * Execute action items (named actions or inline functions)
+ * Handles both single actions and arrays of actions
+ * Each action receives fresh context (rebuilt after previous assigns)
+ */
+export declare function executeRuleActions<TContext, TPayload, TInternal>(actionItems: ActionItem<TContext, TPayload, string, TInternal> | ActionItem<TContext, TPayload, string, TInternal>[], actions: Record<string, (context: TContext, payload: TPayload, assign: AssignFn<TInternal>) => void>, getContext: () => TContext, payload: TPayload, assign: AssignFn<TInternal>): void;
+/**
+ * Evaluate guard items (named guards or inline predicates)
+ * Uses AND logic - all guards must pass for result to be true
+ */
+export declare function evaluateGuards<TContext, TPayload>(guardItems: GuardItem<TContext, TPayload> | GuardItem<TContext, TPayload>[] | undefined, guards: Record<string, (context: TContext, payload?: TPayload) => boolean>, context: TContext, payload: TPayload): boolean;
+/** Type guard to check if handler is a Rule array (has 'do' property) */
 export declare function isRuleArray<TContext, TPayload, TActions extends string>(handler: Handler<TContext, TPayload, TActions>): handler is Rule<TContext, TPayload, TActions>[];
-export declare function executeHandler<TContext, TPayload>(handler: Handler<TContext, TPayload>, actions: Record<string, (context: TContext, payload?: TPayload) => void>, guards: Record<string, (context: TContext, payload?: TPayload) => boolean>, context: TContext, payload: TPayload): void;
-export declare function computeValues<TContext, TComputed extends ComputedConfig>(context: TContext, computed?: {
-    [K in keyof TComputed]: (context: TContext) => TComputed[K];
-}): TContext & TComputed;
 /**
- * Shallow comparison function - for composite watch support
- *
- * Arrays: length + === comparison for each element
- * Others: === comparison
+ * Execute a handler (action string, action array, rule array, inline function, or function array)
+ * For rule arrays, only the first matching rule executes (short-circuit)
+ * Each action/function receives fresh context (rebuilt after previous assigns)
+ */
+export declare function executeHandler<TContext, TPayload, TInternal>(handler: Handler<TContext, TPayload, string, string, TInternal>, actions: Record<string, (context: TContext, payload: TPayload, assign: AssignFn<TInternal>) => void>, guards: Record<string, (context: TContext, payload?: TPayload) => boolean>, getContext: () => TContext, payload: TPayload, assign: AssignFn<TInternal>): void;
+/**
+ * Compute derived values from base context
+ * Each computed function receives the base context (input + internal)
+ */
+export declare function computeValues<TBase, TComputed extends ComputedConfig>(base: TBase, computed?: {
+    [K in keyof TComputed]: (ctx: TBase) => TComputed[K];
+}): TBase & TComputed;
+/**
+ * Build flat context from input + internal
+ * Input takes priority if keys overlap (runtime)
+ */
+export declare function buildContext<TInput, TInternal>(input: TInput, internal: TInternal): TInput & TInternal;
+/**
+ * Create assign function for updating internal state
+ */
+export declare function createAssign<TInternal>(getInternal: () => TInternal, setInternal: (internal: TInternal) => void): AssignFn<TInternal>;
+/**
+ * Build snapshot from internal state, context, and computed definitions
+ * Snapshot = Internal + Computed + state (without Input)
+ */
+export declare function buildSnapshot<T extends MachineTypes>(internal: Internal<T>, context: Context<T>, computedDef: Machine<T>['computed']): Snapshot<T>;
+/**
+ * Shallow comparison for effect watch values
+ * Arrays: compares length and each element with ===
+ * Others: strict equality (===)
  */
 export declare function shallowEqual(a: unknown, b: unknown): boolean;
+/**
+ * EffectStore - tracks watched values and cleanup functions for effects
+ * Used by both vanilla and React implementations
+ */
 export type EffectStore = {
     watchedValues: Map<number, unknown>;
     enterCleanups: Map<number, () => void>;
     changeCleanups: Map<number, () => void>;
     exitCleanups: Map<number, () => void>;
 };
+/** Create a new effect store */
 export declare function createEffectStore(): EffectStore;
 /**
- * Common effects processing logic
+ * Process all effects - detect watch value changes and call appropriate callbacks
+ * Called on every context change in both vanilla (evaluate) and React (useEffect)
  */
 export declare function processEffects<TContext, TEvents extends EventsConfig>(effects: Effect<TContext, TEvents, any>[] | undefined, context: TContext, effectHelpers: EffectHelpers<TEvents>, store: EffectStore): void;
+/** Clear all effect cleanups (called on unmount or cleanup) */
+export declare function clearEffectStore(store: EffectStore): void;
 /**
- * Clear effect store
+ * Create a controlled state machine instance
+ *
+ * The machine manages internal state and provides methods for:
+ * - send: Dispatch events with input and payload
+ * - evaluate: Run always rules and effects
+ * - getSnapshot: Get current state (internal + computed + state)
+ *
+ * @example
+ * const machine = createMachine<{
+ *   input: { count: number }
+ *   internal: { isOpen: boolean }
+ *   events: { TOGGLE: undefined }
+ *   computed: { doubled: number }
+ * }>({
+ *   internal: { isOpen: false },
+ *   computed: { doubled: ctx => ctx.count * 2 },
+ *   on: { TOGGLE: (ctx, _, assign) => assign({ isOpen: !ctx.isOpen }) }
+ * })
  */
-export declare function clearEffectStore(store: EffectStore): void;
 export declare function createMachine<T extends MachineTypes>(config: Machine<T>): MachineInstance<T>;
+export {};
 //# sourceMappingURL=index.d.ts.map