workmatic 1.0.5 → 1.1.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import * as http from 'http';
 import * as better_sqlite3 from 'better-sqlite3';
+import better_sqlite3__default from 'better-sqlite3';
+import * as http from 'http';
 import { Kysely, Generated } from 'kysely';
 
 /**
  * Job status types
  */
-type JobStatus = 'ready' | 'running' | 'done' | 'failed' | 'dead';
+type JobStatus = 'ready' | 'running' | 'done' | 'dead';
 /**
  * Database table schema for workmatic_jobs
  */
@@ -63,7 +64,7 @@ interface Job<TPayload = unknown> {
     maxAttempts: number;
     /** When the job was created (unix ms) */
     createdAt: number;
-    /** Last error message if failed */
+    /** Last error from a previous attempt (e.g. before retry) */
     lastError: string | null;
 }
 /**
@@ -84,6 +85,13 @@ interface AddJobResult {
     ok: true;
     id: string;
 }
+/**
+ * Result of adding multiple jobs in one transaction
+ */
+interface AddManyResult {
+    ok: true;
+    ids: string[];
+}
 /**
  * Options for creating a database
  */
@@ -124,7 +132,7 @@ interface WorkerOptions {
     leaseMs?: number;
     /** Poll interval in ms when no jobs available. Default: 1000 */
     pollMs?: number;
-    /** Job execution timeout in ms. Default: undefined (no timeout) */
+    /** Job execution timeout in ms. Default: 60000 (1 min). Set to 0 to disable. */
     timeoutMs?: number;
     /** Backoff function for retries. Default: exponential */
     backoff?: BackoffFunction;
@@ -132,6 +140,18 @@ interface WorkerOptions {
     persistState?: boolean;
     /** Auto-restore worker state on creation. Default: true (only applies if persistState is true) */
     autoRestore?: boolean;
+    /**
+     * Minimum interval between database pause checks (CLI `pause`). Reduces round-trips while pumping.
+     * Default: 300 ms
+     */
+    pauseCheckIntervalMs?: number;
+    /**
+     * Minimum interval between lease requeue scans. Default: every pump (0).
+     * Set to e.g. 1000 to run expired-lease recovery at most once per second.
+     */
+    requeueExpiredIntervalMs?: number;
+    /** Called when the pump loop catches an error (after optional default logging) */
+    onPumpError?: (error: unknown) => void;
 }
 /**
  * Job processor function type
@@ -144,7 +164,6 @@ interface JobStats {
     ready: number;
     running: number;
     done: number;
-    failed: number;
     dead: number;
     total: number;
 }
@@ -154,6 +173,11 @@ interface JobStats {
 interface WorkmaticClient {
     /** Add a job to the queue */
     add<TPayload = unknown>(payload: TPayload, options?: AddJobOptions): Promise<AddJobResult>;
+    /**
+     * Add many jobs in a single transaction (shared priority, delay, maxAttempts).
+     * Faster than repeated `add()` when inserting large batches.
+     */
+    addMany<TPayload = unknown>(payloads: TPayload[], options?: AddJobOptions): Promise<AddManyResult>;
     /** Get job statistics */
     stats(): Promise<JobStats>;
     /** Clear all jobs from the queue */
@@ -225,6 +249,78 @@ interface WorkmaticDashboard {
     /** Server port */
     readonly port: number;
 }
+/**
+ * Options for creating an orchestrator
+ */
+interface OrchestratorOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+}
+/**
+ * Options when registering a queue with the orchestrator
+ */
+interface RegisterQueueOptions {
+    /** Create a worker for this queue (omit for client-only) */
+    worker?: Omit<WorkerOptions, 'db' | 'queue'>;
+}
+/**
+ * Options for bulk transfer between queues
+ */
+interface TransferOptions {
+    /** Source queue name */
+    from: string;
+    /** Target queue name */
+    to: string;
+    /**
+     * Job statuses to transfer. Default: `['ready', 'dead']`.
+     * `running` and `done` are excluded by default for safety.
+     */
+    status?: JobStatus | JobStatus[];
+    /** Max jobs to move (default: 10000) */
+    limit?: number;
+    /** When moving `dead` jobs, reset to `ready` with attempts cleared (retry queue) */
+    resetForRetry?: boolean;
+}
+/**
+ * Result of a bulk transfer
+ */
+interface TransferResult {
+    moved: number;
+}
+/**
+ * Options for moving a single job by public id
+ */
+interface MoveJobOptions {
+    /** Allowed source statuses (default: ready, dead) */
+    status?: JobStatus | JobStatus[];
+    /** Reset dead job for retry in target queue */
+    resetForRetry?: boolean;
+}
+/**
+ * Multi-queue orchestrator interface
+ */
+interface WorkmaticOrchestrator {
+    /** Register a queue (client + optional worker) */
+    register(queue: string, options?: RegisterQueueOptions): WorkmaticClient;
+    /** Get client for a queue (lazy-creates if not registered) */
+    client(queue: string): WorkmaticClient;
+    /** Get worker for a queue (must be registered with worker option) */
+    worker(queue: string): WorkmaticWorker;
+    /** All registered workers (for dashboard) */
+    workers(): WorkmaticWorker[];
+    /** Queue names from DB and registry */
+    queues(): Promise<string[]>;
+    /** Set processor on a registered worker */
+    process<TPayload = unknown>(queue: string, fn: JobProcessor<TPayload>): void;
+    startAll(): void;
+    stopAll(): Promise<void>;
+    pause(queue: string): Promise<void>;
+    resume(queue: string): Promise<void>;
+    isPaused(queue: string): Promise<boolean>;
+    stats(queue?: string): Promise<Record<string, JobStats>>;
+    transfer(options: TransferOptions): Promise<TransferResult>;
+    moveJob(publicId: string, toQueue: string, options?: MoveJobOptions): Promise<void>;
+}
 /**
  * Internal job representation from database
  */
@@ -235,6 +331,9 @@ interface ClaimedJob {
     payload: string;
     attempts: number;
     max_attempts: number;
+    priority: number;
+    created_at: number;
+    last_error: string | null;
 }
 
 /**
@@ -258,6 +357,12 @@ interface ClaimedJob {
  * ```
  */
 declare function createDatabase(options?: DatabaseOptions): WorkmaticDb;
+/**
+ * Get the underlying better-sqlite3 database instance from a Kysely instance
+ * created with {@link createDatabase}. For manually constructed `Kysely` instances,
+ * falls back to reading the dialect adapter (may break across Kysely versions).
+ */
+declare function getUnderlyingDb(db: WorkmaticDb): better_sqlite3__default.Database;
 
 /**
  * Create a job queue client for adding jobs
@@ -286,6 +391,8 @@ declare function createDatabase(options?: DatabaseOptions): WorkmaticDb;
  */
 declare function createClient(options: ClientOptions): WorkmaticClient;
 
+/** Default job execution timeout when `timeoutMs` is omitted (1 minute). Use `timeoutMs: 0` for no limit. */
+declare const DEFAULT_WORKER_TIMEOUT_MS = 60000;
 /**
  * Create a job queue worker for processing jobs
  *
@@ -311,6 +418,11 @@ declare function createClient(options: ClientOptions): WorkmaticClient;
  */
 declare function createWorker(options: WorkerOptions): WorkmaticWorker;
 
+/**
+ * Create a multi-queue orchestrator for registration, lifecycle, and transfers.
+ */
+declare function createOrchestrator(options: OrchestratorOptions): WorkmaticOrchestrator;
+
 /**
  * Create a dashboard HTTP server for monitoring and controlling the job queue
  *
@@ -383,4 +495,4 @@ declare const defaultBackoff: BackoffFunction;
  */
 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 WorkerState, type WorkmaticClient, type WorkmaticDashboard, type WorkmaticDatabase, type WorkmaticDb, type WorkmaticJobsTable, type WorkmaticWorker, createClient, createDashboard, createDashboardMiddleware, createDatabase, createWorker, defaultBackoff, validatePayload };
+export { type AddJobOptions, type AddJobResult, type AddManyResult, type BackoffFunction, type ClaimedJob, type ClientOptions, DEFAULT_WORKER_TIMEOUT_MS, type DashboardMiddleware, type DashboardMiddlewareOptions, type DashboardOptions, type DatabaseOptions, type Job, type JobProcessor, type JobStats, type JobStatus, type MoveJobOptions, type OrchestratorOptions, type RegisterQueueOptions, type TransferOptions, type TransferResult, type WorkerOptions, type WorkerState, type WorkmaticClient, type WorkmaticDashboard, type WorkmaticDatabase, type WorkmaticDb, type WorkmaticJobsTable, type WorkmaticOrchestrator, type WorkmaticWorker, createClient, createDashboard, createDashboardMiddleware, createDatabase, createOrchestrator, createWorker, defaultBackoff, getUnderlyingDb, validatePayload };