actionhero
Version:
actionhero.js is a multi-transport API Server with integrated cluster capabilities and delayed tasks
234 lines (233 loc) • 10.3 kB
TypeScript
export declare namespace task {
/**
* An example middleware
* ```js
* const middleware = {
* name: 'timer',
* global: true,
* priority: 90,
* preProcessor: async function () {
* const worker = this.worker
* worker.startTime = process.hrtime()
* },
* postProcessor: async function () {
* const worker = this.worker
* const elapsed = process.hrtime(worker.startTime)
* const seconds = elapsed[0]
* const millis = elapsed[1] / 1000000
* log(worker.job.class + ' done in ' + seconds + ' s and ' + millis + ' ms.', 'info')
* },
* preEnqueue: async function () {
* const arg = this.args[0]
* return (arg === 'ok') // returning `false` will prevent the task from enqueueing
* },
* postEnqueue: async function () {
* log("Task successfully enqueued!")
* }
* }
* api.tasks.addMiddleware(middleware)
```
*/
interface TaskMiddleware {
/**Unique name for the middleware. */
name: string;
/**Is this middleware applied to all tasks? */
global: boolean;
/**Module load order. Defaults to `api.config.general.defaultMiddlewarePriority`. */
priority?: number;
/**Called berore the task runs. Has access to all params, before sanitization. Can modify the data object for use in tasks. */
preProcessor?: Function;
/**Called after the task runs.*/
postProcessor?: Function;
/**Called before a task using this middleware is enqueued. */
preEnqueue?: Function;
/**Called after a task using this middleware is enqueued. */
postEnqueue?: Function;
}
/**
* Enqueue a task to be performed in the background.
* Will throw an error if redis cannot be reached.
*/
function enqueue(taskName: string, inputs: {
[key: string]: any;
}, queue?: string): Promise<any>;
/**
* Enqueue a task to be performed in the background, at a certain time in the future.
* Will throw an error if redis cannot be reached.
*
* Inputs:
* * taskName: The name of the task.
* * inputs: inputs to pass to the task.
* * queue: (Optional) Which queue/priority to run this instance of the task on.
*/
function enqueueAt(timestamp: number, taskName: string, inputs: {
[key: string]: any;
}, queue?: string): Promise<void>;
/**
* Enqueue a task to be performed in the background, at a certain number of ms from now.
* Will throw an error if redis cannot be reached.
*
* Inputs:
* * timestamp: At what time the task is able to be run. Does not guarantee that the task will be run at this time. (in ms)
* * taskName: The name of the task.
* * inputs: inputs to pass to the task.
* * queue: (Optional) Which queue/priority to run this instance of the task on.
*/
function enqueueIn(time: number, taskName: string, inputs: {
[key: string]: any;
}, queue?: string): Promise<void>;
/**
* Delete a previously enqueued task, which hasn't been run yet, from a queue.
* Will throw an error if redis cannot be reached.
*
* Inputs:
* * q: Which queue/priority is the task stored on?
* * taskName: The name of the job, likely to be the same name as a tak.
* * args: The arguments of the job. Note, arguments passed to a Task initially may be modified when enqueuing. It is best to read job properties first via `api.tasks.queued` or similar method.
* * count: Of the jobs that match q, taskName, and args, up to what position should we delete? (Default 0; this command is 0-indexed)
*/
function del(q: string, taskName: string, args?: {
[key: string]: any;
}, count?: number): Promise<number>;
/**
* Delete all previously enqueued tasks, which haven't been run yet, from all possible delayed timestamps.
* Will throw an error if redis cannot be reached.
*
* Inputs:
* * q: Which queue/priority is to run on?
* * taskName: The name of the job, likely to be the same name as a tak.
* * inputs The arguments of the job. Note, arguments passed to a Task initially may be modified when enqueuing. It is best to read job properties first via `api.tasks.delayedAt` or similar method.
*/
function delDelayed(q: string, taskName: string, inputs?: {
[key: string]: any;
}): Promise<any[]>;
/**
* Return the timestamps a task is scheduled for.
* Will throw an error if redis cannot be reached.
*
* Inputs:
* * q: Which queue/priority is to run on?
* * taskName: The name of the job, likely to be the same name as a tak.
* * inputs: The arguments of the job. Note, arguments passed to a Task initially may be modified when enqueuing. It is best to read job properties first via `api.tasks.delayedAt` or similar method.
*/
function scheduledAt(q: string, taskName: string, inputs: {
[key: string]: any;
}): Promise<Array<number>>;
/**
* Return all resque stats for this namespace (how jobs failed, jobs succeeded, etc)
* Will throw an error if redis cannot be reached.
*/
function stats(): Promise<{}>;
/**
* Retrieve the details of jobs enqueued on a certain queue between start and stop (0-indexed)
* Will throw an error if redis cannot be reached.
*
* Inputs:
* * q The name of the queue.
* * start The index of the first job to return.
* * stop The index of the last job to return.
*/
function queued(q: string, start: number, stop: number): Promise<Array<{
[key: string]: any;
}>>;
/**
* Delete a queue in redis, and all jobs stored on it.
* Will throw an error if redis cannot be reached.
*/
function delQueue(q: string): Promise<void>;
/**
* Return any locks, as created by resque plugins or task middleware, in this redis namespace.
* Will contain locks with keys like `resque:lock:{job}` and `resque:workerslock:{workerId}`
* Will throw an error if redis cannot be reached.
*/
function locks(): Promise<Object>;
/**
* Delete a lock on a job or worker. Locks can be found via `api.tasks.locks`
* Will throw an error if redis cannot be reached.
*/
function delLock(lock: string): Promise<number>;
/**
* List all timestamps for which tasks are enqueued in the future, via `api.tasks.enqueueIn` or `api.tasks.enqueueAt`
* Will throw an error if redis cannot be reached.
*/
function timestamps(): Promise<Array<number>>;
/**
* Return all jobs which have been enqueued to run at a certain timestamp.
* Will throw an error if redis cannot be reached.
*/
function delayedAt(timestamp: number): Promise<any>;
/**
* Return all delayed jobs, organized by the timestamp at where they are to run at.
* Note: This is a very slow command.
* Will throw an error if redis cannot be reached.
*/
function allDelayed(): Promise<any>;
/**
* Return all workers registered by all members of this cluster.
* Note: MultiWorker processors each register as a unique worker.
* Will throw an error if redis cannot be reached.
*/
function workers(): Promise<Object>;
/**
* What is a given worker working on? If the worker is idle, 'started' will be returned.
* Will throw an error if redis cannot be reached.
*/
function workingOn(workerName: string, queues: string): Promise<any>;
/**
* Return all workers and what job they might be working on.
* Will throw an error if redis cannot be reached.
*/
function allWorkingOn(): Promise<object>;
/**
* How many jobs are in the failed queue.
* Will throw an error if redis cannot be reached.
*/
function failedCount(): Promise<number>;
/**
* Retrieve the details of failed jobs between start and stop (0-indexed).
* Will throw an error if redis cannot be reached.
*/
function failed(start: number, stop: number): Promise<Array<object>>;
/**
* Remove a specific job from the failed queue.
* Will throw an error if redis cannot be reached.
*/
function removeFailed(failedJob: any): Promise<number>;
/**
* Remove a specific job from the failed queue, and retry it by placing it back into its original queue.
* Will throw an error if redis cannot be reached.
*/
function retryAndRemoveFailed(failedJob: any): Promise<any>;
/**
* If a worker process crashes, it will leave its state in redis as "working".
* You can remove workers from redis you know to be over, by specificizing an age which would make them too old to exist.
* This method will remove the data created by a 'stuck' worker and move the payload to the error queue.
* However, it will not actually remove any processes which may be running. A job *may* be running that you have removed.
* Will throw an error if redis cannot be reached.
*/
function cleanOldWorkers(age: number): Promise<object>;
/**
* Ensures that a task which has a frequency is either running, or already enqueued.
* This is run automatically at boot for all tasks which have a frequency, via `api.tasks.enqueueAllRecurrentTasks`.
* Will throw an error if redis cannot be reached.
*/
function enqueueRecurrentTask(taskName: string): Promise<void>;
/**
* This is run automatically at boot for all tasks which have a frequency, calling `api.tasks.enqueueRecurrentTask`
* Will throw an error if redis cannot be reached.
*/
function enqueueAllRecurrentTasks(): Promise<any[]>;
/**
* Stop a task with a frequency by removing it from all possible queues.
* Will throw an error if redis cannot be reached.
*/
function stopRecurrentTask(taskName: string): Promise<number>;
/**
* Return wholistic details about the task system, including failures, queues, and workers.
* Will throw an error if redis cannot be reached.
*/
function details(): Promise<{
[key: string]: any;
}>;
function addMiddleware(middleware: TaskMiddleware): Promise<void>;
}