@coji/durably 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -1,54 +1,74 @@
-# durably
+# @coji/durably
 
 Step-oriented resumable batch execution for Node.js and browsers using SQLite.
 
-> **Note**: This package is under development. The API is not yet implemented.
+**[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)** | **[Live Demo](https://durably-demo.vercel.app)**
 
-## Features (Planned)
+## Features
 
 - Resumable batch processing with step-level persistence
 - Works in both Node.js and browsers
-- Uses SQLite for state management (better-sqlite3, libsql, or WASM)
-- Minimal dependencies - just Kysely as a peer dependency
+- 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
-- Plugin architecture for optional features
+- Type-safe input/output with Zod schemas
 
 ## Installation
 
 ```bash
-npm install durably kysely better-sqlite3
+# 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 (Preview)
+## Usage
 
 ```ts
-import { createClient, defineJob } from 'durably'
-import Database from 'better-sqlite3'
-import { BetterSqlite3Dialect } from 'kysely'
+import { createDurably } from '@coji/durably'
+import SQLite from 'better-sqlite3'
+import { SqliteDialect } from 'kysely'
+import { z } from 'zod'
 
-const dialect = new BetterSqlite3Dialect({
-  database: new Database('app.db'),
+const dialect = new SqliteDialect({
+  database: new SQLite('local.db'),
 })
 
-const client = createClient({ dialect })
+const durably = createDurably({ dialect })
 
-const syncUsers = defineJob('sync-users', async (ctx, payload: { orgId: string }) => {
-  const users = await ctx.run('fetch-users', async () => {
-    return api.fetchUsers(payload.orgId)
-  })
+const syncUsers = durably.defineJob(
+  {
+    name: 'sync-users',
+    input: z.object({ orgId: z.string() }),
+    output: z.object({ syncedCount: z.number() }),
+  },
+  async (context, payload) => {
+    const users = await context.run('fetch-users', async () => {
+      return api.fetchUsers(payload.orgId)
+    })
 
-  await ctx.run('save-to-db', async () => {
-    await db.upsertUsers(users)
-  })
-})
+    await context.run('save-to-db', async () => {
+      await db.upsertUsers(users)
+    })
 
-client.register(syncUsers)
-await client.migrate()
-client.start()
+    return { syncedCount: users.length }
+  },
+)
+
+await durably.migrate()
+durably.start()
 
 await syncUsers.trigger({ orgId: 'org_123' })
 ```
 
+## Documentation
+
+For full documentation, visit [coji.github.io/durably](https://coji.github.io/durably/).
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,55 +1,509 @@
+import { Dialect, Kysely } from 'kysely';
+import { z } from 'zod';
+
 /**
- * durably - Step-oriented resumable batch execution for Node.js and browsers
- *
- * This package is under development. See https://github.com/coji/durably for updates.
+ * Base event interface
  */
-interface ClientOptions {
-    dialect: unknown;
-    pollingInterval?: number;
-    heartbeatInterval?: number;
-    staleThreshold?: number;
+interface BaseEvent {
+    type: string;
+    timestamp: string;
+    sequence: number;
+}
+/**
+ * Run start event
+ */
+interface RunStartEvent extends BaseEvent {
+    type: 'run:start';
+    runId: string;
+    jobName: string;
+    payload: unknown;
+}
+/**
+ * Run complete event
+ */
+interface RunCompleteEvent extends BaseEvent {
+    type: 'run:complete';
+    runId: string;
+    jobName: string;
+    output: unknown;
+    duration: number;
+}
+/**
+ * Run fail event
+ */
+interface RunFailEvent extends BaseEvent {
+    type: 'run:fail';
+    runId: string;
+    jobName: string;
+    error: string;
+    failedStepName: string;
+}
+/**
+ * Step start event
+ */
+interface StepStartEvent extends BaseEvent {
+    type: 'step:start';
+    runId: string;
+    jobName: string;
+    stepName: string;
+    stepIndex: number;
+}
+/**
+ * Step complete event
+ */
+interface StepCompleteEvent extends BaseEvent {
+    type: 'step:complete';
+    runId: string;
+    jobName: string;
+    stepName: string;
+    stepIndex: number;
+    output: unknown;
+    duration: number;
+}
+/**
+ * Step fail event
+ */
+interface StepFailEvent extends BaseEvent {
+    type: 'step:fail';
+    runId: string;
+    jobName: string;
+    stepName: string;
+    stepIndex: number;
+    error: string;
+}
+/**
+ * Log write event
+ */
+interface LogWriteEvent extends BaseEvent {
+    type: 'log:write';
+    runId: string;
+    stepName: string | null;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    data: unknown;
+}
+/**
+ * Worker error event (internal errors like heartbeat failures)
+ */
+interface WorkerErrorEvent extends BaseEvent {
+    type: 'worker:error';
+    error: string;
+    context: string;
+    runId?: string;
+}
+/**
+ * All event types as discriminated union
+ */
+type DurablyEvent = RunStartEvent | RunCompleteEvent | RunFailEvent | StepStartEvent | StepCompleteEvent | StepFailEvent | LogWriteEvent | WorkerErrorEvent;
+/**
+ * Event types for type-safe event names
+ */
+type EventType = DurablyEvent['type'];
+/**
+ * Extract event by type
+ */
+type EventByType<T extends EventType> = Extract<DurablyEvent, {
+    type: T;
+}>;
+/**
+ * Event input (without auto-generated fields)
+ */
+type EventInput<T extends EventType> = Omit<EventByType<T>, 'timestamp' | 'sequence'>;
+/**
+ * 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'>;
+/**
+ * Event listener function
+ */
+type EventListener<T extends EventType> = (event: EventByType<T>) => void;
+/**
+ * Unsubscribe function returned by on()
+ */
+type Unsubscribe = () => void;
+/**
+ * Error handler function for listener exceptions
+ */
+type ErrorHandler = (error: Error, event: DurablyEvent) => void;
+
+/**
+ * Database schema types for Durably
+ */
+interface RunsTable {
+    id: string;
+    job_name: string;
+    payload: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    idempotency_key: string | null;
+    concurrency_key: string | null;
+    current_step_index: number;
+    progress: string | null;
+    output: string | null;
+    error: string | null;
+    heartbeat_at: string;
+    created_at: string;
+    updated_at: string;
+}
+interface StepsTable {
+    id: string;
+    run_id: string;
+    name: string;
+    index: number;
+    status: 'completed' | 'failed';
+    output: string | null;
+    error: string | null;
+    started_at: string;
+    completed_at: string | null;
+}
+interface LogsTable {
+    id: string;
+    run_id: string;
+    step_name: string | null;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    data: string | null;
+    created_at: string;
+}
+interface SchemaVersionsTable {
+    version: number;
+    applied_at: string;
+}
+interface Database {
+    durably_runs: RunsTable;
+    durably_steps: StepsTable;
+    durably_logs: LogsTable;
+    durably_schema_versions: SchemaVersionsTable;
+}
+
+/**
+ * Run data for creating a new run
+ */
+interface CreateRunInput {
+    jobName: string;
+    payload: unknown;
+    idempotencyKey?: string;
+    concurrencyKey?: string;
+}
+/**
+ * Run data returned from storage
+ */
+interface Run {
+    id: string;
+    jobName: string;
+    payload: unknown;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    idempotencyKey: string | null;
+    concurrencyKey: string | null;
+    currentStepIndex: number;
+    progress: {
+        current: number;
+        total?: number;
+        message?: string;
+    } | null;
+    output: unknown | null;
+    error: string | null;
+    heartbeatAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Run update data
+ */
+interface UpdateRunInput {
+    status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    currentStepIndex?: number;
+    progress?: {
+        current: number;
+        total?: number;
+        message?: string;
+    } | null;
+    output?: unknown;
+    error?: string | null;
+    heartbeatAt?: string;
+}
+/**
+ * Run filter options
+ */
+interface RunFilter$1 {
+    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;
 }
-interface JobContext<TPayload> {
-    run<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Step data for creating a new step
+ */
+interface CreateStepInput {
+    runId: string;
+    name: string;
+    index: number;
+    status: 'completed' | 'failed';
+    output?: unknown;
+    error?: string;
+    startedAt: string;
+}
+/**
+ * Step data returned from storage
+ */
+interface Step {
+    id: string;
+    runId: string;
+    name: string;
+    index: number;
+    status: 'completed' | 'failed';
+    output: unknown | null;
+    error: string | null;
+    startedAt: string;
+    completedAt: string | null;
+}
+/**
+ * Log data for creating a new log
+ */
+interface CreateLogInput {
+    runId: string;
+    stepName: string | null;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    data?: unknown;
+}
+/**
+ * Log data returned from storage
+ */
+interface Log {
+    id: string;
+    runId: string;
+    stepName: string | null;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    data: unknown | null;
+    createdAt: string;
+}
+/**
+ * Storage interface for database operations
+ */
+interface Storage {
+    createRun(input: CreateRunInput): Promise<Run>;
+    batchCreateRuns(inputs: CreateRunInput[]): Promise<Run[]>;
+    updateRun(runId: string, data: UpdateRunInput): Promise<void>;
+    deleteRun(runId: string): Promise<void>;
+    getRun(runId: string): Promise<Run | null>;
+    getRuns(filter?: RunFilter$1): Promise<Run[]>;
+    getNextPendingRun(excludeConcurrencyKeys: string[]): Promise<Run | null>;
+    createStep(input: CreateStepInput): Promise<Step>;
+    getSteps(runId: string): Promise<Step[]>;
+    getCompletedStep(runId: string, name: string): Promise<Step | null>;
+    createLog(input: CreateLogInput): Promise<Log>;
+    getLogs(runId: string): Promise<Log[]>;
+}
+
+/**
+ * Job context passed to the job function
+ */
+interface JobContext {
+    /**
+     * The ID of the current run
+     */
+    readonly runId: string;
+    /**
+     * Execute a step with automatic persistence and replay
+     */
+    run<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Report progress for the current run
+     */
+    progress(current: number, total?: number, message?: string): void;
+    /**
+     * Log a message
+     */
     log: {
-        info(message: string, data?: Record<string, unknown>): void;
-        warn(message: string, data?: Record<string, unknown>): void;
-        error(message: string, data?: Record<string, unknown>): void;
+        info(message: string, data?: unknown): void;
+        warn(message: string, data?: unknown): void;
+        error(message: string, data?: unknown): void;
     };
 }
-interface Job<TPayload> {
+/**
+ * Job function type
+ */
+type JobFunction<TInput, TOutput> = (context: JobContext, 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
+ */
+interface TriggerOptions {
+    idempotencyKey?: string;
+    concurrencyKey?: string;
+    /** Timeout in milliseconds for triggerAndWait() */
+    timeout?: number;
+}
+/**
+ * Run filter options
+ */
+interface RunFilter {
+    status?: 'pending' | 'running' | 'completed' | 'failed';
+    jobName?: string;
+}
+/**
+ * Typed run with output type
+ */
+interface TypedRun<TOutput> extends Omit<Run, 'output'> {
+    output: TOutput | null;
+}
+/**
+ * Batch trigger input - either just the input or input with options
+ */
+type BatchTriggerInput<TInput> = TInput | {
+    input: TInput;
+    options?: TriggerOptions;
+};
+/**
+ * Result of triggerAndWait
+ */
+interface TriggerAndWaitResult<TOutput> {
+    id: string;
+    output: TOutput;
+}
+/**
+ * Job handle returned by defineJob
+ */
+interface JobHandle<TName extends string, TInput, TOutput> {
+    readonly name: TName;
+    /**
+     * Trigger a new run
+     */
+    trigger(input: TInput, options?: TriggerOptions): Promise<TypedRun<TOutput>>;
+    /**
+     * Trigger a new run and wait for completion
+     * Returns the output directly, throws if the run fails
+     */
+    triggerAndWait(input: TInput, options?: TriggerOptions): Promise<TriggerAndWaitResult<TOutput>>;
+    /**
+     * Trigger multiple runs in a batch
+     * All inputs are validated before any runs are created
+     */
+    batchTrigger(inputs: BatchTriggerInput<TInput>[]): Promise<TypedRun<TOutput>[]>;
+    /**
+     * Get a run by ID
+     */
+    getRun(id: string): Promise<TypedRun<TOutput> | null>;
+    /**
+     * Get runs with optional filter
+     */
+    getRuns(filter?: Omit<RunFilter, 'jobName'>): Promise<TypedRun<TOutput>[]>;
+}
+
+/**
+ * Options for creating a Durably instance
+ */
+interface DurablyOptions {
+    dialect: Dialect;
+    pollingInterval?: number;
+    heartbeatInterval?: number;
+    staleThreshold?: number;
+}
+/**
+ * Plugin interface for extending Durably
+ */
+interface DurablyPlugin {
     name: string;
-    trigger(payload: TPayload, options?: {
-        idempotencyKey?: string;
-        concurrencyKey?: string;
-    }): Promise<{
-        runId: string;
-    }>;
-    batchTrigger(items: Array<{
-        payload: TPayload;
-        options?: {
-            idempotencyKey?: string;
-            concurrencyKey?: string;
-        };
-    }>): Promise<Array<{
-        runId: string;
-    }>>;
-}
-interface Client {
-    register<TPayload>(job: Job<TPayload>): void;
+    install(durably: Durably): void;
+}
+/**
+ * Durably instance
+ */
+interface Durably {
+    /**
+     * Run database migrations
+     * This is idempotent and safe to call multiple times
+     */
     migrate(): Promise<void>;
+    /**
+     * Get the underlying Kysely database instance
+     * Useful for testing and advanced use cases
+     */
+    readonly db: Kysely<Database>;
+    /**
+     * Storage layer for database operations
+     */
+    readonly storage: Storage;
+    /**
+     * Register an event listener
+     * @returns Unsubscribe function
+     */
+    on<T extends EventType>(type: T, listener: EventListener<T>): Unsubscribe;
+    /**
+     * Emit an event (auto-assigns timestamp and sequence)
+     */
+    emit(event: AnyEventInput): void;
+    /**
+     * Register an error handler for listener exceptions
+     */
+    onError(handler: ErrorHandler): void;
+    /**
+     * Define a job
+     */
+    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>;
+    /**
+     * Start the worker polling loop
+     */
     start(): void;
+    /**
+     * Stop the worker after current run completes
+     */
     stop(): Promise<void>;
+    /**
+     * Retry a failed run by resetting it to pending
+     * @throws Error if run is not in failed status
+     */
     retry(runId: string): Promise<void>;
-    getRuns(filter?: {
-        status?: string;
-    }): Promise<Array<{
-        id: string;
-    }>>;
-    on(event: string, handler: (event: unknown) => void): void;
-    use(plugin: unknown): void;
-}
-declare function createClient(_options: ClientOptions): Client;
-declare function defineJob<TPayload>(_name: string, _handler: (ctx: JobContext<TPayload>, payload: TPayload) => Promise<void>): Job<TPayload>;
-
-export { type Client, type ClientOptions, type Job, type JobContext, createClient, defineJob };
+    /**
+     * Cancel a pending or running run
+     * @throws Error if run is already completed, failed, or cancelled
+     */
+    cancel(runId: string): Promise<void>;
+    /**
+     * Delete a completed, failed, or cancelled run and its associated steps and logs
+     * @throws Error if run is pending or running, or does not exist
+     */
+    deleteRun(runId: string): Promise<void>;
+    /**
+     * Get a run by ID (returns unknown output type)
+     */
+    getRun(runId: string): Promise<Run | null>;
+    /**
+     * Get runs with optional filtering
+     */
+    getRuns(filter?: RunFilter$1): Promise<Run[]>;
+    /**
+     * Register a plugin
+     */
+    use(plugin: DurablyPlugin): void;
+}
+/**
+ * Create a Durably instance
+ */
+declare function createDurably(options: DurablyOptions): Durably;
+
+/**
+ * Plugin that persists log events to the database
+ */
+declare function withLogPersistence(): DurablyPlugin;
+
+/**
+ * Error thrown when a run is cancelled during execution.
+ * The worker catches this error and treats it specially - it does not
+ * mark the run as failed, as the run status is already 'cancelled'.
+ */
+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 JobContext, 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 StepFailEvent, type StepStartEvent, type StepsTable, type TriggerAndWaitResult, type WorkerErrorEvent, createDurably, withLogPersistence };