Queue API reference

import type { QueueMonitor, QueueMonitorOptions } from '../queueMonitor.js';
import type { QueueEvents } from '../QueueEvents.js';
import type { QueueableJob } from '../QueueableJob.js';
import type { QueueLifecycleErrorHandler } from './QueueEvents.js';
import type { DispatchOptions, QueueDriverName, QueueJob, QueueJobId, QueueProcessResult } from './QueuePayload.js';
import type { QueueRetryBackoffStrategy } from './QueueRetry.js';
import type { QueueDriver, QueueFailedJob } from './QueueDriver.js';
import type { QueueableJobClass } from './QueueableJob.js';
import type { QueueWorkerLifecycle, QueueWorkerOptions } from './QueueWorkerLifecycle.js';
import type { RedisQueueDriverOptions } from './RedisQueueDriver.js';
/**
 * Function-style handler registered for a durable queued job name.
 */
export type JobHandler<TData = Record<string, unknown>> = (job: QueueJob<TData>) => Promise<void>;
/**
 * Input passed to a lazy job resolver when a worker sees an unknown job name.
 */
export interface QueueJobResolverContext {
    /** Durable queued job name from the persisted payload. */
    jobName: string;
}
/**
 * Resolves a queueable job class just in time for worker processing.
 */
export type QueueJobResolver = (context: QueueJobResolverContext) => QueueableJobClass | null | Promise<QueueableJobClass | null>;
/**
 * Queue service configuration shared by dispatching, processing, and worker startup.
 */
export interface QueueOptions {
    /**
     * Default queue name used when dispatching or processing jobs without an explicit queue.
     */
    queue?: string;
    /**
     * Concrete queue driver instance, or the registered driver name to resolve lazily.
     */
    driver?: QueueDriver | QueueDriverName;
    /**
     * Named queue driver to resolve when no concrete driver instance is provided.
     */
    driverName?: QueueDriverName;
    /**
     * Redis driver options used when driver or driverName resolves to `redis`.
     */
    redis?: RedisQueueDriverOptions;
    /**
     * Number of seconds before an in-progress job is considered expired and claimable again.
     */
    retryAfterSeconds?: number;
    /**
     * Base delay, in seconds, used when releasing failed jobs for another attempt.
     */
    retryDelaySeconds?: number;
    /**
     * Default delay-growth strategy persisted on newly dispatched jobs.
     */
    retryBackoffStrategy?: QueueRetryBackoffStrategy;
    /**
     * Maximum delay, in seconds, persisted on newly dispatched jobs.
     */
    retryMaxDelaySeconds?: number;
    /**
     * Whether newly dispatched jobs apply equal jitter to ordinary retry delays.
     */
    retryJitter?: boolean;
    /**
     * Default polling interval, in milliseconds, for long-running workers.
     */
    workerIntervalMs?: number;
    /**
     * Maximum number of jobs a worker should process during one polling tick.
     */
    maxJobsPerTick?: number;
    /**
     * Enables or disables worker startup unless startWorker() is called with force.
     */
    workerEnabled?: boolean;
    /**
     * Configures queue lifecycle telemetry for development panels and tests.
     */
    queueMonitor?: false | QueueMonitorOptions;
    /**
     * Reports isolated lifecycle listener and QueueableJob hook failures.
     */
    onLifecycleError?: QueueLifecycleErrorHandler;
    /**
     * Lazily resolves a QueueableJob class when a worker sees an unknown job name.
     */
    jobResolver?: QueueJobResolver;
}
/**
 * Hooks for observing a single job processing attempt.
 */
export interface QueueWorkOptions {
    /**
     * Called after a driver claims a job and before the registered handler runs.
     */
    onClaimed?(job: QueueJob): void;
}
/**
 * Public queue service API used by application code and queueable jobs.
 */
export interface QueueService {
    /**
     * Always-on asynchronous queue lifecycle event dispatcher.
     */
    readonly events: QueueEvents;
    /**
     * Queue lifecycle monitor attached to this service, when enabled.
     */
    readonly queueMonitor: QueueMonitor | null;
    /**
     * Returns recent terminal failures from driver-owned persistence.
     *
     * @param limit - Maximum number of recent failed jobs to return.
     * @returns Recent failed jobs ordered from newest to oldest.
     */
    failedJobs(limit?: number): Promise<QueueFailedJob[]>;
    /**
     * Replays one persisted terminal failure as a new active queue job.
     *
     * The original failure remains available for audit and the replacement job
     * receives a new UUID linked back to that failed record.
     *
     * @param id - Driver-owned failed-job record id.
     * @param options - Optional queue, attempts, backoff, and delay overrides.
     * @returns Queue driver id for the replacement job.
     */
    retryFailed(id: QueueJobId, options?: DispatchOptions): Promise<QueueJobId>;
    /**
     * Registers an async handler for a named job payload.
     *
     * @param name - Durable queued job name.
     * @param handler - Handler invoked when a worker processes that job name.
     */
    registerHandler<TData = Record<string, unknown>>(name: string, handler: JobHandler<TData>): void;
    /**
     * Registers a queueable job class for worker rehydration.
     *
     * @param Job - Job class with JSON rehydration inherited from QueueableJob.
     */
    registerJob<TJob extends QueueableJobClass>(Job: TJob): void;
    /**
     * Dispatches a named job payload.
     *
     * @param job - Durable job name.
     * @param data - JSON-safe payload data.
     * @param options - Per-dispatch queue options.
     * @returns Queue driver id for the queued job.
     */
    dispatch<TData extends Record<string, unknown>>(job: string, data: TData, options?: DispatchOptions): Promise<QueueJobId>;
    /**
     * Dispatches a queueable job instance.
     *
     * @param job - Queueable job instance to serialize and dispatch.
     * @param options - Per-dispatch queue options.
     * @returns Queue driver id for the queued job.
     */
    dispatch<TJob extends QueueableJob>(job: TJob, options?: DispatchOptions): Promise<QueueJobId>;
    /**
     * Dispatches queueable jobs in order, one after each successful predecessor.
     *
     * @param jobs - Serializable jobs to chain.
     * @param options - Per-dispatch options for the first queued job.
     * @returns Queue driver id for the first queued job.
     */
    chain(jobs: QueueableJob[], options?: DispatchOptions): Promise<QueueJobId>;
    /**
     * Dispatches queueable jobs independently.
     *
     * @param jobs - Serializable jobs to dispatch.
     * @param options - Per-dispatch options applied to each job.
     * @returns Queue driver ids for the queued jobs.
     */
    batch(jobs: QueueableJob[], options?: DispatchOptions): Promise<QueueJobId[]>;
    /**
     * Processes at most one available job from a named queue.
     *
     * @param queue - Named queue/channel to process.
     * @returns True when a job was claimed and processed.
     */
    processNextJob(queue?: string): Promise<boolean>;
    /**
     * Processes at most one job and returns the detailed outcome.
     *
     * @param queue - Named queue/channel to process.
     * @param options - Per-work hooks for the processing attempt.
     * @returns Detailed result, or null when the queue was idle.
     */
    workNextJob(queue?: string, options?: QueueWorkOptions): Promise<QueueProcessResult | null>;
    /**
     * Starts a polling worker for a named queue.
     *
     * @param queue - Named queue/channel the worker should poll.
     * @param options - Worker lifecycle and polling options.
     * @returns Worker lifecycle controls, or null when worker startup is disabled.
     */
    startWorker(queue?: string, options?: QueueWorkerOptions): QueueWorkerLifecycle | null;
}

import type * as queue from './contracts/index.js';
export type { QueueableJobClass, QueueableJobContext, QueueableJobFailureContext, QueueableJobRetryContext, SerializedQueueableJob } from './contracts/index.js';
/**
 * Base class for application jobs that serialize their runtime data through JSON.
 *
 * Normal jobs only need to declare their data type and implement `handle()`.
 * Override the constructor to validate or normalize input, and override
 * `fromJSON()` or `toJSON()` only when the default round trip is insufficient.
 */
export declare abstract class QueueableJob<TData extends Record<string, unknown> = Record<string, unknown>> {
    readonly data: TData;
    private chainedJobs;
    /**
     * Creates a queueable job from its JSON-safe runtime data.
     *
     * @param data - Data that will be persisted in the queue payload.
     */
    constructor(data: TData);
    /**
     * Rehydrates a job by passing persisted JSON data to its constructor.
     *
     * Subclasses may override this for advanced serialization formats. Most jobs
     * should validate or normalize data in their constructor instead.
     *
     * @param data - JSON-safe data restored from the queue payload.
     * @returns Rehydrated job instance.
     */
    static fromJSON<TJob extends QueueableJob>(this: new (data: any) => TJob, data: Record<string, unknown>): TJob;
    /**
     * Attaches jobs that should run after this job completes successfully.
     *
     * @param jobs - Serializable jobs to dispatch one at a time after this job.
     * @returns This job instance for fluent dispatching.
     */
    chain(jobs: QueueableJob[]): this;
    /**
     * Serializes this job into the durable database queue payload shape.
     *
     * @returns Serialized queueable job envelope data.
     */
    serialize(): queue.SerializedQueueableJob<TData>;
    /**
     * Handles the job after the worker rehydrates it from queued data.
     *
     * @param context - Queueable job runtime context.
     */
    abstract handle(context: queue.QueueableJobContext): Promise<void>;
    /**
     * Handles a failed attempt after the queue has safely scheduled its retry.
     *
     * Hook failures are reported independently and do not change the retry.
     *
     * @param context - Queue metadata, failure, and retry delay.
     */
    onRetry(_context: queue.QueueableJobRetryContext): Promise<void>;
    /**
     * Handles terminal failure after the queue driver persists the failed job.
     *
     * Hook failures are reported independently and do not change the durable
     * terminal outcome.
     *
     * @param context - Queue metadata and terminal error.
     */
    onFinalFailure(_context: queue.QueueableJobFailureContext): Promise<void>;
    /**
     * Returns the JSON-safe data stored as this queued job's payload data.
     *
     * @returns JSON payload data for this job.
     */
    toJSON(): TData;
    /**
     * Returns jobs that should follow this job when no explicit chain is set.
     *
     * @returns Queueable jobs to run after this job succeeds.
     */
    protected defaultChain(): QueueableJob[];
}
/**
 * Returns true when a value exposes the queueable-job serialization contract.
 *
 * @param value - Unknown value to inspect.
 * @returns True when the value is a queueable job instance.
 */
export declare function isQueueableJob(value: unknown): value is QueueableJob;
/**
 * Returns true when a class looks like a QueueableJob subclass.
 *
 * @param value - Unknown value to inspect.
 * @returns True when the value is a queueable job class with JSON rehydration.
 */
export declare function isQueueableJobClass(value: unknown): value is queue.QueueableJobClass;
/**
 * Resolves the durable queue name for a queueable job class.
 *
 * @param Job - Queueable job class or compatible class metadata.
 * @returns Durable queue job name.
 */
export declare function queueableJobName(Job: queue.QueueableJobClass | {
    name: string;
    jobName?: string;
}): string;
/**
 * Rehydrates a queueable job instance from persisted JSON payload data.
 *
 * @param Job - Queueable job class that owns the payload data.
 * @param data - JSON payload data stored in the queue envelope.
 * @returns Rehydrated queueable job instance.
 */
export declare function queueableJobFromJSON(Job: queue.QueueableJobClass, data: Record<string, unknown>): QueueableJob;

import type { Queue } from '../Queue.js';
import type { QueueableJob } from '../QueueableJob.js';
import type { QueueJob, SerializedQueuedJob } from './QueuePayload.js';
/**
 * Serialized queueable job payload stored before a driver wraps it in an envelope.
 */
export type SerializedQueueableJob<TData extends Record<string, unknown> = Record<string, unknown>> = SerializedQueuedJob<TData>;
/**
 * Queue runtime metadata passed to a rehydrated job.
 */
export interface QueueableJobContext {
    /** Claimed queue job being handled. */
    job: QueueJob;
    /** Queue service that is processing this job. */
    queue: Queue;
}
/**
 * Context passed after a failed attempt has safely been released for retry.
 */
export interface QueueableJobRetryContext extends QueueableJobContext {
    /** Error raised by the failed handler attempt. */
    error: unknown;
    /** Seconds before the released job becomes available again. */
    delaySeconds: number;
}
/**
 * Context passed after a job exhausts its attempts and is durably failed.
 */
export interface QueueableJobFailureContext extends QueueableJobContext {
    /** Terminal error persisted by the queue driver. */
    error: unknown;
}
/**
 * Constructor contract for serializable queueable job classes.
 */
export interface QueueableJobClass<TJob extends QueueableJob = QueueableJob> {
    /** Runtime class name used as the default durable job name. */
    readonly name: string;
    /** Optional durable job name override. */
    readonly jobName?: string;
    /** Creates a job from its application-facing runtime data. */
    new (data: any): TJob;
    /**
     * Rehydrates a queueable job instance from persisted payload data.
     *
     * @param data - JSON-safe data stored in the queue payload.
     * @returns Queueable job instance ready to handle.
     */
    fromJSON(data: Record<string, unknown>): TJob;
}

import type { QueueFailedJobRetryReference, QueueRetryBackoff, QueueRetryBackoffOptions } from './QueueRetry.js';
/**
 * Serialized form of a queueable job before it is wrapped in a durable queue envelope.
 *
 * Queueable jobs use this shape for object serialization and chained follow-up work.
 */
export interface SerializedQueuedJob<TData extends Record<string, unknown> = Record<string, unknown>> {
    /** Durable job name used to resolve the handler when a worker processes the payload. */
    job: string;
    /** Human-readable label shown in logs and queue monitors. */
    displayName?: string;
    /** JSON-safe payload data owned by the queued job. */
    data: TData;
    /** Remaining jobs that should run after this job succeeds. */
    chained?: SerializedQueuedJob[];
}
/**
 * Framework-owned correlation metadata attached to one root queue job.
 *
 * Origins let orchestration layers observe a queue job without adding their
 * identifiers to application-owned job payloads.
 */
export interface QueueJobOrigin {
    /** Framework subsystem that owns the correlated record. */
    type: string;
    /** Stable identifier understood by the originating subsystem. */
    id: string;
}
/**
 * Durable payload stored by queue drivers.
 *
 * Drivers persist this envelope as the canonical queue record payload. Application jobs
 * should treat `data` as their own payload and the other fields as framework metadata.
 */
export interface JobEnvelope<TData = Record<string, unknown>> {
    /** Stable UUID for this queued job attempt chain. */
    uuid: string;
    /** Human-readable label shown in logs and queue monitors. */
    displayName: string;
    /** Durable job name used to resolve the handler. */
    job: string;
    /** Maximum number of attempts before the job is moved to failed storage. */
    maxTries: number;
    /** Durable delay policy used when an ordinary failed attempt is released. */
    backoff?: QueueRetryBackoff;
    /** Absolute Unix timestamp after which another ordinary retry must not be scheduled. */
    retryUntil?: number;
    /** Application-owned JSON-safe payload data. */
    data: TData;
    /** Optional framework-owned record that originated this root queue job. */
    origin?: QueueJobOrigin;
    /** Terminal failed-job record that was replayed to create this job. */
    retryOf?: QueueFailedJobRetryReference;
    /** Remaining jobs that should be dispatched after this job succeeds. */
    chained?: SerializedQueuedJob[];
}
/**
 * Identifier returned by a queue driver when a job is persisted.
 */
export type QueueJobId = number | string;
/**
 * Built-in queue driver names understood by the framework.
 */
export type QueueDriverName = 'database' | 'redis';
/**
 * Claimed queue job passed to handlers and lifecycle hooks.
 */
export interface QueueJob<TData = Record<string, unknown>> {
    /** Driver-owned queue record id. */
    id: QueueJobId;
    /** Named queue/channel this job was claimed from. */
    queue: string;
    /** Number of processing attempts already consumed by this job. */
    attempts: number;
    /** Durable queue payload envelope. */
    payload: JobEnvelope<TData>;
}
/**
 * Per-dispatch overrides for queueing one job.
 */
export interface DispatchOptions {
    /**
     * Named queue/channel the job should be pushed onto.
     *
     * Workers process one named queue at a time, so this lets callers route
     * different classes of work to different worker pools. When omitted, the
     * queue service uses its configured default queue name.
     */
    queue?: string;
    /**
     * Number of seconds to wait before the job becomes available to workers.
     */
    delaySeconds?: number;
    /**
     * Maximum number of processing attempts before the job is failed.
     */
    maxTries?: number;
    /**
     * Durable delay policy for ordinary failed attempts.
     */
    backoff?: QueueRetryBackoffOptions;
    /**
     * Maximum number of seconds ordinary retries may remain active after dispatch.
     *
     * Explicit QueueRetryLaterError deferrals own their own retry horizon and do
     * not consume this ordinary-attempt window.
     */
    retryUntilSeconds?: number;
    /**
     * Framework-owned correlation metadata for this root queued job.
     *
     * Chained jobs do not inherit this value automatically because their
     * lifecycle is distinct from the root dispatch.
     */
    origin?: QueueJobOrigin;
}
/**
 * Result status for one queue processing attempt.
 *
 * `lease_lost` means the handler settled but the worker could not prove that its
 * exact attempt still owned the durable job, so no outcome transition was made.
 */
export type QueueProcessStatus = 'succeeded' | 'released' | 'deferred' | 'failed' | 'lease_lost';
/**
 * Detailed outcome returned after processing one claimed queue job.
 */
export interface QueueProcessResult {
    /** Claimed queue job that was processed. */
    job: QueueJob;
    /** Final status for this processing attempt. */
    status: QueueProcessStatus;
    /** Delay before a released or deferred job becomes available again. */
    delaySeconds?: number;
    /** Handler or lease error explaining why the attempt did not succeed. */
    error?: unknown;
}

import type { QueueJobId } from './QueuePayload.js';
/**
 * Supported delay-growth strategies for ordinary queue retries.
 */
export type QueueRetryBackoffStrategy = 'linear' | 'exponential';
/**
 * Durable retry backoff stored with a queued job.
 *
 * Persisting this policy ensures every worker calculates the same retry schedule,
 * even when queue configuration changes after the job was dispatched.
 */
export interface QueueRetryBackoff {
    /** Delay-growth strategy applied after each consumed attempt. */
    strategy: QueueRetryBackoffStrategy;
    /** Base delay in seconds before the first retry. */
    initialSeconds: number;
    /** Maximum delay in seconds after applying the selected growth strategy. */
    maxSeconds: number;
    /** Whether equal jitter should be applied to reduce coordinated retry spikes. */
    jitter: boolean;
}
/**
 * Per-dispatch overrides used to build a durable retry backoff policy.
 */
export interface QueueRetryBackoffOptions {
    /** Delay-growth strategy applied after each consumed attempt. */
    strategy?: QueueRetryBackoffStrategy;
    /** Base delay in seconds before the first retry. */
    initialSeconds?: number;
    /** Maximum delay in seconds after applying the selected growth strategy. */
    maxSeconds?: number;
    /** Whether equal jitter should be applied to reduce coordinated retry spikes. */
    jitter?: boolean;
}
/**
 * Links a replayed queue job to the terminal failure that produced it.
 */
export interface QueueFailedJobRetryReference {
    /** Driver-owned failed-job record that was replayed. */
    failedJobId: QueueJobId;
    /** Stable UUID of the original terminally failed job. */
    jobUuid: string;
}

/**
 * Minimal logger contract used by queue workers.
 */
export interface QueueLogger {
    /**
     * Writes an informational queue worker message.
     *
     * @param message - Message ready for terminal or log output.
     */
    info(message: string): void;
    /**
     * Writes a warning queue worker message.
     *
     * @param message - Message ready for terminal or log output.
     */
    warn?(message: string): void;
    /**
     * Writes an error queue worker message.
     *
     * @param message - Message ready for terminal or log output.
     */
    error?(message: string): void;
}
/**
 * Runtime controls for a polling queue worker.
 */
export interface QueueWorkerOptions {
    /**
     * Number of milliseconds between worker ticks.
     */
    intervalMs?: number;
    /**
     * Maximum number of jobs to process during each tick.
     */
    maxJobsPerTick?: number;
    /**
     * Logger used for lifecycle and job processing messages.
     */
    logger?: QueueLogger;
    /**
     * Enables detailed lifecycle logging for idle ticks and queued follow-up work.
     */
    verbose?: boolean;
    /**
     * Starts the worker even when QUEUE_WORKER=false or workerEnabled is false.
     */
    force?: boolean;
}
/**
 * Public lifecycle controls for a long-running queue worker.
 */
export interface QueueWorkerLifecycle {
    /**
     * Starts polling the configured queue.
     */
    start(): void;
    /**
     * Stops future polling ticks without aborting an active tick.
     */
    stop(): void;
    /**
     * Stops future polling and resolves after the active tick has completed.
     */
    stopAndDrain(): Promise<void>;
}

import type { JobEnvelope, QueueDriverName, QueueJob, QueueJobId } from './QueuePayload.js';
/**
 * Job data handed to a queue driver when a job is persisted.
 */
export interface QueueDriverPushInput<TData = Record<string, unknown>> {
    /** Named queue/channel the job should be pushed onto. */
    queue: string;
    /** Durable payload envelope to persist. */
    payload: JobEnvelope<TData>;
    /** Number of seconds before the job becomes available to workers. */
    delaySeconds: number;
    /** Unix timestamp used as the queue record creation time. */
    createdAt: number;
}
/**
 * Driver controls used when claiming the next available queue job.
 */
export interface QueueDriverPopOptions {
    /** Number of seconds before a reserved job is considered expired and claimable. */
    retryAfterSeconds: number;
}
/**
 * Terminal queue failure exposed by drivers that support persisted failure inspection.
 *
 * Queue monitoring uses this shape to hydrate recent failures without depending on
 * database models, Redis commands, or another driver-specific storage detail.
 */
export interface QueueFailedJob {
    /** Driver-owned failed-job record id. */
    id: QueueJobId;
    /** Driver or connection name that recorded the failure. */
    connection: string;
    /** Named queue/channel on which the job failed. */
    queue: string;
    /** Durable payload envelope stored for the failed job. */
    payload: JobEnvelope<Record<string, unknown>>;
    /** Stored exception message or stack trace. */
    exception: string;
    /** ISO timestamp at which the terminal failure was recorded. */
    failedAt: string;
}
/**
 * Durable storage contract used by the queue service.
 *
 * Drivers own persistence, claiming, releasing, deferring, deletion, and failed-job
 * recording. Queue owns handler execution and retry decisions.
 */
export interface QueueDriver {
    /** Driver name stored on failed job records and shown in diagnostics. */
    readonly name: QueueDriverName | string;
    /**
     * Persists a job so a worker can claim it later.
     *
     * @param job - Queue job payload and scheduling data.
     * @returns Driver-owned queued job id.
     */
    push<TData extends Record<string, unknown>>(job: QueueDriverPushInput<TData>): Promise<QueueJobId>;
    /**
     * Claims the next available job from a named queue.
     *
     * @param queue - Named queue/channel to claim from.
     * @param options - Driver claim controls.
     * @returns Claimed job or null when no job is available.
     */
    pop(queue: string, options: QueueDriverPopOptions): Promise<QueueJob | null>;
    /**
     * Extends the reservation for a claimed long-running job.
     *
     * @param job - Claimed queue job whose current attempt owns the lease.
     * @param retryAfterSeconds - Number of seconds before the renewed lease expires.
     * @returns True when the current attempt still owned and renewed the lease.
     */
    touch(job: QueueJob, retryAfterSeconds: number): Promise<boolean>;
    /**
     * Deletes a completed job when the current attempt still owns it.
     *
     * @param job - Claimed queue job to delete.
     * @returns True when the current attempt owned and deleted the job.
     */
    delete(job: QueueJob): Promise<boolean>;
    /**
     * Releases an owned failed attempt while consuming the attempt.
     *
     * @param job - Claimed queue job to release.
     * @param delaySeconds - Delay before the job can be claimed again.
     * @returns True when the current attempt owned and released the job.
     */
    release(job: QueueJob, delaySeconds: number): Promise<boolean>;
    /**
     * Defers an owned job without consuming one of its retry attempts.
     *
     * @param job - Claimed queue job to defer.
     * @param delaySeconds - Delay before the job can be claimed again.
     * @returns True when the current attempt owned and deferred the job.
     */
    defer(job: QueueJob, delaySeconds: number): Promise<boolean>;
    /**
     * Records an owned terminal failure and removes it from the active queue.
     *
     * @param job - Claimed queue job that exhausted retries.
     * @param error - Handler error that caused the terminal failure.
     * @returns True when the current attempt owned and failed the job.
     */
    fail(job: QueueJob, error: unknown): Promise<boolean>;
    /**
     * Returns recent terminal failures when the driver supports persisted inspection.
     *
     * This optional capability keeps driver-specific failure storage behind the queue
     * boundary while allowing development tooling to show failures from before startup.
     *
     * @param limit - Maximum number of recent failed jobs to return.
     * @returns Recent failed jobs ordered from newest to oldest.
     */
    failedJobs?(limit?: number): Promise<QueueFailedJob[]>;
    /**
     * Returns one terminal failure by its driver-owned identifier.
     *
     * @param id - Driver-owned failed-job record id.
     * @returns Persisted failed job, or null when no matching record exists.
     */
    failedJob?(id: QueueJobId): Promise<QueueFailedJob | null>;
}

import type * as queue from '../contracts/index.js';
/**
 * Queue driver that stores pending, delayed, reserved, and failed jobs in Redis.
 *
 * @example
 * ```ts
 * const queue = new Queue(db, {
 * 	driverName: 'redis',
 * 	redis: {
 * 		url: 'redis://127.0.0.1:6379',
 * 		keyPrefix: 'app:queue',
 * 	},
 * });
 * ```
 */
export declare class RedisQueueDriver implements queue.QueueDriver {
    #private;
    readonly name = "redis";
    /**
     * Creates a Redis-backed queue driver.
     *
     * @param options - Redis connection and key options.
     */
    constructor(options?: queue.RedisQueueDriverOptions);
    /**
     * Persists a job into Redis and schedules it for immediate or delayed processing.
     *
     * @param job - Queue job payload and scheduling data.
     * @returns Redis queue job id.
     */
    push<TData extends Record<string, unknown>>(job: queue.QueueDriverPushInput<TData>): Promise<queue.QueueJobId>;
    /**
     * Claims the next available job from a Redis queue.
     *
     * @param queue - Named queue/channel to claim from.
     * @param options - Claim controls such as retry expiry.
     * @returns Claimed queue job, or null when no job is ready.
     */
    pop(queue: string, options: queue.QueueDriverPopOptions): Promise<queue.QueueJob | null>;
    /**
     * Renews the Redis reservation for the current queue attempt.
     *
     * @param job - Claimed job whose id and attempt count identify the lease owner.
     * @param retryAfterSeconds - Number of seconds before the renewed reservation expires.
     * @returns True when the current attempt still owns the job.
     */
    touch(job: queue.QueueJob, retryAfterSeconds: number): Promise<boolean>;
    /**
     * Releases a failed attempt for another try after a delay.
     *
     * @param job - Claimed queue job to release.
     * @param delaySeconds - Number of seconds before the job can be claimed again.
     * @returns True when the current attempt owned and released the job.
     */
    release(job: queue.QueueJob, delaySeconds: number): Promise<boolean>;
    /**
     * Defers a claimed job without consuming one of its retry attempts.
     *
     * @param job - Claimed queue job to defer.
     * @param delaySeconds - Number of seconds before the job can be claimed again.
     * @returns True when the current attempt owned and deferred the job.
     */
    defer(job: queue.QueueJob, delaySeconds: number): Promise<boolean>;
    /**
     * Deletes a completed job from Redis.
     *
     * @param job - Claimed queue job to delete.
     * @returns True when the current attempt owned and deleted the job.
     */
    delete(job: queue.QueueJob): Promise<boolean>;
    /**
     * Records a terminal failed job and removes it from the active Redis queue.
     *
     * @param job - Claimed queue job that exhausted retries.
     * @param error - Handler error that caused the terminal failure.
     * @returns True when the current attempt owned and failed the job.
     */
    fail(job: queue.QueueJob, error: unknown): Promise<boolean>;
    /**
     * Returns recent terminal failures stored by the Redis driver.
     *
     * @param limit - Maximum number of recent failed jobs to return.
     * @returns Recent failed jobs ordered from newest to oldest.
     */
    failedJobs(limit?: number): Promise<queue.QueueFailedJob[]>;
    /**
     * Returns one terminal failure from the Redis failed-job list.
     *
     * Failed-job replay is an administrative operation, so an exact lookup may
     * scan the retained failure list without affecting normal worker hot paths.
     *
     * @param id - Redis queue job identifier stored on the failed record.
     * @returns Persisted failed job, or null when it does not exist.
     */
    failedJob(id: queue.QueueJobId): Promise<queue.QueueFailedJob | null>;
    /**
     * Closes the underlying Redis socket.
     *
     * @returns Promise that settles after the Redis client has closed.
     */
    close(): Promise<void>;
}

/**
 * Connection and key options for the Redis queue driver.
 */
export interface RedisQueueDriverOptions {
    /**
     * Redis connection URL. When omitted, the driver reads QUEUE_REDIS_URL or REDIS_URL.
     */
    url?: string;
    /**
     * Redis host used when no URL is supplied.
     */
    host?: string;
    /**
     * Redis port used when no URL is supplied.
     */
    port?: number;
    /**
     * Redis username for ACL authentication.
     */
    username?: string;
    /**
     * Redis password for authentication.
     */
    password?: string;
    /**
     * Redis database index selected after connecting.
     */
    database?: number;
    /**
     * Prefix applied to every key owned by this queue driver.
     */
    keyPrefix?: string;
    /**
     * Milliseconds to wait before failing the Redis connection attempt.
     */
    connectionTimeoutMs?: number;
}

import type { QueueJobId, QueueJobOrigin } from './QueuePayload.js';
import type { QueueFailedJobRetryReference } from './QueueRetry.js';
/**
 * Lifecycle actions emitted as a durable queue job moves through the queue.
 */
export type QueueLifecycleAction = 'dispatched' | 'claimed' | 'released' | 'deferred' | 'succeeded' | 'lease_lost' | 'failed';
/**
 * Immutable lifecycle event emitted after the corresponding queue transition.
 */
export interface QueueLifecycleEvent {
    /** Lifecycle transition represented by this event. */
    action: QueueLifecycleAction;
    /** UTC timestamp captured when the queue published the event. */
    timestamp: string;
    /** Named queue or channel containing the job. */
    queue: string;
    /** Durable job name used to resolve its handler. */
    jobName: string;
    /** Driver-owned queue record identifier. */
    jobId: QueueJobId;
    /** Stable UUID retained across every attempt for this queued job. */
    jobUuid: string;
    /** Number of processing attempts consumed at this transition. */
    attempts: number;
    /** Maximum processing attempts before terminal failure. */
    maxTries: number;
    /** Seconds before the next attempt is available, when applicable. */
    delaySeconds?: number;
    /** Handler duration for processing transitions, when measured. */
    durationMs?: number;
    /** Error that caused a release, deferral, or terminal failure. */
    error?: unknown;
    /** Framework-owned correlation metadata persisted with the queue envelope. */
    origin?: QueueJobOrigin;
    /** Terminal failure that was replayed to create this job, when applicable. */
    retryOf?: QueueFailedJobRetryReference;
    /** Application-owned job payload for opt-in diagnostic consumers. */
    payloadData: Record<string, unknown>;
}
/**
 * Synchronous or asynchronous consumer of queue lifecycle events.
 * Thrown errors and rejected promises are reported without rejecting queue work.
 */
export type QueueLifecycleListener = (event: QueueLifecycleEvent) => void | Promise<void>;
/**
 * Failure raised by a lifecycle listener or optional job hook.
 */
export interface QueueLifecycleFailure {
    /** Component that failed while observing an already-decided queue transition. */
    source: 'listener' | 'hook';
    /** Lifecycle event being observed when the failure occurred. */
    event: QueueLifecycleEvent;
    /** Optional QueueableJob hook that raised the failure. */
    hook?: 'onRetry' | 'onFinalFailure';
    /** Error raised by the listener or hook. */
    error: unknown;
}
/**
 * Reports non-fatal lifecycle listener and job-hook errors.
 */
export type QueueLifecycleErrorHandler = (failure: QueueLifecycleFailure) => void;

import type { Logger } from '../logging/index.js';
import type * as queue from './contracts/index.js';
import type { Queue } from './Queue.js';
interface QueueConsoleLogOptions {
    verbose?: boolean;
}
export interface ParsedQueueConsoleArgs {
    command: string;
    args: string[];
    options: Record<string, string | boolean>;
}
export interface QueueConsoleApp {
    queue: Queue;
    /** Application logger used by long-running queue workers when available. */
    log?: Logger;
    close(): void | Promise<void>;
}
export interface QueueConsoleCommandContext {
    parsed: ParsedQueueConsoleArgs;
    app: QueueConsoleApp;
    dispatchOptions(): queue.DispatchOptions;
    optionString(name: string): string | undefined;
    optionBoolean(name: string): boolean;
    optionNumber(name: string, fallback?: string): number | undefined;
}
export interface QueueConsoleCommand {
    command: string;
    bootstrap?: boolean;
    close?: boolean;
    run(context: QueueConsoleCommandContext): void | Promise<void>;
}
export interface QueueConsoleOptions {
    app: () => QueueConsoleApp;
    bootstrap?: () => void | Promise<void>;
    commands?: QueueConsoleCommand[];
    helpText?: string;
    unknownCommandMessage?: (command: string) => string;
}
export declare function runQueueConsole(options: QueueConsoleOptions, argv?: string[]): Promise<void>;
export declare function parseQueueConsoleArgs(argv: string[]): ParsedQueueConsoleArgs;
export declare function queueConsoleOptionString(parsed: ParsedQueueConsoleArgs, name: string): string | undefined;
export declare function queueConsoleOptionBoolean(parsed: ParsedQueueConsoleArgs, name: string): boolean;
export declare function queueConsoleOptionNumber(parsed: ParsedQueueConsoleArgs, name: string, fallback?: string): number | undefined;
export declare function queueConsoleDispatchOptions(parsed: ParsedQueueConsoleArgs): queue.DispatchOptions;
/**
 * Resolves the process title for a long-running queue worker.
 *
 * @param parsed - Parsed console arguments.
 * @returns Process title to show in system process lists.
 */
export declare function queueConsoleWorkerProcessTitle(parsed: ParsedQueueConsoleArgs): string;
export declare function logQueueProcessResult(result: queue.QueueProcessResult, options?: QueueConsoleLogOptions): void;
/**
 * Logs that a queue job has been claimed in one-off worker mode.
 *
 * @param job - Claimed queue job.
 * @param options - Console logging options.
 */
export declare function logQueueClaimed(job: queue.QueueJob, options?: QueueConsoleLogOptions): void;
export {};