@nwire/queue 0.7.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,71 @@
+# @nwire/queue
+
+> Background-job transport — queue contract + InMemory default + worker factory.
+
+## What it does
+
+Defines a small `QueueTransport` interface (`enqueue` / `consume` / `close`) and ships an in-memory default for dev/tests that honors `delayMs` via `setTimeout`. `createQueueWorker(app, transport, { subscribe })` binds named queues to Nwire actions so background jobs reuse the same handler shape as HTTP. Production deployments plug in `@nwire/queue-bullmq` (Redis); the contract is identical.
+
+## Install
+
+```bash
+pnpm add @nwire/queue
+```
+
+## Quick start
+
+```ts
+import { InMemoryQueueTransport, createQueueWorker } from "@nwire/queue";
+
+const transport = new InMemoryQueueTransport();
+
+const worker = createQueueWorker(app, transport, {
+  subscribe: [
+    { queue: "emails", action: "sendWelcomeEmail" },
+    { queue: "reports", action: "generateMonthlyReport", retry: { attempts: 3 } },
+  ],
+});
+
+await transport.enqueue("emails", { userId: "u-1" });
+await worker.start();
+// worker pulls from "emails" → dispatches sendWelcomeEmail with the payload
+```
+
+## API surface
+
+- `QueueTransport` — interface adapters implement.
+- `InMemoryQueueTransport` — process-local default; `delayMs`-aware.
+- `createQueueWorker(app, transport, opts)` — bind queues to actions.
+- `QueueMessage` / `QueueConsumer` / `QueueWorker` / `QueueSubscription` / `CreateQueueWorkerOptions` — supporting types.
+
+## When to use
+
+Whenever a request shouldn't block the caller — sending emails, building reports, syncing to a third party. Same handler shape as an HTTP action, so behavior is identical across transports. Fits L3 and up.
+
+## Standalone use
+
+For developers using `@nwire/queue` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/queue";
+```
+
+## 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.
+```
+
+## See also
+
+- [Architecture sketch §05 — Interfaces tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/queue-bullmq](../nwire-queue-bullmq), [@nwire/dead-letter](../nwire-dead-letter), [@nwire/cron](../nwire-cron)

package/dist/__tests__/queue.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Queue worker — contract test. Producer enqueues a message; consumer
+ * dispatches the bound action; actor state reflects the message's effect.
+ *
+ * Wire-mode invariance proof: the same handler+actor that the HTTP wire uses
+ * runs identically when triggered through a queue. Domain code unchanged.
+ */
+export {};
+//# sourceMappingURL=queue.test.d.ts.map

package/dist/__tests__/queue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/queue.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/__tests__/queue.test.js

@@ -0,0 +1,112 @@
+/**
+ * Queue worker — contract test. Producer enqueues a message; consumer
+ * dispatches the bound action; actor state reflects the message's effect.
+ *
+ * Wire-mode invariance proof: the same handler+actor that the HTTP wire uses
+ * runs identically when triggered through a queue. Domain code unchanged.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@nwire/messages";
+import * as forge from "@nwire/forge";
+import { seedEnvelope } from "@nwire/envelope";
+import { InMemoryQueueTransport, createQueueWorker } from "../queue";
+const { defineAction, defineActor, defineHandler, defineModule, eventFactory, createApp } = forge;
+const PingedEventDef = defineEvent({
+    name: "demo.pinged",
+    schema: z.object({ pingId: z.string() }),
+});
+const Pinged = eventFactory(PingedEventDef);
+const PingActor = defineActor("ping", {
+    schema: z.object({ pingId: z.string(), pings: z.number().optional() }),
+    key: "pingId",
+    initial: "idle",
+    states: {
+        idle: {
+            on: {
+                [PingedEventDef.name]: {
+                    assign: (ctx, event) => {
+                        const c = ctx;
+                        const e = event;
+                        return { pingId: e.pingId, pings: (c.pings ?? 0) + 1 };
+                    },
+                },
+            },
+        },
+    },
+});
+const ping = defineAction({ name: "demo.ping", schema: z.object({ pingId: z.string() }) });
+const pingHandler = defineHandler(ping, async (input) => Pinged({ pingId: input.pingId }));
+const demoModule = defineModule("demo", {
+    actions: [ping],
+    actors: [PingActor],
+    handlers: [pingHandler],
+    events: [PingedEventDef],
+});
+describe("queue worker — InMemoryQueueTransport drives actions through the runtime", () => {
+    it("an enqueued message dispatches the bound action and updates the actor", async () => {
+        const app = createApp({ modules: [demoModule] });
+        const transport = new InMemoryQueueTransport();
+        const worker = createQueueWorker(app, transport, {
+            subscribe: [{ queue: "demo.ping", action: ping }],
+        });
+        await app.start();
+        await worker.start();
+        await transport.enqueue("demo.ping", {
+            input: { pingId: "p-1" },
+            envelope: seedEnvelope({}),
+        });
+        const stored = await app.runtime.getActorStore().load("ping", "p-1");
+        expect(stored).not.toBeNull();
+        expect((stored?.data).pings).toBe(1);
+        await worker.stop();
+    });
+    it("queue messages carry their tenant — actor state stays in that tenant's scope", async () => {
+        const app = createApp({ modules: [demoModule] });
+        const transport = new InMemoryQueueTransport();
+        const worker = createQueueWorker(app, transport, {
+            subscribe: [{ queue: "demo.ping", action: ping }],
+        });
+        await worker.start();
+        await transport.enqueue("demo.ping", {
+            input: { pingId: "p-2" },
+            envelope: seedEnvelope({ tenant: "school-tlv" }),
+        });
+        await transport.enqueue("demo.ping", {
+            input: { pingId: "p-2" },
+            envelope: seedEnvelope({ tenant: "school-jlm" }),
+        });
+        const tlv = await app.runtime.getActorStore().load("ping", "p-2", "school-tlv");
+        const jlm = await app.runtime.getActorStore().load("ping", "p-2", "school-jlm");
+        const def = await app.runtime.getActorStore().load("ping", "p-2");
+        expect((tlv?.data).pings).toBe(1);
+        expect((jlm?.data).pings).toBe(1);
+        expect(def).toBeNull();
+        await worker.stop();
+    });
+    it("delayed messages fire after their delayMs (durable timer transport pattern)", async () => {
+        const app = createApp({ modules: [demoModule] });
+        const transport = new InMemoryQueueTransport();
+        const worker = createQueueWorker(app, transport, {
+            subscribe: [{ queue: "demo.ping", action: ping }],
+        });
+        await worker.start();
+        // 50ms delay — quick for tests.
+        await transport.enqueue("demo.ping", {
+            input: { pingId: "p-delayed" },
+            envelope: seedEnvelope({}),
+            delayMs: 50,
+        });
+        // Not yet — message is in the future.
+        const before = await app.runtime.getActorStore().load("ping", "p-delayed");
+        expect(before).toBeNull();
+        // Wait past the delay.
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        await transport.flush();
+        const after = await app.runtime.getActorStore().load("ping", "p-delayed");
+        expect(after).not.toBeNull();
+        expect((after?.data).pings).toBe(1);
+        await worker.stop();
+    });
+});
+//# sourceMappingURL=queue.test.js.map

package/dist/__tests__/queue.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.test.js","sourceRoot":"","sources":["../../src/__tests__/queue.test.ts"],"names":[],"mappings":"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"}

package/dist/queue-transport.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `QueueTransport` — pluggable queue abstraction. Different deployments use
+ * different queue backends (BullMQ + Redis for prod, in-memory for tests, GCP
+ * Pub/Sub for the cross-region setup); the framework's promise is that the
+ * domain code doesn't change. Each transport routes published messages to
+ * registered consumers; consumers turn them back into action dispatches.
+ *
+ *   const transport = new InMemoryQueueTransport()
+ *   transport.subscribe('submissions.send-review-reminder', async (msg) => {
+ *     await runtime.dispatch(sendReviewReminder, msg.input, msg.envelope)
+ *   })
+ *   await transport.enqueue('submissions.send-review-reminder', {
+ *     input: { submissionId: 'xyz' },
+ *     envelope: seedEnvelope({ tenant: 'school-tlv' })
+ *   })
+ *
+ * Production swap: `new BullMQQueueTransport({ connection })` against the
+ * same interface. The queue worker wire's boot just changes the transport.
+ */
+import type { MessageEnvelope } from "@nwire/envelope";
+export interface QueueMessage<TInput = unknown> {
+    readonly queue: string;
+    readonly input: TInput;
+    readonly envelope: MessageEnvelope;
+    /**
+     * Optional delay in ms before the message becomes visible to consumers.
+     * Production: BullMQ's `delay` option; in-memory: setTimeout.
+     */
+    readonly delayMs?: number;
+    /** Stable id for at-least-once dedup (idempotency). Optional. */
+    readonly messageId?: string;
+}
+export type QueueConsumer<TInput = unknown> = (msg: QueueMessage<TInput>) => Promise<void>;
+export interface QueueTransport {
+    enqueue<TInput>(queue: string, message: Omit<QueueMessage<TInput>, "queue">): Promise<void>;
+    subscribe<TInput>(queue: string, consumer: QueueConsumer<TInput>): void;
+    /** Drain in-flight work and stop consumers. */
+    stop(): Promise<void>;
+}
+/**
+ * Process-local queue. Writes go to a per-queue array; subscribers receive
+ * each message in FIFO order. `delayMs` is honored via setTimeout.
+ *
+ * For tests: deterministic. For dev: works without Redis. Not safe across
+ * processes — production wires use BullMQ or equivalent.
+ */
+export declare class InMemoryQueueTransport implements QueueTransport {
+    private readonly subscribers;
+    private readonly pending;
+    private readonly inflight;
+    private stopped;
+    enqueue<TInput>(queue: string, message: Omit<QueueMessage<TInput>, "queue">): Promise<void>;
+    subscribe<TInput>(queue: string, consumer: QueueConsumer<TInput>): void;
+    stop(): Promise<void>;
+    /** Test-only — drain pending delayed messages synchronously. */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=queue-transport.d.ts.map

package/dist/queue-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-transport.d.ts","sourceRoot":"","sources":["../src/queue-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,OAAO;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,aAAa,CAAC,MAAM,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3F,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5F,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACxE,+CAA+C;IAC/C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,OAAO,CAAS;IAElB,OAAO,CAAC,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC;IAiChB,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,IAAI;IAMjE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,gEAAgE;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/queue-transport.js

@@ -0,0 +1,83 @@
+/**
+ * `QueueTransport` — pluggable queue abstraction. Different deployments use
+ * different queue backends (BullMQ + Redis for prod, in-memory for tests, GCP
+ * Pub/Sub for the cross-region setup); the framework's promise is that the
+ * domain code doesn't change. Each transport routes published messages to
+ * registered consumers; consumers turn them back into action dispatches.
+ *
+ *   const transport = new InMemoryQueueTransport()
+ *   transport.subscribe('submissions.send-review-reminder', async (msg) => {
+ *     await runtime.dispatch(sendReviewReminder, msg.input, msg.envelope)
+ *   })
+ *   await transport.enqueue('submissions.send-review-reminder', {
+ *     input: { submissionId: 'xyz' },
+ *     envelope: seedEnvelope({ tenant: 'school-tlv' })
+ *   })
+ *
+ * Production swap: `new BullMQQueueTransport({ connection })` against the
+ * same interface. The queue worker wire's boot just changes the transport.
+ */
+/**
+ * Process-local queue. Writes go to a per-queue array; subscribers receive
+ * each message in FIFO order. `delayMs` is honored via setTimeout.
+ *
+ * For tests: deterministic. For dev: works without Redis. Not safe across
+ * processes — production wires use BullMQ or equivalent.
+ */
+export class InMemoryQueueTransport {
+    subscribers = new Map();
+    pending = new Set();
+    inflight = [];
+    stopped = false;
+    async enqueue(queue, message) {
+        if (this.stopped) {
+            throw new Error("InMemoryQueueTransport: enqueue after stop");
+        }
+        const full = { queue, ...message };
+        const fan = async () => {
+            const consumers = this.subscribers.get(queue) ?? [];
+            for (const consumer of consumers) {
+                const promise = consumer(full).catch((err) => {
+                    // Surface in dev console; production transports route
+                    // failed messages to their own DLQ.
+                    // eslint-disable-next-line no-console
+                    console.error(`InMemoryQueueTransport consumer for "${queue}" threw:`, err);
+                });
+                this.inflight.push(promise);
+                await promise;
+            }
+        };
+        if (full.delayMs && full.delayMs > 0) {
+            const timer = setTimeout(() => {
+                this.pending.delete(timer);
+                this.inflight.push(fan());
+            }, full.delayMs);
+            if (typeof timer.unref === "function")
+                timer.unref();
+            this.pending.add(timer);
+        }
+        else {
+            // Inline-await so callers and tests see results synchronously
+            // when no delay is requested.
+            await fan();
+        }
+    }
+    subscribe(queue, consumer) {
+        const list = this.subscribers.get(queue) ?? [];
+        list.push(consumer);
+        this.subscribers.set(queue, list);
+    }
+    async stop() {
+        this.stopped = true;
+        for (const t of this.pending)
+            clearTimeout(t);
+        this.pending.clear();
+        await Promise.allSettled(this.inflight);
+        this.subscribers.clear();
+    }
+    /** Test-only — drain pending delayed messages synchronously. */
+    async flush() {
+        await Promise.allSettled([...this.inflight]);
+    }
+}
+//# sourceMappingURL=queue-transport.js.map

package/dist/queue-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-transport.js","sourceRoot":"","sources":["../src/queue-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA0BH;;;;;;GAMG;AACH,MAAM,OAAO,sBAAsB;IAChB,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAC;IACjD,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IACpC,QAAQ,GAAoB,EAAE,CAAC;IACxC,OAAO,GAAG,KAAK,CAAC;IAExB,KAAK,CAAC,OAAO,CACX,KAAa,EACb,OAA4C;QAE5C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,IAAI,GAAyB,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC;QACzD,MAAM,GAAG,GAAG,KAAK,IAAI,EAAE;YACrB,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACpD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;oBAC3C,sDAAsD;oBACtD,oCAAoC;oBACpC,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,wCAAwC,KAAK,UAAU,EAAE,GAAG,CAAC,CAAC;gBAC9E,CAAC,CAAC,CAAC;gBACH,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC5B,MAAM,OAAO,CAAC;YAChB,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAC5B,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACjB,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU;gBAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,8DAA8D;YAC9D,8BAA8B;YAC9B,MAAM,GAAG,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAED,SAAS,CAAS,KAAa,EAAE,QAA+B;QAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,IAAI,CAAC,QAAyB,CAAC,CAAC;QACrC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO;YAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,KAAK;QACT,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,CAAC;CACF"}

package/dist/queue-worker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Queue worker — binds queue messages to action dispatches.
+ *
+ *   const queue = new InMemoryQueueTransport()
+ *   const worker = createQueueWorker(app, queue, {
+ *     subscribe: [
+ *       { queue: 'submissions.send-review-reminder', action: sendReviewReminder },
+ *       { queue: 'lessons.auto-abandon-attempt', action: autoAbandonAttempt }
+ *     ]
+ *   })
+ *   await worker.start()
+ *
+ *   // Producer side (HTTP wire or another worker):
+ *   await queue.enqueue('submissions.send-review-reminder', {
+ *     input: { submissionId },
+ *     envelope: seedEnvelope({ tenant: 'school-tlv' }),
+ *     delayMs: 3 * 86_400_000
+ *   })
+ *
+ * The worker is a thin adapter — every queue→action binding is one line. It
+ * doesn't know about Redis; the transport does. Swap `InMemoryQueueTransport`
+ * for `BullMQQueueTransport` and the same wire boots in production.
+ *
+ * Wire-mode invariance: domain handlers are the same in HTTP and queue wires.
+ * The framework decides where dispatch happens; the handler is unchanged.
+ */
+import type * as forge from "@nwire/forge";
+import type { QueueTransport } from "./queue-transport";
+type App = forge.App;
+type ActionDefinition = forge.ActionDefinition;
+export interface QueueSubscription {
+    /** Queue name to subscribe to. Convention: `<domain>.<verb-noun>`. */
+    readonly queue: string;
+    /** Action to dispatch when a message arrives. Input + envelope come from the message. */
+    readonly action: ActionDefinition;
+}
+export interface CreateQueueWorkerOptions {
+    readonly subscribe: readonly QueueSubscription[];
+}
+export interface QueueWorker {
+    readonly app: App;
+    readonly transport: QueueTransport;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createQueueWorker(app: App, transport: QueueTransport, options: CreateQueueWorkerOptions): QueueWorker;
+export {};
+//# sourceMappingURL=queue-worker.d.ts.map

package/dist/queue-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-worker.d.ts","sourceRoot":"","sources":["../src/queue-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,mBAAmB,CAAC;AAEtE,KAAK,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;AACrB,KAAK,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,wBAAwB,GAChC,WAAW,CAmBb"}

package/dist/queue-worker.js

@@ -0,0 +1,47 @@
+/**
+ * Queue worker — binds queue messages to action dispatches.
+ *
+ *   const queue = new InMemoryQueueTransport()
+ *   const worker = createQueueWorker(app, queue, {
+ *     subscribe: [
+ *       { queue: 'submissions.send-review-reminder', action: sendReviewReminder },
+ *       { queue: 'lessons.auto-abandon-attempt', action: autoAbandonAttempt }
+ *     ]
+ *   })
+ *   await worker.start()
+ *
+ *   // Producer side (HTTP wire or another worker):
+ *   await queue.enqueue('submissions.send-review-reminder', {
+ *     input: { submissionId },
+ *     envelope: seedEnvelope({ tenant: 'school-tlv' }),
+ *     delayMs: 3 * 86_400_000
+ *   })
+ *
+ * The worker is a thin adapter — every queue→action binding is one line. It
+ * doesn't know about Redis; the transport does. Swap `InMemoryQueueTransport`
+ * for `BullMQQueueTransport` and the same wire boots in production.
+ *
+ * Wire-mode invariance: domain handlers are the same in HTTP and queue wires.
+ * The framework decides where dispatch happens; the handler is unchanged.
+ */
+export function createQueueWorker(app, transport, options) {
+    let started = false;
+    return {
+        app,
+        transport,
+        async start() {
+            if (started)
+                return;
+            started = true;
+            for (const subscription of options.subscribe) {
+                transport.subscribe(subscription.queue, async (msg) => {
+                    await app.runtime.dispatch(subscription.action, msg.input, msg.envelope);
+                });
+            }
+        },
+        async stop() {
+            await transport.stop();
+        },
+    };
+}
+//# sourceMappingURL=queue-worker.js.map

package/dist/queue-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-worker.js","sourceRoot":"","sources":["../src/queue-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA0BH,MAAM,UAAU,iBAAiB,CAC/B,GAAQ,EACR,SAAyB,EACzB,OAAiC;IAEjC,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,GAAG;QACH,SAAS;QACT,KAAK,CAAC,KAAK;YACT,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,KAAK,MAAM,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBAC7C,SAAS,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,GAAiB,EAAE,EAAE;oBAClE,MAAM,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;gBAC3E,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI;YACR,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/queue.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@nwire/queue` — queue transport contract + InMemory default + worker factory.
+ *
+ *   QueueTransport interface — pluggable: in-memory (dev), BullMQ (prod), SQS, …
+ *   InMemoryQueueTransport — process-local, honors delayMs via setTimeout
+ *   createQueueWorker(app, transport, { subscribe }) — bind queue → action
+ *
+ * Production deployments use a persistent adapter like `@nwire/queue-bullmq`
+ * (Redis) or `@nwire/queue-sqs` (AWS). Same interface; swap by config.
+ */
+export { InMemoryQueueTransport, type QueueTransport, type QueueMessage, type QueueConsumer, } from "./queue-transport";
+export { createQueueWorker, type QueueWorker, type QueueSubscription, type CreateQueueWorkerOptions, } from "./queue-worker";
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,GAC9B,MAAM,gBAAgB,CAAC"}

package/dist/queue.js

@@ -0,0 +1,13 @@
+/**
+ * `@nwire/queue` — queue transport contract + InMemory default + worker factory.
+ *
+ *   QueueTransport interface — pluggable: in-memory (dev), BullMQ (prod), SQS, …
+ *   InMemoryQueueTransport — process-local, honors delayMs via setTimeout
+ *   createQueueWorker(app, transport, { subscribe }) — bind queue → action
+ *
+ * Production deployments use a persistent adapter like `@nwire/queue-bullmq`
+ * (Redis) or `@nwire/queue-sqs` (AWS). Same interface; swap by config.
+ */
+export { InMemoryQueueTransport, } from "./queue-transport";
+export { createQueueWorker, } from "./queue-worker";
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,sBAAsB,GAIvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,iBAAiB,GAIlB,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nwire/queue",
+  "version": "0.7.0",
+  "description": "Nwire — queue transport contract + InMemory default + createQueueWorker. Production adapters land as @nwire/queue-bullmq, @nwire/queue-sqs, @nwire/queue-pgboss.",
+  "keywords": [
+    "bus",
+    "nwire",
+    "queue",
+    "transport",
+    "worker"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/queue.js",
+  "types": "./dist/queue.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/queue.js",
+      "types": "./dist/queue.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/forge": "0.7.0",
+    "@nwire/envelope": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.0.0",
+    "@nwire/messages": "0.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}