@nwire/nats 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,130 @@
+# @nwire/nats
+
+> NATS-backed `EventBus` — pick core pub/sub or JetStream + DLQ.
+
+## What it does
+
+Two adapters share this package, both satisfying the `@nwire/bus` `EventBus`
+contract — the runtime doesn't know which is wired in:
+
+| Adapter         | Semantics     | Durability                | Pick when                                                  |
+| --------------- | ------------- | ------------------------- | ---------------------------------------------------------- |
+| `NatsEventBus`  | At-most-once  | None (core pub/sub)       | Low-ceremony cross-service fan-out.                        |
+| `NatsBus` (G11) | At-least-once | JetStream + DLQ + retries | Restarts must not drop events; poison messages quarantine. |
+
+Subject layout: `<prefix>.<eventName>`. Distinct prefixes isolate
+deployments on a shared cluster.
+
+## Install
+
+```bash
+pnpm add @nwire/nats nats
+```
+
+## Quick start — JetStream (recommended for production)
+
+```ts
+import { connect } from "nats";
+import { NatsBus } from "@nwire/nats";
+import { lxApp } from "@amit/lx";
+
+const bus = new NatsBus({
+  servers: "nats://nats:4222",
+  prefix: "lemida.events",
+  maxDeliver: 5,
+  ackWaitMs: 2_000,
+  connect,
+});
+await bus.connect();
+
+const app = lxApp.create({ bus, publishToBus: true, appName: "lx-service" });
+await app.start();
+```
+
+## Quick start — core pub/sub
+
+```ts
+import { connect } from "nats";
+import { NatsEventBus } from "@nwire/nats";
+
+const nc = await connect({ servers: "nats://nats:4222" });
+const bus = new NatsEventBus({ connection: nc, prefix: "lemida" });
+```
+
+## `NatsBus` config
+
+| Option       | Default               | Meaning                                                   |
+| ------------ | --------------------- | --------------------------------------------------------- |
+| `servers`    | (required)            | NATS URL(s).                                              |
+| `name`       | _none_                | Client name (visible in `nats-top`).                      |
+| `prefix`     | `nwire.events`        | Subject prefix; the stream binds `<prefix>.>`.            |
+| `streamName` | derived from `prefix` | JetStream stream name.                                    |
+| `dlqSubject` | `<prefix>.dlq`        | Where exhausted messages land.                            |
+| `maxDeliver` | `5`                   | How many times JetStream redelivers before DLQ.           |
+| `ackWaitMs`  | `1000`                | Ack window; also used as nak backoff.                     |
+| `connect`    | (required)            | `connect` from the `nats` package (injected for testing). |
+| `logger`     | no-op                 | `@nwire/logger` instance.                                 |
+
+## DLQ pattern
+
+When a handler throws and JetStream's `maxDeliver` is exhausted, `NatsBus`
+publishes a `BusDeadLetterRecord` onto `dlqSubject`:
+
+```ts
+{
+  originalSubject: "nwire.events.billing.charge-failed",
+  event: { /* the full BusEventMessage */ },
+  error: { message: "card declined", stack: "..." },
+  deliveryCount: 5,
+  deadLetteredAt: "2026-05-29T12:00:00.000Z",
+}
+```
+
+Drain it into your incident pipeline by subscribing through any NATS client:
+
+```ts
+import { connect } from "nats";
+
+const raw = await connect({ servers: "nats://nats:4222" });
+const sub = raw.subscribe("nwire.events.dlq");
+for await (const m of sub) {
+  const record = JSON.parse(new TextDecoder().decode(m.data));
+  await sentry.captureMessage(`Dead-letter ${record.event.eventName}`, {
+    extra: record,
+  });
+}
+```
+
+## Local development
+
+`docker-compose.yml` at the repo root ships a `nats` service with JetStream
+enabled. Start it with `nwire infra up` (or `docker compose up -d nats`).
+
+## Testing
+
+Unit tests run without docker (fake NATS client). Integration tests spin up
+a real `nats:2-alpine` container via `testcontainers` and are gated behind
+`RUN_INTEGRATION=1`:
+
+```bash
+pnpm --filter @nwire/nats test                # unit only
+RUN_INTEGRATION=1 pnpm --filter @nwire/nats test:integration
+```
+
+## Within nwire-app
+
+Wire the bus on `createApp` and the runtime fans cross-service events
+through it automatically — no domain code changes.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  modules: [
+    /* ... */
+  ],
+  bus,
+  publishToBus: true,
+  appName: "lx-service",
+});
+```

package/dist/bus-nats.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `@nwire/nats` — NATS-backed `EventBus` for production.
+ *
+ * Subject layout: `<prefix>.<eventName>`. NATS core pub/sub by default
+ * (at-most-once, fan-out); switch to JetStream for at-least-once
+ * durability — same contract.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier).
+ */
+import type { EventBus, BusEventMessage, BusSubscriber } from "@nwire/bus";
+/**
+ * Minimal NATS connection contract — what we actually consume. Lets us
+ * accept either the classic `nats` package's `NatsConnection` or the newer
+ * `@nats-io/transport-node` equivalent without binding to one.
+ */
+export interface NatsConnectionLike {
+    publish(subject: string, data: Uint8Array | string): void;
+    subscribe(subject: string, opts?: {
+        callback?: NatsSubscriptionCallback;
+    }): NatsSubscriptionLike;
+    drain(): Promise<void>;
+    close?(): Promise<void>;
+    isClosed?(): boolean;
+}
+export type NatsSubscriptionCallback = (err: unknown, msg: {
+    data: Uint8Array | string;
+    subject: string;
+}) => void | Promise<void>;
+export interface NatsSubscriptionLike {
+    unsubscribe(): void;
+    /** Iterator form (newer NATS clients) — optional; callback form is preferred. */
+    [Symbol.asyncIterator]?(): AsyncIterator<{
+        data: Uint8Array | string;
+        subject: string;
+    }>;
+}
+export interface NatsEventBusOptions {
+    readonly connection: NatsConnectionLike;
+    /** Subject prefix (`<prefix>.<eventName>`). Default `'nwire'`. */
+    readonly prefix?: string;
+    /** Optional JSON serializer override (default: `JSON.stringify` + TextEncoder). */
+    readonly serialize?: (value: unknown) => Uint8Array;
+    /** Optional JSON deserializer override. */
+    readonly deserialize?: (data: Uint8Array | string) => unknown;
+}
+export declare class NatsEventBus implements EventBus {
+    private readonly connection;
+    private readonly prefix;
+    private readonly serialize;
+    private readonly deserialize;
+    private readonly subscriptions;
+    private stopped;
+    constructor(options: NatsEventBusOptions);
+    private subjectFor;
+    publish(msg: BusEventMessage): Promise<void>;
+    subscribe(eventName: string, subscriber: BusSubscriber): void;
+    stop(): Promise<void>;
+}

package/dist/bus-nats.js

@@ -0,0 +1,101 @@
+/**
+ * `@nwire/nats` — NATS-backed `EventBus` for production.
+ *
+ * Subject layout: `<prefix>.<eventName>`. NATS core pub/sub by default
+ * (at-most-once, fan-out); switch to JetStream for at-least-once
+ * durability — same contract.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier).
+ */
+const defaultEncoder = new TextEncoder();
+const defaultDecoder = new TextDecoder();
+function defaultSerialize(value) {
+    return defaultEncoder.encode(JSON.stringify(value));
+}
+function defaultDeserialize(data) {
+    const s = typeof data === "string" ? data : defaultDecoder.decode(data);
+    return JSON.parse(s);
+}
+export class NatsEventBus {
+    connection;
+    prefix;
+    serialize;
+    deserialize;
+    subscriptions = [];
+    stopped = false;
+    constructor(options) {
+        this.connection = options.connection;
+        this.prefix = options.prefix ?? "nwire";
+        this.serialize = options.serialize ?? defaultSerialize;
+        this.deserialize = options.deserialize ?? defaultDeserialize;
+    }
+    subjectFor(eventName) {
+        return `${this.prefix}.${eventName}`;
+    }
+    async publish(msg) {
+        if (this.stopped) {
+            throw new Error("NatsEventBus: publish after stop");
+        }
+        const subject = this.subjectFor(msg.eventName);
+        const data = this.serialize({
+            eventName: msg.eventName,
+            payload: msg.payload,
+            envelope: msg.envelope,
+            origin: msg.origin,
+        });
+        this.connection.publish(subject, data);
+    }
+    subscribe(eventName, subscriber) {
+        if (this.stopped) {
+            throw new Error("NatsEventBus: subscribe after stop");
+        }
+        const subject = this.subjectFor(eventName);
+        const sub = this.connection.subscribe(subject, {
+            callback: async (err, raw) => {
+                if (err) {
+                    // eslint-disable-next-line no-console
+                    console.error(`NatsEventBus subscription error on "${subject}":`, err);
+                    return;
+                }
+                let decoded;
+                try {
+                    decoded = this.deserialize(raw.data);
+                }
+                catch (decodeErr) {
+                    // eslint-disable-next-line no-console
+                    console.error(`NatsEventBus: malformed message on "${subject}":`, decodeErr);
+                    return;
+                }
+                try {
+                    await subscriber(decoded);
+                }
+                catch (subErr) {
+                    // eslint-disable-next-line no-console
+                    console.error(`NatsEventBus subscriber for "${subject}" threw:`, subErr);
+                }
+            },
+        });
+        this.subscriptions.push(sub);
+    }
+    async stop() {
+        this.stopped = true;
+        for (const sub of this.subscriptions) {
+            try {
+                sub.unsubscribe();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        this.subscriptions.length = 0;
+        // Drain flushes pending publishes + closes the connection cleanly.
+        // We don't own the connection (caller passes it in) but draining
+        // before they close is the polite shape.
+        try {
+            await this.connection.drain();
+        }
+        catch {
+            // best-effort
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@nwire/nats` — NATS-backed `EventBus` adapters.
+ *
+ * Two adapters share this package:
+ *
+ *   - `NatsEventBus` — core NATS pub/sub. At-most-once, fan-out. The default
+ *     for low-ceremony cross-service eventing.
+ *   - `NatsBus` — JetStream-backed. At-least-once, durable, with a DLQ for
+ *     poison messages. Pick this when restarts must not drop events.
+ *
+ * Both satisfy the same `EventBus` contract; the runtime doesn't know the
+ * difference.
+ */
+export { NatsEventBus, type NatsConnectionLike as NatsCoreConnectionLike, type NatsEventBusOptions, type NatsSubscriptionCallback, type NatsSubscriptionLike, } from "./bus-nats.js";
+export { NatsBus, natsBus, type BusDeadLetterRecord, type ConsumerLike, type JetStreamClientLike, type JetStreamConsumersLike, type JetStreamManagerLike, type JsMsgLike, type NatsBusOptions, type NatsConnectFn, type NatsConnectionLike, } from "./nats-bus.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@nwire/nats` — NATS-backed `EventBus` adapters.
+ *
+ * Two adapters share this package:
+ *
+ *   - `NatsEventBus` — core NATS pub/sub. At-most-once, fan-out. The default
+ *     for low-ceremony cross-service eventing.
+ *   - `NatsBus` — JetStream-backed. At-least-once, durable, with a DLQ for
+ *     poison messages. Pick this when restarts must not drop events.
+ *
+ * Both satisfy the same `EventBus` contract; the runtime doesn't know the
+ * difference.
+ */
+export { NatsEventBus, } from "./bus-nats.js";
+export { NatsBus, natsBus, } from "./nats-bus.js";

package/dist/nats-bus.d.ts

@@ -0,0 +1,158 @@
+/**
+ * `NatsBus` — JetStream-backed `EventBus` with at-least-once delivery + DLQ.
+ *
+ * Subject layout: `<prefix>.<eventName>` (default prefix `nwire.events`).
+ * A single JetStream stream binds the prefix (`<prefix>.>`) so every event
+ * gets durably acked at publish time and replayed to subscribers via durable
+ * consumers. Handlers ack only after success; on failure the message is
+ * nak'd and re-delivered up to the consumer's `maxDeliver`. Once exhausted,
+ * the bus drops a structured record on `dlqSubject` (default `<prefix>.dlq`).
+ *
+ * Use this when you need durability across service restarts. Pair with the
+ * existing core-NATS `NatsEventBus` when at-most-once fan-out is enough.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier); BRIEFS — G11 (DLQ).
+ */
+import type { BusEventMessage, BusSubscriber, EventBus } from "@nwire/bus";
+import type { Logger } from "@nwire/logger";
+/**
+ * Minimal NATS surface we actually call. Keeping it structural lets us mock
+ * in unit tests and accept either the classic `nats` package or the newer
+ * `@nats-io/transport-node` family without binding the import.
+ */
+export interface JetStreamClientLike {
+    publish(subject: string, data: Uint8Array): Promise<{
+        seq: number;
+    }>;
+}
+export interface JetStreamManagerLike {
+    streams: {
+        info(stream: string): Promise<unknown>;
+        add(config: {
+            name: string;
+            subjects: string[];
+            retention?: string;
+            max_msgs?: number;
+        }): Promise<unknown>;
+    };
+    consumers: {
+        add(stream: string, config: Record<string, unknown>): Promise<unknown>;
+    };
+}
+export interface JsMsgLike {
+    readonly subject: string;
+    readonly data: Uint8Array;
+    readonly info: {
+        redeliveryCount: number;
+        deliveryCount?: number;
+    };
+    ack(): void;
+    nak(delayMs?: number): void;
+    term(): void;
+}
+export interface ConsumerLike {
+    consume(opts?: {
+        callback?: (msg: JsMsgLike) => void | Promise<void>;
+    }): Promise<{
+        stop(): Promise<void> | void;
+    }>;
+}
+export interface JetStreamConsumersLike {
+    get(stream: string, durable: string): Promise<ConsumerLike>;
+}
+export interface NatsConnectionLike {
+    jetstream(): JetStreamClientLike & {
+        consumers: JetStreamConsumersLike;
+    };
+    jetstreamManager(): Promise<JetStreamManagerLike>;
+    publish(subject: string, data: Uint8Array): void;
+    drain(): Promise<void>;
+    close(): Promise<void>;
+    isClosed?(): boolean;
+}
+/**
+ * Caller-supplied factory; we don't import `nats` at module load time so the
+ * package is tree-shake-friendly and unit tests don't pay the cost.
+ */
+export type NatsConnectFn = (opts: {
+    servers: string | string[];
+    name?: string;
+}) => Promise<NatsConnectionLike>;
+export interface NatsBusOptions {
+    /** One or more NATS server URLs (e.g. `nats://localhost:4222`). */
+    readonly servers: string | string[];
+    /** Client name reported to NATS — handy in `nats-top`. */
+    readonly name?: string;
+    /**
+     * Subject prefix; the bus owns `<prefix>.>` end-to-end. Default
+     * `'nwire.events'`. Use distinct prefixes to isolate deployments on a
+     * shared cluster.
+     */
+    readonly prefix?: string;
+    /** DLQ subject; default `'<prefix>.dlq'`. */
+    readonly dlqSubject?: string;
+    /** Stream name; default derived from prefix (`NWIRE_EVENTS`). */
+    readonly streamName?: string;
+    /** Max times JetStream will redeliver before we route to DLQ. Default 5. */
+    readonly maxDeliver?: number;
+    /** Backoff between redeliveries, milliseconds. Default 1000. */
+    readonly ackWaitMs?: number;
+    /**
+     * Injected `connect` from the `nats` package. We accept it rather than
+     * import it so test harnesses can supply a fake without docker.
+     */
+    readonly connect: NatsConnectFn;
+    /** Optional structured logger; defaults to no-op. */
+    readonly logger?: Logger;
+    /** JSON serializer override; defaults to `TextEncoder` + `JSON.stringify`. */
+    readonly serialize?: (value: unknown) => Uint8Array;
+    /** JSON deserializer override; defaults to `TextDecoder` + `JSON.parse`. */
+    readonly deserialize?: (data: Uint8Array) => unknown;
+}
+/**
+ * Shape we publish onto `dlqSubject` when a message exhausts its
+ * redelivery budget. Consumers can attach a normal `subscribe` (on the DLQ
+ * subject, treated as just another event name) to drain it into ops tools.
+ */
+export interface BusDeadLetterRecord {
+    readonly originalSubject: string;
+    readonly event: BusEventMessage;
+    readonly error: {
+        message: string;
+        stack?: string;
+    };
+    readonly deliveryCount: number;
+    readonly deadLetteredAt: string;
+}
+export declare class NatsBus implements EventBus {
+    private readonly opts;
+    private connection;
+    private js;
+    private readonly runningConsumers;
+    private stopped;
+    private connecting;
+    constructor(options: NatsBusOptions);
+    private subjectFor;
+    /**
+     * Opens the NATS connection (idempotent) and ensures the JetStream stream
+     * for `<prefix>.>` exists. Safe to call multiple times — concurrent
+     * callers share the same in-flight promise.
+     */
+    connect(): Promise<void>;
+    publish(msg: BusEventMessage): Promise<void>;
+    /**
+     * Subscribe with at-least-once semantics. We create a durable consumer
+     * derived from `(streamName, eventName)` so multiple processes with the
+     * same durable share work, and restarts resume cleanly.
+     */
+    subscribe(eventName: string, subscriber: BusSubscriber): void;
+    private attachConsumer;
+    private handleDelivery;
+    private routeToDlq;
+    /** Graceful shutdown — drain consumers, then drain the connection. */
+    stop(): Promise<void>;
+    /** Alias for {@link stop} — matches the task's `close()` naming. */
+    close(): Promise<void>;
+}
+/** Factory mirror — for parity with the other `@nwire/*` adapters. */
+export declare function natsBus(options: NatsBusOptions): NatsBus;

package/dist/nats-bus.js

@@ -0,0 +1,275 @@
+/**
+ * `NatsBus` — JetStream-backed `EventBus` with at-least-once delivery + DLQ.
+ *
+ * Subject layout: `<prefix>.<eventName>` (default prefix `nwire.events`).
+ * A single JetStream stream binds the prefix (`<prefix>.>`) so every event
+ * gets durably acked at publish time and replayed to subscribers via durable
+ * consumers. Handlers ack only after success; on failure the message is
+ * nak'd and re-delivered up to the consumer's `maxDeliver`. Once exhausted,
+ * the bus drops a structured record on `dlqSubject` (default `<prefix>.dlq`).
+ *
+ * Use this when you need durability across service restarts. Pair with the
+ * existing core-NATS `NatsEventBus` when at-most-once fan-out is enough.
+ *
+ * See: architecture-sketch.html §05 (Adapters tier); BRIEFS — G11 (DLQ).
+ */
+const defaultEncoder = new TextEncoder();
+const defaultDecoder = new TextDecoder();
+function defaultSerialize(value) {
+    return defaultEncoder.encode(JSON.stringify(value));
+}
+function defaultDeserialize(data) {
+    return JSON.parse(defaultDecoder.decode(data));
+}
+function streamNameFromPrefix(prefix) {
+    return prefix.replace(/[^A-Za-z0-9]/g, "_").toUpperCase();
+}
+function noopLogger() {
+    const l = {
+        debug() { },
+        info() { },
+        warn() { },
+        error() { },
+        child() {
+            return l;
+        },
+    };
+    return l;
+}
+export class NatsBus {
+    opts;
+    connection = null;
+    js = null;
+    runningConsumers = [];
+    stopped = false;
+    connecting = null;
+    constructor(options) {
+        const prefix = options.prefix ?? "nwire.events";
+        this.opts = {
+            servers: options.servers,
+            name: options.name,
+            prefix,
+            dlqSubject: options.dlqSubject ?? `${prefix}.dlq`,
+            streamName: options.streamName ?? streamNameFromPrefix(prefix),
+            maxDeliver: options.maxDeliver ?? 5,
+            ackWaitMs: options.ackWaitMs ?? 1000,
+            connect: options.connect,
+            logger: options.logger ?? noopLogger(),
+            serialize: options.serialize ?? defaultSerialize,
+            deserialize: options.deserialize ?? defaultDeserialize,
+        };
+    }
+    subjectFor(eventName) {
+        return `${this.opts.prefix}.${eventName}`;
+    }
+    /**
+     * Opens the NATS connection (idempotent) and ensures the JetStream stream
+     * for `<prefix>.>` exists. Safe to call multiple times — concurrent
+     * callers share the same in-flight promise.
+     */
+    async connect() {
+        if (this.stopped)
+            throw new Error("NatsBus: connect after stop");
+        if (this.connection)
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = (async () => {
+            const nc = await this.opts.connect({
+                servers: this.opts.servers,
+                name: this.opts.name,
+            });
+            this.connection = nc;
+            this.js = nc.jetstream();
+            const jsm = await nc.jetstreamManager();
+            const streamSubject = `${this.opts.prefix}.>`;
+            try {
+                await jsm.streams.info(this.opts.streamName);
+                this.opts.logger.debug("nats-bus: stream exists", {
+                    stream: this.opts.streamName,
+                });
+            }
+            catch {
+                await jsm.streams.add({
+                    name: this.opts.streamName,
+                    subjects: [streamSubject],
+                });
+                this.opts.logger.info("nats-bus: stream created", {
+                    stream: this.opts.streamName,
+                    subjects: streamSubject,
+                });
+            }
+        })();
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    async publish(msg) {
+        if (this.stopped)
+            throw new Error("NatsBus: publish after stop");
+        if (!this.js)
+            await this.connect();
+        if (!this.js)
+            throw new Error("NatsBus: not connected");
+        const subject = this.subjectFor(msg.eventName);
+        const data = this.opts.serialize({
+            eventName: msg.eventName,
+            payload: msg.payload,
+            envelope: msg.envelope,
+            origin: msg.origin,
+        });
+        const ack = await this.js.publish(subject, data);
+        this.opts.logger.debug("nats-bus: published", {
+            subject,
+            seq: ack.seq,
+        });
+    }
+    /**
+     * Subscribe with at-least-once semantics. We create a durable consumer
+     * derived from `(streamName, eventName)` so multiple processes with the
+     * same durable share work, and restarts resume cleanly.
+     */
+    subscribe(eventName, subscriber) {
+        if (this.stopped)
+            throw new Error("NatsBus: subscribe after stop");
+        void this.attachConsumer(eventName, subscriber).catch((err) => {
+            this.opts.logger.error("nats-bus: subscribe failed", {
+                eventName,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
+    async attachConsumer(eventName, subscriber) {
+        if (!this.connection || !this.js)
+            await this.connect();
+        if (!this.connection || !this.js)
+            throw new Error("NatsBus: not connected");
+        const subject = this.subjectFor(eventName);
+        const durable = `${this.opts.streamName}_${eventName.replace(/[^A-Za-z0-9]/g, "_")}`;
+        const jsm = await this.connection.jetstreamManager();
+        try {
+            await jsm.consumers.add(this.opts.streamName, {
+                durable_name: durable,
+                ack_policy: "explicit",
+                filter_subject: subject,
+                max_deliver: this.opts.maxDeliver,
+                ack_wait: this.opts.ackWaitMs * 1_000_000, // nanos
+            });
+        }
+        catch (err) {
+            // Already exists is fine; surface other failures.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!/already in use|exists/i.test(msg))
+                throw err;
+        }
+        const consumer = await this.js.consumers.get(this.opts.streamName, durable);
+        const running = await consumer.consume({
+            callback: async (jsMsg) => {
+                await this.handleDelivery(jsMsg, subscriber);
+            },
+        });
+        this.runningConsumers.push(running);
+    }
+    async handleDelivery(jsMsg, subscriber) {
+        let decoded;
+        try {
+            decoded = this.opts.deserialize(jsMsg.data);
+        }
+        catch (err) {
+            this.opts.logger.error("nats-bus: malformed message — terminating", {
+                subject: jsMsg.subject,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            jsMsg.term();
+            return;
+        }
+        const deliveryCount = jsMsg.info.deliveryCount ?? jsMsg.info.redeliveryCount + 1;
+        try {
+            await subscriber(decoded);
+            jsMsg.ack();
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (deliveryCount >= this.opts.maxDeliver) {
+                await this.routeToDlq(jsMsg, decoded, error, deliveryCount);
+                jsMsg.term();
+            }
+            else {
+                this.opts.logger.warn("nats-bus: handler threw — nak for retry", {
+                    subject: jsMsg.subject,
+                    deliveryCount,
+                    error: error.message,
+                });
+                jsMsg.nak(this.opts.ackWaitMs);
+            }
+        }
+    }
+    async routeToDlq(jsMsg, event, error, deliveryCount) {
+        if (!this.js)
+            return;
+        const record = {
+            originalSubject: jsMsg.subject,
+            event,
+            error: { message: error.message, stack: error.stack },
+            deliveryCount,
+            deadLetteredAt: new Date().toISOString(),
+        };
+        try {
+            await this.js.publish(this.opts.dlqSubject, this.opts.serialize(record));
+            this.opts.logger.error("nats-bus: routed to DLQ", {
+                subject: jsMsg.subject,
+                dlqSubject: this.opts.dlqSubject,
+                deliveryCount,
+                error: error.message,
+            });
+        }
+        catch (publishErr) {
+            this.opts.logger.error("nats-bus: DLQ publish failed", {
+                subject: jsMsg.subject,
+                error: publishErr instanceof Error ? publishErr.message : String(publishErr),
+            });
+        }
+    }
+    /** Graceful shutdown — drain consumers, then drain the connection. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        for (const c of this.runningConsumers) {
+            try {
+                await c.stop();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        this.runningConsumers.length = 0;
+        if (this.connection) {
+            try {
+                await this.connection.drain();
+            }
+            catch {
+                // best-effort
+            }
+            try {
+                await this.connection.close();
+            }
+            catch {
+                // best-effort
+            }
+            this.connection = null;
+        }
+        this.js = null;
+    }
+    /** Alias for {@link stop} — matches the task's `close()` naming. */
+    close() {
+        return this.stop();
+    }
+}
+/** Factory mirror — for parity with the other `@nwire/*` adapters. */
+export function natsBus(options) {
+    return new NatsBus(options);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@nwire/nats",
+  "version": "0.10.0",
+  "description": "Nwire — NATS-backed EventBus adapter. Core pub/sub OR JetStream (at-least-once + DLQ) — same EventBus contract.",
+  "keywords": [
+    "adapter",
+    "bus",
+    "dlq",
+    "jetstream",
+    "messaging",
+    "nats",
+    "nwire",
+    "pubsub"
+  ],
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nwire/bus": "0.10.0",
+    "@nwire/logger": "0.10.0",
+    "@nwire/envelope": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "nats": "^2.29.0",
+    "testcontainers": "^10.13.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "nats": "^2.29.0"
+  },
+  "peerDependenciesMeta": {
+    "nats": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --dir src",
+    "test:integration": "RUN_INTEGRATION=1 vitest run --dir src"
+  }
+}