@coji/durably 0.11.0 → 0.13.0

package/dist/plugins/index.d.ts

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

package/docs/llms.md

@@ -32,9 +32,11 @@ const dialect = new LibsqlDialect({ client })
 // 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)
+  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: {
@@ -206,10 +208,14 @@ type MyRun = Run & {
 const typedRuns = await durably.getRuns<MyRun>({ jobName: 'my-job' })
 ```
 
-### Retry Failed Runs
+### Retrigger Failed Runs
 
 ```ts
-await durably.retry(runId)
+// 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
 ```
 
 ### Cancel Runs
@@ -224,6 +230,21 @@ 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:
@@ -231,12 +252,11 @@ Subscribe to job execution events:
 ```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))
 durably.on('run:delete', (e) => console.log('Deleted:', e.runId))
-durably.on('run:retry', (e) => console.log('Retried:', e.runId))
 durably.on('run:progress', (e) =>
   console.log('Progress:', e.progress.current, '/', e.progress.total),
 )
@@ -277,8 +297,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)
@@ -336,7 +356,7 @@ const handler = createDurablyHandler(durably, {
       }
     },
 
-    // Guard before run-level operations (read, subscribe, steps, retry, cancel, delete)
+    // Guard before run-level operations (read, subscribe, steps, retrigger, cancel, delete)
     onRunAccess: async (ctx, run, { operation }) => {
       if (run.labels.organizationId !== ctx.orgId) {
         throw new Response('Forbidden', { status: 403 })
@@ -365,7 +385,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'
@@ -418,7 +438,7 @@ type RunOperation =
   | 'read'
   | 'subscribe'
   | 'steps'
-  | 'retry'
+  | 'retrigger'
   | 'cancel'
   | 'delete'
 
@@ -458,9 +478,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',
@@ -479,13 +499,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()`
@@ -526,7 +546,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
@@ -601,7 +621,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

package/package.json

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