feat: add jobFactory option for dependency injection support

Author: RomainLanz

README.md

@@ -72,7 +72,7 @@ const config = {
 
   worker: {
     concurrency: 5,
-    pollingInterval: '10ms',
+    idleDelay: '2s',
   },
 
   locations: ['./app/jobs/**/*.ts'],
@@ -242,7 +242,7 @@ export default class UrgentJob extends Job<Payload> {
   static readonly jobName = 'UrgentJob'
 
   static options: JobOptions = {
-    priority: 1,  // Processed before default priority (5)
+    priority: 1, // Processed before default priority (5)
   }
 
   async execute(): Promise<void> {
@@ -264,12 +264,13 @@ export default class ReliableJob extends Job<Payload> {
   static options: JobOptions = {
     maxRetries: 5,
     retry: {
-      backoff: () => exponentialBackoff({
-        baseDelay: '1s',
-        maxDelay: '1m',
-        multiplier: 2,
-        jitter: true,
-      }),
+      backoff: () =>
+        exponentialBackoff({
+          baseDelay: '1s',
+          maxDelay: '1m',
+          multiplier: 2,
+          jitter: true,
+        }),
     },
   }
 
@@ -309,25 +310,73 @@ You can also set a global timeout in the worker configuration:
 ```typescript
 const config = {
   worker: {
-    timeout: '1m',  // Default timeout for all jobs
+    timeout: '1m', // Default timeout for all jobs
   },
 }
 ```
 
+## Dependency Injection
+
+Use the `jobFactory` option to integrate with IoC containers for dependency injection. This allows your jobs to receive injected services in their constructor.
+
+```typescript
+import { Worker } from '@boringnode/queue'
+import type { JobFactory } from '@boringnode/queue'
+
+const worker = new Worker({
+  default: 'redis',
+  adapters: { redis: redis(connection) },
+  worker: {
+    jobFactory: async (JobClass, payload) => {
+      // Use your IoC container to instantiate jobs
+      return app.container.make(JobClass, [payload])
+    },
+  },
+})
+```
+
+Example with injected dependencies:
+
+```typescript
+import { Job } from '@boringnode/queue'
+
+interface SendEmailPayload {
+  to: string
+  subject: string
+}
+
+export default class SendEmailJob extends Job<SendEmailPayload> {
+  static readonly jobName = 'SendEmailJob'
+
+  constructor(
+    payload: SendEmailPayload,
+    private mailer: MailerService,  // Injected by IoC container
+    private logger: Logger          // Injected by IoC container
+  ) {
+    super(payload)
+  }
+
+  async execute(): Promise<void> {
+    this.logger.info(`Sending email to ${this.payload.to}`)
+    await this.mailer.send(this.payload)
+  }
+}
+```
+
+Without a `jobFactory`, jobs are instantiated with `new JobClass(payload)`.
+
 ## Job Discovery
 
 The queue manager automatically discovers and registers jobs from the specified locations:
 
 ```typescript
 const config = {
-  locations: [
-    './app/jobs/**/*.ts',
-    './modules/**/jobs/**/*.ts',
-  ],
+  locations: ['./app/jobs/**/*.ts', './modules/**/jobs/**/*.ts'],
 }
 ```
 
 Jobs must:
+
 - Extend the `Job` class
 - Have a static `jobName` property
 - Implement the `execute` method
@@ -357,20 +406,20 @@ By default, a simple console logger is used that only outputs warnings and error
 
 Performance comparison with BullMQ using realistic jobs (5ms simulated work per job):
 
-| Jobs | Concurrency | @boringnode/queue | BullMQ | Diff         |
-|------|-------------|-------------------|--------|--------------|
-| 100  | 1           | 562ms             | 596ms  | 5.7% faster  |
-| 100  | 5           | 116ms             | 117ms  | ~same        |
-| 100  | 10          | 62ms              | 62ms   | ~same        |
-| 500  | 1           | 2728ms            | 2798ms | 2.5% faster  |
-| 500  | 5           | 565ms             | 565ms  | ~same        |
-| 500  | 10          | 287ms             | 288ms  | ~same        |
-| 1000 | 1           | 5450ms            | 5547ms | 1.7% faster  |
-| 1000 | 5           | 1096ms            | 1116ms | 1.8% faster  |
-| 1000 | 10          | 565ms             | 579ms  | 2.4% faster  |
-| 100K | 5           | 110.5s            | 112.3s | 1.5% faster  |
-| 100K | 10          | 56.2s             | 57.5s  | 2.1% faster  |
-| 100K | 20          | 29.1s             | 29.6s  | 1.7% faster  |
+| Jobs | Concurrency | @boringnode/queue | BullMQ | Diff        |
+|------|-------------|-------------------|--------|-------------|
+| 100  | 1           | 562ms             | 596ms  | 5.7% faster |
+| 100  | 5           | 116ms             | 117ms  | ~same       |
+| 100  | 10          | 62ms              | 62ms   | ~same       |
+| 500  | 1           | 2728ms            | 2798ms | 2.5% faster |
+| 500  | 5           | 565ms             | 565ms  | ~same       |
+| 500  | 10          | 287ms             | 288ms  | ~same       |
+| 1000 | 1           | 5450ms            | 5547ms | 1.7% faster |
+| 1000 | 5           | 1096ms            | 1116ms | 1.8% faster |
+| 1000 | 10          | 565ms             | 579ms  | 2.4% faster |
+| 100K | 5           | 110.5s            | 112.3s | 1.5% faster |
+| 100K | 10          | 56.2s             | 57.5s  | 2.1% faster |
+| 100K | 20          | 29.1s             | 29.6s  | 1.7% faster |
 
 Run benchmarks yourself:
 

index.ts

@@ -9,3 +9,5 @@ export {
   fixedBackoff,
 } from './src/strategies/backoff_strategy.js'
 export * as errors from './src/exceptions.js'
+
+export type { JobFactory } from './src/types/main.js'

src/types/main.ts

@@ -29,6 +29,31 @@ export interface JobOptions {
 
 export type JobClass<T extends Job = Job> = (new (payload: any) => T) & { options?: JobOptions }
 
+/**
+ * Factory function for custom job instantiation.
+ *
+ * Use this to integrate with IoC containers for dependency injection.
+ * The factory receives the job class and payload, and must return
+ * a job instance (or a Promise that resolves to one).
+ *
+ * @param JobClass - The job class to instantiate
+ * @param payload - The payload data for the job
+ * @returns The job instance, or a Promise resolving to the instance
+ *
+ * @example
+ * ```typescript
+ * // With AdonisJS IoC container
+ * const worker = new Worker({
+ *   worker: {
+ *     jobFactory: async (JobClass, payload) => {
+ *       return app.container.make(JobClass, [payload])
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export type JobFactory = (JobClass: JobClass, payload: any) => Job | Promise<Job>
+
 export interface RetryConfig {
   maxRetries?: number
   backoff?: () => BackoffStrategyClass
@@ -103,6 +128,26 @@ export interface WorkerConfig {
    * Called before the worker starts stopping.
    */
   onShutdownSignal?: () => void | Promise<void>
+
+  /**
+   * Custom factory function for job instantiation.
+   *
+   * Use this to integrate with IoC containers for dependency injection.
+   * When provided, this factory is called instead of `new JobClass(payload)`.
+   *
+   * @example
+   * ```typescript
+   * const worker = new Worker({
+   *   worker: {
+   *     jobFactory: async (JobClass, payload) => {
+   *       // Inject dependencies via IoC container
+   *       return app.container.make(JobClass, [payload])
+   *     }
+   *   }
+   * })
+   * ```
+   */
+  jobFactory?: JobFactory
 }
 
 export type WorkerCycle =

src/worker.ts

@@ -6,7 +6,7 @@ import * as errors from './exceptions.js'
 import { QueueManager } from './queue_manager.js'
 import { JobPool } from './job_pool.js'
 import type { Adapter, AcquiredJob } from './contracts/adapter.js'
-import type { QueueManagerConfig, WorkerCycle } from './types/main.js'
+import type { JobFactory, QueueManagerConfig, WorkerCycle } from './types/main.js'
 import { Locator } from './locator.js'
 import type { JobOptions } from './types/main.js'
 import type { Job } from './job.js'
@@ -58,6 +58,7 @@ export class Worker {
   readonly #concurrency: number
   readonly #gracefulShutdown: boolean
   readonly #onShutdownSignal?: () => void | Promise<void>
+  readonly #jobFactory?: JobFactory
 
   #adapter!: Adapter
   #running = false
@@ -89,6 +90,7 @@ export class Worker {
     this.#concurrency = config.worker?.concurrency ?? 1
     this.#gracefulShutdown = config.worker?.gracefulShutdown ?? true
     this.#onShutdownSignal = config.worker?.onShutdownSignal
+    this.#jobFactory = config.worker?.jobFactory
 
     debug('created worker with id %s and config %O', this.#id, config)
   }
@@ -371,7 +373,9 @@ export class Worker {
   ): Promise<{ instance: Job; options: JobOptions; timeout: number | undefined }> {
     try {
       const JobClass = Locator.getOrThrow(job.name)
-      const instance = new JobClass(job.payload)
+      const instance = this.#jobFactory
+        ? await this.#jobFactory(JobClass, job.payload)
+        : new JobClass(job.payload)
       const options = JobClass.options || {}
       const timeout = this.#getJobTimeout(options)