@rvoh/psychic-workers 2.6.0 → 2.7.0

package/dist/esm/src/error/background/DebouncedJobOutpacesRateLimit.js

@@ -0,0 +1,64 @@
+/**
+ * Not exported from the package: a delayed background job carried a `jobId`
+ * behind a delay short enough that it can enqueue work faster than its own
+ * queue's rate limit allows that work to start. Thrown from `_addToQueue`,
+ * above the test-mode short circuit, so a consumer's test environment raises it
+ * exactly as production does.
+ */
+export default class DebouncedJobOutpacesRateLimit extends Error {
+    jobId;
+    delayMs;
+    keyLifetimeMs;
+    limiter;
+    queue;
+    constructor(jobId, delayMs, keyLifetimeMs, limiter, queue) {
+        super();
+        this.jobId = jobId;
+        this.delayMs = delayMs;
+        this.keyLifetimeMs = keyLifetimeMs;
+        this.limiter = limiter;
+        this.queue = queue;
+    }
+    get message() {
+        return `
+A delayed background job was given the \`jobId\` ${JSON.stringify(this.jobId)} behind a delay of ${this.seconds(this.delayMs)}, but ${this.where}
+is rate limited to ${this.limiter.max} job${this.limiter.max === 1 ? '' : 's'} every ${this.limiter.duration}ms — one job every ${this.seconds(this.msPerJob)}.
+
+\`jobId\` is a deduplication key, and the key that does the collapsing lives ${this.seconds(this.keyLifetimeMs)} (the delay minus a
+one-second margin). Calls closer together than that are collapsed; calls further apart than that stop collapsing
+and produce a job each. This \`jobId\` can therefore enqueue a job every ${this.seconds(this.keyLifetimeMs)}, which is faster than
+this ${this.kind} can start them. Under a sustained stream of calls the backlog grows without bound — the rate
+limit keeps the downstream service safe while it happens, so nothing fails and the jobs simply pile up in Redis.
+
+Either give the delay at least ${this.seconds(this.minimumDelayMs)}, so that calls which stop collapsing still cannot outrun the rate
+limit, or move the job to a ${this.kind} of its own — one with no rate limit, or one whose limit fits this job's
+endpoint. A burst that stops arriving is collapsed into one run at any delay, but which pattern a caller has is
+not knowable here. Nothing was enqueued.
+`;
+    }
+    get msPerJob() {
+        return this.limiter.duration / this.limiter.max;
+    }
+    /**
+     * the shortest delay that would pass: enough that the key outlives the
+     * limiter's spacing. Rounded up to a whole second, since the delay is given
+     * in whole-ish duration fields and a value that still failed by a fraction
+     * of a second would be a hostile suggestion.
+     */
+    get minimumDelayMs() {
+        return Math.ceil((this.msPerJob + (this.delayMs - this.keyLifetimeMs)) / 1000) * 1000;
+    }
+    seconds(ms) {
+        const secs = ms / 1000;
+        const rendered = Number.isInteger(secs) ? String(secs) : secs.toFixed(2).replace(/\.?0+$/, '');
+        return `${rendered} second${rendered === '1' ? '' : 's'}`;
+    }
+    get kind() {
+        return this.queue.mode === 'simple' ? 'workstream' : 'queue';
+    }
+    get where() {
+        if (this.queue.isDefaultQueue)
+            return `the default ${this.kind}`;
+        return `the \`${this.queue.configuredName}\` ${this.queue.transitional ? 'transitional ' : ''}${this.kind}`;
+    }
+}

package/dist/esm/src/error/background/DebouncedJobRequiresMinimumDelay.js

@@ -0,0 +1,52 @@
+/**
+ * Not exported from the package, and deliberately so: every branch of the guard
+ * that throws it is a call-site mistake — a `jobId` behind a delay under the
+ * floor, an empty `jobId`, or a delay that is zero, negative, `Infinity`, `NaN`
+ * or past `Number.MAX_SAFE_INTEGER` — so an application can never usefully
+ * catch it. The fix is always an edit to the call.
+ *
+ * `durationToSeconds` catches none of these: it validates nothing, and its
+ * falsy-field sum silently drops a `NaN` field rather than propagating it
+ * (`{ hours: 1, seconds: NaN }` is `3600`), so `{ seconds: NaN }` reaches this
+ * check as `0`.
+ *
+ * The check runs before the test-mode short circuit in `_addToQueue`, so a
+ * consumer's default test environment raises this exactly as production does.
+ */
+export default class DebouncedJobRequiresMinimumDelay extends Error {
+    jobId;
+    delaySeconds;
+    minimumDelayMs;
+    constructor(jobId, delaySeconds, minimumDelayMs) {
+        super();
+        this.jobId = jobId;
+        this.delaySeconds = delaySeconds;
+        this.minimumDelayMs = minimumDelayMs;
+    }
+    get message() {
+        if (this.jobId === '')
+            return this.emptyJobIdMessage;
+        return `
+A delayed background job was given the \`jobId\` ${JSON.stringify(this.jobId)}, but a delay too short to debounce with (got \`delaySeconds\`: ${String(this.delaySeconds)}).
+\`jobId\` is a deduplication key: repeat calls arriving within the delay window are collapsed into one run, and each
+call restarts the window, so a burst collapses however long it runs. The delay must be at least ${this.minimumDelayMs / 1000} seconds: the key
+that does the collapsing lives one second less than the delay, and below this floor what is left is too short to
+survive an ordinary pause between two calls. The delay must also be a finite number of milliseconds within
+\`Number.MAX_SAFE_INTEGER\`, since BullMQ passes it to Redis unvalidated.
+
+Either give the delay at least ${this.minimumDelayMs / 1000} seconds, e.g. \`{ seconds: ${this.minimumDelayMs / 1000}, jobId: ${JSON.stringify(this.jobId)} }\`, or drop the
+\`jobId\` if you did not want debouncing. Nothing was enqueued.
+`;
+    }
+    get emptyJobIdMessage() {
+        return `
+A delayed background job was given an empty \`jobId\` (got \`delaySeconds\`: ${String(this.delaySeconds)}).
+\`jobId\` is a deduplication key: repeat calls arriving within the delay window are collapsed into one run. An empty
+string is not a usable key — BullMQ refuses it — and it is almost always a key that was built from a value that
+turned out to be missing, e.g. an id read from a nullable column.
+
+Either give the \`jobId\` a non-empty value, or drop it if you did not want debouncing (a delay with no \`jobId\`
+is enqueued normally, at any length). Nothing was enqueued.
+`;
+    }
+}

package/dist/esm/src/error/background/NamedWorkstreamRateLimitMissingMaxOrDuration.js

@@ -0,0 +1,31 @@
+/**
+ * Not exported from the package: a named workstream's `rateLimit` reached
+ * `connect()` without a positive integer `max` or `duration`. Open-source
+ * BullMQ forwards the worker `limiter` it becomes unvalidated: a missing or
+ * non-numeric field fails every job fetch on that workstream with a Lua error
+ * that never names `rateLimit`, a fractional `duration` floors to 0ms and rate
+ * limits nothing, and one past Redis's integer range fails every fetch.
+ */
+export default class NamedWorkstreamRateLimitMissingMaxOrDuration extends Error {
+    workstreamName;
+    transitional;
+    field;
+    received;
+    constructor(workstreamName, transitional, field, received) {
+        super();
+        this.workstreamName = workstreamName;
+        this.transitional = transitional;
+        this.field = field;
+        this.received = received;
+    }
+    get message() {
+        const entry = this.transitional ? 'transitionalWorkstreams.namedWorkstreams' : 'namedWorkstreams';
+        const received = typeof this.received === 'string' ? JSON.stringify(this.received) : String(this.received);
+        return `
+\`rateLimit\` on the \`${this.workstreamName}\` entry in \`${entry}\` is missing a usable \`${this.field}\` (got ${received}).
+Both \`max\` and \`duration\` must be positive integers, e.g. \`rateLimit: { max: 1, duration: 1000 }\`
+(at most \`max\` jobs start in any \`duration\` milliseconds). Open-source BullMQ does not validate the worker
+\`limiter\` this becomes and would fail every job fetch on that workstream or rate limit nothing, so nothing was connected.
+`;
+    }
+}

package/dist/esm/src/error/background/RateLimitedPsychicJob.js

@@ -0,0 +1,82 @@
+/**
+ * Throw from inside a backgrounded (or scheduled) method to signal that the
+ * outside service it talks to rate-limited the request (an HTTP 429, say) and
+ * asked it to stop sending for a while. `pauseQueueForSeconds` is how long that
+ * while is, in whole seconds. Importable from `@rvoh/psychic-workers/errors`.
+ *
+ * ```ts
+ * // conf/workers.ts — one named workstream per rate-limited service
+ * namedWorkstreams: [{ name: 'slack', rateLimit: { max: 1, duration: 1000 } }]
+ *
+ * // app/services/SlackNotifier.ts
+ * import { RateLimitedPsychicJob } from '@rvoh/psychic-workers/errors'
+ *
+ * export default class SlackNotifier extends ApplicationBackgroundedService {
+ *   public static override get backgroundJobConfig() {
+ *     return { workstream: 'slack' }
+ *   }
+ *
+ *   public static async post(channel: string, text: string) {
+ *     const response = await fetch('https://slack.com/api/chat.postMessage', { ... })
+ *
+ *     if (response.status === 429) {
+ *       // Slack's Retry-After header is in seconds, and so is this field
+ *       const seconds = Number(response.headers.get('retry-after') ?? 1)
+ *       throw new RateLimitedPsychicJob({ pauseQueueForSeconds: seconds })
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The worker running the job must carry a BullMQ `limiter` — a named
+ * workstream with `rateLimit`, a native `namedQueueWorkers` entry with
+ * `limiter`, `nativeBullMQ.defaultWorkerOptions.limiter`, or a global
+ * `defaultBullMQWorkerOptions.limiter`. Given one, psychic-workers translates
+ * the signal into BullMQ's own rate-limit mechanism: the queue is paused for
+ * that many seconds and the job goes back onto the queue with `attemptsMade`
+ * unchanged and no backoff, so the burst is not multiplied by the retry
+ * schedule. Note that this package writes a BullMQ priority on every job it
+ * enqueues, so a re-queued job reports `prioritized` rather than `waiting` —
+ * assertions on `getWaitingCount()` do not hold.
+ *
+ * The pause replaces the queue's current limiter window and counter — the
+ * configured `rateLimit` window and any earlier pause alike — so once
+ * `pauseQueueForSeconds` elapses up to `max` jobs may start at once, and a
+ * `pauseQueueForSeconds` shorter than the window's remaining time shortens the
+ * configured limit. Concurrent throws overwrite each other: last writer wins,
+ * not longest.
+ *
+ * `attemptsMade` never grows, but each re-fetch counts in BullMQ's
+ * `attemptsStarted`, and the worker option `maxStartedAttempts`
+ * (`defaultBullMQWorkerOptions: { maxStartedAttempts: 10 }`, say) is the only
+ * bound on that cycle: without it it is unbounded. Set it on any workstream
+ * whose jobs throw this signal.
+ *
+ * Thrown from a job whose worker carries no `limiter`, the signal is a
+ * misconfiguration: the job fails with an ordinary error whose message names
+ * the fix. The same check runs under test invocation and `WorkerTestUtils`, so
+ * a misplaced job goes red in specs.
+ *
+ * `pauseQueueForSeconds` must be a positive, finite number of safe magnitude;
+ * the constructor throws a `RangeError` otherwise, at the throw site, so a
+ * nonsense value fails there rather than at the pause. A fractional number of
+ * seconds is legal and is rounded **up** — the field is a lower bound on the
+ * pause, so overshooting it by under a second cannot break the promise, while
+ * rounding down could.
+ */
+export default class RateLimitedPsychicJob extends Error {
+    pauseQueueForSeconds;
+    constructor({ pauseQueueForSeconds }) {
+        super();
+        // `Number.isFinite` does not coerce, so a non-numeric value fails it too
+        if (!(Number.isFinite(pauseQueueForSeconds) &&
+            pauseQueueForSeconds > 0 &&
+            pauseQueueForSeconds <= Number.MAX_SAFE_INTEGER)) {
+            throw new RangeError(`RateLimitedPsychicJob requires pauseQueueForSeconds to be a positive, finite number of safe magnitude (the number of seconds to pause the queue for); received ${String(pauseQueueForSeconds)}`);
+        }
+        this.pauseQueueForSeconds = pauseQueueForSeconds;
+    }
+    get message() {
+        return `job was rate limited; pause the queue for ${this.pauseQueueForSeconds} seconds`;
+    }
+}

package/dist/esm/src/error/background/RateLimitedPsychicJobThrownFromWorkerWithoutLimiter.js

@@ -0,0 +1,51 @@
+/**
+ * Not exported from the package: a `RateLimitedPsychicJob` was thrown from a
+ * job whose worker carries no BullMQ `limiter`, so the queue cannot be paused.
+ * The job runner fails the job with this in the signal's place, so the failure
+ * reaches the application's failed-job monitoring.
+ */
+export default class RateLimitedPsychicJobThrownFromWorkerWithoutLimiter extends Error {
+    signal;
+    queue;
+    constructor(signal, queue) {
+        super(undefined, { cause: signal });
+        this.signal = signal;
+        this.queue = queue;
+    }
+    get message() {
+        return `
+RateLimitedPsychicJob (pause the queue for ${this.signal.pauseQueueForSeconds} seconds) was thrown from a job on ${this.where},
+but the workers for that queue carry no BullMQ \`limiter\`, so the queue cannot be paused.
+The job has been failed instead.
+
+To fix this, ${this.fix}
+`;
+    }
+    get where() {
+        if (this.queue.isDefaultQueue)
+            return this.queue.mode === 'simple' ? 'the default workstream' : 'the default queue';
+        const kind = this.queue.mode === 'simple' ? 'workstream' : 'queue';
+        return `the \`${this.queue.configuredName}\` ${this.queue.transitional ? 'transitional ' : ''}${kind}`;
+    }
+    get fix() {
+        const name = this.queue.configuredName;
+        if (this.queue.mode === 'simple') {
+            if (this.queue.isDefaultQueue)
+                return `move the job to a named workstream that sets \`rateLimit: { max, duration }\` (a rate limit
+targets one external limit, so the default workstream never carries one, and a service that meters
+its endpoints separately wants a workstream per limit). For example, with
+\`namedWorkstreams: [{ name: 'slack', rateLimit: { max: 1, duration: 1000 } }]\` in your workers config,
+give the backgrounded class \`backgroundJobConfig = { workstream: 'slack' }\`.`;
+            const entry = this.queue.transitional
+                ? `the \`${name}\` entry in \`transitionalWorkstreams.namedWorkstreams\``
+                : `the \`${name}\` entry in \`namedWorkstreams\``;
+            return `set \`rateLimit: { max, duration }\` on ${entry}, or move the job to a named
+workstream that sets \`rateLimit\`.`;
+        }
+        if (this.queue.isDefaultQueue)
+            return `move the job to a named queue whose \`nativeBullMQ.namedQueueWorkers\` entry sets
+\`limiter: { max, duration }\`.`;
+        return `set \`limiter: { max, duration }\` on \`nativeBullMQ.namedQueueWorkers['${name}']\`, or move the job
+to a named queue whose \`namedQueueWorkers\` entry sets \`limiter\`.`;
+    }
+}

package/dist/esm/src/package-exports/errors.js

@@ -1,3 +1,10 @@
 export { default as NoClassForSpecifiedGlobalName } from '../error/background/NoClassForSpecifiedGlobalName.js';
+// exported for backward compatibility only. Thrown by the framework when a job's
+// config names a queue that does not exist — a configuration mistake an
+// application cannot recover from, and not intended to be caught.
 export { default as NoQueueForSpecifiedQueueName } from '../error/background/NoQueueForSpecifiedQueueName.js';
+// exported for backward compatibility only. Thrown by the framework when a job's
+// config names a workstream that does not exist — a configuration mistake an
+// application cannot recover from, and not intended to be caught.
 export { default as NoQueueForSpecifiedWorkstream } from '../error/background/NoQueueForSpecifiedWorkstream.js';
+export { default as RateLimitedPsychicJob } from '../error/background/RateLimitedPsychicJob.js';

package/dist/esm/src/test-utils/WorkerTestUtils.js

@@ -1,5 +1,19 @@
+import nameToRedisQueueName from '../background/helpers/nameToRedisQueueName.js';
 import parallelTestSafeQueueName from '../background/helpers/parallelTestSafeQueueName.js';
 import background, { Background } from '../background/index.js';
+import RateLimitedPsychicJob from '../error/background/RateLimitedPsychicJob.js';
+/**
+ * @internal
+ *
+ * resolves the queue's expected Redis name through `nameToRedisQueueName`,
+ * rather than hand-reconstructing a cluster hash tag or parallel-test suffix.
+ * `queue.opts.connection` is the same `Redis | Cluster` instance the queue was
+ * built with, which is why the cast is safe for every queue this package builds.
+ */
+export function queueNamesMatch(queue, compareQueueName) {
+    return (queue.name ===
+        nameToRedisQueueName(compareQueueName, queue.opts.connection));
+}
 const LOCK_TOKEN = 'psychic-test-worker';
 export default class WorkerTestUtils {
     /*
@@ -24,6 +38,12 @@ export default class WorkerTestUtils {
      * NOTE: this is only useful if you are running with `testInvocation=manual`.
      * make sure to set this in your workers config, or else in your test,
      * so that jobs are successfully commited to the queue and can be worked off.
+     *
+     * A job that throws `RateLimitedPsychicJob` stops the loop: on a queue whose
+     * workers carry a BullMQ `limiter` the job is moved back to the queue (no
+     * attempt counted) and the call rejects with that error; on a queue whose
+     * workers carry none, the job fails with the misconfiguration error that
+     * production would fail it with, and the call rejects with that instead.
      */
     static async work(opts = {}) {
         background.connect();
@@ -32,7 +52,7 @@ export default class WorkerTestUtils {
         do {
             workWasDone = false;
             for (const queue of queues) {
-                if (opts.queue && !this.queueNamesMatch(queue, opts.queue))
+                if (opts.queue && !queueNamesMatch(queue, opts.queue))
                     continue;
                 workWasDone ||= await this.workOne(queue);
             }
@@ -40,8 +60,9 @@ export default class WorkerTestUtils {
     }
     static async workScheduled(opts = {}) {
         background.connect();
-        const queues = opts.queue
-            ? background.queues.filter(queue => queue.name === opts.queue)
+        const compareQueueName = opts.queue;
+        const queues = compareQueueName
+            ? background.queues.filter(queue => queueNamesMatch(queue, compareQueueName))
             : background.queues;
         if (opts.queue && !queues.length)
             throw new Error(`Expected to find queue with name: ${opts.queue}, but none were found by that name. The queue names available are: ${background.queues.map(queue => queue.name).join(', ')}`);
@@ -51,19 +72,33 @@ export default class WorkerTestUtils {
                 const data = job.data;
                 if (opts.for) {
                     if (data.globalName === opts.for.globalName) {
-                        await background.doWork(job);
+                        await this.doScheduledWork(job, queue);
                     }
                 }
                 else {
-                    await background.doWork(job);
+                    await this.doScheduledWork(job, queue);
                 }
             }
         }
     }
+    /**
+     * runs a delayed job in place. A `RateLimitedPsychicJob` thrown from a job on
+     * a queue whose workers carry no BullMQ `limiter` surfaces as the same
+     * misconfiguration error production would fail the job with; on a queue whose
+     * workers carry one, it propagates untranslated so the spec can assert on it.
+     */
+    static async doScheduledWork(job, queue) {
+        try {
+            await background.doWork(job);
+        }
+        catch (err) {
+            throw background.misconfiguredRateLimitSignal(err, queue) ?? err;
+        }
+    }
     /*
      * iterates through each registered queue, and cleans out all
      * jobs, including waiting, paused, prioritized, delayed, completed,
-     * failed, and scheduled jobs. This is especially useful before a test
+     * failed, active, and scheduled jobs. This is especially useful before a test
      * where you plan to exercise background jobs manually.
      *
      * If your entire app is continuously exercising background jobs
@@ -84,9 +119,13 @@ export default class WorkerTestUtils {
             // belong to a job scheduler are intentionally left alone by BullMQ here, and
             // are cleaned up below when their scheduler is removed.
             await queue.drain(true);
-            // clear out completed and failed jobs
+            // clear out completed, failed, and abandoned active jobs. `drain` does not
+            // touch `active`, so a job fetched by hand and never moved on would outlive
+            // the process and be counted by the next run of the suite. BullMQ leaves a
+            // job whose lock is still held alone.
             await queue.clean(0, 10000, 'completed');
             await queue.clean(0, 10000, 'failed');
+            await queue.clean(0, 10000, 'active');
             // clear out scheduled jobs
             const schedulers = await queue.getJobSchedulers();
             for (const scheduler of schedulers) {
@@ -105,19 +144,45 @@ export default class WorkerTestUtils {
         const job = await worker.getNextJob(LOCK_TOKEN);
         if (!job)
             return false;
-        await this.processJob(job);
+        await this.processJob(job, queue);
         return true;
     }
-    static queueNamesMatch(queue, compareQueueName) {
-        return (queue.name === parallelTestSafeQueueName(compareQueueName) ||
-            queue.name === `{${parallelTestSafeQueueName(compareQueueName)}`);
-    }
-    static async processJob(job) {
+    /**
+     * runs one fetched job to completion or failure, mirroring what a real worker
+     * would do with a `RateLimitedPsychicJob`, then surfacing it so the spec goes
+     * red rather than looping:
+     *
+     * - on a queue whose workers carry no BullMQ `limiter`, the job is failed with
+     *   the misconfiguration error production would fail it with (so, with the
+     *   queue's `attempts` > 1, it lands in `delayed` for its retry, out of
+     *   `active`, where `clean()` can reach it), and that error is rethrown
+     * - on a queue whose workers carry one, the job is moved back to the queue
+     *   with no attempt counted (BullMQ's own rate-limit path), and the
+     *   `RateLimitedPsychicJob` is rethrown
+     *
+     * Every other error only fails the job, as before.
+     */
+    static async processJob(job, queue) {
         try {
             const res = await background.doWork(job);
             await job.moveToCompleted(res, LOCK_TOKEN, false);
         }
         catch (err) {
+            const misconfigured = background.misconfiguredRateLimitSignal(err, queue);
+            if (misconfigured) {
+                await job.moveToFailed(misconfigured, LOCK_TOKEN, false);
+                throw misconfigured;
+            }
+            if (err instanceof RateLimitedPsychicJob) {
+                // exactly what a real worker does with this signal: BullMQ's own rate-limit
+                // path is `job.moveToWait(token)` (`Worker#moveLimitedBackToWait`). It takes
+                // the job off `active` and releases the lock `workOne` took, without counting
+                // an attempt. Its Lua reads the job's own priority and puts a prioritized job
+                // back in `prioritized` rather than `wait`, so the destination matches
+                // production too — this package writes a priority on every job it enqueues.
+                await job.moveToWait(LOCK_TOKEN);
+                throw err;
+            }
             await job.moveToFailed(err, LOCK_TOKEN, false);
         }
     }

package/dist/types/src/background/BaseBackgroundedModel.d.ts

@@ -12,7 +12,7 @@ export default class BaseBackgroundedModel extends Dream {
      * @returns {object} config - the background job config
      * @returns {string} config.priority - 'default' | 'urgent' | 'not_urgent' | 'last'
      * @returns {string} config.workstream - a workstream name. This would be the name of a workstream, as defined in conf/workers.ts
-     * @returns {string} config.queueId - the id of the BullMQ queue you wish to connect to. This can only be provided if workstream is not provided.
+     * @returns {string} config.queue - the name of the BullMQ queue you wish to connect to. This can only be provided if workstream is not provided.
      * @returns {string} config.groupId - the groupId of the BullMQ queue you wish to connect to. This can only be provided if workstream is not provided.
      */
     static get backgroundJobConfig(): BackgroundJobConfig<BaseBackgroundedModel>;
@@ -45,16 +45,22 @@ export default class BaseBackgroundedModel extends Dream {
     static background<T, MethodName extends PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, methodName: MethodName, ...args: MethodArgs): Promise<void>;
     /**
      * runs the specified method in a background queue, driven by BullMQ,
-     * sending in the provided args, including a delay in seconds, which
-     * can be used to hold off the job for a certain amount of time after
-     * it is entered into the queue.
+     * sending in the provided args, along with a delay object — one or more of
+     * `{ seconds, minutes, hours, days }` — which holds the job off for that much
+     * time after it is entered into the queue.
+     *
+     * The delay object also accepts an optional `jobId`, which turns the delay
+     * into a **debounce**: repeated calls carrying the same `jobId` collapse into
+     * a single execution, which runs once the delay has elapsed without another
+     * call arriving. `jobId` is a deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
      *
      * ```ts
-     * await User.backgroundWithDelay('myMethod', 'abc', 123)
+     * await User.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * though calling backgroundWithDelay must be awaited, the resolution of the promise
+     * is an indication that a run is pending, not that it has completed.
      *
      * NOTE: in test environments, psychic will immediately invoke the underlying
      * method, preventing you from needing to explicitly wait for queues to flush
@@ -62,7 +68,7 @@ export default class BaseBackgroundedModel extends Dream {
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
-     * @param delaySeconds - the amount of time (in seconds) you want to hold off before allowing the job to run
+     * @param delay - how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
      */
@@ -73,19 +79,25 @@ export default class BaseBackgroundedModel extends Dream {
      * be used to delay the job and/or override the priority provided by
      * the `backgroundJobConfig` getter on this model.
      *
+     * Adding a `jobId` to the delay turns it into a **debounce**: repeated calls
+     * carrying the same `jobId` collapse into a single execution, which runs once
+     * the delay has elapsed without another call arriving. `jobId` is a
+     * deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
+     *
      * ```ts
      * await User.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
      * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * is an indication that a run is pending, not that it has completed.
      *
      * NOTE: in test environments, psychic will immediately invoke the underlying
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
      * @param opts - options for backgrounding this job
-     * @param opts.delay - (optional) the amount of time you want to hold off before allowing the job to run, and an optional `jobId` which debounces repeated calls within the delay window
+     * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
      * @param opts.priority - (optional) a priority which, when provided, overrides the priority provided by `backgroundJobConfig`
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -114,23 +126,29 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
-     * @param methodName - the name of the static method you wish to run in the background
+     * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
      */
     background<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, methodName: MethodName, ...args: MethodArgs): Promise<void>;
     /**
      * runs the specified method in a background queue, driven by BullMQ,
-     * sending in the provided args, including a delay in seconds, which
-     * can be used to hold off the job for a certain amount of time after
-     * it is entered into the queue.
+     * sending in the provided args, along with a delay object — one or more of
+     * `{ seconds, minutes, hours, days }` — which holds the job off for that much
+     * time after it is entered into the queue.
+     *
+     * The delay object also accepts an optional `jobId`, which turns the delay
+     * into a **debounce**: repeated calls carrying the same `jobId` collapse into
+     * a single execution, which runs once the delay has elapsed without another
+     * call arriving. `jobId` is a deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
      *
      * ```ts
      * const user = await User.lastOrFail()
-     * await user.backgroundWithDelay('myMethod', 'abc', 123)
+     * await user.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * though calling backgroundWithDelay must be awaited, the resolution of the promise
+     * is an indication that a run is pending, not that it has completed.
      *
      * NOTE: in test environments, psychic will immediately invoke the underlying
      * method, preventing you from needing to explicitly wait for queues to flush
@@ -138,8 +156,8 @@ export default class BaseBackgroundedModel extends Dream {
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
-     * @param delaySeconds - the amount of time (in seconds) you want to hold off before allowing the job to run
-     * @param methodName - the name of the static method you wish to run in the background
+     * @param delay - how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
+     * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
      */
     backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
@@ -149,20 +167,26 @@ export default class BaseBackgroundedModel extends Dream {
      * be used to delay the job and/or override the priority provided by
      * the `backgroundJobConfig` getter on this model.
      *
+     * Adding a `jobId` to the delay turns it into a **debounce**: repeated calls
+     * carrying the same `jobId` collapse into a single execution, which runs once
+     * the delay has elapsed without another call arriving. `jobId` is a
+     * deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
+     *
      * ```ts
      * const user = await User.lastOrFail()
      * await user.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
      * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * is an indication that a run is pending, not that it has completed.
      *
      * NOTE: in test environments, psychic will immediately invoke the underlying
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
      * @param opts - options for backgrounding this job
-     * @param opts.delay - (optional) the amount of time you want to hold off before allowing the job to run, and an optional `jobId` which debounces repeated calls within the delay window
+     * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
      * @param opts.priority - (optional) a priority which, when provided, overrides the priority provided by `backgroundJobConfig`
      * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method