@open-mercato/queue 0.4.11-develop.2235.49f509443f → 0.4.11-develop.2245.a1059680ca

package/dist/factory.js

@@ -1,12 +1,28 @@
 import { createLocalQueue } from "./strategies/local.js";
 import { createAsyncQueue } from "./strategies/async.js";
+import { getRedisUrlOrThrow } from "@open-mercato/shared/lib/redis/connection";
 function createQueue(name, strategy, options) {
   if (strategy === "async") {
     return createAsyncQueue(name, options);
   }
   return createLocalQueue(name, options);
 }
+function resolveQueueStrategy() {
+  return process.env.QUEUE_STRATEGY === "async" ? "async" : "local";
+}
+function createModuleQueue(name, options) {
+  const strategy = resolveQueueStrategy();
+  if (strategy === "async") {
+    return createAsyncQueue(name, {
+      connection: { url: getRedisUrlOrThrow("QUEUE") },
+      concurrency: options?.concurrency
+    });
+  }
+  return createLocalQueue(name, { concurrency: options?.concurrency });
+}
 export {
-  createQueue
+  createModuleQueue,
+  createQueue,
+  resolveQueueStrategy
 };
 //# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/factory.ts"],
-  "sourcesContent": ["import type { Queue, LocalQueueOptions, AsyncQueueOptions } from './types'\nimport { createLocalQueue } from './strategies/local'\nimport { createAsyncQueue } from './strategies/async'\n\n/**\n * Creates a queue instance with the specified strategy.\n *\n * @template T - The payload type for jobs in this queue\n * @param name - Unique name for the queue\n * @param strategy - Queue strategy: 'local' for file-based, 'async' for BullMQ\n * @param options - Strategy-specific options\n * @returns A Queue instance\n *\n * @example\n * ```typescript\n * // Local file-based queue\n * const localQueue = createQueue<MyJobData>('my-queue', 'local')\n *\n * // BullMQ-based queue\n * const asyncQueue = createQueue<MyJobData>('my-queue', 'async', {\n *   connection: { url: 'redis://localhost:6379' },\n *   concurrency: 5\n * })\n * ```\n */\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'local',\n  options?: LocalQueueOptions\n): Queue<T>\n\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'async',\n  options?: AsyncQueueOptions\n): Queue<T>\n\n// General overload for dynamic strategy (union type)\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'local' | 'async',\n  options?: LocalQueueOptions | AsyncQueueOptions\n): Queue<T>\n\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'local' | 'async',\n  options?: LocalQueueOptions | AsyncQueueOptions\n): Queue<T> {\n  if (strategy === 'async') {\n    return createAsyncQueue<T>(name, options as AsyncQueueOptions)\n  }\n\n  return createLocalQueue<T>(name, options as LocalQueueOptions)\n}\n"],
-  "mappings": "AACA,SAAS,wBAAwB;AACjC,SAAS,wBAAwB;AA0C1B,SAAS,YACd,MACA,UACA,SACU;AACV,MAAI,aAAa,SAAS;AACxB,WAAO,iBAAoB,MAAM,OAA4B;AAAA,EAC/D;AAEA,SAAO,iBAAoB,MAAM,OAA4B;AAC/D;",
+  "sourcesContent": ["import type { Queue, LocalQueueOptions, AsyncQueueOptions, QueueStrategyType } from './types'\nimport { createLocalQueue } from './strategies/local'\nimport { createAsyncQueue } from './strategies/async'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\n\n/**\n * Creates a queue instance with the specified strategy.\n *\n * @template T - The payload type for jobs in this queue\n * @param name - Unique name for the queue\n * @param strategy - Queue strategy: 'local' for file-based, 'async' for BullMQ\n * @param options - Strategy-specific options\n * @returns A Queue instance\n *\n * @example\n * ```typescript\n * // Local file-based queue\n * const localQueue = createQueue<MyJobData>('my-queue', 'local')\n *\n * // BullMQ-based queue\n * const asyncQueue = createQueue<MyJobData>('my-queue', 'async', {\n *   connection: { url: 'redis://localhost:6379' },\n *   concurrency: 5\n * })\n * ```\n */\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'local',\n  options?: LocalQueueOptions\n): Queue<T>\n\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'async',\n  options?: AsyncQueueOptions\n): Queue<T>\n\n// General overload for dynamic strategy (union type)\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'local' | 'async',\n  options?: LocalQueueOptions | AsyncQueueOptions\n): Queue<T>\n\nexport function createQueue<T = unknown>(\n  name: string,\n  strategy: 'local' | 'async',\n  options?: LocalQueueOptions | AsyncQueueOptions\n): Queue<T> {\n  if (strategy === 'async') {\n    return createAsyncQueue<T>(name, options as AsyncQueueOptions)\n  }\n\n  return createLocalQueue<T>(name, options as LocalQueueOptions)\n}\n\n/**\n * Resolve the queue strategy from `QUEUE_STRATEGY`. Defaults to `'local'`.\n */\nexport function resolveQueueStrategy(): QueueStrategyType {\n  return process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local'\n}\n\n/**\n * Create a module-owned queue using the strategy declared in `QUEUE_STRATEGY`.\n *\n * - When `QUEUE_STRATEGY=async`, builds a BullMQ queue and resolves the\n *   Redis URL via `getRedisUrlOrThrow('QUEUE')` so missing config fails loudly.\n * - Otherwise builds a local file-based queue.\n *\n * Replaces the boilerplate `process.env.QUEUE_STRATEGY === 'async' ? ... : ...`\n * pattern that every module queue helper used to repeat. Concurrency applies\n * to both strategies so the same number means the same thing in dev and prod.\n *\n * @example\n * ```typescript\n * export function getDataSyncQueue(name: string) {\n *   return createModuleQueue<MyJob>(name, { concurrency: 5 })\n * }\n * ```\n */\nexport function createModuleQueue<T = unknown>(\n  name: string,\n  options?: { concurrency?: number },\n): Queue<T> {\n  const strategy = resolveQueueStrategy()\n  if (strategy === 'async') {\n    return createAsyncQueue<T>(name, {\n      connection: { url: getRedisUrlOrThrow('QUEUE') },\n      concurrency: options?.concurrency,\n    })\n  }\n  return createLocalQueue<T>(name, { concurrency: options?.concurrency })\n}\n"],
+  "mappings": "AACA,SAAS,wBAAwB;AACjC,SAAS,wBAAwB;AACjC,SAAS,0BAA0B;AA0C5B,SAAS,YACd,MACA,UACA,SACU;AACV,MAAI,aAAa,SAAS;AACxB,WAAO,iBAAoB,MAAM,OAA4B;AAAA,EAC/D;AAEA,SAAO,iBAAoB,MAAM,OAA4B;AAC/D;AAKO,SAAS,uBAA0C;AACxD,SAAO,QAAQ,IAAI,mBAAmB,UAAU,UAAU;AAC5D;AAoBO,SAAS,kBACd,MACA,SACU;AACV,QAAM,WAAW,qBAAqB;AACtC,MAAI,aAAa,SAAS;AACxB,WAAO,iBAAoB,MAAM;AAAA,MAC/B,YAAY,EAAE,KAAK,mBAAmB,OAAO,EAAE;AAAA,MAC/C,aAAa,SAAS;AAAA,IACxB,CAAC;AAAA,EACH;AACA,SAAO,iBAAoB,MAAM,EAAE,aAAa,SAAS,YAAY,CAAC;AACxE;",
   "names": []
 }

package/dist/index.js

@@ -1,10 +1,12 @@
 export * from "./types.js";
-import { createQueue } from "./factory.js";
+import { createQueue, createModuleQueue, resolveQueueStrategy } from "./factory.js";
 export * from "./worker/registry.js";
 import { runWorker, createRoutedHandler } from "./worker/runner.js";
 export {
+  createModuleQueue,
   createQueue,
   createRoutedHandler,
+  resolveQueueStrategy,
   runWorker
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/index.ts"],
-  "sourcesContent": ["/**\n * @open-mercato/queue\n *\n * Multi-strategy job queue package supporting local (file-based) and async (BullMQ) strategies.\n *\n * @example\n * ```typescript\n * import { createQueue } from '@open-mercato/queue'\n *\n * // Create a local queue\n * const queue = createQueue<{ userId: string }>('my-queue', 'local')\n *\n * // Enqueue a job\n * await queue.enqueue({ userId: '123' })\n *\n * // Process jobs\n * await queue.process(async (job, ctx) => {\n *   console.log(`Processing job ${ctx.jobId}:`, job.payload)\n * })\n * ```\n */\n\nexport * from './types'\nexport { createQueue } from './factory'\n\n// Worker utilities\nexport * from './worker/registry'\nexport { runWorker, createRoutedHandler } from './worker/runner'\n"],
-  "mappings": "AAsBA,cAAc;AACd,SAAS,mBAAmB;AAG5B,cAAc;AACd,SAAS,WAAW,2BAA2B;",
+  "sourcesContent": ["/**\n * @open-mercato/queue\n *\n * Multi-strategy job queue package supporting local (file-based) and async (BullMQ) strategies.\n *\n * @example\n * ```typescript\n * import { createQueue } from '@open-mercato/queue'\n *\n * // Create a local queue\n * const queue = createQueue<{ userId: string }>('my-queue', 'local')\n *\n * // Enqueue a job\n * await queue.enqueue({ userId: '123' })\n *\n * // Process jobs\n * await queue.process(async (job, ctx) => {\n *   console.log(`Processing job ${ctx.jobId}:`, job.payload)\n * })\n * ```\n */\n\nexport * from './types'\nexport { createQueue, createModuleQueue, resolveQueueStrategy } from './factory'\n\n// Worker utilities\nexport * from './worker/registry'\nexport { runWorker, createRoutedHandler } from './worker/runner'\n"],
+  "mappings": "AAsBA,cAAc;AACd,SAAS,aAAa,mBAAmB,4BAA4B;AAGrE,cAAc;AACd,SAAS,WAAW,2BAA2B;",
   "names": []
 }

package/dist/strategies/async.js

@@ -1,4 +1,4 @@
-import { getRedisUrl } from "@open-mercato/shared/lib/redis/connection";
+import { getRedisUrlOrThrow } from "@open-mercato/shared/lib/redis/connection";
 function resolveConnection(options) {
   if (options?.url) {
     return { url: options.url };
@@ -13,7 +13,7 @@ function resolveConnection(options) {
       tls: options.tls
     };
   }
-  return { url: getRedisUrl("QUEUE") };
+  return { url: getRedisUrlOrThrow("QUEUE") };
 }
 function createAsyncQueue(name, options) {
   const connection = resolveConnection(options?.connection);

package/dist/strategies/async.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/strategies/async.ts"],
-  "sourcesContent": ["import type { Queue, QueuedJob, JobHandler, AsyncQueueOptions, ProcessResult, EnqueueOptions } from '../types'\nimport { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'\n\n// BullMQ interface types - we define the shape we use to maintain type safety\n// while keeping bullmq as an optional peer dependency\ntype ConnectionOptions = {\n  url?: string\n  host?: string\n  port?: number\n  username?: string\n  password?: string\n  db?: number\n  tls?: Record<string, unknown>\n}\n\ninterface BullQueueInterface<T> {\n  add: (\n    name: string,\n    data: T,\n    opts?: {\n      removeOnComplete?: boolean\n      removeOnFail?: number\n      delay?: number\n      attempts?: number\n      backoff?: { type: string; delay: number }\n    },\n  ) => Promise<{ id?: string }>\n  obliterate: (opts?: { force?: boolean }) => Promise<void>\n  close: () => Promise<void>\n  getJobCounts: (...states: string[]) => Promise<Record<string, number>>\n}\n\ninterface BullWorkerInterface {\n  on: (event: string, handler: (...args: unknown[]) => void) => void\n  close: () => Promise<void>\n}\n\ninterface BullMQModule {\n  Queue: new <T>(name: string, opts: { connection: ConnectionOptions }) => BullQueueInterface<T>\n  Worker: new <T>(\n    name: string,\n    processor: (job: { id?: string; data: T; attemptsMade: number }) => Promise<void>,\n    opts: { connection: ConnectionOptions; concurrency: number }\n  ) => BullWorkerInterface\n}\n\n/**\n * Resolves Redis connection options from various sources.\n *\n * BullMQ expects an ioredis-compatible connection object. Preserve the full\n * Redis URL under the `url` key so rediss://, username, database, and query\n * params are not lost in translation.\n */\nfunction resolveConnection(options?: AsyncQueueOptions['connection']): ConnectionOptions {\n  if (options?.url) {\n    return { url: options.url }\n  }\n\n  if (options?.host) {\n    return {\n      host: options.host,\n      port: options.port ?? 6379,\n      username: options.username,\n      password: options.password,\n      db: options.db,\n      tls: options.tls,\n    }\n  }\n\n  return { url: getRedisUrl('QUEUE') }\n}\n\n/**\n * Creates a BullMQ-based async queue.\n *\n * This strategy provides:\n * - Persistent job storage in Redis\n * - Automatic retries with exponential backoff\n * - Concurrent job processing\n * - Job prioritization and scheduling\n *\n * @template T - The payload type for jobs\n * @param name - Queue name\n * @param options - Async queue options\n */\nexport function createAsyncQueue<T = unknown>(\n  name: string,\n  options?: AsyncQueueOptions\n): Queue<T> {\n  const connection = resolveConnection(options?.connection)\n  const concurrency = options?.concurrency ?? 1\n\n  let bullQueue: BullQueueInterface<QueuedJob<T>> | null = null\n  let bullWorker: BullWorkerInterface | null = null\n  let bullmqModule: BullMQModule | null = null\n\n  // -------------------------------------------------------------------------\n  // Lazy BullMQ initialization\n  // -------------------------------------------------------------------------\n\n  async function getBullMQ(): Promise<BullMQModule> {\n    if (!bullmqModule) {\n      try {\n        bullmqModule = await import('bullmq') as unknown as BullMQModule\n      } catch {\n        throw new Error(\n          'BullMQ is required for async queue strategy. Install it with: npm install bullmq'\n        )\n      }\n    }\n    return bullmqModule\n  }\n\n  async function getQueue(): Promise<BullQueueInterface<QueuedJob<T>>> {\n    if (!bullQueue) {\n      const { Queue: BullQueueClass } = await getBullMQ()\n      bullQueue = new BullQueueClass<QueuedJob<T>>(name, { connection })\n    }\n    return bullQueue\n  }\n\n  // -------------------------------------------------------------------------\n  // Queue Implementation\n  // -------------------------------------------------------------------------\n\n  async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {\n    const queue = await getQueue()\n    const jobData: QueuedJob<T> = {\n      id: crypto.randomUUID(),\n      payload: data,\n      createdAt: new Date().toISOString(),\n    }\n\n    const job = await queue.add(jobData.id, jobData, {\n      delay: options?.delayMs && options.delayMs > 0 ? options.delayMs : undefined,\n      removeOnComplete: true,\n      removeOnFail: 1000,\n      attempts: 3,\n      backoff: { type: 'exponential', delay: 1000 },\n    })\n\n    return job.id ?? jobData.id\n  }\n\n  async function process(handler: JobHandler<T>): Promise<ProcessResult> {\n    const { Worker } = await getBullMQ()\n\n    // Create worker that processes jobs\n    bullWorker = new Worker<QueuedJob<T>>(\n      name,\n      async (job) => {\n        const jobData = job.data\n        await handler(jobData, {\n          jobId: job.id ?? jobData.id,\n          attemptNumber: job.attemptsMade + 1,\n          queueName: name,\n        })\n      },\n      {\n        connection,\n        concurrency,\n      }\n    )\n\n    // Set up event handlers\n    bullWorker.on('completed', (job) => {\n      const jobWithId = job as { id?: string }\n      console.log(`[queue:${name}] Job ${jobWithId.id} completed`)\n    })\n\n    bullWorker.on('failed', (job, err) => {\n      const jobWithId = job as { id?: string } | undefined\n      const error = err as Error\n      console.error(`[queue:${name}] Job ${jobWithId?.id} failed:`, error.message)\n    })\n\n    bullWorker.on('error', (err) => {\n      const error = err as Error\n      console.error(`[queue:${name}] Worker error:`, error.message)\n    })\n\n    console.log(`[queue:${name}] Worker started with concurrency ${concurrency}`)\n\n    // For async strategy, return a sentinel result indicating worker mode\n    // processed=-1 signals that this is a continuous worker, not a batch process\n    return { processed: -1, failed: -1, lastJobId: undefined }\n  }\n\n  async function clear(): Promise<{ removed: number }> {\n    const queue = await getQueue()\n\n    // Obliterate removes all jobs from the queue\n    await queue.obliterate({ force: true })\n\n    return { removed: -1 } // BullMQ obliterate doesn't return count\n  }\n\n  async function close(): Promise<void> {\n    if (bullWorker) {\n      await bullWorker.close()\n      bullWorker = null\n    }\n    if (bullQueue) {\n      await bullQueue.close()\n      bullQueue = null\n    }\n  }\n\n  async function getJobCounts(): Promise<{\n    waiting: number\n    active: number\n    completed: number\n    failed: number\n  }> {\n    const queue = await getQueue()\n    const counts = await queue.getJobCounts('waiting', 'active', 'completed', 'failed')\n    return {\n      waiting: counts.waiting ?? 0,\n      active: counts.active ?? 0,\n      completed: counts.completed ?? 0,\n      failed: counts.failed ?? 0,\n    }\n  }\n\n  return {\n    name,\n    strategy: 'async',\n    enqueue,\n    process,\n    clear,\n    close,\n    getJobCounts,\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { Queue, QueuedJob, JobHandler, AsyncQueueOptions, ProcessResult, EnqueueOptions } from '../types'\nimport { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'\n\n// BullMQ interface types - we define the shape we use to maintain type safety\n// while keeping bullmq as an optional peer dependency\ntype ConnectionOptions = {\n  url?: string\n  host?: string\n  port?: number\n  username?: string\n  password?: string\n  db?: number\n  tls?: Record<string, unknown>\n}\n\ninterface BullQueueInterface<T> {\n  add: (\n    name: string,\n    data: T,\n    opts?: {\n      removeOnComplete?: boolean\n      removeOnFail?: number\n      delay?: number\n      attempts?: number\n      backoff?: { type: string; delay: number }\n    },\n  ) => Promise<{ id?: string }>\n  obliterate: (opts?: { force?: boolean }) => Promise<void>\n  close: () => Promise<void>\n  getJobCounts: (...states: string[]) => Promise<Record<string, number>>\n}\n\ninterface BullWorkerInterface {\n  on: (event: string, handler: (...args: unknown[]) => void) => void\n  close: () => Promise<void>\n}\n\ninterface BullMQModule {\n  Queue: new <T>(name: string, opts: { connection: ConnectionOptions }) => BullQueueInterface<T>\n  Worker: new <T>(\n    name: string,\n    processor: (job: { id?: string; data: T; attemptsMade: number }) => Promise<void>,\n    opts: { connection: ConnectionOptions; concurrency: number }\n  ) => BullWorkerInterface\n}\n\n/**\n * Resolves Redis connection options from various sources.\n *\n * BullMQ expects an ioredis-compatible connection object. Preserve the full\n * Redis URL under the `url` key so rediss://, username, database, and query\n * params are not lost in translation.\n */\nfunction resolveConnection(options?: AsyncQueueOptions['connection']): ConnectionOptions {\n  if (options?.url) {\n    return { url: options.url }\n  }\n\n  if (options?.host) {\n    return {\n      host: options.host,\n      port: options.port ?? 6379,\n      username: options.username,\n      password: options.password,\n      db: options.db,\n      tls: options.tls,\n    }\n  }\n\n  return { url: getRedisUrlOrThrow('QUEUE') }\n}\n\n/**\n * Creates a BullMQ-based async queue.\n *\n * This strategy provides:\n * - Persistent job storage in Redis\n * - Automatic retries with exponential backoff\n * - Concurrent job processing\n * - Job prioritization and scheduling\n *\n * @template T - The payload type for jobs\n * @param name - Queue name\n * @param options - Async queue options\n */\nexport function createAsyncQueue<T = unknown>(\n  name: string,\n  options?: AsyncQueueOptions\n): Queue<T> {\n  const connection = resolveConnection(options?.connection)\n  const concurrency = options?.concurrency ?? 1\n\n  let bullQueue: BullQueueInterface<QueuedJob<T>> | null = null\n  let bullWorker: BullWorkerInterface | null = null\n  let bullmqModule: BullMQModule | null = null\n\n  // -------------------------------------------------------------------------\n  // Lazy BullMQ initialization\n  // -------------------------------------------------------------------------\n\n  async function getBullMQ(): Promise<BullMQModule> {\n    if (!bullmqModule) {\n      try {\n        bullmqModule = await import('bullmq') as unknown as BullMQModule\n      } catch {\n        throw new Error(\n          'BullMQ is required for async queue strategy. Install it with: npm install bullmq'\n        )\n      }\n    }\n    return bullmqModule\n  }\n\n  async function getQueue(): Promise<BullQueueInterface<QueuedJob<T>>> {\n    if (!bullQueue) {\n      const { Queue: BullQueueClass } = await getBullMQ()\n      bullQueue = new BullQueueClass<QueuedJob<T>>(name, { connection })\n    }\n    return bullQueue\n  }\n\n  // -------------------------------------------------------------------------\n  // Queue Implementation\n  // -------------------------------------------------------------------------\n\n  async function enqueue(data: T, options?: EnqueueOptions): Promise<string> {\n    const queue = await getQueue()\n    const jobData: QueuedJob<T> = {\n      id: crypto.randomUUID(),\n      payload: data,\n      createdAt: new Date().toISOString(),\n    }\n\n    const job = await queue.add(jobData.id, jobData, {\n      delay: options?.delayMs && options.delayMs > 0 ? options.delayMs : undefined,\n      removeOnComplete: true,\n      removeOnFail: 1000,\n      attempts: 3,\n      backoff: { type: 'exponential', delay: 1000 },\n    })\n\n    return job.id ?? jobData.id\n  }\n\n  async function process(handler: JobHandler<T>): Promise<ProcessResult> {\n    const { Worker } = await getBullMQ()\n\n    // Create worker that processes jobs\n    bullWorker = new Worker<QueuedJob<T>>(\n      name,\n      async (job) => {\n        const jobData = job.data\n        await handler(jobData, {\n          jobId: job.id ?? jobData.id,\n          attemptNumber: job.attemptsMade + 1,\n          queueName: name,\n        })\n      },\n      {\n        connection,\n        concurrency,\n      }\n    )\n\n    // Set up event handlers\n    bullWorker.on('completed', (job) => {\n      const jobWithId = job as { id?: string }\n      console.log(`[queue:${name}] Job ${jobWithId.id} completed`)\n    })\n\n    bullWorker.on('failed', (job, err) => {\n      const jobWithId = job as { id?: string } | undefined\n      const error = err as Error\n      console.error(`[queue:${name}] Job ${jobWithId?.id} failed:`, error.message)\n    })\n\n    bullWorker.on('error', (err) => {\n      const error = err as Error\n      console.error(`[queue:${name}] Worker error:`, error.message)\n    })\n\n    console.log(`[queue:${name}] Worker started with concurrency ${concurrency}`)\n\n    // For async strategy, return a sentinel result indicating worker mode\n    // processed=-1 signals that this is a continuous worker, not a batch process\n    return { processed: -1, failed: -1, lastJobId: undefined }\n  }\n\n  async function clear(): Promise<{ removed: number }> {\n    const queue = await getQueue()\n\n    // Obliterate removes all jobs from the queue\n    await queue.obliterate({ force: true })\n\n    return { removed: -1 } // BullMQ obliterate doesn't return count\n  }\n\n  async function close(): Promise<void> {\n    if (bullWorker) {\n      await bullWorker.close()\n      bullWorker = null\n    }\n    if (bullQueue) {\n      await bullQueue.close()\n      bullQueue = null\n    }\n  }\n\n  async function getJobCounts(): Promise<{\n    waiting: number\n    active: number\n    completed: number\n    failed: number\n  }> {\n    const queue = await getQueue()\n    const counts = await queue.getJobCounts('waiting', 'active', 'completed', 'failed')\n    return {\n      waiting: counts.waiting ?? 0,\n      active: counts.active ?? 0,\n      completed: counts.completed ?? 0,\n      failed: counts.failed ?? 0,\n    }\n  }\n\n  return {\n    name,\n    strategy: 'async',\n    enqueue,\n    process,\n    clear,\n    close,\n    getJobCounts,\n  }\n}\n"],
+  "mappings": "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",
   "names": ["options"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/queue",
-  "version": "0.4.11-develop.2235.49f509443f",
+  "version": "0.4.11-develop.2245.a1059680ca",
   "description": "Multi-strategy job queue with local and BullMQ support",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@open-mercato/shared": "0.4.11-develop.2235.49f509443f"
+    "@open-mercato/shared": "0.4.11-develop.2245.a1059680ca"
   },
   "stableVersion": "0.4.10"
 }

package/src/__tests__/async.strategy.test.ts

@@ -1,5 +1,5 @@
 import { createQueue } from '../factory'
-import { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'
+import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
 
 const queueCtor = jest.fn()
 const workerCtor = jest.fn()
@@ -16,7 +16,7 @@ const workerClose = jest.fn(async () => {})
 const workerOn = jest.fn()
 
 jest.mock('@open-mercato/shared/lib/redis/connection', () => ({
-  getRedisUrl: jest.fn(),
+  getRedisUrlOrThrow: jest.fn(),
 }))
 
 jest.mock('bullmq', () => {
@@ -51,11 +51,11 @@ jest.mock('bullmq', () => {
 })
 
 describe('Queue - async strategy', () => {
-  const getRedisUrlMock = getRedisUrl as jest.MockedFunction<typeof getRedisUrl>
+  const getRedisUrlOrThrowMock = getRedisUrlOrThrow as jest.MockedFunction<typeof getRedisUrlOrThrow>
 
   beforeEach(() => {
     jest.clearAllMocks()
-    getRedisUrlMock.mockReturnValue('rediss://default:secret@example.com:6380/1')
+    getRedisUrlOrThrowMock.mockReturnValue('rediss://default:secret@example.com:6380/1')
   })
 
   it('passes the full Redis URL to BullMQ when using env-based async config', async () => {

package/src/__tests__/factory.test.ts

@@ -0,0 +1,96 @@
+import { resolveQueueStrategy, createModuleQueue } from '../factory'
+import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
+
+jest.mock('@open-mercato/shared/lib/redis/connection', () => ({
+  getRedisUrlOrThrow: jest.fn(),
+}))
+
+jest.mock('bullmq', () => {
+  class MockQueue<T> {
+    constructor(_name: string, _opts: unknown) {}
+    add = jest.fn(async () => ({ id: 'bull-job-id' }))
+    close = jest.fn(async () => {})
+    obliterate = jest.fn(async () => {})
+    getJobCounts = jest.fn(async () => ({ waiting: 0, active: 0, completed: 0, failed: 0 }))
+  }
+
+  class MockWorker<T> {
+    constructor(_name: string, _processor: unknown, _opts: unknown) {}
+    on = jest.fn()
+    close = jest.fn(async () => {})
+  }
+
+  return { Queue: MockQueue, Worker: MockWorker }
+})
+
+describe('resolveQueueStrategy', () => {
+  const originalEnv = process.env.QUEUE_STRATEGY
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.QUEUE_STRATEGY
+    } else {
+      process.env.QUEUE_STRATEGY = originalEnv
+    }
+  })
+
+  it('returns "local" when QUEUE_STRATEGY is not set', () => {
+    delete process.env.QUEUE_STRATEGY
+    expect(resolveQueueStrategy()).toBe('local')
+  })
+
+  it('returns "local" when QUEUE_STRATEGY is "local"', () => {
+    process.env.QUEUE_STRATEGY = 'local'
+    expect(resolveQueueStrategy()).toBe('local')
+  })
+
+  it('returns "async" when QUEUE_STRATEGY is "async"', () => {
+    process.env.QUEUE_STRATEGY = 'async'
+    expect(resolveQueueStrategy()).toBe('async')
+  })
+
+  it('returns "local" for any unrecognized value', () => {
+    process.env.QUEUE_STRATEGY = 'unknown'
+    expect(resolveQueueStrategy()).toBe('local')
+  })
+})
+
+describe('createModuleQueue', () => {
+  const originalEnv = process.env.QUEUE_STRATEGY
+  const getRedisUrlOrThrowMock = getRedisUrlOrThrow as jest.MockedFunction<typeof getRedisUrlOrThrow>
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    getRedisUrlOrThrowMock.mockReturnValue('redis://localhost:6379')
+  })
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.QUEUE_STRATEGY
+    } else {
+      process.env.QUEUE_STRATEGY = originalEnv
+    }
+  })
+
+  it('creates a local queue when QUEUE_STRATEGY is not set', () => {
+    delete process.env.QUEUE_STRATEGY
+    const queue = createModuleQueue('test-queue')
+    expect(queue.strategy).toBe('local')
+    expect(queue.name).toBe('test-queue')
+  })
+
+  it('creates an async queue when QUEUE_STRATEGY is "async"', () => {
+    process.env.QUEUE_STRATEGY = 'async'
+    const queue = createModuleQueue('test-queue', { concurrency: 5 })
+    expect(queue.strategy).toBe('async')
+    expect(queue.name).toBe('test-queue')
+    expect(getRedisUrlOrThrowMock).toHaveBeenCalledWith('QUEUE')
+  })
+
+  it('passes concurrency to local strategy', () => {
+    delete process.env.QUEUE_STRATEGY
+    const queue = createModuleQueue('test-queue', { concurrency: 3 })
+    expect(queue.strategy).toBe('local')
+    expect(queue.name).toBe('test-queue')
+  })
+})

package/src/factory.ts

@@ -1,6 +1,7 @@
-import type { Queue, LocalQueueOptions, AsyncQueueOptions } from './types'
+import type { Queue, LocalQueueOptions, AsyncQueueOptions, QueueStrategyType } from './types'
 import { createLocalQueue } from './strategies/local'
 import { createAsyncQueue } from './strategies/async'
+import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
 
 /**
  * Creates a queue instance with the specified strategy.
@@ -53,3 +54,42 @@ export function createQueue<T = unknown>(
 
   return createLocalQueue<T>(name, options as LocalQueueOptions)
 }
+
+/**
+ * Resolve the queue strategy from `QUEUE_STRATEGY`. Defaults to `'local'`.
+ */
+export function resolveQueueStrategy(): QueueStrategyType {
+  return process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local'
+}
+
+/**
+ * Create a module-owned queue using the strategy declared in `QUEUE_STRATEGY`.
+ *
+ * - When `QUEUE_STRATEGY=async`, builds a BullMQ queue and resolves the
+ *   Redis URL via `getRedisUrlOrThrow('QUEUE')` so missing config fails loudly.
+ * - Otherwise builds a local file-based queue.
+ *
+ * Replaces the boilerplate `process.env.QUEUE_STRATEGY === 'async' ? ... : ...`
+ * pattern that every module queue helper used to repeat. Concurrency applies
+ * to both strategies so the same number means the same thing in dev and prod.
+ *
+ * @example
+ * ```typescript
+ * export function getDataSyncQueue(name: string) {
+ *   return createModuleQueue<MyJob>(name, { concurrency: 5 })
+ * }
+ * ```
+ */
+export function createModuleQueue<T = unknown>(
+  name: string,
+  options?: { concurrency?: number },
+): Queue<T> {
+  const strategy = resolveQueueStrategy()
+  if (strategy === 'async') {
+    return createAsyncQueue<T>(name, {
+      connection: { url: getRedisUrlOrThrow('QUEUE') },
+      concurrency: options?.concurrency,
+    })
+  }
+  return createLocalQueue<T>(name, { concurrency: options?.concurrency })
+}

package/src/index.ts

@@ -21,7 +21,7 @@
  */
 
 export * from './types'
-export { createQueue } from './factory'
+export { createQueue, createModuleQueue, resolveQueueStrategy } from './factory'
 
 // Worker utilities
 export * from './worker/registry'

package/src/strategies/async.ts

@@ -1,5 +1,5 @@
 import type { Queue, QueuedJob, JobHandler, AsyncQueueOptions, ProcessResult, EnqueueOptions } from '../types'
-import { getRedisUrl } from '@open-mercato/shared/lib/redis/connection'
+import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
 
 // BullMQ interface types - we define the shape we use to maintain type safety
 // while keeping bullmq as an optional peer dependency
@@ -67,7 +67,7 @@ function resolveConnection(options?: AsyncQueueOptions['connection']): Connectio
     }
   }
 
-  return { url: getRedisUrl('QUEUE') }
+  return { url: getRedisUrlOrThrow('QUEUE') }
 }
 
 /**