feat!: expose job context to job instances

Author: RomainLanz

src/drivers/sync_adapter.ts

@@ -1,7 +1,12 @@
 import { Locator } from '../locator.js'
+import { QueueManager } from '../queue_manager.js'
 import type { Adapter, AcquiredJob } from '../contracts/adapter.js'
-import type { JobData } from '../types/main.js'
+import type { JobContext, JobData } from '../types/main.js'
+import { DEFAULT_PRIORITY } from '../constants.js'
 
+/**
+ * Create a sync adapter factory.
+ */
 export function sync() {
   return () => new SyncAdapter()
 }
@@ -17,17 +22,17 @@ export class SyncAdapter implements Adapter {
     return this.pushOn('default', jobData)
   }
 
-  pushOn(_queue: string, jobData: JobData): Promise<void> {
-    return this.#execute(jobData.name, jobData.payload)
+  pushOn(queue: string, jobData: JobData): Promise<void> {
+    return this.#execute(jobData.name, jobData.payload, queue)
   }
 
   pushLater(jobData: JobData, delay: number): Promise<void> {
     return this.pushLaterOn('default', jobData, delay)
   }
 
-  pushLaterOn(_queue: string, jobData: JobData, delay: number): Promise<void> {
+  pushLaterOn(queue: string, jobData: JobData, delay: number): Promise<void> {
     setTimeout(() => {
-      void this.#execute(jobData.name, jobData.payload)
+      void this.#execute(jobData.name, jobData.payload, queue)
     }, delay)
 
     return Promise.resolve()
@@ -74,14 +79,28 @@ export class SyncAdapter implements Adapter {
     return Promise.resolve()
   }
 
-  async #execute(jobName: string, payload: any): Promise<any> {
+  async #execute(jobName: string, payload: any, queue: string = 'default'): Promise<any> {
     const JobClass = Locator.get(jobName)
 
     if (!JobClass) {
       throw new Error(`Job class ${jobName} not found.`)
     }
 
-    const jobInstance = new JobClass(payload)
+    const context: JobContext = Object.freeze({
+      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)
+
     await jobInstance.execute()
   }
 }

src/job.ts

@@ -1,5 +1,5 @@
 import { JobDispatcher } from './job_dispatcher.js'
-import type { JobOptions } from './types/main.js'
+import type { JobContext, JobOptions } from './types/main.js'
 
 /**
  * Abstract base class for all queue jobs.
@@ -12,6 +12,7 @@ import type { JobOptions } from './types/main.js'
  * @example
  * ```typescript
  * import { Job } from '@boringnode/queue'
+ * import type { JobContext } from '@boringnode/queue'
  *
  * interface SendEmailPayload {
  *   to: string
@@ -25,7 +26,12 @@ import type { JobOptions } from './types/main.js'
  *     maxRetries: 3,
  *   }
  *
+ *   constructor(payload: SendEmailPayload, context: JobContext) {
+ *     super(payload, context)
+ *   }
+ *
  *   async execute() {
+ *     console.log(`Attempt ${this.context.attempt} for job ${this.context.jobId}`)
  *     await sendEmail(this.payload.to, this.payload.subject, this.payload.body)
  *   }
  *
@@ -37,6 +43,7 @@ import type { JobOptions } from './types/main.js'
  */
 export abstract class Job<Payload = any> {
   readonly #payload: Payload
+  readonly #context: JobContext
 
   /** Static options for this job class (queue, retries, timeout, etc.) */
   static options: JobOptions = {}
@@ -46,13 +53,35 @@ export abstract class Job<Payload = any> {
     return this.#payload
   }
 
+  /**
+   * Context information for the current job execution.
+   *
+   * Provides metadata such as job ID, current attempt number,
+   * queue name, priority, and timing information.
+   *
+   * @example
+   * ```typescript
+   * async execute() {
+   *   if (this.context.attempt > 1) {
+   *     console.log(`Retry attempt ${this.context.attempt}`)
+   *   }
+   *   console.log(`Processing job ${this.context.jobId} on queue ${this.context.queue}`)
+   * }
+   * ```
+   */
+  get context(): JobContext {
+    return this.#context
+  }
+
   /**
    * Create a new job instance.
    *
    * @param payload - The data to be processed by this job
+   * @param context - The job execution context (provided by the worker)
    */
-  constructor(payload: Payload) {
+  constructor(payload: Payload, context: JobContext) {
     this.#payload = payload
+    this.#context = Object.freeze(context)
   }
 
   /**
@@ -79,7 +108,7 @@ export abstract class Job<Payload = any> {
    * ```
    */
   static dispatch<T extends Job>(
-    this: new (payload: any) => T,
+    this: new (payload: any, context: JobContext) => 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>(

src/queue_manager.ts

@@ -3,7 +3,13 @@ import debug from './debug.js'
 import { Locator } from './locator.js'
 import { consoleLogger, type Logger } from './logger.js'
 import type { Adapter } from './contracts/adapter.js'
-import type { AdapterFactory, QueueConfig, QueueManagerConfig, RetryConfig } from './types/main.js'
+import type {
+  AdapterFactory,
+  JobFactory,
+  QueueConfig,
+  QueueManagerConfig,
+  RetryConfig,
+} from './types/main.js'
 
 /**
  * Central configuration and adapter management for the queue system.
@@ -44,6 +50,7 @@ class QueueManagerSingleton {
   #globalRetryConfig?: RetryConfig
   #queueConfigs: Map<string, QueueConfig> = new Map()
   #logger: Logger = consoleLogger
+  #jobFactory?: JobFactory
 
   /**
    * Initialize the queue system with the given configuration.
@@ -80,6 +87,7 @@ class QueueManagerSingleton {
     this.#adapters = config.adapters
     this.#globalRetryConfig = config.retry
     this.#logger = config.logger ?? consoleLogger
+    this.#jobFactory = config.jobFactory
 
     if (config.queues) {
       for (const [queue, queueConfig] of Object.entries(config.queues)) {
@@ -190,6 +198,15 @@ class QueueManagerSingleton {
     return { maxRetries, backoff }
   }
 
+  /**
+   * Get the configured job factory for custom instantiation.
+   *
+   * @returns The job factory function, or undefined if not configured
+   */
+  getJobFactory(): JobFactory | undefined {
+    return this.#jobFactory
+  }
+
   #validateConfig(config: QueueManagerConfig): void {
     if (!config.adapters || Object.keys(config.adapters).length === 0) {
       throw new errors.E_CONFIGURATION_ERROR(['At least one adapter must be configured'])

src/types/index.ts

@@ -3,6 +3,8 @@ export type {
   JobData,
   JobOptions,
   JobClass,
+  JobContext,
+  JobFactory,
   RetryConfig,
   BackoffStrategy,
   BackoffConfig,

src/types/main.ts

@@ -27,32 +27,78 @@ export interface JobOptions {
   failOnTimeout?: boolean
 }
 
-export type JobClass<T extends Job = Job> = (new (payload: any) => T) & { options?: JobOptions }
+/**
+ * Context information available to a job during execution.
+ *
+ * Provides metadata about the current job execution, including
+ * retry information, queue details, and timing.
+ *
+ * @example
+ * ```typescript
+ * class MyJob extends Job<Payload> {
+ *   async execute() {
+ *     console.log(`Attempt ${this.context.attempt} of job ${this.context.jobId}`)
+ *     console.log(`Running on queue: ${this.context.queue}`)
+ *   }
+ * }
+ * ```
+ */
+export interface JobContext {
+  /** Unique identifier for this job */
+  jobId: string
+
+  /** Job class name */
+  name: string
+
+  /** Current attempt number (1-based: first attempt = 1) */
+  attempt: number
+
+  /** Queue name this job is being processed from */
+  queue: string
+
+  /** Job priority (lower number = higher priority) */
+  priority: number
+
+  /** When this job was acquired by the worker for processing */
+  acquiredAt: Date
+
+  /** Number of times this job has been recovered from stalled state */
+  stalledCount: number
+}
+
+export type JobClass<T extends Job = Job> = (new (payload: any, context: JobContext) => 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
+ * The factory receives the job class, payload, and context, 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
+ * @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) => {
- *       return app.container.make(JobClass, [payload])
+ *     jobFactory: async (JobClass, payload, context) => {
+ *       return app.container.make(JobClass, [payload, context])
  *     }
  *   }
  * })
  * ```
  */
-export type JobFactory = (JobClass: JobClass, payload: any) => Job | Promise<Job>
+export type JobFactory = (
+  JobClass: JobClass,
+  payload: any,
+  context: JobContext
+) => Job | Promise<Job>
 
 export interface RetryConfig {
   maxRetries?: number
@@ -128,26 +174,6 @@ 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 =
@@ -166,4 +192,23 @@ export interface QueueManagerConfig {
   worker?: WorkerConfig
   locations?: string[]
   logger?: Logger
+
+  /**
+   * 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)`.
+   *
+   * @example
+   * ```typescript
+   * await QueueManager.init({
+   *   default: 'redis',
+   *   adapters: { redis: redis() },
+   *   jobFactory: async (JobClass, payload, context) => {
+   *     return app.container.make(JobClass, [payload, context])
+   *   }
+   * })
+   * ```
+   */
+  jobFactory?: JobFactory
 }

src/worker.ts

@@ -6,9 +6,9 @@ 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 { JobFactory, QueueManagerConfig, WorkerCycle } from './types/main.js'
+import type { JobContext, JobOptions, QueueManagerConfig, WorkerCycle } from './types/main.js'
 import { Locator } from './locator.js'
-import type { JobOptions } from './types/main.js'
+import { DEFAULT_PRIORITY } from './constants.js'
 import type { Job } from './job.js'
 import {
   DEFAULT_IDLE_DELAY,
@@ -58,7 +58,6 @@ export class Worker {
   readonly #concurrency: number
   readonly #gracefulShutdown: boolean
   readonly #onShutdownSignal?: () => void | Promise<void>
-  readonly #jobFactory?: JobFactory
 
   #adapter!: Adapter
   #running = false
@@ -90,7 +89,6 @@ 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)
   }
@@ -373,9 +371,21 @@ export class Worker {
   ): Promise<{ instance: Job; options: JobOptions; timeout: number | undefined }> {
     try {
       const JobClass = Locator.getOrThrow(job.name)
-      const instance = this.#jobFactory
-        ? await this.#jobFactory(JobClass, job.payload)
-        : new JobClass(job.payload)
+
+      const context: JobContext = Object.freeze({
+        jobId: job.id,
+        name: job.name,
+        attempt: job.attempts + 1,
+        queue,
+        priority: job.priority ?? DEFAULT_PRIORITY,
+        acquiredAt: new Date(job.acquiredAt),
+        stalledCount: job.stalledCount ?? 0,
+      })
+
+      const jobFactory = QueueManager.getJobFactory()
+      const instance = jobFactory
+        ? await jobFactory(JobClass, job.payload, context)
+        : new JobClass(job.payload, context)
       const options = JobClass.options || {}
       const timeout = this.#getJobTimeout(options)