@coji/durably 0.4.0 → 0.6.1

package/dist/index.d.ts

@@ -1,543 +1,142 @@
-import { Dialect, Kysely } from 'kysely';
-import { z } from 'zod';
+import { D as Durably } from './index-CHQw-b_O.js';
+export { p as Database, g as DurablyEvent, a as DurablyOptions, b as DurablyPlugin, E as ErrorHandler, h as EventType, J as JobDefinition, n as JobHandle, e as JobInput, f as JobOutput, u as Log, L as LogWriteEvent, q as LogsTable, v as Run, R as RunCompleteEvent, i as RunFailEvent, x as RunFilter, j as RunProgressEvent, k as RunStartEvent, r as RunsTable, s as SchemaVersionsTable, y as Step, S as StepCompleteEvent, o as StepContext, l as StepFailEvent, m as StepStartEvent, t as StepsTable, T as TriggerAndWaitResult, W as WorkerErrorEvent, c as createDurably, d as defineJob, w as withLogPersistence } from './index-CHQw-b_O.js';
+import 'kysely';
+import 'zod';
 
 /**
- * Base event interface
- */
-interface BaseEvent {
-    type: string;
-    timestamp: string;
-    sequence: number;
-}
-/**
- * Run start event
- */
-interface RunStartEvent extends BaseEvent {
-    type: 'run:start';
-    runId: string;
-    jobName: string;
-    payload: unknown;
-}
-/**
- * Run complete event
- */
-interface RunCompleteEvent extends BaseEvent {
-    type: 'run:complete';
-    runId: string;
-    jobName: string;
-    output: unknown;
-    duration: number;
-}
-/**
- * Run fail event
- */
-interface RunFailEvent extends BaseEvent {
-    type: 'run:fail';
-    runId: string;
-    jobName: string;
-    error: string;
-    failedStepName: string;
-}
-/**
- * Step start event
- */
-interface StepStartEvent extends BaseEvent {
-    type: 'step:start';
-    runId: string;
-    jobName: string;
-    stepName: string;
-    stepIndex: number;
-}
-/**
- * Step complete event
- */
-interface StepCompleteEvent extends BaseEvent {
-    type: 'step:complete';
-    runId: string;
-    jobName: string;
-    stepName: string;
-    stepIndex: number;
-    output: unknown;
-    duration: number;
-}
-/**
- * Step fail event
- */
-interface StepFailEvent extends BaseEvent {
-    type: 'step:fail';
-    runId: string;
-    jobName: string;
-    stepName: string;
-    stepIndex: number;
-    error: string;
-}
-/**
- * Log write event
- */
-interface LogWriteEvent extends BaseEvent {
-    type: 'log:write';
-    runId: string;
-    stepName: string | null;
-    level: 'info' | 'warn' | 'error';
-    message: string;
-    data: unknown;
-}
-/**
- * Worker error event (internal errors like heartbeat failures)
- */
-interface WorkerErrorEvent extends BaseEvent {
-    type: 'worker:error';
-    error: string;
-    context: string;
-    runId?: string;
-}
-/**
- * All event types as discriminated union
- */
-type DurablyEvent = RunStartEvent | RunCompleteEvent | RunFailEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | LogWriteEvent | WorkerErrorEvent;
-/**
- * Event types for type-safe event names
- */
-type EventType = DurablyEvent['type'];
-/**
- * Extract event by type
- */
-type EventByType<T extends EventType> = Extract<DurablyEvent, {
-    type: T;
-}>;
-/**
- * Event input (without auto-generated fields)
- */
-type EventInput<T extends EventType> = Omit<EventByType<T>, 'timestamp' | 'sequence'>;
-/**
- * All possible event inputs as a union (properly distributed)
- */
-type AnyEventInput = EventInput<'run:start'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'log:write'> | EventInput<'worker:error'>;
-/**
- * Event listener function
- */
-type EventListener<T extends EventType> = (event: EventByType<T>) => void;
-/**
- * Unsubscribe function returned by on()
- */
-type Unsubscribe = () => void;
-/**
- * Error handler function for listener exceptions
- */
-type ErrorHandler = (error: Error, event: DurablyEvent) => void;
-
-/**
- * Database schema types for Durably
+ * Error thrown when a run is cancelled during execution.
+ * The worker catches this error and treats it specially - it does not
+ * mark the run as failed, as the run status is already 'cancelled'.
  */
-interface RunsTable {
-    id: string;
-    job_name: string;
-    payload: string;
-    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-    idempotency_key: string | null;
-    concurrency_key: string | null;
-    current_step_index: number;
-    progress: string | null;
-    output: string | null;
-    error: string | null;
-    heartbeat_at: string;
-    created_at: string;
-    updated_at: string;
-}
-interface StepsTable {
-    id: string;
-    run_id: string;
-    name: string;
-    index: number;
-    status: 'completed' | 'failed';
-    output: string | null;
-    error: string | null;
-    started_at: string;
-    completed_at: string | null;
-}
-interface LogsTable {
-    id: string;
-    run_id: string;
-    step_name: string | null;
-    level: 'info' | 'warn' | 'error';
-    message: string;
-    data: string | null;
-    created_at: string;
-}
-interface SchemaVersionsTable {
-    version: number;
-    applied_at: string;
-}
-interface Database {
-    durably_runs: RunsTable;
-    durably_steps: StepsTable;
-    durably_logs: LogsTable;
-    durably_schema_versions: SchemaVersionsTable;
+declare class CancelledError extends Error {
+    constructor(runId: string);
 }
 
 /**
- * Run data for creating a new run
+ * Request body for triggering a job
  */
-interface CreateRunInput {
+interface TriggerRequest {
     jobName: string;
-    payload: unknown;
+    input: Record<string, unknown>;
     idempotencyKey?: string;
     concurrencyKey?: string;
 }
 /**
- * Run data returned from storage
- */
-interface Run {
-    id: string;
-    jobName: string;
-    payload: unknown;
-    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-    idempotencyKey: string | null;
-    concurrencyKey: string | null;
-    currentStepIndex: number;
-    progress: {
-        current: number;
-        total?: number;
-        message?: string;
-    } | null;
-    output: unknown | null;
-    error: string | null;
-    heartbeatAt: string;
-    createdAt: string;
-    updatedAt: string;
-}
-/**
- * Run update data
- */
-interface UpdateRunInput {
-    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-    currentStepIndex?: number;
-    progress?: {
-        current: number;
-        total?: number;
-        message?: string;
-    } | null;
-    output?: unknown;
-    error?: string | null;
-    heartbeatAt?: string;
-}
-/**
- * Run filter options
- */
-interface RunFilter$1 {
-    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
-    jobName?: string;
-    /** Maximum number of runs to return */
-    limit?: number;
-    /** Number of runs to skip (for pagination) */
-    offset?: number;
-}
-/**
- * Step data for creating a new step
+ * Response for trigger endpoint
  */
-interface CreateStepInput {
+interface TriggerResponse {
     runId: string;
-    name: string;
-    index: number;
-    status: 'completed' | 'failed';
-    output?: unknown;
-    error?: string;
-    startedAt: string;
 }
 /**
- * Step data returned from storage
+ * Handler interface for HTTP endpoints
  */
-interface Step {
-    id: string;
-    runId: string;
-    name: string;
-    index: number;
-    status: 'completed' | 'failed';
-    output: unknown | null;
-    error: string | null;
-    startedAt: string;
-    completedAt: string | null;
-}
-/**
- * Log data for creating a new log
- */
-interface CreateLogInput {
-    runId: string;
-    stepName: string | null;
-    level: 'info' | 'warn' | 'error';
-    message: string;
-    data?: unknown;
-}
-/**
- * Log data returned from storage
- */
-interface Log {
-    id: string;
-    runId: string;
-    stepName: string | null;
-    level: 'info' | 'warn' | 'error';
-    message: string;
-    data: unknown | null;
-    createdAt: string;
-}
-/**
- * Storage interface for database operations
- */
-interface Storage {
-    createRun(input: CreateRunInput): Promise<Run>;
-    batchCreateRuns(inputs: CreateRunInput[]): Promise<Run[]>;
-    updateRun(runId: string, data: UpdateRunInput): Promise<void>;
-    deleteRun(runId: string): Promise<void>;
-    getRun(runId: string): Promise<Run | null>;
-    getRuns(filter?: RunFilter$1): Promise<Run[]>;
-    getNextPendingRun(excludeConcurrencyKeys: string[]): Promise<Run | null>;
-    createStep(input: CreateStepInput): Promise<Step>;
-    getSteps(runId: string): Promise<Step[]>;
-    getCompletedStep(runId: string, name: string): Promise<Step | null>;
-    createLog(input: CreateLogInput): Promise<Log>;
-    getLogs(runId: string): Promise<Log[]>;
-}
-
-/**
- * Step context passed to the job function
- */
-interface StepContext {
+interface DurablyHandler {
     /**
-     * The ID of the current run
+     * Handle all Durably HTTP requests with automatic routing
+     *
+     * Routes:
+     * - GET  {basePath}/subscribe?runId=xxx - SSE stream
+     * - GET  {basePath}/runs - List runs
+     * - GET  {basePath}/run?runId=xxx - Get single run
+     * - POST {basePath}/trigger - Trigger a job
+     * - POST {basePath}/retry?runId=xxx - Retry a failed run
+     * - POST {basePath}/cancel?runId=xxx - Cancel a run
+     *
+     * @param request - The incoming HTTP request
+     * @param basePath - The base path to strip from the URL (e.g., '/api/durably')
+     * @returns Response or null if route not matched
+     *
+     * @example
+     * ```ts
+     * // React Router / Remix
+     * export async function loader({ request }) {
+     *   return durablyHandler.handle(request, '/api/durably')
+     * }
+     * export async function action({ request }) {
+     *   return durablyHandler.handle(request, '/api/durably')
+     * }
+     * ```
      */
-    readonly runId: string;
+    handle(request: Request, basePath: string): Promise<Response>;
     /**
-     * Execute a step with automatic persistence and replay
+     * Handle job trigger request
+     * Expects POST with JSON body: { jobName, input, idempotencyKey?, concurrencyKey? }
+     * Returns JSON: { runId }
      */
-    run<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    trigger(request: Request): Promise<Response>;
     /**
-     * Report progress for the current run
+     * Handle subscription request
+     * Expects GET with query param: runId
+     * Returns SSE stream of events
      */
-    progress(current: number, total?: number, message?: string): void;
+    subscribe(request: Request): Response;
     /**
-     * Log a message
+     * Handle runs list request
+     * Expects GET with optional query params: jobName, status, limit, offset
+     * Returns JSON array of runs
      */
-    log: {
-        info(message: string, data?: unknown): void;
-        warn(message: string, data?: unknown): void;
-        error(message: string, data?: unknown): void;
-    };
-}
-/**
- * Trigger options
- */
-interface TriggerOptions {
-    idempotencyKey?: string;
-    concurrencyKey?: string;
-    /** Timeout in milliseconds for triggerAndWait() */
-    timeout?: number;
-}
-/**
- * Run filter options
- */
-interface RunFilter {
-    status?: 'pending' | 'running' | 'completed' | 'failed';
-    jobName?: string;
-}
-/**
- * Typed run with output type
- */
-interface TypedRun<TOutput> extends Omit<Run, 'output'> {
-    output: TOutput | null;
-}
-/**
- * Batch trigger input - either just the input or input with options
- */
-type BatchTriggerInput<TInput> = TInput | {
-    input: TInput;
-    options?: TriggerOptions;
-};
-/**
- * Result of triggerAndWait
- */
-interface TriggerAndWaitResult<TOutput> {
-    id: string;
-    output: TOutput;
-}
-/**
- * Job handle returned by defineJob
- */
-interface JobHandle<TName extends string, TInput, TOutput> {
-    readonly name: TName;
+    runs(request: Request): Promise<Response>;
     /**
-     * Trigger a new run
+     * Handle single run request
+     * Expects GET with query param: runId
+     * Returns JSON run object or 404
      */
-    trigger(input: TInput, options?: TriggerOptions): Promise<TypedRun<TOutput>>;
+    run(request: Request): Promise<Response>;
     /**
-     * Trigger a new run and wait for completion
-     * Returns the output directly, throws if the run fails
+     * Handle retry request
+     * Expects POST with query param: runId
+     * Returns JSON: { success: true }
      */
-    triggerAndWait(input: TInput, options?: TriggerOptions): Promise<TriggerAndWaitResult<TOutput>>;
+    retry(request: Request): Promise<Response>;
     /**
-     * Trigger multiple runs in a batch
-     * All inputs are validated before any runs are created
+     * Handle cancel request
+     * Expects POST with query param: runId
+     * Returns JSON: { success: true }
      */
-    batchTrigger(inputs: BatchTriggerInput<TInput>[]): Promise<TypedRun<TOutput>[]>;
+    cancel(request: Request): Promise<Response>;
     /**
-     * Get a run by ID
+     * Handle delete request
+     * Expects DELETE with query param: runId
+     * Returns JSON: { success: true }
      */
-    getRun(id: string): Promise<TypedRun<TOutput> | null>;
+    delete(request: Request): Promise<Response>;
     /**
-     * Get runs with optional filter
+     * Handle steps request
+     * Expects GET with query param: runId
+     * Returns JSON array of steps
      */
-    getRuns(filter?: Omit<RunFilter, 'jobName'>): Promise<TypedRun<TOutput>[]>;
-}
-
-/**
- * Job run function type
- */
-type JobRunFunction<TInput, TOutput> = (step: StepContext, payload: TInput) => Promise<TOutput>;
-/**
- * Job definition - a standalone description of a job
- * This is the result of calling defineJob() and can be passed to durably.register()
- */
-interface JobDefinition<TName extends string, TInput, TOutput> {
-    readonly name: TName;
-    readonly input: z.ZodType<TInput>;
-    readonly output: z.ZodType<TOutput> | undefined;
-    readonly run: JobRunFunction<TInput, TOutput>;
-}
-/**
- * Configuration for defining a job
- */
-interface DefineJobConfig<TName extends string, TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType | undefined> {
-    name: TName;
-    input: TInputSchema;
-    output?: TOutputSchema;
-    run: JobRunFunction<z.infer<TInputSchema>, TOutputSchema extends z.ZodType ? z.infer<TOutputSchema> : void>;
-}
-/**
- * Define a job - creates a JobDefinition that can be registered with durably.register()
- *
- * @example
- * ```ts
- * import { defineJob } from '@coji/durably'
- * import { z } from 'zod'
- *
- * export const syncUsers = defineJob({
- *   name: 'sync-users',
- *   input: z.object({ orgId: z.string() }),
- *   output: z.object({ syncedCount: z.number() }),
- *   run: async (step, payload) => {
- *     const users = await step.run('fetch-users', () => fetchUsers(payload.orgId))
- *     return { syncedCount: users.length }
- *   },
- * })
- * ```
- */
-declare function defineJob<TName extends string, TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType | undefined = undefined>(config: DefineJobConfig<TName, TInputSchema, TOutputSchema>): JobDefinition<TName, z.infer<TInputSchema>, TOutputSchema extends z.ZodType ? z.infer<TOutputSchema> : void>;
-
-/**
- * Options for creating a Durably instance
- */
-interface DurablyOptions {
-    dialect: Dialect;
-    pollingInterval?: number;
-    heartbeatInterval?: number;
-    staleThreshold?: number;
-}
-/**
- * Plugin interface for extending Durably
- */
-interface DurablyPlugin {
-    name: string;
-    install(durably: Durably): void;
+    steps(request: Request): Promise<Response>;
+    /**
+     * Handle runs subscription request
+     * Expects GET with optional query param: jobName
+     * Returns SSE stream of run update notifications
+     */
+    runsSubscribe(request: Request): Response;
 }
 /**
- * Durably instance
+ * Options for createDurablyHandler
  */
-interface Durably {
-    /**
-     * Run database migrations
-     * This is idempotent and safe to call multiple times
-     */
-    migrate(): Promise<void>;
-    /**
-     * Get the underlying Kysely database instance
-     * Useful for testing and advanced use cases
-     */
-    readonly db: Kysely<Database>;
-    /**
-     * Storage layer for database operations
-     */
-    readonly storage: Storage;
-    /**
-     * Register an event listener
-     * @returns Unsubscribe function
-     */
-    on<T extends EventType>(type: T, listener: EventListener<T>): Unsubscribe;
-    /**
-     * Emit an event (auto-assigns timestamp and sequence)
-     */
-    emit(event: AnyEventInput): void;
-    /**
-     * Register an error handler for listener exceptions
-     */
-    onError(handler: ErrorHandler): void;
-    /**
-     * Register a job definition and return a job handle
-     * Same JobDefinition can be registered multiple times (idempotent)
-     * Different JobDefinitions with the same name will throw an error
-     */
-    register<TName extends string, TInput, TOutput>(jobDef: JobDefinition<TName, TInput, TOutput>): JobHandle<TName, TInput, TOutput>;
-    /**
-     * Start the worker polling loop
-     */
-    start(): void;
-    /**
-     * Stop the worker after current run completes
-     */
-    stop(): Promise<void>;
-    /**
-     * Retry a failed run by resetting it to pending
-     * @throws Error if run is not in failed status
-     */
-    retry(runId: string): Promise<void>;
-    /**
-     * Cancel a pending or running run
-     * @throws Error if run is already completed, failed, or cancelled
-     */
-    cancel(runId: string): Promise<void>;
+interface CreateDurablyHandlerOptions {
     /**
-     * Delete a completed, failed, or cancelled run and its associated steps and logs
-     * @throws Error if run is pending or running, or does not exist
+     * Called before handling each request.
+     * Use this to initialize Durably (migrate, start worker, etc.)
+     *
+     * @example
+     * ```ts
+     * const durablyHandler = createDurablyHandler(durably, {
+     *   onRequest: async () => {
+     *     await durably.migrate()
+     *     durably.start()
+     *   }
+     * })
+     * ```
      */
-    deleteRun(runId: string): Promise<void>;
-    /**
-     * Get a run by ID (returns unknown output type)
-     */
-    getRun(runId: string): Promise<Run | null>;
-    /**
-     * Get runs with optional filtering
-     */
-    getRuns(filter?: RunFilter$1): Promise<Run[]>;
-    /**
-     * Register a plugin
-     */
-    use(plugin: DurablyPlugin): void;
+    onRequest?: () => Promise<void> | void;
 }
 /**
- * Create a Durably instance
+ * Create HTTP handlers for Durably
+ * Uses Web Standard Request/Response for framework-agnostic usage
  */
-declare function createDurably(options: DurablyOptions): Durably;
-
-/**
- * Plugin that persists log events to the database
- */
-declare function withLogPersistence(): DurablyPlugin;
-
-/**
- * Error thrown when a run is cancelled during execution.
- * The worker catches this error and treats it specially - it does not
- * mark the run as failed, as the run status is already 'cancelled'.
- */
-declare class CancelledError extends Error {
-    constructor(runId: string);
-}
+declare function createDurablyHandler(durably: Durably, options?: CreateDurablyHandlerOptions): DurablyHandler;
 
-export { CancelledError, type Database, type Durably, type DurablyEvent, type DurablyOptions, type DurablyPlugin, type ErrorHandler, type EventType, type JobDefinition, type JobHandle, type Log, type LogWriteEvent, type LogsTable, type Run, type RunCompleteEvent, type RunFailEvent, type RunFilter$1 as RunFilter, type RunStartEvent, type RunsTable, type SchemaVersionsTable, type Step, type StepCompleteEvent, type StepContext, type StepFailEvent, type StepStartEvent, type StepsTable, type TriggerAndWaitResult, type WorkerErrorEvent, createDurably, defineJob, withLogPersistence };
+export { CancelledError, Durably, type DurablyHandler, type TriggerRequest, type TriggerResponse, createDurablyHandler };