@tsed/bullmq 8.0.1 → 8.0.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/bullmq",
   "description": "BullMQ integration for Ts.ED",
   "type": "module",
-  "version": "8.0.1",
+  "version": "8.0.3",
   "keywords": [
     "Ts.ED",
     "BullMQ"
@@ -13,6 +13,7 @@
   "typings": "./lib/types/index.d.ts",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "import": "./lib/esm/index.js",
       "default": "./lib/esm/index.js"
@@ -29,12 +30,12 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.1",
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/platform-http": "8.0.1",
-    "@tsed/schema": "8.0.1",
-    "@tsed/typescript": "8.0.1",
+    "@tsed/barrels": "8.0.3",
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/platform-http": "8.0.3",
+    "@tsed/schema": "8.0.3",
+    "@tsed/typescript": "8.0.3",
     "bullmq": "^4.12.3 || ^5.1.1",
     "eslint": "9.12.0",
     "ts-mockito": "^2.6.1",

package/src/BullMQModule.spec.ts

@@ -0,0 +1,477 @@
+import "./BullMQModule.js";
+
+import {catchAsyncError} from "@tsed/core";
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {Queue, Worker} from "bullmq";
+import {anything, instance, mock, verify, when} from "ts-mockito";
+import {beforeEach} from "vitest";
+
+import {BullMQModule} from "./BullMQModule.js";
+import {type BullMQConfig} from "./config/config.js";
+import {JobMethods} from "./contracts/index.js";
+import {FallbackJobController, JobController} from "./decorators/index.js";
+import {InjectQueue} from "./decorators/InjectQueue.js";
+import {InjectWorker} from "./decorators/InjectWorker.js";
+import {JobDispatcher} from "./dispatchers/index.js";
+
+const queueConstructorSpy = vi.fn();
+const workerConstructorSpy = vi.fn();
+
+vi.mock("bullmq", () => {
+  return {
+    Queue: class {
+      constructor(...args: any[]) {
+        queueConstructorSpy(...args);
+      }
+
+      close() {}
+    },
+    Worker: class {
+      constructor(...args: any[]) {
+        workerConstructorSpy(...args);
+      }
+
+      close() {}
+    }
+  };
+});
+
+@JobController("cron", "default", {
+  repeat: {
+    pattern: "* * * * *"
+  }
+})
+class CustomCronJob implements JobMethods {
+  @InjectQueue("default")
+  queue: Queue;
+
+  @InjectWorker("default")
+  worker: Worker;
+
+  handle() {}
+}
+
+@JobController("regular", "default")
+class RegularJob {
+  handle() {}
+}
+
+describe("BullMQModule", () => {
+  let dispatcher: JobDispatcher;
+
+  beforeEach(() => {
+    dispatcher = mock(JobDispatcher);
+    when(dispatcher.dispatch(CustomCronJob)).thenResolve();
+  });
+  beforeEach(() => {
+    queueConstructorSpy.mockClear();
+    workerConstructorSpy.mockClear();
+  });
+
+  afterEach(PlatformTest.reset);
+
+  describe("configuration", () => {
+    describe("merges config correctly", () => {
+      beforeEach(() =>
+        PlatformTest.create({
+          bullmq: {
+            queues: ["default", "special"],
+            connection: {
+              connectionName: "defaultConnectionName"
+            },
+            defaultQueueOptions: {
+              defaultJobOptions: {
+                delay: 100
+              },
+              blockingConnection: true
+            },
+            queueOptions: {
+              special: {
+                connection: {
+                  connectionName: "specialConnectionName"
+                },
+                defaultJobOptions: {
+                  attempts: 9
+                }
+              }
+            },
+            defaultWorkerOptions: {
+              connection: {
+                connectTimeout: 123
+              },
+              concurrency: 50
+            },
+            workerOptions: {
+              special: {
+                concurrency: 1,
+                lockDuration: 2
+              }
+            }
+          },
+          imports: [
+            {
+              token: JobDispatcher,
+              use: instance(dispatcher)
+            }
+          ]
+        })
+      );
+
+      it("queue", () => {
+        expect(queueConstructorSpy).toHaveBeenCalledTimes(2);
+
+        expect(queueConstructorSpy).toHaveBeenNthCalledWith(1, "default", {
+          connection: {
+            connectionName: "defaultConnectionName"
+          },
+          defaultJobOptions: {
+            delay: 100
+          },
+          blockingConnection: true
+        });
+
+        expect(queueConstructorSpy).toHaveBeenNthCalledWith(2, "special", {
+          connection: {
+            connectionName: "specialConnectionName"
+          },
+          defaultJobOptions: {
+            attempts: 9,
+            delay: 100
+          },
+          blockingConnection: true
+        });
+      });
+
+      it("worker", () => {
+        expect(workerConstructorSpy).toHaveBeenCalledTimes(2);
+
+        expect(workerConstructorSpy).toHaveBeenNthCalledWith(1, "default", expect.any(Function), {
+          connection: {
+            connectTimeout: 123
+          },
+          concurrency: 50
+        });
+
+        expect(workerConstructorSpy).toHaveBeenNthCalledWith(2, "special", expect.any(Function), {
+          connection: {
+            connectTimeout: 123
+          },
+          concurrency: 1,
+          lockDuration: 2
+        });
+      });
+    });
+    describe("discover queues from decorators", () => {
+      beforeEach(() =>
+        PlatformTest.create({
+          bullmq: {
+            queues: ["special"],
+            connection: {
+              connectionName: "defaultConnectionName"
+            },
+            defaultQueueOptions: {
+              defaultJobOptions: {
+                delay: 100
+              },
+              blockingConnection: true
+            },
+            queueOptions: {
+              special: {
+                connection: {
+                  connectionName: "specialConnectionName"
+                },
+                defaultJobOptions: {
+                  attempts: 9
+                }
+              }
+            },
+            defaultWorkerOptions: {
+              connection: {
+                connectTimeout: 123
+              },
+              concurrency: 50
+            },
+            workerOptions: {
+              special: {
+                concurrency: 1,
+                lockDuration: 2
+              }
+            }
+          },
+          imports: [
+            {
+              token: JobDispatcher,
+              use: instance(dispatcher)
+            }
+          ]
+        })
+      );
+
+      it("queue", () => {
+        expect(queueConstructorSpy).toHaveBeenCalledTimes(2);
+
+        expect(queueConstructorSpy).toHaveBeenNthCalledWith(1, "default", {
+          connection: {
+            connectionName: "defaultConnectionName"
+          },
+          defaultJobOptions: {
+            delay: 100
+          },
+          blockingConnection: true
+        });
+
+        expect(queueConstructorSpy).toHaveBeenNthCalledWith(2, "special", {
+          connection: {
+            connectionName: "specialConnectionName"
+          },
+          defaultJobOptions: {
+            attempts: 9,
+            delay: 100
+          },
+          blockingConnection: true
+        });
+      });
+
+      it("worker", () => {
+        expect(workerConstructorSpy).toHaveBeenCalledTimes(2);
+
+        expect(workerConstructorSpy).toHaveBeenNthCalledWith(1, "default", expect.any(Function), {
+          connection: {
+            connectTimeout: 123
+          },
+          concurrency: 50
+        });
+
+        expect(workerConstructorSpy).toHaveBeenNthCalledWith(2, "special", expect.any(Function), {
+          connection: {
+            connectTimeout: 123
+          },
+          concurrency: 1,
+          lockDuration: 2
+        });
+      });
+    });
+    describe("disableWorker", () => {
+      const config = {
+        queues: ["default", "foo", "bar"],
+        connection: {},
+        disableWorker: true
+      } as BullMQConfig;
+
+      beforeEach(() =>
+        PlatformTest.create({
+          bullmq: config,
+          imports: [
+            {
+              token: JobDispatcher,
+              use: instance(dispatcher)
+            }
+          ]
+        })
+      );
+
+      it("should not create any workers", () => {
+        expect(workerConstructorSpy).toHaveBeenCalledTimes(0);
+      });
+    });
+    describe("without", () => {
+      beforeEach(() =>
+        PlatformTest.create({
+          imports: [
+            {
+              token: JobDispatcher,
+              use: instance(dispatcher)
+            }
+          ]
+        })
+      );
+      it("skips initialization", async () => {
+        expect(queueConstructorSpy).not.toHaveBeenCalled();
+        verify(dispatcher.dispatch(anything())).never();
+      });
+    });
+  });
+
+  describe("functionality", () => {
+    const config = {
+      queues: ["default", "foo", "bar"],
+      connection: {},
+      workerQueues: ["default", "foo"]
+    } as BullMQConfig;
+
+    beforeEach(() =>
+      PlatformTest.create({
+        bullmq: config,
+        imports: [
+          {
+            token: JobDispatcher,
+            use: instance(dispatcher)
+          }
+        ]
+      })
+    );
+
+    describe("cronjobs", () => {
+      it("should dispatch cron jobs automatically", () => {
+        verify(dispatcher.dispatch(CustomCronJob)).once();
+      });
+    });
+
+    describe("queues", () => {
+      it("should get default", () => {
+        const instance = PlatformTest.get<Queue>("bullmq.queue.default");
+
+        expect(instance).toBeInstanceOf(Queue);
+      });
+
+      it.each(config.queues!)("should register queue(%s)", (queue) => {
+        const instance = PlatformTest.get<Queue>(`bullmq.queue.${queue}`);
+
+        expect(instance).toBeInstanceOf(Queue);
+      });
+    });
+
+    describe("workers", () => {
+      it("should get default", () => {
+        const instance = PlatformTest.get<Worker>("bullmq.worker.default");
+
+        expect(instance).toBeInstanceOf(Worker);
+      });
+
+      it.each(config.workerQueues!)("should register worker(%s)", (queue) => {
+        const instance = PlatformTest.get<Worker>(`bullmq.worker.${queue}`);
+
+        expect(instance).toBeInstanceOf(Worker);
+      });
+
+      it("should not register unspecified worker queue", () => {
+        expect(PlatformTest.get("bullmq.worker.bar")).toBeUndefined();
+      });
+
+      it("should run worker and execute processor", async () => {
+        const bullMQModule = PlatformTest.get<BullMQModule>(BullMQModule);
+        const worker = PlatformTest.get<JobMethods>("bullmq.job.default.regular");
+        const job = {
+          name: "regular",
+          queueName: "default",
+          data: {test: "test"}
+        };
+
+        vi.spyOn(worker, "handle").mockResolvedValueOnce(undefined as never);
+
+        await (bullMQModule as any).onProcess(job);
+
+        expect(worker.handle).toHaveBeenCalledWith({test: "test"}, job);
+      });
+
+      it("should log warning when the worker doesn't exists", async () => {
+        const bullMQModule = PlatformTest.get<BullMQModule>(BullMQModule);
+
+        vi.spyOn(PlatformTest.injector.logger, "warn");
+
+        const job = {
+          name: "regular",
+          queueName: "toto",
+          data: {test: "test"}
+        };
+
+        await (bullMQModule as any).onProcess(job);
+
+        expect(PlatformTest.injector.logger.warn).toHaveBeenCalledWith({
+          event: "BULLMQ_JOB_NOT_FOUND",
+          message: "Job regular toto not found"
+        });
+      });
+
+      it("should run worker, execute processor and handle error", async () => {
+        const bullMQModule = PlatformTest.get<BullMQModule>(BullMQModule);
+        const worker = PlatformTest.get<JobMethods>("bullmq.job.default.regular");
+        const job = {
+          name: "regular",
+          queueName: "default",
+          data: {test: "test"},
+          attemptsMade: 1
+        };
+
+        vi.spyOn(PlatformTest.injector.logger, "error");
+
+        vi.spyOn(worker, "handle").mockRejectedValue(new Error("error") as never);
+
+        const error = await catchAsyncError(() => (bullMQModule as any).onProcess(job));
+
+        expect(worker.handle).toHaveBeenCalledWith({test: "test"}, job);
+        expect(PlatformTest.injector.logger.error).toHaveBeenCalledWith({
+          attempt: 1,
+          name: "regular",
+          queue: "default",
+          logType: "bullmq",
+          duration: expect.any(Number),
+          event: "BULLMQ_JOB_ERROR",
+          message: "error",
+          reqId: expect.any(String),
+          stack: expect.any(String),
+          time: expect.any(Object)
+        });
+        expect(error?.message).toEqual("error");
+      });
+    });
+  });
+  describe("with fallback controller", () => {
+    beforeEach(async () => {
+      @FallbackJobController("foo")
+      class FooFallbackController {
+        handle() {}
+      }
+
+      @FallbackJobController()
+      class FallbackController {
+        handle() {}
+      }
+
+      await PlatformTest.create({
+        bullmq: {
+          queues: ["default", "foo"],
+          connection: {}
+        },
+        imports: [
+          {
+            token: JobDispatcher,
+            use: instance(dispatcher)
+          }
+        ]
+      });
+    });
+
+    it("should run queue specific fallback job controller", async () => {
+      const bullMQModule = PlatformTest.get<BullMQModule>(BullMQModule);
+      const worker = PlatformTest.get<JobMethods>("bullmq.fallback-job.foo");
+      const job = {
+        name: "unknown-name",
+        queueName: "foo",
+        data: {test: "test"}
+      };
+
+      vi.spyOn(worker, "handle").mockResolvedValueOnce(undefined as never);
+
+      await (bullMQModule as any).onProcess(job);
+
+      expect(worker.handle).toHaveBeenCalledWith({test: "test"}, job);
+    });
+
+    it("should run overall fallback job controller", async () => {
+      const bullMQModule = PlatformTest.get<BullMQModule>(BullMQModule);
+      const worker = PlatformTest.get<JobMethods>("bullmq.fallback-job");
+      const job = {
+        name: "unknown-name",
+        queueName: "default",
+        data: {test: "123"}
+      };
+
+      vi.spyOn(worker, "handle").mockResolvedValueOnce(undefined as never);
+
+      await (bullMQModule as any).onProcess(job);
+
+      expect(worker.handle).toHaveBeenCalledWith({test: "123"}, job);
+    });
+  });
+});

package/src/BullMQModule.ts

@@ -0,0 +1,151 @@
+import {
+  constant,
+  DIContext,
+  inject,
+  injectable,
+  injectMany,
+  injector,
+  logger,
+  OnDestroy,
+  type OnInit,
+  ProviderType,
+  runInContext
+} from "@tsed/di";
+import {getComputedType} from "@tsed/schema";
+import {Job, Queue, Worker} from "bullmq";
+import {v4} from "uuid";
+
+import {BullMQConfig} from "./config/config.js";
+import {BullMQTypes} from "./constants/BullMQTypes.js";
+import {BULLMQ} from "./constants/constants.js";
+import {JobMethods, JobStore} from "./contracts/index.js";
+import {JobDispatcher} from "./dispatchers/index.js";
+import {createQueueProvider} from "./utils/createQueueProvider.js";
+import {createWorkerProvider} from "./utils/createWorkerProvider.js";
+import {getFallbackJobToken, getJobToken} from "./utils/getJobToken.js";
+import {mapQueueOptions} from "./utils/mapQueueOptions.js";
+import {mapWorkerOptions} from "./utils/mapWorkerOptions.js";
+
+export class BullMQModule implements OnInit, OnDestroy {
+  private readonly dispatcher = inject(JobDispatcher);
+
+  constructor() {
+    // build providers allow @Inject(queue) usage in JobController instance
+    if (this.isEnabled()) {
+      const queues = [...this.getUniqQueueNames()];
+
+      this.buildQueues(queues);
+
+      if (!this.isWorkerEnabled()) {
+        const workers = this.config.workerQueues?.length ? this.config.workerQueues : queues;
+
+        this.buildWorkers(workers);
+      }
+    }
+  }
+
+  get config() {
+    return constant<BullMQConfig>("bullmq")!;
+  }
+
+  $onInit() {
+    if (this.isEnabled()) {
+      injectMany<JobMethods>(BullMQTypes.CRON).map((job) => this.dispatcher.dispatch(getComputedType(job)));
+    }
+  }
+
+  async $onDestroy() {
+    if (!this.isEnabled()) {
+      return;
+    }
+
+    await Promise.all(injectMany<Queue>(BullMQTypes.QUEUE).map((queue) => queue.close()));
+    await Promise.all(injectMany<Worker>(BullMQTypes.WORKER).map((worker) => worker.close()));
+  }
+
+  isEnabled() {
+    return !!this.config;
+  }
+
+  isWorkerEnabled() {
+    return this.config.disableWorker;
+  }
+
+  private buildQueues(queues: string[]) {
+    queues.forEach((queue) => {
+      const opts = mapQueueOptions(queue, this.config);
+      createQueueProvider(queue, opts);
+    });
+  }
+
+  private buildWorkers(workers: string[]) {
+    workers.forEach((worker) => {
+      const opts = mapWorkerOptions(worker, this.config);
+      createWorkerProvider(worker, this.onProcess, opts);
+    });
+  }
+
+  /**
+   * Auto discover queue names from provider and merge it with queue names from global configuration.
+   * @private
+   */
+  private getUniqQueueNames() {
+    return new Set(
+      injector()
+        .getProviders([BullMQTypes.JOB, BullMQTypes.CRON, BullMQTypes.FALLBACK_JOB])
+        .map((provider) => provider.store.get<JobStore>(BULLMQ)?.queue)
+        .concat(this.config.queues!)
+        .filter(Boolean)
+    );
+  }
+
+  private getJob(name: string, queueName: string) {
+    return inject<JobMethods>(getJobToken(queueName, name)) || inject(getFallbackJobToken(queueName)) || inject(getFallbackJobToken());
+  }
+
+  private onProcess = async (job: Job) => {
+    const jobService = this.getJob(job.name, job.queueName);
+
+    if (!jobService) {
+      logger().warn({
+        event: "BULLMQ_JOB_NOT_FOUND",
+        message: `Job ${job.name} ${job.queueName} not found`
+      });
+      return;
+    }
+
+    const $ctx = new DIContext({
+      id: job.id || v4().split("-").join(""),
+      additionalProps: {
+        logType: "bullmq",
+        name: job.name,
+        queue: job.queueName,
+        attempt: job.attemptsMade
+      }
+    });
+
+    $ctx.set("BULLMQ_JOB", job);
+
+    try {
+      return await runInContext($ctx, () => {
+        $ctx.logger.info("Processing job");
+        try {
+          return jobService.handle(job.data, job);
+        } finally {
+          $ctx.logger.info("Finished processing job");
+        }
+      });
+    } catch (er) {
+      $ctx.logger.error({
+        event: "BULLMQ_JOB_ERROR",
+        message: er.message,
+        stack: er.stack
+      });
+      throw er;
+    } finally {
+      await $ctx.destroy();
+    }
+  };
+}
+
+injectable(BullMQModule).type(ProviderType.MODULE);

package/src/config/config.ts

@@ -0,0 +1,59 @@
+import type {ConnectionOptions, DefaultJobOptions, QueueOptions, WorkerOptions} from "bullmq";
+
+export type BullMQConfig = {
+  /**
+   * Specify queue name's to create
+   */
+  queues?: string[];
+
+  /**
+   * Default connection to use for queue's and worker's
+   */
+  connection: ConnectionOptions;
+
+  /**
+   * Default queue options which are applied to every queue
+   *
+   * Can be extended/overridden by `queueOptions`
+   */
+  defaultQueueOptions?: Partial<QueueOptions>;
+
+  /**
+   * Specify additional queue options by queue name
+   */
+  queueOptions?: Record<string, Partial<QueueOptions>>;
+
+  /**
+   * Disable the creation of any worker.
+   *
+   * All other worker configuration will be ignored
+   */
+  disableWorker?: boolean;
+
+  /**
+   * Specify for which queues to start a worker for.
+   *
+   * Defaultly for every queue added in the `queues` parameter
+   */
+  workerQueues?: string[];
+
+  /**
+   * Default worker options which are applied to every worker
+   *
+   * Can be extended/overridden by `workerOptions`
+   */
+  defaultWorkerOptions?: Partial<WorkerOptions>;
+
+  /**
+   * Specify additional worker options by queue name
+   */
+  workerOptions?: Record<string, Partial<WorkerOptions>>;
+};
+
+declare global {
+  namespace TsED {
+    interface Configuration {
+      bullmq?: BullMQConfig;
+    }
+  }
+}

package/src/constants/BullMQTypes.ts

@@ -0,0 +1,7 @@
+export enum BullMQTypes {
+  CRON = "bullmq:cron",
+  QUEUE = "bullmq:queue",
+  JOB = "bullmq:job",
+  WORKER = "bullmq:worker",
+  FALLBACK_JOB = "bullmq:fallback-job"
+}

package/src/constants/constants.ts

@@ -0,0 +1 @@
+export const BULLMQ = "bullmq";

package/src/contracts/JobMethods.ts

@@ -0,0 +1,7 @@
+import {Job} from "bullmq";
+
+export interface JobMethods<DataType = unknown, ReturnType = unknown> {
+  handle(payload: DataType, job: Job<DataType, ReturnType>): ReturnType | Promise<ReturnType>;
+
+  jobId?(payload: DataType): string | Promise<string>;
+}

package/src/contracts/JobStore.ts

@@ -0,0 +1,7 @@
+import {JobsOptions} from "bullmq";
+
+export interface JobStore {
+  name: string;
+  queue: string;
+  opts: JobsOptions;
+}

package/src/contracts/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./JobMethods.js";
+export * from "./JobStore.js";

package/src/decorators/InjectQueue.ts

@@ -0,0 +1,7 @@
+import {Inject} from "@tsed/di";
+
+import {getQueueToken} from "../utils/getQueueToken.js";
+
+export function InjectQueue(name: string) {
+  return Inject(getQueueToken(name));
+}

package/src/decorators/InjectWorker.ts

@@ -0,0 +1,7 @@
+import {Inject} from "@tsed/di";
+
+import {getWorkerToken} from "../utils/getWorkerToken.js";
+
+export function InjectWorker(name: string) {
+  return Inject(getWorkerToken(name));
+}

package/src/decorators/JobController.spec.ts

@@ -0,0 +1,94 @@
+import {Store} from "@tsed/core";
+import {GlobalProviders} from "@tsed/di";
+
+import {FallbackJobController, JobController} from "./JobController.js";
+
+describe("JobController", () => {
+  afterEach(() => GlobalProviders.clear());
+
+  it("should set the proper store data", () => {
+    @JobController("testjob")
+    class TestJob {}
+
+    const store = Store.from(TestJob).get("bullmq");
+
+    expect(store.name).toBe("testjob");
+    expect(store.queue).toBe("default");
+    expect(store.opts).toStrictEqual({});
+  });
+
+  it("should allow settings a custom queue", () => {
+    @JobController("testjob", "custom")
+    class CustomQueueJob {}
+
+    const store = Store.from(CustomQueueJob).get("bullmq");
+
+    expect(store.queue).toBe("custom");
+  });
+
+  it("should allow custom options to be set", () => {
+    @JobController("testjob", "default", {
+      backoff: 69,
+      attempts: 42
+    })
+    class CustomOptionsJob {}
+
+    const store = Store.from(CustomOptionsJob).get("bullmq");
+
+    expect(store.opts).toStrictEqual({
+      backoff: 69,
+      attempts: 42
+    });
+  });
+
+  it("should set type for cron jobs", () => {
+    @JobController("testjob", "default", {
+      repeat: {count: 42}
+    })
+    class CustomCronJob {}
+
+    const store = Store.from(CustomCronJob).get("bullmq");
+
+    expect(store).toBeDefined();
+  });
+});
+
+describe("FallbackJobController", () => {
+  afterEach(() => GlobalProviders.clear());
+
+  describe("with queue", () => {
+    it("should set the proper store data", () => {
+      @FallbackJobController("default")
+      class FallbackJob {}
+
+      const store = Store.from(FallbackJob).get("bullmq");
+      expect(store.queue).toBe("default");
+
+      const fallbackControllerForQueue = GlobalProviders.get("bullmq.fallback-job.default");
+      expect(fallbackControllerForQueue).not.toBeUndefined();
+      expect(fallbackControllerForQueue?.type).toEqual("bullmq:fallback-job");
+      expect(fallbackControllerForQueue?.useClass).toEqual(FallbackJob);
+
+      const fallbackController = GlobalProviders.get("bullmq.fallback-job");
+      expect(fallbackController).toBeUndefined();
+    });
+  });
+
+  describe("without queue", () => {
+    it("should set the proper store data", () => {
+      @FallbackJobController()
+      class FallbackJob {}
+
+      const store = Store.from(FallbackJob).get("bullmq");
+      expect(store.queue).toBeUndefined();
+
+      const fallbackController = GlobalProviders.get("bullmq.fallback-job");
+      expect(fallbackController).not.toBeUndefined();
+      expect(fallbackController?.type).toEqual("bullmq:fallback-job");
+      expect(fallbackController?.useClass).toEqual(FallbackJob);
+
+      const fallbackControllerForQueue = GlobalProviders.get("bullmq.fallback-job.default");
+      expect(fallbackControllerForQueue).toBeUndefined();
+    });
+  });
+});

package/src/decorators/JobController.ts

@@ -0,0 +1,33 @@
+import {StoreMerge, useDecorators} from "@tsed/core";
+import {Injectable} from "@tsed/di";
+import {JobsOptions} from "bullmq";
+
+import {BullMQTypes} from "../constants/BullMQTypes.js";
+import {BULLMQ} from "../constants/constants.js";
+import {getFallbackJobToken, getJobToken} from "../utils/getJobToken.js";
+
+export function JobController(name: string, queue: string = "default", opts: JobsOptions = {}) {
+  return useDecorators(
+    StoreMerge(BULLMQ, {
+      name,
+      queue,
+      opts
+    }),
+    Injectable({
+      token: getJobToken(queue, name),
+      type: opts.repeat ? BullMQTypes.CRON : BullMQTypes.JOB
+    })
+  );
+}
+
+export function FallbackJobController(queue?: string) {
+  return useDecorators(
+    StoreMerge(BULLMQ, {
+      queue
+    }),
+    Injectable({
+      token: getFallbackJobToken(queue),
+      type: BullMQTypes.FALLBACK_JOB
+    })
+  );
+}

package/src/decorators/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./InjectQueue.js";
+export * from "./InjectWorker.js";
+export * from "./JobController.js";

package/src/dispatchers/JobDispatcher.spec.ts

@@ -0,0 +1,169 @@
+import {catchAsyncError} from "@tsed/core";
+import {DITest, inject, injectable, injector} from "@tsed/di";
+import {beforeEach} from "vitest";
+
+import {JobMethods} from "../contracts/index.js";
+import {JobController} from "../decorators/index.js";
+import {JobDispatcher} from "./JobDispatcher.js";
+
+@JobController("example-job-with-custom-id-from-job-methods")
+class ExampleJobWithCustomJobIdFromJobMethods implements JobMethods {
+  handle(payload: string) {}
+
+  jobId(payload: string): string {
+    return payload.toUpperCase();
+  }
+}
+
+@JobController("example-job", "default", {
+  backoff: 69
+})
+class ExampleTestJob implements JobMethods {
+  handle(payload: {msg: string}) {}
+}
+
+@JobController("queue-not-configured", "not-configured")
+class NotConfiguredQueueTestJob implements JobMethods {
+  handle() {}
+}
+
+function getFixture() {
+  const dispatcher = inject(JobDispatcher);
+  const queue = {
+    name: "default",
+    add: vi.fn()
+  };
+
+  const specialQueue = {
+    name: "special",
+    add: vi.fn()
+  };
+
+  injectable("bullmq.queue.default").value(queue);
+  injectable("bullmq.queue.special").value(specialQueue);
+  injectable("bullmq.job.default.example-job").value(new ExampleTestJob());
+  injectable("bullmq.job.default.example-job-with-custom-id-from-job-methods").value(new ExampleJobWithCustomJobIdFromJobMethods());
+
+  vi.spyOn(injector(), "resolve");
+
+  return {
+    dispatcher,
+    queue,
+    specialQueue,
+    job: inject<ExampleJobWithCustomJobIdFromJobMethods>("bullmq.job.default.example-job-with-custom-id-from-job-methods")
+  };
+}
+
+describe("JobDispatcher", () => {
+  beforeEach(() => DITest.create());
+  afterEach(() => DITest.reset());
+
+  it("should throw an exception when a queue is not configured", async () => {
+    const {dispatcher} = getFixture();
+
+    const error = await catchAsyncError(() => dispatcher.dispatch(NotConfiguredQueueTestJob));
+
+    await expect(error).toEqual(new Error("Queue(not-configured) not defined"));
+
+    expect(injector().resolve).toHaveBeenCalledWith("bullmq.queue.not-configured", expect.anything());
+  });
+  it("should dispatch job as type", async () => {
+    const {dispatcher, queue} = getFixture();
+
+    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"});
+
+    expect(queue.add).toHaveBeenCalledOnce();
+    expect(queue.add).toHaveBeenCalledWith(
+      "example-job",
+      expect.objectContaining({msg: "hello test"}),
+      expect.objectContaining({backoff: 69})
+    );
+  });
+  it("should dispatch job as options", async () => {
+    const {dispatcher, specialQueue} = getFixture();
+
+    await dispatcher.dispatch(
+      {
+        queue: "special",
+        name: "some-name"
+      },
+      {msg: "hello test"}
+    );
+
+    expect(specialQueue.add).toHaveBeenCalledOnce();
+    expect(specialQueue.add).toHaveBeenCalledWith("some-name", expect.objectContaining({msg: "hello test"}), expect.anything());
+  });
+  it("should dispatch job as string", async () => {
+    const {dispatcher, queue} = getFixture();
+
+    await dispatcher.dispatch("some-name", {msg: "hello test"});
+
+    expect(queue.add).toHaveBeenCalledOnce();
+    expect(queue.add).toHaveBeenCalledWith("some-name", expect.objectContaining({msg: "hello test"}), expect.anything());
+  });
+  it("should overwrite job options defined by the job", async () => {
+    const {dispatcher, queue} = getFixture();
+
+    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"}, {backoff: 42, jobId: "ffeeaa"});
+
+    expect(queue.add).toHaveBeenCalledOnce();
+    expect(queue.add).toHaveBeenCalledWith(
+      "example-job",
+      expect.objectContaining({msg: "hello test"}),
+      expect.objectContaining({backoff: 42, jobId: "ffeeaa"})
+    );
+  });
+  it("should keep existing options and add new ones", async () => {
+    const {dispatcher, queue} = getFixture();
+
+    await dispatcher.dispatch(ExampleTestJob, {msg: "hello test"}, {jobId: "ffeeaa"});
+
+    expect(queue.add).toHaveBeenCalledOnce();
+    expect(queue.add).toHaveBeenCalledWith(
+      "example-job",
+      expect.objectContaining({msg: "hello test"}),
+      expect.objectContaining({backoff: 69, jobId: "ffeeaa"})
+    );
+  });
+  describe("custom jobId", () => {
+    it("should allow setting the job id from within the job", async () => {
+      const {dispatcher, queue} = getFixture();
+
+      await dispatcher.dispatch(ExampleJobWithCustomJobIdFromJobMethods, "hello world");
+
+      expect(queue.add).toHaveBeenCalledOnce();
+      expect(queue.add).toHaveBeenCalledWith("example-job-with-custom-id-from-job-methods", "hello world", expect.anything());
+
+      const [, , opts] = queue.add.mock.calls.at(-1)!;
+
+      expect(opts).toMatchObject({
+        jobId: "HELLO WORLD"
+      });
+    });
+
+    it("should pass the payload to the jobId method", async () => {
+      const {dispatcher, job} = getFixture();
+
+      vi.spyOn(job, "jobId");
+
+      await dispatcher.dispatch(ExampleJobWithCustomJobIdFromJobMethods, "hello world");
+
+      expect(job.jobId).toHaveBeenCalledOnce();
+      expect(job.jobId).toHaveBeenCalledWith("hello world");
+    });
+
+    it("should choose the jobId provided to the dispatcher even when the method is implemented", async () => {
+      const {dispatcher, queue} = getFixture();
+
+      await dispatcher.dispatch(ExampleJobWithCustomJobIdFromJobMethods, "hello world", {
+        jobId: "I don't think so"
+      });
+
+      const [, , opts] = queue.add.mock.calls.at(-1)!;
+
+      expect(opts).toMatchObject({
+        jobId: "I don't think so"
+      });
+    });
+  });
+});

package/src/dispatchers/JobDispatcher.ts

@@ -0,0 +1,78 @@
+import {isClass, Store, Type} from "@tsed/core";
+import {inject, injectable} from "@tsed/di";
+import {Job as BullMQJob, JobsOptions, Queue} from "bullmq";
+
+import {BULLMQ} from "../constants/constants.js";
+import {JobMethods, type JobStore} from "../contracts/index.js";
+import {getJobToken} from "../utils/getJobToken.js";
+import {getQueueToken} from "../utils/getQueueToken.js";
+import type {JobDispatcherOptions} from "./JobDispatcherOptions.js";
+
+export class JobDispatcher {
+  public async dispatch<T extends JobMethods>(
+    job: Type<T>,
+    payload?: Parameters<T["handle"]>[0],
+    options?: JobsOptions
+  ): Promise<BullMQJob>;
+  public async dispatch<P = unknown>(job: JobDispatcherOptions, payload?: P, options?: JobsOptions): Promise<BullMQJob>;
+  public async dispatch<P = unknown>(job: string, payload?: P, options?: JobsOptions): Promise<BullMQJob>;
+  public async dispatch(job: Type | JobDispatcherOptions | string, payload: unknown, options: JobsOptions = {}): Promise<BullMQJob> {
+    const {queueName, jobName, defaultJobOptions} = await this.resolveDispatchArgs(job, payload);
+
+    const queue = inject<Queue>(getQueueToken(queueName));
+
+    if (!queue) {
+      throw new Error(`Queue(${queueName}) not defined`);
+    }
+
+    return queue.add(jobName, payload, {
+      ...defaultJobOptions,
+      ...options
+    });
+  }
+
+  private async resolveDispatchArgs(job: Type | JobDispatcherOptions | string, payload: unknown) {
+    let queueName: string;
+    let jobName: string;
+    let defaultJobOptions: JobsOptions | undefined;
+
+    if (typeof job === "function") {
+      // job is passed as a Type
+      const store = Store.from(job).get<JobStore>(BULLMQ);
+      queueName = store.queue;
+      jobName = store.name;
+
+      defaultJobOptions = await this.retrieveJobOptionsFromClassBasedJob(store, payload);
+    } else if (typeof job === "object") {
+      // job is passed as JobDispatcherOptions
+      queueName = job.queue;
+      jobName = job.name;
+    } else {
+      // job is passed as a string
+      queueName = "default";
+      jobName = job;
+    }
+
+    return {
+      queueName,
+      jobName,
+      defaultJobOptions
+    };
+  }
+
+  private async retrieveJobOptionsFromClassBasedJob(store: JobStore, payload: unknown): Promise<JobsOptions> {
+    const job = inject<JobMethods>(getJobToken(store.queue, store.name));
+    const jobId = await job.jobId?.(payload);
+
+    if (jobId === undefined) {
+      return store.opts;
+    }
+
+    return {
+      ...store.opts,
+      jobId
+    };
+  }
+}
+
+injectable(JobDispatcher);

package/src/dispatchers/JobDispatcherOptions.ts

@@ -0,0 +1,4 @@
+export interface JobDispatcherOptions {
+  queue: string;
+  name: string;
+}

package/src/dispatchers/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./JobDispatcher.js";
+export * from "./JobDispatcherOptions.js";

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./BullMQModule.js";
+export * from "./config/config.js";
+export * from "./constants/BullMQTypes.js";
+export * from "./constants/constants.js";
+export * from "./contracts/index.js";
+export * from "./contracts/JobMethods.js";
+export * from "./contracts/JobStore.js";
+export * from "./decorators/index.js";
+export * from "./decorators/InjectQueue.js";
+export * from "./decorators/InjectWorker.js";
+export * from "./decorators/JobController.js";
+export * from "./dispatchers/index.js";
+export * from "./dispatchers/JobDispatcher.js";
+export * from "./dispatchers/JobDispatcherOptions.js";
+export * from "./utils/createQueueProvider.js";
+export * from "./utils/createWorkerProvider.js";
+export * from "./utils/getJobToken.js";
+export * from "./utils/getQueueToken.js";
+export * from "./utils/getWorkerToken.js";
+export * from "./utils/mapQueueOptions.js";
+export * from "./utils/mapWorkerOptions.js";

package/src/utils/createQueueProvider.ts

@@ -0,0 +1,16 @@
+import {inject, injectable} from "@tsed/di";
+import {Queue, QueueOptions} from "bullmq";
+
+import {getQueueToken} from "./getQueueToken.js";
+
+export function createQueueProvider(queue: string, opts: QueueOptions) {
+  const token = getQueueToken(queue);
+
+  injectable(token)
+    .factory(() => new Queue(queue, opts))
+    .hooks({
+      $onDestroy: (queue: Queue) => queue.close()
+    });
+
+  return inject<Queue>(token);
+}

package/src/utils/createWorkerProvider.ts

@@ -0,0 +1,18 @@
+import {inject, injectable} from "@tsed/di";
+import {Job, Worker, WorkerOptions} from "bullmq";
+
+import {BullMQTypes} from "../constants/BullMQTypes.js";
+import {getWorkerToken} from "./getWorkerToken.js";
+
+export function createWorkerProvider(worker: string, process: (job: Job) => any, opts: WorkerOptions) {
+  const token = getWorkerToken(worker);
+
+  injectable(token)
+    .type(BullMQTypes.WORKER)
+    .value(new Worker(worker, process, opts))
+    .hooks({
+      $onDestroy: (worker: Worker) => worker.close()
+    });
+
+  return inject<Worker>(token);
+}

package/src/utils/getJobToken.ts

@@ -0,0 +1,7 @@
+export function getJobToken(queue: string, name: string) {
+  return `bullmq.job.${queue}.${name}`;
+}
+
+export function getFallbackJobToken(queue?: string) {
+  return ["bullmq.fallback-job", queue].filter(Boolean).join(".");
+}

package/src/utils/getQueueToken.ts

@@ -0,0 +1,3 @@
+export function getQueueToken(queue: string) {
+  return `bullmq.queue.${queue}`;
+}

package/src/utils/getWorkerToken.ts

@@ -0,0 +1,3 @@
+export function getWorkerToken(worker: string) {
+  return `bullmq.worker.${worker}`;
+}

package/src/utils/mapQueueOptions.ts

@@ -0,0 +1,14 @@
+import {deepMerge} from "@tsed/core";
+import type {QueueOptions} from "bullmq";
+
+import {BullMQConfig} from "../config/config.js";
+
+export function mapQueueOptions(queue: string, bullMQConfig: BullMQConfig): QueueOptions {
+  return deepMerge<QueueOptions, QueueOptions>(
+    {
+      connection: bullMQConfig.connection,
+      ...bullMQConfig.defaultQueueOptions
+    },
+    bullMQConfig.queueOptions?.[queue]
+  )!;
+}

package/src/utils/mapWorkerOptions.ts

@@ -0,0 +1,14 @@
+import {deepMerge} from "@tsed/core";
+import type {WorkerOptions} from "bullmq";
+
+import {BullMQConfig} from "../config/config.js";
+
+export function mapWorkerOptions(queue: string, bullMQConfig: BullMQConfig): WorkerOptions {
+  return deepMerge<WorkerOptions, WorkerOptions>(
+    {
+      connection: bullMQConfig.connection,
+      ...bullMQConfig.defaultWorkerOptions
+    },
+    bullMQConfig.workerOptions?.[queue]
+  )!;
+}