feat: expose explicit job loading

Author: RomainLanz

src/queue_manager.ts

@@ -7,7 +7,9 @@ import { QueueConfigResolver } from './queue_config_resolver.js'
 import type { Adapter } from './contracts/adapter.js'
 import type { AdapterFactory, JobFactory, QueueManagerConfig } from './types/main.js'
 
-const noopInternalOperationWrapper: NonNullable<QueueManagerConfig['internalOperationWrapper']> = async (fn) => fn()
+const noopInternalOperationWrapper: NonNullable<
+  QueueManagerConfig['internalOperationWrapper']
+> = async (fn) => fn()
 const noopExecutionWrapper: NonNullable<QueueManagerConfig['executionWrapper']> = async (fn) => fn()
 
 type QueueManagerFakeState = {
@@ -19,6 +21,7 @@ type QueueManagerFakeState = {
   internalOperationWrapper?: QueueManagerConfig['internalOperationWrapper']
   executionWrapper?: QueueManagerConfig['executionWrapper']
   configResolver: QueueConfigResolver
+  locations: string[]
   fakeAdapter: FakeAdapter
 }
 
@@ -63,6 +66,7 @@ class QueueManagerSingleton {
   #internalOperationWrapper?: QueueManagerConfig['internalOperationWrapper']
   #executionWrapper?: QueueManagerConfig['executionWrapper']
   #configResolver: QueueConfigResolver = new QueueConfigResolver({})
+  #locations: string[] = []
   #fakeState?: QueueManagerFakeState
 
   /**
@@ -103,23 +107,52 @@ class QueueManagerSingleton {
     this.#internalOperationWrapper = config.internalOperationWrapper
     this.#executionWrapper = config.executionWrapper
     this.#configResolver = QueueConfigResolver.from(config)
+    this.#locations = config.locations ?? []
 
-    if (config.locations && config.locations.length > 0) {
-      const registered = await Locator.registerFromGlob(config.locations)
-
-      if (registered === 0) {
-        this.#logger.warn(
-          `No jobs found for locations: ${config.locations.join(', ')}. ` +
-            'Verify your glob patterns match your job files.'
-        )
-      }
+    if (config.autoLoadJobs ?? true) {
+      await this.loadJobs()
     }
 
     this.#initialized = true
 
     return this
   }
 
+  /**
+   * Load and register job classes from configured or explicit locations.
+   *
+   * This low-level API is useful for framework integrations that need to
+   * register jobs at a precise moment in their command lifecycle.
+   *
+   * @param locations - Optional glob patterns. Defaults to the configured locations.
+   * @returns Number of jobs successfully registered.
+   *
+   * @example
+   * ```typescript
+   * await QueueManager.init(config)
+   * await QueueManager.loadJobs()
+   *
+   * // Or with explicit locations
+   * await QueueManager.loadJobs(['./app/jobs/**\/*.js'])
+   * ```
+   */
+  async loadJobs(locations: string[] = this.#locations): Promise<number> {
+    if (locations.length === 0) {
+      return 0
+    }
+
+    const registered = await Locator.registerFromGlob(locations)
+
+    if (registered === 0) {
+      this.#logger.warn(
+        `No jobs found for locations: ${locations.join(', ')}. ` +
+          'Verify your glob patterns match your job files.'
+      )
+    }
+
+    return registered
+  }
+
   /**
    * Destroy any materialized adapters from the current configuration before
    * replacing it with a new one.
@@ -254,6 +287,7 @@ class QueueManagerSingleton {
       internalOperationWrapper: this.#internalOperationWrapper,
       executionWrapper: this.#executionWrapper,
       configResolver: this.#configResolver,
+      locations: this.#locations,
       fakeAdapter,
     }
 
@@ -295,6 +329,7 @@ class QueueManagerSingleton {
     this.#internalOperationWrapper = state.internalOperationWrapper
     this.#executionWrapper = state.executionWrapper
     this.#configResolver = state.configResolver
+    this.#locations = state.locations
   }
 
   /**
@@ -399,6 +434,7 @@ class QueueManagerSingleton {
     this.#internalOperationWrapper = undefined
     this.#executionWrapper = undefined
     this.#configResolver = new QueueConfigResolver({})
+    this.#locations = []
     this.#fakeState = undefined
   }
 }

src/types/main.ts

@@ -494,6 +494,16 @@ export interface QueueManagerConfig {
   queues?: Record<string, QueueConfig>
   worker?: WorkerConfig
   locations?: string[]
+
+  /**
+   * Whether `init()` should immediately register jobs from configured locations.
+   *
+   * Framework integrations may disable this to defer job loading until a
+   * command lifecycle is ready, then call `QueueManager.loadJobs()`.
+   *
+   * @default true
+   */
+  autoLoadJobs?: boolean
   logger?: Logger
 
   /**

tests/queue_manager.spec.ts

@@ -3,6 +3,8 @@ import * as errors from '../src/exceptions.js'
 import { QueueManager } from '../src/queue_manager.js'
 import { sync } from '../src/drivers/sync_adapter.js'
 import { MemoryLogger } from './_mocks/memory_logger.js'
+import { Locator } from '../src/locator.js'
+import SendEmailJob from '../examples/jobs/send_email_job.js'
 import type { Adapter } from '../src/contracts/adapter.js'
 
 test.group('QueueManager', () => {
@@ -150,6 +152,53 @@ test.group('QueueManager', () => {
     assert.include(logger.logs[0].message, 'No jobs found for locations')
   })
 
+  test('should load jobs from configured locations', async ({ assert, cleanup }) => {
+    cleanup(() => Locator.clear())
+
+    await QueueManager.init({
+      default: 'sync',
+      adapters: { sync: sync() },
+      locations: ['./examples/jobs/*.ts'],
+    })
+
+    Locator.clear()
+
+    const registered = await QueueManager.loadJobs()
+
+    assert.equal(registered, 3)
+    assert.equal(Locator.get('SendEmailJob'), SendEmailJob)
+  })
+
+  test('should keep configured locations when automatic job loading is disabled', async ({
+    assert,
+    cleanup,
+  }) => {
+    cleanup(() => Locator.clear())
+
+    await QueueManager.init({
+      default: 'sync',
+      adapters: { sync: sync() },
+      locations: ['./examples/jobs/*.ts'],
+      autoLoadJobs: false,
+    })
+
+    assert.isUndefined(Locator.get('SendEmailJob'))
+
+    const registered = await QueueManager.loadJobs()
+
+    assert.equal(registered, 3)
+    assert.equal(Locator.get('SendEmailJob'), SendEmailJob)
+  })
+
+  test('should load jobs from explicit locations', async ({ assert, cleanup }) => {
+    cleanup(() => Locator.clear())
+
+    const registered = await QueueManager.loadJobs(['./examples/jobs/*.ts'])
+
+    assert.equal(registered, 3)
+    assert.equal(Locator.get('SendEmailJob'), SendEmailJob)
+  })
+
   test('should fake adapters and restore them', async ({ assert }) => {
     await QueueManager.init({
       default: 'sync',