@rvoh/psychic-workers 0.3.0 → 0.3.1

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

@@ -3,13 +3,50 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const dream_1 = require("@rvoh/dream");
 const index_js_1 = require("./index.js");
 class BaseBackgroundedModel extends dream_1.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 index_js_1.default.staticMethod(safeThis, methodName, {
@@ -18,6 +55,27 @@ class BaseBackgroundedModel extends dream_1.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 index_js_1.default.staticMethod(safeThis, methodName, {
@@ -27,10 +85,35 @@ class BaseBackgroundedModel extends dream_1.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 index_js_1.default.modelInstanceMethod(safeThis, methodName, {
@@ -38,6 +121,28 @@ class BaseBackgroundedModel extends dream_1.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 index_js_1.default.modelInstanceMethod(safeThis, methodName, {

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

@@ -3,18 +3,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const dream_1 = require("@rvoh/dream");
 const index_js_1 = require("./index.js");
 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 dream_1.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 index_js_1.default.staticMethod(safeThis, methodName, {
@@ -23,6 +67,27 @@ 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 index_js_1.default.staticMethod(safeThis, methodName, {
@@ -32,6 +97,12 @@ 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/cjs/src/background/BaseScheduledService.js

@@ -3,18 +3,63 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const dream_1 = require("@rvoh/dream");
 const index_js_1 = require("./index.js");
 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 dream_1.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 index_js_1.default.scheduledMethod(safeThis, pattern, methodName, {
@@ -23,6 +68,12 @@ 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/cjs/src/background/helpers/nameToRedisQueueName.js

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