workmatic 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -1,12 +1,368 @@
+import * as http from 'http';
+import * as better_sqlite3 from 'better-sqlite3';
+import { Kysely, Generated } from 'kysely';
+
 /**
- * Workmatic - A persistent job queue for Node.js
+ * Job status types
+ */
+type JobStatus = 'ready' | 'running' | 'done' | 'failed' | 'dead';
+/**
+ * Database table schema for workmatic_jobs
+ */
+interface WorkmaticJobsTable {
+    id: Generated<number>;
+    public_id: string;
+    queue: string;
+    payload: string;
+    status: JobStatus;
+    priority: number;
+    run_at: number;
+    attempts: number;
+    max_attempts: number;
+    lease_until: number;
+    created_at: number;
+    updated_at: number;
+    last_error: string | null;
+}
+/**
+ * Database table schema for workmatic_settings
+ */
+interface WorkmaticSettingsTable {
+    queue: string;
+    paused: number;
+    updated_at: number;
+}
+/**
+ * Kysely database schema
+ */
+interface WorkmaticDatabase {
+    workmatic_jobs: WorkmaticJobsTable;
+    workmatic_settings: WorkmaticSettingsTable;
+}
+/**
+ * Kysely database instance type
+ */
+type WorkmaticDb = Kysely<WorkmaticDatabase>;
+/**
+ * Job representation returned to users
+ */
+interface Job<TPayload = unknown> {
+    /** Unique public identifier (nanoid) */
+    id: string;
+    /** Queue name */
+    queue: string;
+    /** Job payload */
+    payload: TPayload;
+    /** Current status */
+    status: JobStatus;
+    /** Priority (lower = higher priority) */
+    priority: number;
+    /** Number of attempts made */
+    attempts: number;
+    /** Maximum allowed attempts */
+    maxAttempts: number;
+    /** When the job was created (unix ms) */
+    createdAt: number;
+    /** Last error message if failed */
+    lastError: string | null;
+}
+/**
+ * Options for adding a job
+ */
+interface AddJobOptions {
+    /** Job priority (lower = higher priority). Default: 0 */
+    priority?: number;
+    /** Delay before job becomes available (ms). Default: 0 */
+    delayMs?: number;
+    /** Maximum retry attempts. Default: 3 */
+    maxAttempts?: number;
+}
+/**
+ * Result of adding a job
+ */
+interface AddJobResult {
+    ok: true;
+    id: string;
+}
+/**
+ * Options for creating a database
+ */
+interface DatabaseOptions {
+    /** Existing better-sqlite3 Database instance */
+    db?: better_sqlite3.Database;
+    /** Path to SQLite database file (ignored if db is provided) */
+    filename?: string;
+}
+/**
+ * Options for creating a client
+ */
+interface ClientOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** Queue name. Default: 'default' */
+    queue?: string;
+}
+/**
+ * Backoff function type
+ */
+type BackoffFunction = (attempts: number) => number;
+/**
+ * Options for creating a worker
+ */
+interface WorkerOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** Queue name. Default: 'default' */
+    queue?: string;
+    /** Number of concurrent job processors. Default: 1 */
+    concurrency?: number;
+    /** Lease duration in ms. Default: 30000 */
+    leaseMs?: number;
+    /** Poll interval in ms when no jobs available. Default: 1000 */
+    pollMs?: number;
+    /** Job execution timeout in ms. Default: undefined (no timeout) */
+    timeoutMs?: number;
+    /** Backoff function for retries. Default: exponential */
+    backoff?: BackoffFunction;
+}
+/**
+ * Job processor function type
+ */
+type JobProcessor<TPayload = unknown> = (job: Job<TPayload>) => Promise<void>;
+/**
+ * Stats by status
+ */
+interface JobStats {
+    ready: number;
+    running: number;
+    done: number;
+    failed: number;
+    dead: number;
+    total: number;
+}
+/**
+ * Client interface
+ */
+interface WorkmaticClient {
+    /** Add a job to the queue */
+    add<TPayload = unknown>(payload: TPayload, options?: AddJobOptions): Promise<AddJobResult>;
+    /** Get job statistics */
+    stats(): Promise<JobStats>;
+}
+/**
+ * Worker interface
+ */
+interface WorkmaticWorker {
+    /** Set the job processor function */
+    process<TPayload = unknown>(fn: JobProcessor<TPayload>): void;
+    /** Start processing jobs */
+    start(): void;
+    /** Stop processing jobs (drains current jobs) */
+    stop(): Promise<void>;
+    /** Pause processing (stops claiming new jobs) */
+    pause(): void;
+    /** Resume processing */
+    resume(): void;
+    /** Get job statistics */
+    stats(): Promise<JobStats>;
+    /** Check if worker is running */
+    readonly isRunning: boolean;
+    /** Check if worker is paused */
+    readonly isPaused: boolean;
+    /** Queue name */
+    readonly queue: string;
+}
+/**
+ * Options for creating a dashboard
+ */
+interface DashboardOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** HTTP server port. Default: 3000 */
+    port?: number;
+    /** Worker instances to control */
+    workers?: WorkmaticWorker[];
+}
+/**
+ * Options for creating dashboard middleware
+ */
+interface DashboardMiddlewareOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** Worker instances to control */
+    workers?: WorkmaticWorker[];
+    /** Base path for mounting (e.g., '/workmatic'). Default: '' */
+    basePath?: string;
+}
+/**
+ * Express-compatible request handler
+ */
+type DashboardMiddleware = (req: http.IncomingMessage, res: http.ServerResponse, next?: () => void) => void;
+/**
+ * Dashboard interface
+ */
+interface WorkmaticDashboard {
+    /** Close the dashboard server */
+    close(): Promise<void>;
+    /** Server port */
+    readonly port: number;
+}
+/**
+ * Internal job representation from database
+ */
+interface ClaimedJob {
+    id: number;
+    public_id: string;
+    queue: string;
+    payload: string;
+    attempts: number;
+    max_attempts: number;
+}
+
+/**
+ * Create and initialize the workmatic database
+ *
+ * @param options - Database options
+ * @returns Kysely database instance
+ *
+ * @example
+ * ```ts
+ * // Using a file path
+ * const db = createDatabase({ filename: './jobs.db' });
+ *
+ * // Using an existing better-sqlite3 instance
+ * import Database from 'better-sqlite3';
+ * const sqlite = new Database('./jobs.db');
+ * const db = createDatabase({ db: sqlite });
+ *
+ * // In-memory database (for testing)
+ * const db = createDatabase({ filename: ':memory:' });
+ * ```
+ */
+declare function createDatabase(options?: DatabaseOptions): WorkmaticDb;
+
+/**
+ * Create a job queue client for adding jobs
+ *
+ * @param options - Client options
+ * @returns Client instance
+ *
+ * @example
+ * ```ts
+ * const client = createClient({ db });
+ *
+ * // Add a simple job
+ * const result = await client.add({ email: 'user@example.com' });
+ * console.log(result.id); // Job public ID
+ *
+ * // Add a job with options
+ * await client.add(
+ *   { userId: 123 },
+ *   { priority: 1, delayMs: 5000, maxAttempts: 5 }
+ * );
+ *
+ * // Get queue statistics
+ * const stats = await client.stats();
+ * console.log(stats); // { ready: 5, running: 2, done: 100, ... }
+ * ```
+ */
+declare function createClient(options: ClientOptions): WorkmaticClient;
+
+/**
+ * Create a job queue worker for processing jobs
+ *
+ * @param options - Worker options
+ * @returns Worker instance
+ *
+ * @example
+ * ```ts
+ * const worker = createWorker({ db, concurrency: 4 });
+ *
+ * // Set the processor function
+ * worker.process(async (job) => {
+ *   console.log('Processing job:', job.id);
+ *   await sendEmail(job.payload.email);
+ * });
+ *
+ * // Start processing
+ * worker.start();
+ *
+ * // Later, gracefully stop
+ * await worker.stop();
+ * ```
+ */
+declare function createWorker(options: WorkerOptions): WorkmaticWorker;
+
+/**
+ * Create a dashboard HTTP server for monitoring and controlling the job queue
+ *
+ * @param options - Dashboard options
+ * @returns Dashboard instance
+ *
+ * @example
+ * ```ts
+ * const dashboard = createDashboard({
+ *   db,
+ *   port: 3000,
+ *   workers: [worker1, worker2]
+ * });
+ *
+ * console.log(`Dashboard running at http://localhost:${dashboard.port}`);
+ *
+ * // Later, close the server
+ * await dashboard.close();
+ * ```
+ */
+declare function createDashboard(options: DashboardOptions): WorkmaticDashboard;
+/**
+ * Create an Express-compatible middleware for the dashboard
+ *
+ * @param options - Middleware options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createDashboardMiddleware } from 'workmatic';
+ *
+ * const app = express();
+ *
+ * // Mount dashboard at /workmatic
+ * app.use(createDashboardMiddleware({
+ *   db,
+ *   basePath: '/workmatic',
+ *   workers: [worker]
+ * }));
+ *
+ * app.listen(3000);
+ * // Dashboard available at http://localhost:3000/workmatic
+ * ```
+ */
+declare function createDashboardMiddleware(options: DashboardMiddlewareOptions): DashboardMiddleware;
+
+/**
+ * Default exponential backoff function
+ * Returns delay in milliseconds: 1000 * 2^attempts
+ *
+ * @param attempts - Number of failed attempts
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * ```ts
+ * defaultBackoff(0) // 1000ms (1 second)
+ * defaultBackoff(1) // 2000ms (2 seconds)
+ * defaultBackoff(2) // 4000ms (4 seconds)
+ * defaultBackoff(3) // 8000ms (8 seconds)
+ * ```
+ */
+declare const defaultBackoff: BackoffFunction;
+/**
+ * Validate that a payload is JSON-serializable
  *
- * @packageDocumentation
+ * @param payload - The payload to validate
+ * @throws Error if payload cannot be serialized to JSON
+ * @returns The JSON string representation
  */
-export { createDatabase } from './database.js';
-export { createClient } from './client.js';
-export { createWorker } from './worker.js';
-export { createDashboard, createDashboardMiddleware } from './dashboard.js';
-export { defaultBackoff, validatePayload } from './utils.js';
-export type { Job, JobStatus, JobStats, ClaimedJob, AddJobOptions, AddJobResult, DatabaseOptions, ClientOptions, WorkerOptions, DashboardOptions, DashboardMiddlewareOptions, BackoffFunction, JobProcessor, WorkmaticClient, WorkmaticWorker, WorkmaticDashboard, DashboardMiddleware, WorkmaticDb, WorkmaticDatabase, WorkmaticJobsTable, } from './types.js';
-//# sourceMappingURL=index.d.ts.map
+declare function validatePayload(payload: unknown): string;
+
+export { type AddJobOptions, type AddJobResult, type BackoffFunction, type ClaimedJob, type ClientOptions, type DashboardMiddleware, type DashboardMiddlewareOptions, type DashboardOptions, type DatabaseOptions, type Job, type JobProcessor, type JobStats, type JobStatus, type WorkerOptions, type WorkmaticClient, type WorkmaticDashboard, type WorkmaticDatabase, type WorkmaticDb, type WorkmaticJobsTable, type WorkmaticWorker, createClient, createDashboard, createDashboardMiddleware, createDatabase, createWorker, defaultBackoff, validatePayload };