@rvoh/psychic-workers 2.4.1 → 2.7.0

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

@@ -1,4 +1,5 @@
 import { Dream } from '@rvoh/dream';
+import { mergeBackgroundWithOptsIntoJobConfig } from './BaseBackgroundedService.js';
 import background from './index.js';
 import durationToSeconds from '../helpers/durationToSeconds.js';
 export default class BaseBackgroundedModel extends Dream {
@@ -11,7 +12,7 @@ export default class BaseBackgroundedModel extends Dream {
      * @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.queue - the name 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() {
@@ -56,22 +57,30 @@ export default class BaseBackgroundedModel extends Dream {
     }
     /**
      * 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.
+     * sending in the provided args, along with a delay object — one or more of
+     * `{ seconds, minutes, hours, days }` — which holds the job off for that much
+     * time after it is entered into the queue.
+     *
+     * The delay object also accepts an optional `jobId`, which turns the delay
+     * into a **debounce**: repeated calls carrying the same `jobId` collapse into
+     * a single execution, which runs once the delay has elapsed without another
+     * call arriving. `jobId` is a deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
      *
      * ```ts
-     * await User.backgroundWithDelay('myMethod', 'abc', 123)
+     * await User.backgroundWithDelay({ minutes: 5 }, '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.
+     * though calling backgroundWithDelay must be awaited, the resolution of the promise
+     * is an indication that a run is pending, 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
+     * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
+     *
+     * @param delay - how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single 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
      */
@@ -85,6 +94,44 @@ 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, along with an options object which can
+     * be used to delay the job and/or override the priority provided by
+     * the `backgroundJobConfig` getter on this model.
+     *
+     * Adding a `jobId` to the delay turns it into a **debounce**: repeated calls
+     * carrying the same `jobId` collapse into a single execution, which runs once
+     * the delay has elapsed without another call arriving. `jobId` is a
+     * deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
+     *
+     * ```ts
+     * await User.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
+     * ```
+     * though calling backgroundWith must be awaited, the resolution of the promise
+     * is an indication that a run is pending, 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 opts - options for backgrounding this job
+     * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
+     * @param opts.priority - (optional) a priority which, when provided, overrides the priority provided by `backgroundJobConfig`
+     * @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 backgroundWith(opts, methodName, ...args) {
+        const safeThis = this;
+        return await background.staticMethod(safeThis, methodName, {
+            globalName: safeThis.globalName,
+            ...(opts.delay ? { delaySeconds: durationToSeconds(opts.delay), jobId: opts.delay.jobId } : {}),
+            args,
+            jobConfig: mergeBackgroundWithOptsIntoJobConfig(safeThis.backgroundJobConfig, opts),
+        });
+    }
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract
@@ -111,7 +158,7 @@ export default class BaseBackgroundedModel extends Dream {
      * 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 methodName - the name of the instance 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) {
@@ -123,24 +170,32 @@ export default class BaseBackgroundedModel extends Dream {
     }
     /**
      * 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.
+     * sending in the provided args, along with a delay object — one or more of
+     * `{ seconds, minutes, hours, days }` — which holds the job off for that much
+     * time after it is entered into the queue.
+     *
+     * The delay object also accepts an optional `jobId`, which turns the delay
+     * into a **debounce**: repeated calls carrying the same `jobId` collapse into
+     * a single execution, which runs once the delay has elapsed without another
+     * call arriving. `jobId` is a deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
      *
      * ```ts
      * const user = await User.lastOrFail()
-     * await user.backgroundWithDelay('myMethod', 'abc', 123)
+     * await user.backgroundWithDelay({ minutes: 5 }, '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.
+     * though calling backgroundWithDelay must be awaited, the resolution of the promise
+     * is an indication that a run is pending, 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
+     * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
+     *
+     * @param delay - how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
+     * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
      */
     async backgroundWithDelay(delay, methodName, ...args) {
@@ -152,4 +207,42 @@ 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, along with an options object which can
+     * be used to delay the job and/or override the priority provided by
+     * the `backgroundJobConfig` getter on this model.
+     *
+     * Adding a `jobId` to the delay turns it into a **debounce**: repeated calls
+     * carrying the same `jobId` collapse into a single execution, which runs once
+     * the delay has elapsed without another call arriving. `jobId` is a
+     * deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
+     *
+     * ```ts
+     * const user = await User.lastOrFail()
+     * await user.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
+     * ```
+     * though calling backgroundWith must be awaited, the resolution of the promise
+     * is an indication that a run is pending, 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 opts - options for backgrounding this job
+     * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
+     * @param opts.priority - (optional) a priority which, when provided, overrides the priority provided by `backgroundJobConfig`
+     * @param methodName - the name of the instance method you wish to run in the background
+     * @param args - a variadic list of arguments to be sent to your method
+     */
+    async backgroundWith(opts, methodName, ...args) {
+        const safeThis = this;
+        return await background.modelInstanceMethod(safeThis, methodName, {
+            args,
+            ...(opts.delay ? { delaySeconds: durationToSeconds(opts.delay), jobId: opts.delay.jobId } : {}),
+            jobConfig: mergeBackgroundWithOptsIntoJobConfig(safeThis.backgroundJobConfig, opts),
+        });
+    }
 }

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

@@ -11,7 +11,7 @@ export default class BaseBackgroundedService {
      * @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.queue - the name 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() {
@@ -68,22 +68,30 @@ export default class BaseBackgroundedService {
     }
     /**
      * 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.
+     * sending in the provided args, along with a delay object — one or more of
+     * `{ seconds, minutes, hours, days }` — which holds the job off for that much
+     * time after it is entered into the queue.
+     *
+     * The delay object also accepts an optional `jobId`, which turns the delay
+     * into a **debounce**: repeated calls carrying the same `jobId` collapse into
+     * a single execution, which runs once the delay has elapsed without another
+     * call arriving. `jobId` is a deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
      *
      * ```ts
-     * await MyBackgroundableClass.backgroundWithDelay('myMethod', 'abc', 123)
+     * await MyBackgroundableClass.backgroundWithDelay({ minutes: 5 }, '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.
+     * though calling backgroundWithDelay must be awaited, the resolution of the promise
+     * is an indication that a run is pending, 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
+     * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
+     *
+     * @param delay - how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single 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
      */
@@ -97,6 +105,49 @@ export default class BaseBackgroundedService {
             jobConfig: safeThis.backgroundJobConfig,
         });
     }
+    /**
+     * runs the specified method in a background queue, driven by BullMQ,
+     * sending in the provided args, along with an options object which can
+     * be used to delay the job and/or override the priority provided by
+     * the `backgroundJobConfig` getter on this service.
+     *
+     * Adding a `jobId` to the delay turns it into a **debounce**: repeated calls
+     * carrying the same `jobId` collapse into a single execution, which runs once
+     * the delay has elapsed without another call arriving. `jobId` is a
+     * deduplication key rather than a BullMQ job id.
+     *
+     * See {@link DelayedJobOpts.jobId}.
+     *
+     * ```ts
+     * await MyBackgroundableClass.backgroundWith(
+     *   { delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' },
+     *   'myMethod',
+     *   'abc',
+     *   123,
+     * )
+     * ```
+     * though calling backgroundWith must be awaited, the resolution of the promise
+     * is an indication that a run is pending, 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 opts - options for backgrounding this job
+     * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
+     * @param opts.priority - (optional) a priority which, when provided, overrides the priority provided by `backgroundJobConfig`
+     * @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 backgroundWith(opts, methodName, ...args) {
+        const safeThis = this;
+        return await background.staticMethod(safeThis, methodName, {
+            globalName: safeThis.globalName,
+            ...(opts.delay ? { delaySeconds: durationToSeconds(opts.delay), jobId: opts.delay.jobId } : {}),
+            args,
+            jobConfig: mergeBackgroundWithOptsIntoJobConfig(safeThis.backgroundJobConfig, opts),
+        });
+    }
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract
@@ -108,3 +159,16 @@ export default class BaseBackgroundedService {
         throw new Error('Must define psychicWorkerTypes getter in ApplicationBackgroundedService class within your application');
     }
 }
+/**
+ * @internal
+ *
+ * returns a copy of the provided job config, with the priority
+ * replaced by the priority found in the `backgroundWith` opts,
+ * if one was provided.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mergeBackgroundWithOptsIntoJobConfig(jobConfig, opts) {
+    if (!opts.priority)
+        return jobConfig;
+    return { ...jobConfig, priority: opts.priority };
+}

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

@@ -10,7 +10,7 @@ export default class BaseScheduledService {
      * @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.queue - the name 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() {
@@ -66,6 +66,64 @@ export default class BaseScheduledService {
             jobConfig: safeThis.backgroundJobConfig,
         });
     }
+    /**
+     * Returns the id that `schedule` registers a job under, which can be passed
+     * to {@link BaseScheduledService.unschedule} to remove that job.
+     *
+     * The id is derived from the service's global name and the method name. It
+     * performs no queue construction and no redis I/O, so it is safe to call
+     * anywhere, including from a console in development.
+     *
+     * The intended workflow for deleting a scheduled service is to read the id
+     * off the class before removing it:
+     *
+     * ```ts
+     * MyScheduledService.unscheduleId('myHourlyMethod')
+     * // => 'services/MyScheduledService:myHourlyMethod'
+     * ```
+     *
+     * then check that string into a seed or migration and call `unschedule` with
+     * it, which allows the class itself to be deleted in the same deploy.
+     *
+     * ```ts
+     * await ApplicationScheduledService.unschedule('services/MyScheduledService:myHourlyMethod')
+     * ```
+     *
+     * @param methodName - the name of the static method that was scheduled
+     * @returns the id `schedule` registered this method under
+     */
+    static unscheduleId(methodName) {
+        const safeThis = this;
+        return background.jobSchedulerId(safeThis.globalName, methodName);
+    }
+    /**
+     * Removes a scheduled job, preventing it from being run again.
+     *
+     * ```ts
+     * await MyScheduledService.unschedule(MyScheduledService.unscheduleId('myHourlyMethod'))
+     * ```
+     *
+     * Since the id is just a string, it can also be checked into a seed or
+     * migration, which allows the scheduled service class to be deleted in the
+     * same deploy that stops its job:
+     *
+     * ```ts
+     * await ApplicationScheduledService.unschedule('services/MyScheduledService:myHourlyMethod')
+     * ```
+     *
+     * Every queue in your application is checked, so this finds the job whether
+     * or not the service's workstream has changed since it was scheduled, and
+     * whether it landed in a current or a transitional queue.
+     *
+     * NOTE: unscheduling stops future runs. It does not cancel a run that has
+     * already been placed on a queue, so a final invocation may still happen.
+     *
+     * @param id - the id the job was scheduled under, from {@link BaseScheduledService.unscheduleId}
+     * @returns true if a scheduled job was removed, false if none was found
+     */
+    static async unschedule(id) {
+        return await background.unschedule(id);
+    }
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract