@rvoh/psychic-workers 2.4.1 → 2.7.0

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

@@ -1,5 +1,5 @@
 import { Job } from 'bullmq';
-import { BackgroundJobConfig, DelayedJobOpts } from '../types/background.js';
+import { BackgroundJobConfig, BackgroundWithOpts, DelayedJobOpts } from '../types/background.js';
 import { FunctionPropertyNames } from '../types/utils.js';
 export default class BaseBackgroundedService {
     /**
@@ -11,7 +11,7 @@ export default class BaseBackgroundedService {
      * @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<BaseBackgroundedService>;
@@ -53,26 +53,69 @@ export default class BaseBackgroundedService {
     static background<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, 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 MyBackgroundableClass.backgroundWithDelay('myMethod', 'abc', 123)
+     * await MyBackgroundableClass.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
      * before making assertions.
      *
-     * @param delaySeconds - the amount of time (in seconds) you want to hold off before allowing the job to run
+     * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
+     *
+     * @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
      */
     static backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * runs the specified method in a background queue, driven by BullMQ,
+     * sending in the provided args, along with an options object which can
+     * be used to delay the job and/or override the priority provided by
+     * the `backgroundJobConfig` getter on this service.
+     *
+     * 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 MyBackgroundableClass.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 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) 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
+     */
+    static backgroundWith<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, opts: BackgroundWithOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract
@@ -81,6 +124,14 @@ export default class BaseBackgroundedService {
      */
     get psychicWorkerTypes(): any;
 }
+/**
+ * @internal
+ *
+ * returns a copy of the provided job config, with the priority
+ * replaced by the priority found in the `backgroundWith` opts,
+ * if one was provided.
+ */
+export declare function mergeBackgroundWithOptsIntoJobConfig<T extends BackgroundJobConfig<any>>(jobConfig: T, opts: BackgroundWithOpts): T;
 export type PsychicBackgroundedServiceStaticMethods<T extends typeof BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedService>>;
 export type PsychicBackgroundedServiceInstanceMethods<T extends BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<BaseBackgroundedService>>;
 type OmitJobFromEndOfArguments<Original extends unknown[]> = Original extends [Job] ? Original extends [string] ? Original : [] : Original extends [...infer Rest, Job] ? Original extends [...unknown[], string] ? Original : Rest : Original;

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

@@ -10,7 +10,7 @@ export default class BaseScheduledService {
      * @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<BaseScheduledService>;
@@ -51,6 +51,59 @@ export default class BaseScheduledService {
      * @param args - a variadic list of arguments to be sent to your method
      */
     static schedule<T, MethodName extends FunctionPropertyNames<Required<T>>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends MethodFunc extends (...args: any) => any ? Parameters<MethodFunc> : never>(this: T, pattern: string, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * Returns the id that `schedule` registers a job under, which can be passed
+     * to {@link BaseScheduledService.unschedule} to remove that job.
+     *
+     * The id is derived from the service's global name and the method name. It
+     * performs no queue construction and no redis I/O, so it is safe to call
+     * anywhere, including from a console in development.
+     *
+     * The intended workflow for deleting a scheduled service is to read the id
+     * off the class before removing it:
+     *
+     * ```ts
+     * MyScheduledService.unscheduleId('myHourlyMethod')
+     * // => 'services/MyScheduledService:myHourlyMethod'
+     * ```
+     *
+     * then check that string into a seed or migration and call `unschedule` with
+     * it, which allows the class itself to be deleted in the same deploy.
+     *
+     * ```ts
+     * await ApplicationScheduledService.unschedule('services/MyScheduledService:myHourlyMethod')
+     * ```
+     *
+     * @param methodName - the name of the static method that was scheduled
+     * @returns the id `schedule` registered this method under
+     */
+    static unscheduleId<T, MethodName extends FunctionPropertyNames<Required<T>>>(this: T, methodName: MethodName): string;
+    /**
+     * Removes a scheduled job, preventing it from being run again.
+     *
+     * ```ts
+     * await MyScheduledService.unschedule(MyScheduledService.unscheduleId('myHourlyMethod'))
+     * ```
+     *
+     * Since the id is just a string, it can also be checked into a seed or
+     * migration, which allows the scheduled service class to be deleted in the
+     * same deploy that stops its job:
+     *
+     * ```ts
+     * await ApplicationScheduledService.unschedule('services/MyScheduledService:myHourlyMethod')
+     * ```
+     *
+     * Every queue in your application is checked, so this finds the job whether
+     * or not the service's workstream has changed since it was scheduled, and
+     * whether it landed in a current or a transitional queue.
+     *
+     * NOTE: unscheduling stops future runs. It does not cancel a run that has
+     * already been placed on a queue, so a final invocation may still happen.
+     *
+     * @param id - the id the job was scheduled under, from {@link BaseScheduledService.unscheduleId}
+     * @returns true if a scheduled job was removed, false if none was found
+     */
+    static unschedule(id: string): Promise<boolean>;
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract

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

@@ -7,7 +7,13 @@ import { BackgroundJobConfig, BackgroundJobData, BackgroundQueuePriority, JobTyp
  */
 export declare class Background {
     /**
-     * returns the default queue name for your app
+     * returns the **logical** name of your app's default queue, built from your
+     * app name (`MyAppBackgroundJobQueue`).
+     *
+     * This is never the name the queue has in Redis: `connect` rewrites it per
+     * connection (brace-stripped, cluster hash-tagged, test-suffixed), and every
+     * key BullMQ writes is namespaced by the rewritten name. Do not compose Redis
+     * keys from this — read `queue.name` off `background.queues` instead.
      */
     static get defaultQueueName(): string;
     /**
@@ -75,17 +81,61 @@ export declare class Background {
      */
     private redisConnections;
     /**
-     * Establishes connection to BullMQ via redis
+     * @internal
+     *
+     * For every queue built by `connect`: how it was configured, whether its
+     * workers carry a BullMQ `limiter`, and what the workers are built from.
+     * Written whether or not workers are activated here, so activation can happen
+     * later without re-walking the configuration. Keyed by Queue identity rather
+     * than name: a transitional workstream's queue has the same formatted name as
+     * its current twin but its own configuration.
+     */
+    private queueWorkerRecords;
+    /**
+     * @internal
+     *
+     * set immediately before {@link buildRecordedWorkers} runs its build loop, so
+     * that a second activation builds nothing
+     */
+    private workersActivated;
+    /**
+     * Establishes connection to BullMQ via redis: builds the `Queue` objects for
+     * the default and named workstreams and, only when `activateWorkers` is true,
+     * the `Worker` objects that run jobs off them. Synchronous: it returns
+     * nothing, so it is called without `await` even from async code.
+     *
+     * Connecting and activating are separate. `activateWorkers` defaults to
+     * `false`, so connecting gets the producer side only. Queues are built once
+     * per instance, but a later activation still builds workers, so a process that
+     * connects first and calls `work()` afterwards gets its workers.
+     *
+     * You rarely call this yourself — Psychic connects on the
+     * `server:init:after-routes` hook, on every enqueue path, in CLI codegen and
+     * in the `WorkerTestUtils` helpers.
      */
     connect({ activateWorkers, }?: {
         activateWorkers?: boolean;
     }): void;
     /**
-     * Returns all the queues in your application
+     * Returns all the queues in your application: the default queue, every named
+     * queue, and their transitional twins when transitional workstreams are
+     * configured.
+     *
+     * `connect` is what populates this, and before it has run the getter returns
+     * an **empty array**, with no error and no warning — indistinguishable from
+     * an application with nothing queued. Each `Queue` here carries the rewritten
+     * Redis name rather than the name you configured.
      */
     get queues(): Queue[];
     /**
-     * Returns all the workers in your application
+     * Returns all the workers in your application: every BullMQ `Worker` this
+     * process has built.
+     *
+     * Only a process that activated workers has any — `work()`, or a direct
+     * `connect({ activateWorkers: true })`. Anywhere else the getter returns an
+     * **empty array**, with no error and no warning, so a worker entrypoint that
+     * attaches failure listeners by looping over it before `work()` runs attaches
+     * nothing and logs nothing to say so.
      */
     get workers(): Worker<any, any, string>[];
     /**
@@ -141,7 +191,61 @@ export declare class Background {
      */
     private nativeBullMQConnect;
     /**
-     * starts background workers
+     * @internal
+     *
+     * the sole writer of {@link queueWorkerRecords}. `workerOptions` is the very
+     * object the workers are built from (minus the connection), so the record and
+     * the workers cannot disagree.
+     */
+    private recordQueueWorkers;
+    /**
+     * @internal
+     *
+     * builds every worker `connect` recorded a queue for, in the order the queues
+     * were built, so the default missing-connection throw still pre-empts the
+     * named one. The activation flag is set before the loop, not after it, because
+     * `_workers` is append-only and a build that throws partway must not be
+     * retryable into a second copy of the workers it already constructed.
+     */
+    private buildRecordedWorkers;
+    /**
+     * @internal
+     *
+     * throws {@link NamedWorkstreamRateLimitMissingMaxOrDuration} for the first
+     * workstream whose `rateLimit` lacks a positive integer `max` or `duration`.
+     * The type requires both but admits any number, and open-source BullMQ does
+     * not validate a `limiter`: a fractional `duration` floors to 0ms and rate
+     * limits nothing, and one past Redis's integer range fails every job fetch.
+     */
+    private assertNamedWorkstreamRateLimits;
+    /**
+     * @internal
+     *
+     * when `err` is a {@link RateLimitedPsychicJob} thrown on a queue whose workers
+     * carry no BullMQ `limiter`, returns the misconfiguration error to fail the job
+     * with instead; otherwise undefined. Declared as `Error` so the concrete,
+     * unexported class stays out of the emitted declarations. Four callers, one
+     * across a module boundary in `WorkerTestUtils`.
+     */
+    misconfiguredRateLimitSignal(err: unknown, queue: Queue): Error | undefined;
+    /**
+     * @internal
+     *
+     * the processor every worker on `queue` runs: {@link doWork}, with a
+     * {@link RateLimitedPsychicJob} translated into BullMQ's own rate-limit
+     * signal — the queue's limiter key is set, pausing every worker on the queue,
+     * then `RateLimitError` moves the job back without counting an attempt or
+     * emitting `failed`. Thrown where the workers carry no `limiter`, it is
+     * instead a misconfiguration: see {@link misconfiguredRateLimitSignal}.
+     */
+    private processorFor;
+    /**
+     * starts background workers: connects if this process has not connected yet,
+     * then builds the `Worker` objects for every queue `connect` recorded, and
+     * installs the process-level fatal-error and signal handlers that shut them
+     * down. An earlier producer-only `connect()` no longer leaves `work()` with
+     * nothing to do. A process with no `defaultWorkerConnection` configured throws
+     * here rather than returning quietly.
      */
     work(): void;
     /**
@@ -182,6 +286,34 @@ export declare class Background {
         jobConfig?: BackgroundJobConfig<any>;
         scheduleOpts?: JobSchedulerTemplateOptions;
     }): Promise<void>;
+    /**
+     * @internal
+     *
+     * Returns the id a scheduled job is registered with BullMQ under.
+     *
+     * `jobId` is used to determine uniqueness along with name and repeat pattern.
+     * Since the name is really a job type and never changes, the `jobId` is the only
+     * way to allow multiple jobs with the same cron repeat pattern. Uniqueness is
+     * enforced by combining the global name and the method name.
+     *
+     * See: https://docs.bullmq.io/guide/jobs/repeatable
+     *
+     * @param globalName - the globalName of the class the method belongs to
+     * @param method - the name of the scheduled method
+     */
+    jobSchedulerId(globalName: string, method: string): string;
+    /**
+     * removes a scheduled job from BullMQ, preventing it from being run again
+     *
+     * Every queue is checked, rather than the one the job's current
+     * `backgroundJobConfig` routes to, so that a job can still be unscheduled
+     * after its workstream has changed, or after the class that scheduled it has
+     * been deleted.
+     *
+     * @param jobSchedulerId - the id the job was scheduled under
+     * @returns true if a scheduled job was removed, false if none was found
+     */
+    unschedule(jobSchedulerId: string): Promise<boolean>;
     private queueInstance;
     /**
      * adds the instance method of a provided dream model to BullMQ

package/dist/types/src/error/background/DebouncedJobOutpacesRateLimit.d.ts

@@ -0,0 +1,31 @@
+import { WorkerQueueDescription } from '../../types/background.js';
+/**
+ * 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 {
+    private jobId;
+    private delayMs;
+    private keyLifetimeMs;
+    private limiter;
+    private queue;
+    constructor(jobId: string, delayMs: number, keyLifetimeMs: number, limiter: {
+        max: number;
+        duration: number;
+    }, queue: WorkerQueueDescription);
+    get message(): string;
+    private get msPerJob();
+    /**
+     * 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.
+     */
+    private get minimumDelayMs();
+    private seconds;
+    private get kind();
+    private get where();
+}

package/dist/types/src/error/background/DebouncedJobRequiresMinimumDelay.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 {
+    private jobId;
+    private delaySeconds;
+    private minimumDelayMs;
+    constructor(jobId: string, delaySeconds: number | undefined, minimumDelayMs: number);
+    get message(): string;
+    private get emptyJobIdMessage();
+}

package/dist/types/src/error/background/NamedWorkstreamRateLimitMissingMaxOrDuration.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 {
+    private workstreamName;
+    private transitional;
+    private field;
+    private received;
+    constructor(workstreamName: string, transitional: boolean, field: 'max' | 'duration', received: unknown);
+    get message(): string;
+}

package/dist/types/src/error/background/RateLimitedPsychicJob.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 {
+    readonly pauseQueueForSeconds: number;
+    constructor({ pauseQueueForSeconds }: {
+        pauseQueueForSeconds: number;
+    });
+    get message(): string;
+}

package/dist/types/src/error/background/RateLimitedPsychicJobThrownFromWorkerWithoutLimiter.d.ts

@@ -0,0 +1,16 @@
+import { WorkerQueueDescription } from '../../types/background.js';
+import RateLimitedPsychicJob from './RateLimitedPsychicJob.js';
+/**
+ * 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 {
+    private signal;
+    private queue;
+    constructor(signal: RateLimitedPsychicJob, queue: WorkerQueueDescription);
+    get message(): string;
+    private get where();
+    private get fix();
+}

package/dist/types/src/package-exports/errors.d.ts

@@ -1,3 +1,4 @@
 export { default as NoClassForSpecifiedGlobalName } from '../error/background/NoClassForSpecifiedGlobalName.js';
 export { default as NoQueueForSpecifiedQueueName } from '../error/background/NoQueueForSpecifiedQueueName.js';
 export { default as NoQueueForSpecifiedWorkstream } from '../error/background/NoQueueForSpecifiedWorkstream.js';
+export { default as RateLimitedPsychicJob } from '../error/background/RateLimitedPsychicJob.js';