@coji/durably 0.14.0 → 0.15.0

package/dist/plugins/index.d.ts

@@ -1,3 +1,3 @@
-export { V as withLogPersistence } from '../index-CDCdrLgw.js';
+export { a5 as withLogPersistence } from '../index-CXH4ozmK.js';
 import 'kysely';
 import 'zod';

package/docs/llms.md

@@ -60,7 +60,8 @@ const dialect = new LibsqlDialect({ client })
 // Option 1: With jobs (1-step initialization, returns typed instance)
 const durably = createDurably({
   dialect,
-  pollingIntervalMs: 1000, // Job polling interval (ms)
+  pollingIntervalMs: 1000, // Delay before polling again when idle (ms)
+  maxConcurrentRuns: 1, // Concurrent runs processed by the worker (default: 1)
   leaseRenewIntervalMs: 5000, // Lease renewal interval (ms)
   leaseMs: 30000, // Lease duration (ms); expired leases are reclaimed
   preserveSteps: false, // Set to true to keep step output data after terminal state (default: false = cleanup)
@@ -123,6 +124,7 @@ await durably.init()
 // Basic trigger (fire and forget)
 const run = await syncUsers.trigger({ orgId: 'org_123' })
 console.log(run.id, run.status) // "pending"
+console.log(run.disposition) // "created"
 
 // Wait for completion
 const result = await syncUsers.triggerAndWait(
@@ -130,15 +132,27 @@ const result = await syncUsers.triggerAndWait(
   { timeout: 5000 },
 )
 console.log(result.output.syncedCount)
+console.log(result.disposition) // "created"
 
 // With idempotency key (prevents duplicate jobs)
-await syncUsers.trigger(
+const idempotentRun = await syncUsers.trigger(
   { orgId: 'org_123' },
   { idempotencyKey: 'webhook-event-456' },
 )
+console.log(idempotentRun.disposition) // "created" or "idempotent"
 
-// With concurrency key (serializes execution)
+// With concurrency key (serializes execution, max 1 pending per key)
 await syncUsers.trigger({ orgId: 'org_123' }, { concurrencyKey: 'org_123' })
+// Second trigger with same key throws ConflictError if a pending run exists
+
+// With coalesce (skip duplicate pending runs gracefully)
+const coalesced = await syncUsers.trigger(
+  { orgId: 'org_123' },
+  { concurrencyKey: 'org_123', coalesce: 'skip' },
+)
+if (coalesced.disposition === 'coalesced') {
+  console.log('Reused existing pending run:', coalesced.id)
+}
 
 // With labels (for filtering)
 await syncUsers.trigger({ orgId: 'org_123' }, { labels: { source: 'browser' } })
@@ -184,6 +198,31 @@ step.log.error('Failed to connect', { error: err.message })
 
 ## Run Management
 
+### Wait for Existing Run
+
+```ts
+// Wait for an existing run to complete (no new run created)
+// Useful when Job A triggers Job B and returns B's run ID
+const completedRun = await durably.waitForRun(runId)
+console.log(completedRun.output) // available when completed
+
+// With timeout and callbacks
+const run = await durably.waitForRun(runId, {
+  timeout: 10000,
+  onProgress: (p) => console.log(`${p.current}/${p.total}`),
+  onLog: (l) => console.log(l.message),
+})
+
+// Same-process listeners settle waits immediately; if another runtime completes the run
+// against the same storage, the wait falls back to storage polling. Optional
+// `pollingIntervalMs` overrides the instance `createDurably({ pollingIntervalMs })` for this call only.
+await durably.waitForRun(runId, { pollingIntervalMs: 2000 })
+
+// Throws NotFoundError if run doesn't exist
+// Throws CancelledError if run is cancelled
+// Throws Error if run fails
+```
+
 ### Get Run Status
 
 ```ts
@@ -210,6 +249,9 @@ const typedRun = await durably.getRun<MyRun>(runId)
 // Get failed runs
 const failedRuns = await durably.getRuns({ status: 'failed' })
 
+// Get active runs (multiple statuses)
+const activeRuns = await durably.getRuns({ status: ['pending', 'leased'] })
+
 // Filter by job name with pagination
 const runs = await durably.getRuns({
   jobName: 'sync-users', // also accepts string[] for multiple jobs
@@ -279,7 +321,11 @@ Subscribe to job execution events. **Listeners run synchronously** in the worker
 
 ```ts
 // Run lifecycle events
+// Note: run:trigger is NOT emitted on idempotent hits (disposition: 'idempotent')
 durably.on('run:trigger', (e) => console.log('Triggered:', e.runId))
+durably.on('run:coalesced', (e) =>
+  console.log('Coalesced:', e.runId, 'skipped input:', e.skippedInput),
+)
 durably.on('run:leased', (e) => console.log('Leased:', e.runId))
 durably.on('run:complete', (e) => console.log('Done:', e.output))
 durably.on('run:fail', (e) => console.error('Failed:', e.error))
@@ -299,6 +345,25 @@ durably.on('step:cancel', (e) => console.log('Step cancelled:', e.stepName))
 durably.on('log:write', (e) => console.log(`[${e.level}]`, e.message))
 ```
 
+### Core event categories
+
+The `DurablyEvent` union is grouped for callers who want lifecycle facts vs operational detail:
+
+- **Domain** (`DomainEvent` / `DomainEventType`): `run:trigger`, `run:coalesced`, `run:complete`, `run:fail`, `run:cancel`, `run:delete`
+- **Operational** (`OperationalEvent` / `OperationalEventType`): `run:leased`, `run:lease-renewed`, `run:progress`, `step:*`, `log:write`, `worker:error`
+
+Use `isDomainEvent(event)` (checks `event.type` only) as a type guard.
+
+```ts
+import { isDomainEvent, type DurablyEvent } from '@coji/durably'
+
+function handleEvent(event: DurablyEvent) {
+  if (isDomainEvent(event)) {
+    console.log('State change:', event.type, event.runId)
+  }
+}
+```
+
 ## Advanced APIs
 
 ### getJob
@@ -413,13 +478,13 @@ GET /runs?label.organizationId=org_123
 GET /runs/subscribe?label.organizationId=org_123&label.env=prod
 ```
 
-**Response Shape:** The `/runs` and `/run` endpoints return `ClientRun` objects (internal fields like `leaseOwner`, `leaseExpiresAt`, `idempotencyKey`, `concurrencyKey`, `updatedAt` are stripped). Use `toClientRun()` to apply the same projection in custom code:
+**Response Shape:** The `/runs` and `/run` endpoints return `ClientRun` objects (internal fields like `leaseOwner`, `leaseExpiresAt`, `idempotencyKey`, `concurrencyKey`, `leaseGeneration`, `updatedAt` are stripped). Each response includes derived `isTerminal` and `isActive` booleans from `status` (terminal: completed, failed, or cancelled; active: pending or leased). Use `toClientRun()` to apply the same projection in custom code:
 
 ```ts
 import { toClientRun } from '@coji/durably'
 
 const run = await durably.getRun(runId)
-const clientRun = toClientRun(run) // strips internal fields
+const clientRun = toClientRun(run) // strips internal fields; adds isTerminal / isActive
 ```
 
 **Handler Interface:**
@@ -477,11 +542,13 @@ interface TriggerRequest<TLabels> {
   input: unknown
   idempotencyKey?: string
   concurrencyKey?: string
+  coalesce?: 'skip'
   labels?: TLabels
 }
 
 interface TriggerResponse {
   runId: string
+  disposition: Disposition
 }
 ```
 
@@ -495,6 +562,10 @@ import { withLogPersistence } from '@coji/durably'
 durably.use(withLogPersistence())
 ```
 
+## SQLite WAL Maintenance
+
+For local SQLite backends using WAL mode, Durably automatically runs periodic WAL checkpoints (`PRAGMA wal_checkpoint(TRUNCATE)`) during idle maintenance to prevent unbounded WAL file growth. This is probed at `migrate()` time and only enabled when the backend supports it — automatically skipped for Turso (remote libSQL), PostgreSQL, and browser (OPFS) backends.
+
 ## Browser Usage
 
 ```ts
@@ -586,6 +657,8 @@ interface Run<TLabels extends Record<string, string> = Record<string, string>> {
   updatedAt: string
 }
 
+type Disposition = 'created' | 'idempotent' | 'coalesced'
+
 interface TypedRun<
   TOutput,
   TLabels extends Record<string, string> = Record<string, string>,
@@ -593,6 +666,10 @@ interface TypedRun<
   output: TOutput | null
 }
 
+type TriggerResult<TOutput, TLabels> = TypedRun<TOutput, TLabels> & {
+  disposition: Disposition
+}
+
 interface JobHandle<
   TName extends string,
   TInput,
@@ -603,14 +680,14 @@ interface JobHandle<
   trigger(
     input: TInput,
     options?: TriggerOptions<TLabels>,
-  ): Promise<TypedRun<TOutput, TLabels>>
+  ): Promise<TriggerResult<TOutput, TLabels>>
   triggerAndWait(
     input: TInput,
     options?: TriggerAndWaitOptions<TLabels>,
-  ): Promise<{ id: string; output: TOutput }>
+  ): Promise<TriggerAndWaitResult<TOutput>>
   batchTrigger(
     inputs: BatchTriggerInput<TInput, TLabels>[],
-  ): Promise<TypedRun<TOutput, TLabels>[]>
+  ): Promise<TriggerResult<TOutput, TLabels>[]>
   getRun(id: string): Promise<TypedRun<TOutput, TLabels> | null>
   getRuns(
     filter?: Omit<RunFilter<TLabels>, 'jobName'>,
@@ -622,17 +699,27 @@ interface TriggerOptions<
 > {
   idempotencyKey?: string
   concurrencyKey?: string
+  coalesce?: 'skip'
   labels?: TLabels
 }
 
-interface TriggerAndWaitOptions<
-  TLabels extends Record<string, string> = Record<string, string>,
-> extends TriggerOptions<TLabels> {
+interface TriggerAndWaitResult<TOutput> {
+  id: string
+  output: TOutput
+  disposition: Disposition
+}
+
+interface WaitForRunOptions {
   timeout?: number
   onProgress?: (progress: ProgressData) => void | Promise<void>
   onLog?: (log: LogData) => void | Promise<void>
 }
 
+interface TriggerAndWaitOptions<
+  TLabels extends Record<string, string> = Record<string, string>,
+>
+  extends TriggerOptions<TLabels>, WaitForRunOptions {}
+
 interface ProgressData {
   current: number
   total?: number
@@ -649,7 +736,7 @@ interface LogData {
 interface RunFilter<
   TLabels extends Record<string, string> = Record<string, string>,
 > {
-  status?: 'pending' | 'leased' | 'completed' | 'failed' | 'cancelled'
+  status?: RunStatus | RunStatus[]
   jobName?: string | string[]
   labels?: Partial<TLabels>
   limit?: number

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coji/durably",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Step-oriented resumable batch execution for Node.js and browsers using SQLite",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,13 +23,11 @@
   "scripts": {
     "build": "tsup",
     "test": "pnpm test:node && pnpm test:react && pnpm test:browser",
-    "test:node": "vitest run --config vitest.config.ts --exclude 'tests/node/**/*.postgres.test.ts'",
-    "test:node:postgres": "vitest run --config vitest.config.ts postgres",
-    "test:node:all": "vitest run --config vitest.config.ts",
+    "test:node": "vitest run --config vitest.config.ts",
     "test:react": "vitest run --config vitest.react.config.ts",
     "test:browser": "vitest run --config vitest.browser.config.ts",
     "typecheck": "tsc --noEmit",
-    "lint": "biome lint .",
+    "lint": "biome lint --error-on-warnings .",
     "lint:fix": "biome lint --write .",
     "format": "prettier --experimental-cli --check .",
     "format:fix": "prettier --experimental-cli --write ."
@@ -66,6 +64,7 @@
     "@biomejs/biome": "^2.4.7",
     "@libsql/client": "^0.17.0",
     "@libsql/kysely-libsql": "^0.4.1",
+    "@testcontainers/postgresql": "11.13.0",
     "@testing-library/react": "^16.3.2",
     "@types/better-sqlite3": "^7.6.13",
     "@types/pg": "^8.15.6",
@@ -83,6 +82,7 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "sqlocal": "^0.17.0",
+    "testcontainers": "11.13.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",