workmatic 1.1.2 → 1.2.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import * as better_sqlite3 from 'better-sqlite3';
-import better_sqlite3__default from 'better-sqlite3';
+import * as Database from 'better-sqlite3';
+import Database__default from 'better-sqlite3';
 import * as http from 'http';
 import { Kysely, Generated } from 'kysely';
 
@@ -97,9 +97,11 @@ interface AddManyResult {
  */
 interface DatabaseOptions {
     /** Existing better-sqlite3 Database instance */
-    db?: better_sqlite3.Database;
+    db?: Database.Database;
     /** Path to SQLite database file (ignored if db is provided) */
     filename?: string;
+    /** Maximum number of prepared statements to cache. Default: 1000. Set to 0 to disable. */
+    statementCacheSize?: number;
 }
 /**
  * Options for creating a client
@@ -109,6 +111,10 @@ interface ClientOptions {
     db: WorkmaticDb;
     /** Queue name. Default: 'default' */
     queue?: string;
+    /** Optional callback to notify immediately when a ready job is added */
+    onJobAdded?: () => void;
+    /** Optional worker instance to wake up immediately when a ready job is added */
+    worker?: WorkmaticWorker;
 }
 /**
  * Backoff function type
@@ -152,6 +158,11 @@ interface WorkerOptions {
     requeueExpiredIntervalMs?: number;
     /** Called when the pump loop catches an error (after optional default logging) */
     onPumpError?: (error: unknown) => void;
+    /**
+     * Maximum number of completions to batch before flushing to the database.
+     * Default: 50. Set to 0 to disable completion micro-batching.
+     */
+    completionBatchSize?: number;
 }
 /**
  * Job processor function type
@@ -207,6 +218,12 @@ interface WorkmaticWorker {
     clear(options?: {
         status?: JobStatus;
     }): Promise<number>;
+    /** Wake up the worker immediately to check for jobs without waiting for pollMs */
+    wakeUp(): void;
+    /** Flush any pending buffered completion updates to the database */
+    flushCompletions(): Promise<void>;
+    /** Attach OS signal handlers (SIGINT, SIGTERM) for graceful shutdown */
+    attachSignalHandlers(options?: GracefulShutdownOptions): () => void;
     /** Check if worker is running */
     readonly isRunning: boolean;
     /** Check if worker is paused */
@@ -320,6 +337,29 @@ interface WorkmaticOrchestrator {
     stats(queue?: string): Promise<Record<string, JobStats>>;
     transfer(options: TransferOptions): Promise<TransferResult>;
     moveJob(publicId: string, toQueue: string, options?: MoveJobOptions): Promise<void>;
+    /** Attach OS signal handlers (SIGINT, SIGTERM) for graceful shutdown of all workers */
+    attachSignalHandlers(options?: GracefulShutdownOptions): () => void;
+}
+/**
+ * Options for configuring graceful shutdown signal listeners
+ */
+interface GracefulShutdownOptions {
+    /** OS signals to listen for. Default: ['SIGINT', 'SIGTERM'] */
+    signals?: NodeJS.Signals[];
+    /** Maximum time in ms to wait for jobs to drain before forced exit. Default: 30000 */
+    timeoutMs?: number;
+    /** Whether to call process.exit when shutdown finishes or times out. Default: true */
+    exitOnComplete?: boolean;
+    /** Process exit code on clean shutdown. Default: 0 */
+    exitCode?: number;
+    /** Process exit code when shutdown times out or errors. Default: 1 */
+    timeoutExitCode?: number;
+    /** Callback triggered when shutdown begins */
+    onShutdownStart?: (signal: NodeJS.Signals) => void;
+    /** Callback triggered after shutdown finishes successfully */
+    onShutdownComplete?: () => void;
+    /** Callback triggered if shutdown times out or fails */
+    onShutdownError?: (error: unknown) => void;
 }
 /**
  * Internal job representation from database
@@ -335,6 +375,61 @@ interface ClaimedJob {
     created_at: number;
     last_error: string | null;
 }
+/**
+ * Event emitted when a job status is updated
+ */
+interface JobStatusChangeEvent {
+    publicId: string;
+    queue: string;
+    previousStatus: JobStatus;
+    status: JobStatus;
+    timestamp: number;
+    error?: string | null;
+}
+/**
+ * Options for creating an MCP server
+ */
+interface McpServerOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** Input readable stream (default: process.stdin) */
+    input?: NodeJS.ReadableStream;
+    /** Output writable stream (default: process.stdout) */
+    output?: NodeJS.WritableStream;
+    /** Optional orchestrator instance to wake up workers on status change */
+    orchestrator?: WorkmaticOrchestrator;
+    /** Optional worker instances to wake up on status change */
+    workers?: WorkmaticWorker[];
+    /** Optional callback invoked whenever a job status changes */
+    onJobStatusChanged?: (event: JobStatusChangeEvent) => void;
+}
+/**
+ * Tool definition for Model Context Protocol (MCP)
+ */
+interface McpToolDefinition$1 {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * MCP Server interface
+ */
+interface WorkmaticMcpServer {
+    /** Start listening for JSON-RPC messages */
+    start(): void;
+    /** Stop listening and close streams */
+    stop(): void;
+    /** Handle a raw JSON-RPC string message */
+    handleMessage(raw: string): Promise<string | null>;
+    /** Register event listener for job status changes */
+    on(event: 'jobStatusChanged', listener: (event: JobStatusChangeEvent) => void): this;
+    /** Remove event listener for job status changes */
+    off(event: 'jobStatusChanged', listener: (event: JobStatusChangeEvent) => void): this;
+}
 
 /**
  * Create and initialize the workmatic database
@@ -362,7 +457,16 @@ declare function createDatabase(options?: DatabaseOptions): WorkmaticDb;
  * 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;
+declare function getUnderlyingDb(db: WorkmaticDb): Database__default.Database;
+/**
+ * Enable prepared statement caching on a better-sqlite3 database instance.
+ * Reuses compiled statements across queries, bypassing SQLite SQL parsing
+ * and bytecode recompilation on repeated queries.
+ *
+ * @param db - better-sqlite3 database instance
+ * @param maxStatements - Maximum cached statements (default: 1000). Set <= 0 to disable.
+ */
+declare function enableStatementCache(db: Database__default.Database, maxStatements?: number): Database__default.Database;
 
 /**
  * Create a job queue client for adding jobs
@@ -470,6 +574,52 @@ declare function createDashboard(options: DashboardOptions): WorkmaticDashboard;
  */
 declare function createDashboardMiddleware(options: DashboardMiddlewareOptions): DashboardMiddleware;
 
+type GracefulShutdownTarget = WorkmaticWorker | WorkmaticOrchestrator | WorkmaticWorker[];
+/**
+ * Attach OS signal listeners (SIGINT, SIGTERM) to gracefully stop a worker,
+ * an orchestrator, or a group of workers before the process exits.
+ *
+ * @param target - Worker, orchestrator, or array of workers to stop
+ * @param options - Graceful shutdown options
+ * @returns Detach function that unregisters the signal listeners
+ *
+ * @example
+ * ```ts
+ * const worker = createWorker({ db });
+ * worker.start();
+ *
+ * const detach = attachGracefulShutdown(worker, {
+ *   timeoutMs: 15000,
+ *   onShutdownComplete: () => console.log('All jobs finished, shutting down'),
+ * });
+ * ```
+ */
+declare function attachGracefulShutdown(target: GracefulShutdownTarget, options?: GracefulShutdownOptions): () => void;
+
+/**
+ * Creates a lightweight stdio JSON-RPC 2.0 MCP server for Workmatic.
+ * Conforms to the MCP Specification (protocol version 2024-11-05).
+ */
+declare function createMcpServer(options: McpServerOptions): WorkmaticMcpServer;
+
+interface ToolExecutionContext {
+    onJobStatusChanged?: (event: JobStatusChangeEvent) => void;
+}
+interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+declare const MCP_TOOL_DEFINITIONS: McpToolDefinition[];
+/**
+ * Execute an MCP tool invocation against a Workmatic database
+ */
+declare function executeTool(db: WorkmaticDb, name: string, args?: Record<string, unknown>, context?: ToolExecutionContext): Promise<unknown>;
+
 /**
  * Default exponential backoff function
  * Returns delay in milliseconds: 1000 * 2^attempts
@@ -495,4 +645,4 @@ declare const defaultBackoff: BackoffFunction;
  */
 declare function validatePayload(payload: unknown): string;
 
-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 };
+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 GracefulShutdownOptions, type Job, type JobProcessor, type JobStats, type JobStatus, type JobStatusChangeEvent, MCP_TOOL_DEFINITIONS, type McpServerOptions, type McpToolDefinition$1 as McpToolDefinition, 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 WorkmaticMcpServer, type WorkmaticOrchestrator, type WorkmaticWorker, attachGracefulShutdown, createClient, createDashboard, createDashboardMiddleware, createDatabase, createMcpServer, createOrchestrator, createWorker, defaultBackoff, enableStatementCache, executeTool, getUnderlyingDb, validatePayload };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import * as better_sqlite3 from 'better-sqlite3';
-import better_sqlite3__default from 'better-sqlite3';
+import * as Database from 'better-sqlite3';
+import Database__default from 'better-sqlite3';
 import * as http from 'http';
 import { Kysely, Generated } from 'kysely';
 
@@ -97,9 +97,11 @@ interface AddManyResult {
  */
 interface DatabaseOptions {
     /** Existing better-sqlite3 Database instance */
-    db?: better_sqlite3.Database;
+    db?: Database.Database;
     /** Path to SQLite database file (ignored if db is provided) */
     filename?: string;
+    /** Maximum number of prepared statements to cache. Default: 1000. Set to 0 to disable. */
+    statementCacheSize?: number;
 }
 /**
  * Options for creating a client
@@ -109,6 +111,10 @@ interface ClientOptions {
     db: WorkmaticDb;
     /** Queue name. Default: 'default' */
     queue?: string;
+    /** Optional callback to notify immediately when a ready job is added */
+    onJobAdded?: () => void;
+    /** Optional worker instance to wake up immediately when a ready job is added */
+    worker?: WorkmaticWorker;
 }
 /**
  * Backoff function type
@@ -152,6 +158,11 @@ interface WorkerOptions {
     requeueExpiredIntervalMs?: number;
     /** Called when the pump loop catches an error (after optional default logging) */
     onPumpError?: (error: unknown) => void;
+    /**
+     * Maximum number of completions to batch before flushing to the database.
+     * Default: 50. Set to 0 to disable completion micro-batching.
+     */
+    completionBatchSize?: number;
 }
 /**
  * Job processor function type
@@ -207,6 +218,12 @@ interface WorkmaticWorker {
     clear(options?: {
         status?: JobStatus;
     }): Promise<number>;
+    /** Wake up the worker immediately to check for jobs without waiting for pollMs */
+    wakeUp(): void;
+    /** Flush any pending buffered completion updates to the database */
+    flushCompletions(): Promise<void>;
+    /** Attach OS signal handlers (SIGINT, SIGTERM) for graceful shutdown */
+    attachSignalHandlers(options?: GracefulShutdownOptions): () => void;
     /** Check if worker is running */
     readonly isRunning: boolean;
     /** Check if worker is paused */
@@ -320,6 +337,29 @@ interface WorkmaticOrchestrator {
     stats(queue?: string): Promise<Record<string, JobStats>>;
     transfer(options: TransferOptions): Promise<TransferResult>;
     moveJob(publicId: string, toQueue: string, options?: MoveJobOptions): Promise<void>;
+    /** Attach OS signal handlers (SIGINT, SIGTERM) for graceful shutdown of all workers */
+    attachSignalHandlers(options?: GracefulShutdownOptions): () => void;
+}
+/**
+ * Options for configuring graceful shutdown signal listeners
+ */
+interface GracefulShutdownOptions {
+    /** OS signals to listen for. Default: ['SIGINT', 'SIGTERM'] */
+    signals?: NodeJS.Signals[];
+    /** Maximum time in ms to wait for jobs to drain before forced exit. Default: 30000 */
+    timeoutMs?: number;
+    /** Whether to call process.exit when shutdown finishes or times out. Default: true */
+    exitOnComplete?: boolean;
+    /** Process exit code on clean shutdown. Default: 0 */
+    exitCode?: number;
+    /** Process exit code when shutdown times out or errors. Default: 1 */
+    timeoutExitCode?: number;
+    /** Callback triggered when shutdown begins */
+    onShutdownStart?: (signal: NodeJS.Signals) => void;
+    /** Callback triggered after shutdown finishes successfully */
+    onShutdownComplete?: () => void;
+    /** Callback triggered if shutdown times out or fails */
+    onShutdownError?: (error: unknown) => void;
 }
 /**
  * Internal job representation from database
@@ -335,6 +375,61 @@ interface ClaimedJob {
     created_at: number;
     last_error: string | null;
 }
+/**
+ * Event emitted when a job status is updated
+ */
+interface JobStatusChangeEvent {
+    publicId: string;
+    queue: string;
+    previousStatus: JobStatus;
+    status: JobStatus;
+    timestamp: number;
+    error?: string | null;
+}
+/**
+ * Options for creating an MCP server
+ */
+interface McpServerOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** Input readable stream (default: process.stdin) */
+    input?: NodeJS.ReadableStream;
+    /** Output writable stream (default: process.stdout) */
+    output?: NodeJS.WritableStream;
+    /** Optional orchestrator instance to wake up workers on status change */
+    orchestrator?: WorkmaticOrchestrator;
+    /** Optional worker instances to wake up on status change */
+    workers?: WorkmaticWorker[];
+    /** Optional callback invoked whenever a job status changes */
+    onJobStatusChanged?: (event: JobStatusChangeEvent) => void;
+}
+/**
+ * Tool definition for Model Context Protocol (MCP)
+ */
+interface McpToolDefinition$1 {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * MCP Server interface
+ */
+interface WorkmaticMcpServer {
+    /** Start listening for JSON-RPC messages */
+    start(): void;
+    /** Stop listening and close streams */
+    stop(): void;
+    /** Handle a raw JSON-RPC string message */
+    handleMessage(raw: string): Promise<string | null>;
+    /** Register event listener for job status changes */
+    on(event: 'jobStatusChanged', listener: (event: JobStatusChangeEvent) => void): this;
+    /** Remove event listener for job status changes */
+    off(event: 'jobStatusChanged', listener: (event: JobStatusChangeEvent) => void): this;
+}
 
 /**
  * Create and initialize the workmatic database
@@ -362,7 +457,16 @@ declare function createDatabase(options?: DatabaseOptions): WorkmaticDb;
  * 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;
+declare function getUnderlyingDb(db: WorkmaticDb): Database__default.Database;
+/**
+ * Enable prepared statement caching on a better-sqlite3 database instance.
+ * Reuses compiled statements across queries, bypassing SQLite SQL parsing
+ * and bytecode recompilation on repeated queries.
+ *
+ * @param db - better-sqlite3 database instance
+ * @param maxStatements - Maximum cached statements (default: 1000). Set <= 0 to disable.
+ */
+declare function enableStatementCache(db: Database__default.Database, maxStatements?: number): Database__default.Database;
 
 /**
  * Create a job queue client for adding jobs
@@ -470,6 +574,52 @@ declare function createDashboard(options: DashboardOptions): WorkmaticDashboard;
  */
 declare function createDashboardMiddleware(options: DashboardMiddlewareOptions): DashboardMiddleware;
 
+type GracefulShutdownTarget = WorkmaticWorker | WorkmaticOrchestrator | WorkmaticWorker[];
+/**
+ * Attach OS signal listeners (SIGINT, SIGTERM) to gracefully stop a worker,
+ * an orchestrator, or a group of workers before the process exits.
+ *
+ * @param target - Worker, orchestrator, or array of workers to stop
+ * @param options - Graceful shutdown options
+ * @returns Detach function that unregisters the signal listeners
+ *
+ * @example
+ * ```ts
+ * const worker = createWorker({ db });
+ * worker.start();
+ *
+ * const detach = attachGracefulShutdown(worker, {
+ *   timeoutMs: 15000,
+ *   onShutdownComplete: () => console.log('All jobs finished, shutting down'),
+ * });
+ * ```
+ */
+declare function attachGracefulShutdown(target: GracefulShutdownTarget, options?: GracefulShutdownOptions): () => void;
+
+/**
+ * Creates a lightweight stdio JSON-RPC 2.0 MCP server for Workmatic.
+ * Conforms to the MCP Specification (protocol version 2024-11-05).
+ */
+declare function createMcpServer(options: McpServerOptions): WorkmaticMcpServer;
+
+interface ToolExecutionContext {
+    onJobStatusChanged?: (event: JobStatusChangeEvent) => void;
+}
+interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+declare const MCP_TOOL_DEFINITIONS: McpToolDefinition[];
+/**
+ * Execute an MCP tool invocation against a Workmatic database
+ */
+declare function executeTool(db: WorkmaticDb, name: string, args?: Record<string, unknown>, context?: ToolExecutionContext): Promise<unknown>;
+
 /**
  * Default exponential backoff function
  * Returns delay in milliseconds: 1000 * 2^attempts
@@ -495,4 +645,4 @@ declare const defaultBackoff: BackoffFunction;
  */
 declare function validatePayload(payload: unknown): string;
 
-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 };
+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 GracefulShutdownOptions, type Job, type JobProcessor, type JobStats, type JobStatus, type JobStatusChangeEvent, MCP_TOOL_DEFINITIONS, type McpServerOptions, type McpToolDefinition$1 as McpToolDefinition, 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 WorkmaticMcpServer, type WorkmaticOrchestrator, type WorkmaticWorker, attachGracefulShutdown, createClient, createDashboard, createDashboardMiddleware, createDatabase, createMcpServer, createOrchestrator, createWorker, defaultBackoff, enableStatementCache, executeTool, getUnderlyingDb, validatePayload };