@boringnode/queue 0.5.0 → 0.5.2

package/README.md

@@ -270,20 +270,22 @@ await QueueManager.init({
   locations: ['./app/jobs/**/*.ts'],
 })
 
-const adapter = QueueManager.fake()
+// The `using` keyword automatically restores the real adapters when
+// the variable goes out of scope (at the end of the test function).
+using fake = QueueManager.fake()
 
 await SendEmailJob.dispatch({ to: 'user@example.com' })
 
-adapter.assertPushed(SendEmailJob)
-adapter.assertPushed(SendEmailJob, {
+fake.assertPushed(SendEmailJob)
+fake.assertPushed(SendEmailJob, {
   queue: 'default',
   payload: (payload) => payload.to === 'user@example.com',
 })
-adapter.assertPushedCount(1)
-
-QueueManager.restore()
+fake.assertPushedCount(1)
 ```
 
+You can also call `QueueManager.restore()` manually if you need more control over when the real adapters are restored.
+
 ### Sync (for testing)
 
 ```typescript
@@ -519,6 +521,78 @@ await QueueManager.init({
 })
 ```
 
+## OpenTelemetry Instrumentation (experimental)
+
+> [!WARNING]
+> The OpenTelemetry instrumentation is experimental and its API may change in future releases.
+
+`@boringnode/queue` ships with built-in OpenTelemetry instrumentation that creates **PRODUCER** spans for job dispatch and **CONSUMER** spans for job execution, following [OTel messaging semantic conventions](https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/).
+
+### Quick Setup
+
+```typescript
+import { QueueInstrumentation } from '@boringnode/queue/otel'
+import * as boringqueue from '@boringnode/queue'
+
+const instrumentation = new QueueInstrumentation({
+  messagingSystem: 'boringqueue', // default
+  executionSpanLinkMode: 'link',  // or 'parent'
+})
+
+instrumentation.enable()
+instrumentation.manuallyRegister(boringqueue)
+```
+
+The instrumentation patches `QueueManager.init()` to automatically inject its wrappers — no config changes needed in your queue setup.
+
+### Span Attributes
+
+The instrumentation uses standard [OTel messaging semantic conventions](https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/) where they map cleanly, plus a few queue-specific custom attributes.
+
+| Attribute                       | Kind    | Description                                |
+| ------------------------------- | ------- | ------------------------------------------ |
+| `messaging.system`              | Semconv | `'boringqueue'` (configurable)             |
+| `messaging.operation.name`      | Semconv | `'publish'` or `'process'`                 |
+| `messaging.destination.name`    | Semconv | Queue name                                 |
+| `messaging.message.id`          | Semconv | Job ID for single-message spans            |
+| `messaging.batch.message_count` | Semconv | Number of jobs in a batch dispatch         |
+| `messaging.message.retry.count` | Custom  | Retry count (0-based) for a job attempt    |
+| `messaging.job.name`            | Custom  | Job class name (e.g. `SendEmailJob`)       |
+| `messaging.job.status`          | Custom  | `'completed'`, `'failed'`, or `'retrying'` |
+| `messaging.job.group_id`        | Custom  | Queue-specific group identifier            |
+| `messaging.job.priority`        | Custom  | Queue-specific job priority                |
+| `messaging.job.delay_ms`        | Custom  | Delay before the job becomes available     |
+| `messaging.job.queue_time_ms`   | Custom  | Time spent waiting in queue before processing |
+
+### Trace Context Propagation
+
+The instrumentation automatically propagates trace context from dispatch to execution:
+
+- **Link mode** (default): Each job execution is an independent trace, linked to the dispatch span
+- **Parent mode**: Job execution is a child of the dispatch span (same trace)
+
+Child spans created inside `execute()` (DB queries, HTTP calls, etc.) are automatically parented to the job consumer span.
+
+### diagnostics_channel
+
+Raw telemetry events are available via `diagnostics_channel` for custom subscribers:
+
+```typescript
+import { tracingChannels } from '@boringnode/queue'
+
+const { executeChannel } = tracingChannels
+
+executeChannel.subscribe({
+  start() {},
+  end() {},
+  asyncStart() {},
+  asyncEnd(message) {
+    console.log(`Job ${message.job.name} ${message.status} in ${message.duration}ms`)
+  },
+  error() {},
+})
+```
+
 ## Benchmarks
 
 Performance comparison with BullMQ (5ms simulated work per job):

package/build/{chunk-WOUYSNK2.js → chunk-KI47AJ6U.js}

@@ -2,7 +2,7 @@ import {
   E_JOB_MAX_ATTEMPTS_REACHED,
   E_JOB_TIMEOUT,
   parse
-} from "./chunk-ZZFSQY36.js";
+} from "./chunk-QEFYHCL7.js";
 
 // src/job_runtime.ts
 var JobExecutionRuntime = class _JobExecutionRuntime {
@@ -125,4 +125,4 @@ var JobExecutionRuntime = class _JobExecutionRuntime {
 export {
   JobExecutionRuntime
 };
-//# sourceMappingURL=chunk-WOUYSNK2.js.map
+//# sourceMappingURL=chunk-KI47AJ6U.js.map

package/build/chunk-PZ5AY32C.js

@@ -0,0 +1,10 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};
+//# sourceMappingURL=chunk-PZ5AY32C.js.map

package/build/chunk-PZ5AY32C.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/build/{chunk-ZZFSQY36.js → chunk-QEFYHCL7.js}

@@ -1,8 +1,6 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
+import {
+  __export
+} from "./chunk-PZ5AY32C.js";
 
 // src/exceptions.ts
 var exceptions_exports = {};
@@ -144,4 +142,4 @@ export {
   parse,
   calculateScore
 };
-//# sourceMappingURL=chunk-ZZFSQY36.js.map
+//# sourceMappingURL=chunk-QEFYHCL7.js.map

package/build/{chunk-ZZFSQY36.js.map → chunk-QEFYHCL7.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/exceptions.ts","../src/constants.ts","../src/utils.ts"],"sourcesContent":["import { createError } from '@poppinss/utils/exception'\n\nexport const E_INVALID_DURATION_EXPRESSION = createError(\n  'Invalid duration expression: \"%s\"',\n  'E_INVALID_DURATION_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_BASE_DELAY = createError<[reason: string]>(\n  'Invalid base delay. Reason: %s',\n  'E_INVALID_BASE_DELAY',\n  500\n)\n\nexport const E_INVALID_MAX_DELAY = createError<[reason: string]>(\n  'Invalid max delay. Reason: %s',\n  'E_INVALID_MAX_DELAY',\n  500\n)\n\nexport const E_INVALID_MULTIPLIER = createError<[reason: string]>(\n  'Invalid multiplier. Reason: %s',\n  'E_INVALID_MULTIPLIER',\n  500\n)\n\nexport const E_CONFIGURATION_ERROR = createError<[reason: string]>(\n  'Configuration error. Reason: %s',\n  'E_CONFIGURATION_ERROR',\n  500\n)\n\nexport const E_JOB_NOT_FOUND = createError<[jobName: string]>(\n  'Requested job \"%s\" is not registered',\n  'E_JOB_NOT_FOUND'\n)\n\nexport const E_JOB_MAX_ATTEMPTS_REACHED = createError<[jobName: string]>(\n  'The job \"%s\" has reached the maximum number of retry attempts',\n  'E_JOB_MAX_ATTEMPTS_REACHED'\n)\n\nexport const E_JOB_TIMEOUT = createError<[jobName: string, timeout: number]>(\n  'The job \"%s\" has exceeded the timeout of %dms',\n  'E_JOB_TIMEOUT'\n)\n\nexport const E_QUEUE_NOT_INITIALIZED = createError(\n  'QueueManager is not initialized. Call QueueManager.init() before using it.',\n  'E_QUEUE_NOT_INITIALIZED',\n  500\n)\n\nexport const E_ADAPTER_INIT_ERROR = createError<[adapterName: string, originalMessage: string]>(\n  'Failed to initialize adapter \"%s\". Reason: %s',\n  'E_ADAPTER_INIT_ERROR',\n  500\n)\n\nexport const E_NO_JOBS_FOUND = createError<[patterns: string]>(\n  'No jobs found for the specified locations: %s. Verify your glob patterns match your job files.',\n  'E_NO_JOBS_FOUND',\n  500\n)\n\nexport const E_INVALID_CRON_EXPRESSION = createError<[expression: string, reason: string]>(\n  'Invalid cron expression \"%s\": %s',\n  'E_INVALID_CRON_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_SCHEDULE_CONFIG = createError<[reason: string]>(\n  'Invalid schedule configuration: %s',\n  'E_INVALID_SCHEDULE_CONFIG',\n  500\n)\n","/**\n * Default job priority (1-10 scale, lower = higher priority)\n */\nexport const DEFAULT_PRIORITY = 5\n\n/**\n * Multiplier used in score calculation: priority * multiplier + timestamp\n *\n * This ensures higher priority jobs are processed first,\n * while preserving FIFO order within the same priority.\n * The value (1e13) leaves room for ~300 years of millisecond timestamps.\n */\nexport const PRIORITY_SCORE_MULTIPLIER = 1e13\n\n/**\n * Default delay when the worker is idle (no jobs in queue)\n */\nexport const DEFAULT_IDLE_DELAY = '2s'\n\n/**\n * Default interval between stalled job checks\n */\nexport const DEFAULT_STALLED_INTERVAL = '30s'\n\n/**\n * Default threshold after which a job is considered stalled\n */\nexport const DEFAULT_STALLED_THRESHOLD = '30s'\n\n/**\n * Default delay before retrying after an error\n */\nexport const DEFAULT_ERROR_RETRY_DELAY = '5s'\n","import { parse as parseDuration } from '@lukeed/ms'\nimport type { Duration, JobRetention } from './types/main.js'\nimport * as errors from './exceptions.js'\nimport { PRIORITY_SCORE_MULTIPLIER } from './constants.js'\n\nexport interface ResolvedRetention {\n  keep: boolean\n  maxAge: number\n  maxCount: number\n}\n\nexport function resolveRetention(retention?: JobRetention): ResolvedRetention {\n  if (retention === undefined || retention === true) {\n    return { keep: false, maxAge: 0, maxCount: 0 }\n  }\n\n  if (retention === false) {\n    return { keep: true, maxAge: 0, maxCount: 0 }\n  }\n\n  return {\n    keep: true,\n    maxAge: retention.age ? parse(retention.age) : 0,\n    maxCount: retention.count ?? 0,\n  }\n}\n\nexport function parse(duration: Duration): number {\n  if (typeof duration === 'number') {\n    return duration\n  }\n\n  const milliseconds = parseDuration(duration)\n\n  if (typeof milliseconds === 'undefined') {\n    throw new errors.E_INVALID_DURATION_EXPRESSION([duration])\n  }\n\n  return milliseconds\n}\n\n/**\n * Calculate the score for job ordering in the queue.\n * Lower scores are processed first.\n *\n * @param priority - Job priority (1-10, lower = higher priority)\n * @param timestamp - Timestamp in milliseconds\n * @returns Score for queue ordering\n */\nexport function calculateScore(priority: number, timestamp: number): number {\n  return priority * PRIORITY_SCORE_MULTIPLIER + timestamp\n}\n"],"mappings":";;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAAS,mBAAmB;AAErB,IAAM,gCAAgC;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AACF;AAEO,IAAM,6BAA6B;AAAA,EACxC;AAAA,EACA;AACF;AAEO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;AAEO,IAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;;;ACxEO,IAAM,mBAAmB;AASzB,IAAM,4BAA4B;AAKlC,IAAM,qBAAqB;AAK3B,IAAM,2BAA2B;AAKjC,IAAM,4BAA4B;AAKlC,IAAM,4BAA4B;;;AChCzC,SAAS,SAAS,qBAAqB;AAWhC,SAAS,iBAAiB,WAA6C;AAC5E,MAAI,cAAc,UAAa,cAAc,MAAM;AACjD,WAAO,EAAE,MAAM,OAAO,QAAQ,GAAG,UAAU,EAAE;AAAA,EAC/C;AAEA,MAAI,cAAc,OAAO;AACvB,WAAO,EAAE,MAAM,MAAM,QAAQ,GAAG,UAAU,EAAE;AAAA,EAC9C;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,UAAU,MAAM,MAAM,UAAU,GAAG,IAAI;AAAA,IAC/C,UAAU,UAAU,SAAS;AAAA,EAC/B;AACF;AAEO,SAAS,MAAM,UAA4B;AAChD,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AAEA,QAAM,eAAe,cAAc,QAAQ;AAE3C,MAAI,OAAO,iBAAiB,aAAa;AACvC,UAAM,IAAW,8BAA8B,CAAC,QAAQ,CAAC;AAAA,EAC3D;AAEA,SAAO;AACT;AAUO,SAAS,eAAe,UAAkB,WAA2B;AAC1E,SAAO,WAAW,4BAA4B;AAChD;","names":[]}
+{"version":3,"sources":["../src/exceptions.ts","../src/constants.ts","../src/utils.ts"],"sourcesContent":["import { createError } from '@poppinss/utils/exception'\n\nexport const E_INVALID_DURATION_EXPRESSION = createError(\n  'Invalid duration expression: \"%s\"',\n  'E_INVALID_DURATION_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_BASE_DELAY = createError<[reason: string]>(\n  'Invalid base delay. Reason: %s',\n  'E_INVALID_BASE_DELAY',\n  500\n)\n\nexport const E_INVALID_MAX_DELAY = createError<[reason: string]>(\n  'Invalid max delay. Reason: %s',\n  'E_INVALID_MAX_DELAY',\n  500\n)\n\nexport const E_INVALID_MULTIPLIER = createError<[reason: string]>(\n  'Invalid multiplier. Reason: %s',\n  'E_INVALID_MULTIPLIER',\n  500\n)\n\nexport const E_CONFIGURATION_ERROR = createError<[reason: string]>(\n  'Configuration error. Reason: %s',\n  'E_CONFIGURATION_ERROR',\n  500\n)\n\nexport const E_JOB_NOT_FOUND = createError<[jobName: string]>(\n  'Requested job \"%s\" is not registered',\n  'E_JOB_NOT_FOUND'\n)\n\nexport const E_JOB_MAX_ATTEMPTS_REACHED = createError<[jobName: string]>(\n  'The job \"%s\" has reached the maximum number of retry attempts',\n  'E_JOB_MAX_ATTEMPTS_REACHED'\n)\n\nexport const E_JOB_TIMEOUT = createError<[jobName: string, timeout: number]>(\n  'The job \"%s\" has exceeded the timeout of %dms',\n  'E_JOB_TIMEOUT'\n)\n\nexport const E_QUEUE_NOT_INITIALIZED = createError(\n  'QueueManager is not initialized. Call QueueManager.init() before using it.',\n  'E_QUEUE_NOT_INITIALIZED',\n  500\n)\n\nexport const E_ADAPTER_INIT_ERROR = createError<[adapterName: string, originalMessage: string]>(\n  'Failed to initialize adapter \"%s\". Reason: %s',\n  'E_ADAPTER_INIT_ERROR',\n  500\n)\n\nexport const E_NO_JOBS_FOUND = createError<[patterns: string]>(\n  'No jobs found for the specified locations: %s. Verify your glob patterns match your job files.',\n  'E_NO_JOBS_FOUND',\n  500\n)\n\nexport const E_INVALID_CRON_EXPRESSION = createError<[expression: string, reason: string]>(\n  'Invalid cron expression \"%s\": %s',\n  'E_INVALID_CRON_EXPRESSION',\n  500\n)\n\nexport const E_INVALID_SCHEDULE_CONFIG = createError<[reason: string]>(\n  'Invalid schedule configuration: %s',\n  'E_INVALID_SCHEDULE_CONFIG',\n  500\n)\n","/**\n * Default job priority (1-10 scale, lower = higher priority)\n */\nexport const DEFAULT_PRIORITY = 5\n\n/**\n * Multiplier used in score calculation: priority * multiplier + timestamp\n *\n * This ensures higher priority jobs are processed first,\n * while preserving FIFO order within the same priority.\n * The value (1e13) leaves room for ~300 years of millisecond timestamps.\n */\nexport const PRIORITY_SCORE_MULTIPLIER = 1e13\n\n/**\n * Default delay when the worker is idle (no jobs in queue)\n */\nexport const DEFAULT_IDLE_DELAY = '2s'\n\n/**\n * Default interval between stalled job checks\n */\nexport const DEFAULT_STALLED_INTERVAL = '30s'\n\n/**\n * Default threshold after which a job is considered stalled\n */\nexport const DEFAULT_STALLED_THRESHOLD = '30s'\n\n/**\n * Default delay before retrying after an error\n */\nexport const DEFAULT_ERROR_RETRY_DELAY = '5s'\n","import { parse as parseDuration } from '@lukeed/ms'\nimport type { Duration, JobRetention } from './types/main.js'\nimport * as errors from './exceptions.js'\nimport { PRIORITY_SCORE_MULTIPLIER } from './constants.js'\n\nexport interface ResolvedRetention {\n  keep: boolean\n  maxAge: number\n  maxCount: number\n}\n\nexport function resolveRetention(retention?: JobRetention): ResolvedRetention {\n  if (retention === undefined || retention === true) {\n    return { keep: false, maxAge: 0, maxCount: 0 }\n  }\n\n  if (retention === false) {\n    return { keep: true, maxAge: 0, maxCount: 0 }\n  }\n\n  return {\n    keep: true,\n    maxAge: retention.age ? parse(retention.age) : 0,\n    maxCount: retention.count ?? 0,\n  }\n}\n\nexport function parse(duration: Duration): number {\n  if (typeof duration === 'number') {\n    return duration\n  }\n\n  const milliseconds = parseDuration(duration)\n\n  if (typeof milliseconds === 'undefined') {\n    throw new errors.E_INVALID_DURATION_EXPRESSION([duration])\n  }\n\n  return milliseconds\n}\n\n/**\n * Calculate the score for job ordering in the queue.\n * Lower scores are processed first.\n *\n * @param priority - Job priority (1-10, lower = higher priority)\n * @param timestamp - Timestamp in milliseconds\n * @returns Score for queue ordering\n */\nexport function calculateScore(priority: number, timestamp: number): number {\n  return priority * PRIORITY_SCORE_MULTIPLIER + timestamp\n}\n"],"mappings":";;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAAS,mBAAmB;AAErB,IAAM,gCAAgC;AAAA,EAC3C;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,sBAAsB;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AACF;AAEO,IAAM,6BAA6B;AAAA,EACxC;AAAA,EACA;AACF;AAEO,IAAM,gBAAgB;AAAA,EAC3B;AAAA,EACA;AACF;AAEO,IAAM,0BAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,kBAAkB;AAAA,EAC7B;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;AAEO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AACF;;;ACxEO,IAAM,mBAAmB;AASzB,IAAM,4BAA4B;AAKlC,IAAM,qBAAqB;AAK3B,IAAM,2BAA2B;AAKjC,IAAM,4BAA4B;AAKlC,IAAM,4BAA4B;;;AChCzC,SAAS,SAAS,qBAAqB;AAWhC,SAAS,iBAAiB,WAA6C;AAC5E,MAAI,cAAc,UAAa,cAAc,MAAM;AACjD,WAAO,EAAE,MAAM,OAAO,QAAQ,GAAG,UAAU,EAAE;AAAA,EAC/C;AAEA,MAAI,cAAc,OAAO;AACvB,WAAO,EAAE,MAAM,MAAM,QAAQ,GAAG,UAAU,EAAE;AAAA,EAC9C;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,QAAQ,UAAU,MAAM,MAAM,UAAU,GAAG,IAAI;AAAA,IAC/C,UAAU,UAAU,SAAS;AAAA,EAC/B;AACF;AAEO,SAAS,MAAM,UAA4B;AAChD,MAAI,OAAO,aAAa,UAAU;AAChC,WAAO;AAAA,EACT;AAEA,QAAM,eAAe,cAAc,QAAQ;AAE3C,MAAI,OAAO,iBAAiB,aAAa;AACvC,UAAM,IAAW,8BAA8B,CAAC,QAAQ,CAAC;AAAA,EAC3D;AAEA,SAAO;AACT;AAUO,SAAS,eAAe,UAAkB,WAA2B;AAC1E,SAAO,WAAW,4BAA4B;AAChD;","names":[]}

package/build/{chunk-OVYXMSSU.js → chunk-VRXHCWNK.js}

@@ -1,3 +1,6 @@
+import {
+  dispatchChannel
+} from "./chunk-WVLSICD4.js";
 import {
   DEFAULT_PRIORITY,
   E_ADAPTER_INIT_ERROR,
@@ -7,7 +10,7 @@ import {
   E_JOB_NOT_FOUND,
   E_QUEUE_NOT_INITIALIZED,
   parse
-} from "./chunk-ZZFSQY36.js";
+} from "./chunk-QEFYHCL7.js";
 
 // src/drivers/fake_adapter.ts
 import assert from "assert/strict";
@@ -260,6 +263,8 @@ var QueueConfigResolver = class _QueueConfigResolver {
 };
 
 // src/queue_manager.ts
+var noopInternalOperationWrapper = async (fn) => fn();
+var noopExecutionWrapper = async (fn) => fn();
 var QueueManagerSingleton = class {
   #initialized = false;
   #defaultAdapter;
@@ -267,7 +272,10 @@ var QueueManagerSingleton = class {
   #adapterInstances = /* @__PURE__ */ new Map();
   #logger = consoleLogger;
   #jobFactory;
+  #internalOperationWrapper;
+  #executionWrapper;
   #configResolver = new QueueConfigResolver({});
+  #locations = [];
   #fakeState;
   /**
    * Initialize the queue system with the given configuration.
@@ -301,18 +309,46 @@ var QueueManagerSingleton = class {
     this.#adapters = config.adapters;
     this.#logger = config.logger ?? consoleLogger;
     this.#jobFactory = config.jobFactory;
+    this.#internalOperationWrapper = config.internalOperationWrapper;
+    this.#executionWrapper = config.executionWrapper;
     this.#configResolver = QueueConfigResolver.from(config);
-    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.`
-        );
-      }
+    this.#locations = config.locations ?? [];
+    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 = this.#locations) {
+    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.
@@ -397,19 +433,18 @@ var QueueManagerSingleton = class {
    * Replace all adapters with a fake adapter for testing.
    *
    * The fake adapter records pushed jobs and exposes assertion helpers.
-   * Call `restore()` to return to the previous configuration.
-   *
-   * @returns The fake adapter instance for assertions
-   * @throws {E_QUEUE_NOT_INITIALIZED} If `init()` hasn't been called
+   * Use the `using` keyword to automatically restore the previous
+   * configuration when the variable goes out of scope, or call
+   * `restore()` manually.
    *
    * @example
    * ```typescript
-   * const fake = QueueManager.fake()
+   * using fake = QueueManager.fake()
    *
    * await SendEmailJob.dispatch({ to: 'user@example.com' })
    *
    * fake.assertPushed(SendEmailJob)
-   * QueueManager.restore()
+   * // Automatically restored at end of scope
    * ```
    */
   fake() {
@@ -420,13 +455,17 @@ var QueueManagerSingleton = class {
       return this.#fakeState.fakeAdapter;
     }
     const fakeAdapter = new FakeAdapter();
+    fakeAdapter.onDispose(() => this.restore());
     this.#fakeState = {
       defaultAdapter: this.#defaultAdapter,
       adapters: this.#adapters,
       adapterInstances: this.#adapterInstances,
       logger: this.#logger,
       jobFactory: this.#jobFactory,
+      internalOperationWrapper: this.#internalOperationWrapper,
+      executionWrapper: this.#executionWrapper,
       configResolver: this.#configResolver,
+      locations: this.#locations,
       fakeAdapter
     };
     const fakeFactory = () => fakeAdapter;
@@ -456,7 +495,10 @@ var QueueManagerSingleton = class {
     this.#adapterInstances = state.adapterInstances;
     this.#logger = state.logger;
     this.#jobFactory = state.jobFactory;
+    this.#internalOperationWrapper = state.internalOperationWrapper;
+    this.#executionWrapper = state.executionWrapper;
     this.#configResolver = state.configResolver;
+    this.#locations = state.locations;
   }
   /**
    * Get the configured job factory for custom instantiation.
@@ -466,12 +508,30 @@ var QueueManagerSingleton = class {
   getJobFactory() {
     return this.#jobFactory;
   }
+  /**
+   * Whether the queue manager has been initialized.
+   */
+  isInitialized() {
+    return this.#initialized;
+  }
   /**
    * Get the configured logger used by the queue runtime.
    */
   getLogger() {
     return this.#logger;
   }
+  /**
+   * Get the configured internal operation wrapper.
+   */
+  getInternalOperationWrapper() {
+    return this.#internalOperationWrapper ?? noopInternalOperationWrapper;
+  }
+  /**
+   * Get the configured execution wrapper.
+   */
+  getExecutionWrapper() {
+    return this.#executionWrapper ?? noopExecutionWrapper;
+  }
   /**
    * Get the resolver responsible for effective queue/job runtime config.
    */
@@ -525,7 +585,10 @@ var QueueManagerSingleton = class {
     }
     this.#adapterInstances.clear();
     this.#initialized = false;
+    this.#internalOperationWrapper = void 0;
+    this.#executionWrapper = void 0;
     this.#configResolver = new QueueConfigResolver({});
+    this.#locations = [];
     this.#fakeState = void 0;
   }
 };
@@ -665,23 +728,26 @@ var JobDispatcher = class {
     const id = randomUUID();
     debug_default("dispatching job %s with id %s using payload %s", this.#name, id, this.#payload);
     const adapter = this.#getAdapterInstance();
-    const payload = {
+    const wrapInternal = QueueManager.getInternalOperationWrapper();
+    const parsedDelay = this.#delay ? parse(this.#delay) : void 0;
+    const jobData = {
       id,
       name: this.#name,
       payload: this.#payload,
       attempts: 0,
       priority: this.#priority,
-      groupId: this.#groupId
-    };
-    if (this.#delay) {
-      const parsedDelay = parse(this.#delay);
-      await adapter.pushLaterOn(this.#queue, payload, parsedDelay);
-    } else {
-      await adapter.pushOn(this.#queue, payload);
-    }
-    return {
-      jobId: id
+      groupId: this.#groupId,
+      createdAt: Date.now()
     };
+    const message = { jobs: [jobData], queue: this.#queue, delay: parsedDelay };
+    await dispatchChannel.tracePromise(async () => {
+      if (parsedDelay !== void 0) {
+        await wrapInternal(() => adapter.pushLaterOn(this.#queue, jobData, parsedDelay));
+      } else {
+        await wrapInternal(() => adapter.pushOn(this.#queue, jobData));
+      }
+    }, message);
+    return { jobId: id };
   }
   /**
    * Thenable implementation for auto-dispatch when awaited.
@@ -806,20 +872,25 @@ var JobBatchDispatcher = class {
    * ```
    */
   async run() {
+    if (this.#payloads.length === 0) return { jobIds: [] };
     debug_default("dispatching %d jobs of type %s", this.#payloads.length, this.#name);
     const adapter = this.#getAdapterInstance();
+    const wrapInternal = QueueManager.getInternalOperationWrapper();
+    const now = Date.now();
     const jobs = this.#payloads.map((payload) => ({
       id: randomUUID2(),
       name: this.#name,
       payload,
       attempts: 0,
       priority: this.#priority,
-      groupId: this.#groupId
+      groupId: this.#groupId,
+      createdAt: now
     }));
-    await adapter.pushManyOn(this.#queue, jobs);
-    return {
-      jobIds: jobs.map((job) => job.id)
-    };
+    const message = { jobs, queue: this.#queue };
+    await dispatchChannel.tracePromise(async () => {
+      await wrapInternal(() => adapter.pushManyOn(this.#queue, jobs));
+    }, message);
+    return { jobIds: jobs.map((job) => job.id) };
   }
   /**
    * Thenable implementation for auto-dispatch when awaited.
@@ -1226,6 +1297,17 @@ var FakeAdapter = class {
   #pendingTimeouts = /* @__PURE__ */ new Set();
   #schedules = /* @__PURE__ */ new Map();
   #pushedJobs = [];
+  #onDispose;
+  /**
+   * Set the function to call when the fake is disposed
+   */
+  onDispose(fn) {
+    this.#onDispose = fn;
+    return this;
+  }
+  [Symbol.dispose]() {
+    this.#onDispose?.();
+  }
   setWorkerId(_workerId) {
   }
   getPushedJobs() {
@@ -1639,4 +1721,4 @@ export {
   ScheduleBuilder,
   Job
 };
-//# sourceMappingURL=chunk-OVYXMSSU.js.map
+//# sourceMappingURL=chunk-VRXHCWNK.js.map