@coji/durably 0.12.0 → 0.14.0

package/dist/plugins/index.d.ts

@@ -1,3 +1,3 @@
-export { M as withLogPersistence } from '../index-hM7-oiyj.js';
+export { V as withLogPersistence } from '../index-CDCdrLgw.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,16 +32,39 @@ 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,
-  pollingInterval: 1000, // Job polling interval (ms)
-  heartbeatInterval: 5000, // Heartbeat update interval (ms)
-  staleThreshold: 30000, // When to consider a job abandoned (ms)
-  cleanupSteps: true, // Delete step output data on terminal state (default: true)
+  pollingIntervalMs: 1000, // Job polling interval (ms)
+  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)
+  retainRuns: '30d', // Auto-delete terminal runs older than 30 days (runs during worker polling; supports 'd', 'h', 'm' units)
   // Optional: type-safe labels with Zod schema
   // labels: z.object({ organizationId: z.string(), env: z.string() }),
   jobs: {
@@ -210,7 +239,9 @@ const typedRuns = await durably.getRuns<MyRun>({ jobName: 'my-job' })
 ### Retrigger Failed Runs
 
 ```ts
-// Creates a fresh run (new ID) with the same input/options
+// Creates a fresh run (new ID) with the same input and labels
+// Input is validated against the current job schema — throws if incompatible
+// Note: idempotencyKey is not carried forward
 const newRun = await durably.retrigger(runId)
 console.log(newRun.id) // new run ID
 ```
@@ -227,14 +258,29 @@ await durably.cancel(runId)
 await durably.deleteRun(runId)
 ```
 
+### Purge Old Runs
+
+Batch-delete terminal runs (completed, failed, cancelled) older than a cutoff date.
+Pending and leased runs are never deleted.
+
+```ts
+// Delete terminal runs older than 30 days
+const deleted = await durably.purgeRuns({
+  olderThan: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+  limit: 500, // optional batch size (default: 500)
+})
+```
+
+For automatic cleanup, use the `retainRuns` option (see Core Concepts). Cleanup runs during idle worker polling cycles, at most once per minute, in batches of 100.
+
 ## 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
 durably.on('run:trigger', (e) => console.log('Triggered:', e.runId))
-durably.on('run:start', (e) => console.log('Started:', e.runId))
+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))
 durably.on('run:cancel', (e) => console.log('Cancelled:', e.runId))
@@ -279,8 +325,8 @@ while (true) {
   if (done) break
 
   switch (value.type) {
-    case 'run:start':
-      console.log('Started')
+    case 'run:leased':
+      console.log('Leased')
       break
     case 'run:complete':
       console.log('Completed:', value.output)
@@ -367,7 +413,7 @@ 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 `heartbeatAt`, `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`, `updatedAt` are stripped). Use `toClientRun()` to apply the same projection in custom code:
 
 ```ts
 import { toClientRun } from '@coji/durably'
@@ -460,9 +506,9 @@ const { dialect } = new SQLocalKysely('app.sqlite3')
 
 const durably = createDurably({
   dialect,
-  pollingInterval: 100,
-  heartbeatInterval: 500,
-  staleThreshold: 3000,
+  pollingIntervalMs: 100,
+  leaseRenewIntervalMs: 500,
+  leaseMs: 3000,
   jobs: {
     myJob: defineJob({
       name: 'my-job',
@@ -481,13 +527,13 @@ await durably.init()
 ## Run Lifecycle
 
 ```text
-trigger() → pending → running → completed
-                  ↘           ↗
+trigger() → pending → leased → completed
+                  ↘          ↗
                     → failed
 ```
 
 - **pending**: Waiting for worker to pick up
-- **running**: Worker is executing steps
+- **leased**: Worker has acquired a lease and is executing steps
 - **completed**: All steps finished successfully
 - **failed**: A step threw an error
 - **cancelled**: Manually cancelled via `cancel()`
@@ -528,7 +574,7 @@ interface StepContext {
 interface Run<TLabels extends Record<string, string> = Record<string, string>> {
   id: string
   jobName: string
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  status: 'pending' | 'leased' | 'completed' | 'failed' | 'cancelled'
   input: unknown
   labels: TLabels
   output: unknown | null
@@ -603,7 +649,7 @@ interface LogData {
 interface RunFilter<
   TLabels extends Record<string, string> = Record<string, string>,
 > {
-  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  status?: 'pending' | 'leased' | 'completed' | 'failed' | 'cancelled'
   jobName?: string | string[]
   labels?: Partial<TLabels>
   limit?: number
@@ -611,6 +657,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.12.0",
+  "version": "0.14.0",
   "description": "Step-oriented resumable batch execution for Node.js and browsers using SQLite",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,6 +20,20 @@
     "docs",
     "README.md"
   ],
+  "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:react": "vitest run --config vitest.react.config.ts",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "prettier --experimental-cli --check .",
+    "format:fix": "prettier --experimental-cli --write ."
+  },
   "keywords": [
     "batch",
     "job",
@@ -45,20 +59,24 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
+    "better-sqlite3": "12.6.2",
     "ulidx": "^2.4.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.6",
+    "@biomejs/biome": "^2.4.7",
     "@libsql/client": "^0.17.0",
     "@libsql/kysely-libsql": "^0.4.1",
     "@testing-library/react": "^16.3.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/pg": "^8.15.6",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.4",
-    "@vitest/browser": "^4.0.18",
-    "@vitest/browser-playwright": "4.0.18",
-    "jsdom": "^28.1.0",
-    "kysely": "^0.28.11",
+    "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/browser": "^4.1.0",
+    "@vitest/browser-playwright": "4.1.0",
+    "jsdom": "^29.0.0",
+    "kysely": "^0.28.12",
+    "pg": "^8.16.3",
     "playwright": "^1.58.2",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
@@ -67,19 +85,7 @@
     "sqlocal": "^0.17.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.0",
     "zod": "^4.3.6"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "pnpm test:node && pnpm test:react && pnpm test:browser",
-    "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:fix": "biome lint --write .",
-    "format": "prettier --experimental-cli --check .",
-    "format:fix": "prettier --experimental-cli --write ."
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 coji
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

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":[]}