@coji/durably 0.9.0 → 0.11.0

package/dist/plugins/index.d.ts

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

package/docs/llms.md

@@ -24,15 +24,29 @@ pnpm add @coji/durably kysely zod sqlocal
 import { createDurably } from '@coji/durably'
 import { LibsqlDialect } from '@libsql/kysely-libsql'
 import { createClient } from '@libsql/client'
+import { z } from 'zod'
 
 const client = createClient({ url: 'file:local.db' })
 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)
+  // Optional: type-safe labels with Zod schema
+  // labels: z.object({ organizationId: z.string(), env: z.string() }),
+  jobs: {
+    syncUsers: syncUsersJob,
+  },
+})
+// durably.jobs.syncUsers is immediately available and type-safe
+
+// Option 2: Without jobs (register later)
+const durably = createDurably({ dialect })
+const { syncUsers } = durably.register({
+  syncUsers: syncUsersJob,
 })
 ```
 
@@ -60,11 +74,6 @@ const syncUsersJob = defineJob({
     return { syncedCount: users.length }
   },
 })
-
-// Register jobs with durably instance
-const { syncUsers } = durably.register({
-  syncUsers: syncUsersJob,
-})
 ```
 
 ### 3. Starting the Worker
@@ -127,7 +136,7 @@ const result = await step.run('step-name', async (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...')
@@ -173,7 +182,7 @@ const failedRuns = await durably.getRuns({ status: 'failed' })
 
 // Filter by job name with pagination
 const runs = await durably.getRuns({
-  jobName: 'sync-users',
+  jobName: 'sync-users', // also accepts string[] for multiple jobs
   status: 'completed',
   limit: 10,
   offset: 0,
@@ -294,23 +303,59 @@ 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)
+  onRequest: async () => {
+    // Called before each request (after auth) — useful for lazy init
+    await durably.init()
+  },
+})
 
-// Use the unified handle() method with automatic routing
+// Use the handle() method with automatic routing
 app.all('/api/durably/*', async (req) => {
   return await handler.handle(req, '/api/durably')
 })
+```
+
+**With auth middleware (multi-tenant):**
+
+```ts
+const handler = createDurablyHandler(durably, {
+  auth: {
+    // Required: authenticate every request. Throw Response to reject.
+    authenticate: async (request) => {
+      const session = await requireUser(request)
+      const orgId = await resolveCurrentOrgId(request, session.user.id)
+      return { orgId }
+    },
+
+    // Guard before trigger (called after body validation + job resolution)
+    onTrigger: async (ctx, { jobName, input, labels }) => {
+      if (labels?.organizationId !== ctx.orgId) {
+        throw new Response('Forbidden', { status: 403 })
+      }
+    },
+
+    // Guard before run-level operations (read, subscribe, steps, retry, cancel, delete)
+    onRunAccess: async (ctx, run, { operation }) => {
+      if (run.labels.organizationId !== ctx.orgId) {
+        throw new Response('Forbidden', { status: 403 })
+      }
+    },
 
-// Or use individual endpoints
-app.post('/api/durably/trigger', (req) => handler.trigger(req))
-app.get('/api/durably/subscribe', (req) => handler.subscribe(req))
-app.get('/api/durably/runs', (req) => handler.runs(req))
-app.get('/api/durably/run', (req) => handler.run(req))
-app.get('/api/durably/steps', (req) => handler.steps(req))
-app.get('/api/durably/runs/subscribe', (req) => handler.runsSubscribe(req))
-app.post('/api/durably/retry', (req) => handler.retry(req))
-app.post('/api/durably/cancel', (req) => handler.cancel(req))
-app.delete('/api/durably/run', (req) => handler.delete(req))
+    // Scope runs list queries (GET /runs)
+    scopeRuns: async (ctx, filter) => ({
+      ...filter,
+      labels: { ...filter.labels, organizationId: ctx.orgId },
+    }),
+
+    // Scope runs subscribe stream (GET /runs/subscribe). Falls back to scopeRuns if not set.
+    scopeRunsSubscribe: async (ctx, filter) => ({
+      ...filter,
+      labels: { ...filter.labels, organizationId: ctx.orgId },
+    }),
+  },
+})
 ```
 
 **Label filtering via query params:**
@@ -333,27 +378,58 @@ const clientRun = toClientRun(run) // strips internal fields
 
 ```ts
 interface DurablyHandler {
-  // Unified routing handler
   handle(request: Request, basePath: string): Promise<Response>
+}
 
-  // Individual endpoints
-  trigger(request: Request): Promise<Response> // POST /trigger
-  subscribe(request: Request): Response // GET /subscribe?runId=xxx (SSE)
-  runs(request: Request): Promise<Response> // GET /runs
-  run(request: Request): Promise<Response> // GET /run?runId=xxx
-  steps(request: Request): Promise<Response> // GET /steps?runId=xxx
-  runsSubscribe(request: Request): Response // GET /runs/subscribe (SSE)
-  retry(request: Request): Promise<Response> // POST /retry?runId=xxx
-  cancel(request: Request): Promise<Response> // POST /cancel?runId=xxx
-  delete(request: Request): Promise<Response> // DELETE /run?runId=xxx
+interface CreateDurablyHandlerOptions<
+  TContext = undefined,
+  TLabels extends Record<string, string> = Record<string, string>,
+> {
+  onRequest?: () => Promise<void> | void
+  sseThrottleMs?: number // default: 100
+  auth?: AuthConfig<TContext, TLabels>
 }
 
-interface TriggerRequest {
+interface AuthConfig<
+  TContext,
+  TLabels extends Record<string, string> = Record<string, string>,
+> {
+  authenticate: (request: Request) => Promise<TContext> | TContext
+  onTrigger?: (
+    ctx: TContext,
+    trigger: TriggerRequest<TLabels>,
+  ) => Promise<void> | void
+  onRunAccess?: (
+    ctx: TContext,
+    run: Run<TLabels>,
+    info: { operation: RunOperation },
+  ) => Promise<void> | void
+  scopeRuns?: (
+    ctx: TContext,
+    filter: RunFilter<TLabels>,
+  ) => RunFilter<TLabels> | Promise<RunFilter<TLabels>>
+  scopeRunsSubscribe?: (
+    ctx: TContext,
+    filter: RunsSubscribeFilter<TLabels>,
+  ) => RunsSubscribeFilter<TLabels> | Promise<RunsSubscribeFilter<TLabels>>
+}
+
+type RunOperation =
+  | 'read'
+  | 'subscribe'
+  | 'steps'
+  | 'retry'
+  | 'cancel'
+  | 'delete'
+
+// RunsSubscribeFilter is Pick<RunFilter, 'jobName' | 'labels'>
+
+interface TriggerRequest<TLabels> {
   jobName: string
-  input: Record<string, unknown>
+  input: unknown
   idempotencyKey?: string
   concurrencyKey?: string
-  labels?: Record<string, string>
+  labels?: TLabels
 }
 
 interface TriggerResponse {
@@ -385,17 +461,15 @@ const durably = createDurably({
   pollingInterval: 100,
   heartbeatInterval: 500,
   staleThreshold: 3000,
-})
-
-// Same API as Node.js
-const { myJob } = durably.register({
-  myJob: defineJob({
-    name: 'my-job',
-    input: z.object({}),
-    run: async (step) => {
-      /* ... */
-    },
-  }),
+  jobs: {
+    myJob: defineJob({
+      name: 'my-job',
+      input: z.object({}),
+      run: async (step) => {
+        /* ... */
+      },
+    }),
+  },
 })
 
 // Initialize (same as Node.js)
@@ -448,44 +522,88 @@ interface StepContext {
   }
 }
 
-interface Run<TOutput = unknown> {
+// TLabels defaults to Record<string, string> when no labels schema is provided
+interface Run<TLabels extends Record<string, string> = Record<string, string>> {
   id: string
   jobName: string
   status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
   input: unknown
-  labels: Record<string, string>
-  output?: TOutput
-  error?: string
-  progress?: { current: number; total?: number; message?: string }
+  labels: TLabels
+  output: unknown | null
+  error: string | null
+  progress: { current: number; total?: number; message?: string } | null
   startedAt: string | null
   completedAt: string | null
   createdAt: string
   updatedAt: string
 }
 
-interface JobHandle<TName, TInput, TOutput> {
+interface TypedRun<
+  TOutput,
+  TLabels extends Record<string, string> = Record<string, string>,
+> extends Omit<Run<TLabels>, 'output'> {
+  output: TOutput | null
+}
+
+interface JobHandle<
+  TName extends string,
+  TInput,
+  TOutput,
+  TLabels extends Record<string, string> = Record<string, string>,
+> {
   name: TName
-  trigger(input: TInput, options?: TriggerOptions): Promise<Run<TOutput>>
+  trigger(
+    input: TInput,
+    options?: TriggerOptions<TLabels>,
+  ): Promise<TypedRun<TOutput, TLabels>>
   triggerAndWait(
     input: TInput,
-    options?: TriggerOptions,
+    options?: TriggerAndWaitOptions<TLabels>,
   ): Promise<{ id: string; output: TOutput }>
-  batchTrigger(inputs: BatchTriggerInput<TInput>[]): Promise<Run<TOutput>[]>
-  getRun(id: string): Promise<Run<TOutput> | null>
-  getRuns(filter?: RunFilter): Promise<Run<TOutput>[]>
+  batchTrigger(
+    inputs: BatchTriggerInput<TInput, TLabels>[],
+  ): Promise<TypedRun<TOutput, TLabels>[]>
+  getRun(id: string): Promise<TypedRun<TOutput, TLabels> | null>
+  getRuns(
+    filter?: Omit<RunFilter<TLabels>, 'jobName'>,
+  ): Promise<TypedRun<TOutput, TLabels>[]>
 }
 
-interface TriggerOptions {
+interface TriggerOptions<
+  TLabels extends Record<string, string> = Record<string, string>,
+> {
   idempotencyKey?: string
   concurrencyKey?: string
-  labels?: Record<string, string>
+  labels?: TLabels
+}
+
+interface TriggerAndWaitOptions<
+  TLabels extends Record<string, string> = Record<string, string>,
+> extends TriggerOptions<TLabels> {
   timeout?: number
+  onProgress?: (progress: ProgressData) => void | Promise<void>
+  onLog?: (log: LogData) => void | Promise<void>
+}
+
+interface ProgressData {
+  current: number
+  total?: number
+  message?: string
+}
+
+interface LogData {
+  level: 'info' | 'warn' | 'error'
+  message: string
+  data?: unknown
+  stepName?: string | null
 }
 
-interface RunFilter {
+interface RunFilter<
+  TLabels extends Record<string, string> = Record<string, string>,
+> {
   status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
-  jobName?: string
-  labels?: Record<string, string>
+  jobName?: string | string[]
+  labels?: Partial<TLabels>
   limit?: number
   offset?: number
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coji/durably",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Step-oriented resumable batch execution for Node.js and browsers using SQLite",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
     "ulidx": "^2.4.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.5",
+    "@biomejs/biome": "^2.4.6",
     "@libsql/client": "^0.17.0",
     "@libsql/kysely-libsql": "^0.4.1",
     "@testing-library/react": "^16.3.2",