DEV Community: Benoit Travers

Building Type-Safe AMQP Messaging with amqp-contract

Benoit Travers — Thu, 25 Dec 2025 01:49:29 +0000

If you've worked with RabbitMQ or AMQP messaging in TypeScript, you've probably experienced the frustration of dealing with untyped messages, scattered validation logic, and the constant fear of runtime errors from mismatched data structures. What if there was a better way?

Today, I'm excited to introduce amqp-contract — a TypeScript library that brings the power of contract-first development, end-to-end type safety, and automatic validation to AMQP messaging.

The Problem with Traditional AMQP Development

Let's start with a typical scenario. You're building a microservices architecture using RabbitMQ for inter-service communication. Your publisher looks something like this:

// ❌ Traditional approach - no type safety
import amqp from 'amqplib';

const connection = await amqp.connect('amqp://localhost');
const channel = await connection.createChannel();

await channel.assertExchange('orders', 'topic', { durable: true });

// What fields should this have? What types?
channel.publish(
  'orders',
  'order.created',
  Buffer.from(JSON.stringify({
    orderId: 'ORD-123',
    amount: 99.99,
    // Did I forget any required fields?
  }))
);

And your consumer:

// ❌ No type information
channel.consume('order-processing', (msg) => {
  const data = JSON.parse(msg.content.toString()); // unknown type
  console.log(data.orderId); // No autocomplete, no validation
  // Is this the right field name? Who knows!
});

This approach has several critical issues:

No Type Safety: You lose all TypeScript benefits at the messaging boundary
Manual Validation: You need to manually validate every message, or risk runtime errors
Scattered Definitions: Message structures are defined implicitly or scattered across your codebase
Refactoring Nightmares: Change a field name? Good luck finding all the places it's used
Documentation Drift: Your code and documentation quickly get out of sync

Enter amqp-contract

amqp-contract solves these problems by bringing a contract-first approach to AMQP messaging. Inspired by the excellent tRPC, oRPC, and ts-rest libraries, it adapts their philosophy of end-to-end type safety to the world of message queues.

Here's what the same code looks like with amqp-contract:

1. Define Your Contract

First, define your contract with full type safety using schema validation libraries like Zod, Valibot, or ArkType:

import {
  defineContract,
  defineExchange,
  defineQueue,
  definePublisher,
  defineConsumer,
  defineMessage,
  defineQueueBinding,
} from '@amqp-contract/contract';
import { z } from 'zod';

// Define your AMQP resources
const ordersExchange = defineExchange('orders', 'topic', { durable: true });
const orderProcessingQueue = defineQueue('order-processing', { durable: true });

// Define your message schema
const orderMessage = defineMessage(
  z.object({
    orderId: z.string(),
    customerId: z.string(),
    items: z.array(
      z.object({
        productId: z.string(),
        quantity: z.number().int().positive(),
        price: z.number().positive(),
      })
    ),
    totalAmount: z.number().positive(),
    status: z.enum(['pending', 'processing', 'completed']),
  })
);

// Compose your contract
export const contract = defineContract({
  exchanges: { orders: ordersExchange },
  queues: { orderProcessing: orderProcessingQueue },
  bindings: {
    orderBinding: defineQueueBinding(
      orderProcessingQueue,
      ordersExchange,
      { routingKey: 'order.created' }
    ),
  },
  publishers: {
    orderCreated: definePublisher(ordersExchange, orderMessage, {
      routingKey: 'order.created',
    }),
  },
  consumers: {
    processOrder: defineConsumer(orderProcessingQueue, orderMessage),
  },
});

2. Type-Safe Publishing

Now use the contract to create a type-safe client:

import { TypedAmqpClient } from '@amqp-contract/client';
import { contract } from './contract';

const clientResult = await TypedAmqpClient.create({
  contract,
  urls: ['amqp://localhost'],
});

if (clientResult.isError()) {
  throw clientResult.error;
}

const client = clientResult.value;

// ✅ Fully typed! TypeScript knows exactly what fields are required
const result = await client.publish('orderCreated', {
  orderId: 'ORD-123',
  customerId: 'CUST-456',
  items: [
    { productId: 'PROD-789', quantity: 2, price: 49.99 }
  ],
  totalAmount: 99.98,
  status: 'pending',
});

result.match({
  Ok: () => console.log('✅ Published'),
  Error: (error) => console.error('❌ Failed:', error),
});

3. Type-Safe Consuming

And create a type-safe worker for consuming messages:

import { TypedAmqpWorker } from '@amqp-contract/worker';
import { contract } from './contract';

const workerResult = await TypedAmqpWorker.create({
  contract,
  handlers: {
    // ✅ message is fully typed based on your schema
    processOrder: async (message) => {
      console.log(`Processing order: ${message.orderId}`);
      console.log(`Customer: ${message.customerId}`);
      console.log(`Total: $${message.totalAmount}`);

      // ✅ Full autocomplete for all fields
      message.items.forEach((item) => {
        console.log(`- ${item.quantity}x Product ${item.productId}`);
      });
    },
  },
  urls: ['amqp://localhost'],
});

workerResult.match({
  Ok: (worker) => console.log('✅ Worker ready'),
  Error: (error) => { throw error; },
});

Key Features That Make amqp-contract Special

🔒 End-to-End Type Safety

TypeScript types flow automatically from your contract to publishers and consumers. No manual type annotations needed. If you refactor your schema, TypeScript immediately shows you every place that needs updating.

✅ Automatic Validation

Messages are automatically validated at network boundaries using Standard Schema v1. This works with Zod, Valibot, and ArkType, giving you the flexibility to choose your preferred validation library.

🛠️ Compile-Time Checks

TypeScript catches errors before runtime:

// ❌ TypeScript error - "orderDeleted" doesn't exist
await client.publish('orderDeleted', { orderId: '123' });

// ❌ TypeScript error - missing handler
await TypedAmqpWorker.create({
  contract,
  handlers: {}, // forgot processOrder!
  urls: ['amqp://localhost'],
});

📄 AsyncAPI 3.0 Generation

Automatically generate AsyncAPI specifications from your contracts:

import { AsyncAPIGenerator } from '@amqp-contract/asyncapi';
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4';

const generator = new AsyncAPIGenerator({
  schemaConverters: [new ZodToJsonSchemaConverter()],
});

const spec = await generator.generate(contract, {
  info: {
    title: 'Order Processing API',
    version: '1.0.0',
  },
  servers: {
    production: {
      host: 'rabbitmq.example.com:5672',
      protocol: 'amqp',
    },
  },
});

🎯 First-Class NestJS Support

If you're using NestJS, amqp-contract provides dedicated integration packages:

import { Module } from '@nestjs/common';
import { AmqpWorkerModule } from '@amqp-contract/worker-nestjs';
import { AmqpClientModule } from '@amqp-contract/client-nestjs';

@Module({
  imports: [
    AmqpWorkerModule.forRoot({
      contract,
      handlers: {
        processOrder: async (message) => {
          console.log('Processing:', message.orderId);
        },
      },
      connection: process.env.RABBITMQ_URL,
    }),
    AmqpClientModule.forRoot({
      contract,
      connection: process.env.RABBITMQ_URL,
    }),
  ],
})
export class AppModule {}

Why Choose amqp-contract?

Compared to Raw amqplib

✅ Type safety vs ❌ No types
✅ Automatic validation vs ❌ Manual validation
✅ Compile-time checks vs ❌ Runtime errors
✅ Refactoring support vs ❌ Find/replace
✅ Documentation from code vs ❌ Manual docs

Compared to Other Solutions

Unlike other AMQP libraries, amqp-contract:

Focuses on type safety first — types are derived from your contract
Uses Standard Schema v1 — compatible with multiple validation libraries
Generates AsyncAPI specs — automatic documentation
Provides explicit error handling — uses Result types
Is framework agnostic — works standalone or with NestJS

Getting Started

Installation

# Core packages
pnpm add @amqp-contract/contract @amqp-contract/client @amqp-contract/worker

# Choose your schema library
pnpm add zod  # or valibot, or arktype

# AMQP client
pnpm add amqplib @types/amqplib

Quick Start

Define your contract with schemas
Create a client to publish messages
Create a worker to consume messages
Enjoy type safety end-to-end!

Try It Today!

amqp-contract is open source (MIT license) and available on npm:

Check out the full documentation for detailed guides, API reference, and examples.

Conclusion

Type safety shouldn't stop at your application boundaries. With amqp-contract, you can bring the same level of type safety and developer experience you enjoy with TypeScript to your AMQP messaging layer.

Stop fighting runtime errors. Stop manually validating messages. Stop worrying about refactoring. Start building type-safe, validated, and maintainable messaging systems today.

What do you think? Have you tried amqp-contract? What are your experiences with type-safe messaging? Let me know in the comments!

Introducing temporal-contract: Type-Safe Temporal. io Workflows for TypeScript

Benoit Travers — Sun, 21 Dec 2025 20:46:05 +0000

If you've worked with Temporal.io for building durable workflows in TypeScript, you know how powerful it is for orchestrating complex business processes. However, maintaining type safety across workflows, activities, and clients can be challenging.

The Problem with Traditional Temporal Development

Temporal is an incredible platform for building reliable, fault-tolerant distributed systems. But the traditional TypeScript approach has some pain points:

// ❌ Traditional approach:  Manual type coordination
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';

const { processPayment, sendEmail } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

export async function orderWorkflow(orderId: string): Promise<void> {
  // What's the expected structure?  No validation!
  await processPayment(orderId);
  await sendEmail(orderId);
}

// Activities file - easy to drift from workflow expectations
export async function processPayment(orderId:  string): Promise<void> {
  // Implementation
}

Problems:

🚫 No runtime validation of inputs/outputs
🚫 Manual type coordination between files
🚫 Easy to drift when refactoring
🚫 No centralized contract definition
🚫 Complex error handling without Result types
🚫 Difficult to ensure consistency across teams

Introducing temporal-contract

temporal-contract solves these problems with a contract-first approach. You define your workflows, activities, and their schemas once using Zod, and type safety is guaranteed everywhere.

Key Features

✅ End-to-end type safety — Full TypeScript inference from contract to client, workflows, and activities

✅ Automatic validation — Zod schema validation at all network boundaries

✅ Compile-time checks — Catch errors before runtime

✅ Result/Future pattern — Explicit error handling for activities and child workflows with @swan-io/boxed

✅ Child workflows — Type-safe child workflow execution

✅ NestJS integration — First-class support for dependency injection

✅ Better DX — Full autocomplete, inline documentation, and refactoring support

How It Works

Step 1: Define Your Contract

First, define your Temporal contract with workflows and activities in one place:

import { defineContract } from '@temporal-contract/contract';
import { z } from 'zod';

// Define contract once with full type safety
export const orderContract = defineContract({
  taskQueue: 'orders',
  workflows: {
    processOrder: {
      input: z.object({
        orderId: z.string(),
        customerId: z. string(),
        items: z.array(
          z.object({
            productId: z.string(),
            quantity: z.number().int().positive(),
            price: z. number().positive(),
          })
        ),
      }),
      output: z.object({
        success: z.boolean(),
        orderId: z.string(),
        totalAmount: z.number(),
      }),
      activities: {
        validateInventory: {
          input: z.object({
            items: z.array(
              z.object({
                productId: z.string(),
                quantity: z.number(),
              })
            ),
          }),
          output: z.object({
            available: z.boolean(),
            unavailableItems: z.array(z.string()),
          }),
        },
        processPayment: {
          input: z.object({
            customerId: z.string(),
            amount: z.number().positive(),
          }),
          output: z. object({
            transactionId:  z.string(),
            status: z.enum(['success', 'failed', 'pending']),
          }),
        },
        sendConfirmationEmail: {
          input: z.object({
            customerId: z.string(),
            orderId: z.string(),
          }),
          output: z. object({
            sent: z. boolean(),
          }),
        },
      },
    },
  },
});

Step 2: Implement Type-Safe Activities

Activities use the declareActivitiesHandler function and return Future objects from @swan-io/boxed for explicit error handling:

import { declareActivitiesHandler, ActivityError } from '@temporal-contract/worker/activity';
import { orderContract } from './contract';
import { Future } from '@swan-io/boxed';

// ✅ Activities are fully typed!  TypeScript knows the input/output types
export const activities = declareActivitiesHandler({
  contract: orderContract,
  activities: {
    validateInventory:  ({ items }) => {
      // input.items is typed! 
      return Future.fromPromise(
        (async () => {
          const unavailable:  string[] = [];

          for (const item of items) {
            const inStock = await checkInventory(item.productId, item.quantity);
            if (!inStock) {
              unavailable.push(item.productId);
            }
          }

          return {
            available: unavailable.length === 0,
            unavailableItems: unavailable,
          };
        })()
      ).mapError((error) =>
        new ActivityError(
          'INVENTORY_CHECK_FAILED',
          error instanceof Error ? error.message : 'Failed to check inventory',
          error
        )
      );
    },

    processPayment: ({ customerId, amount }) => {
      return Future.fromPromise(
        paymentGateway.charge({
          customerId,
          amount,
        })
      )
        .mapError((error) =>
          new ActivityError(
            'PAYMENT_FAILED',
            error instanceof Error ? error. message : 'Payment failed',
            error
          )
        )
        .mapOk((transaction) => ({
          transactionId: transaction.id,
          status: 'success' as const,
        }));
    },

    sendConfirmationEmail: ({ customerId, orderId }) => {
      return Future. fromPromise(
        emailService.send({
          to: customerId,
          template: 'order-confirmation',
          data: { orderId },
        })
      )
        .mapError((error) =>
          new ActivityError(
            'EMAIL_FAILED',
            error instanceof Error ? error.message : 'Failed to send email',
            error
          )
        )
        .mapOk(() => ({ sent: true }));
    },
  },
});

Key Points:

Activities return Future<Output, ActivityError> objects
Use Future.fromPromise() to wrap async operations
Use mapError() to convert errors to ActivityError with error codes
Use mapOk() to transform success values if needed

Step 3: Write Type-Safe Workflows

Workflows use declareWorkflow and receive unwrapped plain values from activities:

import { declareWorkflow } from '@temporal-contract/worker/workflow';
import { orderContract } from './contract';

export const processOrder = declareWorkflow({
  workflowName: 'processOrder',
  contract: orderContract,
  implementation: async ({ activities }, input) => {
    // ✅ input is fully typed from contract!
    console.log(`Processing order ${input.orderId} for customer ${input.customerId}`);

    // ✅ Activities return plain values (Futures are unwrapped automatically)
    const inventory = await activities.validateInventory({
      items: input.items,
    });

    if (!inventory.available) {
      throw new Error(
        `Items unavailable: ${inventory.unavailableItems.join(', ')}`
      );
    }

    // Calculate total
    const totalAmount = input.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );

    // Process payment - activity returns plain value
    const payment = await activities.processPayment({
      customerId: input.customerId,
      amount: totalAmount,
    });

    if (payment.status !== 'success') {
      throw new Error('Payment was not successful');
    }

    // Send confirmation
    await activities.sendConfirmationEmail({
      customerId: input.customerId,
      orderId: input.orderId,
    });

    // ✅ Return type validated against contract schema
    return {
      success: true,
      orderId:  input.orderId,
      totalAmount,
    };
  },
});

Important: Within workflows, activities return plain values. The Future unwrapping happens automatically by the framework. If an activity's Future contains an error, it throws an exception in the workflow.

Step 4: Start the Worker

Create a worker using the standard Temporal Worker with your activities:

import { Worker } from '@temporalio/worker';
import { activities } from './activities';
import { orderContract } from './contract';

async function startWorker() {
  const worker = await Worker.create({
    workflowsPath: require.resolve('./workflows'),
    activities,
    taskQueue: orderContract.taskQueue,
  });

  console.log('Worker started, listening for tasks.. .');
  await worker.run();

  // Graceful shutdown
  process.on('SIGINT', async () => {
    console.log('Shutting down worker...');
    await worker.shutdown();
    process.exit(0);
  });
}

startWorker().catch(console.error);

Step 5: Execute Workflows from Client

Use the TypedClient to execute workflows with full type safety:

import { TypedClient } from '@temporal-contract/client';
import { Connection, Client } from '@temporalio/client';
import { orderContract } from './contract';

async function createOrder() {
  const connection = await Connection.connect({ address: 'localhost:7233' });
  const temporalClient = new Client({ connection });
  const client = TypedClient.create(orderContract, temporalClient);

  // ✅ Fully typed! TypeScript knows exactly what fields are required
  const result = await client. executeWorkflow('processOrder', {
    workflowId: 'order-12345',
    args: {
      orderId: 'ORD-12345',
      customerId: 'CUST-789',
      items: [
        { productId: 'PROD-A', quantity: 2, price: 29.99 },
        { productId: 'PROD-B', quantity: 1, price:  49.99 },
      ],
    },
  });

  console.log('Order processed successfully! ');
  console.log(`Order ID: ${result.orderId}`);
  console.log(`Total:  $${result.totalAmount}`);

  await connection.close();
}

Result/Future Pattern for Error Handling

temporal-contract uses the Result/Future pattern from @swan-io/boxed for explicit, type-safe error handling:

In Activities

Activities return Future objects that can succeed or fail:

const activities = declareActivitiesHandler({
  contract,
  activities: {
    processPayment: ({ orderId }) => {
      return Future.fromPromise(paymentService.process(orderId))
        .mapError((error) =>
          new ActivityError('PAYMENT_FAILED', 'Payment failed', error)
        )
        .mapOk((txId) => ({ transactionId: txId }));
    }
  }
});

In Child Workflows

Child workflows also return Result objects for explicit error handling:

export const parentWorkflow = declareWorkflow({
  workflowName: 'parentWorkflow',
  contract:  myContract,
  implementation: async ({ executeChildWorkflow }, input) => {
    // Execute child workflow and get Result
    const childResult = await executeChildWorkflow(myContract, 'processPayment', {
      workflowId: `payment-${input.orderId}`,
      args: { amount: input.totalAmount }
    });

    // Check for errors explicitly
    childResult.match({
      Ok: (output) => console.log('Payment processed:', output),
      Error: (error) => console.error('Payment failed:', error),
    });

    return { success: true };
  }
});

Benefits:

✅ Explicit error handling — No hidden exceptions
✅ Type-safe — Errors are part of the type system
✅ Composable — Chain operations with map, flatMap, etc.
✅ Better debugging — Clear error paths through your code

Child Workflows with Type Safety

temporal-contract supports type-safe child workflow execution with the Result/Future pattern:

// Define parent and child contracts
const childContract = defineContract({
  taskQueue: 'notifications',
  workflows: {
    sendNotifications: {
      input: z. object({ orderId: z.string() }),
      output: z.object({ sent: z.boolean() }),
    },
  },
});

const parentContract = defineContract({
  taskQueue: 'orders',
  workflows: {
    processOrder: {
      input: z. object({ orderId: z.string() }),
      output: z.object({ success: z.boolean() }),
    },
  },
});

// Execute child workflow with full type safety
export const processOrder = declareWorkflow({
  workflowName: 'processOrder',
  contract: parentContract,
  implementation: async ({ executeChildWorkflow, startChildWorkflow }, input) => {
    // ...  process order logic

    // Execute and wait for result
    const notificationResult = await executeChildWorkflow(
      childContract,
      'sendNotifications',
      {
        workflowId: `notification-${input.orderId}`,
        args: { orderId: input.orderId },
      }
    );

    notificationResult.match({
      Ok: (output) => console.log('Notifications sent:', output. sent),
      Error: (error) => console.error('Failed:', error),
    });

    // Or start without waiting
    const handleResult = await startChildWorkflow(
      childContract,
      'sendNotifications',
      {
        workflowId: `notification-async-${input.orderId}`,
        args: { orderId:  input.orderId },
      }
    );

    handleResult. match({
      Ok: async (handle) => {
        // Can wait for result later
        const result = await handle. result();
        // ... 
      },
      Error: (error) => console.error('Failed to start:', error),
    });

    return { success: true };
  }
});

NestJS Integration

For teams using NestJS, temporal-contract provides first-class integration. See the @temporal-contract/worker-nestjs package for details.

Real-World Benefits

After using temporal-contract in production, here are the benefits we've seen:

1. Catch Errors at Compile Time

// ❌ TypeScript error caught immediately
await client.executeWorkflow('processOrder', {
  workflowId:  'order-123',
  args: {
    orderId: 123, // Error: Type 'number' is not assignable to 'string'
    customerId:  'CUST-456',
  },
});

2. Refactor with Confidence

Change your contract schema once, and TypeScript guides you to update all workflows, activities, and client code. No more runtime surprises!

3. Better Onboarding

New developers can see exactly what workflows are available, what they expect, and what they return — all through autocomplete and type hints.

4. Reduced Bugs

Validation at network boundaries catches invalid data before it reaches your business logic.

5. Explicit Error Handling

The Result/Future pattern provides clear, type-safe error handling for activities and child workflows without relying on exceptions.

Monorepo Architecture

temporal-contract is built as a modular monorepo with separate packages:

Package	Description
`@temporal-contract/contract`	Contract builder and type definitions
`@temporal-contract/worker`	Type-safe worker with automatic validation (uses @swan-io/boxed)
`@temporal-contract/client`	Type-safe client for executing workflows (uses @swan-io/boxed)
`@temporal-contract/worker-nestjs`	NestJS integration with dependency injection
`@temporal-contract/boxed`	Temporal-compatible Result/Future types for workflows (alternative to @swan)
`@temporal-contract/testing`	Testing utilities for integration tests

Install only what you need:

# Just contract and client
pnpm add @temporal-contract/contract @temporal-contract/client

# Add worker for workflow implementation
pnpm add @temporal-contract/worker

# Add NestJS integration
pnpm add @temporal-contract/worker-nestjs

Getting Started

Ready to try temporal-contract? Here's how to get started:

Installation

# Using pnpm (recommended)
pnpm add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
pnpm add @temporalio/client @temporalio/worker zod @swan-io/boxed

# Using npm
npm install @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
npm install @temporalio/client @temporalio/worker zod @swan-io/boxed

# Using yarn
yarn add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client
yarn add @temporalio/client @temporalio/worker zod @swan-io/boxed

Quick Start

Define your contract in contract.ts
Implement activities with declareActivitiesHandler returning Futures
Write workflows with declareWorkflow
Create a worker with standard Temporal Worker
Use the client with TypedClient. create()
*Enjoy type safety! *

Check out the Getting Started Guide for detailed instructions.

Examples

The repository includes several complete examples showing real-world usage patterns. Visit the examples directory to see:

Basic workflow with activities
Child workflow execution
Error handling with Result/Future pattern
NestJS integration

Each example is a working application you can run locally with a Temporal dev server.

Comparison with Other Solutions

vs. Plain Temporal SDK

✅ Type safety enforced at compile time
✅ Automatic validation
✅ Better DX with autocomplete
✅ Single source of truth for schemas
✅ Explicit error handling with Result/Future pattern

vs. Manual Type Definitions

✅ No drift between types and implementations
✅ Automatic validation
✅ Less boilerplate
✅ Guaranteed consistency

vs. Other Workflow Libraries

✅ Built specifically for Temporal. io
✅ Contract-first approach
✅ Result/Future pattern for error handling
✅ NestJS integration included

What's Next?

We have exciting plans for temporal-contract:

🎯 Nexus support — Cross-namespace operations
🎯 Enhanced testing utilities — Better test helpers
🎯 Signal/Query support — Type-safe signals and queries
🎯 More examples — Real-world use cases
🎯 Documentation improvements — More guides and tutorials

Contributing

temporal-contract is open source and we welcome contributions! Whether it's:

🐛 Bug reports
💡 Feature requests
📝 Documentation improvements
🔧 Code contributions

Check out the Contributing Guide to get started.

Resources

Documentation: https://btravers.github.io/temporal-contract
GitHub: https://github.com/btravers/temporal-contract
npm: @temporal-contract/contract
Temporal.io: https://temporal.io

Conclusion

If you're building TypeScript applications with Temporal.io, temporal-contract can dramatically improve your development experience. By bringing type safety to workflows and activities, it catches errors early and makes your code more maintainable.

The contract-first approach ensures consistency across your distributed workflows, while the Result/Future pattern provides robust error handling with explicit, type-safe errors.

Give it a try and let us know what you think! We'd love to hear your feedback and use cases.

Try temporal-contract today:

pnpm add @temporal-contract/contract @temporal-contract/worker @temporal-contract/client

Happy orchestrating! ⚡🔄

btravers / temporal-contract

End-to-end type safety and automatic validation for workflows and activities

temporal-contract

Type-safe contracts for Temporal.io

End-to-end type safety and automatic validation for workflows and activities

Documentation · Get Started · Examples

Features

✅ End-to-end type safety — From contract to client, workflows, and activities
✅ Automatic validation — Zod schemas validate at all network boundaries
✅ Compile-time checks — TypeScript catches missing or incorrect implementations
✅ Better DX — Autocomplete, refactoring support, inline documentation
✅ Child workflows — Type-safe child workflow execution with Result/Future pattern
✅ Result/Future pattern — Explicit error handling without exceptions
🚧 Nexus support — Cross-namespace operations (planned for v0.5.0)

Quick Example

// Define contract once
const contract = defineContract({
  taskQueue: "orders",
  workflows: {
    processOrder: {
      input: z.object({ orderId: z.string() }),
      output: z.object({ success: z.boolean() }),
      activities

…

View on GitHub

Introducing amqp-contract - Type-Safe RabbitMQ/AMQP Messaging for TypeScript

Benoit Travers — Sat, 20 Dec 2025 15:52:08 +0000

If you've worked with RabbitMQ or AMQP messaging in TypeScript, you've probably experienced the pain of maintaining type safety across your message publishers and consumers. Today, I'm excited to introduce amqp-contract — a library that brings end-to-end type safety to AMQP messaging with automatic validation and AsyncAPI generation.

The Problem with Traditional AMQP Development

Working with RabbitMQ is powerful for building distributed systems, but the traditional approach has several pain points:

// ❌ Traditional approach: No type safety
const channel = await connection.createChannel();

// Publishing - what fields? what types?
channel.publish(
  'orders',
  'order.created',
  Buffer.from(JSON.stringify({
    orderId: 'ORD-123',
    amount: 99.99
  }))
);

// Consuming - message type is unknown
channel.consume('order-processing', (msg) => {
  if (msg) {
    const data = JSON.parse(msg.content.toString()); // any type
    console.log(data.orderId); // No autocomplete, no validation
    // What if someone sends the wrong data?
  }
});

Problems:

🚫 No type safety between publishers and consumers
🚫 Manual validation required everywhere
🚫 Runtime errors from wrong data structures
🚫 No autocomplete or IntelliSense
🚫 Difficult to maintain consistency across services
🚫 Message schema scattered across codebase

Introducing amqp-contract

amqp-contract solves these problems with a contract-first approach. You define your AMQP resources and message schemas once using Standard Schema compliant libraries (Zod, Valibot, or ArkType), and type safety flows throughout your application.

Key Features

✅ End-to-end type safety — Full TypeScript inference from contract to client and worker

✅ Automatic validation — Schema validation at all network boundaries

✅ Compile-time checks — Catch errors before runtime

✅ AsyncAPI generation — Generate AsyncAPI 3.0 specifications automatically

✅ Better DX — Full autocomplete, inline documentation, and refactoring support

✅ Flexible schemas — Use Zod, Valibot, or ArkType

How It Works

Step 1: Define Your Contract

First, define your AMQP topology and message schemas in one place:

import {
  defineContract,
  defineExchange,
  defineQueue,
  defineBinding,
  definePublisher,
  defineConsumer,
} from '@amqp-contract/contract';
import { z } from 'zod';

// Define contract once with full type safety
export const orderContract = defineContract({
  exchanges: {
    orders: defineExchange('orders', 'topic', { durable: true }),
  },
  queues: {
    orderProcessing: defineQueue('order-processing', { durable: true }),
  },
  bindings: {
    orderBinding: defineBinding('order-processing', 'orders', {
      routingKey: 'order.created',
    }),
  },
  publishers: {
    orderCreated: definePublisher(
      'orders',
      z.object({
        orderId: z.string(),
        customerId: z.string(),
        amount: z.number().positive(),
        items: z.array(
          z.object({
            productId: z.string(),
            quantity: z.number().int().positive(),
          })
        ),
      }),
      { routingKey: 'order.created' }
    ),
  },
  consumers: {
    processOrder: defineConsumer(
      'order-processing',
      z.object({
        orderId: z.string(),
        customerId: z.string(),
        amount: z.number().positive(),
        items: z.array(
          z.object({
            productId: z.string(),
            quantity: z.number().int().positive(),
          })
        ),
      }),
      { prefetch: 10 }
    ),
  },
});

Step 2: Type-Safe Publishing

Use the typed client to publish messages with full type safety:

import { TypedAmqpClient } from '@amqp-contract/client';
import { orderContract } from './contract';

async function publishOrder() {
  const client = await TypedAmqpClient.create({
    contract: orderContract,
    connection: 'amqp://localhost',
  });

  // ✅ Fully typed! TypeScript knows exactly what fields are required
  await client.publish('orderCreated', {
    orderId: 'ORD-123',
    customerId: 'CUST-456',
    amount: 99.99,
    items: [
      { productId: 'PROD-A', quantity: 2 },
      { productId: 'PROD-B', quantity: 1 },
    ],
  });

  // ❌ TypeScript error: Type 'string' is not assignable to type 'number'
  // await client.publish('orderCreated', {
  //   orderId: 'ORD-123',
  //   customerId: 'CUST-456',
  //   amount: 'invalid', // Error caught at compile time!
  // });

  console.log('Order published with validation!');
  await client.close();
}

The client automatically:

✅ Validates the message against the schema
✅ Serializes to JSON and Buffer
✅ Publishes to the correct exchange with routing key
✅ Provides full autocomplete in your IDE

Step 3: Type-Safe Consuming

Create workers with fully typed message handlers:

import { TypedAmqpWorker } from '@amqp-contract/worker';
import { orderContract } from './contract';

async function startWorker() {
  const worker = await TypedAmqpWorker.create({
    contract: orderContract,
    handlers: {
      processOrder: async (message) => {
        // ✅ message is fully typed!
        // TypeScript knows: message.orderId is string
        // TypeScript knows: message.amount is number
        // TypeScript knows: message.items is an array

        console.log(`Processing order: ${message.orderId}`);
        console.log(`Customer: ${message.customerId}`);
        console.log(`Total: $${message.amount}`);

        for (const item of message.items) {
          console.log(`  - Product ${item.productId}: ${item.quantity}x`);
          // Full autocomplete available!
        }

        // Your business logic here...
      },
    },
    connection: 'amqp://localhost',
  });

  console.log('Worker started, waiting for messages...');

  // Graceful shutdown
  process.on('SIGINT', async () => {
    console.log('Shutting down worker...');
    await worker.close();
    process.exit(0);
  });
}

The worker automatically:

✅ Sets up queues, exchanges, and bindings
✅ Validates incoming messages
✅ Provides typed message handlers
✅ Handles acknowledgments

AsyncAPI Generation

One of the most powerful features is automatic AsyncAPI 3.0 generation. Document your API without writing a single line of YAML:

import { generateAsyncAPI } from '@amqp-contract/asyncapi';
import { orderContract } from './contract';
import { writeFileSync } from 'node:fs';

const spec = generateAsyncAPI(orderContract, {
  info: {
    title: 'Order Processing API',
    version: '1.0.0',
    description: 'API for processing customer orders',
  },
  servers: {
    production: {
      host: 'rabbitmq.example.com:5672',
      protocol: 'amqp',
      description: 'Production RabbitMQ server',
    },
    development: {
      host: 'localhost:5672',
      protocol: 'amqp',
      description: 'Local development server',
    },
  },
});

// Save AsyncAPI spec
writeFileSync('asyncapi.json', JSON.stringify(spec, null, 2));

This generates a complete AsyncAPI specification that you can use with:

AsyncAPI Studio for interactive documentation
AsyncAPI Generator for code generation
Microcks for API mocking and testing
Any other AsyncAPI-compatible tooling

Multiple Schema Library Support

While the examples above use Zod, amqp-contract supports any Standard Schema v1 compliant library:

Zod

import { z } from 'zod';

const schema = z.object({
  orderId: z.string(),
  amount: z.number().positive(),
});

Valibot

import * as v from 'valibot';

const schema = v.object({
  orderId: v.string(),
  amount: v.pipe(v.number(), v.minValue(0)),
});

ArkType

import { type } from 'arktype';

const schema = type({
  orderId: 'string',
  amount: 'number>0',
});

All three work seamlessly with amqp-contract!

Real-World Benefits

After using amqp-contract in production, here are the benefits we've seen:

1. Catch Errors at Compile Time

// ❌ TypeScript error caught immediately
await client.publish('orderCreated', {
  orderId: 123, // Error: Type 'number' is not assignable to 'string'
  amount: 99.99,
});

2. Refactor with Confidence

Change your message schema once, and TypeScript guides you to update all publishers and consumers. No more runtime surprises!

3. Better Onboarding

New developers can see exactly what messages are available and what fields they require just by looking at the contract and using IDE autocomplete.

4. Automatic Documentation

AsyncAPI generation means your documentation is always in sync with your code.

5. Reduced Bugs

Validation at network boundaries catches invalid data before it reaches your business logic.

Monorepo Architecture

amqp-contract is built as a modular monorepo with separate packages:

Package	Description
`@amqp-contract/contract`	Core contract builder and type definitions
`@amqp-contract/client`	Type-safe client for publishing messages
`@amqp-contract/worker`	Type-safe worker for consuming messages
`@amqp-contract/asyncapi`	AsyncAPI 3.0 specification generator
`@amqp-contract/zod`	Zod integration utilities
`@amqp-contract/valibot`	Valibot integration utilities
`@amqp-contract/arktype`	ArkType integration utilities

Install only what you need:

# Just the contract and client
pnpm add @amqp-contract/contract @amqp-contract/client

# Add worker for consuming
pnpm add @amqp-contract/worker

# Add AsyncAPI generation
pnpm add @amqp-contract/asyncapi

Getting Started

Ready to try amqp-contract? Here's how to get started:

Installation

# Using pnpm (recommended)
pnpm add @amqp-contract/contract @amqp-contract/client @amqp-contract/worker
pnpm add amqplib zod

# Using npm
npm install @amqp-contract/contract @amqp-contract/client @amqp-contract/worker
npm install amqplib zod

# Using yarn
yarn add @amqp-contract/contract @amqp-contract/client @amqp-contract/worker
yarn add amqplib zod

Quick Start

Define your contract in contract.ts
Create a publisher using TypedAmqpClient
Create a consumer using TypedAmqpWorker
Enjoy type safety!

Check out our Getting Started Guide for detailed instructions.

Examples

The repository includes several complete examples:

Basic Order Processing - Simple order processing system
AsyncAPI Generation - Generate AsyncAPI specs

Each example is a working application you can run locally.

Comparison with Other Solutions

vs. Plain amqplib

✅ Type safety
✅ Automatic validation
✅ Better DX with autocomplete
✅ AsyncAPI generation

vs. Manual Type Definitions

✅ Single source of truth
✅ Automatic validation
✅ Less boilerplate
✅ Guaranteed consistency

vs. Other Messaging Libraries

✅ Designed specifically for AMQP/RabbitMQ
✅ Contract-first approach
✅ Standard Schema support
✅ AsyncAPI generation included

What's Next?

We have exciting plans for amqp-contract:

🎯 Support for more Standard Schema libraries
🎯 Enhanced AsyncAPI features
🎯 CLI tools for contract validation
🎯 Code generation from AsyncAPI specs
🎯 RabbitMQ management integration
🎯 Testing utilities for contract validation

Contributing

amqp-contract is open source and we welcome contributions! Whether it's:

🐛 Bug reports
💡 Feature requests
📝 Documentation improvements
🔧 Code contributions

Check out our Contributing Guide to get started.

Resources

Documentation: https://btravers.github.io/amqp-contract
GitHub: https://github.com/btravers/amqp-contract
npm: @amqp-contract/contract
Examples: Sample Projects

Conclusion

If you're building TypeScript applications with RabbitMQ or AMQP, amqp-contract can dramatically improve your development experience. By bringing type safety to messaging, it catches errors at compile time, makes refactoring safer, and provides excellent developer experience with autocomplete and inline documentation.

The contract-first approach ensures consistency across your distributed system, while AsyncAPI generation keeps your documentation in sync with your code.

Give it a try and let us know what you think! We'd love to hear your feedback and use cases.

Try amqp-contract today:

pnpm add @amqp-contract/contract @amqp-contract/client @amqp-contract/worker

Happy messaging! 🐰📨

btravers / amqp-contract

Type-safe contracts for AMQP/RabbitMQ messaging with TypeScript

amqp-contract

Type-safe contracts for AMQP/RabbitMQ messaging with TypeScript

Documentation · Get Started · 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

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"

…

View on GitHub