@nwire/bullmq 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @nwire/bullmq
+
+> [BullMQ](https://docs.bullmq.io)-backed `QueueTransport` — Redis-durable background jobs.
+
+## What it does
+
+Implements the `@nwire/queue` `QueueTransport` over BullMQ. One BullMQ Queue per queue name; one Worker per `subscribe()`. `enqueue` with `delayMs` translates to BullMQ's `delay` option; `messageId` becomes BullMQ's `jobId` for idempotency. Failed jobs flow into BullMQ's failed-jobs board after the runtime's retry+DLQ logic exhausts.
+
+## Install
+
+```bash
+pnpm add @nwire/bullmq @nwire/queue bullmq
+```
+
+## Quick start
+
+```ts
+import { BullMQQueueTransport } from "@nwire/bullmq";
+import { createQueueWorker } from "@nwire/queue";
+import { app } from "./app";
+
+const transport = new BullMQQueueTransport({
+  connection: { host: "localhost", port: 6379 },
+  prefix: "learnflow",
+  defaultConcurrency: 5,
+});
+
+const worker = createQueueWorker(app, transport, {
+  subscribe: [
+    { queue: "emails", action: "sendWelcomeEmail" },
+    { queue: "reports", action: "generateMonthlyReport", retry: { attempts: 3 } },
+  ],
+});
+
+await worker.start();
+```
+
+## API surface
+
+- `BullMQQueueTransport({ connection, prefix?, defaultConcurrency? })` — implements `QueueTransport`.
+
+## When to use
+
+Any production queue workload — same handler shape as `InMemoryQueueTransport`, swapped by config.
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```

package/dist/queue-bullmq.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@nwire/bullmq` — BullMQ-backed QueueTransport for production.
+ *
+ *   import { BullMQQueueTransport } from '@nwire/bullmq'
+ *
+ *   const transport = new BullMQQueueTransport({
+ *       connection: { host: 'localhost', port: 6379 }
+ *   })
+ *   const worker = createQueueWorker(app, transport, { subscribe: [...] })
+ *   await worker.start()
+ *
+ * One BullMQ Queue per `queue` name; one BullMQ Worker per `subscribe()` call.
+ * `enqueue` with `delayMs` translates to BullMQ's `delay` option. Idempotency
+ * via `messageId` becomes BullMQ's `jobId`.
+ *
+ * Failed jobs flow into BullMQ's failed-jobs board automatically; the
+ * runtime's retry+DLQ logic still runs first (per-action retry policy) — by
+ * the time a job lands on BullMQ's failure list, the framework has already
+ * exhausted retries and dead-lettered.
+ */
+import { type ConnectionOptions } from "bullmq";
+import type { QueueTransport, QueueMessage, QueueConsumer } from "@nwire/queue";
+export interface BullMQQueueOptions {
+    readonly connection: ConnectionOptions;
+    /** Prefix every BullMQ key (multi-tenant isolation at the Redis level). Default: `'nwire'`. */
+    readonly prefix?: string;
+    /** Default worker concurrency. Default: 5. */
+    readonly defaultConcurrency?: number;
+}
+export declare class BullMQQueueTransport implements QueueTransport {
+    private readonly queues;
+    private readonly workers;
+    private readonly connection;
+    private readonly prefix;
+    private readonly defaultConcurrency;
+    private stopped;
+    constructor(options: BullMQQueueOptions);
+    private getOrCreateQueue;
+    enqueue<TInput>(queue: string, message: Omit<QueueMessage<TInput>, "queue">): Promise<void>;
+    subscribe<TInput>(queue: string, consumer: QueueConsumer<TInput>): void;
+    stop(): Promise<void>;
+}

package/dist/queue-bullmq.js

@@ -0,0 +1,85 @@
+/**
+ * `@nwire/bullmq` — BullMQ-backed QueueTransport for production.
+ *
+ *   import { BullMQQueueTransport } from '@nwire/bullmq'
+ *
+ *   const transport = new BullMQQueueTransport({
+ *       connection: { host: 'localhost', port: 6379 }
+ *   })
+ *   const worker = createQueueWorker(app, transport, { subscribe: [...] })
+ *   await worker.start()
+ *
+ * One BullMQ Queue per `queue` name; one BullMQ Worker per `subscribe()` call.
+ * `enqueue` with `delayMs` translates to BullMQ's `delay` option. Idempotency
+ * via `messageId` becomes BullMQ's `jobId`.
+ *
+ * Failed jobs flow into BullMQ's failed-jobs board automatically; the
+ * runtime's retry+DLQ logic still runs first (per-action retry policy) — by
+ * the time a job lands on BullMQ's failure list, the framework has already
+ * exhausted retries and dead-lettered.
+ */
+import { Queue, Worker } from "bullmq";
+export class BullMQQueueTransport {
+    queues = new Map();
+    workers = new Map();
+    connection;
+    prefix;
+    defaultConcurrency;
+    stopped = false;
+    constructor(options) {
+        this.connection = options.connection;
+        this.prefix = options.prefix ?? "nwire";
+        this.defaultConcurrency = options.defaultConcurrency ?? 5;
+    }
+    getOrCreateQueue(name) {
+        let q = this.queues.get(name);
+        if (!q) {
+            q = new Queue(name, { connection: this.connection, prefix: this.prefix });
+            this.queues.set(name, q);
+        }
+        return q;
+    }
+    async enqueue(queue, message) {
+        if (this.stopped) {
+            throw new Error("BullMQQueueTransport: enqueue after stop");
+        }
+        const q = this.getOrCreateQueue(queue);
+        await q.add(queue, { input: message.input, envelope: message.envelope }, {
+            jobId: message.messageId,
+            delay: message.delayMs && message.delayMs > 0 ? message.delayMs : undefined,
+        });
+    }
+    subscribe(queue, consumer) {
+        if (this.stopped) {
+            throw new Error("BullMQQueueTransport: subscribe after stop");
+        }
+        const worker = new Worker(queue, async (job) => {
+            const payload = job.data;
+            await consumer({
+                queue,
+                input: payload.input,
+                envelope: payload.envelope,
+                messageId: job.id,
+            });
+        }, {
+            connection: this.connection,
+            prefix: this.prefix,
+            concurrency: this.defaultConcurrency,
+        });
+        const list = this.workers.get(queue) ?? [];
+        list.push(worker);
+        this.workers.set(queue, list);
+    }
+    async stop() {
+        this.stopped = true;
+        for (const list of this.workers.values()) {
+            for (const w of list)
+                await w.close();
+        }
+        for (const q of this.queues.values()) {
+            await q.close();
+        }
+        this.workers.clear();
+        this.queues.clear();
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nwire/bullmq",
+  "version": "0.10.0",
+  "description": "Nwire — BullMQ-backed QueueTransport for production. Redis-backed durable queues + delayed jobs (timer scheduler) + failed-jobs board.",
+  "keywords": [
+    "adapter",
+    "bullmq",
+    "nwire",
+    "queue",
+    "redis"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/queue-bullmq.js",
+  "types": "./dist/queue-bullmq.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/queue-bullmq.js",
+      "types": "./dist/queue-bullmq.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "bullmq": "^5.67.3",
+    "@nwire/queue": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "@nwire/test-kit": "0.10.0"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}