workmatic 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,218 @@
+import type { Kysely, Generated } from 'kysely';
+/**
+ * Job status types
+ */
+export type JobStatus = 'ready' | 'running' | 'done' | 'failed' | 'dead';
+/**
+ * Database table schema for workmatic_jobs
+ */
+export 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
+ */
+export interface WorkmaticSettingsTable {
+    queue: string;
+    paused: number;
+    updated_at: number;
+}
+/**
+ * Kysely database schema
+ */
+export interface WorkmaticDatabase {
+    workmatic_jobs: WorkmaticJobsTable;
+    workmatic_settings: WorkmaticSettingsTable;
+}
+/**
+ * Kysely database instance type
+ */
+export type WorkmaticDb = Kysely<WorkmaticDatabase>;
+/**
+ * Job representation returned to users
+ */
+export 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
+ */
+export 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
+ */
+export interface AddJobResult {
+    ok: true;
+    id: string;
+}
+/**
+ * Options for creating a database
+ */
+export interface DatabaseOptions {
+    /** Existing better-sqlite3 Database instance */
+    db?: import('better-sqlite3').Database;
+    /** Path to SQLite database file (ignored if db is provided) */
+    filename?: string;
+}
+/**
+ * Options for creating a client
+ */
+export interface ClientOptions {
+    /** Kysely database instance */
+    db: WorkmaticDb;
+    /** Queue name. Default: 'default' */
+    queue?: string;
+}
+/**
+ * Backoff function type
+ */
+export type BackoffFunction = (attempts: number) => number;
+/**
+ * Options for creating a worker
+ */
+export 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
+ */
+export type JobProcessor<TPayload = unknown> = (job: Job<TPayload>) => Promise<void>;
+/**
+ * Stats by status
+ */
+export interface JobStats {
+    ready: number;
+    running: number;
+    done: number;
+    failed: number;
+    dead: number;
+    total: number;
+}
+/**
+ * Client interface
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export type DashboardMiddleware = (req: import('http').IncomingMessage, res: import('http').ServerResponse, next?: () => void) => void;
+/**
+ * Dashboard interface
+ */
+export interface WorkmaticDashboard {
+    /** Close the dashboard server */
+    close(): Promise<void>;
+    /** Server port */
+    readonly port: number;
+}
+/**
+ * Internal job representation from database
+ */
+export interface ClaimedJob {
+    id: number;
+    public_id: string;
+    queue: string;
+    payload: string;
+    attempts: number;
+    max_attempts: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,45 @@
+import type { BackoffFunction } from './types.js';
+/**
+ * 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)
+ * ```
+ */
+export declare const defaultBackoff: BackoffFunction;
+/**
+ * Validate that a payload is JSON-serializable
+ *
+ * @param payload - The payload to validate
+ * @throws Error if payload cannot be serialized to JSON
+ * @returns The JSON string representation
+ */
+export declare function validatePayload(payload: unknown): string;
+/**
+ * Parse a JSON payload safely
+ *
+ * @param json - JSON string to parse
+ * @returns Parsed payload
+ * @throws Error if JSON is invalid
+ */
+export declare function parsePayload<T = unknown>(json: string): T;
+/**
+ * Sleep for a specified duration
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Promise that resolves after the duration
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Get current timestamp in milliseconds
+ */
+export declare function now(): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,eAE5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAQxD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAQzD;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;GAEG;AACH,wBAAgB,GAAG,IAAI,MAAM,CAE5B"}

package/dist/utils.js

@@ -0,0 +1,64 @@
+/**
+ * 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)
+ * ```
+ */
+export const defaultBackoff = (attempts) => {
+    return 1000 * Math.pow(2, attempts);
+};
+/**
+ * Validate that a payload is JSON-serializable
+ *
+ * @param payload - The payload to validate
+ * @throws Error if payload cannot be serialized to JSON
+ * @returns The JSON string representation
+ */
+export function validatePayload(payload) {
+    try {
+        return JSON.stringify(payload);
+    }
+    catch (error) {
+        throw new Error(`Payload is not JSON-serializable: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Parse a JSON payload safely
+ *
+ * @param json - JSON string to parse
+ * @returns Parsed payload
+ * @throws Error if JSON is invalid
+ */
+export function parsePayload(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON payload: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Sleep for a specified duration
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Promise that resolves after the duration
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Get current timestamp in milliseconds
+ */
+export function now() {
+    return Date.now();
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAoB,CAAC,QAAgB,EAAU,EAAE;IAC1E,OAAO,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,qCAAqC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CAChG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAc,IAAY;IACpD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CACpF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG;IACjB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;AACpB,CAAC"}

package/dist/worker.d.ts

@@ -0,0 +1,26 @@
+import type { WorkerOptions, WorkmaticWorker } from './types.js';
+/**
+ * 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();
+ * ```
+ */
+export declare function createWorker(options: WorkerOptions): WorkmaticWorker;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,aAAa,EACb,eAAe,EAMhB,MAAM,YAAY,CAAC;AAGpB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAgXpE"}