@coji/durably 0.8.0 → 0.9.0

package/README.md

@@ -23,7 +23,7 @@ import { z } from 'zod'
 const myJob = defineJob({
   name: 'my-job',
   input: z.object({ id: z.string() }),
-  run: async (step, payload) => {
+  run: async (step, input) => {
     await step.run('step-1', async () => {
       /* ... */
     })

package/dist/{index-4aPZWn8r.d.ts → index-BjlCb0gP.d.ts}

@@ -1,4 +1,4 @@
-import { Dialect, Kysely } from 'kysely';
+import { Kysely, Dialect } from 'kysely';
 import { z } from 'zod';
 
 /**
@@ -16,7 +16,8 @@ interface RunTriggerEvent extends BaseEvent {
     type: 'run:trigger';
     runId: string;
     jobName: string;
-    payload: unknown;
+    input: unknown;
+    labels: Record<string, string>;
 }
 /**
  * Run start event
@@ -25,7 +26,8 @@ interface RunStartEvent extends BaseEvent {
     type: 'run:start';
     runId: string;
     jobName: string;
-    payload: unknown;
+    input: unknown;
+    labels: Record<string, string>;
 }
 /**
  * Run complete event
@@ -36,6 +38,7 @@ interface RunCompleteEvent extends BaseEvent {
     jobName: string;
     output: unknown;
     duration: number;
+    labels: Record<string, string>;
 }
 /**
  * Run fail event
@@ -46,6 +49,7 @@ interface RunFailEvent extends BaseEvent {
     jobName: string;
     error: string;
     failedStepName: string;
+    labels: Record<string, string>;
 }
 /**
  * Run cancel event
@@ -54,6 +58,16 @@ interface RunCancelEvent extends BaseEvent {
     type: 'run:cancel';
     runId: string;
     jobName: string;
+    labels: Record<string, string>;
+}
+/**
+ * Run delete event (emitted when a run is deleted)
+ */
+interface RunDeleteEvent extends BaseEvent {
+    type: 'run:delete';
+    runId: string;
+    jobName: string;
+    labels: Record<string, string>;
 }
 /**
  * Run retry event (emitted when a failed run is retried)
@@ -62,6 +76,7 @@ interface RunRetryEvent extends BaseEvent {
     type: 'run:retry';
     runId: string;
     jobName: string;
+    labels: Record<string, string>;
 }
 /**
  * Run progress event
@@ -75,6 +90,7 @@ interface RunProgressEvent extends BaseEvent {
         total?: number;
         message?: string;
     };
+    labels: Record<string, string>;
 }
 /**
  * Step start event
@@ -85,6 +101,7 @@ interface StepStartEvent extends BaseEvent {
     jobName: string;
     stepName: string;
     stepIndex: number;
+    labels: Record<string, string>;
 }
 /**
  * Step complete event
@@ -97,6 +114,7 @@ interface StepCompleteEvent extends BaseEvent {
     stepIndex: number;
     output: unknown;
     duration: number;
+    labels: Record<string, string>;
 }
 /**
  * Step fail event
@@ -108,6 +126,15 @@ interface StepFailEvent extends BaseEvent {
     stepName: string;
     stepIndex: number;
     error: string;
+    labels: Record<string, string>;
+}
+interface StepCancelEvent extends BaseEvent {
+    type: 'step:cancel';
+    runId: string;
+    jobName: string;
+    stepName: string;
+    stepIndex: number;
+    labels: Record<string, string>;
 }
 /**
  * Log write event
@@ -115,6 +142,8 @@ interface StepFailEvent extends BaseEvent {
 interface LogWriteEvent extends BaseEvent {
     type: 'log:write';
     runId: string;
+    jobName: string;
+    labels: Record<string, string>;
     stepName: string | null;
     level: 'info' | 'warn' | 'error';
     message: string;
@@ -132,7 +161,7 @@ interface WorkerErrorEvent extends BaseEvent {
 /**
  * All event types as discriminated union
  */
-type DurablyEvent = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunRetryEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | LogWriteEvent | WorkerErrorEvent;
+type DurablyEvent = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunRetryEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
 /**
  * Event types for type-safe event names
  */
@@ -150,7 +179,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:retry'> | EventInput<'run:progress'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'log:write'> | EventInput<'worker:error'>;
+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'>;
 /**
  * Event listener function
  */
@@ -170,7 +199,7 @@ type ErrorHandler = (error: Error, event: DurablyEvent) => void;
 interface RunsTable {
     id: string;
     job_name: string;
-    payload: string;
+    input: string;
     status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
     idempotency_key: string | null;
     concurrency_key: string | null;
@@ -178,7 +207,10 @@ interface RunsTable {
     progress: string | null;
     output: string | null;
     error: string | null;
+    labels: string;
     heartbeat_at: string;
+    started_at: string | null;
+    completed_at: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -187,7 +219,7 @@ interface StepsTable {
     run_id: string;
     name: string;
     index: number;
-    status: 'completed' | 'failed';
+    status: 'completed' | 'failed' | 'cancelled';
     output: string | null;
     error: string | null;
     started_at: string;
@@ -218,9 +250,10 @@ interface Database {
  */
 interface CreateRunInput {
     jobName: string;
-    payload: unknown;
+    input: unknown;
     idempotencyKey?: string;
     concurrencyKey?: string;
+    labels?: Record<string, string>;
 }
 /**
  * Run data returned from storage
@@ -228,7 +261,7 @@ interface CreateRunInput {
 interface Run {
     id: string;
     jobName: string;
-    payload: unknown;
+    input: unknown;
     status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
     idempotencyKey: string | null;
     concurrencyKey: string | null;
@@ -241,7 +274,10 @@ interface Run {
     } | null;
     output: unknown | null;
     error: string | null;
+    labels: Record<string, string>;
     heartbeatAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -259,6 +295,8 @@ interface UpdateRunInput {
     output?: unknown;
     error?: string | null;
     heartbeatAt?: string;
+    startedAt?: string;
+    completedAt?: string;
 }
 /**
  * Run filter options
@@ -266,6 +304,7 @@ interface UpdateRunInput {
 interface RunFilter$1 {
     status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
     jobName?: string;
+    labels?: Record<string, string>;
     /** Maximum number of runs to return */
     limit?: number;
     /** Number of runs to skip (for pagination) */
@@ -278,7 +317,7 @@ interface CreateStepInput {
     runId: string;
     name: string;
     index: number;
-    status: 'completed' | 'failed';
+    status: 'completed' | 'failed' | 'cancelled';
     output?: unknown;
     error?: string;
     startedAt: string;
@@ -291,7 +330,7 @@ interface Step {
     runId: string;
     name: string;
     index: number;
-    status: 'completed' | 'failed';
+    status: 'completed' | 'failed' | 'cancelled';
     output: unknown | null;
     error: string | null;
     startedAt: string;
@@ -319,6 +358,15 @@ interface Log {
     data: unknown | null;
     createdAt: string;
 }
+/**
+ * A client-safe subset of Run, excluding internal fields like
+ * heartbeatAt, idempotencyKey, concurrencyKey, and updatedAt.
+ */
+type ClientRun = Omit<Run, 'idempotencyKey' | 'concurrencyKey' | 'heartbeatAt' | 'updatedAt'>;
+/**
+ * Project a full Run to a ClientRun by stripping internal fields.
+ */
+declare function toClientRun(run: Run): ClientRun;
 /**
  * Storage interface for database operations
  */
@@ -329,7 +377,7 @@ interface Storage {
     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>;
+    claimNextPendingRun(excludeConcurrencyKeys: string[]): Promise<Run | null>;
     createStep(input: CreateStepInput): Promise<Step>;
     getSteps(runId: string): Promise<Step[]>;
     getCompletedStep(runId: string, name: string): Promise<Step | null>;
@@ -348,7 +396,7 @@ interface StepContext {
     /**
      * Execute a step with automatic persistence and replay
      */
-    run<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    run<T>(name: string, fn: (signal: AbortSignal) => T | Promise<T>): Promise<T>;
     /**
      * Report progress for the current run
      */
@@ -368,6 +416,7 @@ interface StepContext {
 interface TriggerOptions {
     idempotencyKey?: string;
     concurrencyKey?: string;
+    labels?: Record<string, string>;
     /** Timeout in milliseconds for triggerAndWait() */
     timeout?: number;
 }
@@ -377,6 +426,7 @@ interface TriggerOptions {
 interface RunFilter {
     status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
     jobName?: string;
+    labels?: Record<string, string>;
     /** Maximum number of runs to return */
     limit?: number;
     /** Number of runs to skip (for pagination) */
@@ -434,7 +484,7 @@ interface JobHandle<TName extends string, TInput, TOutput> {
 /**
  * Job run function type
  */
-type JobRunFunction<TInput, TOutput> = (step: StepContext, payload: TInput) => Promise<TOutput>;
+type JobRunFunction<TInput, TOutput> = (step: StepContext, input: 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()
@@ -482,8 +532,8 @@ interface DefineJobConfig<TName extends string, TInputSchema extends z.ZodType,
  *   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))
+ *   run: async (step, input) => {
+ *     const users = await step.run('fetch-users', () => fetchUsers(input.orgId))
  *     return { syncedCount: users.length }
  *   },
  * })
@@ -604,7 +654,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * const run = await durably.getRun(runId)
      *
      * // Typed (returns custom type)
-     * type MyRun = Run & { payload: { userId: string }; output: { count: number } | null }
+     * type MyRun = Run & { input: { userId: string }; output: { count: number } | null }
      * const typedRun = await durably.getRun<MyRun>(runId)
      * ```
      */
@@ -617,7 +667,7 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * const runs = await durably.getRuns({ status: 'completed' })
      *
      * // Typed (returns custom type[])
-     * type MyRun = Run & { payload: { userId: string }; output: { count: number } | null }
+     * type MyRun = Run & { input: { userId: string }; output: { count: number } | null }
      * const typedRuns = await durably.getRuns<MyRun>({ jobName: 'my-job' })
      * ```
      */
@@ -647,4 +697,4 @@ declare function createDurably(options: DurablyOptions): Durably<Record<string,
  */
 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 };
+export { type StepsTable as A, createDurably as B, type ClientRun as C, type Durably as D, type ErrorHandler as E, defineJob as F, toClientRun as G, withLogPersistence as H, type JobDefinition as J, type Log as L, type Run as R, type SchemaVersionsTable as S, type TriggerAndWaitResult as T, type WorkerErrorEvent as W, type Database as a, type DurablyEvent as b, type DurablyOptions as c, type DurablyPlugin as d, type EventType as e, type JobHandle as f, type JobInput as g, type JobOutput as h, type LogWriteEvent as i, type LogsTable as j, type RunCancelEvent as k, type RunCompleteEvent as l, type RunDeleteEvent as m, type RunFailEvent as n, type RunFilter$1 as o, type RunProgressEvent as p, type RunRetryEvent as q, type RunStartEvent as r, type RunTriggerEvent as s, type RunsTable as t, type Step as u, type StepCancelEvent as v, type StepCompleteEvent as w, type StepContext as x, type StepFailEvent as y, type StepStartEvent as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { D as Durably } from './index-4aPZWn8r.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-4aPZWn8r.js';
+import { D as Durably } from './index-BjlCb0gP.js';
+export { C as ClientRun, a as Database, b as DurablyEvent, c as DurablyOptions, d as DurablyPlugin, E as ErrorHandler, e as EventType, J as JobDefinition, f as JobHandle, g as JobInput, h as JobOutput, L as Log, i as LogWriteEvent, j as LogsTable, R as Run, k as RunCancelEvent, l as RunCompleteEvent, m as RunDeleteEvent, n as RunFailEvent, o as RunFilter, p as RunProgressEvent, q as RunRetryEvent, r as RunStartEvent, s as RunTriggerEvent, t as RunsTable, S as SchemaVersionsTable, u as Step, v as StepCancelEvent, w as StepCompleteEvent, x as StepContext, y as StepFailEvent, z as StepStartEvent, A as StepsTable, T as TriggerAndWaitResult, W as WorkerErrorEvent, B as createDurably, F as defineJob, G as toClientRun, H as withLogPersistence } from './index-BjlCb0gP.js';
 import 'kysely';
 import 'zod';
 
@@ -20,6 +20,7 @@ interface TriggerRequest {
     input: Record<string, unknown>;
     idempotencyKey?: string;
     concurrencyKey?: string;
+    labels?: Record<string, string>;
 }
 /**
  * Response for trigger endpoint