Share a message contract between services
A checkout service needs a shelf location from the catalog. Give both services the same contract so they agree on the subject, the request and the reply. The example uses a local sender first and then shows how to use the same client over NATS.
Define the lookup
Put the contract and its validators in a file or package both services import. This lookup accepts a copy ID and returns a shelf label. Both are nonempty strings encoded as JSON, including the quotation marks on the wire.
const nonemptyText = {
parse(value: unknown): string {
if (typeof value !== "string" || !value.trim()) throw new Error("Expected text");
return value.trim();
},
};
export const LocateCopy = contract({
topic: "books.locate",
request: nonemptyText,
reply: nonemptyText,
});A Standard Schema can describe different input and output types. For a parse-only validator, CHO infers both from the awaited result. For an event, omit reply and use client.publish. If you only need compile-time types, use contract<Request, Reply>({ topic }). Type parameters alone perform no runtime checks.
Implement the subscriber
@Middlewares(validate())
@Controller({ topic: "books" })
class Shelves {
private readonly shelves = new Map([["copy-17", "B2"]]);
@Subscribe(LocateCopy)
locate(copy: string): string {
const shelf = this.shelves.get(copy);
if (shelf === undefined) throw new ReplyError(404, "Unknown copy");
return shelf;
}
}
@Module({ controllers: [Shelves] })
class Library {}@Subscribe(LocateCopy) supplies the decoded request, followed by an optional delivery context. It already declares how to read the payload, so adding @Args to the same method is an error. validate() runs the request validator on the receiving route. A client checks the reply validator when it reads the answer.
Use the whole topic in the contract. The declaring feature and controller topics must match its leading segments. If the application uses a deployment prefix such as staging, put that prefix in the application's options and the client's options. Both then address staging.books.locate using the same contract.
Try both outcomes in memory
const app = await ChoMessage.create(Library);
try {
const client = new ChoMessageClient(localSender(app));
for (const copy of ["copy-17", "copy-99"]) {
try {
console.log(copy, await client.request(LocateCopy, copy));
} catch (error) {
if (!isReplyError(error, 404)) throw error;
console.log(copy, error.code, error.description);
}
}
} finally {
await app.close();
}Complete contracts.ts
import {
ChoMessage, ChoMessageClient, contract, Controller, isReplyError,
localSender, Middlewares, Module, ReplyError, Subscribe, validate,
} from "@chojs/message";
// #region contract
const nonemptyText = {
parse(value: unknown): string {
if (typeof value !== "string" || !value.trim()) throw new Error("Expected text");
return value.trim();
},
};
export const LocateCopy = contract({
topic: "books.locate",
request: nonemptyText,
reply: nonemptyText,
});
// #endregion contract
// #region service
@Middlewares(validate())
@Controller({ topic: "books" })
class Shelves {
private readonly shelves = new Map([["copy-17", "B2"]]);
@Subscribe(LocateCopy)
locate(copy: string): string {
const shelf = this.shelves.get(copy);
if (shelf === undefined) throw new ReplyError(404, "Unknown copy");
return shelf;
}
}
@Module({ controllers: [Shelves] })
class Library {}
// #endregion service
// #region caller
const app = await ChoMessage.create(Library);
try {
const client = new ChoMessageClient(localSender(app));
for (const copy of ["copy-17", "copy-99"]) {
try {
console.log(copy, await client.request(LocateCopy, copy));
} catch (error) {
if (!isReplyError(error, 404)) throw error;
console.log(copy, error.code, error.description);
}
}
} finally {
await app.close();
}
// #endregion callerSave the complete file as examples/contracts.ts in the development checkout. Run deno run examples/contracts.ts. Expect copy-17 B2 and copy-99 404 Unknown copy. The test goes through JSON encoding, validation, the handler and reply decoding. Local failures propagate directly from app.handle.
Send through a broker
Keep the linker you pass to ChoMessage.create. After await app.start(), use its sender in place of localSender(app). With a started NATS linker, the request becomes:
const client = new ChoMessageClient(linker.sender, { timeout: 2000 });
const shelf = await client.request(LocateCopy, "copy-17", {
headers: { "X-Branch": "central" },
});Supply prefix and a default request timeout on the client. Individual calls accept headers and key, and requests can override timeout in milliseconds. Kafka preserves a key and supports publish. Core NATS supports both publish and request and ignores keys. For a storage acknowledgment on NATS, use the JetStream publisher.
| What the requester observes | How to handle it |
|---|---|
| The service reports a domain failure | Match isReplyError(error, 404) or read its public code and description |
| No Core NATS subscriber or the request expires | Match CHO_MESSAGE_NO_RESPONDERS or CHO_MESSAGE_REQUEST_TIMEOUT with isChoError |
| The sender only supports publishing | request rejects with CHO_MESSAGE_NO_REPLIES |
| The answer is malformed JSON or the reply validator rejects it | Inspect CHO_MESSAGE_UNEXPECTED_REPLY and its cause |
An empty answer is decoded as undefined before the reply validator runs. For callers that need raw bytes or reply headers, use the native NATS request.
Move from an in-process client to NATS
Keep the contract and the subscriber unchanged. Replace the local sender with the started NATS linker's sender and set a request timeout. Compare a domain error returned by the service with a request sent when nobody is listening. A caller can handle these failures differently.
Use different types on the wire and in the handler
For an RPC that accepts a decimal ID, use a schema whose input is a string and whose output is a number. Both sides import the same contract. Here the reply also crosses the wire as a string.
import { z } from "zod";
import { contract, Controller, Middlewares, Subscribe, validate } from "@chojs/message";
const Decimal = z.string().regex(/^\d+$/).transform(Number);
export const NextId = contract({ topic: "catalog.next", request: Decimal, reply: Decimal });
@Middlewares(validate())
@Controller({ topic: "catalog" })
class Numbers {
@Subscribe(NextId)
next(id: number): string { return String(id + 1); }
}
// In the caller, using a connected client or a local sender:
// const next = await client.request(NextId, "41"); // number: 42The four contract parameters are Contract<Request, Reply, Sent, Returned>. Here they are number, number, string, string. The client serializes the sent value; the subscriber validates the decoded request. The handler returns the reply schema's input; the caller validates and transforms the decoded reply. A rejected reply value yields CHO_MESSAGE_UNEXPECTED_REPLY. An exception thrown inside Standard Schema's validation function propagates to the caller. For parse-only validators or an unspecified input type, contract inference uses the output as the wire type.