@rvoh/psychic-workers 0.3.1 → 0.4.0

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

@@ -2,6 +2,7 @@
 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");
 class BaseBackgroundedModel extends dream_1.Dream {
     /**
      * A getter meant to be overridden in child classes. This does
@@ -76,11 +77,12 @@ class BaseBackgroundedModel extends dream_1.Dream {
      * @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 async backgroundWithDelay(delaySeconds, methodName, ...args) {
+    static async backgroundWithDelay(delay, methodName, ...args) {
         const safeThis = this;
         return await index_js_1.default.staticMethod(safeThis, methodName, {
             globalName: safeThis.globalName,
-            delaySeconds,
+            delaySeconds: (0, durationToSeconds_js_1.default)(delay),
+            jobId: delay.jobId,
             args,
             jobConfig: safeThis.backgroundJobConfig,
         });
@@ -143,11 +145,12 @@ class BaseBackgroundedModel extends dream_1.Dream {
      * @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
      */
-    async backgroundWithDelay(delaySeconds, methodName, ...args) {
+    async backgroundWithDelay(delay, methodName, ...args) {
         const safeThis = this;
         return await index_js_1.default.modelInstanceMethod(safeThis, methodName, {
             args,
-            delaySeconds,
+            delaySeconds: (0, durationToSeconds_js_1.default)(delay),
+            jobId: delay.jobId,
             jobConfig: safeThis.backgroundJobConfig,
         });
     }

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

@@ -2,6 +2,7 @@
 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");
 class BaseBackgroundedService {
     /**
      * A getter meant to be overridden in child classes. This does
@@ -88,11 +89,12 @@ class BaseBackgroundedService {
      * @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 async backgroundWithDelay(delaySeconds, methodName, ...args) {
+    static async backgroundWithDelay(delay, methodName, ...args) {
         const safeThis = this;
         return await index_js_1.default.staticMethod(safeThis, methodName, {
             globalName: safeThis.globalName,
-            delaySeconds,
+            delaySeconds: (0, durationToSeconds_js_1.default)(delay),
+            jobId: delay.jobId,
             args,
             jobConfig: safeThis.backgroundJobConfig,
         });

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

@@ -14,6 +14,7 @@ const NoQueueForSpecifiedWorkstream_js_1 = require("../error/background/NoQueueF
 const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
 const index_js_1 = require("../psychic-app-workers/index.js");
 const nameToRedisQueueName_js_1 = require("./helpers/nameToRedisQueueName.js");
+const DEFAULT_CONCURRENCY = 10;
 /**
  * the underlying class driving the `background` singleton,
  * available as an import from `psychic-workers`.
@@ -130,13 +131,14 @@ class Background {
     }
     async shutdownAndExit() {
         await this.shutdown();
-        process.exit();
+        // https://docs.bullmq.io/guide/going-to-production#gracefully-shut-down-workers
+        process.exit(0);
     }
     /**
      * Shuts down workers, closes all redis connections
      */
     async shutdown() {
-        await Promise.all(this._workers.map(worker => worker.close()));
+        index_js_1.default.getOrFail().psychicApp.logger.info(`[psychic-workers] shutdown`);
         const psychicWorkersApp = index_js_1.default.getOrFail();
         for (const hook of psychicWorkersApp.hooks.workerShutdown) {
             await hook();
@@ -148,19 +150,12 @@ class Background {
      * closes all redis connections for workers and queues
      */
     async closeAllRedisConnections() {
-        for (const queue of this.queues) {
-            await queue.close();
-        }
+        index_js_1.default.getOrFail().psychicApp.logger.info(`[psychic-workers] closeAllRedisConnections`);
         for (const worker of this.workers) {
             await worker.close();
         }
         for (const connection of this.redisConnections) {
-            try {
-                connection.disconnect();
-            }
-            catch {
-                // noop
-            }
+            await connection.quit();
         }
     }
     /**
@@ -205,7 +200,7 @@ class Background {
             for (let i = 0; i < workerCount; i++) {
                 this._workers.push(new Background.Worker(formattedQueueName, async (job) => await this.doWork(job), {
                     connection: defaultWorkerConnection,
-                    concurrency: backgroundOptions.defaultWorkstream?.concurrency || 1,
+                    concurrency: backgroundOptions.defaultWorkstream?.concurrency || DEFAULT_CONCURRENCY,
                 }));
             }
         }
@@ -252,7 +247,7 @@ class Background {
                             limit: namedWorkstream.rateLimit,
                         },
                         connection: namedWorkstreamWorkerConnection,
-                        concurrency: namedWorkstream.concurrency || 1,
+                        concurrency: namedWorkstream.concurrency || DEFAULT_CONCURRENCY,
                         // explicitly typing as WorkerOptions because Psychic can't be aware of BullMQ Pro options
                     }));
                 }
@@ -322,6 +317,7 @@ class Background {
         /////////////////////////
         const namedQueueOptionsMap = nativeBullMQ.namedQueueOptions || {};
         Object.keys(namedQueueOptionsMap).forEach(queueName => {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
             const namedQueueOptions = namedQueueOptionsMap[queueName];
             if (namedQueueOptions.queueConnection)
                 this.redisConnections.push(namedQueueOptions.queueConnection);
@@ -344,7 +340,7 @@ class Background {
             const extraWorkerOptions = extraWorkerOptionsMap[queueName];
             const extraWorkerCount = extraWorkerOptions ? (extraWorkerOptions.workerCount ?? 1) : 0;
             this.groupNames[queueName] ||= [];
-            if (extraWorkerOptions.group?.id)
+            if (extraWorkerOptions?.group?.id)
                 this.groupNames[queueName].push(extraWorkerOptions.group.id);
             if (activateWorkers) {
                 if (!namedWorkerConnection)
@@ -370,11 +366,13 @@ class Background {
     work() {
         this.connect({ activateWorkers: true });
         process.on('SIGTERM', () => {
+            index_js_1.default.getOrFail().psychicApp.logger.info('[psychic-workers] handle SIGTERM');
             void this.shutdownAndExit()
                 .then(() => { })
                 .catch(() => { });
         });
         process.on('SIGINT', () => {
+            index_js_1.default.getOrFail().psychicApp.logger.info('[psychic-workers] handle SIGINT');
             void this.shutdownAndExit()
                 .then(() => { })
                 .catch(() => { });
@@ -391,7 +389,7 @@ class Background {
      * @param importKey - (optional) the import key for the class
      * @param jobConfig - (optional) the background job config to use when backgrounding this method
      */
-    async staticMethod(ObjectClass, method, { globalName, delaySeconds, args = [], jobConfig = {}, }) {
+    async staticMethod(ObjectClass, method, { globalName, delaySeconds, jobId, args = [], jobConfig = {}, }) {
         this.connect();
         await this._addToQueue(`BackgroundJobQueueStaticJob`, {
             globalName,
@@ -399,6 +397,7 @@ class Background {
             args,
         }, {
             delaySeconds,
+            jobId,
             jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
@@ -425,7 +424,10 @@ class Background {
         //
         // See: https://docs.bullmq.io/guide/jobs/repeatable
         const jobId = `${ObjectClass.name}:${method}`;
-        await this.queueInstance(jobConfig).add('BackgroundJobQueueStaticJob', {
+        const queueInstance = this.queueInstance(jobConfig);
+        if (!queueInstance)
+            throw new Error(`Missing queue for: ${jobConfig.queue?.toString()}`);
+        await queueInstance.add('BackgroundJobQueueStaticJob', {
             globalName,
             method,
             args,
@@ -468,7 +470,7 @@ class Background {
      * @param importKey - (optional) the import key for the class
      * @param jobConfig - (optional) the background job config to use when backgrounding this method
      */
-    async modelInstanceMethod(modelInstance, method, { delaySeconds, args = [], jobConfig = {}, }) {
+    async modelInstanceMethod(modelInstance, method, { delaySeconds, jobId, args = [], jobConfig = {}, }) {
         this.connect();
         await this._addToQueue('BackgroundJobQueueModelInstanceJob', {
             id: modelInstance.primaryKeyValue,
@@ -477,26 +479,33 @@ class Background {
             args,
         }, {
             delaySeconds,
+            jobId,
             jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
         });
     }
     // should be private, but public so we can test
-    async _addToQueue(jobType, jobData, { delaySeconds, jobConfig, priority, groupId, }) {
+    async _addToQueue(jobType, jobData, { delaySeconds, jobId, jobConfig, priority, groupId, }) {
         // set this variable out side of the conditional so that
         // mismatches will raise exceptions even in tests
         const queueInstance = this.queueInstance(jobConfig);
+        // 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 queue = new Background.Queue('TestQueue', { connection: {} });
             const job = new bullmq_1.Job(queue, jobType, jobData, {});
             await this.doWork(job);
+            return;
             //
         }
-        else if (groupId && priority) {
+        if (!queueInstance)
+            throw new Error(`missing queue: ${jobConfig?.queue?.toString() || 'N/A'}`);
+        if (groupId && priority) {
             await queueInstance.add(jobType, jobData, {
                 delay,
+                jobId,
                 group: {
                     ...this.groupIdToGroupConfig(groupId),
                     priority: this.mapPriorityWordToPriorityNumber(priority),
@@ -508,6 +517,7 @@ class Background {
         else {
             await queueInstance.add(jobType, jobData, {
                 delay,
+                jobId,
                 group: this.groupIdToGroupConfig(groupId),
                 priority: this.mapPriorityWordToPriorityNumber(priority),
                 // explicitly typing as JobsOptions because Psychic can't be aware of BullMQ Pro options

package/dist/cjs/src/helpers/durationToSeconds.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = durationToSeconds;
+function durationToSeconds(duration) {
+    return ((duration.seconds ? duration.seconds : 0) +
+        (duration.minutes ? duration.minutes * 60 : 0) +
+        (duration.hours ? duration.hours * 60 * 60 : 0) +
+        (duration.days ? duration.days * 60 * 60 * 24 : 0));
+}

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

@@ -1,5 +1,6 @@
 import { Dream } from '@rvoh/dream';
 import background from './index.js';
+import durationToSeconds from '../helpers/durationToSeconds.js';
 export default class BaseBackgroundedModel extends Dream {
     /**
      * A getter meant to be overridden in child classes. This does
@@ -74,11 +75,12 @@ export default class BaseBackgroundedModel extends Dream {
      * @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 async backgroundWithDelay(delaySeconds, methodName, ...args) {
+    static async backgroundWithDelay(delay, methodName, ...args) {
         const safeThis = this;
         return await background.staticMethod(safeThis, methodName, {
             globalName: safeThis.globalName,
-            delaySeconds,
+            delaySeconds: durationToSeconds(delay),
+            jobId: delay.jobId,
             args,
             jobConfig: safeThis.backgroundJobConfig,
         });
@@ -141,11 +143,12 @@ export default class BaseBackgroundedModel extends Dream {
      * @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
      */
-    async backgroundWithDelay(delaySeconds, methodName, ...args) {
+    async backgroundWithDelay(delay, methodName, ...args) {
         const safeThis = this;
         return await background.modelInstanceMethod(safeThis, methodName, {
             args,
-            delaySeconds,
+            delaySeconds: durationToSeconds(delay),
+            jobId: delay.jobId,
             jobConfig: safeThis.backgroundJobConfig,
         });
     }

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

@@ -1,5 +1,6 @@
 import { GlobalNameNotSet } from '@rvoh/dream';
 import background from './index.js';
+import durationToSeconds from '../helpers/durationToSeconds.js';
 export default class BaseBackgroundedService {
     /**
      * A getter meant to be overridden in child classes. This does
@@ -86,11 +87,12 @@ export default class BaseBackgroundedService {
      * @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 async backgroundWithDelay(delaySeconds, methodName, ...args) {
+    static async backgroundWithDelay(delay, methodName, ...args) {
         const safeThis = this;
         return await background.staticMethod(safeThis, methodName, {
             globalName: safeThis.globalName,
-            delaySeconds,
+            delaySeconds: durationToSeconds(delay),
+            jobId: delay.jobId,
             args,
             jobConfig: safeThis.backgroundJobConfig,
         });

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

@@ -10,6 +10,7 @@ import NoQueueForSpecifiedWorkstream from '../error/background/NoQueueForSpecifi
 import EnvInternal from '../helpers/EnvInternal.js';
 import PsychicAppWorkers from '../psychic-app-workers/index.js';
 import nameToRedisQueueName from './helpers/nameToRedisQueueName.js';
+const DEFAULT_CONCURRENCY = 10;
 /**
  * the underlying class driving the `background` singleton,
  * available as an import from `psychic-workers`.
@@ -126,13 +127,14 @@ export class Background {
     }
     async shutdownAndExit() {
         await this.shutdown();
-        process.exit();
+        // https://docs.bullmq.io/guide/going-to-production#gracefully-shut-down-workers
+        process.exit(0);
     }
     /**
      * Shuts down workers, closes all redis connections
      */
     async shutdown() {
-        await Promise.all(this._workers.map(worker => worker.close()));
+        PsychicAppWorkers.getOrFail().psychicApp.logger.info(`[psychic-workers] shutdown`);
         const psychicWorkersApp = PsychicAppWorkers.getOrFail();
         for (const hook of psychicWorkersApp.hooks.workerShutdown) {
             await hook();
@@ -144,19 +146,12 @@ export class Background {
      * closes all redis connections for workers and queues
      */
     async closeAllRedisConnections() {
-        for (const queue of this.queues) {
-            await queue.close();
-        }
+        PsychicAppWorkers.getOrFail().psychicApp.logger.info(`[psychic-workers] closeAllRedisConnections`);
         for (const worker of this.workers) {
             await worker.close();
         }
         for (const connection of this.redisConnections) {
-            try {
-                connection.disconnect();
-            }
-            catch {
-                // noop
-            }
+            await connection.quit();
         }
     }
     /**
@@ -201,7 +196,7 @@ export class Background {
             for (let i = 0; i < workerCount; i++) {
                 this._workers.push(new Background.Worker(formattedQueueName, async (job) => await this.doWork(job), {
                     connection: defaultWorkerConnection,
-                    concurrency: backgroundOptions.defaultWorkstream?.concurrency || 1,
+                    concurrency: backgroundOptions.defaultWorkstream?.concurrency || DEFAULT_CONCURRENCY,
                 }));
             }
         }
@@ -248,7 +243,7 @@ export class Background {
                             limit: namedWorkstream.rateLimit,
                         },
                         connection: namedWorkstreamWorkerConnection,
-                        concurrency: namedWorkstream.concurrency || 1,
+                        concurrency: namedWorkstream.concurrency || DEFAULT_CONCURRENCY,
                         // explicitly typing as WorkerOptions because Psychic can't be aware of BullMQ Pro options
                     }));
                 }
@@ -318,6 +313,7 @@ export class Background {
         /////////////////////////
         const namedQueueOptionsMap = nativeBullMQ.namedQueueOptions || {};
         Object.keys(namedQueueOptionsMap).forEach(queueName => {
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
             const namedQueueOptions = namedQueueOptionsMap[queueName];
             if (namedQueueOptions.queueConnection)
                 this.redisConnections.push(namedQueueOptions.queueConnection);
@@ -340,7 +336,7 @@ export class Background {
             const extraWorkerOptions = extraWorkerOptionsMap[queueName];
             const extraWorkerCount = extraWorkerOptions ? (extraWorkerOptions.workerCount ?? 1) : 0;
             this.groupNames[queueName] ||= [];
-            if (extraWorkerOptions.group?.id)
+            if (extraWorkerOptions?.group?.id)
                 this.groupNames[queueName].push(extraWorkerOptions.group.id);
             if (activateWorkers) {
                 if (!namedWorkerConnection)
@@ -366,11 +362,13 @@ export class Background {
     work() {
         this.connect({ activateWorkers: true });
         process.on('SIGTERM', () => {
+            PsychicAppWorkers.getOrFail().psychicApp.logger.info('[psychic-workers] handle SIGTERM');
             void this.shutdownAndExit()
                 .then(() => { })
                 .catch(() => { });
         });
         process.on('SIGINT', () => {
+            PsychicAppWorkers.getOrFail().psychicApp.logger.info('[psychic-workers] handle SIGINT');
             void this.shutdownAndExit()
                 .then(() => { })
                 .catch(() => { });
@@ -387,7 +385,7 @@ export class Background {
      * @param importKey - (optional) the import key for the class
      * @param jobConfig - (optional) the background job config to use when backgrounding this method
      */
-    async staticMethod(ObjectClass, method, { globalName, delaySeconds, args = [], jobConfig = {}, }) {
+    async staticMethod(ObjectClass, method, { globalName, delaySeconds, jobId, args = [], jobConfig = {}, }) {
         this.connect();
         await this._addToQueue(`BackgroundJobQueueStaticJob`, {
             globalName,
@@ -395,6 +393,7 @@ export class Background {
             args,
         }, {
             delaySeconds,
+            jobId,
             jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
@@ -421,7 +420,10 @@ export class Background {
         //
         // See: https://docs.bullmq.io/guide/jobs/repeatable
         const jobId = `${ObjectClass.name}:${method}`;
-        await this.queueInstance(jobConfig).add('BackgroundJobQueueStaticJob', {
+        const queueInstance = this.queueInstance(jobConfig);
+        if (!queueInstance)
+            throw new Error(`Missing queue for: ${jobConfig.queue?.toString()}`);
+        await queueInstance.add('BackgroundJobQueueStaticJob', {
             globalName,
             method,
             args,
@@ -464,7 +466,7 @@ export class Background {
      * @param importKey - (optional) the import key for the class
      * @param jobConfig - (optional) the background job config to use when backgrounding this method
      */
-    async modelInstanceMethod(modelInstance, method, { delaySeconds, args = [], jobConfig = {}, }) {
+    async modelInstanceMethod(modelInstance, method, { delaySeconds, jobId, args = [], jobConfig = {}, }) {
         this.connect();
         await this._addToQueue('BackgroundJobQueueModelInstanceJob', {
             id: modelInstance.primaryKeyValue,
@@ -473,26 +475,33 @@ export class Background {
             args,
         }, {
             delaySeconds,
+            jobId,
             jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
         });
     }
     // should be private, but public so we can test
-    async _addToQueue(jobType, jobData, { delaySeconds, jobConfig, priority, groupId, }) {
+    async _addToQueue(jobType, jobData, { delaySeconds, jobId, jobConfig, priority, groupId, }) {
         // set this variable out side of the conditional so that
         // mismatches will raise exceptions even in tests
         const queueInstance = this.queueInstance(jobConfig);
+        // 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 queue = new Background.Queue('TestQueue', { connection: {} });
             const job = new Job(queue, jobType, jobData, {});
             await this.doWork(job);
+            return;
             //
         }
-        else if (groupId && priority) {
+        if (!queueInstance)
+            throw new Error(`missing queue: ${jobConfig?.queue?.toString() || 'N/A'}`);
+        if (groupId && priority) {
             await queueInstance.add(jobType, jobData, {
                 delay,
+                jobId,
                 group: {
                     ...this.groupIdToGroupConfig(groupId),
                     priority: this.mapPriorityWordToPriorityNumber(priority),
@@ -504,6 +513,7 @@ export class Background {
         else {
             await queueInstance.add(jobType, jobData, {
                 delay,
+                jobId,
                 group: this.groupIdToGroupConfig(groupId),
                 priority: this.mapPriorityWordToPriorityNumber(priority),
                 // explicitly typing as JobsOptions because Psychic can't be aware of BullMQ Pro options

package/dist/esm/src/helpers/durationToSeconds.js

@@ -0,0 +1,6 @@
+export default function durationToSeconds(duration) {
+    return ((duration.seconds ? duration.seconds : 0) +
+        (duration.minutes ? duration.minutes * 60 : 0) +
+        (duration.hours ? duration.hours * 60 * 60 : 0) +
+        (duration.days ? duration.days * 60 * 60 * 24 : 0));
+}

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

@@ -1,5 +1,5 @@
 import { Dream } from '@rvoh/dream';
-import { BackgroundJobConfig } from '../types/background.js';
+import { BackgroundJobConfig, DelayedJobOpts } from '../types/background.js';
 import { FunctionPropertyNames } from '../types/utils.js';
 import { BackgroundableMethodArgs } from './BaseBackgroundedService.js';
 export default class BaseBackgroundedModel extends Dream {
@@ -64,7 +64,7 @@ export default class BaseBackgroundedModel extends Dream {
      * @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 PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delaySeconds: number, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    static backgroundWithDelay<T, MethodName extends PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, 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
@@ -114,7 +114,7 @@ export default class BaseBackgroundedModel extends Dream {
      * @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
      */
-    backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delaySeconds: number, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
 }
 export type PsychicBackgroundedModelStaticMethods<T extends typeof BaseBackgroundedModel> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedModel>>;
 export type PsychicBackgroundedServiceInstanceMethods<T extends BaseBackgroundedModel> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<BaseBackgroundedModel>>;

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

@@ -1,5 +1,5 @@
 import { Job } from 'bullmq';
-import { BackgroundJobConfig } from '../types/background.js';
+import { BackgroundJobConfig, DelayedJobOpts } from '../types/background.js';
 import { FunctionPropertyNames } from '../types/utils.js';
 export default class BaseBackgroundedService {
     /**
@@ -72,7 +72,7 @@ export default class BaseBackgroundedService {
      * @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, delaySeconds: number, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    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>;
     /**
      * 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

@@ -124,11 +124,12 @@ export declare class Background {
      * @param importKey - (optional) the import key for the class
      * @param jobConfig - (optional) the background job config to use when backgrounding this method
      */
-    staticMethod(ObjectClass: Record<'name', string>, method: string, { globalName, delaySeconds, args, jobConfig, }: {
+    staticMethod(ObjectClass: Record<'name', string>, method: string, { globalName, delaySeconds, jobId, args, jobConfig, }: {
         globalName: string;
         args?: any[];
         filepath?: string;
         delaySeconds?: number;
+        jobId?: string | undefined;
         importKey?: string;
         jobConfig?: BackgroundJobConfig<any>;
     }): Promise<void>;
@@ -162,17 +163,19 @@ export declare class Background {
      * @param importKey - (optional) the import key for the class
      * @param jobConfig - (optional) the background job config to use when backgrounding this method
      */
-    modelInstanceMethod(modelInstance: Dream, method: string, { delaySeconds, args, jobConfig, }: {
+    modelInstanceMethod(modelInstance: Dream, method: string, { delaySeconds, jobId, args, jobConfig, }: {
         delaySeconds?: number;
+        jobId?: string | undefined;
         importKey?: string;
         args?: any[];
         jobConfig?: BackgroundJobConfig<any>;
     }): Promise<void>;
-    _addToQueue(jobType: JobTypes, jobData: BackgroundJobData, { delaySeconds, jobConfig, priority, groupId, }: {
-        delaySeconds?: number;
+    _addToQueue(jobType: JobTypes, jobData: BackgroundJobData, { delaySeconds, jobId, jobConfig, priority, groupId, }: {
+        delaySeconds?: number | undefined;
+        jobId?: string | undefined;
         jobConfig: BackgroundJobConfig<any>;
         priority: BackgroundQueuePriority;
-        groupId?: string;
+        groupId?: string | undefined;
     }): Promise<void>;
     private jobConfigToPriority;
     private jobConfigToGroupId;

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

@@ -0,0 +1,2 @@
+import { DelayedJobDuration } from '../types/background.js';
+export default function durationToSeconds(duration: DelayedJobDuration): number;

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

@@ -103,7 +103,7 @@ export type QueueOptionsWithConnectionInstance = Omit<QueueOptions, 'connection'
      * queue and worker connections.
      */
     queueConnection?: RedisOrRedisClusterConnection;
-    workerConnection?: RedisOrRedisClusterConnection;
+    workerConnection?: RedisOrRedisClusterConnection | undefined;
 };
 export interface PsychicBackgroundSimpleOptions extends PsychicBackgroundSharedOptions {
     /**
@@ -114,7 +114,7 @@ export interface PsychicBackgroundSimpleOptions extends PsychicBackgroundSharedO
     /**
      * defaultWorkerConnection is only optional when workers will not be activated (e.g. on the webserver)
      */
-    defaultWorkerConnection?: RedisOrRedisClusterConnection;
+    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

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

@@ -30,6 +30,20 @@ export interface BackgroundJobData {
      */
     globalName?: string;
 }
+export type DelayedJobOpts = DelayedJobDuration & {
+    /**
+     * a unique identifier for your job. this identifier will be
+     * used to debounce, leveraging the internal throttling mechanisms
+     * provided by BullMQ
+     */
+    jobId?: string;
+};
+export interface DelayedJobDuration {
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+    days?: number;
+}
 export type JobTypes = 'BackgroundJobQueueFunctionJob' | 'BackgroundJobQueueStaticJob' | 'BackgroundJobQueueModelInstanceJob';
 export type BackgroundQueuePriority = 'default' | 'urgent' | 'not_urgent' | 'last';
 interface BaseBackgroundJobConfig {

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "author": "RVO Health",
   "repository": {
     "type": "git",