@coji/durably 0.13.0 → 0.15.0

package/dist/plugins/index.d.ts

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

package/dist/plugins/index.js

@@ -1,6 +1,6 @@
 import {
   withLogPersistence
-} from "../chunk-UCUP6NMJ.js";
+} from "../chunk-L42OCQEV.js";
 export {
   withLogPersistence
 };

package/docs/llms.md

@@ -1,18 +1,24 @@
 # Durably - LLM Documentation
 
-> Step-oriented resumable batch execution for Node.js and browsers using SQLite.
+> Step-oriented resumable batch execution for Node.js and browsers using SQLite or PostgreSQL.
 
 ## Overview
 
-Durably is a minimal workflow engine that persists step results to SQLite. If a job is interrupted (server restart, browser tab close, crash), it automatically resumes from the last successful step.
+Durably is a minimal workflow engine that persists step results to SQLite or PostgreSQL. If a job is interrupted (server restart, browser tab close, crash), it automatically resumes from the last successful step. Supports libSQL/Turso (single-server or serverless), PostgreSQL (recommended for multi-worker), and SQLocal (browser/OPFS).
 
 ## Installation
 
 ```bash
-# Node.js with libsql (recommended)
+# Node.js with libSQL (recommended for single-server / Turso)
 pnpm add @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
 
-# Browser with SQLocal
+# Node.js with better-sqlite3 (lightweight local alternative)
+pnpm add @coji/durably kysely zod better-sqlite3
+
+# Node.js with PostgreSQL (recommended for multi-worker)
+pnpm add @coji/durably kysely zod pg
+
+# Browser with SQLocal (OPFS-backed)
 pnpm add @coji/durably kysely zod sqlocal
 ```
 
@@ -26,13 +32,36 @@ import { LibsqlDialect } from '@libsql/kysely-libsql'
 import { createClient } from '@libsql/client'
 import { z } from 'zod'
 
+// --- libSQL local (single-server) ---
 const client = createClient({ url: 'file:local.db' })
 const dialect = new LibsqlDialect({ client })
 
+// --- Turso remote (serverless/edge) ---
+// const client = createClient({
+//   url: process.env.TURSO_DATABASE_URL!,
+//   authToken: process.env.TURSO_AUTH_TOKEN!,
+// })
+// const dialect = new LibsqlDialect({ client })
+
+// --- better-sqlite3 (lightweight local) ---
+// import Database from 'better-sqlite3'
+// import { SqliteDialect } from 'kysely'
+// const dialect = new SqliteDialect({
+//   database: new Database('local.db'),
+// })
+
+// --- PostgreSQL (multi-worker) ---
+// import pg from 'pg'
+// import { PostgresDialect } from 'kysely'
+// const dialect = new PostgresDialect({
+//   pool: new pg.Pool({ connectionString: process.env.DATABASE_URL }),
+// })
+
 // 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)
@@ -95,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(
@@ -102,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' } })
@@ -156,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
@@ -182,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
@@ -247,11 +317,15 @@ For automatic cleanup, use the `retainRuns` option (see Core Concepts). Cleanup
 
 ## Events
 
-Subscribe to job execution events:
+Subscribe to job execution events. **Listeners run synchronously** in the worker's hot path — keep them fast and non-blocking. Use fire-and-forget (`void asyncFn()`) for expensive work.
 
 ```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))
@@ -271,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
@@ -385,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:**
@@ -449,11 +542,13 @@ interface TriggerRequest<TLabels> {
   input: unknown
   idempotencyKey?: string
   concurrencyKey?: string
+  coalesce?: 'skip'
   labels?: TLabels
 }
 
 interface TriggerResponse {
   runId: string
+  disposition: Disposition
 }
 ```
 
@@ -467,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
@@ -558,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>,
@@ -565,6 +666,10 @@ interface TypedRun<
   output: TOutput | null
 }
 
+type TriggerResult<TOutput, TLabels> = TypedRun<TOutput, TLabels> & {
+  disposition: Disposition
+}
+
 interface JobHandle<
   TName extends string,
   TInput,
@@ -575,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'>,
@@ -594,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
@@ -621,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
@@ -629,6 +744,23 @@ interface RunFilter<
 }
 ```
 
+## Error Classes
+
+Durably exports typed error classes for programmatic error handling:
+
+```ts
+import {
+  DurablyError, // Base class with statusCode (extends Error)
+  NotFoundError, // 404 — resource not found
+  ValidationError, // 400 — invalid input or request
+  ConflictError, // 409 — operation conflicts with current state
+  CancelledError, // Run was cancelled during execution
+  LeaseLostError, // Worker lost lease ownership
+} from '@coji/durably'
+```
+
+`DurablyError` subclasses (`NotFoundError`, `ValidationError`, `ConflictError`) carry a `statusCode` property and are used by the HTTP handler to return appropriate responses.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coji/durably",
-  "version": "0.13.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",

package/dist/chunk-UCUP6NMJ.js.map

@@ -1 +0,0 @@
-{"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":[]}