@rvoh/psychic-workers 2.4.0 → 2.6.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 {
@@ -71,6 +72,8 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
@@ -85,6 +88,38 @@ 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.
+     *
+     * ```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.
+     *
+     * 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.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
@@ -139,6 +174,8 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
@@ -152,4 +189,36 @@ 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.
+     *
+     * ```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.
+     *
+     * 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.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

@@ -83,6 +83,8 @@ export default class BaseBackgroundedService {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
@@ -97,6 +99,43 @@ 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.
+     *
+     * ```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 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 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.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 +147,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

@@ -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

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

@@ -500,13 +500,7 @@ export class Background {
      */
     async scheduledMethod(ObjectClass, pattern, method, { globalName, args = [], jobConfig = {}, scheduleOpts = {}, }) {
         this.connect();
-        // `jobId` is used to determine uniqueness along with name and repeat pattern.
-        // Since the name is really a job type and never changes, the `jobId` is the only
-        // way to allow multiple jobs with the same cron repeat pattern. Uniqueness will
-        // now be enforced by combining class name, method name, and cron repeat pattern.
-        //
-        // See: https://docs.bullmq.io/guide/jobs/repeatable
-        const schedulerId = `${globalName}:${method}`;
+        const schedulerId = this.jobSchedulerId(globalName, method);
         const queueInstance = this.queueInstance(jobConfig);
         if (!queueInstance)
             throw new Error(`Missing queue for: ${jobConfig.queue?.toString()}`);
@@ -520,6 +514,40 @@ export class Background {
             },
         });
     }
+    /**
+     * @internal
+     *
+     * Returns the id a scheduled job is registered with BullMQ under.
+     *
+     * `jobId` is used to determine uniqueness along with name and repeat pattern.
+     * Since the name is really a job type and never changes, the `jobId` is the only
+     * way to allow multiple jobs with the same cron repeat pattern. Uniqueness is
+     * enforced by combining the global name and the method name.
+     *
+     * See: https://docs.bullmq.io/guide/jobs/repeatable
+     *
+     * @param globalName - the globalName of the class the method belongs to
+     * @param method - the name of the scheduled method
+     */
+    jobSchedulerId(globalName, method) {
+        return `${globalName}:${method}`;
+    }
+    /**
+     * removes a scheduled job from BullMQ, preventing it from being run again
+     *
+     * Every queue is checked, rather than the one the job's current
+     * `backgroundJobConfig` routes to, so that a job can still be unscheduled
+     * after its workstream has changed, or after the class that scheduled it has
+     * been deleted.
+     *
+     * @param jobSchedulerId - the id the job was scheduled under
+     * @returns true if a scheduled job was removed, false if none was found
+     */
+    async unschedule(jobSchedulerId) {
+        this.connect();
+        const removed = await Promise.all(this.queues.map(queue => queue.removeJobScheduler(jobSchedulerId)));
+        return removed.some(Boolean);
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     queueInstance(values) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/cjs/src/test-utils/WorkerTestUtils.js

@@ -28,7 +28,7 @@ export default class WorkerTestUtils {
     static async work(opts = {}) {
         background.connect();
         const queues = background.queues;
-        let workWasDone = true;
+        let workWasDone;
         do {
             workWasDone = false;
             for (const queue of queues) {
@@ -62,9 +62,9 @@ export default class WorkerTestUtils {
     }
     /*
      * iterates through each registered queue, and cleans out all
-     * jobs, including completed, failed, and scheduled jobs. This
-     * is especially useful before a test where you plan to exercise
-     * background jobs manually.
+     * jobs, including waiting, paused, prioritized, delayed, completed,
+     * failed, and scheduled jobs. This is especially useful before a test
+     * where you plan to exercise background jobs manually.
      *
      * If your entire app is continuously exercising background jobs
      * manually, you may want to do this in your spec/setup/hooks.ts file,
@@ -79,8 +79,11 @@ export default class WorkerTestUtils {
     static async clean() {
         background.connect();
         for (const queue of background.queues) {
-            // clears all non-scheduled, non-completed, and non-failed jobs
-            await queue.drain();
+            // clears waiting, paused, and prioritized jobs, as well as delayed jobs
+            // (i.e. jobs which have failed and are awaiting a retry). Delayed jobs which
+            // belong to a job scheduler are intentionally left alone by BullMQ here, and
+            // are cleaned up below when their scheduler is removed.
+            await queue.drain(true);
             // clear out completed and failed jobs
             await queue.clean(0, 10000, 'completed');
             await queue.clean(0, 10000, 'failed');

package/dist/esm/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 {
@@ -71,6 +72,8 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
@@ -85,6 +88,38 @@ 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.
+     *
+     * ```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.
+     *
+     * 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.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
@@ -139,6 +174,8 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
@@ -152,4 +189,36 @@ 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.
+     *
+     * ```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.
+     *
+     * 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.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/esm/src/background/BaseBackgroundedService.js

@@ -83,6 +83,8 @@ export default class BaseBackgroundedService {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
@@ -97,6 +99,43 @@ 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.
+     *
+     * ```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 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 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.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 +147,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/esm/src/background/BaseScheduledService.js

@@ -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

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

@@ -500,13 +500,7 @@ export class Background {
      */
     async scheduledMethod(ObjectClass, pattern, method, { globalName, args = [], jobConfig = {}, scheduleOpts = {}, }) {
         this.connect();
-        // `jobId` is used to determine uniqueness along with name and repeat pattern.
-        // Since the name is really a job type and never changes, the `jobId` is the only
-        // way to allow multiple jobs with the same cron repeat pattern. Uniqueness will
-        // now be enforced by combining class name, method name, and cron repeat pattern.
-        //
-        // See: https://docs.bullmq.io/guide/jobs/repeatable
-        const schedulerId = `${globalName}:${method}`;
+        const schedulerId = this.jobSchedulerId(globalName, method);
         const queueInstance = this.queueInstance(jobConfig);
         if (!queueInstance)
             throw new Error(`Missing queue for: ${jobConfig.queue?.toString()}`);
@@ -520,6 +514,40 @@ export class Background {
             },
         });
     }
+    /**
+     * @internal
+     *
+     * Returns the id a scheduled job is registered with BullMQ under.
+     *
+     * `jobId` is used to determine uniqueness along with name and repeat pattern.
+     * Since the name is really a job type and never changes, the `jobId` is the only
+     * way to allow multiple jobs with the same cron repeat pattern. Uniqueness is
+     * enforced by combining the global name and the method name.
+     *
+     * See: https://docs.bullmq.io/guide/jobs/repeatable
+     *
+     * @param globalName - the globalName of the class the method belongs to
+     * @param method - the name of the scheduled method
+     */
+    jobSchedulerId(globalName, method) {
+        return `${globalName}:${method}`;
+    }
+    /**
+     * removes a scheduled job from BullMQ, preventing it from being run again
+     *
+     * Every queue is checked, rather than the one the job's current
+     * `backgroundJobConfig` routes to, so that a job can still be unscheduled
+     * after its workstream has changed, or after the class that scheduled it has
+     * been deleted.
+     *
+     * @param jobSchedulerId - the id the job was scheduled under
+     * @returns true if a scheduled job was removed, false if none was found
+     */
+    async unschedule(jobSchedulerId) {
+        this.connect();
+        const removed = await Promise.all(this.queues.map(queue => queue.removeJobScheduler(jobSchedulerId)));
+        return removed.some(Boolean);
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     queueInstance(values) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/esm/src/test-utils/WorkerTestUtils.js

@@ -28,7 +28,7 @@ export default class WorkerTestUtils {
     static async work(opts = {}) {
         background.connect();
         const queues = background.queues;
-        let workWasDone = true;
+        let workWasDone;
         do {
             workWasDone = false;
             for (const queue of queues) {
@@ -62,9 +62,9 @@ export default class WorkerTestUtils {
     }
     /*
      * iterates through each registered queue, and cleans out all
-     * jobs, including completed, failed, and scheduled jobs. This
-     * is especially useful before a test where you plan to exercise
-     * background jobs manually.
+     * jobs, including waiting, paused, prioritized, delayed, completed,
+     * failed, and scheduled jobs. This is especially useful before a test
+     * where you plan to exercise background jobs manually.
      *
      * If your entire app is continuously exercising background jobs
      * manually, you may want to do this in your spec/setup/hooks.ts file,
@@ -79,8 +79,11 @@ export default class WorkerTestUtils {
     static async clean() {
         background.connect();
         for (const queue of background.queues) {
-            // clears all non-scheduled, non-completed, and non-failed jobs
-            await queue.drain();
+            // clears waiting, paused, and prioritized jobs, as well as delayed jobs
+            // (i.e. jobs which have failed and are awaiting a retry). Delayed jobs which
+            // belong to a job scheduler are intentionally left alone by BullMQ here, and
+            // are cleaned up below when their scheduler is removed.
+            await queue.drain(true);
             // clear out completed and failed jobs
             await queue.clean(0, 10000, 'completed');
             await queue.clean(0, 10000, 'failed');

package/dist/types/src/background/BaseBackgroundedModel.d.ts

@@ -1,5 +1,5 @@
 import { Dream } from '@rvoh/dream';
-import { BackgroundJobConfig, DelayedJobOpts } from '../types/background.js';
+import { BackgroundJobConfig, BackgroundWithOpts, DelayedJobOpts } from '../types/background.js';
 import { FunctionPropertyNames } from '../types/utils.js';
 import { BackgroundableMethodArgs } from './BaseBackgroundedService.js';
 export default class BaseBackgroundedModel extends Dream {
@@ -60,11 +60,37 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
      */
     static backgroundWithDelay<T, MethodName extends PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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.
+     *
+     * ```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.
+     *
+     * 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.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 backgroundWith<T, MethodName extends PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, opts: BackgroundWithOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract
@@ -110,11 +136,38 @@ export default class BaseBackgroundedModel extends Dream {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
      */
     backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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.
+     *
+     * ```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.
+     *
+     * 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.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
+     */
+    backgroundWith<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, opts: BackgroundWithOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
 }
 export type PsychicBackgroundedModelStaticMethods<T extends typeof BaseBackgroundedModel> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedModel>>;
 export type PsychicBackgroundedServiceInstanceMethods<T extends BaseBackgroundedModel> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<BaseBackgroundedModel>>;

package/dist/types/src/background/BaseBackgroundedService.d.ts

@@ -1,5 +1,5 @@
 import { Job } from 'bullmq';
-import { BackgroundJobConfig, DelayedJobOpts } from '../types/background.js';
+import { BackgroundJobConfig, BackgroundWithOpts, DelayedJobOpts } from '../types/background.js';
 import { FunctionPropertyNames } from '../types/utils.js';
 export default class BaseBackgroundedService {
     /**
@@ -68,11 +68,42 @@ export default class BaseBackgroundedService {
      * method, preventing you from needing to explicitly wait for queues to flush
      * before making assertions.
      *
+     * @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 args - a variadic list of arguments to be sent to your method
      */
     static backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delay: DelayedJobOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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.
+     *
+     * ```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 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 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.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 backgroundWith<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, opts: BackgroundWithOpts, methodName: MethodName, ...args: MethodArgs): Promise<void>;
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract
@@ -81,6 +112,14 @@ export default class BaseBackgroundedService {
      */
     get psychicWorkerTypes(): any;
 }
+/**
+ * @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.
+ */
+export declare function mergeBackgroundWithOptsIntoJobConfig<T extends BackgroundJobConfig<any>>(jobConfig: T, opts: BackgroundWithOpts): T;
 export type PsychicBackgroundedServiceStaticMethods<T extends typeof BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedService>>;
 export type PsychicBackgroundedServiceInstanceMethods<T extends BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<BaseBackgroundedService>>;
 type OmitJobFromEndOfArguments<Original extends unknown[]> = Original extends [Job] ? Original extends [string] ? Original : [] : Original extends [...infer Rest, Job] ? Original extends [...unknown[], string] ? Original : Rest : Original;

package/dist/types/src/background/BaseScheduledService.d.ts

@@ -51,6 +51,59 @@ export default class BaseScheduledService {
      * @param args - a variadic list of arguments to be sent to your method
      */
     static schedule<T, MethodName extends FunctionPropertyNames<Required<T>>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends MethodFunc extends (...args: any) => any ? Parameters<MethodFunc> : never>(this: T, pattern: string, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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<T, MethodName extends FunctionPropertyNames<Required<T>>>(this: T, methodName: MethodName): string;
+    /**
+     * 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 unschedule(id: string): Promise<boolean>;
     /**
      * types composed by psychic must be provided, since psychic-workers leverages
      * the sync command in psychic to read your backgroundable services and extract

package/dist/types/src/background/index.d.ts

@@ -182,6 +182,34 @@ export declare class Background {
         jobConfig?: BackgroundJobConfig<any>;
         scheduleOpts?: JobSchedulerTemplateOptions;
     }): Promise<void>;
+    /**
+     * @internal
+     *
+     * Returns the id a scheduled job is registered with BullMQ under.
+     *
+     * `jobId` is used to determine uniqueness along with name and repeat pattern.
+     * Since the name is really a job type and never changes, the `jobId` is the only
+     * way to allow multiple jobs with the same cron repeat pattern. Uniqueness is
+     * enforced by combining the global name and the method name.
+     *
+     * See: https://docs.bullmq.io/guide/jobs/repeatable
+     *
+     * @param globalName - the globalName of the class the method belongs to
+     * @param method - the name of the scheduled method
+     */
+    jobSchedulerId(globalName: string, method: string): string;
+    /**
+     * removes a scheduled job from BullMQ, preventing it from being run again
+     *
+     * Every queue is checked, rather than the one the job's current
+     * `backgroundJobConfig` routes to, so that a job can still be unscheduled
+     * after its workstream has changed, or after the class that scheduled it has
+     * been deleted.
+     *
+     * @param jobSchedulerId - the id the job was scheduled under
+     * @returns true if a scheduled job was removed, false if none was found
+     */
+    unschedule(jobSchedulerId: string): Promise<boolean>;
     private queueInstance;
     /**
      * adds the instance method of a provided dream model to BullMQ

package/dist/types/src/types/background.d.ts

@@ -45,6 +45,20 @@ export interface DelayedJobDuration {
 }
 export type JobTypes = 'BackgroundJobQueueFunctionJob' | 'BackgroundJobQueueStaticJob' | 'BackgroundJobQueueModelInstanceJob';
 export type BackgroundQueuePriority = 'default' | 'urgent' | 'not_urgent' | 'last';
+export interface BackgroundWithOpts {
+    /**
+     * an optional delay to hold off the job for a certain amount of
+     * time after it is entered into the queue. Accepts the same options
+     * as `backgroundWithDelay`, including an optional `jobId` which
+     * debounces repeated calls within the delay window.
+     */
+    delay?: DelayedJobOpts;
+    /**
+     * an optional priority. When provided, this overrides the priority
+     * set on the `backgroundJobConfig` of the service or model.
+     */
+    priority?: BackgroundQueuePriority;
+}
 interface BaseBackgroundJobConfig {
     priority?: BackgroundQueuePriority;
 }

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "author": "RVO Health",
   "publishConfig": {
     "access": "public"
@@ -48,7 +48,7 @@
     "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && tsc -p ./tsconfig.esm.build.test-app.json && echo \"building test app to cjs...\" && tsc -p ./tsconfig.cjs.build.test-app.json",
     "uspec": "vitest --config ./spec/unit/vite.config.ts",
     "format": "pnpm prettier . --write",
-    "lint": "pnpm eslint --no-warn-ignored \"src/**/*.ts\" && pnpm prettier . --check",
+    "lint": "pnpm eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\" \"test-app/**/*.ts\" && pnpm prettier . --check",
     "console": "tsx ./src/conf/repl.ts",
     "console:js": "node ./dist/src/conf/repl.js",
     "prepack": "pnpm build",
@@ -61,7 +61,7 @@
     "ioredis": "^5.8.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
+    "@eslint/js": "^10.0.1",
     "@koa/cors": "^5.0.0",
     "@koa/etag": "^5.0.2",
     "@koa/router": "^15.4.0",
@@ -78,15 +78,15 @@
     "@types/node": "^22.12.0",
     "@types/pg": "^8",
     "@types/supertest": "^6.0.3",
-    "@typescript-eslint/parser": "^8.48.1",
+    "@typescript-eslint/parser": "^8.67.0",
     "bullmq": "^5.64.0",
-    "eslint": "^9.39.1",
+    "eslint": "^10.0.1",
     "ioredis": "^5.8.2",
     "koa": "^3.1.2",
     "koa-bodyparser": "^4.4.1",
     "koa-conditional-get": "^3.0.0",
-    "kysely": "^0.28.13",
-    "kysely-codegen": "^0.19.0",
+    "kysely": "^0.28.17",
+    "kysely-codegen": "~0.20.0",
     "luxon-jest-matchers": "^0.1.14",
     "openapi-typescript": "^7.9.1",
     "pg": "^8.13.1",
@@ -96,8 +96,9 @@
     "tsx": "^4.20.6",
     "typedoc": "^0.28.17",
     "typescript": "^5.8.2",
-    "typescript-eslint": "^8.48.1",
-    "vitest": "^4.1.0"
+    "typescript-eslint": "^8.67.0",
+    "vite": "^7.3.6",
+    "vitest": "^4.1.11"
   },
   "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b",
   "dependencies": {