@amqp-contract/contract 0.20.0 → 0.22.0

package/README.md

@@ -26,6 +26,7 @@ For robust contract definitions with guaranteed consistency, use Event or Comman
 | ----------- | ------------------------------------------ | -------------------------------------------------- |
 | **Event**   | One publisher, many consumers (broadcast)  | `defineEventPublisher` → `defineEventConsumer`     |
 | **Command** | Many publishers, one consumer (task queue) | `defineCommandConsumer` → `defineCommandPublisher` |
+| **RPC**     | Request / response with typed reply        | `defineRpc` (single bidirectional definition)      |
 
 ```typescript
 import {
@@ -41,7 +42,7 @@ import {
 import { z } from "zod";
 
 // Event pattern: publisher broadcasts, consumers subscribe
-const ordersExchange = defineExchange("orders", "topic", { durable: true });
+const ordersExchange = defineExchange("orders");
 const orderMessage = defineMessage(
   z.object({
     orderId: z.string(),
@@ -55,8 +56,8 @@ const orderCreatedEvent = defineEventPublisher(ordersExchange, orderMessage, {
 });
 
 // Multiple queues can consume the same event
-const orderQueue = defineQueue("order-processing", { durable: true });
-const analyticsQueue = defineQueue("analytics", { durable: true });
+const orderQueue = defineQueue("order-processing");
+const analyticsQueue = defineQueue("analytics");
 
 // Compose contract - exchanges, queues, bindings auto-extracted
 const contract = defineContract({
@@ -75,12 +76,41 @@ const contract = defineContract({
 });
 ```
 
+### RPC Pattern
+
+Use `defineRpc` for typed request/response calls. RPC is bidirectional on both
+ends — the worker handler consumes the request and produces a typed response;
+the client awaits it via `client.call(name, request, { timeoutMs })`. Both
+ends share the same definition, and RPCs live in their own `rpcs` slot of the
+contract (not `publishers` or `consumers`). RabbitMQ direct reply-to is used
+under the hood, so no reply queue declaration is needed.
+
+```typescript
+import { defineContract, defineMessage, defineQueue, defineRpc } from "@amqp-contract/contract";
+import { z } from "zod";
+
+const calculate = defineRpc(defineQueue("rpc.calculate"), {
+  request: defineMessage(z.object({ a: z.number(), b: z.number() })),
+  response: defineMessage(z.object({ sum: z.number() })),
+});
+
+const contract = defineContract({
+  rpcs: { calculate },
+});
+
+// Server handler returns the response value, not void:
+//   handlers: { calculate: ({ payload }) => Future.value(Result.Ok({ sum: payload.a + payload.b })) }
+//
+// Client invokes with a required timeout:
+//   const result = await client.call("calculate", { a: 1, b: 2 }, { timeoutMs: 5_000 }).toPromise();
+```
+
 **Benefits:**
 
 - ✅ Guaranteed message schema consistency between publishers and consumers
 - ✅ Routing key validation and type safety
 - ✅ Full type safety with TypeScript inference
-- ✅ Event-oriented and command-oriented patterns
+- ✅ Event, command, and RPC patterns
 - ✅ Flexible routing key patterns for topic exchanges
 
 ## Documentation