@coji/durably 0.3.0 → 0.6.0

package/README.md

@@ -4,65 +4,36 @@ Step-oriented resumable batch execution for Node.js and browsers using SQLite.
 
 **[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)** | **[Live Demo](https://durably-demo.vercel.app)**
 
-## Features
-
-- Resumable batch processing with step-level persistence
-- Works in both Node.js and browsers
-- Uses SQLite for state management (better-sqlite3/libsql for Node.js, SQLite WASM for browsers)
-- Minimal dependencies - just Kysely and Zod as peer dependencies
-- Event system for monitoring and extensibility
-- Type-safe input/output with Zod schemas
+> **Note:** This package is ESM-only. CommonJS is not supported.
 
 ## Installation
 
 ```bash
-# Node.js with better-sqlite3
 npm install @coji/durably kysely zod better-sqlite3
-
-# Node.js with libsql
-npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
-
-# Browser with SQLocal
-npm install @coji/durably kysely zod sqlocal
 ```
 
-## Usage
+See the [Getting Started Guide](https://coji.github.io/durably/guide/getting-started) for other SQLite backends (libsql, SQLocal for browsers).
+
+## Quick Start
 
 ```ts
-import { createDurably } from '@coji/durably'
-import SQLite from 'better-sqlite3'
-import { SqliteDialect } from 'kysely'
+import { createDurably, defineJob } from '@coji/durably'
 import { z } from 'zod'
 
-const dialect = new SqliteDialect({
-  database: new SQLite('local.db'),
-})
-
-const durably = createDurably({ dialect })
-
-const syncUsers = durably.defineJob(
-  {
-    name: 'sync-users',
-    input: z.object({ orgId: z.string() }),
-    output: z.object({ syncedCount: z.number() }),
-  },
-  async (step, payload) => {
-    const users = await step.run('fetch-users', async () => {
-      return api.fetchUsers(payload.orgId)
-    })
-
-    await step.run('save-to-db', async () => {
-      await db.upsertUsers(users)
+const myJob = defineJob({
+  name: 'my-job',
+  input: z.object({ id: z.string() }),
+  run: async (step, payload) => {
+    await step.run('step-1', async () => {
+      /* ... */
     })
-
-    return { syncedCount: users.length }
   },
-)
+})
 
-await durably.migrate()
-durably.start()
+const durably = createDurably({ dialect }).register({ myJob })
 
-await syncUsers.trigger({ orgId: 'org_123' })
+await durably.init() // migrate + start
+await durably.jobs.myJob.trigger({ id: '123' })
 ```
 
 ## Documentation

package/dist/index.d.ts

@@ -9,6 +9,15 @@ interface BaseEvent {
     timestamp: string;
     sequence: number;
 }
+/**
+ * Run trigger event (emitted when a job is triggered, before worker picks it up)
+ */
+interface RunTriggerEvent extends BaseEvent {
+    type: 'run:trigger';
+    runId: string;
+    jobName: string;
+    payload: unknown;
+}
 /**
  * Run start event
  */
@@ -38,6 +47,35 @@ interface RunFailEvent extends BaseEvent {
     error: string;
     failedStepName: string;
 }
+/**
+ * Run cancel event
+ */
+interface RunCancelEvent extends BaseEvent {
+    type: 'run:cancel';
+    runId: string;
+    jobName: string;
+}
+/**
+ * Run retry event (emitted when a failed run is retried)
+ */
+interface RunRetryEvent extends BaseEvent {
+    type: 'run:retry';
+    runId: string;
+    jobName: string;
+}
+/**
+ * Run progress event
+ */
+interface RunProgressEvent extends BaseEvent {
+    type: 'run:progress';
+    runId: string;
+    jobName: string;
+    progress: {
+        current: number;
+        total?: number;
+        message?: string;
+    };
+}
 /**
  * Step start event
  */
@@ -94,7 +132,7 @@ interface WorkerErrorEvent extends BaseEvent {
 /**
  * All event types as discriminated union
  */
-type DurablyEvent = RunStartEvent | RunCompleteEvent | RunFailEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | LogWriteEvent | WorkerErrorEvent;
+type DurablyEvent = RunTriggerEvent | RunStartEvent | RunCompleteEvent | RunFailEvent | RunCancelEvent | RunRetryEvent | RunProgressEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | LogWriteEvent | WorkerErrorEvent;
 /**
  * Event types for type-safe event names
  */
@@ -112,7 +150,7 @@ type EventInput<T extends EventType> = Omit<EventByType<T>, 'timestamp' | 'seque
 /**
  * All possible event inputs as a union (properly distributed)
  */
-type AnyEventInput = EventInput<'run:start'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'log:write'> | EventInput<'worker:error'>;
+type AnyEventInput = EventInput<'run:trigger'> | EventInput<'run:start'> | EventInput<'run:complete'> | EventInput<'run:fail'> | EventInput<'run:cancel'> | EventInput<'run:retry'> | EventInput<'run:progress'> | EventInput<'step:start'> | EventInput<'step:complete'> | EventInput<'step:fail'> | EventInput<'log:write'> | EventInput<'worker:error'>;
 /**
  * Event listener function
  */
@@ -195,6 +233,7 @@ interface Run {
     idempotencyKey: string | null;
     concurrencyKey: string | null;
     currentStepIndex: number;
+    stepCount: number;
     progress: {
         current: number;
         total?: number;
@@ -323,18 +362,6 @@ interface StepContext {
         error(message: string, data?: unknown): void;
     };
 }
-/**
- * Job function type
- */
-type JobFunction<TInput, TOutput> = (step: StepContext, payload: TInput) => Promise<TOutput>;
-/**
- * Job definition options
- */
-interface JobDefinition<TName extends string, TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType | undefined> {
-    name: TName;
-    input: TInputSchema;
-    output?: TOutputSchema;
-}
 /**
  * Trigger options
  */
@@ -348,8 +375,12 @@ interface TriggerOptions {
  * Run filter options
  */
 interface RunFilter {
-    status?: 'pending' | 'running' | 'completed' | 'failed';
+    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
     jobName?: string;
+    /** Maximum number of runs to return */
+    limit?: number;
+    /** Number of runs to skip (for pagination) */
+    offset?: number;
 }
 /**
  * Typed run with output type
@@ -400,6 +431,66 @@ interface JobHandle<TName extends string, TInput, TOutput> {
     getRuns(filter?: Omit<RunFilter, 'jobName'>): Promise<TypedRun<TOutput>[]>;
 }
 
+/**
+ * Job run function type
+ */
+type JobRunFunction<TInput, TOutput> = (step: StepContext, payload: TInput) => Promise<TOutput>;
+/**
+ * Job definition - a standalone description of a job
+ * This is the result of calling defineJob() and can be passed to durably.register()
+ */
+interface JobDefinition<TName extends string, TInput, TOutput> {
+    readonly name: TName;
+    readonly input: z.ZodType<TInput>;
+    readonly output: z.ZodType<TOutput> | undefined;
+    readonly run: JobRunFunction<TInput, TOutput>;
+}
+/**
+ * Extract input type from a JobDefinition
+ * @example
+ * ```ts
+ * type Input = JobInput<typeof myJob> // { userId: string }
+ * ```
+ */
+type JobInput<T> = T extends JobDefinition<string, infer TInput, unknown> ? TInput : never;
+/**
+ * Extract output type from a JobDefinition
+ * @example
+ * ```ts
+ * type Output = JobOutput<typeof myJob> // { count: number }
+ * ```
+ */
+type JobOutput<T> = T extends JobDefinition<string, unknown, infer TOutput> ? TOutput : never;
+/**
+ * Configuration for defining a job
+ */
+interface DefineJobConfig<TName extends string, TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType | undefined> {
+    name: TName;
+    input: TInputSchema;
+    output?: TOutputSchema;
+    run: JobRunFunction<z.infer<TInputSchema>, TOutputSchema extends z.ZodType ? z.infer<TOutputSchema> : void>;
+}
+/**
+ * Define a job - creates a JobDefinition that can be registered with durably.register()
+ *
+ * @example
+ * ```ts
+ * import { defineJob } from '@coji/durably'
+ * import { z } from 'zod'
+ *
+ * export const syncUsers = defineJob({
+ *   name: 'sync-users',
+ *   input: z.object({ orgId: z.string() }),
+ *   output: z.object({ syncedCount: z.number() }),
+ *   run: async (step, payload) => {
+ *     const users = await step.run('fetch-users', () => fetchUsers(payload.orgId))
+ *     return { syncedCount: users.length }
+ *   },
+ * })
+ * ```
+ */
+declare function defineJob<TName extends string, TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType | undefined = undefined>(config: DefineJobConfig<TName, TInputSchema, TOutputSchema>): JobDefinition<TName, z.infer<TInputSchema>, TOutputSchema extends z.ZodType ? z.infer<TOutputSchema> : void>;
+
 /**
  * Options for creating a Durably instance
  */
@@ -414,12 +505,33 @@ interface DurablyOptions {
  */
 interface DurablyPlugin {
     name: string;
-    install(durably: Durably): void;
+    install(durably: Durably<any>): void;
 }
 /**
- * Durably instance
+ * Helper type to transform JobDefinition record to JobHandle record
+ */
+type TransformToHandles<TJobs extends Record<string, JobDefinition<string, unknown, unknown>>> = {
+    [K in keyof TJobs]: TJobs[K] extends JobDefinition<infer TName, infer TInput, infer TOutput> ? JobHandle<TName & string, TInput, TOutput> : never;
+};
+/**
+ * Durably instance with type-safe jobs
  */
-interface Durably {
+interface Durably<TJobs extends Record<string, JobHandle<string, unknown, unknown>> = Record<string, never>> {
+    /**
+     * Registered job handles (type-safe)
+     */
+    readonly jobs: TJobs;
+    /**
+     * Initialize Durably: run migrations and start the worker
+     * This is the recommended way to start Durably.
+     * Equivalent to calling migrate() then start().
+     * @example
+     * ```ts
+     * const durably = createDurably({ dialect }).register({ ... })
+     * await durably.init()
+     * ```
+     */
+    init(): Promise<void>;
     /**
      * Run database migrations
      * This is idempotent and safe to call multiple times
@@ -448,9 +560,19 @@ interface Durably {
      */
     onError(handler: ErrorHandler): void;
     /**
-     * Define a job
+     * Register job definitions and return a new Durably instance with type-safe jobs
+     * @example
+     * ```ts
+     * const durably = createDurably({ dialect })
+     *   .register({
+     *     importCsv: importCsvJob,
+     *     syncUsers: syncUsersJob,
+     *   })
+     * await durably.migrate()
+     * // Usage: durably.jobs.importCsv.trigger({ rows: [...] })
+     * ```
      */
-    defineJob<TName extends string, TInputSchema extends z.ZodType, TOutputSchema extends z.ZodType | undefined = undefined>(definition: JobDefinition<TName, TInputSchema, TOutputSchema>, fn: JobFunction<z.infer<TInputSchema>, TOutputSchema extends z.ZodType ? z.infer<TOutputSchema> : void>): JobHandle<TName, z.infer<TInputSchema>, TOutputSchema extends z.ZodType ? z.infer<TOutputSchema> : void>;
+    register<TNewJobs extends Record<string, JobDefinition<string, any, any>>>(jobDefs: TNewJobs): Durably<TJobs & TransformToHandles<TNewJobs>>;
     /**
      * Start the worker polling loop
      */
@@ -486,11 +608,21 @@ interface Durably {
      * Register a plugin
      */
     use(plugin: DurablyPlugin): void;
+    /**
+     * Get a registered job handle by name
+     * Returns undefined if job is not registered
+     */
+    getJob<TName extends string = string>(name: TName): JobHandle<TName, Record<string, unknown>, unknown> | undefined;
+    /**
+     * Subscribe to events for a specific run
+     * Returns a ReadableStream that can be used for SSE
+     */
+    subscribe(runId: string): ReadableStream<DurablyEvent>;
 }
 /**
  * Create a Durably instance
  */
-declare function createDurably(options: DurablyOptions): Durably;
+declare function createDurably(options: DurablyOptions): Durably<Record<string, never>>;
 
 /**
  * Plugin that persists log events to the database
@@ -506,4 +638,131 @@ declare class CancelledError extends Error {
     constructor(runId: string);
 }
 
-export { CancelledError, type Database, type Durably, type DurablyEvent, type DurablyOptions, type DurablyPlugin, type ErrorHandler, type EventType, type JobHandle, type Log, type LogWriteEvent, type LogsTable, type Run, type RunCompleteEvent, type RunFailEvent, type RunFilter$1 as RunFilter, type RunStartEvent, type RunsTable, type SchemaVersionsTable, type Step, type StepCompleteEvent, type StepContext, type StepFailEvent, type StepStartEvent, type StepsTable, type TriggerAndWaitResult, type WorkerErrorEvent, createDurably, withLogPersistence };
+/**
+ * Request body for triggering a job
+ */
+interface TriggerRequest {
+    jobName: string;
+    input: Record<string, unknown>;
+    idempotencyKey?: string;
+    concurrencyKey?: string;
+}
+/**
+ * Response for trigger endpoint
+ */
+interface TriggerResponse {
+    runId: string;
+}
+/**
+ * Handler interface for HTTP endpoints
+ */
+interface DurablyHandler {
+    /**
+     * Handle all Durably HTTP requests with automatic routing
+     *
+     * Routes:
+     * - GET  {basePath}/subscribe?runId=xxx - SSE stream
+     * - GET  {basePath}/runs - List runs
+     * - GET  {basePath}/run?runId=xxx - Get single run
+     * - POST {basePath}/trigger - Trigger a job
+     * - POST {basePath}/retry?runId=xxx - Retry a failed run
+     * - POST {basePath}/cancel?runId=xxx - Cancel a run
+     *
+     * @param request - The incoming HTTP request
+     * @param basePath - The base path to strip from the URL (e.g., '/api/durably')
+     * @returns Response or null if route not matched
+     *
+     * @example
+     * ```ts
+     * // React Router / Remix
+     * export async function loader({ request }) {
+     *   return durablyHandler.handle(request, '/api/durably')
+     * }
+     * export async function action({ request }) {
+     *   return durablyHandler.handle(request, '/api/durably')
+     * }
+     * ```
+     */
+    handle(request: Request, basePath: string): Promise<Response>;
+    /**
+     * Handle job trigger request
+     * Expects POST with JSON body: { jobName, input, idempotencyKey?, concurrencyKey? }
+     * Returns JSON: { runId }
+     */
+    trigger(request: Request): Promise<Response>;
+    /**
+     * Handle subscription request
+     * Expects GET with query param: runId
+     * Returns SSE stream of events
+     */
+    subscribe(request: Request): Response;
+    /**
+     * Handle runs list request
+     * Expects GET with optional query params: jobName, status, limit, offset
+     * Returns JSON array of runs
+     */
+    runs(request: Request): Promise<Response>;
+    /**
+     * Handle single run request
+     * Expects GET with query param: runId
+     * Returns JSON run object or 404
+     */
+    run(request: Request): Promise<Response>;
+    /**
+     * Handle retry request
+     * Expects POST with query param: runId
+     * Returns JSON: { success: true }
+     */
+    retry(request: Request): Promise<Response>;
+    /**
+     * Handle cancel request
+     * Expects POST with query param: runId
+     * Returns JSON: { success: true }
+     */
+    cancel(request: Request): Promise<Response>;
+    /**
+     * Handle delete request
+     * Expects DELETE with query param: runId
+     * Returns JSON: { success: true }
+     */
+    delete(request: Request): Promise<Response>;
+    /**
+     * Handle steps request
+     * Expects GET with query param: runId
+     * Returns JSON array of steps
+     */
+    steps(request: Request): Promise<Response>;
+    /**
+     * Handle runs subscription request
+     * Expects GET with optional query param: jobName
+     * Returns SSE stream of run update notifications
+     */
+    runsSubscribe(request: Request): Response;
+}
+/**
+ * Options for createDurablyHandler
+ */
+interface CreateDurablyHandlerOptions {
+    /**
+     * Called before handling each request.
+     * Use this to initialize Durably (migrate, start worker, etc.)
+     *
+     * @example
+     * ```ts
+     * const durablyHandler = createDurablyHandler(durably, {
+     *   onRequest: async () => {
+     *     await durably.migrate()
+     *     durably.start()
+     *   }
+     * })
+     * ```
+     */
+    onRequest?: () => Promise<void> | void;
+}
+/**
+ * Create HTTP handlers for Durably
+ * Uses Web Standard Request/Response for framework-agnostic usage
+ */
+declare function createDurablyHandler(durably: Durably, options?: CreateDurablyHandlerOptions): DurablyHandler;
+
+export { CancelledError, type Database, type Durably, type DurablyEvent, type DurablyHandler, type DurablyOptions, type DurablyPlugin, type ErrorHandler, type EventType, type JobDefinition, type JobHandle, type JobInput, type JobOutput, type Log, type LogWriteEvent, type LogsTable, type Run, type RunCompleteEvent, type RunFailEvent, type RunFilter$1 as RunFilter, type RunProgressEvent, type RunStartEvent, type RunsTable, type SchemaVersionsTable, type Step, type StepCompleteEvent, type StepContext, type StepFailEvent, type StepStartEvent, type StepsTable, type TriggerAndWaitResult, type TriggerRequest, type TriggerResponse, type WorkerErrorEvent, createDurably, createDurablyHandler, defineJob, withLogPersistence };