refactor!: separate dependency injection from job hydration

Author: RomainLanz

README.md

@@ -239,9 +239,9 @@ Schedule jobs to run in the future:
 ```typescript
 // Various time formats
 await SendEmailJob.dispatch(payload).in('30s') // 30 seconds
-await SendEmailJob.dispatch(payload).in('5m')  // 5 minutes
-await SendEmailJob.dispatch(payload).in('2h')  // 2 hours
-await SendEmailJob.dispatch(payload).in('1d')  // 1 day
+await SendEmailJob.dispatch(payload).in('5m') // 5 minutes
+await SendEmailJob.dispatch(payload).in('2h') // 2 hours
+await SendEmailJob.dispatch(payload).in('1d') // 1 day
 ```
 
 ## Priority
@@ -326,19 +326,44 @@ const config = {
 }
 ```
 
+### Handling Timeout Gracefully
+
+Jobs have access to an abort signal via `this.signal` to handle timeouts gracefully:
+
+```typescript
+export default class LongRunningJob extends Job<Payload> {
+  static readonly jobName = 'LongRunningJob'
+
+  static options: JobOptions = {
+    timeout: '30s',
+  }
+
+  async execute(): Promise<void> {
+    for (const item of this.payload.items) {
+      // Check if the job has been aborted
+      if (this.signal?.aborted) {
+        throw new Error('Job timed out')
+      }
+
+      await this.processItem(item)
+    }
+  }
+
+  private async processItem(item: any): Promise<void> {
+    // Pass the signal to fetch or other async operations
+    await fetch(item.url, { signal: this.signal })
+  }
+}
+```
+
 ## Job Context
 
 Every job has access to execution context via `this.context`. This provides metadata about the current job execution:
 
 ```typescript
 import { Job } from '@boringnode/queue'
-import type { JobContext } from '@boringnode/queue'
 
 export default class MyJob extends Job<Payload> {
-  constructor(payload: Payload, context: JobContext) {
-    super(payload, context)
-  }
-
   async execute(): Promise<void> {
     console.log(`Job ID: ${this.context.jobId}`)
     console.log(`Attempt: ${this.context.attempt}`) // 1, 2, 3...
@@ -367,17 +392,17 @@ export default class MyJob extends Job<Payload> {
 
 ## 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.
+Use the `jobFactory` option to integrate with IoC containers for dependency injection. The constructor is reserved for injecting dependencies - payload and context are provided separately by the worker.
 
 ```typescript
 import { QueueManager } from '@boringnode/queue'
 
 await QueueManager.init({
   default: 'redis',
   adapters: { redis: redis(connection) },
-  jobFactory: async (JobClass, payload, context) => {
+  jobFactory: async (JobClass) => {
     // Use your IoC container to instantiate jobs
-    return app.container.make(JobClass, [payload, context])
+    return app.container.make(JobClass)
   },
 })
 ```
@@ -386,7 +411,6 @@ Example with injected dependencies:
 
 ```typescript
 import { Job } from '@boringnode/queue'
-import type { JobContext } from '@boringnode/queue'
 
 interface SendEmailPayload {
   to: string
@@ -397,12 +421,10 @@ export default class SendEmailJob extends Job<SendEmailPayload> {
   static readonly jobName = 'SendEmailJob'
 
   constructor(
-    payload: SendEmailPayload,
-    context: JobContext,
     private mailer: MailerService, // Injected by IoC container
     private logger: Logger // Injected by IoC container
   ) {
-    super(payload, context)
+    super()
   }
 
   async execute(): Promise<void> {
@@ -412,7 +434,7 @@ export default class SendEmailJob extends Job<SendEmailPayload> {
 }
 ```
 
-Without a `jobFactory`, jobs are instantiated with `new JobClass(payload, context)`.
+Without a `jobFactory`, jobs are instantiated with `new JobClass()`.
 
 ## Scheduled Jobs
 

src/drivers/sync_adapter.ts

@@ -122,21 +122,20 @@ export class SyncAdapter implements Adapter {
       throw new Error(`Job class ${jobName} not found.`)
     }
 
-    const context: JobContext = Object.freeze({
+    const context: JobContext = {
       jobId: `sync-${Date.now()}`,
       name: jobName,
       attempt: 1,
       queue,
       priority: DEFAULT_PRIORITY,
       acquiredAt: new Date(),
       stalledCount: 0,
-    })
+    }
 
     const jobFactory = QueueManager.getJobFactory()
-    const jobInstance = jobFactory
-      ? await jobFactory(JobClass, payload, context)
-      : new JobClass(payload, context)
+    const jobInstance = jobFactory ? await jobFactory(JobClass) : new JobClass()
 
+    jobInstance.$hydrate(payload, context)
     await jobInstance.execute()
   }
 }

src/job.ts

@@ -8,12 +8,14 @@ import type { JobContext, JobOptions } from './types/main.js'
  * Extend this class to create your own jobs. Each job must implement
  * the `execute()` method which contains the job's business logic.
  *
+ * The constructor is reserved for dependency injection. Payload and context
+ * are provided separately via the `$hydrate()` method (called by the worker).
+ *
  * @typeParam Payload - The type of data this job receives
  *
  * @example
  * ```typescript
  * import { Job } from '@boringnode/queue'
- * import type { JobContext } from '@boringnode/queue'
  *
  * interface SendEmailPayload {
  *   to: string
@@ -27,13 +29,14 @@ import type { JobContext, JobOptions } from './types/main.js'
  *     maxRetries: 3,
  *   }
  *
- *   constructor(payload: SendEmailPayload, context: JobContext) {
- *     super(payload, context)
+ *   // Constructor is for dependency injection only
+ *   constructor(private mailer: MailerService) {
+ *     super()
  *   }
  *
  *   async execute() {
  *     console.log(`Attempt ${this.context.attempt} for job ${this.context.jobId}`)
- *     await sendEmail(this.payload.to, this.payload.subject, this.payload.body)
+ *     await this.mailer.send(this.payload.to, this.payload.subject, this.payload.body)
  *   }
  *
  *   async failed(error: Error) {
@@ -43,13 +46,43 @@ import type { JobContext, JobOptions } from './types/main.js'
  * ```
  */
 export abstract class Job<Payload = any> {
-  readonly #payload: Payload
-  readonly #context: JobContext
+  #payload!: Payload
+  #context!: JobContext
+  #signal?: AbortSignal
 
-  /** Static options for this job class (queue, retries, timeout, etc.) */
+  /**
+   * Static options for this job class.
+   *
+   * Override this property in subclasses to configure job behavior
+   * such as queue name, retry policy, timeout, and more.
+   *
+   * @example
+   * ```typescript
+   * class SendEmailJob extends Job<SendEmailPayload> {
+   *   static options = {
+   *     queue: 'emails',
+   *     maxRetries: 3,
+   *     timeout: '30s',
+   *   }
+   * }
+   * ```
+   */
   static options: JobOptions = {}
 
-  /** The payload data passed to this job instance */
+  /**
+   * The payload data passed to this job instance.
+   *
+   * Contains the data provided when the job was dispatched.
+   * Available after the job has been hydrated by the worker.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   const { to, subject, body } = this.payload
+   *   await sendEmail(to, subject, body)
+   * }
+   * ```
+   */
   get payload(): Payload {
     return this.#payload
   }
@@ -75,14 +108,42 @@ export abstract class Job<Payload = any> {
   }
 
   /**
-   * Create a new job instance.
+   * The abort signal for timeout handling.
+   *
+   * Check `signal.aborted` in long-running operations to handle timeouts gracefully.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   for (const item of this.payload.items) {
+   *     if (this.signal?.aborted) {
+   *       throw new Error('Job timed out')
+   *     }
+   *     await processItem(item)
+   *   }
+   * }
+   * ```
+   */
+  get signal(): AbortSignal | undefined {
+    return this.#signal
+  }
+
+  /**
+   * Hydrate the job with payload, context, and optional abort signal.
+   *
+   * This method is called by the worker after instantiation to provide
+   * the job's runtime data. It should not be called directly by user code.
    *
    * @param payload - The data to be processed by this job
-   * @param context - The job execution context (provided by the worker)
+   * @param context - The job execution context
+   * @param signal - Optional abort signal for timeout handling
+   *
+   * @internal
    */
-  constructor(payload: Payload, context: JobContext) {
+  $hydrate(payload: Payload, context: JobContext, signal?: AbortSignal): void {
     this.#payload = payload
     this.#context = Object.freeze(context)
+    this.#signal = signal
   }
 
   /**
@@ -109,7 +170,7 @@ export abstract class Job<Payload = any> {
    * ```
    */
   static dispatch<T extends Job>(
-    this: new (payload: any, context: JobContext) => T,
+    this: new (...args: any[]) => T,
     payload: T extends Job<infer P> ? P : never
   ): JobDispatcher<T extends Job<infer P> ? P : never> {
     const dispatcher = new JobDispatcher<T extends Job<infer P> ? P : never>(
@@ -158,7 +219,7 @@ export abstract class Job<Payload = any> {
    * ```
    */
   static schedule<T extends Job>(
-    this: new (payload: any, context: JobContext) => T,
+    this: new (...args: any[]) => T,
     payload: T extends Job<infer P> ? P : never
   ): ScheduleBuilder {
     return new ScheduleBuilder((this as any).jobName, payload)
@@ -170,23 +231,23 @@ export abstract class Job<Payload = any> {
    * This method is called by the worker when processing the job.
    * Implement your job's logic here.
    *
-   * @param signal - Optional AbortSignal for timeout handling.
-   *                 Check `signal.aborted` for long-running operations.
+   * For timeout handling, use `this.signal` which is available after hydration.
+   *
    * @throws Any error thrown will trigger retry logic (if configured)
    *
    * @example
    * ```typescript
-   * async execute(signal?: AbortSignal) {
+   * async execute() {
    *   for (const item of this.payload.items) {
-   *     if (signal?.aborted) {
+   *     if (this.signal?.aborted) {
    *       throw new Error('Job timed out')
    *     }
    *     await processItem(item)
    *   }
    * }
    * ```
    */
-  abstract execute(signal?: AbortSignal): Promise<void>
+  abstract execute(): Promise<void>
 
   /**
    * Called when the job has permanently failed (after all retries exhausted).

src/types/main.ts

@@ -181,39 +181,40 @@ export interface JobContext {
   stalledCount: number
 }
 
-export type JobClass<T extends Job = Job> = (new (payload: any, context: JobContext) => T) & {
+/**
+ * Type representing a Job class constructor.
+ *
+ * The constructor accepts any arguments for dependency injection.
+ * Payload and context are provided separately via `$hydrate()`.
+ */
+export type JobClass<T extends Job = Job> = (new (...args: 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, payload, and context, and must return
- * a job instance (or a Promise that resolves to one).
+ * The factory receives only the job class and should return an instance
+ * with all dependencies injected. The worker will call `$hydrate()` separately
+ * to provide payload, context, and signal.
  *
  * @param JobClass - The job class to instantiate
- * @param payload - The payload data for the job
- * @param context - The job execution context (jobId, attempt, queue, etc.)
  * @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, context) => {
- *       return app.container.make(JobClass, [payload, context])
- *     }
+ * await QueueManager.init({
+ *   default: 'redis',
+ *   adapters: { redis: redis() },
+ *   jobFactory: async (JobClass) => {
+ *     return app.container.make(JobClass)
  *   }
  * })
  * ```
  */
-export type JobFactory = (
-  JobClass: JobClass,
-  payload: any,
-  context: JobContext
-) => Job | Promise<Job>
+export type JobFactory = (JobClass: JobClass) => Job | Promise<Job>
 
 export interface RetryConfig {
   maxRetries?: number
@@ -414,15 +415,17 @@ export interface QueueManagerConfig {
    * 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, context)`.
+   * When provided, this factory is called instead of `new JobClass()`.
+   * The worker will call `$hydrate()` on the returned instance to provide
+   * payload, context, and signal.
    *
    * @example
    * ```typescript
    * await QueueManager.init({
    *   default: 'redis',
    *   adapters: { redis: redis() },
-   *   jobFactory: async (JobClass, payload, context) => {
-   *     return app.container.make(JobClass, [payload, context])
+   *   jobFactory: async (JobClass) => {
+   *     return app.container.make(JobClass)
    *   }
    * })
    * ```