@rvoh/psychic-workers 0.3.0 → 0.3.2

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

@@ -1,18 +1,62 @@
 import { GlobalNameNotSet } from '@rvoh/dream';
 import background from './index.js';
 export default class BaseBackgroundedService {
+    /**
+     * A getter meant to be overridden in child classes. This does
+     * not have to be explicitly provided, but if so, it would allow
+     * you to override the default behavior of anything backgrounded
+     * by this service, such as the priority or workstream.
+     *
+     * @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.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() {
         return {};
     }
+    /**
+     * @internal
+     *
+     * Returns a unique global name for the given service.
+     *
+     * @returns A string representing a unique key for this service
+     */
     static get globalName() {
         if (!this._globalName)
             throw new GlobalNameNotSet(this);
         return this._globalName;
     }
+    /**
+     * @internal
+     *
+     * Used by PsychicApplicationWorkers during the load process
+     * for services to assign unique global names to each service
+     * based on the file name of that model.
+     */
     static setGlobalName(globalName) {
         this._globalName = globalName;
     }
     static _globalName;
+    /**
+     * runs the specified method in a background queue, driven by BullMQ,
+     * sending in the provided args.
+     *
+     * ```ts
+     * await MyBackgroundableClass.background('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.
+     *
+     * 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 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 background(methodName, ...args) {
         const safeThis = this;
         return await background.staticMethod(safeThis, methodName, {
@@ -21,6 +65,27 @@ export default class BaseBackgroundedService {
             jobConfig: safeThis.backgroundJobConfig,
         });
     }
+    /**
+     * 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.
+     *
+     * ```ts
+     * await MyBackgroundableClass.backgroundWithDelay('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.
+     *
+     * NOTE: in test environments, psychic will immediately invoke the underlying
+     * method, preventing you from needing to explicitly wait for queues to flush
+     * before making assertions.
+     *
+     * @param delaySeconds - the amount of time (in seconds) you want to hold off before allowing the job to run
+     * @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) {
         const safeThis = this;
         return await background.staticMethod(safeThis, methodName, {
@@ -30,6 +95,12 @@ export default class BaseBackgroundedService {
             jobConfig: safeThis.backgroundJobConfig,
         });
     }
+    /**
+     * types composed by psychic must be provided, since psychic-workers leverages
+     * the sync command in psychic to read your backgroundable services and extract
+     * metadata, which can be used to help provide types for the underlying methods
+     * in psychic-workers.
+     */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     get psychicTypes() {
         throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');

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

@@ -1,18 +1,63 @@
 import { GlobalNameNotSet } from '@rvoh/dream';
 import background from './index.js';
 export default class BaseScheduledService {
+    /**
+     * A getter meant to be overridden in child classes. This does
+     * not have to be explicitly provided, but if so, it would allow
+     * you to override the default behavior of anything backgrounded
+     * by this service, such as the priority or workstream.
+     *
+     * @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.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() {
         return {};
     }
+    /**
+     * @internal
+     *
+     * Returns a unique global name for the given service.
+     *
+     * @returns A string representing a unique key for this service
+     */
     static get globalName() {
         if (!this._globalName)
             throw new GlobalNameNotSet(this);
         return this._globalName;
     }
+    /**
+     * @internal
+     *
+     * Used by PsychicApplicationWorkers during the load process
+     * for services to assign unique global names to each service
+     * based on the file name of that model.
+     */
     static setGlobalName(globalName) {
         this._globalName = globalName;
     }
     static _globalName;
+    /**
+     * Schedules a job to be run repeatedly at a certain cron interval
+     * sending in the provided args.
+     *
+     * ```ts
+     * await MySchedulableClass.schedule('0 * * * *', 'myHourlyMethod', '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.
+     *
+     * 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 pattern - A cron string representing the time interval you wish this to run on
+     * @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 schedule(pattern, methodName, ...args) {
         const safeThis = this;
         return await background.scheduledMethod(safeThis, pattern, methodName, {
@@ -21,6 +66,12 @@ export default class BaseScheduledService {
             jobConfig: safeThis.backgroundJobConfig,
         });
     }
+    /**
+     * types composed by psychic must be provided, since psychic-workers leverages
+     * the sync command in psychic to read your backgroundable services and extract
+     * metadata, which can be used to help provide types for the underlying methods
+     * in psychic-workers.
+     */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     get psychicTypes() {
         throw new Error('Must define psychicTypes getter in BackgroundedService class within your application');

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

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

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

@@ -1,87 +1,100 @@
 import { closeAllDbConnections, compact, pascalize } from '@rvoh/dream';
 import { PsychicApp } from '@rvoh/psychic';
 import { Job, Queue, Worker } from 'bullmq';
-import { Cluster } from 'ioredis';
+import ActivatingBackgroundWorkersWithoutDefaultWorkerConnection from '../error/background/ActivatingBackgroundWorkersWithoutDefaultWorkerConnection.js';
+import ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection from '../error/background/ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection.js';
+import DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection from '../error/background/DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection.js';
+import NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection from '../error/background/NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection.js';
 import NoQueueForSpecifiedQueueName from '../error/background/NoQueueForSpecifiedQueueName.js';
 import NoQueueForSpecifiedWorkstream from '../error/background/NoQueueForSpecifiedWorkstream.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import PsychicAppWorkers from '../psychic-app-workers/index.js';
-class DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection extends Error {
-    get message() {
-        return `
-Native BullMQ options don't include a default queue connection, and the
-default config does not include a queue connection
-`;
-    }
-}
-class NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection extends Error {
-    queueName;
-    constructor(queueName) {
-        super();
-        this.queueName = queueName;
-    }
-    get message() {
-        return `
-Native BullMQ options don't include a default queue connection, and the
-${this.queueName} queue does not include a queue connection
-`;
-    }
-}
-class ActivatingBackgroundWorkersWithoutDefaultWorkerConnection extends Error {
-    get message() {
-        return `
-defaultWorkerConnection is required when activating workers. For example,
-it may be omitted on webserver instances, but is required on worker instances.
-`;
-    }
-}
-class ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection extends Error {
-    queueName;
-    constructor(queueName) {
-        super();
-        this.queueName = queueName;
-    }
-    get message() {
-        return `
-defaultWorkerConnection is missing, and the ${this.queueName} queue does not
-specify a workerConnection. A worker connection isrequired when activating workers.
-For example, it may be omitted on webserver instances, but is required on worker instances.
-`;
-    }
-}
+import nameToRedisQueueName from './helpers/nameToRedisQueueName.js';
+/**
+ * the underlying class driving the `background` singleton,
+ * available as an import from `psychic-workers`.
+ */
 export class Background {
+    /**
+     * returns the default queue name for your app
+     */
     static get defaultQueueName() {
         const psychicWorkersApp = PsychicAppWorkers.getOrFail();
         return `${pascalize(psychicWorkersApp.psychicApp.appName)}BackgroundJobQueue`;
     }
+    /**
+     * @internal
+     *
+     * returns the provided Worker class, or the Worker class from BullMQ
+     * if no override was provided. This is providable because BullMQ also
+     * offers a pro version, which requires you to provide custom classes.
+     */
     static get Worker() {
         const psychicWorkersApp = PsychicAppWorkers.getOrFail();
         return (psychicWorkersApp.backgroundOptions.providers?.Worker || Worker);
     }
+    /**
+     * @internal
+     *
+     * returns the provided Queue class, or the Queue class from BullMQ
+     * if no override was provided. This is providable because BullMQ also
+     * offers a pro version, which requires you to provide custom classes.
+     */
     static get Queue() {
         const psychicWorkersApp = PsychicAppWorkers.getOrFail();
         return (psychicWorkersApp.backgroundOptions.providers?.Queue || Queue);
     }
     /**
+     * @internal
+     *
      * Used when adding jobs to the default queue
      */
     defaultQueue = null;
     /**
+     * @internal
+     *
      * Used when adding jobs to the default transitional queue
      */
     defaultTransitionalQueue = null;
     /**
+     * @internal
+     *
      * Used when adding jobs to a named queue
      */
     namedQueues = {};
+    /**
+     * @internal
+     *
+     * Used when adding grouped jobs
+     */
     groupNames = {};
+    /**
+     * @internal
+     *
+     * Used when adding workstreams
+     */
     workstreamNames = [];
     /**
+     * @internal
+     *
      * Used when adding jobs to a named transitioanl queue
      */
     namedTransitionalQueues = {};
+    /**
+     * @internal
+     *
+     * All of the workers that are currently registered
+     */
     _workers = [];
+    /**
+     * @internal
+     *
+     * All of the redis connections that are currently registered
+     */
     redisConnections = [];
+    /**
+     * Establishes connection to BullMQ via redis
+     */
     connect({ activateWorkers = false, } = {}) {
         if (this.defaultQueue)
             return;
@@ -94,6 +107,9 @@ export class Background {
             this.simpleConnect(defaultBullMQQueueOptions, psychicWorkersApp.backgroundOptions, { activateWorkers });
         }
     }
+    /**
+     * Returns all the queues in your application
+     */
     get queues() {
         return compact([
             this.defaultQueue,
@@ -102,6 +118,9 @@ export class Background {
             ...Object.values(this.namedTransitionalQueues).map(queue => queue),
         ]);
     }
+    /**
+     * Returns all the workers in your application
+     */
     get workers() {
         return [...this._workers];
     }
@@ -109,6 +128,9 @@ export class Background {
         await this.shutdown();
         process.exit();
     }
+    /**
+     * Shuts down workers, closes all redis connections
+     */
     async shutdown() {
         await Promise.all(this._workers.map(worker => worker.close()));
         const psychicWorkersApp = PsychicAppWorkers.getOrFail();
@@ -118,6 +140,9 @@ export class Background {
         await closeAllDbConnections();
         await this.closeAllRedisConnections();
     }
+    /**
+     * closes all redis connections for workers and queues
+     */
     async closeAllRedisConnections() {
         for (const queue of this.queues) {
             await queue.close();
@@ -134,6 +159,11 @@ export class Background {
             }
         }
     }
+    /**
+     * @internal
+     *
+     * connects to BullMQ using workstream-based arguments
+     */
     simpleConnect(defaultBullMQQueueOptions, backgroundOptions, { activateWorkers = false, activatingTransitionalWorkstreams = false, }) {
         const defaultQueueConnection = backgroundOptions.defaultQueueConnection;
         const defaultWorkerConnection = backgroundOptions.defaultWorkerConnection;
@@ -239,6 +269,11 @@ export class Background {
             });
         }
     }
+    /**
+     * @internal
+     *
+     * connects to BullMQ using native BullMQ arguments
+     */
     nativeBullMQConnect(defaultBullMQQueueOptions, backgroundOptions, { activateWorkers = false, }) {
         const nativeBullMQ = backgroundOptions.nativeBullMQ;
         const defaultQueueConnection = nativeBullMQ.defaultQueueOptions?.queueConnection || backgroundOptions.defaultQueueConnection;
@@ -283,6 +318,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);
@@ -305,7 +341,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)
@@ -325,16 +361,34 @@ export class Background {
         // end: create named queues //
         //////////////////////////////
     }
+    /**
+     * starts background workers
+     */
     work() {
         this.connect({ activateWorkers: true });
         process.on('SIGTERM', () => {
-            void this.shutdownAndExit();
+            void this.shutdownAndExit()
+                .then(() => { })
+                .catch(() => { });
         });
         process.on('SIGINT', () => {
-            void this.shutdownAndExit();
+            void this.shutdownAndExit()
+                .then(() => { })
+                .catch(() => { });
         });
     }
-    async staticMethod(ObjectClass, method, { delaySeconds, globalName, args = [], jobConfig = {}, }) {
+    /**
+     * adds the static method of a provided class to BullMQ
+     *
+     * @param ObjectClass - the class you wish to background
+     * @param method - the method you wish to background
+     * @param globalName - the globalName of the class you are processing
+     * @param args - (optional) a list of arguments to provide to your method when it is called
+     * @param delaySeconds - (optional) the number of seconds you wish to wait before allowing this job to process
+     * @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 = {}, }) {
         this.connect();
         await this._addToQueue(`BackgroundJobQueueStaticJob`, {
             globalName,
@@ -342,11 +396,23 @@ export class Background {
             args,
         }, {
             delaySeconds,
-            jobConfig: jobConfig,
+            jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
         });
     }
+    /**
+     * adds the static method of a provided class to BullMQ,
+     * to be scheduled to run at a specified cron pattern
+     *
+     * @param ObjectClass - the class you wish to background
+     * @param pattern - the cron string you wish to use to govern the scheduling for this job
+     * @param method - the method you wish to background
+     * @param globalName - the globalName of the class you are processing
+     * @param args - (optional) a list of arguments to provide to your method when it is called
+     * @param importKey - (optional) the import key for the class
+     * @param jobConfig - (optional) the background job config to use when backgrounding this method
+     */
     async scheduledMethod(ObjectClass, pattern, method, { globalName, args = [], jobConfig = {}, }) {
         this.connect();
         // `jobId` is used to determine uniqueness along with name and repeat pattern.
@@ -356,7 +422,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,
@@ -389,6 +458,16 @@ export class Background {
         }
         return queueInstance;
     }
+    /**
+     * adds the instance method of a provided dream model to BullMQ
+     *
+     * @param modelInstance - the dream model instance you wish to background
+     * @param method - the method you wish to background
+     * @param globalName - the globalName of the class you are processing
+     * @param args - (optional) a list of arguments to provide to your method when it is called
+     * @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 = {}, }) {
         this.connect();
         await this._addToQueue('BackgroundJobQueueModelInstanceJob', {
@@ -398,7 +477,7 @@ export class Background {
             args,
         }, {
             delaySeconds,
-            jobConfig: jobConfig,
+            jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
         });
@@ -413,9 +492,12 @@ export class Background {
             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,
                 group: {
@@ -516,9 +598,3 @@ export default background;
 export async function stopBackgroundWorkers() {
     await background.shutdown();
 }
-function nameToRedisQueueName(queueName, redis) {
-    queueName = queueName.replace(/\{|\}/g, '');
-    if (redis instanceof Cluster)
-        return `{${queueName}}`;
-    return queueName;
-}

package/dist/esm/src/error/background/ActivatingBackgroundWorkersWithoutDefaultWorkerConnection.js

@@ -0,0 +1,8 @@
+export default class ActivatingBackgroundWorkersWithoutDefaultWorkerConnection extends Error {
+    get message() {
+        return `
+defaultWorkerConnection is required when activating workers. For example,
+it may be omitted on webserver instances, but is required on worker instances.
+`;
+    }
+}

package/dist/esm/src/error/background/ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection.js

@@ -0,0 +1,14 @@
+export default class ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection extends Error {
+    queueName;
+    constructor(queueName) {
+        super();
+        this.queueName = queueName;
+    }
+    get message() {
+        return `
+defaultWorkerConnection is missing, and the ${this.queueName} queue does not
+specify a workerConnection. A worker connection isrequired when activating workers.
+For example, it may be omitted on webserver instances, but is required on worker instances.
+`;
+    }
+}

package/dist/esm/src/error/background/DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection.js

@@ -0,0 +1,8 @@
+export default class DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection extends Error {
+    get message() {
+        return `
+Native BullMQ options don't include a default queue connection, and the
+default config does not include a queue connection
+`;
+    }
+}

package/dist/esm/src/error/background/NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection.js

@@ -0,0 +1,13 @@
+export default class NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection extends Error {
+    queueName;
+    constructor(queueName) {
+        super();
+        this.queueName = queueName;
+    }
+    get message() {
+        return `
+Native BullMQ options don't include a default queue connection, and the
+${this.queueName} queue does not include a queue connection
+`;
+    }
+}

package/dist/esm/src/index.js

@@ -1,4 +1,4 @@
-export { default as background, Background, stopBackgroundWorkers, } from './background/index.js';
+export { default as background, Background, stopBackgroundWorkers } from './background/index.js';
 export { default as BaseBackgroundedModel } from './background/BaseBackgroundedModel.js';
 export { default as BaseBackgroundedService } from './background/BaseBackgroundedService.js';
 export { default as BaseScheduledService } from './background/BaseScheduledService.js';

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

@@ -1,6 +1,6 @@
 import { Queue, Worker } from 'bullmq';
-import background from '../background/index.js';
 import { cachePsychicWorkersApp, getCachedPsychicWorkersAppOrFail } from './cache.js';
+import background from '../background/index.js';
 export default class PsychicAppWorkers {
     static async init(psychicApp, cb) {
         const psychicWorkersApp = new PsychicAppWorkers(psychicApp);

package/dist/esm/src/types/utils.js

@@ -0,0 +1 @@
+export {};