fix(backoff): accept a per-attempt backoff schedule in JobOptions

`JobOptions.backoff` only described the `{ type, delay }` strategy, so the
per-attempt array a job class declares via `withBackoff()` had nowhere to go:
every path that turned a job class into job options collapsed it to
`{ type: 'fixed', delay: backoff[0] }`, silently dropping the rest of the
schedule. Callers that wanted the array had to cast, and the cast compiled to
a `backoff` the worker could not read at all -- it only ever looked at `.type`
and `.delay`, so an array meant a zero delay and an immediate retry.

Widen the type to `BackoffOptions` and resolve both forms through one shared
`backoffDelay()` helper, which clamps an exhausted schedule to its last entry
instead of falling through to no wait.

Author: chrisbbreuer

docs/guide/jobs.md

@@ -50,10 +50,9 @@ await queue.add(
 interface JobOptions {
   delay?: number              // Delay before processing (ms)
   attempts?: number           // Max retry attempts
-  backoff?: {
-    type: 'fixed' | 'exponential'
-    delay: number             // Base delay in ms
-  }
+  backoff?:                   // Retry backoff, in ms
+    | { type: 'fixed' | 'exponential', delay: number }
+    | number[]                // Explicit per-attempt schedule
   removeOnComplete?: boolean | number  // Remove after completion (or keep N jobs)
   removeOnFail?: boolean | number      // Remove after failure (or keep N jobs)
   priority?: number           // Higher = processed first
@@ -122,8 +121,22 @@ await queue.add(
     }
   }
 )
+
+// Explicit schedule: 1s, then 5s, then 30s for every attempt after that.
+// A schedule shorter than `attempts` clamps to its last entry rather than
+// dropping to no wait at all.
+await queue.add(
+  { task: 'api-call' },
+  {
+    attempts: 5,
+    backoff: [1000, 5000, 30000]
+  }
+)
 ```
 
+This is the same schedule a job class declares with `withBackoff()`, so a job
+class dispatched through a plain `queue.add()` keeps its full retry timing.
+
 ## Job Management
 
 ### Get Job by ID

packages/bun-queue/src/job-base.ts

@@ -92,7 +92,7 @@ export abstract class JobBase implements JobContract, Queueable, Dispatchable, I
       delay: this.delay,
       attempts: this.tries,
       timeout: this.timeout,
-      backoff: this.backoff ? { type: 'fixed', delay: this.backoff[0] } : undefined,
+      backoff: this.backoff,
       jobId: this.uniqueId?.(),
     }
 

packages/bun-queue/src/queue.ts

@@ -1031,7 +1031,7 @@ export class Queue<T = any> {
       delay: job.delay,
       attempts: job.tries,
       timeout: job.timeout,
-      backoff: job.backoff ? { type: 'fixed', delay: job.backoff[0] } : undefined,
+      backoff: job.backoff,
       jobId: job.uniqueId?.(),
       removeOnComplete: true,
       removeOnFail: false,
@@ -1078,7 +1078,7 @@ export class Queue<T = any> {
         delay: job.delay,
         attempts: job.tries,
         timeout: job.timeout,
-        backoff: job.backoff ? { type: 'fixed', delay: job.backoff[0] } : undefined,
+        backoff: job.backoff,
         jobId: job.uniqueId?.() ? `${batchId}_${job.uniqueId()}` : undefined,
       }
 

packages/bun-queue/src/types.ts

@@ -60,13 +60,29 @@ export type { RedisClient }
 
 export type JobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused'
 
-export interface JobOptions {
-  delay?: number
-  attempts?: number
-  backoff?: {
+/**
+ * Retry backoff, in milliseconds.
+ *
+ * The object form describes a strategy: `fixed` waits `delay` before every
+ * retry, `exponential` doubles it each attempt (`delay * 2 ** (n - 1)`).
+ *
+ * The array form gives an explicit per-attempt schedule — `[1000, 5000, 30000]`
+ * waits 1s after the first failure, 5s after the second, and 30s after the
+ * third and every one after it. This is what job classes express through
+ * `withBackoff()`, and it is accepted here so the same schedule survives a
+ * plain `queue.add()`.
+ */
+export type BackoffOptions =
+  | {
     type: 'fixed' | 'exponential'
     delay: number
   }
+  | number[]
+
+export interface JobOptions {
+  delay?: number
+  attempts?: number
+  backoff?: BackoffOptions
   removeOnComplete?: boolean | number
   removeOnFail?: boolean | number
   priority?: number

packages/bun-queue/src/utils.ts

@@ -1,4 +1,4 @@
-import type { JobOptions, QueueConfig } from './types'
+import type { BackoffOptions, JobOptions, QueueConfig } from './types'
 import { RedisClient } from 'bun'
 import process from 'node:process'
 import { config } from './config'
@@ -34,6 +34,34 @@ export function mergeOptions(options?: JobOptions): JobOptions {
   }
 }
 
+/**
+ * Resolves a backoff setting into the delay, in milliseconds, to wait before
+ * the next attempt.
+ *
+ * `attemptsMade` is the number of attempts that have already failed, so it is
+ * 1 when the first attempt has just failed. An explicit per-attempt array is
+ * indexed by that attempt (`backoff[attemptsMade - 1]`) and clamps to its last
+ * entry once the schedule runs out, which is what makes `[1000, 5000]` mean
+ * "1s, then 5s from here on" rather than "1s, 5s, then no wait at all".
+ */
+export function backoffDelay(backoff: BackoffOptions | undefined, attemptsMade: number): number {
+  if (!backoff)
+    return 0
+
+  if (Array.isArray(backoff)) {
+    if (backoff.length === 0)
+      return 0
+
+    const index = Math.min(Math.max(attemptsMade - 1, 0), backoff.length - 1)
+    return Number(backoff[index]) || 0
+  }
+
+  if (backoff.type === 'exponential')
+    return backoff.delay * 2 ** Math.max(attemptsMade - 1, 0)
+
+  return backoff.delay
+}
+
 /**
  * Gets key with prefix
  */

packages/bun-queue/src/worker.ts

@@ -1,5 +1,6 @@
 import type { Job } from './job'
 import type { Queue } from './queue'
+import { backoffDelay } from './utils'
 
 export class Worker<T = any> {
   queue: Queue<T>
@@ -200,15 +201,7 @@ export class Worker<T = any> {
 
         if (job.attemptsMade < maxAttempts) {
           // Calculate delay for retry based on backoff strategy
-          let delay = 0
-          if (job.opts.backoff) {
-            if (job.opts.backoff.type === 'fixed') {
-              delay = job.opts.backoff.delay
-            }
-            else if (job.opts.backoff.type === 'exponential') {
-              delay = job.opts.backoff.delay * 2 ** (job.attemptsMade - 1)
-            }
-          }
+          const delay = backoffDelay(job.opts.backoff, job.attemptsMade)
 
           if (delay > 0) {
             // Add to delayed set

packages/bun-queue/test/backoff.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test'
+import { backoffDelay } from '../src/utils'
+
+describe('backoffDelay', () => {
+  test('returns no delay when backoff is unset', () => {
+    expect(backoffDelay(undefined, 1)).toBe(0)
+  })
+
+  test('fixed backoff waits the same delay on every attempt', () => {
+    const backoff = { type: 'fixed', delay: 5000 } as const
+
+    expect(backoffDelay(backoff, 1)).toBe(5000)
+    expect(backoffDelay(backoff, 2)).toBe(5000)
+    expect(backoffDelay(backoff, 9)).toBe(5000)
+  })
+
+  test('exponential backoff doubles from the base delay', () => {
+    const backoff = { type: 'exponential', delay: 1000 } as const
+
+    expect(backoffDelay(backoff, 1)).toBe(1000)
+    expect(backoffDelay(backoff, 2)).toBe(2000)
+    expect(backoffDelay(backoff, 3)).toBe(4000)
+    expect(backoffDelay(backoff, 4)).toBe(8000)
+  })
+
+  test('an array is an explicit per-attempt schedule in milliseconds', () => {
+    const backoff = [1000, 5000, 30000]
+
+    expect(backoffDelay(backoff, 1)).toBe(1000)
+    expect(backoffDelay(backoff, 2)).toBe(5000)
+    expect(backoffDelay(backoff, 3)).toBe(30000)
+  })
+
+  test('an exhausted schedule clamps to its last entry', () => {
+    expect(backoffDelay([1000, 5000], 3)).toBe(5000)
+    expect(backoffDelay([1000, 5000], 100)).toBe(5000)
+  })
+
+  test('an empty schedule retries immediately', () => {
+    expect(backoffDelay([], 1)).toBe(0)
+  })
+
+  test('a zero or negative attempt count reads the first entry', () => {
+    expect(backoffDelay([1000, 5000], 0)).toBe(1000)
+    expect(backoffDelay({ type: 'exponential', delay: 1000 }, 0)).toBe(1000)
+  })
+})