@coji/durably 0.11.0 → 0.13.0

package/dist/{index-fppJjkF-.d.ts → index-DWsJlgyh.d.ts}

@@ -20,13 +20,23 @@ interface RunTriggerEvent extends BaseEvent {
     labels: Record<string, string>;
 }
 /**
- * Run start event
+ * Run leased event
  */
-interface RunStartEvent extends BaseEvent {
-    type: 'run:start';
+interface RunLeasedEvent extends BaseEvent {
+    type: 'run:leased';
     runId: string;
     jobName: string;
     input: unknown;
+    leaseOwner: string;
+    leaseExpiresAt: string;
+    labels: Record<string, string>;
+}
+interface RunLeaseRenewedEvent extends BaseEvent {
+    type: 'run:lease-renewed';
+    runId: string;
+    jobName: string;
+    leaseOwner: string;
+    leaseExpiresAt: string;
     labels: Record<string, string>;
 }
 /**
@@ -69,19 +79,10 @@ interface RunDeleteEvent extends BaseEvent {
     jobName: string;
     labels: Record<string, string>;
 }
-/**
- * Run retry event (emitted when a failed run is retried)
- */
-interface RunRetryEvent extends BaseEvent {
-    type: 'run:retry';
-    runId: string;
-    jobName: string;
-    labels: Record<string, string>;
-}
 /**
  * Progress data reported by step.progress()
  */
-interface ProgressData {
+interface ProgressData$1 {
     current: number;
     total?: number;
     message?: string;
@@ -93,7 +94,7 @@ interface RunProgressEvent extends BaseEvent {
     type: 'run:progress';
     runId: string;
     jobName: string;
-    progress: ProgressData;
+    progress: ProgressData$1;
     labels: Record<string, string>;
 }
 /**
@@ -172,7 +173,7 @@ interface WorkerErrorEvent extends BaseEvent {
 /**
  * All event types as discriminated union
  */
-type DurablyEvent = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunRetryEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
+type DurablyEvent = RunTriggerEvent | RunLeasedEvent | RunLeaseRenewedEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
 /**
  * Event types for type-safe event names
  */
@@ -190,7 +191,7 @@ type EventInput<T extends EventType> = Omit<EventByType<T>, 'timestamp' | 'seque
 /**
  * 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:delete'> | EventInput<'run:retry'> | EventInput<'run:progress'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'step:cancel'> | EventInput<'log:write'> | EventInput<'worker:error'>;
+type AnyEventInput = EventInput<'run:trigger'> | EventInput<'run:leased'> | EventInput<'run:lease-renewed'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'run:cancel'> | EventInput<'run:delete'> | EventInput<'run:progress'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'step:cancel'> | EventInput<'log:write'> | EventInput<'worker:error'>;
 /**
  * Event listener function
  */
@@ -211,7 +212,7 @@ interface RunsTable {
     id: string;
     job_name: string;
     input: string;
-    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    status: 'pending' | 'leased' | 'completed' | 'failed' | 'cancelled';
     idempotency_key: string | null;
     concurrency_key: string | null;
     current_step_index: number;
@@ -219,7 +220,9 @@ interface RunsTable {
     output: string | null;
     error: string | null;
     labels: string;
-    heartbeat_at: string;
+    lease_owner: string | null;
+    lease_expires_at: string | null;
+    lease_generation: number;
     started_at: string | null;
     completed_at: string | null;
     created_at: string;
@@ -245,17 +248,24 @@ interface LogsTable {
     data: string | null;
     created_at: string;
 }
+interface RunLabelsTable {
+    run_id: string;
+    key: string;
+    value: string;
+}
 interface SchemaVersionsTable {
     version: number;
     applied_at: string;
 }
 interface Database {
     durably_runs: RunsTable;
+    durably_run_labels: RunLabelsTable;
     durably_steps: StepsTable;
     durably_logs: LogsTable;
     durably_schema_versions: SchemaVersionsTable;
 }
 
+type RunStatus = 'pending' | 'leased' | 'completed' | 'failed' | 'cancelled';
 /**
  * Run data for creating a new run
  */
@@ -273,7 +283,7 @@ interface Run<TLabels extends Record<string, string> = Record<string, string>> {
     id: string;
     jobName: string;
     input: unknown;
-    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    status: RunStatus;
     idempotencyKey: string | null;
     concurrencyKey: string | null;
     currentStepIndex: number;
@@ -286,34 +296,19 @@ interface Run<TLabels extends Record<string, string> = Record<string, string>> {
     output: unknown | null;
     error: string | null;
     labels: TLabels;
-    heartbeatAt: string;
+    leaseOwner: string | null;
+    leaseExpiresAt: string | null;
+    leaseGeneration: number;
     startedAt: string | null;
     completedAt: string | null;
     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;
-    startedAt?: string;
-    completedAt?: string;
-}
 /**
  * Run filter options
  */
 interface RunFilter<TLabels extends Record<string, string> = Record<string, string>> {
-    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    status?: RunStatus;
     /** Filter by job name(s). Pass a string for one, or an array for multiple (OR). */
     jobName?: string | string[];
     /** Filter by labels (all specified labels must match) */
@@ -326,10 +321,9 @@ interface RunFilter<TLabels extends Record<string, string> = Record<string, stri
     offset?: number;
 }
 /**
- * Step data for creating a new step
+ * Step data for persisting a step checkpoint
  */
 interface CreateStepInput {
-    runId: string;
     name: string;
     index: number;
     status: 'completed' | 'failed' | 'cancelled';
@@ -373,32 +367,73 @@ interface Log {
     data: unknown | null;
     createdAt: string;
 }
+interface ProgressData {
+    current: number;
+    total?: number;
+    message?: string;
+}
+type DatabaseBackend = 'generic' | 'postgres';
 /**
- * A client-safe subset of Run, excluding internal fields like
- * heartbeatAt, idempotencyKey, concurrencyKey, and updatedAt.
- */
-type ClientRun<TLabels extends Record<string, string> = Record<string, string>> = Omit<Run<TLabels>, 'idempotencyKey' | 'concurrencyKey' | 'heartbeatAt' | 'updatedAt'>;
-/**
- * Project a full Run to a ClientRun by stripping internal fields.
+ * Data for updating a run
  */
-declare function toClientRun<TLabels extends Record<string, string> = Record<string, string>>(run: Run<TLabels>): ClientRun<TLabels>;
+interface UpdateRunData {
+    status?: RunStatus;
+    currentStepIndex?: number;
+    progress?: ProgressData | null;
+    output?: unknown;
+    error?: string | null;
+    leaseOwner?: string | null;
+    leaseExpiresAt?: string | null;
+    startedAt?: string;
+    completedAt?: string;
+}
 /**
- * Storage interface for database operations
+ * Unified storage interface used by the runtime.
  */
-interface Storage {
-    createRun(input: CreateRunInput): Promise<Run>;
-    batchCreateRuns(inputs: CreateRunInput[]): Promise<Run[]>;
-    updateRun(runId: string, data: UpdateRunInput): Promise<void>;
+interface Store<TLabels extends Record<string, string> = Record<string, string>> {
+    enqueue(input: CreateRunInput<TLabels>): Promise<Run<TLabels>>;
+    enqueueMany(inputs: CreateRunInput<TLabels>[]): Promise<Run<TLabels>[]>;
+    getRun<T extends Run<TLabels> = Run<TLabels>>(runId: string): Promise<T | null>;
+    getRuns<T extends Run<TLabels> = Run<TLabels>>(filter?: RunFilter<TLabels>): Promise<T[]>;
+    updateRun(runId: string, data: UpdateRunData): Promise<void>;
     deleteRun(runId: string): Promise<void>;
-    getRun<T extends Run = Run>(runId: string): Promise<T | null>;
-    getRuns<T extends Run = Run>(filter?: RunFilter): Promise<T[]>;
-    claimNextPendingRun(excludeConcurrencyKeys: string[]): Promise<Run | null>;
-    createStep(input: CreateStepInput): Promise<Step>;
+    claimNext(workerId: string, now: string, leaseMs: number): Promise<Run<TLabels> | null>;
+    renewLease(runId: string, leaseGeneration: number, now: string, leaseMs: number): Promise<boolean>;
+    releaseExpiredLeases(now: string): Promise<number>;
+    completeRun(runId: string, leaseGeneration: number, output: unknown, completedAt: string): Promise<boolean>;
+    failRun(runId: string, leaseGeneration: number, error: string, completedAt: string): Promise<boolean>;
+    cancelRun(runId: string, now: string): Promise<boolean>;
+    /**
+     * Atomically persist a step checkpoint, guarded by lease generation.
+     * Inserts the step record and advances currentStepIndex (for completed
+     * steps only) in a single transaction. Returns null if the generation
+     * does not match (lease was lost).
+     */
+    persistStep(runId: string, leaseGeneration: number, input: CreateStepInput): Promise<Step | null>;
     getSteps(runId: string): Promise<Step[]>;
     getCompletedStep(runId: string, name: string): Promise<Step | null>;
+    deleteSteps(runId: string): Promise<void>;
+    updateProgress(runId: string, leaseGeneration: number, progress: ProgressData | null): Promise<void>;
+    purgeRuns(options: {
+        olderThan: string;
+        limit?: number;
+    }): Promise<number>;
     createLog(input: CreateLogInput): Promise<Log>;
     getLogs(runId: string): Promise<Log[]>;
 }
+/**
+ * A client-safe subset of Run, excluding internal fields like
+ * leaseOwner, leaseExpiresAt, idempotencyKey, concurrencyKey, and updatedAt.
+ */
+type ClientRun<TLabels extends Record<string, string> = Record<string, string>> = Omit<Run<TLabels>, 'idempotencyKey' | 'concurrencyKey' | 'leaseOwner' | 'leaseExpiresAt' | 'leaseGeneration' | 'updatedAt'>;
+/**
+ * Project a full Run to a ClientRun by stripping internal fields.
+ */
+declare function toClientRun<TLabels extends Record<string, string> = Record<string, string>>(run: Run<TLabels>): ClientRun<TLabels>;
+/**
+ * Create a Kysely-based Store implementation
+ */
+declare function createKyselyStore(db: Kysely<Database>, backend?: DatabaseBackend): Store<Record<string, string>>;
 
 /**
  * Step context passed to the job function
@@ -408,6 +443,18 @@ interface StepContext {
      * The ID of the current run
      */
     readonly runId: string;
+    /**
+     * AbortSignal for cooperative cancellation or lease-loss handling.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Whether this execution should stop cooperatively.
+     */
+    isAborted(): boolean;
+    /**
+     * Throw if execution has been cancelled or lease ownership was lost.
+     */
+    throwIfAborted(): void;
     /**
      * Execute a step with automatic persistence and replay
      */
@@ -440,7 +487,7 @@ interface TriggerAndWaitOptions<TLabels extends Record<string, string> = Record<
     /** Timeout in milliseconds */
     timeout?: number;
     /** Called when step.progress() is invoked during execution */
-    onProgress?: (progress: ProgressData) => void | Promise<void>;
+    onProgress?: (progress: ProgressData$1) => void | Promise<void>;
     /** Called when step.log is invoked during execution */
     onLog?: (log: LogData) => void | Promise<void>;
 }
@@ -558,9 +605,15 @@ declare function defineJob<TName extends string, TInputSchema extends z.ZodType,
  */
 interface DurablyOptions<TLabels extends Record<string, string> = Record<string, string>, TJobs extends Record<string, JobDefinition<string, any, any>> = Record<string, never>> {
     dialect: Dialect;
-    pollingInterval?: number;
-    heartbeatInterval?: number;
-    staleThreshold?: number;
+    /**
+     * Browser-local singleton key used to detect multiple runtimes against the same local database in one tab.
+     * When omitted, Durably will use browser-local dialect metadata if available.
+     */
+    singletonKey?: string;
+    pollingIntervalMs?: number;
+    leaseRenewIntervalMs?: number;
+    leaseMs?: number;
+    preserveSteps?: boolean;
     /**
      * Zod schema for labels. When provided:
      * - Labels are type-checked at compile time
@@ -578,6 +631,12 @@ interface DurablyOptions<TLabels extends Record<string, string> = Record<string,
      * ```
      */
     jobs?: TJobs;
+    /**
+     * Auto-delete terminal runs older than the specified duration.
+     * Only runs in terminal states (completed, failed, cancelled) are purged.
+     * @example '30d' (30 days), '24h' (24 hours), '60m' (60 minutes)
+     */
+    retainRuns?: string;
 }
 /**
  * Plugin interface for extending Durably
@@ -624,7 +683,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
     /**
      * Storage layer for database operations
      */
-    readonly storage: Storage;
+    readonly storage: Store<TLabels>;
     /**
      * Register an event listener
      * @returns Unsubscribe function
@@ -652,19 +711,34 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * ```
      */
     register<TNewJobs extends Record<string, JobDefinition<string, any, any>>>(jobDefs: TNewJobs): Durably<TJobs & TransformToHandles<TNewJobs, TLabels>, TLabels>;
+    /**
+     * Process a single claimable run.
+     */
+    processOne(options?: {
+        workerId?: string;
+    }): Promise<boolean>;
+    /**
+     * Process runs until the queue appears idle.
+     */
+    processUntilIdle(options?: {
+        workerId?: string;
+        maxRuns?: number;
+    }): Promise<number>;
     /**
      * Start the worker polling loop
      */
-    start(): void;
+    start(options?: {
+        workerId?: string;
+    }): 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
+     * Create a fresh run from a completed, failed, or cancelled run
+     * @throws Error if run is pending, running, or does not exist
      */
-    retry(runId: string): Promise<void>;
+    retrigger(runId: string): Promise<Run<TLabels>>;
     /**
      * Cancel a pending or running run
      * @throws Error if run is already completed, failed, or cancelled
@@ -675,6 +749,15 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * @throws Error if run is pending or running, or does not exist
      */
     deleteRun(runId: string): Promise<void>;
+    /**
+     * Delete terminal runs older than the specified cutoff.
+     * Only runs in terminal states (completed, failed, cancelled) are purged.
+     * @returns Number of deleted runs
+     */
+    purgeRuns(options: {
+        olderThan: Date;
+        limit?: number;
+    }): Promise<number>;
     /**
      * Get a run by ID
      * @example
@@ -729,4 +812,4 @@ declare function createDurably<TLabels extends Record<string, string> = Record<s
  */
 declare function withLogPersistence(): DurablyPlugin;
 
-export { type StepStartEvent as A, type BatchTriggerInput as B, type ClientRun as C, type Durably as D, type ErrorHandler as E, type StepsTable as F, type TriggerAndWaitResult as G, type TriggerOptions as H, createDurably as I, type JobDefinition as J, defineJob as K, type Log as L, toClientRun as M, withLogPersistence as N, type ProgressData as P, type Run as R, type SchemaVersionsTable as S, type TriggerAndWaitOptions as T, type WorkerErrorEvent as W, type RunFilter as a, type Database as b, type DurablyEvent as c, type DurablyOptions as d, type DurablyPlugin as e, type EventType as f, type JobHandle as g, type JobInput as h, type JobOutput as i, type LogData as j, type LogWriteEvent as k, type LogsTable as l, type RunCancelEvent as m, type RunCompleteEvent as n, type RunDeleteEvent as o, type RunFailEvent as p, type RunProgressEvent as q, type RunRetryEvent as r, type RunStartEvent as s, type RunTriggerEvent as t, type RunsTable as u, type Step as v, type StepCancelEvent as w, type StepCompleteEvent as x, type StepContext as y, type StepFailEvent as z };
+export { type StepFailEvent as A, type BatchTriggerInput as B, type ClientRun as C, type Durably as D, type ErrorHandler as E, type StepStartEvent as F, type StepsTable as G, type Store as H, type TriggerAndWaitResult as I, type JobDefinition as J, type TriggerOptions as K, type Log as L, createDurably as M, createKyselyStore as N, defineJob as O, type ProgressData$1 as P, toClientRun as Q, type Run as R, type SchemaVersionsTable as S, type TriggerAndWaitOptions as T, type UpdateRunData as U, withLogPersistence as V, type WorkerErrorEvent as W, type RunFilter as a, type Database as b, type DurablyEvent as c, type DurablyOptions as d, type DurablyPlugin as e, type EventType as f, type JobHandle as g, type JobInput as h, type JobOutput as i, type LogData as j, type LogWriteEvent as k, type LogsTable as l, type RunCancelEvent as m, type RunCompleteEvent as n, type RunDeleteEvent as o, type RunFailEvent as p, type RunLeaseRenewedEvent as q, type RunLeasedEvent as r, type RunProgressEvent as s, type RunStatus as t, type RunTriggerEvent as u, type RunsTable as v, type Step as w, type StepCancelEvent as x, type StepCompleteEvent as y, type StepContext as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as Run, a as RunFilter, D as Durably } from './index-fppJjkF-.js';
-export { B as BatchTriggerInput, C as ClientRun, b as Database, c as DurablyEvent, d as DurablyOptions, e as DurablyPlugin, E as ErrorHandler, f as EventType, J as JobDefinition, g as JobHandle, h as JobInput, i as JobOutput, L as Log, j as LogData, k as LogWriteEvent, l as LogsTable, P as ProgressData, m as RunCancelEvent, n as RunCompleteEvent, o as RunDeleteEvent, p as RunFailEvent, q as RunProgressEvent, r as RunRetryEvent, s as RunStartEvent, t as RunTriggerEvent, u as RunsTable, S as SchemaVersionsTable, v as Step, w as StepCancelEvent, x as StepCompleteEvent, y as StepContext, z as StepFailEvent, A as StepStartEvent, F as StepsTable, T as TriggerAndWaitOptions, G as TriggerAndWaitResult, H as TriggerOptions, W as WorkerErrorEvent, I as createDurably, K as defineJob, M as toClientRun, N as withLogPersistence } from './index-fppJjkF-.js';
+import { R as Run, a as RunFilter, D as Durably } from './index-DWsJlgyh.js';
+export { B as BatchTriggerInput, C as ClientRun, b as Database, c as DurablyEvent, d as DurablyOptions, e as DurablyPlugin, E as ErrorHandler, f as EventType, J as JobDefinition, g as JobHandle, h as JobInput, i as JobOutput, L as Log, j as LogData, k as LogWriteEvent, l as LogsTable, P as ProgressData, m as RunCancelEvent, n as RunCompleteEvent, o as RunDeleteEvent, p as RunFailEvent, q as RunLeaseRenewedEvent, r as RunLeasedEvent, s as RunProgressEvent, t as RunStatus, u as RunTriggerEvent, v as RunsTable, S as SchemaVersionsTable, w as Step, x as StepCancelEvent, y as StepCompleteEvent, z as StepContext, A as StepFailEvent, F as StepStartEvent, G as StepsTable, H as Store, T as TriggerAndWaitOptions, I as TriggerAndWaitResult, K as TriggerOptions, U as UpdateRunData, W as WorkerErrorEvent, M as createDurably, N as createKyselyStore, O as defineJob, Q as toClientRun, V as withLogPersistence } from './index-DWsJlgyh.js';
 import 'kysely';
 import 'zod';
 
@@ -11,11 +11,17 @@ import 'zod';
 declare class CancelledError extends Error {
     constructor(runId: string);
 }
+/**
+ * Error thrown when a worker loses lease ownership during execution.
+ */
+declare class LeaseLostError extends Error {
+    constructor(runId: string);
+}
 
 /**
  * Run operation types for onRunAccess
  */
-type RunOperation = 'read' | 'subscribe' | 'steps' | 'retry' | 'cancel' | 'delete';
+type RunOperation = 'read' | 'subscribe' | 'steps' | 'retrigger' | 'cancel' | 'delete';
 /**
  * Subscription filter — only fields that SSE subscriptions actually support.
  */
@@ -70,7 +76,7 @@ interface DurablyHandler {
      * - GET  {basePath}/run?runId=xxx - Get single run
      * - GET  {basePath}/steps?runId=xxx - Get steps
      * - POST {basePath}/trigger - Trigger a job
-     * - POST {basePath}/retry?runId=xxx - Retry a failed run
+     * - POST {basePath}/retrigger?runId=xxx - Create a fresh run from a terminal run
      * - POST {basePath}/cancel?runId=xxx - Cancel a run
      * - DELETE {basePath}/run?runId=xxx - Delete a run
      */
@@ -101,4 +107,4 @@ interface CreateDurablyHandlerOptions<TContext = undefined, TLabels extends Reco
  */
 declare function createDurablyHandler<TContext = undefined, TLabels extends Record<string, string> = Record<string, string>>(durably: Durably<any, TLabels>, options?: CreateDurablyHandlerOptions<TContext, TLabels>): DurablyHandler;
 
-export { type AuthConfig, CancelledError, type CreateDurablyHandlerOptions, Durably, type DurablyHandler, Run, RunFilter, type RunOperation, type RunsSubscribeFilter, type TriggerRequest, type TriggerResponse, createDurablyHandler };
+export { type AuthConfig, CancelledError, type CreateDurablyHandlerOptions, Durably, type DurablyHandler, LeaseLostError, Run, RunFilter, type RunOperation, type RunsSubscribeFilter, type TriggerRequest, type TriggerResponse, createDurablyHandler };