sidequest/dist/operations/job.d.ts

Sidequest is a modern, scalable background job processor for Node.js applications.

import { Backend, JobCounts, NewJobData, UpdateJobData } from '@sidequest/backend';
import { JobData, JobState } from '@sidequest/core';

/**
 * Entry point for managing jobs in Sidequest.
 *
 * Provides high-level methods for job management operations including
 * job building, state management, querying, and administrative tasks.
 */
declare class JobOperations {
    /**
     * Backend instance from the Sidequest engine.
     * @returns The backend instance.
     * @throws Error if the engine is not configured.
     */
    private backend?;
    /**
     * Singleton instance of JobOperations.
     * This allows for easy access to job management methods without needing to instantiate the class.
     */
    static readonly instance: JobOperations;
    /**
     * Private constructor to enforce singleton pattern.
     * Prevents instantiation from outside the class.
     */
    private constructor();
    /**
     * Sets the backend instance for the JobOperations.
     * This is typically called by the Sidequest engine during configuration.
     *
     * @param backend - The backend instance to set
     */
    setBackend(backend: Backend | undefined): void;
    /**
     * Gets the backend instance from the engine.
     * @returns The backend instance.
     * @throws Error if the engine is not configured.
     */
    private getBackend;
    /**
     * Gets a job by its ID.
     *
     * @param id - The job ID
     * @returns Promise resolving to the job data if found, undefined otherwise
     */
    get(id: number): Promise<JobData | undefined>;
    /**
     * Lists jobs with optional filters and pagination.
     *
     * @param params - Optional filter parameters
     * @param params.queue - Filter by queue name(s)
     * @param params.jobClass - Filter by job class name(s)
     * @param params.state - Filter by job state(s)
     * @param params.limit - Maximum number of jobs to return
     * @param params.offset - Offset for pagination
     * @param params.args - Filter by job arguments
     * @param params.timeRange - Filter by job time range
     * @returns Promise resolving to an array of job data
     */
    list(params?: {
        queue?: string | string[];
        jobClass?: string | string[];
        state?: JobState | JobState[];
        limit?: number;
        offset?: number;
        args?: unknown[];
        timeRange?: {
            from?: Date;
            to?: Date;
        };
    }): Promise<JobData[]>;
    /**
     * Counts jobs by their states, optionally within a time range.
     *
     * @param timeRange - Optional time range for filtering jobs by attempted_at
     * @returns Promise resolving to job counts grouped by state
     */
    count(timeRange?: {
        from?: Date;
        to?: Date;
    }): Promise<JobCounts>;
    /**
     * Counts jobs over time, grouped by a specified time unit.
     *
     * @param timeRange - The time range to filter jobs (e.g., '12m', '12h', '12d')
     * @returns Promise resolving to an array of objects containing timestamps and job counts
     */
    countOverTime(timeRange: string): Promise<({
        timestamp: Date;
    } & JobCounts)[]>;
    /**
     * Finds jobs that are stale or have timed out.
     *
     * @param maxStaleMs - Maximum milliseconds for a job to be considered stale. Defaults to 10m.
     * @param maxClaimedMs - Maximum milliseconds for a claimed job to be in the claimed state. Defaults to 1m.
     * @returns Promise resolving to an array of stale job data
     */
    findStale(maxStaleMs?: number, maxClaimedMs?: number): Promise<JobData[]>;
    /**
     * Deletes finished jobs (completed, failed, canceled) before a cutoff date.
     *
     * @param cutoffDate - The cutoff date - jobs finished before this date will be deleted
     * @returns Promise that resolves when deletion is complete
     */
    deleteFinished(cutoffDate: Date): Promise<void>;
    /**
     * Cancels a job by transitioning it to the canceled state.
     *
     * Running jobs will be aborted, but this method does not
     * stop jobs that are already claimed or running. It only marks them as canceled.
     * The engine will handle the actual stopping of running jobs.
     *
     * This transition can only be applied to jobs in "waiting" or "running" states.
     *
     * @param jobId - The ID of the job to cancel
     * @returns Promise resolving to the updated job data or the same job data if transition is not applicable
     * @throws Error if the job is not found
     */
    cancel(jobId: number): Promise<JobData>;
    /**
     * Runs a job immediately by setting its available_at to the current time.
     * This makes the job available for execution on the next polling cycle.
     *
     * If `force` is `false`, it will simply update the available_at time for waiting jobs.
     * It is effectively a snooze with 0 delay.
     * This can only be applied to `waiting` and `running` jobs.
     *
     * If `force` is `true`, it will use RerunTransition to completely reset and re-run the job,
     * similar to the dashboard's re-run functionality. It will completely ignore the number of attempts
     * and the current state of the job, allowing it to be re-run regardless of its current state.
     * This can only be applied to jobs that are in `waiting`, `running`, `completed`, `canceled`, or `failed` states.
     *
     * Calling this method on a running job will do nothing other than update the available_at time.
     *
     * @param jobId - The ID of the job to run
     * @param force - Whether to force re-run the job regardless of state and attempts
     * @returns Promise resolving to the updated job data or the same job data if transition is not applicable
     * @throws Error if the job is not found
     */
    run(jobId: number, force?: boolean): Promise<JobData>;
    /**
     * Snoozes a job by delaying its execution for the specified time.
     *
     * This method can only be applied to jobs that are in "waiting" or "running" states.
     *
     * Running jobs won't be stopped, they will run regardless. However, if they fail,
     * it will prevent new attempts to run the job until the snooze delay has passed.
     *
     * @param jobId - The ID of the job to snooze
     * @param delayMs - The delay in milliseconds
     * @returns Promise resolving to the updated job data or the same job data if transition is not applicable
     * @throws Error if the job is not found
     */
    snooze(jobId: number, delayMs: number): Promise<JobData>;
    /**
     * Creates a new job directly (bypasses the JobBuilder pattern).
     * This is useful for programmatically creating jobs with specific configurations.
     *
     * @param jobData - The job data to create
     * @returns Promise resolving to the created job data
     */
    create(jobData: NewJobData): Promise<JobData>;
    /**
     * Updates an existing job with new data. ID is required in the jobData to identify the job.
     *
     * **WARNING**: This method does not perform any validation on the job data and does not ensure Sidequest's integrity.
     * This means you must ensure the job data is valid, complete, and with integrity.
     * Changing a job's state directly is not recommended and should be done through transitions
     * or other methods in this class.
     *
     * Use this with CAUTION.
     *
     * @param jobData - The job update data (must include id)
     * @returns Promise resolving to the updated job data
     * @throws Error if the job is not found
     */
    update(jobData: UpdateJobData): Promise<JobData>;
}

export { JobOperations };