@rvoh/psychic-workers 2.6.0 → 2.8.0

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 {

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

@@ -29,14 +29,73 @@ export interface BackgroundJobData {
      */
     globalName?: string;
 }
-export type DelayedJobOpts = DelayedJobDuration & {
+/**
+ * the delay to hold a job for and, when a `jobId` is provided, the debounce
+ * that delay drives.
+ *
+ * Calling a delayed background method repeatedly with the same `jobId`
+ * collapses those calls into a **single execution**. Each call slides the
+ * pending job's fire time further out, and the job runs once, after the last
+ * call, when the delay has finally elapsed without another call arriving.
+ *
+ * ```ts
+ * // ten calls in quick succession; the report is generated once,
+ * // ten seconds after the last of them
+ * await Report.backgroundWith({ delay: { seconds: 10, jobId: `report-${user.id}` } }, 'generate', user.id)
+ * ```
+ *
+ * A delay object must carry at least one of `seconds`, `minutes`, `hours` or
+ * `days`. `{}` and `{ jobId: 'my-job' }` are compile errors, since a delay with
+ * no duration delays nothing and a `jobId` with no duration debounces
+ * nothing.
+ */
+export type DelayedJobOpts = AtLeastOneDelayedJobDuration & {
     /**
-     * a unique identifier for your job. this identifier will be
-     * used to debounce, leveraging the internal throttling mechanisms
-     * provided by BullMQ
+     * a **deduplication key**, which debounces repeated calls: calls carrying the
+     * same `jobId` collapse into a single execution, which runs once the delay
+     * has elapsed without another call arriving. The window runs from the last
+     * call, not the first, so a burst is collapsed however long it lasts.
+     *
+     * Despite the name, this is not the BullMQ job id of the enqueued job, and
+     * `queue.getJob(jobId)` will not resolve the debounced job through it. BullMQ
+     * stores it as a separate Redis key; the matching read is
+     * `queue.getDeduplicationJobId(jobId)`.
+     *
+     * A delay carrying a `jobId` must be **at least three seconds**, and a
+     * shorter one is refused at enqueue.
+     *
+     * On a rate-limited workstream the delay must also clear the limiter's
+     * spacing: `delay - 1s >= duration / max`, so a workstream limited to one job
+     * a minute needs a 61-second delay. A delay that does not is refused at
+     * enqueue, naming the queue, both limiter numbers and a delay that would
+     * pass.
      */
     jobId?: string;
 };
+/**
+ * `DelayedJobDuration`, but at least one field has to be there. Every field is
+ * optional on its own, so `{}` would otherwise compile and delay nothing.
+ * TypeScript has no "at least one of these" operator, so this spells out the
+ * four ways to satisfy it and joins them with `|`:
+ *
+ * ```ts
+ * | { seconds: number;  minutes?: number; hours?:   number; days?:  number }
+ * | { minutes: number;  seconds?: number; hours?:   number; days?:  number }
+ * | { hours:   number;  seconds?: number; minutes?: number; days?:  number }
+ * | { days:    number;  seconds?: number; minutes?: number; hours?: number }
+ * ```
+ *
+ * A value has to match one of those, which means carrying that line's required
+ * field. `{ seconds: 30 }` matches the first. `{}` matches none, and neither
+ * does `{ jobId: 'my-job' }`.
+ *
+ * Not exported: it exists only to narrow `DelayedJobOpts`. `DelayedJobDuration`
+ * itself stays all-optional because it is also the parameter type of the shared
+ * `durationToSeconds` helper.
+ */
+type AtLeastOneDelayedJobDuration = {
+    [Field in keyof DelayedJobDuration]-?: Required<Pick<DelayedJobDuration, Field>> & Partial<Omit<DelayedJobDuration, Field>>;
+}[keyof DelayedJobDuration];
 export interface DelayedJobDuration {
     seconds?: number;
     minutes?: number;
@@ -49,8 +108,15 @@ export interface BackgroundWithOpts {
     /**
      * an optional delay to hold off the job for a certain amount of
      * time after it is entered into the queue. Accepts the same options
-     * as `backgroundWithDelay`, including an optional `jobId` which
-     * debounces repeated calls within the delay window.
+     * as `backgroundWithDelay`, and must carry at least one of `seconds`,
+     * `minutes`, `hours` or `days`.
+     *
+     * Adding a `jobId` 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}.
      */
     delay?: DelayedJobOpts;
     /**
@@ -71,4 +137,20 @@ export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseB
 }
 export type BackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> = Either<WorkstreamBackgroundJobConfig<T>, QueueBackgroundJobConfig<T>>;
 export type PsychicBackgroundOptions = (PsychicBackgroundSimpleOptions & Partial<Record<Exclude<keyof PsychicBackgroundNativeBullMQOptions, keyof PsychicBackgroundSimpleOptions>, never>>) | (PsychicBackgroundNativeBullMQOptions & Partial<Record<Exclude<keyof PsychicBackgroundSimpleOptions, keyof PsychicBackgroundNativeBullMQOptions>, never>>);
+/**
+ * @internal
+ *
+ * how a queue was configured, as far as the misconfiguration message needs to
+ * know in order to name the fix that applies to the worker that threw
+ */
+export interface WorkerQueueDescription {
+    /** simple (workstream) configuration or native BullMQ configuration */
+    mode: 'simple' | 'native';
+    /** the default workstream/queue, as opposed to a named one */
+    isDefaultQueue: boolean;
+    /** the workstream or queue name as configured (not the formatted Redis queue name) */
+    configuredName: string;
+    /** a workstream declared under `transitionalWorkstreams` */
+    transitional: boolean;
+}
 export {};

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "author": "RVO Health",
   "publishConfig": {
     "access": "public"
@@ -40,6 +40,9 @@
   "files": [
     "dist/**/*"
   ],
+  "engines": {
+    "node": ">=24"
+  },
   "scripts": {
     "psy": "NODE_ENV=${NODE_ENV:-test} pnpm psy:ts",
     "psy:js": "node ./dist/test-app/src/cli/index.js",
@@ -64,46 +67,46 @@
     "@eslint/js": "^10.0.1",
     "@koa/cors": "^5.0.0",
     "@koa/etag": "^5.0.2",
-    "@koa/router": "^15.4.0",
-    "@rvoh/dream": "^2.5.3",
-    "@rvoh/dream-spec-helpers": "^2.1.1",
-    "@rvoh/psychic": "^3.0.3",
-    "@rvoh/psychic-spec-helpers": "^3.0.0",
-    "@types/koa": "^3.0.2",
+    "@koa/router": "^15.7.0",
+    "@rvoh/dream": "^2.33.0",
+    "@rvoh/dream-spec-helpers": "^2.3.0",
+    "@rvoh/psychic": "^3.15.2",
+    "@rvoh/psychic-spec-helpers": "^3.4.0",
+    "@types/koa": "^3.0.3",
     "@types/koa-bodyparser": "^4.3.13",
     "@types/koa-conditional-get": "^2.0.4",
     "@types/koa-etag": "^3.0.4",
     "@types/koa__cors": "^5.0.1",
     "@types/koa__router": "^12.0.5",
-    "@types/node": "^22.12.0",
+    "@types/node": "^26.6.3",
     "@types/pg": "^8",
-    "@types/supertest": "^6.0.3",
-    "@typescript-eslint/parser": "^8.67.0",
+    "@types/supertest": "^7.2.1",
+    "@typescript-eslint/parser": "^8.70.1",
     "bullmq": "^5.64.0",
-    "eslint": "^10.0.1",
+    "eslint": "^10.11.0",
     "ioredis": "^5.8.2",
-    "koa": "^3.1.2",
+    "koa": "^3.2.1",
     "koa-bodyparser": "^4.4.1",
     "koa-conditional-get": "^3.0.0",
-    "kysely": "^0.28.17",
+    "kysely": "^0.29.6",
     "kysely-codegen": "~0.20.0",
     "luxon-jest-matchers": "^0.1.14",
-    "openapi-typescript": "^7.9.1",
-    "pg": "^8.13.1",
-    "prettier": "^3.3.3",
-    "supertest": "^7.2.2",
+    "openapi-typescript": "^7.13.0",
+    "pg": "^8.23.0",
+    "prettier": "^3.9.9",
+    "supertest": "^7.3.0",
     "tslib": "^2.7.0",
-    "tsx": "^4.20.6",
-    "typedoc": "^0.28.17",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.67.0",
-    "vite": "^7.3.6",
-    "vitest": "^4.1.11"
+    "tsx": "^4.23.15",
+    "typedoc": "^0.28.20",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
   },
   "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b",
   "dependencies": {
-    "commander": "^14.0.2",
-    "dotenv": "^17.2.3",
+    "commander": "^14.0.3",
+    "dotenv": "^17.4.2",
     "pluralize-esm": "^9.0.5"
   }
 }