@rvoh/psychic-workers 2.6.0 → 2.7.0

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

@@ -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,16 +53,22 @@ 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
@@ -70,7 +76,7 @@ export default class BaseBackgroundedService {
      *
      * @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
      */
@@ -81,6 +87,13 @@ export default class BaseBackgroundedService {
      * 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' },
@@ -90,15 +103,14 @@ export default class BaseBackgroundedService {
      * )
      * ```
      * 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

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>;

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;
     /**

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';

package/dist/types/src/psychic-app-workers/index.d.ts

@@ -64,7 +64,25 @@ export interface BullMQNativeWorkerOptions extends WorkerOptions {
         concurrency?: number;
         priority?: number;
     };
+    /**
+     * How many jobs each worker built from this configuration runs at once
+     * (https://docs.bullmq.io/guide/workers/concurrency).
+     *
+     * Native BullMQ mode writes none, so BullMQ's default of **1** applies unless
+     * this or `defaultBullMQWorkerOptions.concurrency` sets it. See
+     * `PsychicBackgroundWorkstreamOptions.concurrency`.
+     */
     concurrency?: number;
+    /**
+     * the number of workers to create with this configuration, in this process.
+     *
+     * Read **only** for `nativeBullMQ.namedQueueWorkers`, where it defaults to 1
+     * (a named queue with no entry in `namedQueueWorkers` gets no workers at
+     * all). It is *not* read for `nativeBullMQ.defaultWorkerOptions`: the default
+     * queue's worker count comes from `nativeBullMQ.defaultWorkerCount`. See
+     * `PsychicBackgroundWorkstreamOptions.workerCount` for the
+     * `workerCount × concurrency` product.
+     */
     workerCount?: number;
 }
 export interface PsychicBackgroundNativeBullMQOptions extends PsychicBackgroundSharedOptions {
@@ -82,26 +100,24 @@ export interface PsychicBackgroundNativeBullMQOptions extends PsychicBackgroundS
          */
         namedQueueOptions?: Record<string, QueueOptionsWithConnectionInstance>;
         /**
-         * Native BullMQ options to provide to configure the default workers
-         * for psychic. By default, Psychic leverages a single-queue system, with
-         * many workers running off the queue. Each worker receives the
-         * same worker configuration, so this configuration is really
-         * only used to supply the number of default workers that you want.
+         * Native BullMQ options for the default workers, spread over
+         * `defaultBullMQWorkerOptions` — where `concurrency`, `limiter` and every
+         * other BullMQ worker option for them comes from. A `workerCount` set here
+         * is never read; the count comes from `defaultWorkerCount` below.
          */
         defaultWorkerOptions?: BullMQNativeWorkerOptions;
         /**
-         * The number of default workers to run against the default Psychic
-         * background queues.
-         *
-         * By default, Psychic leverages a single-queue system, with
-         * many workers running off a single queue. This number determines
-         * the number of those default workers to provide.
+         * The number of default workers to run in this process, and the only source
+         * of that count in native mode. Defaults to 1, and takes effect only in a
+         * process that activates workers. See
+         * `PsychicBackgroundWorkstreamOptions.workerCount`.
          */
         defaultWorkerCount?: number;
         /**
-         * namedQueueWorkers are necessary to work off namedQueues
-         * With BullMQ Pro, namedQueueWorkers can be rate limited (useful
-         * for interacting with external APIs)
+         * namedQueueWorkers are necessary to work off namedQueues.
+         * A named queue's workers can be rate limited with BullMQ's `limiter`
+         * option (https://docs.bullmq.io/guide/rate-limiting; useful for
+         * interacting with external APIs) on open-source BullMQ and BullMQ Pro alike
          */
         namedQueueWorkers?: Record<string, BullMQNativeWorkerOptions>;
     };
@@ -138,24 +154,34 @@ export interface PsychicBackgroundSimpleOptions extends PsychicBackgroundSharedO
      */
     defaultWorkerConnection: RedisOrRedisClusterConnection | undefined;
     /**
-     * Every Psychic application that leverages simple background jobs will have a default
-     * workstream. Set workerCount to set the number of workers that will work through the
-     * default queue
+     * The default workstream, whose queue carries every job not backgrounded to a
+     * named workstream. Both fields mean exactly what they mean on a named
+     * workstream — see `PsychicBackgroundWorkstreamOptions.workerCount` and
+     * `.concurrency`.
      */
     defaultWorkstream?: {
+        /** The number of workers working through the default queue, in this process. Defaults to 1. */
         workerCount?: number;
+        /**
+         * How many jobs each default worker runs at once
+         * (https://docs.bullmq.io/guide/workers/concurrency). Left unset, psychic
+         * falls back to 10, as everywhere in simple mode. See
+         * `PsychicBackgroundWorkstreamOptions.concurrency`.
+         */
         concurrency?: number;
     };
     /**
      * When running background jobs on BullMQ, each named workstream corresponds
-     * to a specific queue and workers created for a named workstream are given
-     * a groupId corresponding to the workstream name
-     *
-     * named workstreams are useful for dispersing queues among nodes in a Redis cluster
-     * and for running queues on different Redis instances
+     * to a specific queue, and jobs backgrounded to a named workstream are added
+     * with a group id equal to the workstream name (a BullMQ Pro concept, ignored
+     * by open-source BullMQ)
      *
-     * With BullMQ Pro, named workstreams can be rate limited (useful
-     * for interacting with external APIs)
+     * named workstreams are useful for dispersing queues among nodes in a Redis cluster,
+     * for running queues on different Redis instances, and for rate limiting, on
+     * open-source BullMQ and BullMQ Pro alike (see
+     * `PsychicBackgroundWorkstreamOptions.rateLimit`). A rate limit targets one external
+     * limit, so give each rate-limited service its own named workstream — and where a
+     * service meters its endpoints separately, one workstream per limit
      */
     namedWorkstreams?: PsychicBackgroundWorkstreamOptions[];
     /**
@@ -171,43 +197,66 @@ export interface PsychicBackgroundWorkstreamOptions {
      */
     name: string;
     /**
-     * The number of workers you want to run on this configuration
+     * The number of workers you want to run on this configuration, in **this
+     * process**. Defaults to 1. These are BullMQ `Worker` objects sharing the
+     * activating process's event loop, not forked processes, so raising this buys
+     * concurrent waiting rather than concurrent CPU.
+     *
+     * `workerCount × concurrency` is the ceiling on this workstream's jobs in
+     * flight in one process, and that product is what to size against a
+     * downstream limit such as a connection pool or an external API's quota.
      */
     workerCount?: number;
-    concurrency?: number;
-    /**
-     * See https://docs.bullmq.io/bullmq-pro/groups/rate-limiting for documentation
-     * on rate limiting in BullMQ Pro (requires paid BullMQ Pro license)
-     */
-    rateLimit?: {
-        max?: number;
-        duration?: number;
-    };
-    /**
-     * Optional redis connection. If not provided, the default background redis connection will be used.
-     * See https://docs.bullmq.io/guide/going-to-production for the different settings to use between
-     * queue and worker connections.
-     */
-    queueConnection?: RedisOrRedisClusterConnection;
-    workerConnection?: RedisOrRedisClusterConnection;
-}
-export interface PsychicBackgroundWorkstreamOptions {
-    /**
-     * This will be the name of the queue (and the group if using BullMQ Pro)
-     */
-    name: string;
     /**
-     * The number of workers you want to run on this configuration
+     * How many jobs each of this workstream's workers runs at once
+     * (https://docs.bullmq.io/guide/workers/concurrency).
+     *
+     * **In simple mode this defaults to 10.** Psychic always writes a
+     * `concurrency` onto a simple-mode worker, falling back to 10 when the
+     * workstream does not set one — which also means it overrides any
+     * `concurrency` placed in `defaultBullMQWorkerOptions`. Native BullMQ mode
+     * writes none, so BullMQ's own default of 1 applies there. Moving a queue
+     * between the two modes therefore changes how many jobs it runs at once by a
+     * factor of ten, with nothing in either configuration saying so.
+     *
+     * See `workerCount` above for the `workerCount × concurrency` product.
      */
-    workerCount?: number;
     concurrency?: number;
     /**
-     * See https://docs.bullmq.io/bullmq-pro/groups/rate-limiting for documentation
-     * on rate limiting in BullMQ Pro (requires paid BullMQ Pro license)
+     * Rate-limit this workstream: at most `max` jobs start in any `duration`
+     * milliseconds. Works on open-source BullMQ and on BullMQ Pro.
+     *
+     * The limit is per queue, not per worker: every one of this workstream's
+     * workers, in every process running it, shares one counter kept in Redis, so
+     * `{ max: 1, duration: 1000 }` means one job per second for the workstream as
+     * a whole. `concurrency` caps how many jobs each worker runs at once;
+     * `rateLimit` caps how many may start per window across the whole workstream.
+     * For this workstream's workers it takes precedence over a global
+     * `defaultBullMQWorkerOptions.limiter`.
+     *
+     * A job on this workstream that is told to slow down (an HTTP 429, say) can
+     * throw `RateLimitedPsychicJob` from `@rvoh/psychic-workers/errors` to pause
+     * the whole workstream without burning a retry attempt; see that class for
+     * the pause semantics and for the `maxStartedAttempts` bound.
+     *
+     * A debounced job on this workstream must carry a delay long enough that it
+     * cannot enqueue faster than this limit starts jobs, or it is refused at
+     * enqueue: see `DelayedJobOpts.jobId`.
+     *
+     * `max` and `duration` are both required positive integers (`duration` in
+     * milliseconds): open-source BullMQ floors a fractional `duration` to 0ms
+     * (rate limiting nothing) and fails every job fetch on one past Redis's
+     * integer range. A `rateLimit` that reaches `connect()` without both fails
+     * `connect()` naming the workstream and the field, before any queue or worker
+     * is built.
+     *
+     * Implemented as BullMQ's worker `limiter` option, and on BullMQ Pro also as
+     * the workstream group's rate limit (unverified against an installed Pro
+     * build).
      */
     rateLimit?: {
-        max?: number;
-        duration?: number;
+        max: number;
+        duration: number;
     };
     /**
      * Optional redis connection. If not provided, the default background redis connection will be used.

package/dist/types/src/test-utils/WorkerTestUtils.d.ts

@@ -1,10 +1,41 @@
+import { Queue } from 'bullmq';
+/**
+ * @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 declare function queueNamesMatch(queue: Queue, compareQueueName: string): boolean;
 export default class WorkerTestUtils {
     static parallelTestSafeQueueName(queueName: string): string;
     static work(opts?: TestWorkerWorkOffOpts): Promise<void>;
     static workScheduled(opts?: TestWorkerScheduledWorkOffOpts): Promise<void>;
+    /**
+     * 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.
+     */
+    private static doScheduledWork;
     static clean(): Promise<void>;
     private static workOne;
-    private static queueNamesMatch;
+    /**
+     * 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.
+     */
     private static processJob;
 }
 interface TestWorkerWorkOffOpts {