torotask
Version:
Task queue processing in NodeJS based on BullMQ and Redis
207 lines • 8.8 kB
TypeScript
import type { JobsOptions, MinimalQueue, QueueEvents } from 'bullmq';
import type { Logger } from 'pino';
import type { ToroTask } from './client.js';
import type { TaskJobData, TaskJobOptions, TaskJobState } from './types/index.js';
import { Job } from 'bullmq';
import { TaskQueue } from './queue.js';
export declare class TaskJob<PayloadType = any, ReturnType = any, NameType extends string = string, const DataType extends TaskJobData = TaskJobData<PayloadType>, const StateType = TaskJobState> extends Job<DataType, ReturnType, NameType> {
options: TaskJobOptions<DataType>;
logger?: Logger;
taskClient?: ToroTask;
taskQueue?: TaskQueue;
/**
* The array of real TaskJob instances that constitute a batch.
*/
private batch;
/**
* Whether this job has already been completed early within a batch.
* When true, the moveToCompleted override will no-op to prevent double-completion.
*/
private _batchCompleted;
payload: PayloadType;
state: StateType;
opts: JobsOptions;
constructor(queue: MinimalQueue, name: NameType, data: DataType, options?: TaskJobOptions<DataType>, id?: string);
/**
* Sets a job's payload
*
* @param payload - the payload that will replace the current jobs payload.
*/
setPayload(payload: PayloadType): Promise<void>;
/**
* Partially updates a job's payload
*
* @param payload - the payload that will merge with the current jobs payload.
*/
updatePayload(payload: Partial<PayloadType>): Promise<void>;
/**
* Sets a job's state
*
* @param state - the state that will replace the current jobs state.
*/
setState(state: StateType): Promise<void>;
/**
* Partially updates a job's state
*
* @param state - the state that will merge with the current jobs state.
*/
updateState(state: Partial<StateType>): Promise<void>;
/**
* Throws an UnrecoverableError to permanently fail this job.
* The job will not be retried and will immediately move to the failed state.
*
* @param message - Error message describing why the job failed
* @param logMessage - If true, logs the message to the job's log before throwing (default: true)
* @throws UnrecoverableError - Always throws to fail the job
*
* @example
* ```ts
* if (!payload.userId) {
* await job.failUnrecoverable('Missing required userId');
* }
* ```
*/
failUnrecoverable(message: string, logMessage?: boolean): Promise<never>;
/**
* Sets the return value for this job in memory.
* When used inside a batch handler, this value will be persisted to Redis
* when the batch completes and BullMQ's normal completion flow runs.
*
* For immediate persistence, use {@link complete} instead.
*
* @param value - The return value to set.
*/
setResult(value: ReturnType): void;
/**
* Completes this individual job immediately, persisting the return value to Redis.
* The job will be skipped during the batch's final completion step to avoid double-completion.
*
* Use this when you want to complete a job early within a batch loop,
* for example when a job can be resolved without waiting for the entire batch to finish.
*
* @param value - The return value to persist.
* @throws Error if the job is missing its lock token.
*
* @example
* ```ts
* for (const item of job.getBatch()) {
* const result = await processItem(item.payload);
* await item.complete(result); // Persisted to Redis immediately
* }
* ```
*/
complete(value: ReturnType): Promise<void>;
/**
* Whether this job has already been completed early within a batch.
*/
get isBatchCompleted(): boolean;
/**
* Override moveToCompleted to prevent double-completion of batch jobs.
* When a job has been completed early via {@link complete}, this returns
* an empty array (no-op) instead of calling the parent implementation.
*
* BullMQ's Worker calls this after the processor returns. Returning `[]`
* tells the Worker there is no next job to fetch from this call.
*/
moveToCompleted(returnValue: ReturnType, token: string, fetchNext?: boolean): Promise<any>;
/**
* Sets/replaces the internal list of Job instances managed by this container.
* @param batch The array of Job instances representing the batch.
*/
setBatch(batch: (typeof this)[]): void;
/**
* Adds a single job to the internal list for this batch container.
* @param job The job to add.
*/
addBatchJob(job: typeof this): void;
/**
* Adds multiple jobs to the internal list for this batch container.
* @param jobs The jobs to add.
*/
addBatchJobs(jobs: (typeof this)[]): void;
/**
* Returns the array of actual TaskJob instances managed by this batch container.
* @returns The array of jobs.
*/
getBatch(): (typeof this)[];
/**
* Returns the array of actual TaskJob instances managed by this batch container.
* @returns The array of jobs.
*/
get isBatch(): boolean;
/**
* Returns the number of jobs currently in the batch.
* @returns The number of jobs.
*/
get batchLength(): number;
/**
* **Manual Lock Extension:** Extends the lock for all individual jobs currently held within this batch container.
*
* **Usage Note:** Generally **not required**. Rely on the Worker's automatic lock renewal
* by configuring `lockDuration` appropriately. Use this only for explicit manual control
* during very long-running steps within your handler.
*
* @param duration - Duration (in milliseconds) to extend the lock by. Uses the job's configured lock duration if omitted.
* @returns A promise that resolves when all lock extensions have been attempted.
*/
extendLocks(duration: number): Promise<void>;
/**
* Updates the progress for all individual jobs currently held within this batch container.
*
* @param progress The progress value (number or object).
* @returns A promise that resolves when all progress updates have been attempted.
*/
updateProgress(progress: number | object): Promise<void>;
/**
* Sends the same log entry to all individual jobs currently held within this batch container
* using the underlying `job.log()` method.
*
* @param logRow The string log entry to add to each job's log in Redis.
* @returns A promise that resolves when all log additions have been attempted.
*/
log(logRow: string): Promise<number>;
/**
* Clears all batched job's logs
*
* @param keepLogs - the amount of log entries to preserve
*/
clearLogs(keepLogs?: number): Promise<void>;
/**
* Attempts to move all individual jobs currently held within this batch container to the 'failed' state in BullMQ.
*
* **Use Case:** Useful if you detect a non-recoverable error *within* your batch handler
* and want to explicitly mark all jobs as failed *before* throwing an error to signal the overall batch failure.
* Often, just throwing an error from the handler is sufficient.
*
* **Requires Job Tokens:** This operation requires the lock `token` for each individual job.
*
* @param error The Error object representing the reason for failure.
* @returns A promise that resolves when all `moveToFailed` operations have been attempted.
*/
moveToFailed(error: Error, token: string, fetchNext?: boolean): Promise<void | any[]>;
/**
* Waits for this job to complete and returns its typed result.
* This is useful when you have started a child task with `step.runTask()` and want
* to later retrieve its result after `step.waitForChildTasks()`.
*
* @param queueEvents - Optional QueueEvents instance. If not provided, uses the one from taskQueue.
* @returns The typed return value of the job.
* @throws Error if the job fails or no QueueEvents is available.
*
* @example
* ```ts
* const childJob = await step.runTask('step-id', 'groupName', 'taskName', payload);
* await step.waitForChildTasks('wait-for-children');
* const result = await childJob.waitForResult(); // Typed result
* ```
*/
waitForResult(queueEvents?: QueueEvents): Promise<ReturnType>;
/**
* Gets the result of a completed job without waiting.
* Returns undefined if the job hasn't completed yet.
*
* @returns The return value if completed, undefined otherwise.
*/
getResult(): Promise<ReturnType | undefined>;
}
//# sourceMappingURL=job.d.ts.map