@rvoh/psychic-workers 0.3.0 → 0.3.2

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

@@ -5,87 +5,100 @@ exports.stopBackgroundWorkers = stopBackgroundWorkers;
 const dream_1 = require("@rvoh/dream");
 const psychic_1 = require("@rvoh/psychic");
 const bullmq_1 = require("bullmq");
-const ioredis_1 = require("ioredis");
+const ActivatingBackgroundWorkersWithoutDefaultWorkerConnection_js_1 = require("../error/background/ActivatingBackgroundWorkersWithoutDefaultWorkerConnection.js");
+const ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection_js_1 = require("../error/background/ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection.js");
+const DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection_js_1 = require("../error/background/DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection.js");
+const NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection_js_1 = require("../error/background/NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection.js");
 const NoQueueForSpecifiedQueueName_js_1 = require("../error/background/NoQueueForSpecifiedQueueName.js");
 const NoQueueForSpecifiedWorkstream_js_1 = require("../error/background/NoQueueForSpecifiedWorkstream.js");
 const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
 const index_js_1 = require("../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.
-`;
-    }
-}
+const nameToRedisQueueName_js_1 = require("./helpers/nameToRedisQueueName.js");
+/**
+ * the underlying class driving the `background` singleton,
+ * available as an import from `psychic-workers`.
+ */
 class Background {
+    /**
+     * returns the default queue name for your app
+     */
     static get defaultQueueName() {
         const psychicWorkersApp = index_js_1.default.getOrFail();
         return `${(0, dream_1.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 = index_js_1.default.getOrFail();
         return (psychicWorkersApp.backgroundOptions.providers?.Worker || bullmq_1.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 = index_js_1.default.getOrFail();
         return (psychicWorkersApp.backgroundOptions.providers?.Queue || bullmq_1.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;
@@ -98,6 +111,9 @@ class Background {
             this.simpleConnect(defaultBullMQQueueOptions, psychicWorkersApp.backgroundOptions, { activateWorkers });
         }
     }
+    /**
+     * Returns all the queues in your application
+     */
     get queues() {
         return (0, dream_1.compact)([
             this.defaultQueue,
@@ -106,6 +122,9 @@ class Background {
             ...Object.values(this.namedTransitionalQueues).map(queue => queue),
         ]);
     }
+    /**
+     * Returns all the workers in your application
+     */
     get workers() {
         return [...this._workers];
     }
@@ -113,6 +132,9 @@ 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 = index_js_1.default.getOrFail();
@@ -122,6 +144,9 @@ class Background {
         await (0, dream_1.closeAllDbConnections)();
         await this.closeAllRedisConnections();
     }
+    /**
+     * closes all redis connections for workers and queues
+     */
     async closeAllRedisConnections() {
         for (const queue of this.queues) {
             await queue.close();
@@ -138,6 +163,11 @@ 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;
@@ -148,7 +178,7 @@ class Background {
         // transitional queues must have the same names they had prior to making them
         // transitional since the name is what identifies the queues and enables the
         // queues to be worked off
-        const formattedQueueName = nameToRedisQueueName(Background.defaultQueueName, defaultQueueConnection);
+        const formattedQueueName = (0, nameToRedisQueueName_js_1.default)(Background.defaultQueueName, defaultQueueConnection);
         ///////////////////////////////
         // create default workstream //
         ///////////////////////////////
@@ -170,7 +200,7 @@ class Background {
         /////////////////////////////
         if (activateWorkers) {
             if (!defaultWorkerConnection)
-                throw new ActivatingBackgroundWorkersWithoutDefaultWorkerConnection();
+                throw new ActivatingBackgroundWorkersWithoutDefaultWorkerConnection_js_1.default();
             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), {
@@ -196,7 +226,7 @@ class Background {
             // transitional queues must have the same names they had prior to making them
             // transitional since the name is what identifies the queues and enables the
             // queues to be worked off
-            const namedWorkstreamFormattedQueueName = nameToRedisQueueName(namedWorkstream.name, namedWorkstreamQueueConnection);
+            const namedWorkstreamFormattedQueueName = (0, nameToRedisQueueName_js_1.default)(namedWorkstream.name, namedWorkstreamQueueConnection);
             const namedQueue = new Background.Queue(namedWorkstreamFormattedQueueName, {
                 ...defaultBullMQQueueOptions,
                 connection: namedWorkstreamQueueConnection,
@@ -213,7 +243,7 @@ class Background {
             //////////////////////////
             if (activateWorkers) {
                 if (!namedWorkstreamWorkerConnection)
-                    throw new ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection(namedWorkstream.name);
+                    throw new ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection_js_1.default(namedWorkstream.name);
                 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), {
@@ -243,6 +273,11 @@ 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;
@@ -252,8 +287,8 @@ class Background {
         if (defaultWorkerConnection)
             this.redisConnections.push(defaultWorkerConnection);
         if (!defaultQueueConnection)
-            throw new DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection();
-        const formattedQueueName = nameToRedisQueueName(Background.defaultQueueName, defaultQueueConnection);
+            throw new DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection_js_1.default();
+        const formattedQueueName = (0, nameToRedisQueueName_js_1.default)(Background.defaultQueueName, defaultQueueConnection);
         //////////////////////////
         // create default queue //
         //////////////////////////
@@ -270,7 +305,7 @@ class Background {
         /////////////////////////////
         if (activateWorkers) {
             if (!defaultWorkerConnection)
-                throw new ActivatingBackgroundWorkersWithoutDefaultWorkerConnection();
+                throw new ActivatingBackgroundWorkersWithoutDefaultWorkerConnection_js_1.default();
             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), {
@@ -287,6 +322,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);
@@ -295,8 +331,8 @@ class Background {
             const namedQueueConnection = namedQueueOptions.queueConnection || defaultQueueConnection;
             const namedWorkerConnection = namedQueueOptions.workerConnection || defaultWorkerConnection;
             if (!namedQueueConnection)
-                throw new NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection(queueName);
-            const formattedQueuename = nameToRedisQueueName(queueName, namedQueueConnection);
+                throw new NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection_js_1.default(queueName);
+            const formattedQueuename = (0, nameToRedisQueueName_js_1.default)(queueName, namedQueueConnection);
             this.namedQueues[queueName] = new Background.Queue(formattedQueuename, {
                 ...defaultBullMQQueueOptions,
                 ...namedQueueOptions,
@@ -309,11 +345,11 @@ 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)
-                    throw new ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection(queueName);
+                    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), {
                         ...extraWorkerOptions,
@@ -329,16 +365,34 @@ 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,
@@ -346,11 +400,23 @@ 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.
@@ -360,7 +426,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,
@@ -393,6 +462,16 @@ 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', {
@@ -402,7 +481,7 @@ class Background {
             args,
         }, {
             delaySeconds,
-            jobConfig: jobConfig,
+            jobConfig,
             groupId: this.jobConfigToGroupId(jobConfig),
             priority: this.jobConfigToPriority(jobConfig),
         });
@@ -417,9 +496,12 @@ class Background {
             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,
                 group: {
@@ -521,9 +603,3 @@ exports.default = background;
 async function stopBackgroundWorkers() {
     await background.shutdown();
 }
-function nameToRedisQueueName(queueName, redis) {
-    queueName = queueName.replace(/\{|\}/g, '');
-    if (redis instanceof ioredis_1.Cluster)
-        return `{${queueName}}`;
-    return queueName;
-}

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

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+`;
+    }
+}
+exports.default = ActivatingBackgroundWorkersWithoutDefaultWorkerConnection;

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+`;
+    }
+}
+exports.default = ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection;

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

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+`;
+    }
+}
+exports.default = DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection;

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+`;
+    }
+}
+exports.default = NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection;

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

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const bullmq_1 = require("bullmq");
-const index_js_1 = require("../background/index.js");
 const cache_js_1 = require("./cache.js");
+const index_js_1 = require("../background/index.js");
 class PsychicAppWorkers {
     static async init(psychicApp, cb) {
         const psychicWorkersApp = new PsychicAppWorkers(psychicApp);

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

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,13 +1,50 @@
 import { Dream } from '@rvoh/dream';
 import background from './index.js';
 export default class BaseBackgroundedModel extends Dream {
+    /**
+     * 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
+     *
+     * shadows the static `backgroundJobConfig` getter provided by the user.
+     * This should never be overridden, and is meant to provide easy access
+     * to the config from within an instance.
+     */
     get backgroundJobConfig() {
         const klass = this.constructor;
         return klass.backgroundJobConfig;
     }
+    /**
+     * runs the specified method in a background queue, driven by BullMQ,
+     * sending in the provided args.
+     *
+     * ```ts
+     * await User.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, {
@@ -16,6 +53,27 @@ export default class BaseBackgroundedModel extends Dream {
             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 User.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, {
@@ -25,10 +83,35 @@ export default class BaseBackgroundedModel extends Dream {
             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');
     }
+    /**
+     * runs the specified method in a background queue, driven by BullMQ,
+     * sending in the provided args.
+     *
+     * ```ts
+     * const user = await User.lastOrFail()
+     * await user.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
+     */
     async background(methodName, ...args) {
         const safeThis = this;
         return await background.modelInstanceMethod(safeThis, methodName, {
@@ -36,6 +119,28 @@ export default class BaseBackgroundedModel extends Dream {
             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
+     * const user = await User.lastOrFail()
+     * await user.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
+     */
     async backgroundWithDelay(delaySeconds, methodName, ...args) {
         const safeThis = this;
         return await background.modelInstanceMethod(safeThis, methodName, {