@rvoh/psychic-workers 0.3.0 → 0.3.1

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

@@ -1,14 +1,119 @@
 import { Dream } from '@rvoh/dream';
+import { BackgroundJobConfig } from '../types/background.js';
+import { FunctionPropertyNames } from '../types/utils.js';
 import { BackgroundableMethodArgs } from './BaseBackgroundedService.js';
-import { BackgroundJobConfig } from './index.js';
-import { FunctionPropertyNames } from './types.js';
 export default class BaseBackgroundedModel extends Dream {
+    /**
+     * A getter meant to be overridden in child classes. This does
+     * not have to be explicitly provided, but if so, it would allow
+     * you to override the default behavior of anything backgrounded
+     * by this service, such as the priority or workstream.
+     *
+     * @returns {object} config - the background job config
+     * @returns {string} config.priority - 'default' | 'urgent' | 'not_urgent' | 'last'
+     * @returns {string} config.workstream - a workstream name. This would be the name of a workstream, as defined in conf/workers.ts
+     * @returns {string} config.queueId - the id of the BullMQ queue you wish to connect to. This can only be provided if workstream is not provided.
+     * @returns {string} config.groupId - the groupId of the BullMQ queue you wish to connect to. This can only be provided if workstream is not provided.
+     */
     static get backgroundJobConfig(): BackgroundJobConfig<BaseBackgroundedModel>;
-    get backgroundJobConfig(): BackgroundJobConfig<BaseBackgroundedModel>;
+    /**
+     * @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.
+     */
+    protected get backgroundJobConfig(): BackgroundJobConfig<BaseBackgroundedModel>;
+    /**
+     * 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 background<T, MethodName extends PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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 backgroundWithDelay<T, MethodName extends PsychicBackgroundedModelStaticMethods<T & typeof BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delaySeconds: number, 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
+     * metadata, which can be used to help provide types for the underlying methods
+     * in psychic-workers.
+     */
     get psychicTypes(): any;
+    /**
+     * 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
+     */
     background<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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
+     */
     backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceInstanceMethods<T & BaseBackgroundedModel>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delaySeconds: number, methodName: MethodName, ...args: MethodArgs): Promise<void>;
 }
 export type PsychicBackgroundedModelStaticMethods<T extends typeof BaseBackgroundedModel> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedModel>>;

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

@@ -1,13 +1,84 @@
 import { Job } from 'bullmq';
-import { BackgroundJobConfig } from './index.js';
-import { FunctionPropertyNames } from './types.js';
+import { BackgroundJobConfig } from '../types/background.js';
+import { FunctionPropertyNames } from '../types/utils.js';
 export default 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(): BackgroundJobConfig<BaseBackgroundedService>;
+    /**
+     * @internal
+     *
+     * Returns a unique global name for the given service.
+     *
+     * @returns A string representing a unique key for this service
+     */
     static get globalName(): string;
+    /**
+     * @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: string): void;
     private 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 background<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, methodName: MethodName, ...args: MethodArgs): Promise<void>;
+    /**
+     * 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 backgroundWithDelay<T, MethodName extends PsychicBackgroundedServiceStaticMethods<T & typeof BaseBackgroundedService>, MethodFunc extends T[MethodName & keyof T], MethodArgs extends BackgroundableMethodArgs<MethodFunc>>(this: T, delaySeconds: number, 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
+     * metadata, which can be used to help provide types for the underlying methods
+     * in psychic-workers.
+     */
     get psychicTypes(): any;
 }
 export type PsychicBackgroundedServiceStaticMethods<T extends typeof BaseBackgroundedService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseBackgroundedService>>;

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

@@ -1,11 +1,62 @@
-import { BackgroundJobConfig } from './index.js';
-import { FunctionPropertyNames } from './types.js';
+import { BackgroundJobConfig } from '../types/background.js';
+import { FunctionPropertyNames } from '../types/utils.js';
 export default 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(): BackgroundJobConfig<BaseScheduledService>;
+    /**
+     * @internal
+     *
+     * Returns a unique global name for the given service.
+     *
+     * @returns A string representing a unique key for this service
+     */
     static get globalName(): string;
+    /**
+     * @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: string): void;
     private 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 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>;
+    /**
+     * 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.
+     */
     get psychicTypes(): any;
 }
 export type PsychicScheduledServiceStaticMethods<T extends typeof BaseScheduledService> = Exclude<FunctionPropertyNames<Required<T>>, FunctionPropertyNames<typeof BaseScheduledService>>;

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

@@ -0,0 +1,2 @@
+import { Redis, Cluster } from 'ioredis';
+export default function nameToRedisQueueName(queueName: string, redis: Redis | Cluster): string;

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

@@ -1,69 +1,167 @@
-import { Dream, IdType } from '@rvoh/dream';
+import { Dream } from '@rvoh/dream';
 import { Job, Queue, Worker } from 'bullmq';
-import { PsychicBackgroundNativeBullMQOptions, PsychicBackgroundSimpleOptions } from '../psychic-app-workers/index.js';
-import BaseBackgroundedService from './BaseBackgroundedService.js';
-import BaseScheduledService from './BaseScheduledService.js';
-import { Either } from './types.js';
-type JobTypes = 'BackgroundJobQueueFunctionJob' | 'BackgroundJobQueueStaticJob' | 'BackgroundJobQueueModelInstanceJob';
-export interface BackgroundJobData {
-    id?: IdType;
-    method?: string;
-    args: any;
-    filepath?: string;
-    importKey?: string;
-    globalName?: string;
-}
+import { BackgroundJobConfig, BackgroundJobData, BackgroundQueuePriority, JobTypes } from '../types/background.js';
+/**
+ * the underlying class driving the `background` singleton,
+ * available as an import from `psychic-workers`.
+ */
 export declare class Background {
+    /**
+     * returns the default queue name for your app
+     */
     static get defaultQueueName(): string;
+    /**
+     * @internal
+     *
+     * returns the provided Worker class, or the Worker class from BullMQ
+     * if no override was provided. This is providable because BullMQ also
+     * offers a pro version, which requires you to provide custom classes.
+     */
     static get Worker(): typeof Worker;
+    /**
+     * @internal
+     *
+     * returns the provided Queue class, or the Queue class from BullMQ
+     * if no override was provided. This is providable because BullMQ also
+     * offers a pro version, which requires you to provide custom classes.
+     */
     static get Queue(): typeof Queue;
     /**
+     * @internal
+     *
      * Used when adding jobs to the default queue
      */
     private defaultQueue;
     /**
+     * @internal
+     *
      * Used when adding jobs to the default transitional queue
      */
     private defaultTransitionalQueue;
     /**
+     * @internal
+     *
      * Used when adding jobs to a named queue
      */
     private namedQueues;
+    /**
+     * @internal
+     *
+     * Used when adding grouped jobs
+     */
     private groupNames;
+    /**
+     * @internal
+     *
+     * Used when adding workstreams
+     */
     private workstreamNames;
     /**
+     * @internal
+     *
      * Used when adding jobs to a named transitioanl queue
      */
     private namedTransitionalQueues;
+    /**
+     * @internal
+     *
+     * All of the workers that are currently registered
+     */
     private _workers;
+    /**
+     * @internal
+     *
+     * All of the redis connections that are currently registered
+     */
     private redisConnections;
+    /**
+     * Establishes connection to BullMQ via redis
+     */
     connect({ activateWorkers, }?: {
         activateWorkers?: boolean;
     }): void;
+    /**
+     * Returns all the queues in your application
+     */
     get queues(): Queue[];
+    /**
+     * Returns all the workers in your application
+     */
     get workers(): Worker<any, any, string>[];
     private shutdownAndExit;
+    /**
+     * Shuts down workers, closes all redis connections
+     */
     shutdown(): Promise<void>;
+    /**
+     * closes all redis connections for workers and queues
+     */
     closeAllRedisConnections(): Promise<void>;
+    /**
+     * @internal
+     *
+     * connects to BullMQ using workstream-based arguments
+     */
     private simpleConnect;
+    /**
+     * @internal
+     *
+     * connects to BullMQ using native BullMQ arguments
+     */
     private nativeBullMQConnect;
+    /**
+     * starts background workers
+     */
     work(): void;
-    staticMethod(ObjectClass: Record<'name', string>, method: string, { delaySeconds, globalName, args, jobConfig, }: {
+    /**
+     * adds the static method of a provided class to BullMQ
+     *
+     * @param ObjectClass - the class you wish to background
+     * @param method - the method you wish to background
+     * @param globalName - the globalName of the class you are processing
+     * @param args - (optional) a list of arguments to provide to your method when it is called
+     * @param delaySeconds - (optional) the number of seconds you wish to wait before allowing this job to process
+     * @param importKey - (optional) the import key for the class
+     * @param jobConfig - (optional) the background job config to use when backgrounding this method
+     */
+    staticMethod(ObjectClass: Record<'name', string>, method: string, { globalName, delaySeconds, args, jobConfig, }: {
         globalName: string;
+        args?: any[];
         filepath?: string;
         delaySeconds?: number;
         importKey?: string;
-        args?: any[];
         jobConfig?: BackgroundJobConfig<any>;
     }): Promise<void>;
+    /**
+     * adds the static method of a provided class to BullMQ,
+     * to be scheduled to run at a specified cron pattern
+     *
+     * @param ObjectClass - the class you wish to background
+     * @param pattern - the cron string you wish to use to govern the scheduling for this job
+     * @param method - the method you wish to background
+     * @param globalName - the globalName of the class you are processing
+     * @param args - (optional) a list of arguments to provide to your method when it is called
+     * @param importKey - (optional) the import key for the class
+     * @param jobConfig - (optional) the background job config to use when backgrounding this method
+     */
     scheduledMethod(ObjectClass: Record<'name', string>, pattern: string, method: string, { globalName, args, jobConfig, }: {
         globalName: string;
+        args?: any[];
         filepath?: string;
         importKey?: string;
-        args?: any[];
         jobConfig?: BackgroundJobConfig<any>;
     }): Promise<void>;
     private queueInstance;
+    /**
+     * adds the instance method of a provided dream model to BullMQ
+     *
+     * @param modelInstance - the dream model instance you wish to background
+     * @param method - the method you wish to background
+     * @param globalName - the globalName of the class you are processing
+     * @param args - (optional) a list of arguments to provide to your method when it is called
+     * @param importKey - (optional) the import key for the class
+     * @param jobConfig - (optional) the background job config to use when backgrounding this method
+     */
     modelInstanceMethod(modelInstance: Dream, method: string, { delaySeconds, args, jobConfig, }: {
         delaySeconds?: number;
         importKey?: string;
@@ -86,16 +184,3 @@ export declare class Background {
 declare const background: Background;
 export default background;
 export declare function stopBackgroundWorkers(): Promise<void>;
-export type BackgroundQueuePriority = 'default' | 'urgent' | 'not_urgent' | 'last';
-interface BaseBackgroundJobConfig {
-    priority?: BackgroundQueuePriority;
-}
-export interface WorkstreamBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> extends BaseBackgroundJobConfig {
-    workstream?: T['psychicTypes']['workstreamNames'][number];
-}
-export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService, PsyTypes extends T['psychicTypes'] = T['psychicTypes'], QueueGroupMap = PsyTypes['queueGroupMap'], Queue extends keyof QueueGroupMap = keyof QueueGroupMap, Groups extends QueueGroupMap[Queue] = QueueGroupMap[Queue], GroupId = Groups[number & keyof Groups]> extends BaseBackgroundJobConfig {
-    groupId?: GroupId;
-    queue?: Queue;
-}
-export type BackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> = Either<WorkstreamBackgroundJobConfig<T>, QueueBackgroundJobConfig<T>>;
-export type PsychicBackgroundOptions = (PsychicBackgroundSimpleOptions & Partial<Record<Exclude<keyof PsychicBackgroundNativeBullMQOptions, keyof PsychicBackgroundSimpleOptions>, never>>) | (PsychicBackgroundNativeBullMQOptions & Partial<Record<Exclude<keyof PsychicBackgroundSimpleOptions, keyof PsychicBackgroundNativeBullMQOptions>, never>>);

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

@@ -0,0 +1,3 @@
+export default class ActivatingBackgroundWorkersWithoutDefaultWorkerConnection extends Error {
+    get message(): string;
+}

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

@@ -0,0 +1,5 @@
+export default class ActivatingNamedQueueBackgroundWorkersWithoutWorkerConnection extends Error {
+    private queueName;
+    constructor(queueName: string);
+    get message(): string;
+}

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

@@ -0,0 +1,3 @@
+export default class DefaultBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection extends Error {
+    get message(): string;
+}

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

@@ -0,0 +1,5 @@
+export default class NamedBullMQNativeOptionsMissingQueueConnectionAndDefaultQueueConnection extends Error {
+    private queueName;
+    constructor(queueName: string);
+    get message(): string;
+}

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

@@ -1,4 +1,5 @@
-export { default as background, Background, stopBackgroundWorkers, type BackgroundJobConfig, type BackgroundQueuePriority, } from './background/index.js';
+export { default as background, Background, stopBackgroundWorkers } from './background/index.js';
+export { type BackgroundJobConfig, type BackgroundQueuePriority } from './types/background.js';
 export { default as BaseBackgroundedModel } from './background/BaseBackgroundedModel.js';
 export { default as BaseBackgroundedService } from './background/BaseBackgroundedService.js';
 export { default as BaseScheduledService } from './background/BaseScheduledService.js';

package/dist/types/src/psychic-app-workers/index.d.ts

@@ -1,7 +1,7 @@
 import { PsychicApp } from '@rvoh/psychic';
 import { QueueOptions, WorkerOptions } from 'bullmq';
 import { Cluster, Redis } from 'ioredis';
-import { PsychicBackgroundOptions } from '../background/index.js';
+import { PsychicBackgroundOptions } from '../types/background.js';
 export default class PsychicAppWorkers {
     static init(psychicApp: PsychicApp, cb: (app: PsychicAppWorkers) => void | Promise<void>): Promise<PsychicAppWorkers>;
     /**
@@ -21,7 +21,7 @@ export default class PsychicAppWorkers {
     private _hooks;
     get hooks(): PsychicWorkersAppHooks;
     on<T extends PsychicWorkersHookEventType>(hookEventType: T, cb: T extends 'workers:shutdown' ? () => void | Promise<void> : never): void;
-    set<Opt extends PsychicWorkersAppOption>(option: Opt, value: unknown): void;
+    set<Opt extends PsychicWorkersAppOption>(option: Opt, value: Opt extends 'background' ? PsychicBackgroundOptions : unknown): void;
 }
 export interface PsychicWorkersTypeSync {
     workstreamNames: string[];

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

@@ -0,0 +1,47 @@
+import { IdType } from '@rvoh/dream';
+import BaseBackgroundedService from '../background/BaseBackgroundedService.js';
+import BaseScheduledService from '../background/BaseScheduledService.js';
+import { PsychicBackgroundNativeBullMQOptions, PsychicBackgroundSimpleOptions } from '../psychic-app-workers/index.js';
+import { Either } from './utils.js';
+export interface BackgroundJobData {
+    /**
+     * the id of the background job. This is provided by BullMQ
+     */
+    id?: IdType;
+    /**
+     * the method name of the method on the provided class
+     */
+    method?: string;
+    /**
+     * the arguments that are fed into your background job
+     */
+    args: any;
+    /**
+     * the path to the file containing the class you are backgrounding
+     */
+    filepath?: string;
+    /**
+     * the import key of the class, which will be 'default' if the class is the default
+     * export of the file, and will otherwise be the name of the exported class.
+     */
+    importKey?: string;
+    /**
+     * the globalName value of the service that is being backgrounded.
+     */
+    globalName?: string;
+}
+export type JobTypes = 'BackgroundJobQueueFunctionJob' | 'BackgroundJobQueueStaticJob' | 'BackgroundJobQueueModelInstanceJob';
+export type BackgroundQueuePriority = 'default' | 'urgent' | 'not_urgent' | 'last';
+interface BaseBackgroundJobConfig {
+    priority?: BackgroundQueuePriority;
+}
+export interface WorkstreamBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> extends BaseBackgroundJobConfig {
+    workstream?: T['psychicTypes']['workstreamNames'][number];
+}
+export interface QueueBackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService, PsyTypes extends T['psychicTypes'] = T['psychicTypes'], QueueGroupMap = PsyTypes['queueGroupMap'], Queue extends keyof QueueGroupMap = keyof QueueGroupMap, Groups extends QueueGroupMap[Queue] = QueueGroupMap[Queue], GroupId = Groups[number & keyof Groups]> extends BaseBackgroundJobConfig {
+    groupId?: GroupId;
+    queue?: Queue;
+}
+export type BackgroundJobConfig<T extends BaseScheduledService | BaseBackgroundedService> = Either<WorkstreamBackgroundJobConfig<T>, QueueBackgroundJobConfig<T>>;
+export type PsychicBackgroundOptions = (PsychicBackgroundSimpleOptions & Partial<Record<Exclude<keyof PsychicBackgroundNativeBullMQOptions, keyof PsychicBackgroundSimpleOptions>, never>>) | (PsychicBackgroundNativeBullMQOptions & Partial<Record<Exclude<keyof PsychicBackgroundSimpleOptions, keyof PsychicBackgroundNativeBullMQOptions>, never>>);
+export {};

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": "RVO Health",
   "repository": {
     "type": "git",
@@ -73,4 +73,4 @@
     "vitest": "^3.1.1"
   },
   "packageManager": "yarn@4.7.0"
-}
+}