@rvoh/psychic-workers 2.6.0 → 2.8.0

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

@@ -12,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() {
@@ -57,16 +57,22 @@ 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
@@ -74,7 +80,7 @@ export default class BaseBackgroundedModel extends Dream {
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
-     * @param delaySeconds - the amount of time (in seconds) you want to hold off before allowing the job to run
+     * @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
      */
@@ -94,19 +100,25 @@ export default class BaseBackgroundedModel extends Dream {
      * 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 the job was put in the queue, not that it has
-     * completed.
+     * 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) the amount of time you want to hold off before allowing the job to run, and an optional `jobId` which debounces repeated calls within the delay window
+     * @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
@@ -146,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) {
@@ -158,17 +170,23 @@ 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
@@ -176,8 +194,8 @@ export default class BaseBackgroundedModel extends Dream {
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
-     * @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 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) {
@@ -195,20 +213,26 @@ export default class BaseBackgroundedModel extends Dream {
      * 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 the job was put in the queue, not that it has
-     * completed.
+     * 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) the amount of time you want to hold off before allowing the job to run, and an optional `jobId` which debounces repeated calls within the delay window
+     * @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

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,16 +68,22 @@ 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
@@ -85,7 +91,7 @@ export default class BaseBackgroundedService {
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
-     * @param delaySeconds - the amount of time (in seconds) you want to hold off before allowing the job to run
+     * @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
      */
@@ -105,6 +111,13 @@ export default class BaseBackgroundedService {
      * 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' },
@@ -114,15 +127,14 @@ export default class BaseBackgroundedService {
      * )
      * ```
      * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * 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) the amount of time you want to hold off before allowing the job to run, and an optional `jobId` which debounces repeated calls within the delay window
+     * @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

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() {