@rvoh/psychic-workers 0.4.4 → 1.0.0

package/dist/cjs/src/background/BaseBackgroundedService.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const dream_1 = require("@rvoh/dream");
-const index_js_1 = require("./index.js");
 const durationToSeconds_js_1 = require("../helpers/durationToSeconds.js");
+const index_js_1 = require("./index.js");
 class BaseBackgroundedService {
     /**
      * A getter meant to be overridden in child classes. This does

package/dist/cjs/src/background/helpers/nameToRedisQueueName.js

@@ -2,9 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = nameToRedisQueueName;
 const ioredis_1 = require("ioredis");
+const parallelTestSafeQueueName_js_1 = require("./parallelTestSafeQueueName.js");
 function nameToRedisQueueName(queueName, redis) {
     queueName = queueName.replace(/\{|\}/g, '');
     if (redis instanceof ioredis_1.Cluster)
         return `{${queueName}}`;
-    return queueName;
+    return (0, parallelTestSafeQueueName_js_1.default)(queueName);
 }

package/dist/cjs/src/background/helpers/parallelTestSafeQueueName.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = parallelTestSafeQueueName;
+const EnvInternal_js_1 = require("../../helpers/EnvInternal.js");
+function parallelTestSafeQueueName(queueName) {
+    if (EnvInternal_js_1.default.isTest && (EnvInternal_js_1.default.integer('VITEST_POOL_ID', { optional: true }) || 0) > 1) {
+        queueName = `${queueName}-${EnvInternal_js_1.default.integer('VITEST_POOL_ID')}`;
+    }
+    return queueName;
+}

package/dist/cjs/src/background/index.js

@@ -207,6 +207,7 @@ class Background {
             const workerCount = backgroundOptions.defaultWorkstream?.workerCount ?? 1;
             for (let i = 0; i < workerCount; i++) {
                 this._workers.push(new Background.Worker(formattedQueueName, async (job) => await this.doWork(job), {
+                    autorun: !EnvInternal_js_1.default.isTest,
                     connection: defaultWorkerConnection,
                     concurrency: backgroundOptions.defaultWorkstream?.concurrency || DEFAULT_CONCURRENCY,
                 }));
@@ -250,6 +251,7 @@ class Background {
                 const workerCount = namedWorkstream.workerCount ?? 1;
                 for (let i = 0; i < workerCount; i++) {
                     this._workers.push(new Background.Worker(namedWorkstreamFormattedQueueName, async (job) => await this.doWork(job), {
+                        autorun: !EnvInternal_js_1.default.isTest,
                         group: {
                             id: namedWorkstream.name,
                             limit: namedWorkstream.rateLimit,
@@ -312,6 +314,7 @@ class Background {
             const workerCount = nativeBullMQ.defaultWorkerCount ?? 1;
             for (let i = 0; i < workerCount; i++) {
                 this._workers.push(new Background.Worker(formattedQueueName, async (job) => await this.doWork(job), {
+                    autorun: !EnvInternal_js_1.default.isTest,
                     ...(backgroundOptions.nativeBullMQ.defaultWorkerOptions || {}),
                     connection: defaultWorkerConnection,
                 }));
@@ -354,6 +357,7 @@ class Background {
                     throw new ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection_js_1.default(queueName);
                 for (let i = 0; i < extraWorkerCount; i++) {
                     this._workers.push(new Background.Worker(formattedQueuename, async (job) => await this.doWork(job), {
+                        autorun: !EnvInternal_js_1.default.isTest,
                         ...extraWorkerOptions,
                         connection: namedWorkerConnection,
                     }));
@@ -504,7 +508,11 @@ class Background {
         // if delaySeconds is 0, we will intentionally treat
         // this as `undefined`
         const delay = delaySeconds ? delaySeconds * 1000 : undefined;
-        if (EnvInternal_js_1.default.isTest && !EnvInternal_js_1.default.boolean('REALLY_TEST_BACKGROUND_QUEUE')) {
+        const workersApp = index_js_1.default.getOrFail();
+        // in test environments, this block will short-circuit adding to the queue,
+        // causing the job to immediately invoke instead. This behavior can be bypassed
+        // by setting `testInvocation=manual` in the workers config.
+        if (EnvInternal_js_1.default.isTest && workersApp.testInvocation === 'automatic') {
             const queue = new Background.Queue('TestQueue', { connection: {} });
             const job = new bullmq_1.Job(queue, jobType, jobData, {});
             await this.doWork(job);

package/dist/cjs/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NoQueueForSpecifiedWorkstream = exports.NoQueueForSpecifiedQueueName = exports.PsychicAppWorkers = exports.BaseScheduledService = exports.BaseBackgroundedService = exports.BaseBackgroundedModel = exports.stopBackgroundWorkers = exports.Background = exports.background = void 0;
+exports.WorkerTestUtils = exports.NoQueueForSpecifiedWorkstream = exports.NoQueueForSpecifiedQueueName = exports.PsychicAppWorkers = exports.BaseScheduledService = exports.BaseBackgroundedService = exports.BaseBackgroundedModel = exports.stopBackgroundWorkers = exports.Background = exports.background = void 0;
 var index_js_1 = require("./background/index.js");
 Object.defineProperty(exports, "background", { enumerable: true, get: function () { return index_js_1.default; } });
 Object.defineProperty(exports, "Background", { enumerable: true, get: function () { return index_js_1.Background; } });
@@ -17,3 +17,5 @@ var NoQueueForSpecifiedQueueName_js_1 = require("./error/background/NoQueueForSp
 Object.defineProperty(exports, "NoQueueForSpecifiedQueueName", { enumerable: true, get: function () { return NoQueueForSpecifiedQueueName_js_1.default; } });
 var NoQueueForSpecifiedWorkstream_js_1 = require("./error/background/NoQueueForSpecifiedWorkstream.js");
 Object.defineProperty(exports, "NoQueueForSpecifiedWorkstream", { enumerable: true, get: function () { return NoQueueForSpecifiedWorkstream_js_1.default; } });
+var WorkerTestUtils_js_1 = require("./test-utils/WorkerTestUtils.js");
+Object.defineProperty(exports, "WorkerTestUtils", { enumerable: true, get: function () { return WorkerTestUtils_js_1.default; } });

package/dist/cjs/src/psychic-app-workers/index.js

@@ -7,7 +7,7 @@ class PsychicAppWorkers {
     static async init(psychicApp, cb) {
         const psychicWorkersApp = new PsychicAppWorkers(psychicApp);
         await cb(psychicWorkersApp);
-        psychicApp.on('sync', () => {
+        psychicApp.on('cli:sync', () => {
             index_js_1.default.connect();
             const output = {
                 workstreamNames: [...index_js_1.default['workstreamNames']],
@@ -18,6 +18,9 @@ class PsychicAppWorkers {
         psychicApp.on('server:shutdown', async () => {
             await index_js_1.default.closeAllRedisConnections();
         });
+        psychicApp.on('server:init:after-routes', () => {
+            index_js_1.default.connect();
+        });
         (0, cache_js_1.cachePsychicWorkersApp)(psychicWorkersApp);
         return psychicWorkersApp;
     }
@@ -41,6 +44,20 @@ class PsychicAppWorkers {
         return this._backgroundOptions;
     }
     _backgroundOptions;
+    /**
+     * Returns the testInvocation option provided by the user
+     *
+     * when "automatic", any backgrounded job will be immediately
+     * invoked during tests. This is the default behavior
+     *
+     * when "manual", this will enable the dev to manually interact with
+     * queues, enabling them to target jobs and run them at specific
+     * code points.
+     */
+    get testInvocation() {
+        return this._testInvocation;
+    }
+    _testInvocation = 'automatic';
     _hooks = {
         workerShutdown: [],
     };
@@ -69,6 +86,9 @@ class PsychicAppWorkers {
                     ...value,
                 };
                 break;
+            case 'testInvocation':
+                this._testInvocation = value;
+                break;
             default:
                 throw new Error(`Unhandled option type passed to PsychicWorkersApp#set: ${option}`);
         }

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

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("../background/index.js");
+const parallelTestSafeQueueName_js_1 = require("../background/helpers/parallelTestSafeQueueName.js");
+const LOCK_TOKEN = 'psychic-test-worker';
+class WorkerTestUtils {
+    /*
+     * Safely encapsulate's a queue name in parallel test runs,
+     * capturing the VITEST_POOL_ID and appending it to the
+     * end of the queue name if VITEST_POOL_ID > 1
+     */
+    static parallelTestSafeQueueName(queueName) {
+        return (0, parallelTestSafeQueueName_js_1.default)(queueName);
+    }
+    /*
+     * Works off all of the jobs in all queues. The jobs
+     * are worked off in a round-robin fashion until every queue
+     * is empty, at which point the promise will resolve
+     *
+     * ```ts
+     * await MyService.background('someMethod', ...)
+     * await WorkerTestUtils.work()
+     * // now you can safely assert the results of your background job
+     * ```
+     *
+     * 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.
+     */
+    static async work(opts = {}) {
+        index_js_1.default.connect();
+        const queues = index_js_1.default.queues;
+        let workWasDone = true;
+        do {
+            workWasDone = false;
+            for (const queue of queues) {
+                if (opts.queue && !this.queueNamesMatch(queue, opts.queue))
+                    continue;
+                workWasDone ||= await this.workOne(queue);
+            }
+        } while (workWasDone);
+    }
+    static async workScheduled(opts = {}) {
+        index_js_1.default.connect();
+        const queues = opts.queue
+            ? index_js_1.default.queues.filter(queue => queue.name === opts.queue)
+            : index_js_1.default.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: ${index_js_1.default.queues.map(queue => queue.name).join(', ')}`);
+        for (const queue of queues) {
+            const jobs = (await queue.getDelayed());
+            for (const job of jobs) {
+                const data = job.data;
+                if (opts.for) {
+                    if (data.globalName === opts.for.globalName) {
+                        await index_js_1.default.doWork(job);
+                    }
+                }
+                else {
+                    await index_js_1.default.doWork(job);
+                }
+            }
+        }
+    }
+    /*
+     * iterates through each registered queue, and cleans out all
+     * jobs, including completed, failed, 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
+     * manually, you may want to do this in your spec/setup/hooks.ts file,
+     * so that it can be called before every test.
+     *
+     * ```ts
+     * beforeEach(async () => {
+     *   await WorkerTestUtils.clean()
+     * })
+     * ```
+     */
+    static async clean() {
+        index_js_1.default.connect();
+        for (const queue of index_js_1.default.queues) {
+            // clears all non-scheduled, non-completed, and non-failed jobs
+            await queue.drain();
+            // clear out completed and failed jobs
+            await queue.clean(0, 10000, 'completed');
+            await queue.clean(0, 10000, 'failed');
+            // clear out scheduled jobs
+            const schedulers = await queue.getJobSchedulers();
+            for (const scheduler of schedulers) {
+                await queue.removeJobScheduler(scheduler.key);
+            }
+        }
+    }
+    static async workOne(queue) {
+        const worker = new index_js_1.Background.Worker(queue.name, async (job) => await index_js_1.default.doWork(job), {
+            autorun: false,
+            connection: queue.client,
+            concurrency: 1,
+        });
+        if (!worker)
+            throw new Error(`Failed to find worker for queue: ${queue.name}`);
+        const job = await worker.getNextJob(LOCK_TOKEN);
+        if (!job)
+            return false;
+        await this.processJob(job);
+        return true;
+    }
+    static queueNamesMatch(queue, compareQueueName) {
+        return (queue.name === (0, parallelTestSafeQueueName_js_1.default)(compareQueueName) ||
+            queue.name === `{${(0, parallelTestSafeQueueName_js_1.default)(compareQueueName)}`);
+    }
+    static async processJob(job) {
+        try {
+            const res = await index_js_1.default.doWork(job);
+            await job.moveToCompleted(res, LOCK_TOKEN, false);
+        }
+        catch (err) {
+            await job.moveToFailed(err, LOCK_TOKEN, false);
+        }
+    }
+}
+exports.default = WorkerTestUtils;

package/dist/esm/src/background/BaseBackgroundedService.js

@@ -1,6 +1,6 @@
 import { GlobalNameNotSet } from '@rvoh/dream';
-import background from './index.js';
 import durationToSeconds from '../helpers/durationToSeconds.js';
+import background from './index.js';
 export default class BaseBackgroundedService {
     /**
      * A getter meant to be overridden in child classes. This does

package/dist/esm/src/background/helpers/nameToRedisQueueName.js

@@ -1,7 +1,8 @@
 import { Cluster } from 'ioredis';
+import parallelTestSafeQueueName from './parallelTestSafeQueueName.js';
 export default function nameToRedisQueueName(queueName, redis) {
     queueName = queueName.replace(/\{|\}/g, '');
     if (redis instanceof Cluster)
         return `{${queueName}}`;
-    return queueName;
+    return parallelTestSafeQueueName(queueName);
 }

package/dist/esm/src/background/helpers/parallelTestSafeQueueName.js

@@ -0,0 +1,7 @@
+import EnvInternal from '../../helpers/EnvInternal.js';
+export default function parallelTestSafeQueueName(queueName) {
+    if (EnvInternal.isTest && (EnvInternal.integer('VITEST_POOL_ID', { optional: true }) || 0) > 1) {
+        queueName = `${queueName}-${EnvInternal.integer('VITEST_POOL_ID')}`;
+    }
+    return queueName;
+}

package/dist/esm/src/background/index.js

@@ -203,6 +203,7 @@ export class Background {
             const workerCount = backgroundOptions.defaultWorkstream?.workerCount ?? 1;
             for (let i = 0; i < workerCount; i++) {
                 this._workers.push(new Background.Worker(formattedQueueName, async (job) => await this.doWork(job), {
+                    autorun: !EnvInternal.isTest,
                     connection: defaultWorkerConnection,
                     concurrency: backgroundOptions.defaultWorkstream?.concurrency || DEFAULT_CONCURRENCY,
                 }));
@@ -246,6 +247,7 @@ export class Background {
                 const workerCount = namedWorkstream.workerCount ?? 1;
                 for (let i = 0; i < workerCount; i++) {
                     this._workers.push(new Background.Worker(namedWorkstreamFormattedQueueName, async (job) => await this.doWork(job), {
+                        autorun: !EnvInternal.isTest,
                         group: {
                             id: namedWorkstream.name,
                             limit: namedWorkstream.rateLimit,
@@ -308,6 +310,7 @@ export class Background {
             const workerCount = nativeBullMQ.defaultWorkerCount ?? 1;
             for (let i = 0; i < workerCount; i++) {
                 this._workers.push(new Background.Worker(formattedQueueName, async (job) => await this.doWork(job), {
+                    autorun: !EnvInternal.isTest,
                     ...(backgroundOptions.nativeBullMQ.defaultWorkerOptions || {}),
                     connection: defaultWorkerConnection,
                 }));
@@ -350,6 +353,7 @@ export class Background {
                     throw new ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection(queueName);
                 for (let i = 0; i < extraWorkerCount; i++) {
                     this._workers.push(new Background.Worker(formattedQueuename, async (job) => await this.doWork(job), {
+                        autorun: !EnvInternal.isTest,
                         ...extraWorkerOptions,
                         connection: namedWorkerConnection,
                     }));
@@ -500,7 +504,11 @@ export class Background {
         // if delaySeconds is 0, we will intentionally treat
         // this as `undefined`
         const delay = delaySeconds ? delaySeconds * 1000 : undefined;
-        if (EnvInternal.isTest && !EnvInternal.boolean('REALLY_TEST_BACKGROUND_QUEUE')) {
+        const workersApp = PsychicAppWorkers.getOrFail();
+        // in test environments, this block will short-circuit adding to the queue,
+        // causing the job to immediately invoke instead. This behavior can be bypassed
+        // by setting `testInvocation=manual` in the workers config.
+        if (EnvInternal.isTest && workersApp.testInvocation === 'automatic') {
             const queue = new Background.Queue('TestQueue', { connection: {} });
             const job = new Job(queue, jobType, jobData, {});
             await this.doWork(job);

package/dist/esm/src/index.js

@@ -5,3 +5,4 @@ export { default as BaseScheduledService } from './background/BaseScheduledServi
 export { default as PsychicAppWorkers, } from './psychic-app-workers/index.js';
 export { default as NoQueueForSpecifiedQueueName } from './error/background/NoQueueForSpecifiedQueueName.js';
 export { default as NoQueueForSpecifiedWorkstream } from './error/background/NoQueueForSpecifiedWorkstream.js';
+export { default as WorkerTestUtils } from './test-utils/WorkerTestUtils.js';

package/dist/esm/src/psychic-app-workers/index.js

@@ -5,7 +5,7 @@ export default class PsychicAppWorkers {
     static async init(psychicApp, cb) {
         const psychicWorkersApp = new PsychicAppWorkers(psychicApp);
         await cb(psychicWorkersApp);
-        psychicApp.on('sync', () => {
+        psychicApp.on('cli:sync', () => {
             background.connect();
             const output = {
                 workstreamNames: [...background['workstreamNames']],
@@ -16,6 +16,9 @@ export default class PsychicAppWorkers {
         psychicApp.on('server:shutdown', async () => {
             await background.closeAllRedisConnections();
         });
+        psychicApp.on('server:init:after-routes', () => {
+            background.connect();
+        });
         cachePsychicWorkersApp(psychicWorkersApp);
         return psychicWorkersApp;
     }
@@ -39,6 +42,20 @@ export default class PsychicAppWorkers {
         return this._backgroundOptions;
     }
     _backgroundOptions;
+    /**
+     * Returns the testInvocation option provided by the user
+     *
+     * when "automatic", any backgrounded job will be immediately
+     * invoked during tests. This is the default behavior
+     *
+     * when "manual", this will enable the dev to manually interact with
+     * queues, enabling them to target jobs and run them at specific
+     * code points.
+     */
+    get testInvocation() {
+        return this._testInvocation;
+    }
+    _testInvocation = 'automatic';
     _hooks = {
         workerShutdown: [],
     };
@@ -67,6 +84,9 @@ export default class PsychicAppWorkers {
                     ...value,
                 };
                 break;
+            case 'testInvocation':
+                this._testInvocation = value;
+                break;
             default:
                 throw new Error(`Unhandled option type passed to PsychicWorkersApp#set: ${option}`);
         }

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

@@ -0,0 +1,121 @@
+import background, { Background } from '../background/index.js';
+import parallelTestSafeQueueName from '../background/helpers/parallelTestSafeQueueName.js';
+const LOCK_TOKEN = 'psychic-test-worker';
+export default class WorkerTestUtils {
+    /*
+     * Safely encapsulate's a queue name in parallel test runs,
+     * capturing the VITEST_POOL_ID and appending it to the
+     * end of the queue name if VITEST_POOL_ID > 1
+     */
+    static parallelTestSafeQueueName(queueName) {
+        return parallelTestSafeQueueName(queueName);
+    }
+    /*
+     * Works off all of the jobs in all queues. The jobs
+     * are worked off in a round-robin fashion until every queue
+     * is empty, at which point the promise will resolve
+     *
+     * ```ts
+     * await MyService.background('someMethod', ...)
+     * await WorkerTestUtils.work()
+     * // now you can safely assert the results of your background job
+     * ```
+     *
+     * 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.
+     */
+    static async work(opts = {}) {
+        background.connect();
+        const queues = background.queues;
+        let workWasDone = true;
+        do {
+            workWasDone = false;
+            for (const queue of queues) {
+                if (opts.queue && !this.queueNamesMatch(queue, opts.queue))
+                    continue;
+                workWasDone ||= await this.workOne(queue);
+            }
+        } while (workWasDone);
+    }
+    static async workScheduled(opts = {}) {
+        background.connect();
+        const queues = opts.queue
+            ? background.queues.filter(queue => queue.name === opts.queue)
+            : 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(', ')}`);
+        for (const queue of queues) {
+            const jobs = (await queue.getDelayed());
+            for (const job of jobs) {
+                const data = job.data;
+                if (opts.for) {
+                    if (data.globalName === opts.for.globalName) {
+                        await background.doWork(job);
+                    }
+                }
+                else {
+                    await background.doWork(job);
+                }
+            }
+        }
+    }
+    /*
+     * iterates through each registered queue, and cleans out all
+     * jobs, including completed, failed, 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
+     * manually, you may want to do this in your spec/setup/hooks.ts file,
+     * so that it can be called before every test.
+     *
+     * ```ts
+     * beforeEach(async () => {
+     *   await WorkerTestUtils.clean()
+     * })
+     * ```
+     */
+    static async clean() {
+        background.connect();
+        for (const queue of background.queues) {
+            // clears all non-scheduled, non-completed, and non-failed jobs
+            await queue.drain();
+            // clear out completed and failed jobs
+            await queue.clean(0, 10000, 'completed');
+            await queue.clean(0, 10000, 'failed');
+            // clear out scheduled jobs
+            const schedulers = await queue.getJobSchedulers();
+            for (const scheduler of schedulers) {
+                await queue.removeJobScheduler(scheduler.key);
+            }
+        }
+    }
+    static async workOne(queue) {
+        const worker = new Background.Worker(queue.name, async (job) => await background.doWork(job), {
+            autorun: false,
+            connection: queue.client,
+            concurrency: 1,
+        });
+        if (!worker)
+            throw new Error(`Failed to find worker for queue: ${queue.name}`);
+        const job = await worker.getNextJob(LOCK_TOKEN);
+        if (!job)
+            return false;
+        await this.processJob(job);
+        return true;
+    }
+    static queueNamesMatch(queue, compareQueueName) {
+        return (queue.name === parallelTestSafeQueueName(compareQueueName) ||
+            queue.name === `{${parallelTestSafeQueueName(compareQueueName)}`);
+    }
+    static async processJob(job) {
+        try {
+            const res = await background.doWork(job);
+            await job.moveToCompleted(res, LOCK_TOKEN, false);
+        }
+        catch (err) {
+            await job.moveToFailed(err, LOCK_TOKEN, false);
+        }
+    }
+}

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

@@ -1,2 +1,2 @@
-import { Redis, Cluster } from 'ioredis';
+import { Cluster, Redis } from 'ioredis';
 export default function nameToRedisQueueName(queueName: string, redis: Redis | Cluster): string;

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

@@ -0,0 +1 @@
+export default function parallelTestSafeQueueName(queueName: string): string;

package/dist/types/src/helpers/EnvInternal.d.ts

@@ -1,6 +1,7 @@
 import { Env } from '@rvoh/dream';
 declare const EnvInternal: Env<{
     string: "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT";
+    integer: "VITEST_POOL_ID";
     boolean: "REALLY_TEST_BACKGROUND_QUEUE";
-}, "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT", never, "REALLY_TEST_BACKGROUND_QUEUE">;
+}, "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT", "VITEST_POOL_ID", "REALLY_TEST_BACKGROUND_QUEUE">;
 export default EnvInternal;

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

@@ -6,3 +6,4 @@ export { default as BaseScheduledService } from './background/BaseScheduledServi
 export { default as PsychicAppWorkers, type BullMQNativeWorkerOptions, type PsychicBackgroundNativeBullMQOptions, type PsychicBackgroundSimpleOptions, type PsychicBackgroundWorkstreamOptions, type QueueOptionsWithConnectionInstance, type RedisOrRedisClusterConnection, type TransitionalPsychicBackgroundSimpleOptions, } from './psychic-app-workers/index.js';
 export { default as NoQueueForSpecifiedQueueName } from './error/background/NoQueueForSpecifiedQueueName.js';
 export { default as NoQueueForSpecifiedWorkstream } from './error/background/NoQueueForSpecifiedWorkstream.js';
+export { default as WorkerTestUtils } from './test-utils/WorkerTestUtils.js';

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

@@ -18,16 +18,29 @@ export default class PsychicAppWorkers {
      */
     get backgroundOptions(): PsychicBackgroundOptions;
     private _backgroundOptions;
+    /**
+     * Returns the testInvocation option provided by the user
+     *
+     * when "automatic", any backgrounded job will be immediately
+     * invoked during tests. This is the default behavior
+     *
+     * when "manual", this will enable the dev to manually interact with
+     * queues, enabling them to target jobs and run them at specific
+     * code points.
+     */
+    get testInvocation(): PsychicWorkersAppTestInvocationType;
+    private _testInvocation;
     private _hooks;
     get hooks(): PsychicWorkersAppHooks;
     on<T extends PsychicWorkersHookEventType>(hookEventType: T, cb: T extends 'workers:shutdown' ? () => void | Promise<void> : never): void;
-    set<Opt extends PsychicWorkersAppOption>(option: Opt, value: Opt extends 'background' ? PsychicBackgroundOptions : unknown): void;
+    set<Opt extends PsychicWorkersAppOption>(option: Opt, value: Opt extends 'background' ? PsychicBackgroundOptions : Opt extends 'testInvocation' ? PsychicWorkersAppTestInvocationType : unknown): void;
 }
 export interface PsychicWorkersTypeSync {
     workstreamNames: string[];
     queueGroupMap: Record<string, string[]>;
 }
-export type PsychicWorkersAppOption = 'background';
+export type PsychicWorkersAppOption = 'background' | 'testInvocation';
+export type PsychicWorkersAppTestInvocationType = 'automatic' | 'manual';
 export type PsychicWorkersHookEventType = 'workers:shutdown';
 export interface PsychicWorkersAppHooks {
     workerShutdown: (() => void | Promise<void>)[];

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

@@ -0,0 +1,19 @@
+export default class WorkerTestUtils {
+    static parallelTestSafeQueueName(queueName: string): string;
+    static work(opts?: TestWorkerWorkOffOpts): Promise<void>;
+    static workScheduled(opts?: TestWorkerScheduledWorkOffOpts): Promise<void>;
+    static clean(): Promise<void>;
+    private static workOne;
+    private static queueNamesMatch;
+    private static processJob;
+}
+interface TestWorkerWorkOffOpts {
+    queue?: string;
+}
+interface TestWorkerScheduledWorkOffOpts {
+    queue?: string;
+    for?: {
+        globalName: string;
+    };
+}
+export {};

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

@@ -52,7 +52,7 @@ interface BaseBackgroundJobConfig {
 export interface WorkstreamBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> extends BaseBackgroundJobConfig {
     workstream?: T['psychicTypes']['workstreamNames'][number];
 }
-export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService, PsyTypes extends T['psychicTypes'] = T['psychicTypes'], QueueGroupMap = PsyTypes['queueGroupMap'], Queue extends keyof QueueGroupMap = keyof QueueGroupMap, Groups extends QueueGroupMap[Queue] = QueueGroupMap[Queue], GroupId = Groups[number & keyof Groups]> extends BaseBackgroundJobConfig {
+export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService, PsyTypes extends T['psychicTypes'] = T['psychicTypes'], QueueGroupMap = PsyTypes['queueGroupMap'], Queue extends keyof QueueGroupMap & string = keyof QueueGroupMap & string, Groups extends QueueGroupMap[Queue] = QueueGroupMap[Queue], GroupId = Groups[number & keyof Groups]> extends BaseBackgroundJobConfig {
     groupId?: GroupId;
     queue?: Queue;
 }

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "0.4.4",
+  "version": "1.0.0",
   "author": "RVO Health",
   "repository": {
     "type": "git",
@@ -45,7 +45,7 @@
     "@eslint/js": "=9.0.0",
     "@rvoh/dream": "^0.39.0",
     "@rvoh/dream-spec-helpers": "^0.2.4",
-    "@rvoh/psychic": "^0.31.0",
+    "@rvoh/psychic": "^0.35.1",
     "@rvoh/psychic-spec-helpers": "^0.6.0",
     "@socket.io/redis-adapter": "^8.3.0",
     "@socket.io/redis-emitter": "^5.1.0",
@@ -70,7 +70,7 @@
     "typedoc": "^0.26.6",
     "typescript": "^5.8.2",
     "typescript-eslint": "=7.18.0",
-    "vitest": "^3.1.1"
+    "vitest": "^3.1.3"
   },
   "packageManager": "yarn@4.7.0"
 }