tspace-mysql
Version:
Tspace MySQL is a promise-based ORM for Node.js, designed with modern TypeScript and providing type safety for schema databases.
241 lines (240 loc) • 7.87 kB
TypeScript
import type { T } from "./UtilityTypes";
import { Blueprint } from "./Blueprint";
import { Model } from "./Model";
export type Job<T = any> = {
id: number;
name: string;
status: 'pending' | 'active' | 'completed' | 'failed';
payload: T;
};
type Handler = (job: Job) => any | Promise<any>;
type QueueAddOptions = {
delayMs?: number;
priority?: number;
metadata?: Record<string, any>;
maxAttempts?: number;
};
type QueueProcessOptions = {
interval?: number;
concurrency?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 15 | 20 | 25 | 30;
};
declare const schema: {
id: Blueprint<number>;
uuid: Blueprint<string | null>;
name: Blueprint<string>;
status: Blueprint<"pending" | "active" | "completed" | "failed">;
priority: Blueprint<number>;
payload: Blueprint<string | null>;
result: Blueprint<string | null>;
error: Blueprint<string | null>;
metadata: Blueprint<string | null>;
attempts: Blueprint<number>;
max_attempts: Blueprint<number>;
locked_by: Blueprint<string | null>;
locked_at: Blueprint<string | Date | null>;
available_at: Blueprint<string | Date>;
completed_at: Blueprint<string | Date | null>;
created_at: Blueprint<string | Date | null>;
updated_at: Blueprint<string | Date | null>;
};
type TS = T.Schema<typeof schema>;
declare class Worker extends Model<TS> {
private HOSTNAME;
private INSPECT_EXEC;
private STOPPING;
private IS_FLUSHING;
private LIMIT_CONNECTIONS;
private MAX_IDLE_RETRIES;
private ACTIVE_JOBS;
private BATCH_SIZE;
private MAX_WAIT_MS;
private BUFFER;
private WORKER_STATE;
protected boot(): void;
initialize(opts?: {
inspect?: boolean;
flush?: boolean;
hostname?: string;
maxIdleRetries?: number;
limitConnections?: number;
}): Promise<this>;
shutdown(): Promise<void>;
flush(): Promise<void>;
getJobOverallStats(name?: string): Promise<{
total: number;
completed: number;
active: number;
pending: number;
failed: number;
}>;
getJobStats(name?: string): Promise<{
name: string;
completed: number;
active: number;
pending: number;
failed: number;
}[]>;
getNames(): Promise<any[]>;
add(name: string, payload: any, opts?: QueueAddOptions): Promise<void>;
process(name: string, handler: Handler, opts?: QueueProcessOptions): Promise<void>;
private _runJob;
private _waitForSafeConnections;
private _dequeueMany;
private _flushBuffer;
private _wakeWorker;
private safeJsonParse;
private safeJsonStringify;
}
/**
* Queue facade class (static API wrapper)
*
* This class provides a singleton-style interface over the underlying Worker instance.
* It must be initialized before use via `Queue.start()`.
*
* @example
* ```ts
* const sendEmail = (job) => console.log('send mail :' + job.payload.email)
*
* await Queue.start({ inspect : true, flush : true // **remove all jobs });
*
* // register
* Queue.progress("send-email", async (job) => {
* return await sendEmail(job);
* }, { concurrency : 3 });
*
* // add
* Queue.add("send-email", { email: "test@gmail.com" });
*
* ```
*/
declare class Queue {
/**
* Internal Worker instance used for all queue operations.
* @type {Worker | null}
*/
private static WORKER;
private static MESSAGE;
/**
* The 'start' method is used to initialize the Queue system.
* Creates and prepares the underlying Worker instance.
* @param {Object} [opts] - options (inspect, flush)
* @property {boolean} opts.inspect queue work flow
* @property {boolean} opts.flush remove all queue
* @property {number} opts.maxIdleRetries - Maximum idle time () when no jobs are available
* @property {number} opts.limitConnections - Allowed DB connections limit before pausing
* @returns {Promise<void>}
*/
static start(opts?: {
inspect?: boolean;
flush?: boolean;
hostname?: string;
maxIdleRetries?: number;
limitConnections?: 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100 | 150 | 200;
}): Promise<void>;
/**
* The 'end' method is used to shutdown the Queue system.
*
* @returns {Promise<void>}
*/
static end(): Promise<void>;
/**
* The 'flush' method is used to flush all jobs in the queue (dangerous operation).
*
* @throws {Error} If Queue is not initialized.
* @returns {Promise<void>}
*/
static flush(): Promise<void>;
/**
* The 'getJobOverallStats' method is used to get aggregated queue statistics.
*
* @param {string} [name] - Optional queue name filter.
* @throws {Error} If Queue is not initialized.
* @returns {Promise<any>}
*/
static getJobOverallStats(name?: string): Promise<{
total: number;
completed: number;
active: number;
pending: number;
failed: number;
}>;
/**
* The 'getJobStats' method is used to Get jobs statistics grouped by name.
*
* @param {string} [name] - Optional queue name filter.
* @throws {Error} If Queue is not initialized.
* @returns {Promise<Record<string,any>>}
*/
static getJobStats(name?: string): Promise<{
completed: number;
active: number;
pending: number;
failed: number;
}[]>;
/**
* Get all unique queue names.
*
* @throws {Error} If Queue is not initialized.
* @returns {Promise<string[]>}
*/
static getNames(): Promise<string[]>;
/**
* Access raw Worker instance safely.
*
* @param {(worker: Worker) => any} cb - Callback with Worker instance.
* @throws {Error} If Queue is not initialized.
* @returns {Promise<Work>}
*/
static worker(cb: (worker: Worker) => any): Promise<Worker>;
/**
* Start a worker for processing jobs of a specific name.
*
* @param {string} name - Queue name to process.
* @param {Handler} handler - Job handler function.
* @param {QueueProcessOptions} [opts] - Job options (interval, concurrency)
* @throws {Error} If Queue is not initialized.
* @returns {Promise<void>}
*
* @example
* const helloWorld = (job) => console.log('hello world :' + job.id);
*
* Queue.progress("hello", async (job) => {
* return await helloWorld(job)
* }, { concurrency : 3 });
*/
static process(name: string, handler: Handler, opts?: QueueProcessOptions): Promise<void>;
/**
* Start a worker for processing jobs of a specific name.
*
* @param {string} name - Queue name to process.
* @param {Handler} handler - Job handler function.
* @param {QueueProcessOptions} [opts] - Job options (interval, concurrency)
* @throws {Error} If Queue is not initialized.
* @returns {Promise<void>}
*
* @example
* const helloWorld = (job) => console.log('hello world :' + job.id);
*
* Queue.on("hello", async (job) => {
* return await helloWorld(job)
* }, { concurrency : 3 });
*/
static on(name: string, handler: Handler, opts?: QueueProcessOptions): Promise<void>;
/**
* Add a new job into the queue.
*
* @param {string} name - Queue name / job type.
* @param {any} payload - Job payload data.
* @param {QueueAddOptions} [opts] - Job options (delay, priority, retry, etc.)
* @throws {Error} If Queue is not initialized.
* @returns {Promise<T.Result<Worker>>}
*
* @example
* ```ts
* Queue.add("send-email", { email: "test@gmail.com" });
* ```
*/
static add(name: string, payload: any, opts?: QueueAddOptions): Promise<void>;
}
export { Queue };
export default Queue;