@coji/durably 0.8.1 → 0.10.0

package/dist/plugins/index.d.ts

@@ -1,3 +1,3 @@
-export { w as withLogPersistence } from '../index-4aPZWn8r.js';
+export { H as withLogPersistence } from '../index-BjlCb0gP.js';
 import 'kysely';
 import 'zod';

package/docs/llms.md

@@ -46,10 +46,10 @@ const syncUsersJob = defineJob({
   name: 'sync-users',
   input: z.object({ orgId: z.string() }),
   output: z.object({ syncedCount: z.number() }),
-  run: async (step, payload) => {
+  run: async (step, input) => {
     // Step 1: Fetch users (result is persisted)
     const users = await step.run('fetch-users', async () => {
-      return await api.fetchUsers(payload.orgId)
+      return await api.fetchUsers(input.orgId)
     })
 
     // Step 2: Save to database
@@ -100,6 +100,15 @@ await syncUsers.trigger(
 
 // With concurrency key (serializes execution)
 await syncUsers.trigger({ orgId: 'org_123' }, { concurrencyKey: 'org_123' })
+
+// With labels (for filtering)
+await syncUsers.trigger({ orgId: 'org_123' }, { labels: { source: 'browser' } })
+
+// Labels for multi-tenancy
+await syncUsers.trigger(
+  { orgId: 'org_123' },
+  { labels: { organizationId: 'org_123', env: 'prod' } },
+)
 ```
 
 ## Step Context API
@@ -108,17 +117,17 @@ The `step` object provides these methods:
 
 ### step.run(name, fn)
 
-Executes a step and persists its result. On resume, returns cached result without re-executing.
+Executes a step and persists its result. On resume, returns cached result without re-executing. The callback receives an `AbortSignal` that is aborted when the run is cancelled, enabling cooperative cancellation of long-running steps.
 
 ```ts
-const result = await step.run('step-name', async () => {
-  return await someAsyncOperation()
+const result = await step.run('step-name', async (signal) => {
+  return await someAsyncOperation({ signal })
 })
 ```
 
 ### step.progress(current, total?, message?)
 
-Updates progress information for the run.
+Updates progress information for the run. Call freely in loops — SSE delivery is throttled by `sseThrottleMs` (default 100ms) so clients receive smooth updates without flooding.
 
 ```ts
 step.progress(50, 100, 'Processing items...')
@@ -150,7 +159,7 @@ const run = await durably.getRun(runId)
 
 // Via durably instance (typed with generic parameter)
 type MyRun = Run & {
-  payload: { userId: string }
+  input: { userId: string }
   output: { count: number } | null
 }
 const typedRun = await durably.getRun<MyRun>(runId)
@@ -170,9 +179,19 @@ const runs = await durably.getRuns({
   offset: 0,
 })
 
+// Filter by labels
+const browserRuns = await durably.getRuns({
+  labels: { source: 'browser' },
+})
+
+// Filter by labels (multi-tenancy)
+const orgRuns = await durably.getRuns({
+  labels: { organizationId: 'org_123' },
+})
+
 // Typed getRuns with generic parameter
 type MyRun = Run & {
-  payload: { userId: string }
+  input: { userId: string }
   output: { count: number } | null
 }
 const typedRuns = await durably.getRuns<MyRun>({ jobName: 'my-job' })
@@ -207,6 +226,7 @@ durably.on('run:start', (e) => console.log('Started:', 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),
@@ -216,6 +236,7 @@ durably.on('run:progress', (e) =>
 durably.on('step:start', (e) => console.log('Step:', e.stepName))
 durably.on('step:complete', (e) => console.log('Step done:', e.stepName))
 durably.on('step:fail', (e) => console.error('Step failed:', e.stepName))
+durably.on('step:cancel', (e) => console.log('Step cancelled:', e.stepName))
 
 // Log events
 durably.on('log:write', (e) => console.log(`[${e.level}]`, e.message))
@@ -273,7 +294,9 @@ Create HTTP handlers for client/server architecture using Web Standard Request/R
 ```ts
 import { createDurablyHandler } from '@coji/durably'
 
-const handler = createDurablyHandler(durably)
+const handler = createDurablyHandler(durably, {
+  sseThrottleMs: 100, // default: throttle progress SSE events (0 to disable)
+})
 
 // Use the unified handle() method with automatic routing
 app.all('/api/durably/*', async (req) => {
@@ -292,6 +315,22 @@ app.post('/api/durably/cancel', (req) => handler.cancel(req))
 app.delete('/api/durably/run', (req) => handler.delete(req))
 ```
 
+**Label filtering via query params:**
+
+```http
+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:
+
+```ts
+import { toClientRun } from '@coji/durably'
+
+const run = await durably.getRun(runId)
+const clientRun = toClientRun(run) // strips internal fields
+```
+
 **Handler Interface:**
 
 ```ts
@@ -316,6 +355,7 @@ interface TriggerRequest {
   input: Record<string, unknown>
   idempotencyKey?: string
   concurrencyKey?: string
+  labels?: Record<string, string>
 }
 
 interface TriggerResponse {
@@ -395,12 +435,13 @@ interface JobDefinition<TName, TInput, TOutput> {
   name: TName
   input: ZodType<TInput>
   output?: ZodType<TOutput>
-  run: (step: StepContext, payload: TInput) => Promise<TOutput>
+  run: (step: StepContext, input: TInput) => Promise<TOutput>
 }
 
+// AbortSignal is aborted when the run is cancelled
 interface StepContext {
   runId: string
-  run<T>(name: string, fn: () => T | Promise<T>): Promise<T>
+  run<T>(name: string, fn: (signal: AbortSignal) => T | Promise<T>): Promise<T>
   progress(current: number, total?: number, message?: string): void
   log: {
     info(message: string, data?: unknown): void
@@ -413,10 +454,13 @@ interface Run<TOutput = unknown> {
   id: string
   jobName: string
   status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
-  payload: unknown
+  input: unknown
+  labels: Record<string, string>
   output?: TOutput
   error?: string
   progress?: { current: number; total?: number; message?: string }
+  startedAt: string | null
+  completedAt: string | null
   createdAt: string
   updatedAt: string
 }
@@ -436,8 +480,17 @@ interface JobHandle<TName, TInput, TOutput> {
 interface TriggerOptions {
   idempotencyKey?: string
   concurrencyKey?: string
+  labels?: Record<string, string>
   timeout?: number
 }
+
+interface RunFilter {
+  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  jobName?: string
+  labels?: Record<string, string>
+  limit?: number
+  offset?: number
+}
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coji/durably",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Step-oriented resumable batch execution for Node.js and browsers using SQLite",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,27 +48,27 @@
     "ulidx": "^2.4.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
+    "@biomejs/biome": "^2.4.5",
     "@libsql/client": "^0.17.0",
     "@libsql/kysely-libsql": "^0.4.1",
-    "@testing-library/react": "^16.3.1",
-    "@types/react": "^19.2.7",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.2",
-    "@vitest/browser": "^4.0.16",
-    "@vitest/browser-playwright": "4.0.16",
-    "jsdom": "^27.4.0",
-    "kysely": "^0.28.9",
-    "playwright": "^1.57.0",
-    "prettier": "^3.7.4",
+    "@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",
+    "playwright": "^1.58.2",
+    "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "sqlocal": "^0.16.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "sqlocal": "^0.17.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.16",
-    "zod": "^4.3.5"
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
   },
   "scripts": {
     "build": "tsup",