@open-mercato/queue 0.4.2-canary-c02407ff85

package/src/worker/registry.ts

@@ -0,0 +1,76 @@
+/**
+ * Worker Registry
+ *
+ * Provides registration and lookup for auto-discovered queue workers.
+ * Workers are registered during bootstrap and accessed by the CLI worker command.
+ */
+
+import type { WorkerDescriptor } from '../types'
+
+const workers: Map<string, WorkerDescriptor> = new Map()
+
+/**
+ * Register a single worker.
+ * @param worker - The worker descriptor to register
+ */
+export function registerWorker(worker: WorkerDescriptor): void {
+  if (workers.has(worker.id)) {
+    console.warn(`[worker-registry] Worker "${worker.id}" already registered, overwriting`)
+  }
+  workers.set(worker.id, worker)
+}
+
+/**
+ * Register multiple workers at once (typically from module discovery).
+ * @param list - Array of worker descriptors to register
+ */
+export function registerModuleWorkers(list: WorkerDescriptor[]): void {
+  for (const worker of list) {
+    registerWorker(worker)
+  }
+}
+
+/**
+ * Get all registered workers.
+ * @returns Array of all worker descriptors
+ */
+export function getWorkers(): WorkerDescriptor[] {
+  return Array.from(workers.values())
+}
+
+/**
+ * Get workers registered for a specific queue.
+ * @param queue - The queue name to filter by
+ * @returns Array of workers for the specified queue
+ */
+export function getWorkersByQueue(queue: string): WorkerDescriptor[] {
+  return Array.from(workers.values()).filter((w) => w.queue === queue)
+}
+
+/**
+ * Get a specific worker by ID.
+ * @param id - The worker ID to look up
+ * @returns The worker descriptor if found, undefined otherwise
+ */
+export function getWorker(id: string): WorkerDescriptor | undefined {
+  return workers.get(id)
+}
+
+/**
+ * Get all unique queue names that have registered workers.
+ * @returns Array of queue names
+ */
+export function getRegisteredQueues(): string[] {
+  const queues = new Set<string>()
+  for (const worker of workers.values()) {
+    queues.add(worker.queue)
+  }
+  return Array.from(queues)
+}
+
+/**
+ * Clear all registered workers (useful for testing).
+ */
+export function clearWorkers(): void {
+  workers.clear()
+}

package/src/worker/runner.ts

@@ -0,0 +1,140 @@
+import { createQueue } from '../factory'
+import type { JobHandler, AsyncQueueOptions, QueueStrategyType } from '../types'
+
+/**
+ * Options for running a queue worker.
+ */
+export type WorkerRunnerOptions<T = unknown> = {
+  /** Name of the queue to process */
+  queueName: string
+  /** Handler function to process each job */
+  handler: JobHandler<T>
+  /** Redis connection options (only used for async strategy) */
+  connection?: AsyncQueueOptions['connection']
+  /** Number of concurrent jobs to process */
+  concurrency?: number
+  /** Whether to set up graceful shutdown handlers */
+  gracefulShutdown?: boolean
+  /** If true, don't block - return immediately after starting processing (for multi-queue mode) */
+  background?: boolean
+  /** Queue strategy to use. Defaults to QUEUE_STRATEGY env var or 'local' */
+  strategy?: QueueStrategyType
+}
+
+/**
+ * Runs a queue worker that processes jobs continuously.
+ *
+ * This function:
+ * 1. Creates an async queue instance
+ * 2. Starts a BullMQ worker
+ * 3. Sets up graceful shutdown on SIGTERM/SIGINT
+ * 4. Keeps the process running until shutdown
+ *
+ * @template T - The job payload type
+ * @param options - Worker configuration
+ *
+ * @example
+ * ```typescript
+ * import { runWorker } from '@open-mercato/queue/worker'
+ *
+ * await runWorker({
+ *   queueName: 'events',
+ *   handler: async (job, ctx) => {
+ *     console.log(`Processing ${ctx.jobId}:`, job.payload)
+ *   },
+ *   connection: { url: process.env.REDIS_URL },
+ *   concurrency: 5,
+ * })
+ * ```
+ */
+export async function runWorker<T = unknown>(
+  options: WorkerRunnerOptions<T>
+): Promise<void> {
+  const {
+    queueName,
+    handler,
+    connection,
+    concurrency = 1,
+    gracefulShutdown = true,
+    background = false,
+    strategy: strategyOption,
+  } = options
+
+  // Determine queue strategy from option, env var, or default to 'local'
+  const strategy: QueueStrategyType = strategyOption
+    ?? (process.env.QUEUE_STRATEGY === 'async' ? 'async' : 'local')
+
+  console.log(`[worker] Starting worker for queue "${queueName}" (strategy: ${strategy})...`)
+
+  const queue = createQueue<T>(queueName, strategy, {
+    connection,
+    concurrency,
+  })
+
+  // Set up graceful shutdown
+  if (gracefulShutdown) {
+    const shutdown = async (signal: string) => {
+      console.log(`[worker] Received ${signal}, shutting down gracefully...`)
+      try {
+        await queue.close()
+        console.log('[worker] Worker closed successfully')
+        process.exit(0)
+      } catch (error) {
+        console.error('[worker] Error during shutdown:', error)
+        process.exit(1)
+      }
+    }
+
+    process.on('SIGTERM', () => shutdown('SIGTERM'))
+    process.on('SIGINT', () => shutdown('SIGINT'))
+  }
+
+  // Start processing
+  await queue.process(handler)
+
+  console.log(`[worker] Worker running with concurrency ${concurrency}`)
+
+  if (background) {
+    // Return immediately for multi-queue mode
+    return
+  }
+
+  console.log('[worker] Press Ctrl+C to stop')
+
+  // Keep the process alive (single-queue mode)
+  await new Promise(() => {
+    // This promise never resolves, keeping the worker running
+  })
+}
+
+/**
+ * Creates a worker handler that routes jobs to specific handlers based on job type.
+ *
+ * @template T - Base job payload type (must include a 'type' field)
+ * @param handlers - Map of job types to their handlers
+ *
+ * @example
+ * ```typescript
+ * const handler = createRoutedHandler({
+ *   'user.created': async (job) => { ... },
+ *   'order.placed': async (job) => { ... },
+ * })
+ *
+ * await runWorker({ queueName: 'events', handler })
+ * ```
+ */
+export function createRoutedHandler<T extends { type: string }>(
+  handlers: Record<string, JobHandler<T>>
+): JobHandler<T> {
+  return async (job, ctx) => {
+    const type = job.payload.type
+    const handler = handlers[type]
+
+    if (!handler) {
+      console.warn(`[worker] No handler registered for job type "${type}"`)
+      return
+    }
+
+    await handler(job, ctx)
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,6 @@
+import { watch } from '../../scripts/watch.mjs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+watch(__dirname)