@nats-kit/rpc 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @nats-kit/rpc
+
+## 0.3.0
+
+### Minor Changes
+
+- Add `@nats-kit/rpc`: typed request/reply RPC over NATS, built on
+  `@nats-io/services` (ADR-32) with a reconnect supervisor, zod contracts,
+  and error normalisation per the new `docs/spec/nats-kit-wire-spec.md`.
+
+  `@nats-kit/nestjs` adds `RpcService` (server-side handler discovery via
+  `@RpcController` / `@RpcHandler`), `RpcClientModule.forFeature` +
+  `@InjectRpcClient`, `NatsService.registerBeforeStop` for graceful RPC
+  drain on shutdown, and re-exports the full `@nats-kit/rpc` surface.
+
+  `@nats-kit/core`'s `NatsTelemetry` seam gains optional `onRpcRequest` /
+  `onRpcResponse` / `onRpcHandled` / `onRpcServiceStarted` /
+  `onRpcServiceStopped` hooks — purely additive, no behavior change for
+  existing consumers.
+
+### Patch Changes
+
+- Updated dependencies
+  - @nats-kit/core@0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anatoly Tarnavsky
+
+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,94 @@
+# `@nats-kit/rpc`
+
+Typed request/reply RPC over NATS: zod contracts, an ADR-32
+[`@nats-io/services`](https://www.npmjs.com/package/@nats-io/services)
+server/client, and a reconnect supervisor. Built on
+[`@nats-kit/core`](https://www.npmjs.com/package/@nats-kit/core)'s
+`NatsConnectionLike` seam, so it works with the bare
+`NatsConnectionRunner` or the [`@nats-kit/nestjs`](https://www.npmjs.com/package/@nats-kit/nestjs)
+adapter's `NatsService`.
+
+The full wire spec this package implements lives at
+[`docs/spec/nats-kit-wire-spec.md`](../../docs/spec/nats-kit-wire-spec.md) —
+implementable from that document alone, in any language.
+
+## Install
+
+```bash
+npm install @nats-kit/rpc
+```
+
+(`@nats-kit/core` and `zod` are regular dependencies of `@nats-kit/rpc`, so
+npm installs them automatically.)
+
+## Quickstart
+
+```typescript
+import { z } from "zod";
+import { defineService, method, createRpcClient, createRpcServer, ok, fail } from "@nats-kit/rpc";
+
+export const SandboxContract = defineService({
+  app: "anki",
+  service: "sandbox",
+  version: "1.0.0",
+  methods: {
+    "get-session": method({
+      input: z.object({ sessionId: z.uuid() }),
+      output: z.object({ cards: z.array(z.string()) }),
+      errors: ["NOT_FOUND"],
+      timeoutMs: 5_000,
+    }),
+  },
+});
+
+// Server
+const server = createRpcServer(SandboxContract, {
+  nats: runner, // a NatsConnectionRunner or NestJS NatsService
+  signal: abortController.signal,
+  handlers: {
+    "get-session": async (input, ctx) => {
+      const session = await repo.find(input.sessionId, ctx.caller.id);
+      return session ? ok({ cards: session.cards }) : fail("NOT_FOUND", "no such session");
+    },
+  },
+});
+
+// Client
+const client = createRpcClient(SandboxContract, { nats: runner });
+const { cards } = await client["get-session"]({ sessionId: "..." });
+```
+
+The client resolves with the parsed `output` on success and rejects with
+`RpcError` in every other case (`isRpcError`, `isDomainError`,
+`isTransportError` narrow it). See the wire spec for the exact header set,
+error taxonomy, and dispatch order.
+
+## ESLint boundary rules
+
+```js
+// eslint.config.js
+import { rpcBoundaryRules } from "@nats-kit/rpc/eslint";
+export default [{ files: ["src/**/*.ts"], rules: { ...rpcBoundaryRules } }];
+```
+
+A lint-level nudge (not a guarantee) against bypassing the RPC layer with raw
+`nc.request()` / `msg.respond()` / `msg.respondError()`.
+
+## Known deviations from the design doc
+
+- **`nats micro stats` `num_errors` does not increment for this package's
+  service errors.** ADR-32's own error counting (`@nats-io/services` and the
+  Go `micro` package alike) only fires when an endpoint handler throws
+  *synchronously*; this package's handler is `async` so it can build a
+  wire-accurate `{ok:false,...}` / ADR-32 response with a JSON `details`
+  body, and an async rejection never reaches that synchronous catch. This is
+  intentional (kept, not fixed) — every response this server sends is still
+  wire-correct (right status code, right headers, right body); only the
+  built-in `nats micro stats` counter under-reports. Don't rely on
+  `num_errors` for this service's error rate — use `onRpcHandled`/telemetry
+  instead.
+- **A handler throw never puts the real error message on the wire.** The 500
+  response always carries the generic `Nats-Service-Error: internal error`;
+  the actual error is logged server-side (via the configured `logger`, with
+  `requestId` + `subject`) instead. This avoids leaking server-internal
+  detail (stack traces, DB errors, etc.) to the caller.

package/dist/commonjs/client.d.ts

@@ -0,0 +1,9 @@
+import { type ServiceContract } from "./contract.js";
+import { type RpcClient, type RpcClientOptions } from "./types.js";
+/**
+ * Build a typed `RpcClient<C>` — one method per contract entry, request
+ * headers per §4.2, and error normalisation per §4.6. Rejects with
+ * {@link RpcError} in every non-success case; never leaks `{ok:false}`.
+ */
+export declare function createRpcClient<C extends ServiceContract>(contract: C, options: RpcClientOptions): RpcClient<C>;
+//# sourceMappingURL=client.d.ts.map

package/dist/commonjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,eAAe,CAAC;AAmBpE,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAsUpB;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,eAAe,EACvD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,gBAAgB,GACxB,SAAS,CAAC,CAAC,CAAC,CAMd"}

package/dist/commonjs/client.js

@@ -0,0 +1,307 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRpcClient = createRpcClient;
+const nuid_1 = require("@nats-io/nuid");
+const nats_core_1 = require("@nats-io/nats-core");
+const core_1 = require("@nats-kit/core");
+const contract_js_1 = require("./contract.js");
+const errors_js_1 = require("./errors.js");
+const headers_js_1 = require("./headers.js");
+const DEFAULT_TIMEOUT_MS = 10_000;
+const RESERVED_HEADER_NAMES = new Set([
+    headers_js_1.HEADER_REQUEST_ID,
+    headers_js_1.HEADER_CALLER_KIND,
+    headers_js_1.HEADER_CALLER_ID,
+    headers_js_1.HEADER_CALLER_ROLE,
+    headers_js_1.HEADER_DEADLINE,
+    headers_js_1.HEADER_CONTENT_TYPE,
+    headers_js_1.HEADER_TRACEPARENT,
+    headers_js_1.HEADER_TRACESTATE,
+].map((name) => name.toLowerCase()));
+function assertAllowedExtraHeaders(extra) {
+    if (!extra)
+        return;
+    for (const name of Object.keys(extra)) {
+        if (name.toLowerCase().startsWith("nats-")) {
+            throw new Error(`createRpcClient: cannot set a "Nats-*" header ("${name}")`);
+        }
+        if (RESERVED_HEADER_NAMES.has(name.toLowerCase())) {
+            throw new Error(`createRpcClient: "${name}" is set by the client, not overridable`);
+        }
+    }
+}
+/**
+ * Parse a JSON response body, tolerating an empty buffer (§4.5: service
+ * errors MAY have no body at all — uncaught handler throws emit one).
+ */
+function tryParseJson(data) {
+    if (data.length === 0)
+        return { ok: false };
+    try {
+        return { ok: true, value: JSON.parse(new TextDecoder().decode(data)) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/** Build the `createRpcClient` implementation for a single contract method. */
+function buildMethodCaller(contract, methodName, options) {
+    const methodDef = contract.methods[methodName];
+    if (!methodDef) {
+        throw new Error(`createRpcClient: unknown method "${methodName}"`);
+    }
+    const subject = (0, contract_js_1.methodSubject)(contract, methodName);
+    const validateResponses = options.validateResponses ?? true;
+    const logger = options.logger;
+    const telemetry = options.telemetry ?? core_1.noopTelemetry;
+    return async (input, callOpts = {}) => {
+        assertAllowedExtraHeaders(callOpts.headers);
+        const requestId = callOpts.requestId ?? nuid_1.nuid.next();
+        const start = Date.now();
+        let outcome = "ok";
+        try {
+            telemetry.onRpcRequest?.(subject, requestId);
+            const parsedInputResult = methodDef.input.safeParse(input);
+            if (!parsedInputResult.success) {
+                outcome = "service-error";
+                throw new errors_js_1.RpcError({
+                    kind: "service",
+                    code: errors_js_1.SERVICE_ERROR_CODES.BAD_REQUEST,
+                    message: "input failed local schema validation",
+                    details: parsedInputResult.error.issues,
+                    subject,
+                    requestId,
+                });
+            }
+            const parsedInput = parsedInputResult.data;
+            const caller = callOpts.caller ?? options.caller ?? { kind: "service" };
+            const timeoutMs = callOpts.timeoutMs ?? methodDef.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const deadlineMs = callOpts.deadlineMs ?? Date.now() + timeoutMs;
+            const reqHeaders = (0, headers_js_1.buildRequestHeaders)({
+                requestId,
+                caller,
+                deadlineMs,
+                traceparent: callOpts.traceparent,
+                extra: callOpts.headers,
+            });
+            const body = new TextEncoder().encode(JSON.stringify(parsedInput));
+            await options.nats.waitForReady();
+            const nc = options.nats.getConnection();
+            let reply;
+            try {
+                const requestPromise = nc.request(subject, body, {
+                    timeout: timeoutMs,
+                    headers: reqHeaders,
+                });
+                reply = callOpts.signal
+                    ? await raceWithSignal(requestPromise, callOpts.signal)
+                    : await requestPromise;
+            }
+            catch (error) {
+                throw toTransportError(error, subject, requestId);
+            }
+            const svcErrorCode = reply.headers?.get("Nats-Service-Error-Code", nats_core_1.Match.IgnoreCase);
+            if (svcErrorCode) {
+                outcome = "service-error";
+                const status = Number(svcErrorCode);
+                const description = reply.headers?.get("Nats-Service-Error", nats_core_1.Match.IgnoreCase) || "service error";
+                const parsedBody = tryParseJson(reply.data);
+                const details = parsedBody.ok && typeof parsedBody.value === "object" && parsedBody.value !== null
+                    ? parsedBody.value.details
+                    : undefined;
+                throw new errors_js_1.RpcError({
+                    kind: "service",
+                    code: errors_js_1.SERVICE_CODE_BY_STATUS[status] ?? errors_js_1.SERVICE_ERROR_CODES.SERVICE_ERROR,
+                    message: description,
+                    serviceCode: status,
+                    details,
+                    subject,
+                    requestId,
+                });
+            }
+            const parsedBody = tryParseJson(reply.data);
+            if (!parsedBody.ok || typeof parsedBody.value !== "object" || parsedBody.value === null) {
+                outcome = "service-error";
+                throw new errors_js_1.RpcError({
+                    kind: "service",
+                    code: errors_js_1.SERVICE_ERROR_CODES.MALFORMED_REPLY,
+                    message: "reply body was not valid JSON",
+                    subject,
+                    requestId,
+                });
+            }
+            const envelope = parsedBody.value;
+            if (envelope.ok === false) {
+                outcome = "domain-error";
+                throw new errors_js_1.RpcError({
+                    kind: "domain",
+                    code: envelope.error?.code ?? "UNKNOWN",
+                    message: envelope.error?.message ?? "domain error",
+                    details: envelope.error?.details,
+                    subject,
+                    requestId,
+                });
+            }
+            if (envelope.ok !== true) {
+                outcome = "service-error";
+                throw new errors_js_1.RpcError({
+                    kind: "service",
+                    code: errors_js_1.SERVICE_ERROR_CODES.MALFORMED_REPLY,
+                    message: 'reply body missing "ok"',
+                    subject,
+                    requestId,
+                });
+            }
+            if (!validateResponses) {
+                return envelope.result;
+            }
+            // Wire spec §4.3: a method with no output sends `"result": null` on
+            // the wire, but `z.void()`/`z.undefined()` only accept `undefined` —
+            // retry with `undefined` before treating a `null` result as malformed.
+            let parsedOutput = methodDef.output.safeParse(envelope.result);
+            if (!parsedOutput.success && envelope.result === null) {
+                parsedOutput = methodDef.output.safeParse(undefined);
+            }
+            if (!parsedOutput.success) {
+                outcome = "service-error";
+                throw new errors_js_1.RpcError({
+                    kind: "service",
+                    code: errors_js_1.SERVICE_ERROR_CODES.MALFORMED_REPLY,
+                    message: "reply result failed output schema validation",
+                    details: parsedOutput.error.issues,
+                    subject,
+                    requestId,
+                });
+            }
+            return parsedOutput.data;
+        }
+        catch (error) {
+            // Transport errors (timeout, no-responders, connection-lost, aborted)
+            // never flow through the `outcome = "..."` assignments above — derive
+            // it here from the normalised `RpcError` before it's telemetered.
+            if (outcome === "ok" && (0, errors_js_1.isRpcError)(error)) {
+                if (error.kind === "transport") {
+                    outcome =
+                        error.code === errors_js_1.TRANSPORT_ERROR_CODES.TIMEOUT
+                            ? "timeout"
+                            : error.code === errors_js_1.TRANSPORT_ERROR_CODES.NO_RESPONDERS
+                                ? "no-responders"
+                                : error.code === errors_js_1.TRANSPORT_ERROR_CODES.ABORTED
+                                    ? "aborted"
+                                    : error.code === errors_js_1.TRANSPORT_ERROR_CODES.CONNECTION_LOST
+                                        ? "connection-lost"
+                                        : "service-error";
+                }
+                else if (error.kind === "domain") {
+                    outcome = "domain-error";
+                }
+                else {
+                    outcome = "service-error";
+                }
+            }
+            throw error;
+        }
+        finally {
+            logger?.debug?.({ subject, requestId, outcome, durationMs: Date.now() - start }, "RPC call completed");
+            telemetry.onRpcResponse?.(subject, outcome, Date.now() - start);
+        }
+    };
+}
+function toTransportError(error, subject, requestId) {
+    // `raceWithSignal` already builds a fully-formed `RpcError` (kind:
+    // "transport", code: ABORTED) when the caller's signal fires — pass it
+    // through unchanged instead of reclassifying it as CONNECTION_LOST.
+    if ((0, errors_js_1.isRpcError)(error))
+        return error;
+    if (error instanceof core_1.RequestError) {
+        if (error.isNoResponders() || error.cause instanceof core_1.NoRespondersError) {
+            return new errors_js_1.RpcError({
+                kind: "transport",
+                code: errors_js_1.TRANSPORT_ERROR_CODES.NO_RESPONDERS,
+                message: "no responders for subject",
+                subject,
+                requestId,
+                cause: error,
+            });
+        }
+        if (error.cause instanceof core_1.TimeoutError) {
+            return new errors_js_1.RpcError({
+                kind: "transport",
+                code: errors_js_1.TRANSPORT_ERROR_CODES.TIMEOUT,
+                message: "request timed out",
+                subject,
+                requestId,
+                cause: error,
+            });
+        }
+    }
+    if (error instanceof core_1.TimeoutError) {
+        return new errors_js_1.RpcError({
+            kind: "transport",
+            code: errors_js_1.TRANSPORT_ERROR_CODES.TIMEOUT,
+            message: "request timed out",
+            subject,
+            requestId,
+            cause: error,
+        });
+    }
+    if (error instanceof core_1.NoRespondersError) {
+        return new errors_js_1.RpcError({
+            kind: "transport",
+            code: errors_js_1.TRANSPORT_ERROR_CODES.NO_RESPONDERS,
+            message: "no responders for subject",
+            subject,
+            requestId,
+            cause: error,
+        });
+    }
+    if (error instanceof core_1.ClosedConnectionError || error instanceof core_1.ConnectionError) {
+        return new errors_js_1.RpcError({
+            kind: "transport",
+            code: errors_js_1.TRANSPORT_ERROR_CODES.CONNECTION_LOST,
+            message: "connection closed or lost",
+            subject,
+            requestId,
+            cause: error,
+        });
+    }
+    return new errors_js_1.RpcError({
+        kind: "transport",
+        code: errors_js_1.TRANSPORT_ERROR_CODES.CONNECTION_LOST,
+        message: error instanceof Error ? error.message : "request failed",
+        subject,
+        requestId,
+        cause: error,
+    });
+}
+function raceWithSignal(promise, signal) {
+    if (signal.aborted) {
+        return Promise.reject(new errors_js_1.RpcError({ kind: "transport", code: errors_js_1.TRANSPORT_ERROR_CODES.ABORTED, message: "aborted" }));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(new errors_js_1.RpcError({ kind: "transport", code: errors_js_1.TRANSPORT_ERROR_CODES.ABORTED, message: "aborted" }));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * Build a typed `RpcClient<C>` — one method per contract entry, request
+ * headers per §4.2, and error normalisation per §4.6. Rejects with
+ * {@link RpcError} in every non-success case; never leaks `{ok:false}`.
+ */
+function createRpcClient(contract, options) {
+    const client = {};
+    for (const methodName of Object.keys(contract.methods)) {
+        client[methodName] = buildMethodCaller(contract, methodName, options);
+    }
+    return client;
+}
+//# sourceMappingURL=client.js.map

package/dist/commonjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":";;AA+WA,0CASC;AAxXD,wCAAqC;AACrC,kDAA2C;AAC3C,yCAQwB;AAExB,+CAAoE;AACpE,2CAMqB;AACrB,6CAUsB;AAQtB,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,qBAAqB,GAAG,IAAI,GAAG,CACnC;IACE,8BAAiB;IACjB,+BAAkB;IAClB,6BAAgB;IAChB,+BAAkB;IAClB,4BAAe;IACf,gCAAmB;IACnB,+BAAkB;IAClB,8BAAiB;CAClB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CACpC,CAAC;AAEF,SAAS,yBAAyB,CAAC,KAAyC;IAC1E,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,mDAAmD,IAAI,IAAI,CAAC,CAAC;QAC/E,CAAC;QACD,IAAI,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,yCAAyC,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,IAAgB;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,SAAS,iBAAiB,CACxB,QAAW,EACX,UAAkB,EAClB,OAAyB;IAEzB,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oCAAoC,UAAU,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,OAAO,GAAG,IAAA,2BAAa,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACpD,MAAM,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,IAAI,CAAC;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,oBAAa,CAAC;IAErD,OAAO,KAAK,EAAE,KAAc,EAAE,WAA2B,EAAE,EAAoB,EAAE;QAC/E,yBAAyB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAE5C,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,WAAI,CAAC,IAAI,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,OAAO,GAOa,IAAI,CAAC;QAE7B,IAAI,CAAC;YACH,SAAS,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAE7C,MAAM,iBAAiB,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC3D,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;gBAC/B,OAAO,GAAG,eAAe,CAAC;gBAC1B,MAAM,IAAI,oBAAQ,CAAC;oBACjB,IAAI,EAAE,SAAS;oBACf,IAAI,EAAE,+BAAmB,CAAC,WAAW;oBACrC,OAAO,EAAE,sCAAsC;oBAC/C,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,MAAM;oBACvC,OAAO;oBACP,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YACD,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,CAAC;YAC3C,MAAM,MAAM,GAAc,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YACnF,MAAM,SAAS,GACb,QAAQ,CAAC,SAAS,IAAI,SAAS,CAAC,SAAS,IAAI,OAAO,CAAC,gBAAgB,IAAI,kBAAkB,CAAC;YAC9F,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAEjE,MAAM,UAAU,GAAY,IAAA,gCAAmB,EAAC;gBAC9C,SAAS;gBACT,MAAM;gBACN,UAAU;gBACV,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,KAAK,EAAE,QAAQ,CAAC,OAAO;aACxB,CAAC,CAAC;YAEH,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;YAEnE,MAAM,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YAClC,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YAExC,IAAI,KAA8C,CAAC;YACnD,IAAI,CAAC;gBACH,MAAM,cAAc,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE;oBAC/C,OAAO,EAAE,SAAS;oBAClB,OAAO,EAAE,UAAU;iBACpB,CAAC,CAAC;gBACH,KAAK,GAAG,QAAQ,CAAC,MAAM;oBACrB,CAAC,CAAC,MAAM,cAAc,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC;oBACvD,CAAC,CAAC,MAAM,cAAc,CAAC;YAC3B,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YACpD,CAAC;YAED,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,yBAAyB,EAAE,iBAAK,CAAC,UAAU,CAAC,CAAC;YACrF,IAAI,YAAY,EAAE,CAAC;gBACjB,OAAO,GAAG,eAAe,CAAC;gBAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;gBACpC,MAAM,WAAW,GACf,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,oBAAoB,EAAE,iBAAK,CAAC,UAAU,CAAC,IAAI,eAAe,CAAC;gBAChF,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC5C,MAAM,OAAO,GACX,UAAU,CAAC,EAAE,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI;oBAChF,CAAC,CAAE,UAAU,CAAC,KAA+B,CAAC,OAAO;oBACrD,CAAC,CAAC,SAAS,CAAC;gBAChB,MAAM,IAAI,oBAAQ,CAAC;oBACjB,IAAI,EAAE,SAAS;oBACf,IAAI,EAAE,kCAAsB,CAAC,MAAM,CAAC,IAAI,+BAAmB,CAAC,aAAa;oBACzE,OAAO,EAAE,WAAW;oBACpB,WAAW,EAAE,MAAM;oBACnB,OAAO;oBACP,OAAO;oBACP,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;gBACxF,OAAO,GAAG,eAAe,CAAC;gBAC1B,MAAM,IAAI,oBAAQ,CAAC;oBACjB,IAAI,EAAE,SAAS;oBACf,IAAI,EAAE,+BAAmB,CAAC,eAAe;oBACzC,OAAO,EAAE,+BAA+B;oBACxC,OAAO;oBACP,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,MAAM,QAAQ,GAAG,UAAU,CAAC,KAI3B,CAAC;YAEF,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;gBAC1B,OAAO,GAAG,cAAc,CAAC;gBACzB,MAAM,IAAI,oBAAQ,CAAC;oBACjB,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,IAAI,SAAS;oBACvC,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,IAAI,cAAc;oBAClD,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,OAAO;oBAChC,OAAO;oBACP,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,IAAI,QAAQ,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;gBACzB,OAAO,GAAG,eAAe,CAAC;gBAC1B,MAAM,IAAI,oBAAQ,CAAC;oBACjB,IAAI,EAAE,SAAS;oBACf,IAAI,EAAE,+BAAmB,CAAC,eAAe;oBACzC,OAAO,EAAE,yBAAyB;oBAClC,OAAO;oBACP,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBACvB,OAAO,QAAQ,CAAC,MAAM,CAAC;YACzB,CAAC;YAED,oEAAoE;YACpE,qEAAqE;YACrE,uEAAuE;YACvE,IAAI,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/D,IAAI,CAAC,YAAY,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;gBACtD,YAAY,GAAG,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YACvD,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;gBAC1B,OAAO,GAAG,eAAe,CAAC;gBAC1B,MAAM,IAAI,oBAAQ,CAAC;oBACjB,IAAI,EAAE,SAAS;oBACf,IAAI,EAAE,+BAAmB,CAAC,eAAe;oBACzC,OAAO,EAAE,8CAA8C;oBACvD,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM;oBAClC,OAAO;oBACP,SAAS;iBACV,CAAC,CAAC;YACL,CAAC;YAED,OAAO,YAAY,CAAC,IAAI,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,sEAAsE;YACtE,sEAAsE;YACtE,kEAAkE;YAClE,IAAI,OAAO,KAAK,IAAI,IAAI,IAAA,sBAAU,EAAC,KAAK,CAAC,EAAE,CAAC;gBAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;oBAC/B,OAAO;wBACL,KAAK,CAAC,IAAI,KAAK,iCAAqB,CAAC,OAAO;4BAC1C,CAAC,CAAC,SAAS;4BACX,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,iCAAqB,CAAC,aAAa;gCAClD,CAAC,CAAC,eAAe;gCACjB,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,iCAAqB,CAAC,OAAO;oCAC5C,CAAC,CAAC,SAAS;oCACX,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,iCAAqB,CAAC,eAAe;wCACpD,CAAC,CAAC,iBAAiB;wCACnB,CAAC,CAAC,eAAe,CAAC;gBAC9B,CAAC;qBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACnC,OAAO,GAAG,cAAc,CAAC;gBAC3B,CAAC;qBAAM,CAAC;oBACN,OAAO,GAAG,eAAe,CAAC;gBAC5B,CAAC;YACH,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,MAAM,EAAE,KAAK,EAAE,CACb,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,EAC/D,oBAAoB,CACrB,CAAC;YACF,SAAS,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;QAClE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc,EAAE,OAAe,EAAE,SAAiB;IAC1E,mEAAmE;IACnE,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,IAAA,sBAAU,EAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,KAAK,YAAY,mBAAY,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,cAAc,EAAE,IAAI,KAAK,CAAC,KAAK,YAAY,wBAAiB,EAAE,CAAC;YACvE,OAAO,IAAI,oBAAQ,CAAC;gBAClB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,iCAAqB,CAAC,aAAa;gBACzC,OAAO,EAAE,2BAA2B;gBACpC,OAAO;gBACP,SAAS;gBACT,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,YAAY,mBAAY,EAAE,CAAC;YACxC,OAAO,IAAI,oBAAQ,CAAC;gBAClB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,iCAAqB,CAAC,OAAO;gBACnC,OAAO,EAAE,mBAAmB;gBAC5B,OAAO;gBACP,SAAS;gBACT,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,IAAI,KAAK,YAAY,mBAAY,EAAE,CAAC;QAClC,OAAO,IAAI,oBAAQ,CAAC;YAClB,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,iCAAqB,CAAC,OAAO;YACnC,OAAO,EAAE,mBAAmB;YAC5B,OAAO;YACP,SAAS;YACT,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,YAAY,wBAAiB,EAAE,CAAC;QACvC,OAAO,IAAI,oBAAQ,CAAC;YAClB,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,iCAAqB,CAAC,aAAa;YACzC,OAAO,EAAE,2BAA2B;YACpC,OAAO;YACP,SAAS;YACT,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,YAAY,4BAAqB,IAAI,KAAK,YAAY,sBAAe,EAAE,CAAC;QAC/E,OAAO,IAAI,oBAAQ,CAAC;YAClB,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,iCAAqB,CAAC,eAAe;YAC3C,OAAO,EAAE,2BAA2B;YACpC,OAAO;YACP,SAAS;YACT,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,oBAAQ,CAAC;QAClB,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,iCAAqB,CAAC,eAAe;QAC3C,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB;QAClE,OAAO;QACP,SAAS;QACT,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CAAI,OAAmB,EAAE,MAAmB;IACjE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,oBAAQ,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,iCAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,MAAM,CAAC,IAAI,oBAAQ,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,iCAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QACvG,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAC7B,QAAW,EACX,OAAyB;IAEzB,MAAM,MAAM,GAAgF,EAAE,CAAC;IAC/F,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACvD,MAAM,CAAC,UAAU,CAAC,GAAG,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,MAAsB,CAAC;AAChC,CAAC"}

package/dist/commonjs/contract.d.ts

@@ -0,0 +1,59 @@
+import { type z } from "zod";
+/** Segment grammar shared by `app`, `service` and every method name (§4.1). */
+export declare const SUBJECT_SEGMENT_RE: RegExp;
+/**
+ * Definition of a single RPC method within a {@link ServiceContract}.
+ *
+ * See design §2.1. `errors` is a closed set of domain error codes the method
+ * may return via `fail()` — kept as a literal tuple by {@link method} so
+ * `RpcHandlers<C>` and `isDomainError` can narrow against it.
+ */
+export interface RpcMethodDef<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType, E extends readonly string[] = readonly string[]> {
+    input: I;
+    output: O;
+    /** Closed set of domain error codes this method may return. */
+    errors?: E;
+    /**
+     * Roles the caller must hold. Empty/absent means no role requirement.
+     * Enforced by the library BEFORE dispatch: a caller missing any of these
+     * gets a 403 service error and the handler is never invoked.
+     */
+    requiredRoles?: readonly string[];
+    /** Default client timeout for this method. Falls back to 10_000. */
+    timeoutMs?: number;
+    /** Free-form endpoint metadata; surfaces in `nats micro info`. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Identity helper that preserves the literal tuple type of `errors` — a bare
+ * object literal would widen `errors: ["NOT_FOUND"]` to `string[]`, which
+ * would flatten every domain error union to `string` throughout the contract.
+ */
+export declare function method<I extends z.ZodType, O extends z.ZodType, const E extends readonly string[] = readonly []>(def: RpcMethodDef<I, O, E>): RpcMethodDef<I, O, E>;
+/** A named collection of RPC methods, addressed at `<app>.<service>.<method>` (§2.1, §4.1). */
+export interface ServiceContract<M extends Record<string, RpcMethodDef> = Record<string, RpcMethodDef>> {
+    /** Subject segment 1. `[a-z0-9-]+`. */
+    app: string;
+    /** Subject segment 2. `[a-z0-9-]+`. */
+    service: string;
+    /** SemVer — `@nats-io/services` rejects anything else (`parseSemVer`). */
+    version: string;
+    description?: string;
+    metadata?: Record<string, string>;
+    /** Keys are method names; each must be `[a-z0-9-]+`. */
+    methods: M;
+}
+/**
+ * Validate and return a {@link ServiceContract}. Throws synchronously on a
+ * malformed `app`/`service`/`version`/method name — a contract is authored
+ * once and imported everywhere, so failing fast at module-load time is
+ * preferable to a runtime surprise deep inside `createRpcServer`.
+ */
+export declare function defineService<const M extends Record<string, RpcMethodDef>>(def: ServiceContract<M>): ServiceContract<M>;
+/** The subject a method is served/called on: `<app>.<service>.<method>` (§4.1). */
+export declare function methodSubject(contract: ServiceContract, methodName: string): string;
+/** The micro service `name` (dots are rejected by `Svcm.add`, so `-` joins app/service). */
+export declare function serviceName(contract: ServiceContract): string;
+/** The group subject prefix every endpoint is registered under. */
+export declare function groupSubject(contract: ServiceContract): string;
+//# sourceMappingURL=contract.d.ts.map

package/dist/commonjs/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,QAAoC,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAC3B,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EAC/B,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EAC/B,CAAC,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE;IAE/C,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,EAAE,CAAC,CAAC;IACV,+DAA+D;IAC/D,MAAM,CAAC,EAAE,CAAC,CAAC;IACX;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,CAAC,SAAS,CAAC,CAAC,OAAO,EACnB,CAAC,SAAS,CAAC,CAAC,OAAO,EACnB,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,EAC/C,GAAG,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAEnD;AAED,+FAA+F;AAC/F,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAErE,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,wDAAwD;IACxD,OAAO,EAAE,CAAC,CAAC;CACZ;AAKD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACxE,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC,GACtB,eAAe,CAAC,CAAC,CAAC,CAgBpB;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE7D;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE9D"}

package/dist/commonjs/contract.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBJECT_SEGMENT_RE = void 0;
+exports.method = method;
+exports.defineService = defineService;
+exports.methodSubject = methodSubject;
+exports.serviceName = serviceName;
+exports.groupSubject = groupSubject;
+/** Segment grammar shared by `app`, `service` and every method name (§4.1). */
+exports.SUBJECT_SEGMENT_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Identity helper that preserves the literal tuple type of `errors` — a bare
+ * object literal would widen `errors: ["NOT_FOUND"]` to `string[]`, which
+ * would flatten every domain error union to `string` throughout the contract.
+ */
+function method(def) {
+    return def;
+}
+/** SemVer as required by `@nats-io/services`' `ServiceConfig.version` (`parseSemVer`). */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+/**
+ * Validate and return a {@link ServiceContract}. Throws synchronously on a
+ * malformed `app`/`service`/`version`/method name — a contract is authored
+ * once and imported everywhere, so failing fast at module-load time is
+ * preferable to a runtime surprise deep inside `createRpcServer`.
+ */
+function defineService(def) {
+    if (!exports.SUBJECT_SEGMENT_RE.test(def.app)) {
+        throw new Error(`defineService: invalid app segment "${def.app}"`);
+    }
+    if (!exports.SUBJECT_SEGMENT_RE.test(def.service)) {
+        throw new Error(`defineService: invalid service segment "${def.service}"`);
+    }
+    if (!SEMVER_RE.test(def.version)) {
+        throw new Error(`defineService: invalid semver version "${def.version}"`);
+    }
+    for (const name of Object.keys(def.methods)) {
+        if (!exports.SUBJECT_SEGMENT_RE.test(name)) {
+            throw new Error(`defineService: invalid method name "${name}"`);
+        }
+    }
+    return def;
+}
+/** The subject a method is served/called on: `<app>.<service>.<method>` (§4.1). */
+function methodSubject(contract, methodName) {
+    return `${contract.app}.${contract.service}.${methodName}`;
+}
+/** The micro service `name` (dots are rejected by `Svcm.add`, so `-` joins app/service). */
+function serviceName(contract) {
+    return `${contract.app}-${contract.service}`;
+}
+/** The group subject prefix every endpoint is registered under. */
+function groupSubject(contract) {
+    return `${contract.app}.${contract.service}`;
+}
+//# sourceMappingURL=contract.js.map

package/dist/commonjs/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/contract.ts"],"names":[],"mappings":";;;AAsCA,wBAMC;AA2BD,sCAkBC;AAGD,sCAEC;AAGD,kCAEC;AAGD,oCAEC;AAtGD,+EAA+E;AAClE,QAAA,kBAAkB,GAAG,iCAAiC,CAAC;AA8BpE;;;;GAIG;AACH,SAAgB,MAAM,CAIpB,GAA0B;IAC1B,OAAO,GAAG,CAAC;AACb,CAAC;AAkBD,0FAA0F;AAC1F,MAAM,SAAS,GAAG,0DAA0D,CAAC;AAE7E;;;;;GAKG;AACH,SAAgB,aAAa,CAC3B,GAAuB;IAEvB,IAAI,CAAC,0BAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,uCAAuC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,0BAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,2CAA2C,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,0CAA0C,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC,0BAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,uCAAuC,IAAI,GAAG,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mFAAmF;AACnF,SAAgB,aAAa,CAAC,QAAyB,EAAE,UAAkB;IACzE,OAAO,GAAG,QAAQ,CAAC,GAAG,IAAI,QAAQ,CAAC,OAAO,IAAI,UAAU,EAAE,CAAC;AAC7D,CAAC;AAED,4FAA4F;AAC5F,SAAgB,WAAW,CAAC,QAAyB;IACnD,OAAO,GAAG,QAAQ,CAAC,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED,mEAAmE;AACnE,SAAgB,YAAY,CAAC,QAAyB;IACpD,OAAO,GAAG,QAAQ,CAAC,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;AAC/C,CAAC"}