@coji/durably 0.6.0 → 0.7.0

package/dist/chunk-UCUP6NMJ.js

@@ -0,0 +1,22 @@
+// src/plugins/log-persistence.ts
+function withLogPersistence() {
+  return {
+    name: "log-persistence",
+    install(durably) {
+      durably.on("log:write", async (event) => {
+        await durably.storage.createLog({
+          runId: event.runId,
+          stepName: event.stepName,
+          level: event.level,
+          message: event.message,
+          data: event.data
+        });
+      });
+    }
+  };
+}
+
+export {
+  withLogPersistence
+};
+//# sourceMappingURL=chunk-UCUP6NMJ.js.map

package/dist/chunk-UCUP6NMJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugins/log-persistence.ts"],"sourcesContent":["import type { DurablyPlugin } from '../durably'\n\n/**\n * Plugin that persists log events to the database\n */\nexport function withLogPersistence(): DurablyPlugin {\n  return {\n    name: 'log-persistence',\n    install(durably) {\n      durably.on('log:write', async (event) => {\n        await durably.storage.createLog({\n          runId: event.runId,\n          stepName: event.stepName,\n          level: event.level,\n          message: event.message,\n          data: event.data,\n        })\n      })\n    },\n  }\n}\n"],"mappings":";AAKO,SAAS,qBAAoC;AAClD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,SAAS;AACf,cAAQ,GAAG,aAAa,OAAO,UAAU;AACvC,cAAM,QAAQ,QAAQ,UAAU;AAAA,UAC9B,OAAO,MAAM;AAAA,UACb,UAAU,MAAM;AAAA,UAChB,OAAO,MAAM;AAAA,UACb,SAAS,MAAM;AAAA,UACf,MAAM,MAAM;AAAA,QACd,CAAC;AAAA,MACH,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}

package/dist/index-4aPZWn8r.d.ts

@@ -0,0 +1,650 @@
+import { Dialect, Kysely } from 'kysely';
+import { z } from 'zod';
+
+/**
+ * Base event interface
+ */
+interface BaseEvent {
+    type: string;
+    timestamp: string;
+    sequence: number;
+}
+/**
+ * Run trigger event (emitted when a job is triggered, before worker picks it up)
+ */
+interface RunTriggerEvent extends BaseEvent {
+    type: 'run:trigger';
+    runId: string;
+    jobName: string;
+    payload: unknown;
+}
+/**
+ * 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;
+}
+/**
+ * Run cancel event
+ */
+interface RunCancelEvent extends BaseEvent {
+    type: 'run:cancel';
+    runId: string;
+    jobName: string;
+}
+/**
+ * Run retry event (emitted when a failed run is retried)
+ */
+interface RunRetryEvent extends BaseEvent {
+    type: 'run:retry';
+    runId: string;
+    jobName: string;
+}
+/**
+ * Run progress event
+ */
+interface RunProgressEvent extends BaseEvent {
+    type: 'run:progress';
+    runId: string;
+    jobName: string;
+    progress: {
+        current: number;
+        total?: number;
+        message?: 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 = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunRetryEvent | RunProgressEvent | 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:trigger'> | EventInput<'run:start'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'run:cancel'> | EventInput<'run:retry'> | EventInput<'run:progress'> | 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
+ */
+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;
+}
+
+/**
+ * Run data for creating a new run
+ */
+interface CreateRunInput {
+    jobName: string;
+    payload: 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;
+    stepCount: 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
+ */
+interface CreateStepInput {
+    runId: string;
+    name: string;
+    index: number;
+    status: 'completed' | 'failed';
+    output?: unknown;
+    error?: string;
+    startedAt: string;
+}
+/**
+ * Step data returned from storage
+ */
+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<T extends Run = Run>(runId: string): Promise<T | null>;
+    getRuns<T extends Run = Run>(filter?: RunFilter$1): Promise<T[]>;
+    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 {
+    /**
+     * The ID of the current run
+     */
+    readonly runId: string;
+    /**
+     * Execute a step with automatic persistence and replay
+     */
+    run<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Report progress for the current run
+     */
+    progress(current: number, total?: number, message?: string): void;
+    /**
+     * Log a message
+     */
+    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' | 'cancelled';
+    jobName?: string;
+    /** Maximum number of runs to return */
+    limit?: number;
+    /** Number of runs to skip (for pagination) */
+    offset?: number;
+}
+/**
+ * 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;
+    /**
+     * Trigger a new run
+     */
+    trigger(input: TInput, options?: TriggerOptions): Promise<TypedRun<TOutput>>;
+    /**
+     * Trigger a new run and wait for completion
+     * Returns the output directly, throws if the run fails
+     */
+    triggerAndWait(input: TInput, options?: TriggerOptions): Promise<TriggerAndWaitResult<TOutput>>;
+    /**
+     * Trigger multiple runs in a batch
+     * All inputs are validated before any runs are created
+     */
+    batchTrigger(inputs: BatchTriggerInput<TInput>[]): Promise<TypedRun<TOutput>[]>;
+    /**
+     * Get a run by ID
+     */
+    getRun(id: string): Promise<TypedRun<TOutput> | null>;
+    /**
+     * Get runs with optional filter
+     */
+    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>;
+}
+/**
+ * Extract input type from a JobDefinition
+ * @example
+ * ```ts
+ * type Input = JobInput<typeof myJob> // { userId: string }
+ * ```
+ */
+type JobInput<T> = T extends JobDefinition<string, infer TInput, unknown> ? TInput : never;
+/**
+ * Extract output type from a JobDefinition
+ * @example
+ * ```ts
+ * type Output = JobOutput<typeof myJob> // { count: number }
+ * ```
+ */
+type JobOutput<T> = T extends JobDefinition<string, unknown, infer TOutput> ? TOutput : never;
+/**
+ * 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<any>): void;
+}
+/**
+ * Helper type to transform JobDefinition record to JobHandle record
+ */
+type TransformToHandles<TJobs extends Record<string, JobDefinition<string, unknown, unknown>>> = {
+    [K in keyof TJobs]: TJobs[K] extends JobDefinition<infer TName, infer TInput, infer TOutput> ? JobHandle<TName & string, TInput, TOutput> : never;
+};
+/**
+ * Durably instance with type-safe jobs
+ */
+interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknown>> = Record<string, never>> {
+    /**
+     * Registered job handles (type-safe)
+     */
+    readonly jobs: TJobs;
+    /**
+     * Initialize Durably: run migrations and start the worker
+     * This is the recommended way to start Durably.
+     * Equivalent to calling migrate() then start().
+     * @example
+     * ```ts
+     * const durably = createDurably({ dialect }).register({ ... })
+     * await durably.init()
+     * ```
+     */
+    init(): Promise<void>;
+    /**
+     * 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 job definitions and return a new Durably instance with type-safe jobs
+     * @example
+     * ```ts
+     * const durably = createDurably({ dialect })
+     *   .register({
+     *     importCsv: importCsvJob,
+     *     syncUsers: syncUsersJob,
+     *   })
+     * await durably.migrate()
+     * // Usage: durably.jobs.importCsv.trigger({ rows: [...] })
+     * ```
+     */
+    register<TNewJobs extends Record<string, JobDefinition<string, any, any>>>(jobDefs: TNewJobs): Durably<TJobs & TransformToHandles<TNewJobs>>;
+    /**
+     * 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>;
+    /**
+     * 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
+     */
+    deleteRun(runId: string): Promise<void>;
+    /**
+     * Get a run by ID
+     * @example
+     * ```ts
+     * // Untyped (returns Run)
+     * const run = await durably.getRun(runId)
+     *
+     * // Typed (returns custom type)
+     * type MyRun = Run & { payload: { userId: string }; output: { count: number } | null }
+     * const typedRun = await durably.getRun<MyRun>(runId)
+     * ```
+     */
+    getRun<T extends Run = Run>(runId: string): Promise<T | null>;
+    /**
+     * Get runs with optional filtering
+     * @example
+     * ```ts
+     * // Untyped (returns Run[])
+     * const runs = await durably.getRuns({ status: 'completed' })
+     *
+     * // Typed (returns custom type[])
+     * type MyRun = Run & { payload: { userId: string }; output: { count: number } | null }
+     * const typedRuns = await durably.getRuns<MyRun>({ jobName: 'my-job' })
+     * ```
+     */
+    getRuns<T extends Run = Run>(filter?: RunFilter$1): Promise<T[]>;
+    /**
+     * Register a plugin
+     */
+    use(plugin: DurablyPlugin): void;
+    /**
+     * Get a registered job handle by name
+     * Returns undefined if job is not registered
+     */
+    getJob<TName extends string = string>(name: TName): JobHandle<TName, Record<string, unknown>, unknown> | undefined;
+    /**
+     * Subscribe to events for a specific run
+     * Returns a ReadableStream that can be used for SSE
+     */
+    subscribe(runId: string): ReadableStream<DurablyEvent>;
+}
+/**
+ * Create a Durably instance
+ */
+declare function createDurably(options: DurablyOptions): Durably<Record<string, never>>;
+
+/**
+ * Plugin that persists log events to the database
+ */
+declare function withLogPersistence(): DurablyPlugin;
+
+export { type Durably as D, type ErrorHandler as E, type JobDefinition as J, type LogWriteEvent as L, type RunCompleteEvent as R, type StepCompleteEvent as S, type TriggerAndWaitResult as T, type WorkerErrorEvent as W, type DurablyOptions as a, type DurablyPlugin as b, createDurably as c, defineJob as d, type JobInput as e, type JobOutput as f, type DurablyEvent as g, type EventType as h, type RunFailEvent as i, type RunProgressEvent as j, type RunStartEvent as k, type StepFailEvent as l, type StepStartEvent as m, type JobHandle as n, type StepContext as o, type Database as p, type LogsTable as q, type RunsTable as r, type SchemaVersionsTable as s, type StepsTable as t, type Log as u, type Run as v, withLogPersistence as w, type RunFilter$1 as x, type Step as y };