@open-mercato/queue 0.6.6-develop.6507.1.cc8b36505d → 0.6.6-develop.6515.1.01911d00e2

package/dist/worker/runner.js

@@ -2,6 +2,7 @@ import { createQueue } from "../factory.js";
 import { createLogger } from "@open-mercato/shared/lib/logger";
 const logger = createLogger("queue").child({ component: "worker" });
 const managedQueues = /* @__PURE__ */ new Set();
+const managedShutdownHooks = /* @__PURE__ */ new Set();
 let shutdownHandlersRegistered = false;
 let shutdownInProgress = false;
 function unregisterShutdownHandlers(sigtermHandler, sigintHandler) {
@@ -25,6 +26,15 @@ function registerShutdownHandlers() {
       }
     }
     managedQueues.clear();
+    for (const hook of managedShutdownHooks) {
+      try {
+        await hook();
+      } catch (error) {
+        hasError = true;
+        logger.error("Error during shutdown hook", { err: error });
+      }
+    }
+    managedShutdownHooks.clear();
     unregisterShutdownHandlers(sigtermHandler, sigintHandler);
     shutdownInProgress = false;
     if (!hasError) {
@@ -42,6 +52,10 @@ function registerShutdownHandlers() {
   process.on("SIGINT", sigintHandler);
   shutdownHandlersRegistered = true;
 }
+function registerWorkerShutdownHook(hook) {
+  managedShutdownHooks.add(hook);
+  return () => managedShutdownHooks.delete(hook);
+}
 async function runWorker(options) {
   const {
     queueName,
@@ -84,6 +98,7 @@ function createRoutedHandler(handlers) {
 }
 export {
   createRoutedHandler,
+  registerWorkerShutdownHook,
   runWorker
 };
 //# sourceMappingURL=runner.js.map

package/dist/worker/runner.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/worker/runner.ts"],
-  "sourcesContent": ["import { createQueue } from '../factory'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport type { Queue, JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'\n\nconst logger = createLogger('queue').child({ component: 'worker' })\n\n/**\n * Options for running a queue worker.\n */\nexport type WorkerRunnerOptions<T = unknown> = {\n  /** Name of the queue to process */\n  queueName: string\n  /** Handler function to process each job */\n  handler: JobHandler<T>\n  /** Redis connection options (only used for async strategy) */\n  connection?: AsyncQueueOptions['connection']\n  /** Number of concurrent jobs to process */\n  concurrency?: number\n  /** Whether to set up graceful shutdown handlers */\n  gracefulShutdown?: boolean\n  /** If true, don't block - return immediately after starting processing (for multi-queue mode) */\n  background?: boolean\n  /** Queue strategy to use. Defaults to QUEUE_STRATEGY env var or 'local' */\n  strategy?: QueueStrategyType\n}\n\nconst managedQueues = new Set<Queue<unknown>>()\nlet shutdownHandlersRegistered = false\nlet shutdownInProgress = false\n\nfunction unregisterShutdownHandlers(sigtermHandler: () => void, sigintHandler: () => void): void {\n  process.off('SIGTERM', sigtermHandler)\n  process.off('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = false\n}\n\nfunction registerShutdownHandlers(): void {\n  if (shutdownHandlersRegistered) return\n\n  const shutdown = async (signal: string) => {\n    if (shutdownInProgress) return\n    shutdownInProgress = true\n\n    logger.info('Received signal, shutting down gracefully', { signal })\n\n    let hasError = false\n    for (const queue of managedQueues) {\n      try {\n        await queue.close()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown', { err: error })\n      }\n    }\n\n    managedQueues.clear()\n    unregisterShutdownHandlers(sigtermHandler, sigintHandler)\n    shutdownInProgress = false\n\n    if (!hasError) {\n      logger.info('Worker closed successfully')\n    }\n\n    process.exit(hasError ? 1 : 0)\n  }\n\n  const sigtermHandler = () => {\n    void shutdown('SIGTERM')\n  }\n\n  const sigintHandler = () => {\n    void shutdown('SIGINT')\n  }\n\n  process.on('SIGTERM', sigtermHandler)\n  process.on('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = true\n}\n\n/**\n * Runs a queue worker that processes jobs continuously.\n *\n * This function:\n * 1. Creates an async queue instance\n * 2. Starts a BullMQ worker\n * 3. Sets up graceful shutdown on SIGTERM/SIGINT\n * 4. Keeps the process running until shutdown\n *\n * @template T - The job payload type\n * @param options - Worker configuration\n *\n * @example\n * ```typescript\n * import { runWorker } from '@open-mercato/queue/worker'\n *\n * await runWorker({\n *   queueName: 'events',\n *   handler: async (job, ctx) => {\n *     console.log(`Processing ${ctx.jobId}:`, job.payload)\n *   },\n *   connection: { url: process.env.REDIS_URL },\n *   concurrency: 5,\n * })\n * ```\n */\nexport async function runWorker<T = unknown>(\n  options: WorkerRunnerOptions<T>\n): Promise<void> {\n  const {\n    queueName,\n    handler,\n    connection,\n    concurrency = 1,\n    gracefulShutdown = true,\n    background = false,\n    strategy: strategyOption,\n  } = options\n\n  // Determine queue strategy from option, env var, or default to 'local'\n  const strategy: QueueStrategyType = strategyOption\n    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  logger.info('Starting worker for queue', { queueName, strategy })\n\n  const queue = createQueue<T>(queueName, strategy, {\n    connection,\n    concurrency,\n  })\n\n  // Set up graceful shutdown\n  if (gracefulShutdown) {\n    managedQueues.add(queue as Queue<unknown>)\n    registerShutdownHandlers()\n  }\n\n  // Start processing\n  await queue.process(handler)\n\n  logger.info('Worker running', { concurrency })\n\n  if (background) {\n    // Return immediately for multi-queue mode\n    return\n  }\n\n  logger.info('Press Ctrl+C to stop')\n\n  // Keep the process alive (single-queue mode)\n  await new Promise(() => {\n    // This promise never resolves, keeping the worker running\n  })\n}\n\n/**\n * Creates a worker handler that routes jobs to specific handlers based on job type.\n *\n * @template T - Base job payload type (must include a 'type' field)\n * @param handlers - Map of job types to their handlers\n *\n * @example\n * ```typescript\n * const handler = createRoutedHandler({\n *   'user.created': async (job) => { ... },\n *   'order.placed': async (job) => { ... },\n * })\n *\n * await runWorker({ queueName: 'events', handler })\n * ```\n */\nexport function createRoutedHandler<T extends { type: string }>(\n  handlers: Record<string, JobHandler<T>>\n): JobHandler<T> {\n  return async (job, ctx) => {\n    const type = job.payload.type\n    const handler = handlers[type]\n\n    if (!handler) {\n      logger.warn('No handler registered for job type', { type })\n      return\n    }\n\n    await handler(job, ctx)\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,mBAAmB;AAC5B,SAAS,oBAAoB;AAG7B,MAAM,SAAS,aAAa,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,CAAC;AAsBlE,MAAM,gBAAgB,oBAAI,IAAoB;AAC9C,IAAI,6BAA6B;AACjC,IAAI,qBAAqB;AAEzB,SAAS,2BAA2B,gBAA4B,eAAiC;AAC/F,UAAQ,IAAI,WAAW,cAAc;AACrC,UAAQ,IAAI,UAAU,aAAa;AACnC,+BAA6B;AAC/B;AAEA,SAAS,2BAAiC;AACxC,MAAI,2BAA4B;AAEhC,QAAM,WAAW,OAAO,WAAmB;AACzC,QAAI,mBAAoB;AACxB,yBAAqB;AAErB,WAAO,KAAK,6CAA6C,EAAE,OAAO,CAAC;AAEnE,QAAI,WAAW;AACf,eAAW,SAAS,eAAe;AACjC,UAAI;AACF,cAAM,MAAM,MAAM;AAAA,MACpB,SAAS,OAAO;AACd,mBAAW;AACX,eAAO,MAAM,yBAAyB,EAAE,KAAK,MAAM,CAAC;AAAA,MACtD;AAAA,IACF;AAEA,kBAAc,MAAM;AACpB,+BAA2B,gBAAgB,aAAa;AACxD,yBAAqB;AAErB,QAAI,CAAC,UAAU;AACb,aAAO,KAAK,4BAA4B;AAAA,IAC1C;AAEA,YAAQ,KAAK,WAAW,IAAI,CAAC;AAAA,EAC/B;AAEA,QAAM,iBAAiB,MAAM;AAC3B,SAAK,SAAS,SAAS;AAAA,EACzB;AAEA,QAAM,gBAAgB,MAAM;AAC1B,SAAK,SAAS,QAAQ;AAAA,EACxB;AAEA,UAAQ,GAAG,WAAW,cAAc;AACpC,UAAQ,GAAG,UAAU,aAAa;AAClC,+BAA6B;AAC/B;AA4BA,eAAsB,UACpB,SACe;AACf,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,IACd,mBAAmB;AAAA,IACnB,aAAa;AAAA,IACb,UAAU;AAAA,EACZ,IAAI;AAGJ,QAAM,WAA8B,mBAC9B,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAEzD,SAAO,KAAK,6BAA6B,EAAE,WAAW,SAAS,CAAC;AAEhE,QAAM,QAAQ,YAAe,WAAW,UAAU;AAAA,IAChD;AAAA,IACA;AAAA,EACF,CAAC;AAGD,MAAI,kBAAkB;AACpB,kBAAc,IAAI,KAAuB;AACzC,6BAAyB;AAAA,EAC3B;AAGA,QAAM,MAAM,QAAQ,OAAO;AAE3B,SAAO,KAAK,kBAAkB,EAAE,YAAY,CAAC;AAE7C,MAAI,YAAY;AAEd;AAAA,EACF;AAEA,SAAO,KAAK,sBAAsB;AAGlC,QAAM,IAAI,QAAQ,MAAM;AAAA,EAExB,CAAC;AACH;AAkBO,SAAS,oBACd,UACe;AACf,SAAO,OAAO,KAAK,QAAQ;AACzB,UAAM,OAAO,IAAI,QAAQ;AACzB,UAAM,UAAU,SAAS,IAAI;AAE7B,QAAI,CAAC,SAAS;AACZ,aAAO,KAAK,sCAAsC,EAAE,KAAK,CAAC;AAC1D;AAAA,IACF;AAEA,UAAM,QAAQ,KAAK,GAAG;AAAA,EACxB;AACF;",
+  "sourcesContent": ["import { createQueue } from '../factory'\nimport { createLogger } from '@open-mercato/shared/lib/logger'\nimport type { Queue, JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'\n\nconst logger = createLogger('queue').child({ component: 'worker' })\n\n/**\n * Options for running a queue worker.\n */\nexport type WorkerRunnerOptions<T = unknown> = {\n  /** Name of the queue to process */\n  queueName: string\n  /** Handler function to process each job */\n  handler: JobHandler<T>\n  /** Redis connection options (only used for async strategy) */\n  connection?: AsyncQueueOptions['connection']\n  /** Number of concurrent jobs to process */\n  concurrency?: number\n  /** Whether to set up graceful shutdown handlers */\n  gracefulShutdown?: boolean\n  /** If true, don't block - return immediately after starting processing (for multi-queue mode) */\n  background?: boolean\n  /** Queue strategy to use. Defaults to QUEUE_STRATEGY env var or 'local' */\n  strategy?: QueueStrategyType\n}\n\nconst managedQueues = new Set<Queue<unknown>>()\nconst managedShutdownHooks = new Set<() => Promise<void> | void>()\nlet shutdownHandlersRegistered = false\nlet shutdownInProgress = false\n\nfunction unregisterShutdownHandlers(sigtermHandler: () => void, sigintHandler: () => void): void {\n  process.off('SIGTERM', sigtermHandler)\n  process.off('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = false\n}\n\nfunction registerShutdownHandlers(): void {\n  if (shutdownHandlersRegistered) return\n\n  const shutdown = async (signal: string) => {\n    if (shutdownInProgress) return\n    shutdownInProgress = true\n\n    logger.info('Received signal, shutting down gracefully', { signal })\n\n    let hasError = false\n    for (const queue of managedQueues) {\n      try {\n        await queue.close()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown', { err: error })\n      }\n    }\n\n    managedQueues.clear()\n    for (const hook of managedShutdownHooks) {\n      try {\n        await hook()\n      } catch (error) {\n        hasError = true\n        logger.error('Error during shutdown hook', { err: error })\n      }\n    }\n    managedShutdownHooks.clear()\n    unregisterShutdownHandlers(sigtermHandler, sigintHandler)\n    shutdownInProgress = false\n\n    if (!hasError) {\n      logger.info('Worker closed successfully')\n    }\n\n    process.exit(hasError ? 1 : 0)\n  }\n\n  const sigtermHandler = () => {\n    void shutdown('SIGTERM')\n  }\n\n  const sigintHandler = () => {\n    void shutdown('SIGINT')\n  }\n\n  process.on('SIGTERM', sigtermHandler)\n  process.on('SIGINT', sigintHandler)\n  shutdownHandlersRegistered = true\n}\n\n/**\n * Register a process-local service that must stop before a worker exits.\n * The returned callback removes the hook when the service is stopped early.\n */\nexport function registerWorkerShutdownHook(hook: () => Promise<void> | void): () => void {\n  managedShutdownHooks.add(hook)\n  return () => managedShutdownHooks.delete(hook)\n}\n\n/**\n * Runs a queue worker that processes jobs continuously.\n *\n * This function:\n * 1. Creates an async queue instance\n * 2. Starts a BullMQ worker\n * 3. Sets up graceful shutdown on SIGTERM/SIGINT\n * 4. Keeps the process running until shutdown\n *\n * @template T - The job payload type\n * @param options - Worker configuration\n *\n * @example\n * ```typescript\n * import { runWorker } from '@open-mercato/queue/worker'\n *\n * await runWorker({\n *   queueName: 'events',\n *   handler: async (job, ctx) => {\n *     console.log(`Processing ${ctx.jobId}:`, job.payload)\n *   },\n *   connection: { url: process.env.REDIS_URL },\n *   concurrency: 5,\n * })\n * ```\n */\nexport async function runWorker<T = unknown>(\n  options: WorkerRunnerOptions<T>\n): Promise<void> {\n  const {\n    queueName,\n    handler,\n    connection,\n    concurrency = 1,\n    gracefulShutdown = true,\n    background = false,\n    strategy: strategyOption,\n  } = options\n\n  // Determine queue strategy from option, env var, or default to 'local'\n  const strategy: QueueStrategyType = strategyOption\n    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')\n\n  logger.info('Starting worker for queue', { queueName, strategy })\n\n  const queue = createQueue<T>(queueName, strategy, {\n    connection,\n    concurrency,\n  })\n\n  // Set up graceful shutdown\n  if (gracefulShutdown) {\n    managedQueues.add(queue as Queue<unknown>)\n    registerShutdownHandlers()\n  }\n\n  // Start processing\n  await queue.process(handler)\n\n  logger.info('Worker running', { concurrency })\n\n  if (background) {\n    // Return immediately for multi-queue mode\n    return\n  }\n\n  logger.info('Press Ctrl+C to stop')\n\n  // Keep the process alive (single-queue mode)\n  await new Promise(() => {\n    // This promise never resolves, keeping the worker running\n  })\n}\n\n/**\n * Creates a worker handler that routes jobs to specific handlers based on job type.\n *\n * @template T - Base job payload type (must include a 'type' field)\n * @param handlers - Map of job types to their handlers\n *\n * @example\n * ```typescript\n * const handler = createRoutedHandler({\n *   'user.created': async (job) => { ... },\n *   'order.placed': async (job) => { ... },\n * })\n *\n * await runWorker({ queueName: 'events', handler })\n * ```\n */\nexport function createRoutedHandler<T extends { type: string }>(\n  handlers: Record<string, JobHandler<T>>\n): JobHandler<T> {\n  return async (job, ctx) => {\n    const type = job.payload.type\n    const handler = handlers[type]\n\n    if (!handler) {\n      logger.warn('No handler registered for job type', { type })\n      return\n    }\n\n    await handler(job, ctx)\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,mBAAmB;AAC5B,SAAS,oBAAoB;AAG7B,MAAM,SAAS,aAAa,OAAO,EAAE,MAAM,EAAE,WAAW,SAAS,CAAC;AAsBlE,MAAM,gBAAgB,oBAAI,IAAoB;AAC9C,MAAM,uBAAuB,oBAAI,IAAgC;AACjE,IAAI,6BAA6B;AACjC,IAAI,qBAAqB;AAEzB,SAAS,2BAA2B,gBAA4B,eAAiC;AAC/F,UAAQ,IAAI,WAAW,cAAc;AACrC,UAAQ,IAAI,UAAU,aAAa;AACnC,+BAA6B;AAC/B;AAEA,SAAS,2BAAiC;AACxC,MAAI,2BAA4B;AAEhC,QAAM,WAAW,OAAO,WAAmB;AACzC,QAAI,mBAAoB;AACxB,yBAAqB;AAErB,WAAO,KAAK,6CAA6C,EAAE,OAAO,CAAC;AAEnE,QAAI,WAAW;AACf,eAAW,SAAS,eAAe;AACjC,UAAI;AACF,cAAM,MAAM,MAAM;AAAA,MACpB,SAAS,OAAO;AACd,mBAAW;AACX,eAAO,MAAM,yBAAyB,EAAE,KAAK,MAAM,CAAC;AAAA,MACtD;AAAA,IACF;AAEA,kBAAc,MAAM;AACpB,eAAW,QAAQ,sBAAsB;AACvC,UAAI;AACF,cAAM,KAAK;AAAA,MACb,SAAS,OAAO;AACd,mBAAW;AACX,eAAO,MAAM,8BAA8B,EAAE,KAAK,MAAM,CAAC;AAAA,MAC3D;AAAA,IACF;AACA,yBAAqB,MAAM;AAC3B,+BAA2B,gBAAgB,aAAa;AACxD,yBAAqB;AAErB,QAAI,CAAC,UAAU;AACb,aAAO,KAAK,4BAA4B;AAAA,IAC1C;AAEA,YAAQ,KAAK,WAAW,IAAI,CAAC;AAAA,EAC/B;AAEA,QAAM,iBAAiB,MAAM;AAC3B,SAAK,SAAS,SAAS;AAAA,EACzB;AAEA,QAAM,gBAAgB,MAAM;AAC1B,SAAK,SAAS,QAAQ;AAAA,EACxB;AAEA,UAAQ,GAAG,WAAW,cAAc;AACpC,UAAQ,GAAG,UAAU,aAAa;AAClC,+BAA6B;AAC/B;AAMO,SAAS,2BAA2B,MAA8C;AACvF,uBAAqB,IAAI,IAAI;AAC7B,SAAO,MAAM,qBAAqB,OAAO,IAAI;AAC/C;AA4BA,eAAsB,UACpB,SACe;AACf,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,IACd,mBAAmB;AAAA,IACnB,aAAa;AAAA,IACb,UAAU;AAAA,EACZ,IAAI;AAGJ,QAAM,WAA8B,mBAC9B,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAEzD,SAAO,KAAK,6BAA6B,EAAE,WAAW,SAAS,CAAC;AAEhE,QAAM,QAAQ,YAAe,WAAW,UAAU;AAAA,IAChD;AAAA,IACA;AAAA,EACF,CAAC;AAGD,MAAI,kBAAkB;AACpB,kBAAc,IAAI,KAAuB;AACzC,6BAAyB;AAAA,EAC3B;AAGA,QAAM,MAAM,QAAQ,OAAO;AAE3B,SAAO,KAAK,kBAAkB,EAAE,YAAY,CAAC;AAE7C,MAAI,YAAY;AAEd;AAAA,EACF;AAEA,SAAO,KAAK,sBAAsB;AAGlC,QAAM,IAAI,QAAQ,MAAM;AAAA,EAExB,CAAC;AACH;AAkBO,SAAS,oBACd,UACe;AACf,SAAO,OAAO,KAAK,QAAQ;AACzB,UAAM,OAAO,IAAI,QAAQ;AACzB,UAAM,UAAU,SAAS,IAAI;AAE7B,QAAI,CAAC,SAAS;AACZ,aAAO,KAAK,sCAAsC,EAAE,KAAK,CAAC;AAC1D;AAAA,IACF;AAEA,UAAM,QAAQ,KAAK,GAAG;AAAA,EACxB;AACF;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/queue",
-  "version": "0.6.6-develop.6507.1.cc8b36505d",
+  "version": "0.6.6-develop.6515.1.01911d00e2",
   "license": "MIT",
   "description": "Multi-strategy job queue with local and BullMQ support",
   "type": "module",
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@open-mercato/shared": "0.6.6-develop.6507.1.cc8b36505d"
+    "@open-mercato/shared": "0.6.6-develop.6515.1.01911d00e2"
   },
   "repository": {
     "type": "git",

package/src/worker/__tests__/runner.test.ts

@@ -1,6 +1,6 @@
 import { createQueue } from '../../factory'
 import type { Queue } from '../../types'
-import { runWorker } from '../runner'
+import { registerWorkerShutdownHook, runWorker } from '../runner'
 
 jest.mock('../../factory', () => ({
   createQueue: jest.fn(),
@@ -31,6 +31,7 @@ describe('runWorker', () => {
     createQueueMock.mockReturnValueOnce(queueA).mockReturnValueOnce(queueB)
 
     const exitSpy = jest.spyOn(process, 'exit').mockImplementation((() => undefined) as never)
+    const shutdownHook = jest.fn(async () => {})
     const initialSigtermListeners = process.listenerCount('SIGTERM')
     const initialSigintListeners = process.listenerCount('SIGINT')
 
@@ -47,6 +48,7 @@ describe('runWorker', () => {
       background: true,
       gracefulShutdown: true,
     })
+    registerWorkerShutdownHook(shutdownHook)
 
     expect(process.listenerCount('SIGTERM')).toBe(initialSigtermListeners + 1)
     expect(process.listenerCount('SIGINT')).toBe(initialSigintListeners + 1)
@@ -57,6 +59,7 @@ describe('runWorker', () => {
 
     expect(queueA.close).toHaveBeenCalledTimes(1)
     expect(queueB.close).toHaveBeenCalledTimes(1)
+    expect(shutdownHook).toHaveBeenCalledTimes(1)
     expect(exitSpy).toHaveBeenCalledWith(0)
     expect(process.listenerCount('SIGTERM')).toBe(initialSigtermListeners)
     expect(process.listenerCount('SIGINT')).toBe(initialSigintListeners)

package/src/worker/runner.ts

@@ -25,6 +25,7 @@ export type WorkerRunnerOptions<T = unknown> = {
 }
 
 const managedQueues = new Set<Queue<unknown>>()
+const managedShutdownHooks = new Set<() => Promise<void> | void>()
 let shutdownHandlersRegistered = false
 let shutdownInProgress = false
 
@@ -54,6 +55,15 @@ function registerShutdownHandlers(): void {
     }
 
     managedQueues.clear()
+    for (const hook of managedShutdownHooks) {
+      try {
+        await hook()
+      } catch (error) {
+        hasError = true
+        logger.error('Error during shutdown hook', { err: error })
+      }
+    }
+    managedShutdownHooks.clear()
     unregisterShutdownHandlers(sigtermHandler, sigintHandler)
     shutdownInProgress = false
 
@@ -77,6 +87,15 @@ function registerShutdownHandlers(): void {
   shutdownHandlersRegistered = true
 }
 
+/**
+ * Register a process-local service that must stop before a worker exits.
+ * The returned callback removes the hook when the service is stopped early.
+ */
+export function registerWorkerShutdownHook(hook: () => Promise<void> | void): () => void {
+  managedShutdownHooks.add(hook)
+  return () => managedShutdownHooks.delete(hook)
+}
+
 /**
  * Runs a queue worker that processes jobs continuously.
  *