slapflow 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+type Input = Record<string, unknown>;
+type Props = Record<string, unknown>;
+type Config = {
+    version?: 1;
+    strategies: Record<string, Strategy>;
+    entrypoints?: Record<string, string>;
+};
+type Strategy = {
+    fn: string;
+    props?: Props;
+    when?: ConditionExpression;
+    then?: Next[];
+    catch?: Next[];
+    mode?: Mode;
+    terminal?: boolean;
+    tags?: string[];
+    description?: string;
+};
+type Mode = 'sequence' | 'selector' | 'parallel';
+type Next = string | {
+    id?: string;
+    strategy: string;
+    props?: Props;
+    when?: ConditionExpression;
+};
+type ConditionExpression = boolean | [operator: string, ...args: unknown[]];
+type Action<TContext, TPatch = unknown> = (args: ActionArgs<TContext>) => ActionResult<TContext, TPatch> | Promise<ActionResult<TContext, TPatch>>;
+type ActionArgs<TContext> = {
+    context: TContext;
+    props: Props;
+    input: Input;
+    signal: AbortSignal;
+    runtime: Runtime;
+};
+type ActionResult<TContext, TPatch = unknown> = void | false | ActionSuccess<TContext, TPatch> | ActionSkip | ActionStop<TPatch> | ActionFail;
+type ActionSuccess<TContext, TPatch> = {
+    type?: 'success';
+    context?: TContext;
+    data?: Record<string, unknown>;
+    patch?: TPatch | TPatch[];
+    events?: SlapEvent[];
+    continue?: boolean;
+};
+type RuntimeBranchResult = {
+    status: 'success';
+} | {
+    status: 'skipped';
+    reason?: string;
+} | {
+    status: 'stopped';
+    reason?: string;
+} | {
+    status: 'failed';
+    error: SlapError;
+};
+type ActionSkip = {
+    type: 'skip';
+    reason?: string;
+    data?: Record<string, unknown>;
+};
+type ActionStop<TPatch> = {
+    type: 'stop';
+    reason?: string;
+    patch?: TPatch | TPatch[];
+    events?: SlapEvent[];
+};
+type ActionFail = {
+    type: 'fail';
+    reason?: string;
+    error?: unknown;
+    data?: Record<string, unknown>;
+    handled?: boolean;
+};
+type SlapEvent = {
+    type: string;
+    payload?: unknown;
+};
+type EventMap = Record<string, unknown>;
+type EventName<TEvents extends object> = Extract<keyof TEvents, string>;
+type BusEvent<TPayload = unknown> = {
+    id: string;
+    topic: string;
+    occurredAt: number;
+    origin?: string;
+    parsed: TPayload;
+    serialized: string;
+};
+type EventHandler<TEvents extends object, TEvent extends EventName<TEvents>> = (event: BusEvent<TEvents[TEvent]>) => void;
+type BusErrorEvent<TEvents extends object> = {
+    type: 'serialization';
+    topic: EventName<TEvents>;
+    payload: TEvents[EventName<TEvents>];
+    origin?: string;
+    error: unknown;
+} | {
+    type: 'subscriber';
+    event: BusEvent<TEvents[EventName<TEvents>]>;
+    error: unknown;
+};
+type BusEmitOptions = {
+    origin?: string;
+};
+type BusOptions<TEvents extends object> = {
+    onError?: (event: BusErrorEvent<TEvents>) => void;
+};
+type Bus<TEvents extends object = EventMap> = {
+    on<TEvent extends EventName<TEvents>>(event: TEvent, handler: EventHandler<TEvents, TEvent>): () => void;
+    off<TEvent extends EventName<TEvents>>(event: TEvent, handler?: EventHandler<TEvents, TEvent>): void;
+    emit<TEvent extends EventName<TEvents>>(topic: TEvent, payload: TEvents[TEvent], options?: BusEmitOptions): BusEvent<TEvents[TEvent]>;
+    dispatch(event: unknown): BusEvent | undefined;
+};
+type WSSocket = {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: 'open' | 'close' | 'error' | 'message', listener: EventListener): void;
+    removeEventListener(type: 'open' | 'close' | 'error' | 'message', listener: EventListener): void;
+};
+type RetryOptions = {
+    initialDelay?: number;
+    maxDelay?: number;
+    multiplier?: number;
+    jitter?: boolean;
+    maxAttempts?: number;
+};
+type WSRetryOptions = RetryOptions;
+type WSOptions<TEvents extends object = EventMap> = {
+    bus: Bus<TEvents>;
+    createSocket: () => WSSocket;
+    inboundTopics?: EventName<TEvents>[];
+    outboundTopics?: EventName<TEvents>[];
+    origin?: string;
+    retry?: WSRetryOptions;
+};
+type WSStatus = 'idle' | 'connecting' | 'connected' | 'retrying' | 'stopped';
+type FetchResponseType = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'none';
+type WS = {
+    start(): void;
+    stop(): void;
+    reconnect(): void;
+    status(): WSStatus;
+};
+type BindingEventMap = Record<string, Input>;
+type BusBindingKey<TEvents extends object> = {
+    [TEvent in EventName<TEvents>]: TEvents[TEvent] extends Input ? `[bus] ${TEvent}` : never;
+}[EventName<TEvents>];
+type ConcurrencyMode = 'parallel' | 'latest' | 'queue' | 'drop';
+type QueueOverflow = 'drop-oldest' | 'drop-newest';
+type ConcurrencyOptions<TPayload = Input> = {
+    mode?: ConcurrencyMode;
+    key?: (payload: TPayload) => string;
+    maxQueueSize?: number;
+    overflow?: QueueOverflow;
+};
+type BusBinding<TPayload = Input> = {
+    entrypoint: string;
+    options?: {
+        concurrency?: ConcurrencyOptions<TPayload>;
+    };
+};
+type BusBindings<TEvents extends object> = {
+    [TBinding in BusBindingKey<TEvents>]?: BusBinding<TEvents[Extract<TBinding extends `[bus] ${infer TEvent}` ? TEvent : never, EventName<TEvents>>]>;
+};
+type DomBindingKey = `[dom] ${string}:${string}`;
+type DomForm = Record<string, FormDataEntryValue | FormDataEntryValue[]>;
+type DomInput = Input & {
+    type: string;
+    value?: string;
+    dataset: Record<string, string>;
+    form?: DomForm;
+};
+type DomBinding = {
+    entrypoint: string;
+    options?: {
+        preventDefault?: boolean;
+        stopPropagation?: boolean;
+        capture?: boolean;
+        once?: boolean;
+        input?: (scope: {
+            event: Event;
+            element: Element;
+            defaultInput: DomInput;
+        }) => Input;
+        concurrency?: ConcurrencyOptions<DomInput>;
+    };
+};
+type DomBindings = Partial<Record<DomBindingKey, DomBinding>>;
+type FlowDefinition<TContext, TPatch = unknown, TEvents extends object = BindingEventMap> = {
+    config: Config;
+    actions?: Record<string, Action<TContext, TPatch>>;
+    conditions?: Record<string, ConditionFn<TContext>>;
+    events?: BusBindings<TEvents> & DomBindings;
+};
+type FlowOptions<TContext, TPatch = unknown, TEvents extends object = BindingEventMap> = RunnerOptions<TContext, TPatch> & {
+    context: TContext | (() => TContext);
+    bus?: Bus<TEvents>;
+    root?: Document | Element;
+    concurrency?: ConcurrencyOptions;
+    onRunnerError?: (event: RunnerErrorEvent<TContext, TPatch>) => void;
+};
+type RunnerErrorEvent<TContext, TPatch = unknown> = {
+    error: SlapError;
+    result: RunResult<TContext, TPatch>;
+    binding: string;
+    entrypoint: string;
+    runId: string;
+    key?: string;
+};
+type InactiveBinding = {
+    binding: string;
+    reason: 'unsupported-source' | 'dom-unavailable';
+};
+type StartResult = {
+    active: string[];
+    inactive: InactiveBinding[];
+    validation: ValidationResult;
+};
+type Flow<TContext, TPatch = unknown> = {
+    runner: Runner<TContext, TPatch>;
+    start(): StartResult;
+    stop(options?: {
+        force?: boolean;
+    }): void;
+};
+type RunResult<TContext, TPatch = unknown> = {
+    status: 'success' | 'stopped' | 'failed' | 'skipped';
+    context: TContext;
+    data: Record<string, unknown>;
+    patches: TPatch[];
+    events: SlapEvent[];
+    error?: SlapError;
+    trace?: TraceEntry[];
+    steps: number;
+};
+type Runtime = {
+    get(path: string): unknown;
+    set(path: string, value: unknown): void;
+    data: {
+        get(path: string): unknown;
+        set(path: string, value: unknown): void;
+    };
+    variables?: {
+        get(path: string): unknown;
+    };
+    /** @deprecated Use `runtime.data.get(path)` instead. */
+    getData(path: string): unknown;
+    /** @deprecated Use `runtime.data.set(path, value)` instead. */
+    setData(path: string, value: unknown): void;
+    resolve(value: unknown): unknown;
+    signal: AbortSignal;
+    executeThen(): Promise<RuntimeBranchResult>;
+    executeCatch(): Promise<RuntimeBranchResult | undefined>;
+    emit(event: SlapEvent): void;
+    patch(patch: unknown): void;
+    stop(reason?: string): ActionStop<unknown>;
+    fail(reason?: string, data?: Record<string, unknown>): ActionFail;
+};
+type VariableValue = string | number | boolean | bigint | null | readonly VariableValue[] | {
+    readonly [key: string]: VariableValue;
+};
+type Variables = Readonly<Record<string, VariableValue>>;
+type RunnerOptions<TContext, TPatch> = {
+    maxStepCount?: number;
+    /** @deprecated Use `maxStepCount` instead. */
+    maxSteps?: number;
+    maxDepth?: number;
+    timeout?: number;
+    /** @deprecated Use `timeout`. It will be removed in a future major release. */
+    timeoutMs?: number;
+    trace?: boolean | TraceSink;
+    onError?: ErrorReporter<TContext, TPatch>;
+    mergeData?: (current: Record<string, unknown>, next: Record<string, unknown>) => Record<string, unknown>;
+    variables?: Variables;
+    expressions?: Record<string, ExpressionOperator>;
+};
+type ExpressionOperator = (args: unknown[]) => unknown;
+type RunOptions = {
+    signal?: AbortSignal;
+};
+type TraceSink = {
+    push(entry: TraceEntry): void;
+    entries?(): TraceEntry[];
+};
+type TraceEntry = {
+    step: number;
+    depth: number;
+    strategy: string;
+    fn: string;
+    mode: Mode | undefined;
+    status: 'matched' | 'skipped' | 'success' | 'stopped' | 'failed';
+    input: Input;
+    props: Props;
+    dataBefore: Record<string, unknown>;
+    dataAfter: Record<string, unknown>;
+    durationMs: number;
+    reason?: string;
+};
+type SlapError = {
+    code: string;
+    message: string;
+    strategy?: string;
+    fn?: string;
+    stage?: ErrorStage;
+    cause?: unknown;
+    path?: string;
+};
+type ErrorStage = {
+    phase: 'entrypoint' | 'condition' | 'action' | 'catch' | 'limit';
+    entrypoint?: string | undefined;
+    strategy?: string | undefined;
+    fn?: string | undefined;
+    mode?: Mode | undefined;
+    step?: number | undefined;
+    depth?: number | undefined;
+};
+type SlapErrorEvent<TContext, TPatch = unknown> = {
+    error: SlapError;
+    context: TContext;
+    input: Input;
+    data: Record<string, unknown>;
+    patches: TPatch[];
+    events: SlapEvent[];
+    trace?: TraceEntry[];
+};
+type ErrorReporter<TContext, TPatch = unknown> = (event: SlapErrorEvent<TContext, TPatch>) => void;
+type ErrorReporterHandlers<TContext, TPatch = unknown> = {
+    report: ErrorReporter<TContext, TPatch>;
+};
+type ValidationResult = {
+    ok: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+type ValidationIssue = {
+    code: string;
+    message: string;
+    path?: string;
+    strategy?: string;
+};
+type ConditionFn<TContext> = (context: {
+    context: TContext;
+    input: Input;
+    data: Record<string, unknown>;
+    runtime: Pick<Runtime, 'resolve' | 'get' | 'data' | 'variables' | 'getData'>;
+}, ...conditionArgs: unknown[]) => boolean;
+type Runner<TContext, TPatch = unknown> = {
+    registerAction(name: string, action: Action<TContext, TPatch>): void;
+    registerActions(actions: Record<string, Action<TContext, TPatch>>): void;
+    registerCondition(name: string, condition: ConditionFn<TContext>): void;
+    registerConditions(conditions: Record<string, ConditionFn<TContext>>): void;
+    loadConfig(config: Config): ValidationResult;
+    validateConfig(config?: Config): ValidationResult;
+    run(entrypoint: string, context: TContext, input?: Input, options?: RunOptions): Promise<RunResult<TContext, TPatch>>;
+    runSync(entrypoint: string, context: TContext, input?: Input, options?: RunOptions): RunResult<TContext, TPatch>;
+};
+
+/** @deprecated Pass the configuration object directly to `createFlow` or `runner.loadConfig`. */
+declare const defineConfig: <TConfig extends Config>(config: TConfig) => TConfig;
+
+declare const createMemoryTraceSink: () => TraceSink;
+
+declare const defineErrorReporter: <TContext, TPatch = unknown>(handlers: ErrorReporterHandlers<TContext, TPatch> | ErrorReporter<TContext, TPatch>) => ErrorReporter<TContext, TPatch>;
+
+declare const createPubSub: <TEvents extends object = EventMap>(options?: BusOptions<TEvents>) => Bus<TEvents>;
+declare const PubSub: Bus<EventMap>;
+
+declare const createFlow: <TContext, TPatch = unknown, TEvents extends object = BindingEventMap>(definition: FlowDefinition<TContext, TPatch, TEvents>, options: FlowOptions<TContext, TPatch, TEvents>) => Flow<TContext, TPatch>;
+
+declare const createWS: <TEvents extends object = EventMap>(options: WSOptions<TEvents>) => WS;
+
+declare const catchError: <T>(callback: () => T | PromiseLike<T>) => Promise<T>;
+
+type ActionsRegistry<TContext, TPatch> = Map<string, Action<TContext, TPatch>>;
+declare const createActionsRegistry: <TContext, TPatch>() => ActionsRegistry<TContext, TPatch>;
+
+type ConditionsRegistry<TContext> = Map<string, ConditionFn<TContext>>;
+declare const createConditionsRegistry: <TContext>() => ConditionsRegistry<TContext>;
+
+export { type Action, type ActionArgs, type ActionFail, type ActionResult, type ActionSkip, type ActionStop, type ActionSuccess, type ActionsRegistry, type BindingEventMap, type Bus, type BusBinding, type BusBindingKey, type BusBindings, type BusEmitOptions, type BusErrorEvent, type BusEvent, type BusOptions, type ConcurrencyMode, type ConcurrencyOptions, type ConditionExpression, type ConditionFn, type ConditionsRegistry, type Config, type DomBinding, type DomBindingKey, type DomBindings, type DomForm, type DomInput, type ErrorReporter, type ErrorReporterHandlers, type ErrorStage, type EventHandler, type EventMap, type EventName, type ExpressionOperator, type FetchResponseType, type Flow, type FlowDefinition, type FlowOptions, type InactiveBinding, type Input, type Mode, type Next, type Props, PubSub, type QueueOverflow, type RetryOptions, type RunOptions, type RunResult, type Runner, type RunnerErrorEvent, type RunnerOptions, type Runtime, type SlapError, type SlapErrorEvent, type SlapEvent, type StartResult, type Strategy, type TraceEntry, type TraceSink, type ValidationIssue, type ValidationResult, type VariableValue, type Variables, type WS, type WSOptions, type WSRetryOptions, type WSSocket, type WSStatus, catchError, createActionsRegistry, createConditionsRegistry, createFlow, createMemoryTraceSink, createPubSub, createWS, defineConfig, defineErrorReporter };