@coji/durably 0.14.0 → 0.15.0

package/dist/{index-CDCdrLgw.d.ts → index-CXH4ozmK.d.ts}

@@ -19,6 +19,17 @@ interface RunTriggerEvent extends BaseEvent {
     input: unknown;
     labels: Record<string, string>;
 }
+/**
+ * Emitted when a trigger was coalesced onto an existing pending run (same concurrency key).
+ */
+interface RunCoalescedEvent extends BaseEvent {
+    type: 'run:coalesced';
+    runId: string;
+    jobName: string;
+    labels: Record<string, string>;
+    skippedInput: unknown;
+    skippedLabels: Record<string, string>;
+}
 /**
  * Run leased event
  */
@@ -173,11 +184,37 @@ interface WorkerErrorEvent extends BaseEvent {
 /**
  * All event types as discriminated union
  */
-type DurablyEvent = RunTriggerEvent | RunLeasedEvent | RunLeaseRenewedEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
+type DurablyEvent = RunTriggerEvent | RunCoalescedEvent | RunLeasedEvent | RunLeaseRenewedEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunDeleteEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | StepCancelEvent | LogWriteEvent | WorkerErrorEvent;
 /**
  * Event types for type-safe event names
  */
 type EventType = DurablyEvent['type'];
+/**
+ * Domain (lifecycle) event names — run state-transition facts.
+ * Derived from DOMAIN_EVENT_TYPE_VALUES so the Set and type stay in sync.
+ */
+declare const DOMAIN_EVENT_TYPE_VALUES: readonly ["run:trigger", "run:coalesced", "run:complete", "run:fail", "run:cancel", "run:delete"];
+type DomainEventType = (typeof DOMAIN_EVENT_TYPE_VALUES)[number];
+/**
+ * Operational / diagnostic event names — execution detail and worker diagnostics.
+ */
+type OperationalEventType = 'run:leased' | 'run:lease-renewed' | 'run:progress' | 'step:start' | 'step:complete' | 'step:fail' | 'step:cancel' | 'log:write' | 'worker:error';
+/**
+ * Domain events: run lifecycle facts (trigger, terminal outcomes, coalesce, delete).
+ */
+type DomainEvent = Extract<DurablyEvent, {
+    type: DomainEventType;
+}>;
+/**
+ * Operational events: leased/progress/steps/logs/worker diagnostics.
+ */
+type OperationalEvent = Extract<DurablyEvent, {
+    type: OperationalEventType;
+}>;
+/**
+ * True when `event` is a domain (lifecycle) event — uses `event.type` only.
+ */
+declare function isDomainEvent(event: DurablyEvent): event is DomainEvent;
 /**
  * Extract event by type
  */
@@ -191,7 +228,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: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'>;
+type AnyEventInput = EventInput<'run:trigger'> | EventInput<'run:coalesced'> | 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
  */
@@ -276,6 +313,11 @@ interface CreateRunInput<TLabels extends Record<string, string> = Record<string,
     idempotencyKey?: string;
     concurrencyKey?: string;
     labels?: TLabels;
+    coalesce?: 'skip';
+}
+interface EnqueueResult<TLabels extends Record<string, string> = Record<string, string>> {
+    run: Run<TLabels>;
+    disposition: Disposition;
 }
 /**
  * Run data returned from storage
@@ -309,7 +351,8 @@ interface Run<TLabels extends Record<string, string> = Record<string, string>> {
  * Run filter options
  */
 interface RunFilter<TLabels extends Record<string, string> = Record<string, string>> {
-    status?: RunStatus;
+    /** Filter by status(es). Pass one status, or an array for multiple (OR). */
+    status?: RunStatus | 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) */
@@ -392,8 +435,8 @@ interface UpdateRunData {
  * Unified storage interface used by the runtime.
  */
 interface Store<TLabels extends Record<string, string> = Record<string, string>> {
-    enqueue(input: CreateRunInput<TLabels>): Promise<Run<TLabels>>;
-    enqueueMany(inputs: CreateRunInput<TLabels>[]): Promise<Run<TLabels>[]>;
+    enqueue(input: CreateRunInput<TLabels>): Promise<EnqueueResult<TLabels>>;
+    enqueueMany(inputs: CreateRunInput<TLabels>[]): Promise<EnqueueResult<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>;
@@ -424,16 +467,17 @@ interface Store<TLabels extends Record<string, string> = Record<string, string>>
 }
 /**
  * A client-safe subset of Run, excluding internal fields like
- * leaseOwner, leaseExpiresAt, idempotencyKey, concurrencyKey, and updatedAt.
+ * leaseOwner, leaseExpiresAt, idempotencyKey, concurrencyKey, and updatedAt,
+ * plus derived `isTerminal` / `isActive` flags from `status`.
  */
-type ClientRun<TLabels extends Record<string, string> = Record<string, string>> = Omit<Run<TLabels>, 'idempotencyKey' | 'concurrencyKey' | 'leaseOwner' | 'leaseExpiresAt' | 'leaseGeneration' | 'updatedAt'>;
+type ClientRun<TLabels extends Record<string, string> = Record<string, string>> = Omit<Run<TLabels>, 'idempotencyKey' | 'concurrencyKey' | 'leaseOwner' | 'leaseExpiresAt' | 'leaseGeneration' | 'updatedAt'> & {
+    isTerminal: boolean;
+    isActive: boolean;
+};
 /**
  * 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>>;
 
 /**
@@ -473,6 +517,10 @@ interface StepContext {
         error(message: string, data?: unknown): void;
     };
 }
+/**
+ * How a trigger was resolved relative to durable storage.
+ */
+type Disposition = 'created' | 'idempotent' | 'coalesced';
 /**
  * Trigger options for trigger() and batchTrigger()
  */
@@ -480,24 +528,41 @@ interface TriggerOptions<TLabels extends Record<string, string> = Record<string,
     idempotencyKey?: string;
     concurrencyKey?: string;
     labels?: TLabels;
+    coalesce?: 'skip';
 }
 /**
- * Options for triggerAndWait() (extends TriggerOptions with wait-specific options)
+ * Options for waiting on a run (live onProgress/onLog only; no replay of past events)
  */
-interface TriggerAndWaitOptions<TLabels extends Record<string, string> = Record<string, string>> extends TriggerOptions<TLabels> {
+interface WaitForRunOptions {
     /** Timeout in milliseconds */
     timeout?: number;
+    /**
+     * Storage polling interval when waiting for a non-terminal run (cross-runtime fallback).
+     * Omitted values inherit the surrounding `createDurably({ pollingIntervalMs })` setting.
+     */
+    pollingIntervalMs?: number;
     /** Called when step.progress() is invoked during execution */
     onProgress?: (progress: ProgressData$1) => void | Promise<void>;
     /** Called when step.log is invoked during execution */
     onLog?: (log: LogData) => void | Promise<void>;
 }
+/**
+ * Options for triggerAndWait() (extends TriggerOptions with wait-specific options)
+ */
+interface TriggerAndWaitOptions<TLabels extends Record<string, string> = Record<string, string>> extends TriggerOptions<TLabels>, WaitForRunOptions {
+}
 /**
  * Typed run with output type
  */
 interface TypedRun<TOutput, TLabels extends Record<string, string> = Record<string, string>> extends Omit<Run<TLabels>, 'output'> {
     output: TOutput | null;
 }
+/**
+ * Result of trigger() / batchTrigger(): the run plus how it was resolved.
+ */
+type TriggerResult<TOutput, TLabels extends Record<string, string> = Record<string, string>> = TypedRun<TOutput, TLabels> & {
+    disposition: Disposition;
+};
 /**
  * Batch trigger input - either just the input or input with options
  */
@@ -511,6 +576,7 @@ type BatchTriggerInput<TInput, TLabels extends Record<string, string> = Record<s
 interface TriggerAndWaitResult<TOutput> {
     id: string;
     output: TOutput;
+    disposition: Disposition;
 }
 /**
  * Job handle returned by defineJob
@@ -520,7 +586,7 @@ interface JobHandle<TName extends string, TInput, TOutput, TLabels extends Recor
     /**
      * Trigger a new run
      */
-    trigger(input: TInput, options?: TriggerOptions<TLabels>): Promise<TypedRun<TOutput, TLabels>>;
+    trigger(input: TInput, options?: TriggerOptions<TLabels>): Promise<TriggerResult<TOutput, TLabels>>;
     /**
      * Trigger a new run and wait for completion
      * Returns the output directly, throws if the run fails
@@ -530,7 +596,7 @@ interface JobHandle<TName extends string, TInput, TOutput, TLabels extends Recor
      * Trigger multiple runs in a batch
      * All inputs are validated before any runs are created
      */
-    batchTrigger(inputs: BatchTriggerInput<TInput, TLabels>[]): Promise<TypedRun<TOutput, TLabels>[]>;
+    batchTrigger(inputs: BatchTriggerInput<TInput, TLabels>[]): Promise<TriggerResult<TOutput, TLabels>[]>;
     /**
      * Get a run by ID
      */
@@ -612,6 +678,10 @@ interface DurablyOptions<TLabels extends Record<string, string> = Record<string,
      */
     singletonKey?: string;
     pollingIntervalMs?: number;
+    /**
+     * Maximum number of runs the worker processes concurrently. Defaults to `1` (one run at a time).
+     */
+    maxConcurrentRuns?: number;
     leaseRenewIntervalMs?: number;
     leaseMs?: number;
     preserveSteps?: boolean;
@@ -639,12 +709,18 @@ interface DurablyOptions<TLabels extends Record<string, string> = Record<string,
      */
     retainRuns?: string;
 }
+/**
+ * A Durably instance with erased job types.
+ * Use when the function only needs access to Durably's runtime capabilities
+ * (trigger, getRun, etc.) without constraining the registered job types.
+ */
+type AnyDurably<TLabels extends Record<string, string> = Record<string, string>> = Durably<Record<string, JobHandle<string, unknown, unknown, TLabels>>, TLabels>;
 /**
  * Plugin interface for extending Durably
  */
 interface DurablyPlugin {
     name: string;
-    install(durably: Durably<any, any>): void;
+    install(durably: AnyDurably): void;
 }
 /**
  * Helper type to transform JobDefinition record to JobHandle record
@@ -799,6 +875,14 @@ interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknow
      * Returns a ReadableStream that can be used for SSE
      */
     subscribe(runId: string): ReadableStream<DurablyEvent>;
+    /**
+     * Wait for an existing run to complete (no new run created).
+     * Resolves only when status is completed; failed, cancelled, or missing run throws.
+     */
+    waitForRun(runId: string, options?: WaitForRunOptions): Promise<Run<TLabels> & {
+        status: 'completed';
+        output: unknown;
+    }>;
 }
 /**
  * Create a Durably instance
@@ -814,4 +898,4 @@ declare function createDurably<TLabels extends Record<string, string> = Record<s
  */
 declare function withLogPersistence(): DurablyPlugin;
 
-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 };
+export { type WorkerErrorEvent as $, type AnyDurably as A, type BatchTriggerInput as B, type ClientRun as C, type Disposition as D, type EnqueueResult as E, type RunTriggerEvent as F, type RunsTable as G, type Step as H, type StepCancelEvent as I, type JobDefinition as J, type StepCompleteEvent as K, type Log as L, type StepContext as M, type StepFailEvent as N, type OperationalEvent as O, type ProgressData$1 as P, type StepStartEvent as Q, type Run as R, type SchemaVersionsTable as S, type StepsTable as T, type Store as U, type TriggerAndWaitOptions as V, type TriggerAndWaitResult as W, type TriggerOptions as X, type TriggerResult as Y, type UpdateRunData as Z, type WaitForRunOptions as _, type RunFilter as a, createDurably as a0, createKyselyStore as a1, defineJob as a2, isDomainEvent as a3, toClientRun as a4, withLogPersistence as a5, type Database as b, type DomainEvent as c, type DomainEventType as d, type Durably as e, type DurablyEvent as f, type DurablyOptions as g, type DurablyPlugin as h, type ErrorHandler as i, type EventType as j, type JobHandle as k, type JobInput as l, type JobOutput as m, type LogData as n, type LogWriteEvent as o, type LogsTable as p, type OperationalEventType as q, type RunCancelEvent as r, type RunCoalescedEvent as s, type RunCompleteEvent as t, type RunDeleteEvent as u, type RunFailEvent as v, type RunLeaseRenewedEvent as w, type RunLeasedEvent as x, type RunProgressEvent as y, type RunStatus as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { R as Run, a as RunFilter, D as Durably } from './index-CDCdrLgw.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-CDCdrLgw.js';
+import { R as Run, a as RunFilter, D as Disposition, A as AnyDurably } from './index-CXH4ozmK.js';
+export { B as BatchTriggerInput, C as ClientRun, b as Database, c as DomainEvent, d as DomainEventType, e as Durably, f as DurablyEvent, g as DurablyOptions, h as DurablyPlugin, E as EnqueueResult, i as ErrorHandler, j as EventType, J as JobDefinition, k as JobHandle, l as JobInput, m as JobOutput, L as Log, n as LogData, o as LogWriteEvent, p as LogsTable, O as OperationalEvent, q as OperationalEventType, P as ProgressData, r as RunCancelEvent, s as RunCoalescedEvent, t as RunCompleteEvent, u as RunDeleteEvent, v as RunFailEvent, w as RunLeaseRenewedEvent, x as RunLeasedEvent, y as RunProgressEvent, z as RunStatus, F as RunTriggerEvent, G as RunsTable, S as SchemaVersionsTable, H as Step, I as StepCancelEvent, K as StepCompleteEvent, M as StepContext, N as StepFailEvent, Q as StepStartEvent, T as StepsTable, U as Store, V as TriggerAndWaitOptions, W as TriggerAndWaitResult, X as TriggerOptions, Y as TriggerResult, Z as UpdateRunData, _ as WaitForRunOptions, $ as WorkerErrorEvent, a0 as createDurably, a1 as createKyselyStore, a2 as defineJob, a3 as isDomainEvent, a4 as toClientRun, a5 as withLogPersistence } from './index-CXH4ozmK.js';
 import 'kysely';
 import 'zod';
 
@@ -55,12 +55,14 @@ interface TriggerRequest<TLabels extends Record<string, string> = Record<string,
     idempotencyKey?: string;
     concurrencyKey?: string;
     labels?: TLabels;
+    coalesce?: 'skip';
 }
 /**
  * Response for trigger endpoint
  */
 interface TriggerResponse {
     runId: string;
+    disposition: Disposition;
 }
 /**
  * Auth middleware configuration.
@@ -125,6 +127,6 @@ interface CreateDurablyHandlerOptions<TContext = undefined, TLabels extends Reco
  * Create HTTP handlers for Durably
  * Uses Web Standard Request/Response for framework-agnostic usage
  */
-declare function createDurablyHandler<TContext = undefined, TLabels extends Record<string, string> = Record<string, string>>(durably: Durably<any, TLabels>, options?: CreateDurablyHandlerOptions<TContext, TLabels>): DurablyHandler;
+declare function createDurablyHandler<TContext = undefined, TLabels extends Record<string, string> = Record<string, string>>(durably: AnyDurably<TLabels>, options?: CreateDurablyHandlerOptions<TContext, TLabels>): DurablyHandler;
 
-export { type AuthConfig, CancelledError, ConflictError, type CreateDurablyHandlerOptions, Durably, DurablyError, type DurablyHandler, LeaseLostError, NotFoundError, Run, RunFilter, type RunOperation, type RunsSubscribeFilter, type TriggerRequest, type TriggerResponse, ValidationError, createDurablyHandler };
+export { AnyDurably, type AuthConfig, CancelledError, ConflictError, type CreateDurablyHandlerOptions, Disposition, DurablyError, type DurablyHandler, LeaseLostError, NotFoundError, Run, RunFilter, type RunOperation, type RunsSubscribeFilter, type TriggerRequest, type TriggerResponse, ValidationError, createDurablyHandler };