@boringnode/queue 0.1.0 → 0.2.0

package/README.md

@@ -39,15 +39,13 @@ Create a job by extending the `Job` class:
 
 ```typescript
 import { Job } from '@boringnode/queue'
-import type { JobContext, JobOptions } from '@boringnode/queue/types'
+import type { JobOptions } from '@boringnode/queue/types'
 
 interface SendEmailPayload {
   to: string
 }
 
 export default class SendEmailJob extends Job<SendEmailPayload> {
-  static readonly jobName = 'SendEmailJob'
-
   static options: JobOptions = {
     queue: 'email',
   }
@@ -58,6 +56,10 @@ export default class SendEmailJob extends Job<SendEmailPayload> {
 }
 ```
 
+> **Note**: The job name defaults to the class name (`SendEmailJob`). You can override it with `name: 'CustomName'` in options if needed.
+>
+> **Warning**: If you minify your code in production, class names may be mangled. In that case, always specify `name` explicitly in your job options.
+
 ### 2. Configure the Queue Manager
 
 ```typescript
@@ -239,9 +241,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
@@ -250,8 +252,6 @@ Jobs with lower priority numbers are processed first:
 
 ```typescript
 export default class UrgentJob extends Job<Payload> {
-  static readonly jobName = 'UrgentJob'
-
   static options: JobOptions = {
     priority: 1, // Processed before default priority (5)
   }
@@ -270,8 +270,6 @@ Configure automatic retries with backoff strategies:
 import { exponentialBackoff, linearBackoff, fixedBackoff } from '@boringnode/queue'
 
 export default class ReliableJob extends Job<Payload> {
-  static readonly jobName = 'ReliableJob'
-
   static options: JobOptions = {
     maxRetries: 5,
     retry: {
@@ -303,8 +301,6 @@ Set a maximum execution time for jobs:
 
 ```typescript
 export default class LimitedJob extends Job<Payload> {
-  static readonly jobName = 'LimitedJob'
-
   static options: JobOptions = {
     timeout: '30s', // Maximum execution time
     failOnTimeout: false, // Retry on timeout (default)
@@ -326,19 +322,42 @@ 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 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,7 +386,7 @@ 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'
@@ -375,9 +394,9 @@ 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 +405,6 @@ Example with injected dependencies:
 
 ```typescript
 import { Job } from '@boringnode/queue'
-import type { JobContext } from '@boringnode/queue'
 
 interface SendEmailPayload {
   to: string
@@ -394,15 +412,11 @@ interface SendEmailPayload {
 }
 
 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 +426,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
 
@@ -518,10 +532,11 @@ const config = {
 Jobs must:
 
 - Extend the `Job` class
-- Have a static `jobName` property
 - Implement the `execute` method
 - Be exported as default
 
+The job name is automatically derived from the class name, or can be explicitly set via `static options = { name: 'CustomName' }`.
+
 ## Logging
 
 You can pass a logger to the queue manager for debugging or monitoring. The logger must be compatible with the [pino](https://github.com/pinojs/pino) interface.

package/build/{chunk-US7THLSZ.js → chunk-RIXMQXYJ.js}

@@ -57,8 +57,9 @@ var LocatorSingleton = class {
           const absolutePath = resolve(file);
           const module = await import(`file://${absolutePath}`);
           const JobClass = module.default;
-          if (JobClass && typeof JobClass === "function" && JobClass.name) {
-            this.register(JobClass.name, JobClass);
+          if (JobClass && typeof JobClass === "function") {
+            const jobName = JobClass.options?.name || JobClass.name;
+            this.register(jobName, JobClass);
             registered++;
           }
         } catch (error) {
@@ -354,4 +355,4 @@ export {
   Locator,
   QueueManager
 };
-//# sourceMappingURL=chunk-US7THLSZ.js.map
+//# sourceMappingURL=chunk-RIXMQXYJ.js.map

package/build/chunk-RIXMQXYJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/debug.ts","../src/locator.ts","../src/logger.ts","../src/queue_manager.ts"],"sourcesContent":["import { debuglog } from 'node:util'\n\nexport default debuglog('boringnode:queue')\n","import { Job } from './job.js'\nimport * as errors from './exceptions.js'\nimport type { JobClass } from './types/main.js'\nimport debug from './debug.js'\nimport { glob } from 'node:fs/promises'\nimport { resolve } from 'node:path'\n\n/**\n * Job class registry.\n *\n * The Locator maintains a mapping of job names to their classes,\n * allowing the Worker to instantiate jobs by name when processing.\n *\n * Jobs are typically registered automatically via `QueueManager.init()`\n * using the `locations` config option, but can also be registered manually.\n *\n * @example\n * ```typescript\n * import { Locator } from '@boringnode/queue'\n * import SendEmailJob from './jobs/send_email_job.js'\n *\n * // Manual registration\n * Locator.register('SendEmailJob', SendEmailJob)\n *\n * // Auto-registration via glob (used by QueueManager.init)\n * await Locator.registerFromGlob(['./jobs/**\\/*.js'])\n *\n * // Retrieve a job class\n * const JobClass = Locator.getOrThrow('SendEmailJob')\n * ```\n */\nclass LocatorSingleton {\n  #registry = new Map<string, JobClass>()\n\n  /**\n   * Register a job class with a given name.\n   *\n   * @param name - The job name (usually the class name)\n   * @param JobClass - The job class constructor\n   *\n   * @example\n   * ```typescript\n   * Locator.register('SendEmailJob', SendEmailJob)\n   * ```\n   */\n  register<T extends Job>(name: string, JobClass: JobClass<T>) {\n    debug('registering job: %s', name)\n\n    this.#registry.set(name, JobClass)\n  }\n\n  /**\n   * Auto-register job classes from files matching glob patterns.\n   *\n   * Each file should have a default export that is a Job class.\n   * The class name is used as the registration name.\n   *\n   * @param patterns - Glob patterns to match job files\n   * @returns Number of jobs successfully registered\n   *\n   * @example\n   * ```typescript\n   * const count = await Locator.registerFromGlob([\n   *   './jobs/**\\/*.js',\n   *   './app/jobs/**\\/*.ts'\n   * ])\n   * console.log(`Registered ${count} jobs`)\n   * ```\n   */\n  async registerFromGlob(patterns: string[]): Promise<number> {\n    let registered = 0\n\n    for (const pattern of patterns) {\n      debug('registering jobs from glob pattern: %s', pattern)\n      for await (const file of glob(pattern)) {\n        debug('found job file: %s', file)\n\n        try {\n          const absolutePath = resolve(file)\n          const module = await import(`file://${absolutePath}`)\n          const JobClass = module.default as JobClass\n\n          if (JobClass && typeof JobClass === 'function') {\n            const jobName = JobClass.options?.name || JobClass.name\n            this.register(jobName, JobClass)\n            registered++\n          }\n        } catch (error) {\n          console.warn(`Failed to load job from ${file}:`, error)\n        }\n      }\n    }\n\n    return registered\n  }\n\n  /**\n   * Get a job class by name.\n   *\n   * @param name - The job name to look up\n   * @returns The job class, or undefined if not found\n   *\n   * @example\n   * ```typescript\n   * const JobClass = Locator.get('SendEmailJob')\n   * if (JobClass) {\n   *   const instance = new JobClass(payload)\n   * }\n   * ```\n   */\n  get<T extends Job = Job>(name: string): JobClass<T> | undefined {\n    return this.#registry.get(name) as JobClass<T> | undefined\n  }\n\n  /**\n   * Get a job class by name, throwing if not found.\n   *\n   * @param name - The job name to look up\n   * @returns The job class\n   * @throws {E_JOB_NOT_FOUND} If the job is not registered\n   *\n   * @example\n   * ```typescript\n   * const JobClass = Locator.getOrThrow('SendEmailJob')\n   * const instance = new JobClass(payload)\n   * ```\n   */\n  getOrThrow<T extends Job = Job>(name: string): JobClass<T> {\n    const JobClass = this.get<T>(name)\n\n    if (!JobClass) {\n      throw new errors.E_JOB_NOT_FOUND([name])\n    }\n\n    return JobClass\n  }\n\n  /**\n   * Remove all registered jobs.\n   *\n   * Primarily useful for testing.\n   */\n  clear(): void {\n    this.#registry.clear()\n  }\n}\n\n/** Global job class registry singleton */\nexport const Locator = new LocatorSingleton()\n","export interface LogObject {\n  [key: string]: unknown\n}\n\nexport interface ErrorObject extends LogObject {\n  err?: Error\n}\n\nexport interface Logger {\n  trace(msg: string): void\n  trace(obj: LogObject, msg: string): void\n\n  debug(msg: string): void\n  debug(obj: LogObject, msg: string): void\n\n  info(msg: string): void\n  info(obj: LogObject, msg: string): void\n\n  warn(msg: string): void\n  warn(obj: LogObject, msg: string): void\n\n  error(msg: string): void\n  error(obj: ErrorObject, msg: string): void\n\n  child(obj: LogObject): Logger\n}\n\n/**\n * A simple logger that writes to console.\n */\nclass ConsoleLogger implements Logger {\n  #prefix: string\n\n  constructor(prefix: string = 'queue') {\n    this.#prefix = prefix\n  }\n\n  #format(level: string, msgOrObj: string | LogObject, msg?: string): [string, LogObject?] {\n    const prefix = `[${this.#prefix}] ${level}:`\n\n    if (typeof msgOrObj === 'object') {\n      return [`${prefix} ${msg}`, msgOrObj]\n    }\n\n    return [`${prefix} ${msgOrObj}`]\n  }\n\n  trace(msg: string): void\n  trace(obj: LogObject, msg: string): void\n  trace(msgOrObj: string | LogObject, msg?: string): void {\n    const [message, obj] = this.#format('TRACE', msgOrObj, msg)\n\n    if (obj) {\n      return console.log(message, obj)\n    }\n\n    console.log(message)\n  }\n\n  debug(msg: string): void\n  debug(obj: LogObject, msg: string): void\n  debug(msgOrObj: string | LogObject, msg?: string): void {\n    const [message, obj] = this.#format('DEBUG', msgOrObj, msg)\n\n    if (obj) {\n      return console.log(message, obj)\n    }\n\n    console.log(message)\n  }\n\n  info(msg: string): void\n  info(obj: LogObject, msg: string): void\n  info(msgOrObj: string | LogObject, msg?: string): void {\n    const [message, obj] = this.#format('INFO', msgOrObj, msg)\n\n    if (obj) {\n      return console.log(message, obj)\n    }\n\n    console.log(message)\n  }\n\n  warn(msg: string): void\n  warn(obj: LogObject, msg: string): void\n  warn(msgOrObj: string | LogObject, msg?: string): void {\n    const [message, obj] = this.#format('WARN', msgOrObj, msg)\n\n    if (obj) {\n      return console.warn(message, obj)\n    }\n\n    console.warn(message)\n  }\n\n  error(msg: string): void\n  error(obj: ErrorObject, msg: string): void\n  error(msgOrObj: string | ErrorObject, msg?: string): void {\n    const [message, obj] = this.#format('ERROR', msgOrObj, msg)\n\n    if (obj) {\n      return console.error(message, obj)\n    }\n\n    console.error(message)\n  }\n\n  child(obj: LogObject): Logger {\n    const childPrefix = obj.pkg ? String(obj.pkg) : this.#prefix\n    return new ConsoleLogger(childPrefix)\n  }\n}\n\nexport const consoleLogger = new ConsoleLogger()\n","import * as errors from './exceptions.js'\nimport debug from './debug.js'\nimport { Locator } from './locator.js'\nimport { consoleLogger, type Logger } from './logger.js'\nimport type { Adapter } from './contracts/adapter.js'\nimport type {\n  AdapterFactory,\n  JobFactory,\n  QueueConfig,\n  QueueManagerConfig,\n  RetryConfig,\n} from './types/main.js'\n\n/**\n * Central configuration and adapter management for the queue system.\n *\n * The QueueManager is responsible for:\n * - Initializing adapters and job registration\n * - Providing adapter instances to workers and dispatchers\n * - Managing retry configuration across global, queue, and job levels\n *\n * @example\n * ```typescript\n * import { QueueManager, redis } from '@boringnode/queue'\n *\n * await QueueManager.init({\n *   default: 'redis',\n *   adapters: {\n *     redis: redis({ host: 'localhost' }),\n *   },\n *   locations: ['./jobs/**\\/*.js'],\n *   retry: {\n *     maxRetries: 3,\n *     backoff: exponentialBackoff(),\n *   },\n * })\n *\n * // Get the default adapter\n * const adapter = QueueManager.use()\n *\n * // Clean up when done\n * await QueueManager.destroy()\n * ```\n */\nclass QueueManagerSingleton {\n  #initialized = false\n  #defaultAdapter!: string\n  #adapters: Record<string, AdapterFactory> = {}\n  #adapterInstances: Map<string, Adapter> = new Map()\n  #globalRetryConfig?: RetryConfig\n  #queueConfigs: Map<string, QueueConfig> = new Map()\n  #logger: Logger = consoleLogger\n  #jobFactory?: JobFactory\n\n  /**\n   * Initialize the queue system with the given configuration.\n   *\n   * This must be called before using the queue system. It:\n   * - Validates the configuration\n   * - Registers adapters\n   * - Auto-discovers and registers job classes from `locations`\n   *\n   * @param config - The queue configuration\n   * @returns This instance for chaining\n   * @throws {E_CONFIGURATION_ERROR} If the configuration is invalid\n   *\n   * @example\n   * ```typescript\n   * await QueueManager.init({\n   *   default: 'redis',\n   *   adapters: {\n   *     redis: redis(),\n   *     postgres: knex(pgConfig),\n   *   },\n   *   locations: ['./jobs/**\\/*.js'],\n   * })\n   * ```\n   */\n  async init(config: QueueManagerConfig) {\n    debug('initializing queue manager with config: %O', config)\n\n    this.#validateConfig(config)\n\n    this.#adapterInstances.clear()\n\n    this.#defaultAdapter = config.default\n    this.#adapters = config.adapters\n    this.#globalRetryConfig = config.retry\n    this.#logger = config.logger ?? consoleLogger\n    this.#jobFactory = config.jobFactory\n\n    if (config.queues) {\n      for (const [queue, queueConfig] of Object.entries(config.queues)) {\n        this.#queueConfigs.set(queue, queueConfig as QueueConfig)\n      }\n    }\n\n    if (config.locations && config.locations.length > 0) {\n      const registered = await Locator.registerFromGlob(config.locations)\n\n      if (registered === 0) {\n        this.#logger.warn(\n          `No jobs found for locations: ${config.locations.join(', ')}. ` +\n            'Verify your glob patterns match your job files.'\n        )\n      }\n    }\n\n    this.#initialized = true\n\n    return this\n  }\n\n  /**\n   * Get an adapter instance by name.\n   *\n   * Adapter instances are cached and reused. If no name is provided,\n   * the default adapter is returned.\n   *\n   * @param adapter - Adapter name (optional, defaults to the default adapter)\n   * @returns The adapter instance\n   * @throws {E_QUEUE_NOT_INITIALIZED} If `init()` hasn't been called\n   * @throws {E_CONFIGURATION_ERROR} If the adapter is not registered\n   * @throws {E_ADAPTER_INIT_ERROR} If the adapter factory throws\n   *\n   * @example\n   * ```typescript\n   * // Get default adapter\n   * const adapter = QueueManager.use()\n   *\n   * // Get specific adapter\n   * const redisAdapter = QueueManager.use('redis')\n   * ```\n   */\n  use(adapter?: string): Adapter {\n    if (!this.#initialized) {\n      throw new errors.E_QUEUE_NOT_INITIALIZED()\n    }\n\n    if (!adapter) {\n      adapter = this.#defaultAdapter\n    }\n\n    // Return cached instance if exists\n    const cached = this.#adapterInstances.get(adapter)\n    if (cached) {\n      return cached\n    }\n\n    const adapterFactory = this.#adapters[adapter]\n\n    if (!adapterFactory) {\n      throw new errors.E_CONFIGURATION_ERROR([`Adapter \"${adapter}\" is not registered`])\n    }\n\n    debug('using adapter \"%s\"', adapter)\n\n    try {\n      const instance = adapterFactory()\n      this.#adapterInstances.set(adapter, instance)\n      return instance\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error)\n      throw new errors.E_ADAPTER_INIT_ERROR([adapter, message])\n    }\n  }\n\n  /**\n   * Get the merged retry configuration for a job.\n   *\n   * Configuration is merged with priority: job > queue > global.\n   * This allows specific jobs or queues to override global defaults.\n   *\n   * @param queue - The queue name\n   * @param jobRetryConfig - Optional job-level retry config\n   * @returns The merged retry configuration\n   *\n   * @example\n   * ```typescript\n   * // Global: maxRetries=3, Queue: maxRetries=5, Job: maxRetries=1\n   * // Result: maxRetries=1 (job wins)\n   * const config = QueueManager.getMergedRetryConfig('emails', { maxRetries: 1 })\n   * ```\n   */\n  getMergedRetryConfig(queue: string, jobRetryConfig?: RetryConfig): RetryConfig {\n    const queueConfig = this.#queueConfigs.get(queue)\n    const queueRetryConfig = queueConfig?.retry || {}\n\n    let maxRetries =\n      jobRetryConfig?.maxRetries ||\n      queueRetryConfig.maxRetries ||\n      this.#globalRetryConfig?.maxRetries ||\n      0\n\n    let backoff =\n      jobRetryConfig?.backoff || queueRetryConfig.backoff || this.#globalRetryConfig?.backoff\n\n    return { maxRetries, backoff }\n  }\n\n  /**\n   * Get the configured job factory for custom instantiation.\n   *\n   * @returns The job factory function, or undefined if not configured\n   */\n  getJobFactory(): JobFactory | undefined {\n    return this.#jobFactory\n  }\n\n  #validateConfig(config: QueueManagerConfig): void {\n    if (!config.adapters || Object.keys(config.adapters).length === 0) {\n      throw new errors.E_CONFIGURATION_ERROR(['At least one adapter must be configured'])\n    }\n\n    if (!config.default) {\n      throw new errors.E_CONFIGURATION_ERROR(['Default adapter must be specified'])\n    }\n\n    if (!config.adapters[config.default]) {\n      throw new errors.E_CONFIGURATION_ERROR([\n        `Default adapter \"${config.default}\" not found in adapters configuration`,\n      ])\n    }\n\n    for (const [name, factory] of Object.entries(config.adapters)) {\n      if (typeof factory !== 'function') {\n        throw new errors.E_CONFIGURATION_ERROR([`Adapter \"${name}\" must be a factory function`])\n      }\n    }\n  }\n\n  /**\n   * Clean up all adapter instances and reset state.\n   *\n   * Call this when shutting down the application or when\n   * you need to reinitialize with a new configuration.\n   *\n   * @example\n   * ```typescript\n   * // On application shutdown\n   * await QueueManager.destroy()\n   * ```\n   */\n  async destroy() {\n    for (const [name, adapter] of this.#adapterInstances) {\n      debug('destroying adapter \"%s\"', name)\n      await adapter.destroy()\n    }\n    this.#adapterInstances.clear()\n    this.#initialized = false\n  }\n}\n\n/** Global queue manager singleton */\nexport const QueueManager = new QueueManagerSingleton()\n"],"mappings":"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","names":[]}

package/build/{index-2Ng_OpVK.d.ts → index-C0Xg6F4E.d.ts}

@@ -185,6 +185,18 @@ interface Logger {
     child(obj: LogObject): Logger;
 }
 
+/**
+ * Duration can be specified as milliseconds (number) or as a human-readable string.
+ *
+ * Supported string formats: '1s', '5m', '2h', '1d', etc.
+ *
+ * @example
+ * ```typescript
+ * const timeout: Duration = '30s'   // 30 seconds
+ * const delay: Duration = 5000      // 5000 milliseconds
+ * const interval: Duration = '5m'   // 5 minutes
+ * ```
+ */
 type Duration = number | string;
 /**
  * Result returned when dispatching a job.
@@ -199,22 +211,108 @@ interface DispatchResult {
     /** Unique identifier for this specific job instance */
     jobId: string;
 }
+/**
+ * Internal representation of a job in the queue.
+ *
+ * This is used by adapters to store and retrieve job data.
+ * Not typically used directly by application code.
+ */
 interface JobData {
+    /**
+     * Unique identifier for this job.
+     */
     id: string;
+    /**
+     * Job class name.
+     */
     name: string;
+    /**
+     * Serialized job payload.
+     */
     payload: any;
+    /**
+     * Number of execution attempts so far.
+     */
     attempts: number;
+    /**
+     * Job priority (lower = higher priority).
+     *
+     * @default 0
+     */
     priority?: number;
+    /**
+     * When to retry this job next (for failed jobs).
+     */
     nextRetryAt?: Date;
+    /**
+     * Number of times this job was recovered from stalled state.
+     */
     stalledCount?: number;
 }
+/**
+ * Static options for a Job class.
+ *
+ * Define these as a static property on your Job class to configure
+ * default behavior for all instances.
+ *
+ * @example
+ * ```typescript
+ * class SendEmailJob extends Job<EmailPayload> {
+ *   static options: JobOptions = {
+ *     name: 'SendEmailJob',
+ *     queue: 'emails',
+ *     maxRetries: 3,
+ *     timeout: '30s',
+ *   }
+ * }
+ * ```
+ */
 interface JobOptions {
+    /**
+     * Unique name for this job class.
+     *
+     * Used to identify the job when dispatching and processing.
+     *
+     * @default constructor.name
+     */
+    name?: string;
+    /**
+     * Queue name for this job.
+     *
+     * @default 'default'
+     */
     queue?: string;
+    /**
+     * Adapter name or factory to use for this job.
+     */
     adapter?: string | (() => Adapter);
+    /**
+     * Maximum retry attempts before permanent failure.
+     *
+     * @default 3
+     */
     maxRetries?: number;
+    /**
+     * Job priority (lower = higher priority).
+     *
+     * @default 0
+     */
     priority?: number;
+    /**
+     * Retry configuration (backoff strategy, delays, etc.).
+     */
     retry?: RetryConfig;
+    /**
+     * Maximum execution time before timeout.
+     *
+     * @default undefined (no timeout)
+     */
     timeout?: Duration;
+    /**
+     * Whether to mark job as failed on timeout.
+     *
+     * @default true
+     */
     failOnTimeout?: boolean;
 }
 /**
@@ -249,34 +347,39 @@ interface JobContext {
     /** Number of times this job has been recovered from stalled state */
     stalledCount: number;
 }
-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()`.
+ */
+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)
  *   }
  * })
  * ```
  */
-type JobFactory = (JobClass: JobClass, payload: any, context: JobContext) => Job | Promise<Job>;
+type JobFactory = (JobClass: JobClass) => Job | Promise<Job>;
 interface RetryConfig {
     maxRetries?: number;
     backoff?: () => BackoffStrategy$1;
@@ -370,7 +473,7 @@ interface ScheduleConfig {
     /** Optional ID for the schedule (UUID if not set). Used for upsert. */
     id?: string;
     /** Job class name */
-    jobName: string;
+    name: string;
     /** Job payload */
     payload: any;
     /** Cron expression (mutually exclusive with everyMs) */
@@ -394,7 +497,7 @@ interface ScheduleData {
     /** Unique identifier */
     id: string;
     /** Job class name */
-    jobName: string;
+    name: string;
     /** Job payload */
     payload: any;
     /** Cron expression (null if using interval) */
@@ -446,15 +549,17 @@ 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)
      *   }
      * })
      * ```
@@ -797,7 +902,7 @@ declare class JobDispatcher<T> {
  */
 declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
     #private;
-    constructor(jobName: string, payload: any);
+    constructor(name: string, payload: any);
     /**
      * Set a custom schedule ID.
      * If not specified, defaults to the job name.
@@ -854,12 +959,14 @@ declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
  * 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
@@ -873,13 +980,14 @@ declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
  *     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) {
@@ -890,9 +998,38 @@ declare class ScheduleBuilder implements PromiseLike<ScheduleResult> {
  */
 declare abstract class Job<Payload = any> {
     #private;
-    /** 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;
     /**
      * Context information for the current job execution.
@@ -912,12 +1049,36 @@ declare abstract class Job<Payload = any> {
      */
     get context(): JobContext;
     /**
-     * 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;
+    /**
+     * 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;
     /**
      * Dispatch this job to the queue.
      *
@@ -941,7 +1102,7 @@ declare abstract class Job<Payload = any> {
      *   .run()
      * ```
      */
-    static dispatch<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
+    static dispatch<T extends Job>(this: new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): JobDispatcher<T extends Job<infer P> ? P : never>;
     /**
      * Create a schedule for this job.
      *
@@ -967,22 +1128,22 @@ declare abstract class Job<Payload = any> {
      *   .run()
      * ```
      */
-    static schedule<T extends Job>(this: new (payload: any, context: JobContext) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder;
+    static schedule<T extends Job>(this: new (...args: any[]) => T, payload: T extends Job<infer P> ? P : never): ScheduleBuilder;
     /**
      * Execute the job's business logic.
      *
      * 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)
@@ -990,7 +1151,7 @@ declare abstract class Job<Payload = any> {
      * }
      * ```
      */
-    abstract execute(signal?: AbortSignal): Promise<void>;
+    abstract execute(): Promise<void>;
     /**
      * Called when the job has permanently failed (after all retries exhausted).
      *

package/build/index.d.ts

@@ -1,5 +1,5 @@
-import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, d as JobFactory, e as Job, f as JobClass, b as ScheduleData, g as ScheduleStatus, c as ScheduleListOptions } from './index-2Ng_OpVK.js';
-export { h as ScheduleBuilder, i as customBackoff, j as exponentialBackoff, k as fixedBackoff, l as linearBackoff } from './index-2Ng_OpVK.js';
+import { Q as QueueManagerConfig, W as WorkerCycle, A as Adapter, R as RetryConfig, d as JobFactory, e as Job, f as JobClass, b as ScheduleData, g as ScheduleStatus, c as ScheduleListOptions } from './index-C0Xg6F4E.js';
+export { h as ScheduleBuilder, i as customBackoff, j as exponentialBackoff, k as fixedBackoff, l as linearBackoff } from './index-C0Xg6F4E.js';
 import * as _poppinss_utils from '@poppinss/utils';
 
 /**
@@ -368,7 +368,7 @@ declare class Schedule {
     #private;
     constructor(data: ScheduleData);
     get id(): string;
-    get jobName(): string;
+    get name(): string;
     get payload(): any;
     get cronExpression(): string | null;
     get everyMs(): number | null;