@stepflowjs/core 0.0.1

package/dist/index-D_2FGtKL.d.ts

@@ -0,0 +1,155 @@
+type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+type ExecutionStatus = "pending" | "running" | "completed" | "failed" | "waiting" | "sleeping" | "cancelled";
+interface WorkflowEvent<TData = unknown> {
+    id: string;
+    name: string;
+    data: TData;
+    timestamp: Date;
+    metadata: Record<string, unknown>;
+}
+type WorkflowEventMap = Record<string, {
+    data: unknown;
+}>;
+interface Execution<TPayload = unknown, TResult = unknown> {
+    id: string;
+    runId: string;
+    workflowId: string;
+    workflowVersion?: string;
+    eventName: string;
+    payload: TPayload;
+    status: ExecutionStatus;
+    result?: TResult;
+    error?: ExecutionError;
+    steps: StepExecution[];
+    metadata: Record<string, unknown>;
+    attempt: number;
+    startedAt: Date;
+    completedAt?: Date;
+    timeline: TimelineEvent[];
+}
+interface ExecutionError {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+}
+interface StepExecution {
+    name: string;
+    status: "pending" | "running" | "completed" | "failed" | "cached";
+    result?: unknown;
+    error?: ExecutionError;
+    startedAt?: Date;
+    completedAt?: Date;
+    durationMs?: number;
+}
+interface StepResult<T = unknown> {
+    data: T;
+    startedAt: Date;
+    completedAt: Date;
+    durationMs: number;
+}
+type TimelineEventType = "execution:start" | "execution:complete" | "execution:failed" | "step:start" | "step:complete" | "step:failed" | "step:cached" | "invoke:start" | "sleep:start" | "sleep:complete" | "event:wait" | "event:received" | "event:timeout" | "log:info" | "log:warn" | "log:error" | "log:debug" | "metadata:update";
+interface TimelineEvent {
+    id: string;
+    type: TimelineEventType;
+    timestamp: Date;
+    data: unknown;
+    stepName?: string;
+    metadata?: Record<string, unknown>;
+}
+interface QueueJob {
+    id: string;
+    workflowId: string;
+    eventName: string;
+    payload: unknown;
+    metadata: Record<string, unknown>;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    scheduledFor?: Date;
+    createdAt: Date;
+}
+interface PopOptions {
+    workerId?: string;
+    lockDuration?: number;
+}
+interface NackOptions {
+    delay?: number;
+    requeue?: boolean;
+}
+interface TriggerEvent {
+    id: string;
+    type: string;
+    source: string;
+    data: unknown;
+    metadata: Record<string, unknown>;
+    timestamp: Date;
+}
+type TriggerHandler = (event: TriggerEvent) => Promise<void>;
+interface Trigger<TConfig = unknown> {
+    readonly type: string;
+    readonly config: TConfig;
+    start(handler: TriggerHandler): Promise<void>;
+    stop(): Promise<void>;
+    healthCheck(): Promise<boolean>;
+}
+interface WorkflowConfig {
+    id: string;
+    version?: string;
+    retries?: number;
+    retryDelay?: Duration;
+    timeout?: Duration;
+    cron?: string;
+}
+interface InvokeOptions {
+    timeout?: Duration;
+    metadata?: Record<string, unknown>;
+}
+interface WaitForEventOptions {
+    timeout?: Duration;
+}
+interface WaitForEventResult<T = unknown> {
+    eventData: T;
+    timeout: boolean;
+}
+interface StepOptions {
+    /** Timeout for this step */
+    timeout?: Duration;
+    /** Custom cache key for this step (for idempotency) */
+    idempotencyKey?: string;
+}
+interface ListOptions {
+    workflowId?: string;
+    status?: ExecutionStatus;
+    runId?: string;
+    limit?: number;
+    offset?: number;
+}
+interface EventWaiter {
+    executionId: string;
+    timeoutAt?: Date;
+}
+interface TriggerResult {
+    runId: string;
+    executionId: string;
+    publicAccessToken: string;
+    /** True if this trigger returned an existing execution (deduplicated) */
+    deduplicated?: boolean;
+}
+interface NotifyResult {
+    waiters: number;
+    executions: string[];
+}
+interface SubscribeOptions<TPayload = unknown, TResult = unknown> {
+    accessToken?: string;
+    throttleMs?: number;
+    onUpdate?: (run: Execution<TPayload, TResult>) => void;
+    onStepComplete?: (step: StepExecution) => void;
+    onComplete?: (result: TResult) => void;
+    onError?: (error: Error) => void;
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+}
+type Unsubscribe = () => void;
+
+export type { Duration as D, Execution as E, InvokeOptions as I, ListOptions as L, NotifyResult as N, PopOptions as P, QueueJob as Q, StepOptions as S, TimelineEvent as T, Unsubscribe as U, WorkflowEvent as W, WaitForEventOptions as a, WaitForEventResult as b, WorkflowConfig as c, Trigger as d, TriggerResult as e, ExecutionStatus as f, WorkflowEventMap as g, ExecutionError as h, StepExecution as i, StepResult as j, TimelineEventType as k, NackOptions as l, TriggerEvent as m, TriggerHandler as n, EventWaiter as o, SubscribeOptions as p };

package/dist/index.d.ts

@@ -0,0 +1,466 @@
+import { EventEmitter } from 'events';
+import { StorageAdapter } from './storage/index.js';
+import { W as WorkflowEvent, S as StepOptions, I as InvokeOptions, D as Duration, a as WaitForEventOptions, b as WaitForEventResult, T as TimelineEvent, c as WorkflowConfig, d as Trigger, e as TriggerResult, E as Execution, L as ListOptions, N as NotifyResult } from './index-D_2FGtKL.js';
+export { o as EventWaiter, h as ExecutionError, f as ExecutionStatus, l as NackOptions, P as PopOptions, Q as QueueJob, i as StepExecution, j as StepResult, p as SubscribeOptions, k as TimelineEventType, m as TriggerEvent, n as TriggerHandler, U as Unsubscribe, g as WorkflowEventMap } from './index-D_2FGtKL.js';
+
+interface WorkflowContext<TPayload = unknown> {
+    /**
+     * The event that triggered this workflow
+     */
+    readonly event: WorkflowEvent<TPayload>;
+    /**
+     * Execution metadata
+     */
+    readonly execution: {
+        readonly id: string;
+        readonly runId: string;
+        readonly attempt: number;
+        readonly startedAt: Date;
+    };
+    /**
+     * Step execution methods (checkpointed, never re-execute on retry)
+     */
+    readonly step: StepContext;
+    /**
+     * Sleep for a duration (durable - survives restarts)
+     */
+    sleep(name: string, duration: Duration): Promise<void>;
+    /**
+     * Sleep until a specific timestamp
+     */
+    sleepUntil(name: string, timestamp: Date): Promise<void>;
+    /**
+     * Wait for an external event
+     */
+    waitForEvent<T = unknown>(name: string, eventId: string, options?: WaitForEventOptions): Promise<WaitForEventResult<T>>;
+    /**
+     * Structured logging (captured in timeline)
+     */
+    readonly log: LogContext;
+    /**
+     * Update metadata (visible to subscribers)
+     */
+    setMetadata(key: string, value: unknown): Promise<void>;
+    /**
+     * Get metadata value
+     */
+    getMetadata<T = unknown>(key: string): T | undefined;
+}
+interface StepContext {
+    /**
+     * Run a step with automatic checkpointing
+     * If the workflow retries, completed steps are not re-executed
+     */
+    run<T>(name: string, fn: () => Promise<T> | T, options?: StepOptions): Promise<T>;
+    /**
+     * Run multiple steps in parallel
+     */
+    parallel<T extends readonly unknown[]>(name: string, fns: {
+        [K in keyof T]: () => Promise<T[K]>;
+    }, options?: StepOptions): Promise<T>;
+    /**
+     * Invoke another workflow
+     */
+    invoke<TResult = unknown>(workflowId: string, payload: unknown, options?: InvokeOptions): Promise<TResult>;
+    /**
+     * Send an event (for waitForEvent in other workflows)
+     */
+    sendEvent(eventId: string, data: unknown): Promise<void>;
+}
+interface LogContext {
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+}
+interface CreateContextOptions<TPayload> {
+    event: WorkflowEvent<TPayload>;
+    executionId: string;
+    runId: string;
+    attempt: number;
+    startedAt: Date;
+    storage: StorageAdapter;
+    onTimelineEvent?: (event: TimelineEvent) => void;
+}
+declare function createContext<TPayload>(options: CreateContextOptions<TPayload>): WorkflowContext<TPayload>;
+declare class StepTimeoutError extends Error {
+    readonly stepName: string;
+    readonly timeoutMs: number;
+    constructor(stepName: string, timeoutMs: number);
+}
+declare class SleepInterrupt extends Error {
+    readonly stepName: string;
+    readonly wakeAt: Date;
+    constructor(stepName: string, wakeAt: Date);
+}
+declare class WaitForEventInterrupt extends Error {
+    readonly stepName: string;
+    readonly eventId: string;
+    readonly timeoutAt: Date;
+    constructor(stepName: string, eventId: string, timeoutAt: Date);
+}
+declare class InvokeInterrupt extends Error {
+    readonly stepName: string;
+    readonly workflowId: string;
+    readonly payload: unknown;
+    readonly childExecutionId: string;
+    readonly options?: InvokeOptions | undefined;
+    constructor(stepName: string, workflowId: string, payload: unknown, childExecutionId: string, options?: InvokeOptions | undefined);
+}
+
+type WorkflowHandler<TInput = unknown, TResult = unknown> = (context: WorkflowContext<TInput>) => Promise<TResult>;
+interface WorkflowDefinition<TInput = unknown, TResult = unknown> {
+    readonly id: string;
+    readonly config: WorkflowConfig;
+    readonly handler: WorkflowHandler<TInput, TResult>;
+}
+interface CreateWorkflowOptions extends Partial<WorkflowConfig> {
+    id: string;
+}
+/**
+ * Create a new workflow definition
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with input type
+ * const processOrder = createWorkflow<{ orderId: string }>({
+ *   id: 'process-order',
+ *   retries: 3,
+ * }, async ({ event, step, sleep }) => {
+ *   const order = await step.run('validate', async () => {
+ *     return validateOrder(event.data.orderId); // orderId is typed
+ *   });
+ *
+ *   await sleep('wait-before-shipping', '1h');
+ *
+ *   await step.run('ship', async () => {
+ *     return shipOrder(order);
+ *   });
+ *
+ *   return { status: 'completed' };
+ * });
+ *
+ * // With explicit result type
+ * const workflow = createWorkflow<{ userId: string }, { status: string }>({
+ *   id: 'my-workflow',
+ * }, async ({ event }) => {
+ *   return { status: 'done' }; // result type is enforced
+ * });
+ * ```
+ */
+declare function createWorkflow<TInput = unknown, TResult = unknown>(options: CreateWorkflowOptions, handler: WorkflowHandler<TInput, TResult>): WorkflowDefinition<TInput, TResult>;
+declare class WorkflowRegistry {
+    private workflows;
+    /**
+     * Register a workflow
+     */
+    register(workflow: WorkflowDefinition<any, any>): void;
+    /**
+     * Get a workflow by ID and optional version
+     */
+    get(id: string, version?: string): WorkflowDefinition<any, any> | undefined;
+    /**
+     * Get the latest version of a workflow
+     */
+    getLatest(id: string): WorkflowDefinition<any, any> | undefined;
+    /**
+     * Compare semantic versions
+     */
+    private compareVersions;
+    /**
+     * Check if a workflow exists
+     */
+    has(id: string): boolean;
+    /**
+     * Get all registered workflows (latest version of each)
+     */
+    all(): WorkflowDefinition<any, any>[];
+    /**
+     * Get all versions of a workflow
+     */
+    allVersions(id: string): WorkflowDefinition<any, any>[];
+    /**
+     * Get all workflows with cron schedules
+     */
+    scheduled(): WorkflowDefinition<any, any>[];
+    /**
+     * Unregister a workflow or specific version
+     */
+    unregister(id: string, version?: string): boolean;
+    /**
+     * Clear all workflows
+     */
+    clear(): void;
+}
+
+interface StepflowOptions {
+    /**
+     * Storage adapter for persistence
+     */
+    storage: StorageAdapter;
+    /**
+     * Number of worker concurrency
+     * @default 1
+     */
+    concurrency?: number;
+    /**
+     * Enable logging
+     * @default false
+     */
+    logging?: boolean;
+    /**
+     * Secret for signing access tokens
+     */
+    tokenSecret?: string;
+    /**
+     * Access token expiry in seconds
+     * @default 3600 (1 hour)
+     */
+    tokenExpiry?: number;
+}
+declare class Stepflow extends EventEmitter {
+    private storage;
+    private registry;
+    private worker;
+    private triggers;
+    private logging;
+    private tokenSecret;
+    private tokenExpiry;
+    constructor(options: StepflowOptions);
+    /**
+     * Register a workflow
+     */
+    register(workflow: WorkflowDefinition<any, any>): this;
+    /**
+     * Register multiple workflows
+     */
+    registerAll(workflows: WorkflowDefinition<any, any>[]): this;
+    /**
+     * Add a trigger
+     */
+    addTrigger(name: string, trigger: Trigger): this;
+    /**
+     * Start the orchestrator
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the orchestrator
+     */
+    stop(): Promise<void>;
+    /**
+     * Trigger a workflow execution
+     */
+    trigger<TPayload = unknown>(workflowId: string, payload: TPayload, options?: {
+        runId?: string;
+        metadata?: Record<string, unknown>;
+        delay?: number;
+        idempotencyKey?: string;
+    }): Promise<TriggerResult>;
+    /**
+     * Get a run by ID
+     */
+    getRun(runId: string, options?: {
+        accessToken?: string;
+    }): Promise<Execution | null>;
+    /**
+     * Get execution by ID
+     */
+    getExecution(executionId: string): Promise<Execution | null>;
+    /**
+     * List executions
+     */
+    listRuns(options?: ListOptions): Promise<Execution[]>;
+    /**
+     * Notify an event (for waitForEvent)
+     */
+    notify(eventId: string, data: unknown): Promise<NotifyResult>;
+    /**
+     * Create a public access token for a run
+     */
+    createPublicToken(runId: string, executionId?: string): string;
+    /**
+     * Subscribe to run updates
+     */
+    subscribeToRun(runId: string, callback: (execution: Execution) => void): () => void;
+    /**
+     * Subscribe to execution updates
+     */
+    subscribeToExecution(executionId: string, callback: (event: unknown) => void): () => void;
+    /**
+     * Handle trigger events
+     */
+    private handleTrigger;
+    /**
+     * Get a trigger by name
+     */
+    getTrigger(type: string, ...args: unknown[]): Trigger | undefined;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Get workflow registry
+     */
+    getRegistry(): WorkflowRegistry;
+    /**
+     * Log helper
+     */
+    private log;
+}
+
+interface WorkerEvents {
+    "execution:start": {
+        executionId: string;
+        workflowId: string;
+        eventName: string;
+    };
+    "execution:complete": {
+        executionId: string;
+        result: unknown;
+    };
+    "execution:failed": {
+        executionId: string;
+        error: Error;
+        willRetry: boolean;
+    };
+    "execution:sleeping": {
+        executionId: string;
+        wakeAt: Date;
+    };
+    "execution:waiting": {
+        executionId: string;
+        eventId: string;
+        timeoutAt: Date;
+    };
+    "execution:invoking": {
+        executionId: string;
+        childExecutionId: string;
+        childWorkflowId: string;
+    };
+    "step:complete": {
+        executionId: string;
+        stepName: string;
+        result: unknown;
+    };
+    "step:failed": {
+        executionId: string;
+        stepName: string;
+        error: Error;
+    };
+    error: {
+        error: Error;
+    };
+}
+interface WorkerOptions {
+    /**
+     * Storage adapter for persistence
+     */
+    storage: StorageAdapter;
+    /**
+     * Workflow registry
+     */
+    registry: WorkflowRegistry;
+    /**
+     * Number of concurrent jobs to process
+     * @default 1
+     */
+    concurrency?: number;
+    /**
+     * Interval in ms to poll for jobs when queue is empty
+     * @default 1000
+     */
+    pollInterval?: number;
+    /**
+     * Worker ID (for debugging/logging)
+     */
+    workerId?: string;
+    /**
+     * Enable logging
+     * @default false
+     */
+    logging?: boolean;
+}
+declare class Worker extends EventEmitter {
+    private storage;
+    private registry;
+    private concurrency;
+    private pollInterval;
+    private workerId;
+    private logging;
+    private running;
+    private activeJobs;
+    private pollTimeout?;
+    constructor(options: WorkerOptions);
+    /**
+     * Start the worker
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the worker gracefully
+     */
+    stop(): Promise<void>;
+    /**
+     * Poll for jobs
+     */
+    private poll;
+    /**
+     * Process a single job
+     */
+    private processJob;
+    /**
+     * Execute a workflow
+     */
+    private executeWorkflow;
+    /**
+     * Handle resume from sleep
+     */
+    private handleResume;
+    /**
+     * Handle event timeout
+     */
+    private handleTimeout;
+    /**
+     * Handle child workflow completion
+     */
+    private handleInvokeComplete;
+    /**
+     * Handle timeline events
+     */
+    private handleTimelineEvent;
+    /**
+     * Log helper
+     */
+    private log;
+}
+
+/**
+ * Parse a duration value to milliseconds
+ *
+ * Supports:
+ * - Number: treated as milliseconds
+ * - String: parsed with ms library (e.g., "1d", "2h", "30m", "10s", "500ms")
+ */
+declare function parseDuration(duration: Duration): number;
+/**
+ * Format milliseconds as a human-readable duration string
+ */
+declare function formatDuration(ms: number): string;
+
+interface TokenPayload {
+    runId: string;
+    executionId?: string;
+    exp: number;
+}
+/**
+ * Create a simple signed access token
+ */
+declare function createAccessToken(data: {
+    runId: string;
+    executionId?: string;
+}, secret: string, expirySeconds: number): string;
+/**
+ * Verify and decode an access token
+ */
+declare function verifyAccessToken(token: string, secret: string): TokenPayload | null;
+
+export { type CreateContextOptions, type CreateWorkflowOptions, Duration, Execution, InvokeInterrupt, InvokeOptions, ListOptions, type LogContext, NotifyResult, SleepInterrupt, type StepContext, StepOptions, StepTimeoutError, Stepflow, type StepflowOptions, TimelineEvent, Trigger, TriggerResult, WaitForEventInterrupt, WaitForEventOptions, WaitForEventResult, Worker, type WorkerEvents, type WorkerOptions, WorkflowConfig, type WorkflowContext, type WorkflowDefinition, WorkflowEvent, type WorkflowHandler, WorkflowRegistry, createAccessToken, createContext, createWorkflow, formatDuration, parseDuration, verifyAccessToken };