@zmdb/transport-nats 1.0.0-beta.1

package/README.md

@@ -0,0 +1,61 @@
+# @zmdb/transport-nats
+
+`@zmdb/transport-nats` connects the public `@zmdb/app/messaging` transport strategy contract to core NATS.
+
+It supports native `*` and final-`>` subjects, queue groups, one-way events, request/reply, cancellation, deadlines, and bounded shutdown. It does not imply JetStream durability or own a
+process-global connection.
+
+## Install
+
+```bash
+yarn add @zmdb/transport-nats@1.0.0-beta.1 @nats-io/transport-node@^3.4.0
+```
+
+> **Prerelease** (`1.0.0-beta.1`). Requires **Node.js 26+** and is **ESM-only**. Ships built ESM `.js` + `.d.ts` under `./dist`.
+
+The sole peer is `@nats-io/transport-node@^3.4.0`. Neither it nor this package is installed by `yarn add zmdb@1.0.0-beta.1`.
+
+## Usage
+
+```ts
+import { transportExtension } from '@zmdb/app/messaging';
+import { createNatsStrategy } from '@zmdb/transport-nats';
+
+const connection = process.env.NATS_URL;
+if (connection === undefined) throw new Error('NATS_URL is required');
+
+const nats = createNatsStrategy({
+  connection: { servers: connection },
+  subscriptions: [{ subject: 'orders.*', queue: 'orders-workers' }],
+  onError: error => console.error(error),
+});
+
+const extension = transportExtension({
+  transports: [nats],
+  dispatcher: {
+    onUnhandled: message => console.warn('unhandled', message.pattern),
+    onInvalidPayload: (message, error) => console.error('invalid', message.pattern, error),
+    onHandlerError: (message, error) => console.error('handler', message.pattern, error),
+    onUndeliverable: (message, settlement) => console.error('dropped', message.pattern, settlement),
+  },
+});
+
+void extension;
+```
+
+Core NATS is at-most-once. `redelivery` and `deadLetter` are therefore `false`, so an application attaching this strategy must provide `dispatcher.onUndeliverable`.
+
+`transportExtension` starts the strategy, stops intake, waits for accepted dispatches within the application grace budget, drains the NATS connection, and closes it. The strategy creates no
+process-global connection.
+
+## Entry points
+
+- `@zmdb/transport-nats` — `createNatsStrategy`, `NatsStrategyOptions`, and `NatsSubscription`.
+
+## Documentation
+
+Full docs: **https://ambasta.github.io/zmdb/**
+
+## License
+
+GNU General Public License v3.0 or later (GPL-3.0-or-later) — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { type NodeConnectionOptions } from '@nats-io/transport-node';
+import { type TransportErrorSink, type TransportStrategy } from '@zmdb/app/messaging';
+export interface NatsSubscription {
+    /** NATS subject; `*` and a final `>` use native NATS token semantics. */
+    readonly subject: string;
+    /** Queue group for horizontally balanced delivery. */
+    readonly queue?: string;
+}
+export interface NatsStrategyOptions {
+    readonly connection?: NodeConnectionOptions;
+    readonly name?: string;
+    readonly onError: TransportErrorSink;
+    readonly subscriptions: readonly NatsSubscription[];
+}
+/**
+ * Core NATS strategy.
+ *
+ * Core NATS is at-most-once: successful settlements need no acknowledgement,
+ * while `retry` and `dead` cannot be honoured after delivery. Queue groups and
+ * subject wildcards are native subscription features; wildcard membership is
+ * also checked through a startup-built trie rather than a pattern scan.
+ */
+export declare function createNatsStrategy(options: NatsStrategyOptions): TransportStrategy;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,qBAAqB,EAE3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAWL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAQ7B,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACrD;AAoBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,iBAAiB,CAsLlF"}

package/dist/index.js

@@ -0,0 +1,197 @@
+import { connect, createInbox, } from '@nats-io/transport-node';
+import { abortError, decodeDelivery, decodeReply, encodeDelivery, encodeReply, InFlight, MessageTimeoutError, reportTransportError, withinGrace, } from '@zmdb/app/messaging';
+import { createNatsSubjectMatcher } from './matcher.js';
+function bytes(text) {
+    return new TextEncoder().encode(text);
+}
+function validateSubscriptions(subscriptions) {
+    const seen = new Set();
+    return subscriptions.map(subscription => {
+        if (subscription.subject.length === 0) {
+            throw new RangeError('@zmdb/transport-nats: a NATS subscription subject cannot be empty');
+        }
+        if (subscription.queue !== undefined && subscription.queue.length === 0) {
+            throw new RangeError('@zmdb/transport-nats: a NATS queue group cannot be empty');
+        }
+        const key = `${subscription.subject}\u0000${subscription.queue ?? ''}`;
+        if (seen.has(key)) {
+            throw new Error(`@zmdb/transport-nats: duplicate NATS subscription "${subscription.subject}"`);
+        }
+        seen.add(key);
+        return { ...subscription };
+    });
+}
+/**
+ * Core NATS strategy.
+ *
+ * Core NATS is at-most-once: successful settlements need no acknowledgement,
+ * while `retry` and `dead` cannot be honoured after delivery. Queue groups and
+ * subject wildcards are native subscription features; wildcard membership is
+ * also checked through a startup-built trie rather than a pattern scan.
+ */
+export function createNatsStrategy(options) {
+    const subscriptions = validateSubscriptions(options.subscriptions);
+    const matcher = createNatsSubjectMatcher(subscriptions.map(subscription => subscription.subject));
+    const inFlight = new InFlight(options.onError);
+    const name = options.name ?? 'nats';
+    let connection;
+    let activeSubscriptions = [];
+    let started = false;
+    let closed = false;
+    return {
+        name,
+        capabilities: { redelivery: false, deadLetter: false, requestResponse: true },
+        async listen(dispatch) {
+            if (started) {
+                throw new Error('@zmdb/transport-nats: NATS strategy is already listening');
+            }
+            if (closed) {
+                throw new Error('@zmdb/transport-nats: NATS strategy is closed');
+            }
+            started = true;
+            const nextConnection = await connect(options.connection);
+            const nextSubscriptions = [];
+            try {
+                for (const subscription of subscriptions) {
+                    const opened = nextConnection.subscribe(subscription.subject, {
+                        ...(subscription.queue === undefined ? {} : { queue: subscription.queue }),
+                        callback(error, message) {
+                            if (error !== null) {
+                                reportTransportError(options.onError, error);
+                                return;
+                            }
+                            void inFlight.run(async () => {
+                                if (!matcher.matches(message.subject)) {
+                                    throw new Error(`@zmdb/transport-nats: NATS delivered unsubscribed subject "${message.subject}"`);
+                                }
+                                const delivery = decodeDelivery(message.subject, message.string(), 1, message.reply === undefined ? {} : { replyTo: message.reply });
+                                const outcome = await dispatch(delivery);
+                                if (outcome.reply !== undefined && !message.respond(bytes(encodeReply(outcome.reply)))) {
+                                    throw new Error('@zmdb/transport-nats: NATS request has no reply subject');
+                                }
+                            });
+                        },
+                    });
+                    nextSubscriptions.push(opened);
+                }
+                await nextConnection.flush();
+            }
+            catch (error) {
+                await nextConnection.close();
+                throw error;
+            }
+            connection = nextConnection;
+            activeSubscriptions = nextSubscriptions;
+            void nextConnection.closed().then(error => {
+                if (error !== undefined) {
+                    reportTransportError(options.onError, error);
+                }
+            }, error => reportTransportError(options.onError, error));
+        },
+        async send(request) {
+            const activeConnection = connection;
+            if (activeConnection === undefined) {
+                throw new Error('@zmdb/transport-nats: NATS strategy is not listening');
+            }
+            if (request.signal.aborted) {
+                throw abortError(request.signal);
+            }
+            const inbox = createInbox();
+            let responseSubscription;
+            let timer;
+            let abort = () => undefined;
+            let resolveResponse = (_reply) => undefined;
+            let rejectResponse = (_error) => undefined;
+            let finished = false;
+            const response = new Promise((resolve, reject) => {
+                resolveResponse = resolve;
+                rejectResponse = reject;
+            });
+            const cleanup = () => {
+                responseSubscription?.unsubscribe();
+                request.signal.removeEventListener('abort', abort);
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+            };
+            const fail = (error) => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                cleanup();
+                rejectResponse(error);
+            };
+            const succeed = (reply) => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                cleanup();
+                resolveResponse(reply);
+            };
+            abort = () => fail(abortError(request.signal));
+            try {
+                responseSubscription = activeConnection.subscribe(inbox, {
+                    max: 1,
+                    callback(error, message) {
+                        if (error !== null) {
+                            fail(error);
+                            return;
+                        }
+                        try {
+                            succeed(decodeReply(message.string()));
+                        }
+                        catch (decodeError) {
+                            fail(decodeError);
+                        }
+                    },
+                });
+                request.signal.addEventListener('abort', abort, { once: true });
+                timer = setTimeout(() => {
+                    fail(new MessageTimeoutError(request.pattern, request.timeoutMs, request.correlationId));
+                }, request.timeoutMs);
+                await activeConnection.flush();
+                if (!finished) {
+                    activeConnection.publish(request.pattern, bytes(encodeDelivery(request.payload, request, { correlationId: request.correlationId })), { reply: inbox });
+                }
+            }
+            catch (error) {
+                fail(error);
+            }
+            return response;
+        },
+        async emit(pattern, payload, carrier) {
+            const activeConnection = connection;
+            if (activeConnection === undefined) {
+                throw new Error('@zmdb/transport-nats: NATS strategy is not listening');
+            }
+            activeConnection.publish(pattern, bytes(encodeDelivery(payload, carrier)));
+        },
+        async close(graceMs) {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            const activeConnection = connection;
+            const subscriptionsToClose = activeSubscriptions;
+            connection = undefined;
+            activeSubscriptions = [];
+            if (activeConnection === undefined) {
+                return;
+            }
+            const graceful = (async () => {
+                await Promise.all(subscriptionsToClose.map(subscription => subscription.drain()));
+                inFlight.stop();
+                await inFlight.settled();
+                await activeConnection.flush();
+                await activeConnection.close();
+            })();
+            if (!(await withinGrace(graceful, graceMs))) {
+                await activeConnection.close();
+                throw new Error(`@zmdb/transport-nats: NATS strategy did not drain within ${String(graceMs)}ms`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/matcher.d.ts

@@ -0,0 +1,9 @@
+export interface NatsSubjectMatcher {
+    matches(subject: string): boolean;
+}
+/**
+ * Compile NATS `*`/`>` subscriptions into a trie. Matching walks subject
+ * tokens and active trie nodes; it never iterates the configured patterns.
+ */
+export declare function createNatsSubjectMatcher(patterns: readonly string[]): NatsSubjectMatcher;
+//# sourceMappingURL=matcher.d.ts.map

package/dist/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":"AA6CA,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAoCxF"}

package/dist/matcher.js

@@ -0,0 +1,84 @@
+class SubjectNode {
+    literals = new Map();
+    one;
+    tail = false;
+    terminal = false;
+}
+function tokens(value, description) {
+    const parts = value.split('.');
+    if (parts.length === 0 || parts.some(part => part.length === 0)) {
+        throw new RangeError(`@zmdb/transport-nats: ${description} must contain non-empty dot-separated tokens`);
+    }
+    return parts;
+}
+function add(root, pattern) {
+    const parts = tokens(pattern, 'a NATS subscription');
+    let node = root;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        if (part === '>') {
+            if (index !== parts.length - 1) {
+                throw new RangeError('@zmdb/transport-nats: a NATS > wildcard must be the final token');
+            }
+            node.tail = true;
+            return;
+        }
+        if (part === '*') {
+            node.one ??= new SubjectNode();
+            node = node.one;
+            continue;
+        }
+        if (part?.includes('*') || part?.includes('>')) {
+            throw new RangeError('@zmdb/transport-nats: NATS wildcards must occupy a whole token');
+        }
+        let child = node.literals.get(part ?? '');
+        if (child === undefined) {
+            child = new SubjectNode();
+            node.literals.set(part ?? '', child);
+        }
+        node = child;
+    }
+    node.terminal = true;
+}
+/**
+ * Compile NATS `*`/`>` subscriptions into a trie. Matching walks subject
+ * tokens and active trie nodes; it never iterates the configured patterns.
+ */
+export function createNatsSubjectMatcher(patterns) {
+    const root = new SubjectNode();
+    for (const pattern of patterns) {
+        add(root, pattern);
+    }
+    return {
+        matches(subject) {
+            const parts = tokens(subject, 'a NATS subject');
+            let active = new Set([root]);
+            for (const part of parts) {
+                const next = new Set();
+                for (const node of active) {
+                    if (node.tail) {
+                        return true;
+                    }
+                    const literal = node.literals.get(part);
+                    if (literal !== undefined) {
+                        next.add(literal);
+                    }
+                    if (node.one !== undefined) {
+                        next.add(node.one);
+                    }
+                }
+                active = next;
+                if (active.size === 0) {
+                    return false;
+                }
+            }
+            for (const node of active) {
+                if (node.terminal) {
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}
+//# sourceMappingURL=matcher.js.map

package/dist/matcher.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@zmdb/transport-nats",
+  "version": "1.0.0-beta.1",
+  "description": "Core NATS transport strategy for the public messaging contract owned by the zmdb application kernel.",
+  "keywords": [
+    "messaging",
+    "nats",
+    "request-reply",
+    "transport",
+    "typescript",
+    "zmdb"
+  ],
+  "homepage": "https://github.com/ambasta/zmdb#readme",
+  "bugs": {
+    "url": "https://github.com/ambasta/zmdb/issues"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "zmdb contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasta/zmdb.git",
+    "directory": "packages/transport-nats"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@nats-io/transport-node": "^3.4.0",
+    "@zmdb/app": "1.0.0-beta.1"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}