@boringnode/queue 0.0.1-alpha.3 → 0.1.0

package/build/index-2Ng_OpVK.d.ts

@@ -0,0 +1,1013 @@
+/**
+ * Calculates retry delays using configurable strategies.
+ *
+ * Supports three built-in strategies:
+ * - `exponential`: Delay doubles each attempt (1s, 2s, 4s, 8s, ...)
+ * - `linear`: Delay increases linearly (5s, 10s, 15s, 20s, ...)
+ * - `fixed`: Same delay every time (10s, 10s, 10s, ...)
+ *
+ * All strategies support:
+ * - `maxDelay`: Cap the maximum delay
+ * - `jitter`: Add randomness to prevent thundering herd
+ *
+ * @example
+ * ```typescript
+ * const strategy = new BackoffStrategy({
+ *   strategy: 'exponential',
+ *   baseDelay: '1s',
+ *   maxDelay: '5m',
+ *   multiplier: 2,
+ *   jitter: true,
+ * })
+ *
+ * strategy.calculateDelay(1) // ~1000ms
+ * strategy.calculateDelay(2) // ~2000ms
+ * strategy.calculateDelay(3) // ~4000ms
+ * ```
+ */
+declare class BackoffStrategy$1 {
+    #private;
+    /**
+     * Create a new backoff strategy.
+     *
+     * @param config - Backoff configuration
+     * @throws {E_INVALID_BASE_DELAY} If baseDelay is not positive
+     * @throws {E_INVALID_MAX_DELAY} If maxDelay is invalid
+     * @throws {E_INVALID_MULTIPLIER} If multiplier is invalid
+     */
+    constructor(config: BackoffConfig);
+    /**
+     * Calculate the delay for a given attempt number.
+     *
+     * @param attempt - The attempt number (1-based)
+     * @returns Delay in milliseconds
+     * @throws {RuntimeException} If attempt is less than 1
+     *
+     * @example
+     * ```typescript
+     * // Exponential: 1s, 2s, 4s, 8s, 16s, ...
+     * strategy.calculateDelay(1) // 1000
+     * strategy.calculateDelay(2) // 2000
+     * strategy.calculateDelay(3) // 4000
+     * ```
+     */
+    calculateDelay(attempt: number): number;
+    /**
+     * Get the Date when the next retry should occur.
+     *
+     * @param attempt - The attempt number (1-based)
+     * @returns Date for the next retry
+     *
+     * @example
+     * ```typescript
+     * const nextRetry = strategy.getNextRetryAt(3)
+     * console.log(`Retry at: ${nextRetry.toISOString()}`)
+     * ```
+     */
+    getNextRetryAt(attempt: number): Date;
+    /**
+     * Get a frozen copy of the configuration.
+     *
+     * @returns Readonly configuration object
+     */
+    getConfig(): Readonly<BackoffConfig>;
+}
+/**
+ * Create an exponential backoff strategy factory.
+ *
+ * Delay doubles with each attempt: 1s → 2s → 4s → 8s → ...
+ *
+ * Default config:
+ * - baseDelay: 1s
+ * - maxDelay: 5m
+ * - multiplier: 2
+ * - jitter: true
+ *
+ * @param config - Optional overrides for default config
+ * @returns Factory function for creating BackoffStrategy instances
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   retry: {
+ *     maxRetries: 5,
+ *     backoff: exponentialBackoff({ baseDelay: '500ms', maxDelay: '1m' }),
+ *   },
+ * }
+ * ```
+ */
+declare function exponentialBackoff(config?: Partial<Omit<BackoffConfig, 'strategy'>>): () => BackoffStrategy$1;
+/**
+ * Create a linear backoff strategy factory.
+ *
+ * Delay increases linearly: 5s → 10s → 15s → 20s → ...
+ *
+ * Default config:
+ * - baseDelay: 5s
+ * - maxDelay: 2m
+ *
+ * @param config - Optional overrides for default config
+ * @returns Factory function for creating BackoffStrategy instances
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   retry: {
+ *     maxRetries: 3,
+ *     backoff: linearBackoff({ baseDelay: '10s' }),
+ *   },
+ * }
+ * ```
+ */
+declare function linearBackoff(config?: Partial<Omit<BackoffConfig, 'strategy'>>): () => BackoffStrategy$1;
+/**
+ * Create a fixed delay backoff strategy factory.
+ *
+ * Same delay every time: 10s → 10s → 10s → ...
+ *
+ * @param delay - The fixed delay (default: '10s')
+ * @returns Factory function for creating BackoffStrategy instances
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   retry: {
+ *     maxRetries: 3,
+ *     backoff: fixedBackoff('30s'),
+ *   },
+ * }
+ * ```
+ */
+declare function fixedBackoff(delay?: Duration): () => BackoffStrategy$1;
+/**
+ * Create a custom backoff strategy factory.
+ *
+ * Use this when you need full control over the configuration.
+ *
+ * @param config - Complete backoff configuration
+ * @returns Factory function for creating BackoffStrategy instances
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   retry: {
+ *     maxRetries: 5,
+ *     backoff: customBackoff({
+ *       strategy: 'exponential',
+ *       baseDelay: '100ms',
+ *       maxDelay: '30s',
+ *       multiplier: 3,
+ *       jitter: false,
+ *     }),
+ *   },
+ * }
+ * ```
+ */
+declare function customBackoff(config: BackoffConfig): () => BackoffStrategy$1;
+
+interface LogObject {
+    [key: string]: unknown;
+}
+interface ErrorObject extends LogObject {
+    err?: Error;
+}
+interface Logger {
+    trace(msg: string): void;
+    trace(obj: LogObject, msg: string): void;
+    debug(msg: string): void;
+    debug(obj: LogObject, msg: string): void;
+    info(msg: string): void;
+    info(obj: LogObject, msg: string): void;
+    warn(msg: string): void;
+    warn(obj: LogObject, msg: string): void;
+    error(msg: string): void;
+    error(obj: ErrorObject, msg: string): void;
+    child(obj: LogObject): Logger;
+}
+
+type Duration = number | string;
+/**
+ * Result returned when dispatching a job.
+ *
+ * @example
+ * ```typescript
+ * const { jobId } = await SendEmailJob.dispatch(payload)
+ * console.log(`Dispatched job: ${jobId}`)
+ * ```
+ */
+interface DispatchResult {
+    /** Unique identifier for this specific job instance */
+    jobId: string;
+}
+interface JobData {
+    id: string;
+    name: string;
+    payload: any;
+    attempts: number;
+    priority?: number;
+    nextRetryAt?: Date;
+    stalledCount?: number;
+}
+interface JobOptions {
+    queue?: string;
+    adapter?: string | (() => Adapter);
+    maxRetries?: number;
+    priority?: number;
+    retry?: RetryConfig;
+    timeout?: Duration;
+    failOnTimeout?: boolean;
+}
+/**
+ * Context information available to a job during execution.
+ *
+ * Provides metadata about the current job execution, including
+ * retry information, queue details, and timing.
+ *
+ * @example
+ * ```typescript
+ * class MyJob extends Job<Payload> {
+ *   async execute() {
+ *     console.log(`Attempt ${this.context.attempt} of job ${this.context.jobId}`)
+ *     console.log(`Running on queue: ${this.context.queue}`)
+ *   }
+ * }
+ * ```
+ */
+interface JobContext {
+    /** Unique identifier for this job */
+    jobId: string;
+    /** Job class name */
+    name: string;
+    /** Current attempt number (1-based: first attempt = 1) */
+    attempt: number;
+    /** Queue name this job is being processed from */
+    queue: string;
+    /** Job priority (lower number = higher priority) */
+    priority: number;
+    /** When this job was acquired by the worker for processing */
+    acquiredAt: Date;
+    /** Number of times this job has been recovered from stalled state */
+    stalledCount: number;
+}
+type JobClass<T extends Job = Job> = (new (payload: any, context: JobContext) => T) & {
+    options?: JobOptions;
+};
+/**
+ * Factory function for custom job instantiation.
+ *
+ * Use this to integrate with IoC containers for dependency injection.
+ * The factory receives the job class, payload, and context, and must return
+ * a job instance (or a Promise that resolves to one).
+ *
+ * @param JobClass - The job class to instantiate
+ * @param payload - The payload data for the job
+ * @param context - The job execution context (jobId, attempt, queue, etc.)
+ * @returns The job instance, or a Promise resolving to the instance
+ *
+ * @example
+ * ```typescript
+ * // With AdonisJS IoC container
+ * const worker = new Worker({
+ *   worker: {
+ *     jobFactory: async (JobClass, payload, context) => {
+ *       return app.container.make(JobClass, [payload, context])
+ *     }
+ *   }
+ * })
+ * ```
+ */
+type JobFactory = (JobClass: JobClass, payload: any, context: JobContext) => Job | Promise<Job>;
+interface RetryConfig {
+    maxRetries?: number;
+    backoff?: () => BackoffStrategy$1;
+}
+type BackoffStrategy = 'exponential' | 'linear' | 'fixed';
+interface BackoffConfig {
+    strategy: BackoffStrategy;
+    baseDelay: Duration;
+    maxDelay?: Duration;
+    multiplier?: number;
+    jitter?: boolean;
+}
+interface QueueConfig {
+    adapter?: string;
+    retry?: any;
+}
+interface WorkerConfig {
+    /**
+     * Maximum number of jobs to process concurrently.
+     * @default 1
+     */
+    concurrency?: number;
+    /**
+     * Delay between queue polls when idle (no jobs available).
+     * @default '2s'
+     */
+    idleDelay?: Duration;
+    /**
+     * Maximum duration a job can run before being timed out.
+     * Can be overridden per job via JobOptions.timeout.
+     * @default undefined (no timeout)
+     */
+    timeout?: Duration;
+    /**
+     * Duration after which an active job is considered stalled.
+     * A stalled job is one that was acquired but the worker stopped
+     * responding (e.g., due to a crash).
+     * @default '30s'
+     */
+    stalledThreshold?: Duration;
+    /**
+     * How often to check for stalled jobs.
+     * @default '30s'
+     */
+    stalledInterval?: Duration;
+    /**
+     * Maximum number of times a job can be recovered from stalled state
+     * before being marked as failed permanently.
+     * @default 1
+     */
+    maxStalledCount?: number;
+    /**
+     * Whether to automatically stop the worker on SIGINT/SIGTERM signals.
+     * When enabled, the worker will wait for running jobs to complete
+     * before stopping.
+     * @default true
+     */
+    gracefulShutdown?: boolean;
+    /**
+     * Callback invoked when a shutdown signal is received.
+     * Called before the worker starts stopping.
+     */
+    onShutdownSignal?: () => void | Promise<void>;
+}
+type WorkerCycle = {
+    type: 'started';
+    queue: string;
+    job: any;
+} | {
+    type: 'completed';
+    queue: string;
+    job: any;
+} | {
+    type: 'idle';
+    suggestedDelay: Duration;
+} | {
+    type: 'error';
+    error: Error;
+    suggestedDelay: Duration;
+};
+type AdapterFactory<T extends Adapter = Adapter> = () => T;
+/**
+ * Status of a schedule.
+ */
+type ScheduleStatus = 'active' | 'paused';
+/**
+ * Configuration for creating a schedule.
+ * Used by ScheduleBuilder to collect schedule options before creation.
+ */
+interface ScheduleConfig {
+    /** Optional ID for the schedule (UUID if not set). Used for upsert. */
+    id?: string;
+    /** Job class name */
+    jobName: string;
+    /** Job payload */
+    payload: any;
+    /** Cron expression (mutually exclusive with everyMs) */
+    cronExpression?: string;
+    /** Interval in milliseconds (mutually exclusive with cronExpression) */
+    everyMs?: number;
+    /** IANA timezone for cron evaluation */
+    timezone: string;
+    /** Start boundary - no jobs dispatched before this */
+    from?: Date;
+    /** End boundary - no jobs dispatched after this */
+    to?: Date;
+    /** Maximum number of runs (null = unlimited) */
+    limit?: number;
+}
+/**
+ * Persisted schedule data.
+ * Represents a schedule stored in the adapter.
+ */
+interface ScheduleData {
+    /** Unique identifier */
+    id: string;
+    /** Job class name */
+    jobName: string;
+    /** Job payload */
+    payload: any;
+    /** Cron expression (null if using interval) */
+    cronExpression: string | null;
+    /** Interval in milliseconds (null if using cron) */
+    everyMs: number | null;
+    /** IANA timezone */
+    timezone: string;
+    /** Start boundary - no jobs dispatched before this */
+    from: Date | null;
+    /** End boundary - no jobs dispatched after this */
+    to: Date | null;
+    /** Maximum number of runs */
+    limit: number | null;
+    /** Number of times this schedule has run */
+    runCount: number;
+    /** Next scheduled run time */
+    nextRunAt: Date | null;
+    /** Last run time */
+    lastRunAt: Date | null;
+    /** Current status */
+    status: ScheduleStatus;
+    /** When the schedule was created */
+    createdAt: Date;
+}
+/**
+ * Result returned when creating a schedule.
+ */
+interface ScheduleResult {
+    /** Unique identifier for the schedule */
+    scheduleId: string;
+}
+/**
+ * Options for listing schedules.
+ */
+interface ScheduleListOptions {
+    /** Filter by status */
+    status?: ScheduleStatus;
+}
+interface QueueManagerConfig {
+    default: string;
+    adapters: Record<string, AdapterFactory>;
+    retry?: RetryConfig;
+    queues?: Record<string, QueueConfig>;
+    worker?: WorkerConfig;
+    locations?: string[];
+    logger?: Logger;
+    /**
+     * Custom factory function for job instantiation.
+     *
+     * Use this to integrate with IoC containers for dependency injection.
+     * When provided, this factory is called instead of `new JobClass(payload, context)`.
+     *
+     * @example
+     * ```typescript
+     * await QueueManager.init({
+     *   default: 'redis',
+     *   adapters: { redis: redis() },
+     *   jobFactory: async (JobClass, payload, context) => {
+     *     return app.container.make(JobClass, [payload, context])
+     *   }
+     * })
+     * ```
+     */
+    jobFactory?: JobFactory;
+}
+
+/**
+ * A job that has been acquired by a worker for processing.
+ * Extends JobData with the timestamp when the job was acquired.
+ */
+interface AcquiredJob extends JobData {
+    /** Timestamp (in ms) when the job was acquired by the worker */
+    acquiredAt: number;
+}
+/**
+ * Adapter interface for queue storage backends.
+ *
+ * Implementations handle job persistence, atomic operations, and
+ * concurrency control. Built-in adapters: Redis, Knex (PostgreSQL/SQLite).
+ *
+ * @example
+ * ```typescript
+ * import { redis } from '@boringnode/queue'
+ *
+ * const config = {
+ *   default: 'redis',
+ *   adapters: {
+ *     redis: redis({ host: 'localhost', port: 6379 })
+ *   }
+ * }
+ * ```
+ */
+interface Adapter {
+    /**
+     * Set the worker ID for this adapter instance.
+     * Required before calling pop methods when consuming jobs.
+     *
+     * @param workerId - Unique identifier for the worker
+     */
+    setWorkerId(workerId: string): void;
+    /**
+     * Pop the next available job from the default queue.
+     * Atomically moves the job from pending to active state.
+     *
+     * @returns The acquired job, or null if queue is empty
+     */
+    pop(): Promise<AcquiredJob | null>;
+    /**
+     * Pop the next available job from a specific queue.
+     * Atomically moves the job from pending to active state.
+     *
+     * @param queue - The queue name to pop from
+     * @returns The acquired job, or null if queue is empty
+     */
+    popFrom(queue: string): Promise<AcquiredJob | null>;
+    /**
+     * Recover stalled jobs that have been active for too long.
+     * A stalled job is one where the worker stopped responding (e.g., crash).
+     *
+     * Jobs within maxStalledCount are moved back to pending.
+     * Jobs exceeding maxStalledCount are failed permanently.
+     *
+     * @param queue - The queue to check for stalled jobs
+     * @param stalledThreshold - Duration in ms after which a job is considered stalled
+     * @param maxStalledCount - Maximum times a job can be recovered before failing
+     * @returns Number of jobs that were recovered (not including permanently failed ones)
+     */
+    recoverStalledJobs(queue: string, stalledThreshold: number, maxStalledCount: number): Promise<number>;
+    /**
+     * Mark a job as completed and remove it from the queue.
+     *
+     * @param jobId - The job ID to complete
+     * @param queue - The queue the job belongs to
+     */
+    completeJob(jobId: string, queue: string): Promise<void>;
+    /**
+     * Mark a job as failed permanently and remove it from the queue.
+     *
+     * @param jobId - The job ID to fail
+     * @param queue - The queue the job belongs to
+     * @param error - Optional error that caused the failure
+     */
+    failJob(jobId: string, queue: string, error?: Error): Promise<void>;
+    /**
+     * Retry a job by moving it back to pending with incremented attempts.
+     *
+     * @param jobId - The job ID to retry
+     * @param queue - The queue the job belongs to
+     * @param retryAt - Optional future date to delay the retry
+     */
+    retryJob(jobId: string, queue: string, retryAt?: Date): Promise<void>;
+    /**
+     * Push a job to the default queue for immediate processing.
+     *
+     * @param jobData - The job data to push
+     */
+    push(jobData: JobData): Promise<void>;
+    /**
+     * Push a job to a specific queue for immediate processing.
+     *
+     * @param queue - The queue name to push to
+     * @param jobData - The job data to push
+     */
+    pushOn(queue: string, jobData: JobData): Promise<void>;
+    /**
+     * Push a job to the default queue with a delay.
+     *
+     * @param jobData - The job data to push
+     * @param delay - Delay in milliseconds before the job becomes available
+     */
+    pushLater(jobData: JobData, delay: number): Promise<void>;
+    /**
+     * Push a job to a specific queue with a delay.
+     *
+     * @param queue - The queue name to push to
+     * @param jobData - The job data to push
+     * @param delay - Delay in milliseconds before the job becomes available
+     */
+    pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<void>;
+    /**
+     * Get the number of pending jobs in the default queue.
+     *
+     * @returns The number of pending jobs
+     */
+    size(): Promise<number>;
+    /**
+     * Get the number of pending jobs in a specific queue.
+     *
+     * @param queue - The queue name to check
+     * @returns The number of pending jobs
+     */
+    sizeOf(queue: string): Promise<number>;
+    /**
+     * Clean up resources (close connections, etc.).
+     * Called when the worker stops or the adapter is no longer needed.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Create or update a schedule.
+     *
+     * If a schedule with the given id exists, it will be updated (upsert).
+     * Otherwise, a new schedule is created.
+     *
+     * @param config - The schedule configuration
+     * @returns The schedule ID
+     */
+    createSchedule(config: ScheduleConfig): Promise<string>;
+    /**
+     * Get a schedule by ID.
+     *
+     * @param id - The schedule ID
+     * @returns The schedule data, or null if not found
+     */
+    getSchedule(id: string): Promise<ScheduleData | null>;
+    /**
+     * List all schedules matching the given options.
+     *
+     * @param options - Optional filters for listing
+     * @returns Array of schedule data
+     */
+    listSchedules(options?: ScheduleListOptions): Promise<ScheduleData[]>;
+    /**
+     * Update a schedule's status or run metadata.
+     *
+     * @param id - The schedule ID
+     * @param updates - The fields to update
+     */
+    updateSchedule(id: string, updates: Partial<Pick<ScheduleData, 'status' | 'nextRunAt' | 'lastRunAt' | 'runCount'>>): Promise<void>;
+    /**
+     * Delete a schedule permanently.
+     *
+     * @param id - The schedule ID to delete
+     */
+    deleteSchedule(id: string): Promise<void>;
+    /**
+     * Atomically claim a due schedule for execution.
+     *
+     * This method:
+     * 1. Finds ONE schedule where nextRunAt <= now AND status = 'active'
+     * 2. Calculates and updates its nextRunAt to the next occurrence
+     * 3. Increments runCount and sets lastRunAt
+     * 4. Returns the schedule data for job dispatching
+     *
+     * The atomic nature prevents multiple workers from claiming the same schedule.
+     *
+     * @returns The claimed schedule, or null if no schedules are due
+     */
+    claimDueSchedule(): Promise<ScheduleData | null>;
+}
+
+/**
+ * Fluent builder for dispatching jobs to the queue.
+ *
+ * Provides a chainable API for configuring job options before dispatch.
+ * Usually created via `Job.dispatch()` rather than directly.
+ *
+ * ```
+ * Job.dispatch(payload)
+ *     .toQueue('emails')     // optional: target queue
+ *     .priority(1)           // optional: 1-10, lower = higher priority
+ *     .in('5m')              // optional: delay before processing
+ *     .with('redis')         // optional: specific adapter
+ *     .run()                 // dispatch the job
+ * ```
+ *
+ * @typeParam T - The payload type for this job
+ *
+ * @example
+ * ```typescript
+ * // Simple dispatch (auto-runs via thenable)
+ * await SendEmailJob.dispatch({ to: 'user@example.com', subject: 'Hello' })
+ *
+ * // With options
+ * const jobId = await SendEmailJob.dispatch({ to: 'user@example.com' })
+ *   .toQueue('high-priority')
+ *   .priority(1)
+ *   .run()
+ *
+ * // Delayed job
+ * await ReminderJob.dispatch({ userId: 123 }).in('24h')
+ * ```
+ */
+declare class JobDispatcher<T> {
+    #private;
+    /**
+     * Create a new job dispatcher.
+     *
+     * @param name - The job class name (used to locate the class at runtime)
+     * @param payload - The data to pass to the job
+     */
+    constructor(name: string, payload: T);
+    /**
+     * Set the target queue for this job.
+     *
+     * @param queue - Queue name (default: 'default')
+     * @returns This dispatcher for chaining
+     *
+     * @example
+     * ```typescript
+     * await SendEmailJob.dispatch(payload).toQueue('emails')
+     * ```
+     */
+    toQueue(queue: string): this;
+    /**
+     * Delay the job execution.
+     *
+     * The job will be stored in a delayed state and moved to pending
+     * after the delay expires.
+     *
+     * @param delay - Delay as milliseconds or duration string ('5s', '1h', '7d')
+     * @returns This dispatcher for chaining
+     *
+     * @example
+     * ```typescript
+     * // Send reminder in 24 hours
+     * await ReminderJob.dispatch(payload).in('24h')
+     *
+     * // Process in 5 minutes
+     * await CleanupJob.dispatch(payload).in('5m')
+     * ```
+     */
+    in(delay: Duration): this;
+    /**
+     * Set the job priority.
+     *
+     * Lower numbers = higher priority. Jobs with lower priority values
+     * are processed before jobs with higher values.
+     *
+     * @param priority - Priority level (1-10, default: 5)
+     * @returns This dispatcher for chaining
+     *
+     * @example
+     * ```typescript
+     * // High priority job
+     * await UrgentJob.dispatch(payload).priority(1)
+     *
+     * // Low priority job
+     * await BackgroundJob.dispatch(payload).priority(10)
+     * ```
+     */
+    priority(priority: number): this;
+    /**
+     * Use a specific adapter for this job.
+     *
+     * @param adapter - Adapter name or factory function
+     * @returns This dispatcher for chaining
+     *
+     * @example
+     * ```typescript
+     * // Use named adapter
+     * await Job.dispatch(payload).with('redis')
+     *
+     * // Use custom adapter instance
+     * await Job.dispatch(payload).with(() => new CustomAdapter())
+     * ```
+     */
+    with(adapter: string | (() => Adapter)): this;
+    /**
+     * Dispatch the job to the queue.
+     *
+     * @returns A DispatchResult containing the jobId
+     *
+     * @example
+     * ```typescript
+     * const { jobId } = await SendEmailJob.dispatch(payload).run()
+     * console.log(`Dispatched job: ${jobId}`)
+     * ```
+     */
+    run(): Promise<DispatchResult>;
+    /**
+     * Thenable implementation for auto-dispatch when awaited.
+     *
+     * Allows `await Job.dispatch(payload)` without explicit `.run()`.
+     *
+     * @param onFulfilled - Success callback
+     * @param onRejected - Error callback
+     * @returns Promise resolving to the DispatchResult
+     */
+    then(onFulfilled?: (value: DispatchResult) => any, onRejected?: (reason: any) => any): Promise<any>;
+}
+
+/**
+ * Fluent builder for creating job schedules.
+ *
+ * @example
+ * ```typescript
+ * // Create with cron
+ * const { scheduleId } = await new ScheduleBuilder('CleanupJob', { days: 30 })
+ *   .id('cleanup-daily')
+ *   .cron('0 0 * * *')
+ *   .timezone('Europe/Paris')
+ *   .run()
+ *
+ * // Create with interval
+ * const { scheduleId } = await new ScheduleBuilder('SyncJob', {})
+ *   .every('5m')
+ *   .run()
+ * ```
+ */
+declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
+    #private;
+    constructor(jobName: string, payload: any);
+    /**
+     * Set a custom schedule ID.
+     * If not specified, defaults to the job name.
+     * If a schedule with this ID exists, it will be updated (upsert).
+     */
+    id(scheduleId: string): this;
+    /**
+     * Set a cron expression for the schedule.
+     * Mutually exclusive with `every()`.
+     */
+    cron(expression: string): this;
+    /**
+     * Set a repeating interval for the schedule.
+     * Mutually exclusive with `cron()`.
+     */
+    every(interval: Duration): this;
+    /**
+     * Set the timezone for cron evaluation.
+     * @default 'UTC'
+     */
+    timezone(tz: string): this;
+    /**
+     * Set the start boundary for the schedule.
+     * No jobs will be dispatched before this date.
+     */
+    from(date: Date): this;
+    /**
+     * Set the end boundary for the schedule.
+     * No jobs will be dispatched after this date.
+     */
+    to(date: Date): this;
+    /**
+     * Set both start and end boundaries for the schedule.
+     * Shorthand for `.from(start).to(end)`.
+     */
+    between(from: Date, to: Date): this;
+    /**
+     * Set the maximum number of runs for this schedule.
+     */
+    limit(maxRuns: number): this;
+    /**
+     * Create the schedule and return the schedule ID.
+     */
+    run(): Promise<ScheduleResult>;
+    /**
+     * Implement PromiseLike to allow `await builder.every('5m')` syntax.
+     */
+    then<TResult1 = ScheduleResult, TResult2 = never>(onfulfilled?: ((value: ScheduleResult) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}
+
+/**
+ * Abstract base class for all queue jobs.
+ *
+ * Extend this class to create your own jobs. Each job must implement
+ * the `execute()` method which contains the job's business logic.
+ *
+ * @typeParam Payload - The type of data this job receives
+ *
+ * @example
+ * ```typescript
+ * import { Job } from '@boringnode/queue'
+ * import type { JobContext } from '@boringnode/queue'
+ *
+ * interface SendEmailPayload {
+ *   to: string
+ *   subject: string
+ *   body: string
+ * }
+ *
+ * export default class SendEmailJob extends Job<SendEmailPayload> {
+ *   static options = {
+ *     queue: 'emails',
+ *     maxRetries: 3,
+ *   }
+ *
+ *   constructor(payload: SendEmailPayload, context: JobContext) {
+ *     super(payload, context)
+ *   }
+ *
+ *   async execute() {
+ *     console.log(`Attempt ${this.context.attempt} for job ${this.context.jobId}`)
+ *     await sendEmail(this.payload.to, this.payload.subject, this.payload.body)
+ *   }
+ *
+ *   async failed(error: Error) {
+ *     console.error(`Failed to send email to ${this.payload.to}:`, error)
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Job<Payload = any> {
+    #private;
+    /** Static options for this job class (queue, retries, timeout, etc.) */
+    static options: JobOptions;
+    /** The payload data passed to this job instance */
+    get payload(): Payload;
+    /**
+     * Context information for the current job execution.
+     *
+     * Provides metadata such as job ID, current attempt number,
+     * queue name, priority, and timing information.
+     *
+     * @example
+     * ```typescript
+     * async execute() {
+     *   if (this.context.attempt > 1) {
+     *     console.log(`Retry attempt ${this.context.attempt}`)
+     *   }
+     *   console.log(`Processing job ${this.context.jobId} on queue ${this.context.queue}`)
+     * }
+     * ```
+     */
+    get context(): JobContext;
+    /**
+     * Create a new job instance.
+     *
+     * @param payload - The data to be processed by this job
+     * @param context - The job execution context (provided by the worker)
+     */
+    constructor(payload: Payload, context: JobContext);
+    /**
+     * Dispatch this job to the queue.
+     *
+     * Returns a JobDispatcher for fluent configuration before dispatching.
+     * The job is not actually dispatched until `.run()` is called or the
+     * dispatcher is awaited.
+     *
+     * @param payload - The data to pass to the job
+     * @returns A JobDispatcher for fluent configuration
+     *
+     * @example
+     * ```typescript
+     * // Simple dispatch
+     * await SendEmailJob.dispatch({ to: 'user@example.com', subject: 'Hello' })
+     *
+     * // With options
+     * await SendEmailJob.dispatch({ to: 'user@example.com' })
+     *   .toQueue('high-priority')
+     *   .priority(1)
+     *   .in('5m')
+     *   .run()
+     * ```
+     */
+    static dispatch<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
+    /**
+     * Create a schedule for this job.
+     *
+     * Returns a ScheduleBuilder for fluent configuration before creating the schedule.
+     * The schedule is not actually created until `.run()` is called or the
+     * builder is awaited.
+     *
+     * @param payload - The data to pass to the job on each run
+     * @returns A ScheduleBuilder for fluent configuration
+     *
+     * @example
+     * ```typescript
+     * // Cron schedule
+     * await CleanupJob.schedule({ days: 30 })
+     *   .id('cleanup-daily')
+     *   .cron('0 0 * * *')
+     *   .timezone('Europe/Paris')
+     *   .run()
+     *
+     * // Interval schedule
+     * await SyncJob.schedule({ source: 'api' })
+     *   .every('5m')
+     *   .run()
+     * ```
+     */
+    static schedule<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder;
+    /**
+     * Execute the job's business logic.
+     *
+     * This method is called by the worker when processing the job.
+     * Implement your job's logic here.
+     *
+     * @param signal - Optional AbortSignal for timeout handling.
+     *                 Check `signal.aborted` for long-running operations.
+     * @throws Any error thrown will trigger retry logic (if configured)
+     *
+     * @example
+     * ```typescript
+     * async execute(signal?: AbortSignal) {
+     *   for (const item of this.payload.items) {
+     *     if (signal?.aborted) {
+     *       throw new Error('Job timed out')
+     *     }
+     *     await processItem(item)
+     *   }
+     * }
+     * ```
+     */
+    abstract execute(signal?: AbortSignal): Promise<void>;
+    /**
+     * Called when the job has permanently failed (after all retries exhausted).
+     *
+     * Use this hook for cleanup, logging, or notifications.
+     * This is optional - implement only if you need failure handling.
+     *
+     * @param error - The error that caused the final failure
+     *
+     * @example
+     * ```typescript
+     * async failed(error: Error) {
+     *   await notifyAdmin(`Job failed: ${error.message}`)
+     *   await cleanup(this.payload)
+     * }
+     * ```
+     */
+    failed?(error: Error): Promise<void>;
+}
+
+export { type Adapter as A, type BackoffStrategy as B, type Duration as D, type JobData as J, type Logger as L, type QueueManagerConfig as Q, type RetryConfig as R, type ScheduleConfig as S, type WorkerCycle as W, type AcquiredJob as a, type ScheduleData as b, type ScheduleListOptions as c, type JobFactory as d, Job as e, type JobClass as f, type ScheduleStatus as g, ScheduleBuilder as h, customBackoff as i, exponentialBackoff as j, fixedBackoff as k, linearBackoff as l, type DispatchResult as m, type JobOptions as n, type JobContext as o, type BackoffConfig as p, type QueueConfig as q, type WorkerConfig as r, type AdapterFactory as s, type ScheduleResult as t };