@coji/durably 0.13.0 → 0.14.0

package/dist/plugins/index.d.ts

@@ -1,3 +1,3 @@
-export { V as withLogPersistence } from '../index-DWsJlgyh.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,9 +32,31 @@ 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,
@@ -247,7 +275,7 @@ 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
@@ -629,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.13.0",
+  "version": "0.14.0",
   "description": "Step-oriented resumable batch execution for Node.js and browsers using SQLite",
   "type": "module",
   "main": "./dist/index.js",

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