https://github.com/btravers/amqp-contract
Type-safe contracts for AMQP/RabbitMQ messaging with TypeScript
https://github.com/btravers/amqp-contract
amqp amqplib arktype asyncapi contract messaging nestjs nodejs rabbitmq schema standard-schema typescript valibot validation zod
Last synced: 27 days ago
JSON representation
Type-safe contracts for AMQP/RabbitMQ messaging with TypeScript
- Host: GitHub
- URL: https://github.com/btravers/amqp-contract
- Owner: btravers
- License: mit
- Created: 2025-12-11T22:32:32.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-01-19T20:51:27.000Z (2 months ago)
- Last Synced: 2026-01-19T21:42:12.627Z (2 months ago)
- Topics: amqp, amqplib, arktype, asyncapi, contract, messaging, nestjs, nodejs, rabbitmq, schema, standard-schema, typescript, valibot, validation, zod
- Language: TypeScript
- Homepage: https://btravers.github.io/amqp-contract/
- Size: 1.4 MB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# amqp-contract
**Type-safe contracts for [AMQP](https://www.amqp.org/)/[RabbitMQ](https://www.rabbitmq.com/) messaging with [TypeScript](https://www.typescriptlang.org/)**
[](https://github.com/btravers/amqp-contract/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@amqp-contract/contract)
[](https://www.npmjs.com/package/@amqp-contract/contract)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[**Documentation**](https://btravers.github.io/amqp-contract) · [**Get Started**](https://btravers.github.io/amqp-contract/guide/getting-started) · [**Examples**](https://btravers.github.io/amqp-contract/examples/)
## Why amqp-contract?
Define your AMQP contracts once — get **type safety**, **autocompletion**, and **runtime validation** everywhere.
- 🔒 **End-to-end type safety** — TypeScript knows your message shapes
- 🔄 **Reliable retry** — Built-in exponential backoff with Dead Letter Queue support
- 📄 **AsyncAPI compatible** — Generate documentation from your contracts
## Quick Example
```typescript
import {
defineContract,
defineEventConsumer,
defineEventPublisher,
defineExchange,
defineMessage,
defineQueue,
} from "@amqp-contract/contract";
import { TypedAmqpClient } from "@amqp-contract/client";
import { TypedAmqpWorker } from "@amqp-contract/worker";
import { Future, Result } from "@swan-io/boxed";
import { z } from "zod";
// 1. Define resources with Dead Letter Exchange and retry configuration
const ordersExchange = defineExchange("orders", "topic", { durable: true });
const ordersDlx = defineExchange("orders-dlx", "topic", { durable: true });
const orderProcessingQueue = defineQueue("order-processing", {
deadLetter: { exchange: ordersDlx, routingKey: "order.failed" },
retry: { mode: "ttl-backoff", maxRetries: 3, initialDelayMs: 1000 }, // Retry configured at queue level
});
// 2. Define message with schema validation
const orderMessage = defineMessage(
z.object({
orderId: z.string(),
amount: z.number(),
}),
);
// 3. Event pattern: publisher broadcasts, consumers subscribe
const orderCreatedEvent = defineEventPublisher(ordersExchange, orderMessage, {
routingKey: "order.created",
});
// 4. Define contract - only publishers and consumers needed
// Exchanges, queues, and bindings are automatically extracted
const contract = defineContract({
publishers: {
orderCreated: orderCreatedEvent,
},
consumers: {
processOrder: defineEventConsumer(orderCreatedEvent, orderProcessingQueue),
},
});
// 6. Type-safe publishing with validation
const client = await TypedAmqpClient.create({
contract,
urls: ["amqp://localhost"],
}).resultToPromise();
await client.publish("orderCreated", {
orderId: "ORD-123", // ✅ TypeScript knows!
amount: 99.99,
});
// 7. Type-safe consuming with automatic retry (configured at queue level)
const worker = await TypedAmqpWorker.create({
contract,
handlers: {
processOrder: ({ payload }) => {
console.log(payload.orderId); // ✅ TypeScript knows!
return Future.value(Result.Ok(undefined));
},
},
urls: ["amqp://localhost"],
}).resultToPromise();
```
## Installation
```bash
pnpm add @amqp-contract/contract @amqp-contract/client @amqp-contract/worker
```
## Documentation
📖 **[Full Documentation →](https://btravers.github.io/amqp-contract)**
- [Get Started](https://btravers.github.io/amqp-contract/guide/getting-started) — Get running in 5 minutes
- [Core Concepts](https://btravers.github.io/amqp-contract/guide/core-concepts) — Understand the fundamentals
- [Examples](https://btravers.github.io/amqp-contract/examples/) — Real-world usage patterns
## Packages
| Package | Description |
| ---------------------------------------------- | ------------------------------------- |
| [@amqp-contract/contract](./packages/contract) | Contract builder and type definitions |
| [@amqp-contract/client](./packages/client) | Type-safe client for publishing |
| [@amqp-contract/worker](./packages/worker) | Type-safe worker with retry support |
| [@amqp-contract/asyncapi](./packages/asyncapi) | AsyncAPI 3.0 generator |
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
MIT