{ "version": "https://jsonfeed.org/version/1", "title": "The Codegen Project feed", "home_page_url": "https://the-codegen-project.org/blog", "description": "The Codegen Project Blog", "items": [ { "id": "https://the-codegen-project.org/blog/update-3", "content_html": "

I am way to good at working in the shadows... Since our last update at v0.39.0, the project has grown substantially. Spanning versions v0.40.0 through v0.62.1 and brings complete OpenAPI support, a powerful HTTP client support, and an MCP server for AI integration.

\n

TLDR:

\n\n

MCP Server for AI Integration​

\n

Perhaps the most exciting addition is the MCP (Model Context Protocol) server. This gives AI assistants like Claude, Cursor, and others deep context about The Codegen Project - its generators, protocols, configuration options, and best practices.

\n

Why does this matter? Deterministic code generation and AI are complementary. The MCP server bridges these worlds by helping AI assistants create the right context for the task at hand.

\n

This means you can ask your AI assistant to \"set up NATS messaging from my AsyncAPI spec\" and it will use The Codegen Project to generate consistent, tested code - then help you implement the business logic on top.

\n

Complete OpenAPI Support​

\n

The Codegen Project now fully supports OpenAPI (Swagger 2.0, OpenAPI 3.0, and 3.1) specifications:

\n
// codegen.config.mjs
export default {
  inputType: 'openapi',
  inputPath: './openapi.json',
  language: 'typescript',
  generators: [
    { preset: 'payloads', outputPath: './src/models' },
    { preset: 'parameters', outputPath: './src/params' },
    { preset: 'headers', outputPath: './src/headers' },
    { preset: 'types', outputPath: './src/types' },
    { preset: 'channels', outputPath: './src/api', protocols: ['http_client'] }
  ]
};
\n

Most of the generators you know from AsyncAPI now work with OpenAPI - payloads with validation, typed parameters and headers, and HTTP-specific channel functions.

\n

HTTP Client Protocol Refactor​

\n

The HTTP client protocol received a major overhaul with enterprise-grade features:

\n

Authentication:

\n\n

Resilience:

\n\n

Pagination:

\n\n
// Generated code with full type safety
const response = await getUsers({
  parameters: { page: 1, limit: 10 },
  auth: { type: 'bearer', token: 'your-token' },
  retry: { maxRetries: 3, backoffMs: 1000 }
});
\n

JSON Schema Input Processor​

\n

You can now generate models directly from JSON Schema files:

\n
export default {
  inputType: 'jsonschema',
  inputPath: './schema.json',
  language: 'typescript',
  generators: [
    { preset: 'models', outputPath: './src/models' }
  ]
};
\n

This supports Draft-4, Draft-6, and Draft-7 specifications.

\n

Other Notable Improvements​

\n

Watch Mode - Automatically regenerate code when your spec changes:

\n
codegen generate --watch
codegen generate --watch --watchPath ./specs
\n

WebSocket Channels - Full WebSocket support with publish, subscribe, and register patterns for bidirectional messaging.

\n

MQTT Subscribe - Complete MQTT subscription functionality with QoS support.

\n

Headers Across Protocols - NATS, Kafka, MQTT, AMQP, and WebSocket all now support typed headers when defined in your spec.

\n

Types Generator - Generate simple type definitions without full model classes.

\n

Models Generator - Generate complex data models using Modelina integration.

\n

Telemetry - Anonymous usage tracking to help improve the project (easily disabled via CODEGEN_TELEMETRY_DISABLED=true).

\n

Improved Channel Structure - Protocol implementations are now split into separate files for better maintainability.

\n
\n

This release represents a significant expansion of The Codegen Project's capabilities. Whether you're working with AsyncAPI, OpenAPI, or JSON Schema - and whether you're building messaging systems or REST APIs - the tooling is now more comprehensive than ever.

\n

The MCP server integration particularly excites us as it validates the vision: deterministic code generation and AI working together, each doing what they do best.

\n

Give v0.62.1 a try, and let us know what you think!

\n

Until next time, happy coding!

", "url": "https://the-codegen-project.org/blog/update-3", "title": "The Codegen Project - 8 Months of Progress", "summary": "I am way to good at working in the shadows... Since our last update at v0.39.0, the project has grown substantially. Spanning versions v0.40.0 through v0.62.1 and brings complete OpenAPI support, a powerful HTTP client support, and an MCP server for AI integration.", "date_modified": "2026-01-28T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-client-generator", "content_html": "

Building integrations with event-driven services requires managing connections alongside your messaging logic. In our previous post on protocol-specific messaging functions, we explored how to generate low-level channel functions for NATS, Kafka, and other protocols. Now let's see how The Codegen Project's client generator takes this a step further by providing a convenient wrapper around those channel functions that handles connection management and exposes all relevant models like parameters and headers.

\n

From Channel Functions to Client Wrapper​

\n

While channel functions provide excellent protocol-specific abstractions, they require you to manage connections manually and import various model types separately. The client generator creates a simple wrapper that:

\n
    \n
  1. Connection Management - Provides connection handling methods on a class
    2. \n
  2. Centralized Access - All protocol functions accessible through one client instance
    3. \n
  3. Model Exposure - All relevant models (parameters, headers, payloads) are exported from one place
    4. \n
  4. Same Functionality - All the same protocol functions, just wrapped in a class
    5. \n
\n

The client generator builds on the foundation of channel functions without changing their core functionality.

\n

The Problem: Manual Connection Management​

\n

When using raw channel functions (as generated by the channels preset), you typically write code like this:

\n
// Using channel functions - manual connection management
import { Protocols } from './generated';
import { connect } from 'nats';
const { nats } = Protocols;

// Manual connection management
const connection = await connect({ servers: 'nats://localhost:4222' });

// Protocol-specific function calls
await nats.publishToPublishOrderCreated({
  message: orderCreatedMessage,
  parameters: orderCreatedParams,
  nc: connection  // Must pass connection to every call
});

// Must manage connection lifecycle yourself
await connection.close();
\n

You need to manage connections manually and pass them to every function call.

\n

The Solution: Client Wrapper + Connection Management​

\n

The Codegen Project's client preset generates a simple wrapper class that manages connections for you while exposing the same protocol functions.

\n
\n

💡 Built on Channel Functions: The client generator automatically includes and wraps the channels generator functions, providing connection management while maintaining all the same functionality.

\n
\n

Real-World Example: E-commerce Order Management Client​

\n

Let's build a client wrapper for order lifecycle management. We'll use the same AsyncAPI specification from our channels generator post, but generate a client wrapper that manages connections.

\n
\n

💡 Complete Example: You can find the full working example, including all files mentioned in this post, in our ecommerce-asyncapi-client example.

\n
\n
Show me the AsyncAPI document!

asyncapi: 3.0.0
info:
  title: E-commerce Order Lifecycle Events
  version: 1.0.0
  description: Event-driven order management system with comprehensive lifecycle tracking

channels:
  # Order Management Channels
  order-lifecycle:
    address: orders.{action}
    parameters:
      action:
        $ref: '#/components/parameters/OrderAction'
    messages:
      OrderCreated:
        $ref: '#/components/messages/OrderCreated'
      OrderUpdated:
        $ref: '#/components/messages/OrderUpdated'
      OrderCancelled:
        $ref: '#/components/messages/OrderCancelled'

operations:
  # Order Management Operations
  OrderCreated:
    action: send
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderCreated'

  OrderUpdated:
    action: send
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderUpdated'

  OrderCancelled:
    action: send
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderCancelled'

  OrderEvents:
    action: receive
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderCreated'
      - $ref: '#/channels/order-lifecycle/messages/OrderUpdated'
      - $ref: '#/channels/order-lifecycle/messages/OrderCancelled'

components:
  # Reusable Parameters
  parameters:
    OrderAction:
      enum: [created, updated, cancelled, shipped, delivered]
      description: Order lifecycle action

  # Reusable Messages
  messages:
    OrderCreated:
      name: OrderCreated
      title: Order Created Event
      summary: Published when a new order is created
      payload:
        $ref: '#/components/schemas/OrderCreatedPayload'
      headers:
        $ref: '#/components/schemas/OrderHeaders'

    OrderUpdated:
      name: OrderUpdated
      title: Order Updated Event
      summary: Published when order details are modified
      payload:
        $ref: '#/components/schemas/OrderUpdatedPayload'
      headers:
        $ref: '#/components/schemas/OrderHeaders'

    OrderCancelled:
      name: OrderCancelled
      title: Order Cancelled Event
      summary: Published when an order is cancelled
      payload:
        $ref: '#/components/schemas/OrderCancelledPayload'
      headers:
        $ref: '#/components/schemas/OrderHeaders'

  schemas:
    # Order Payload Schemas
    OrderCreatedPayload:
      type: object
      required: [orderId, customerId, items, totalAmount]
      properties:
        orderId:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        totalAmount:
          $ref: '#/components/schemas/Money'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        createdAt:
          type: string
          format: date-time

    OrderUpdatedPayload:
      type: object
      required: [orderId, status, updatedAt]
      properties:
        orderId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/OrderStatus'
        updatedAt:
          type: string
          format: date-time
        reason:
          type: string
        updatedFields:
          type: array
          items:
            type: string

    OrderStatus:
      type: string
      enum: [pending, confirmed, processing, shipped, delivered, cancelled]
    OrderCancelledPayload:
      type: object
      required: [orderId, reason, cancelledAt]
      properties:
        orderId:
          type: string
          format: uuid
        reason:
          type: string
        cancelledAt:
          type: string
          format: date-time
        refundAmount:
          $ref: '#/components/schemas/Money'

    # Order Header Schema
    OrderHeaders:
      type: object
      required: [x-correlation-id, x-order-id, x-customer-id]
      properties:
        x-correlation-id:
          type: string
          format: uuid
        x-order-id:
          type: string
          format: uuid
        x-customer-id:
          type: string
          format: uuid
        x-source-service:
          type: string

    # Supporting Schemas
    OrderItem:
      type: object
      required: [productId, quantity, unitPrice]
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
        unitPrice:
          $ref: '#/components/schemas/Money'
        productName:
          type: string
        productCategory:
          type: string

    Money:
      type: object
      required: [amount, currency]
      properties:
        amount:
          type: integer
          minimum: 0
          description: Amount in smallest currency unit (e.g., cents for USD)
        currency:
          $ref: '#/components/schemas/Currency'
    Currency:
      type: string
      enum: [USD, EUR, GBP]
    Address:
      type: object
      required: [street, city, country, postalCode]
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string

\n

Generating the Client Wrapper​

\n

Create a configuration file to generate a TypeScript client wrapper:

\n
// codegen.config.js
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-event-channels.yaml',
  generators: [
    {
      preset: 'client',
      outputPath: './src/generated',
      language: 'typescript',
      protocols: ['nats']
    }
  ]
};
\n

Run the generator:

\n
npx @the-codegen-project/cli generate codegen.config.js
\n

This generates a wrapper class around the protocol functions:

\n
// Generated: src/generated/NatsClient.ts

// All models exported for convenience
// export * from './payloads';

export class NatsClient {
  private connection?: NatsConnection;

  // Connection management methods
  async connectToHost(url: string): Promise<void> {
    this.connection = await connect({ servers: url });
  }

  async disconnect(): Promise<void> {
    if (this.connection) {
      await this.connection.close();
    }
  }

  // Same protocol functions as channels generator, but wrapped
  async publishToOrderCreated({message, parameters}: {
    message: OrderCreated, 
    parameters: OrderLifecycleParameters
  }): Promise<void> {
    /* Handle connection logic and call channel function */
  }
}
\n

Using the Generated Client Wrapper: Connection Management​

\n

Now let's see how the client wrapper simplifies connection management compared to raw channel functions:

\n

Connection Management Made Simple​

\n
import { NatsClient, OrderCreated, OrderLifecycleParameters } from './generated/NatsClient';

class OrderService {
  private client = new NatsClient();

  async initialize() {
    // Connection managed by the client wrapper
    await this.client.connectToHost('nats://localhost:4222');
    console.log('✅ Connected to NATS server');
  }

  async createOrder(): Promise<string> {
    const orderData = new OrderCreated({
      orderId: '123e4567-e89b-12d3-a456-426614174000',
      customerId: '987fcdeb-51a2-43d1-9f12-345678901234',
      items: [/* order items */],
      totalAmount: new Money({ amount: 309895, currency: Currency.USD }),
      // ... other order data
    });

    const parameters = new OrderLifecycleParameters({ action: 'created' });

    // Same function as channels generator, but connection is managed
    await this.client.publishToOrderCreated({message: orderData, parameters});
    console.log(`✅ Order created: ${orderData.orderId}`);
    
    return orderData.orderId;
  }

  async cleanup() {
    // Clean connection management
    await this.client.disconnect();
  }
}
\n

Event Subscription with Managed Connection​

\n
class OrderService {
  private client = new NatsClient();
  ...
  
  private async setupEventHandlers() {
    const parameters = new OrderLifecycleParameters({ action: 'created' });

    // Same callback signature as channel functions
    await this.client.subscribeToOrderEvents({
      onDataCallback: (err, message, parameters, natsMsg) => {
        // Same callback parameters as channel functions
        if (err) {
          console.error('❌ Error processing order event:', err.message);
          return;
        }
        this.handleOrderEvent(message, parameters);
      },
      parameters
    });
  }

  private handleOrderEvent(message: any, parameters?: OrderLifecycleParameters) {
    const action = parameters?.action || 'unknown';
    
    switch (action) {
      case 'created':
        console.log(`💰 New sale: $${(message?.totalAmount?.amount / 100).toFixed(2)}`);
        break;
      case 'updated':
        console.log(`📊 Status updated: ${message?.status}`);
        break;
      case 'cancelled':
        console.log(`💸 Processing refund: $${(message?.refundAmount?.amount / 100).toFixed(2)}`);
        break;
    }
  }
}
\n

JetStream with Connection Management​

\n
class DurableOrderProcessor {
  private client = new NatsClient();

  async setupDurableProcessing() {
    const parameters = new OrderLifecycleParameters({ action: 'created' });

    // Same JetStream functions as channel generator, but wrapped
    await this.client.jetStreamPullSubscribeToOrderEvents({
      onDataCallback: (err, message, parameters, jsMsg) => {
        // Same callback as channel functions
        if (err) {
          console.error('❌ Error processing order:', err.message);
          return;
        }
        this.processOrderForFulfillment(message);
      },
      parameters,
      options: { name: 'order-processor', config: { max_batch: 10 } }
    });
  }

  private async processOrderForFulfillment(order: any) {
    console.log(`🏭 Processing order: ${order?.orderId}`);
    
    // Business logic here...
    
    // Same JetStream publish function, connection managed
    const updateMessage = new OrderUpdated({
      orderId: order?.orderId,
      status: OrderStatus.PROCESSING,
      updatedAt: new Date().toISOString(),
      reason: 'Order processing started by fulfillment system'
    });

    const parameters = new OrderLifecycleParameters({ action: 'updated' });

    await this.client.jetStreamPublishToOrderUpdated({message: updateMessage, parameters});
  }
}
\n

Client Wrapper vs Channel Functions: Key Differences​

\n
AspectChannel FunctionsClient Wrapper
Connection ManagementManual - you manage connectionsWrapped - client manages connections
Function SignaturesSame protocol functionsSame protocol functions (wrapped)
Method NamesSame as channel functionsSame as channel functions
Callback SignatureProtocol-specific parametersSame protocol-specific parameters
Error HandlingSame protocol errorsSame protocol errors
Model AccessImport separatelyAll exported from client
Use CaseDirect protocol controlConnection convenience
\n

Benefits of This Approach​

\n
    \n
  1. Connection Management: Automatic connection handling in a class wrapper
    2. \n
  2. Centralized Models: All parameters, headers, and payloads exported from one place
    3. \n
  3. Same Functionality: All the same protocol functions, just connection-wrapped
    4. \n
  4. Type Safety: Same TypeScript support as channel functions
    5. \n
  5. Built on Channel Functions: Uses channel functions internally unchanged
    6. \n
  6. Protocol Functions: Same NATS/JetStream functions as channels generator
    7. \n
  7. Simple Wrapper: Minimal abstraction over existing channel functions
    8. \n
  8. Easy Migration: Can switch between channel functions and client wrapper easily
    9. \n
\n

Conclusion​

\n

The client generator provides a thin wrapper around the channel functions from our channels generator, adding connection management convenience while preserving all the same protocol functionality.

\n

This approach allows developers to use the same protocol functions they're familiar with, but with the convenience of managed connections and centralized model exports. The wrapper doesn't change the underlying functionality - it just makes connection management easier.

\n

Ready to try it yourself? Check out the client generator documentation and start building your connection wrapper today!

\n

Try It Yourself​

\n

Want to see this in action? Clone our ecommerce-asyncapi-client example and run:

\n
cd examples/ecommerce-asyncapi-client
npm install
npm run generate
npm run demo
\n

This will generate the client wrapper and run the demonstration shown above, highlighting the connection management convenience with the same NATS messaging functions.

\n

🎯 Key Benefits of Client Wrapper:\n• Connection management in a class\n• Centralized model exports\n• Same protocol functions as channels generator\n• Minimal wrapper overhead\n• Easy migration path\n• No functional changes to messaging

\n

Additional Resources​

\n

Documentation​

\n", "url": "https://the-codegen-project.org/blog/asyncapi-client-generator", "title": "AsyncAPI - Simplifying Channels Into One", "summary": "Building integrations with event-driven services requires managing connections alongside your messaging logic. In our previous post on protocol-specific messaging functions, we explored how to generate low-level channel functions for NATS, Kafka, and other protocols. Now let's see how The Codegen Project's client generator takes this a step further by providing a convenient wrapper around those channel functions that handles connection management and exposes all relevant models like parameters and headers.", "date_modified": "2025-07-15T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Client", "TypeScript", "Integration", "Automation" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-channel-generator", "content_html": "

Building scalable event-driven applications requires robust messaging infrastructure that works seamlessly with your chosen protocols. We've covered payload generation, header management, and type-safe routing. Now let's explore how The Codegen Project's channels generator creates protocol-specific functions that streamline your messaging architecture while working with your favorite messaging systems.

\n

The Problem: Protocol-Specific Integration​

\n

When building event-driven order management systems, you typically need:

\n
    \n
  1. Protocol Integration - Working seamlessly with NATS, Kafka, MQTT, AMQP, or HTTP
    2. \n
  2. Channel Management - Publishing and subscribing to channels with proper addressing
    3. \n
  3. Type-Safe Operations - Ensuring messages are sent with correct payloads and parameters
    4. \n
  4. Parameter Handling - Managing dynamic channel addresses with parameters
    5. \n
  5. Protocol Abstraction - Clean abstractions over complex protocol APIs
    6. \n
\n

Without automated channel generation, teams often struggle with:

\n\n

The Solution: Generated Protocol Functions + Your Infrastructure​

\n

The Codegen Project's channels preset generates protocol-specific functions from your AsyncAPI specification, providing clean abstractions for publishing and subscribing while automatically including payload and parameter validation.

\n

Real-World Example: Order Lifecycle Management​

\n

Let's build protocol-specific functions for order lifecycle management. Here's our AsyncAPI specification focused on order operations:

\n
\n

💡 Complete Example: You can find the full working example, including all files mentioned in this post, in our ecommerce-channels example.

\n
\n
Show me the AsyncAPI document!

asyncapi: 3.0.0
info:
  title: E-commerce Order Lifecycle Events
  version: 1.0.0
  description: Event-driven order management system with comprehensive lifecycle tracking

channels:
  # Order Management Channels
  order-lifecycle:
    address: orders.{action}
    parameters:
      action:
        $ref: '#/components/parameters/OrderAction'
    messages:
      OrderCreated:
        $ref: '#/components/messages/OrderCreated'
      OrderUpdated:
        $ref: '#/components/messages/OrderUpdated'
      OrderCancelled:
        $ref: '#/components/messages/OrderCancelled'

operations:
  # Order Management Operations
  publishOrderCreated:
    action: send
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderCreated'

  publishOrderUpdated:
    action: send
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderUpdated'

  publishOrderCancelled:
    action: send
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderCancelled'

  subscribeToOrderEvents:
    action: receive
    channel:
      $ref: '#/channels/order-lifecycle'
    messages:
      - $ref: '#/channels/order-lifecycle/messages/OrderCreated'
      - $ref: '#/channels/order-lifecycle/messages/OrderUpdated'
      - $ref: '#/channels/order-lifecycle/messages/OrderCancelled'

components:
  # Reusable Parameters
  parameters:
    OrderAction:
      enum: [created, updated, cancelled, shipped, delivered]
      description: Order lifecycle action

  # Reusable Messages
  messages:
    OrderCreated:
      name: OrderCreated
      title: Order Created Event
      summary: Published when a new order is created
      payload:
        $ref: '#/components/schemas/OrderCreatedPayload'
      headers:
        $ref: '#/components/schemas/OrderHeaders'

    OrderUpdated:
      name: OrderUpdated
      title: Order Updated Event
      summary: Published when order details are modified
      payload:
        $ref: '#/components/schemas/OrderUpdatedPayload'
      headers:
        $ref: '#/components/schemas/OrderHeaders'

    OrderCancelled:
      name: OrderCancelled
      title: Order Cancelled Event
      summary: Published when an order is cancelled
      payload:
        $ref: '#/components/schemas/OrderCancelledPayload'
      headers:
        $ref: '#/components/schemas/OrderHeaders'

  schemas:
    # Order Payload Schemas
    OrderCreatedPayload:
      type: object
      required: [orderId, customerId, items, totalAmount]
      properties:
        orderId:
          type: string
          format: uuid
        customerId:
          type: string
          format: uuid
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        totalAmount:
          $ref: '#/components/schemas/Money'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        createdAt:
          type: string
          format: date-time

    OrderUpdatedPayload:
      type: object
      required: [orderId, status, updatedAt]
      properties:
        orderId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/OrderStatus'
        updatedAt:
          type: string
          format: date-time
        reason:
          type: string
        updatedFields:
          type: array
          items:
            type: string

    OrderStatus:
      type: string
      enum: [pending, confirmed, processing, shipped, delivered, cancelled]
    OrderCancelledPayload:
      type: object
      required: [orderId, reason, cancelledAt]
      properties:
        orderId:
          type: string
          format: uuid
        reason:
          type: string
        cancelledAt:
          type: string
          format: date-time
        refundAmount:
          $ref: '#/components/schemas/Money'

    # Order Header Schema
    OrderHeaders:
      type: object
      required: [x-correlation-id, x-order-id, x-customer-id]
      properties:
        x-correlation-id:
          type: string
          format: uuid
        x-order-id:
          type: string
          format: uuid
        x-customer-id:
          type: string
          format: uuid
        x-source-service:
          type: string

    # Supporting Schemas
    OrderItem:
      type: object
      required: [productId, quantity, unitPrice]
      properties:
        productId:
          type: string
          format: uuid
        quantity:
          type: integer
          minimum: 1
        unitPrice:
          $ref: '#/components/schemas/Money'
        productName:
          type: string
        productCategory:
          type: string

    Money:
      type: object
      required: [amount, currency]
      properties:
        amount:
          type: integer
          minimum: 0
          description: Amount in smallest currency unit (e.g., cents for USD)
        currency:
          $ref: '#/components/schemas/Currency'
    Currency:
      type: string
      enum: [USD, EUR, GBP]
    Address:
      type: object
      required: [street, city, country, postalCode]
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postalCode:
          type: string

\n

Generating Protocol-Specific Functions​

\n

Create a configuration file to generate protocol-specific functions:

\n
// codegen.config.js
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-event-channels.yaml',
  generators: [
    {
      preset: 'channels',
      outputPath: './src/generated',
      language: 'typescript',
      protocols: ['nats', 'kafka']
    }
  ]
};
\n
\n

📁 See the complete configuration: codegen.config.js

\n
\n

Run the generator:

\n
npx @the-codegen-project/cli generate codegen.config.js
\n
\n

💡 Automatic Dependencies: The channels generator automatically includes the payloads and parameters generators, so you get complete type-safe models alongside your protocol functions.

\n
\n

This generates a single file with protocol-specific functions organized by protocol. The function names are based on your operation names from the AsyncAPI specification:

\n
// Generated: src/generated/index.ts
import { OrderCreated } from './payload/OrderCreated';
import { OrderUpdated } from './payload/OrderUpdated';
import { OrderCancelled } from './payload/OrderCancelled';
import * as SubscribeToOrderEventsPayloadModule from './payload/SubscribeToOrderEventsPayload';
import { OrderLifecycleParameters } from './parameter/OrderLifecycleParameters';
import * as Nats from 'nats';
import * as Kafka from 'kafkajs';

export const Protocols = {
  nats: {
    // NATS-specific functions for order operations
    publishToPublishOrderCreated: ({
      message, 
      parameters, 
      nc, 
      codec = Nats.JSONCodec(), 
      options
    }: {
      message: OrderCreated, 
      parameters: OrderLifecycleParameters, 
      nc: Nats.NatsConnection, 
      codec?: Nats.Codec<any>, 
      options?: Nats.PublishOptions
    }): Promise<void> => {
      // Implementation handles validation, serialization
    },

    publishToPublishOrderUpdated: (...): Promise<void> => {
      // Implementation handles validation, serialization
    },

    publishToPublishOrderCancelled: (...): Promise<void> => {
      // Implementation handles validation, serialization
    },

    // JetStream support
    jetStreamPublishToPublishOrderCreated: (...): Promise<void> => {
      // Implementation handles validation, serialization
    },

    // Subscription functions with callback-based API
    subscribeToSubscribeToOrderEvents: (...): Promise<Nats.Subscription> => {
      // Implementation handles validation, deserialization, and callback invocation
    },

    // JetStream subscription support
    jetStreamPullSubscribeToSubscribeToOrderEvents: (...): Promise<Nats.JetStreamPullSubscription> => {
      // Implementation handles validation, deserialization, and callback invocation
    }
  },

  kafka: {
    // Kafka-specific functions for order operations  
    produceToPublishOrderCreated: ({
      message, 
      parameters, 
      kafka
    }: {
      message: OrderCreated, 
      parameters: OrderLifecycleParameters, 
      kafka: Kafka.Kafka
    }): Promise<Kafka.Producer> => {
      // Implementation handles validation, serialization
    },

    produceToPublishOrderUpdated: (...): Promise<Kafka.Producer> => {
      // Implementation handles validation, serialization
    },

    produceToPublishOrderCancelled: (...): Promise<Kafka.Producer> => {
      // Implementation handles validation, serialization
    },

    // Kafka consumer functions with callback-based API
    consumeFromSubscribeToOrderEvents: (...): Promise<Kafka.Consumer> => {
      // Implementation handles topic subscription, validation, and callback invocation
    }
  }
};
\n

Using Generated Functions in Your Services​

\n

Now you can use these protocol-specific functions to build robust order management services:

\n

Order Service with NATS​

\n
import { connect } from 'nats';
import { Protocols } from './generated';
import { OrderCreated } from './generated/payload/OrderCreated';
import { OrderUpdated } from './generated/payload/OrderUpdated';
import { OrderCancelled } from './generated/payload/OrderCancelled';
import { OrderLifecycleParameters } from './generated/parameter/OrderLifecycleParameters';

const { nats } = Protocols;

class OrderService {
  private connection!: NatsConnection;

  async initialize() {
    this.connection = await connect({ servers: 'nats://localhost:4222' });
    await this.setupEventHandlers();
  }

  async createOrder(orderData: CreateOrderRequest): Promise<Order> {
    // Create the order
    const order = await this.repository.createOrder(orderData);

    // Publish order created event using generated function
    const orderCreatedMessage = new OrderCreated({
      orderId: order.id,
      customerId: order.customerId,
      items: order.items,
      totalAmount: order.totalAmount,
      shippingAddress: order.shippingAddress,
      createdAt: new Date().toISOString()
    });

    const orderCreatedParams = new OrderLifecycleParameters({ action: 'created' });

    await nats.publishToPublishOrderCreated({
      message: orderCreatedMessage,
      parameters: orderCreatedParams,
      nc: this.connection
    });

    return order;
  }

  async updateOrderStatus(orderId: string, status: string): Promise<void> {
    await this.repository.updateOrderStatus(orderId, status);

    // Publish order updated event
    const orderUpdatedMessage = new OrderUpdated({
      orderId,
      status,
      updatedAt: new Date().toISOString(),
      reason: `Status changed to ${status}`,
      updatedFields: ['status']
    });

    const orderUpdatedParams = new OrderLifecycleParameters({ action: 'updated' });

    await nats.publishToPublishOrderUpdated({
      message: orderUpdatedMessage,
      parameters: orderUpdatedParams,
      nc: this.connection
    });
  }

  async cancelOrder(orderId: string, reason: string): Promise<void> {
    const order = await this.repository.getOrder(orderId);
    await this.repository.cancelOrder(orderId);

    // Publish order cancelled event
    const orderCancelledMessage = new OrderCancelled({
      orderId,
      reason,
      cancelledAt: new Date().toISOString(),
      refundAmount: order.totalAmount
    });

    const orderCancelledParams = new OrderLifecycleParameters({ action: 'cancelled' });

    await nats.publishToPublishOrderCancelled({
      message: orderCancelledMessage,
      parameters: orderCancelledParams,
      nc: this.connection
    });
  }

  private async setupEventHandlers(): Promise<void> {
    // Subscribe to all order events for logging and monitoring
    const orderEventsParams = new OrderLifecycleParameters({ action: 'created' });
    await nats.subscribeToSubscribeToOrderEvents({
      onDataCallback: (err, message, parameters, natsMsg) => {
        if (err) {
          console.error('[Handler] Error processing order event:', err.message);
          return;
        }
        this.handleOrderEvent(message, parameters);
      },
      parameters: orderEventsParams,
      nc: this.connection
    });
  }

  private async handleOrderEvent(message: any, parameters: OrderLifecycleParameters): Promise<void> {
    console.log(`[OrderService] Received order event: ${parameters.action}`, message);
    
    // Add business logic here (logging, analytics, etc.)
    switch (parameters.action) {
      case 'created':
        await this.handleOrderCreated(message);
        break;
      case 'updated':
        await this.handleOrderUpdated(message);
        break;
      case 'cancelled':
        await this.handleOrderCancelled(message);
        break;
    }
  }

  private async handleOrderCreated(message: any): Promise<void> {
    console.log(`[OrderService] Order created: ${message.orderId}`);
    // Send welcome email, trigger fulfillment, etc.
  }

  private async handleOrderUpdated(message: any): Promise<void> {
    console.log(`[OrderService] Order updated: ${message.orderId} -> ${message.status}`);
    // Update customer, send notifications, etc.
  }

  private async handleOrderCancelled(message: any): Promise<void> {
    console.log(`[OrderService] Order cancelled: ${message.orderId}`);
    // Process refund, send cancellation email, etc.
  }
}
\n

Warehouse Service with Kafka​

\n
import { Kafka } from 'kafkajs';
import { Protocols } from './generated';
import { OrderUpdated } from './generated/payload/OrderUpdated';
import { OrderLifecycleParameters } from './generated/parameter/OrderLifecycleParameters';

const { kafka } = Protocols;

class WarehouseService {
  private kafkaClient!: Kafka;

  async initialize() {
    this.kafkaClient = new Kafka({
      clientId: 'warehouse-service',
      brokers: ['localhost:9092']
    });
    
    await this.setupEventHandlers();
  }

  async setupEventHandlers(): Promise<void> {
    // Subscribe to order creation events to trigger fulfillment
    const orderCreatedParams = new OrderLifecycleParameters({ action: 'created' });
    await kafka.consumeFromSubscribeToOrderEvents({
      onDataCallback: (err, message, parameters, kafkaMsg) => {
        if (err) {
          console.error('[Warehouse] Error processing order event:', err.message);
          return;
        }
        if (parameters?.action === 'created') {
          this.handleOrderCreated(message);
        }
      },
      parameters: orderCreatedParams,
      kafka: this.kafkaClient,
      options: { fromBeginning: true, groupId: 'warehouse-service' }
    });
  }

  private async handleOrderCreated(message: any): Promise<void> {
    console.log(`[Warehouse] Processing order for fulfillment: ${message.orderId}`);
    
    // Check inventory, allocate items, etc.
    const fulfillmentResult = await this.processFulfillment(message);
    
    if (fulfillmentResult.success) {
      // Update order status to processing
      const orderUpdatedMessage = new OrderUpdated({
        orderId: message.orderId,
        status: 'processing',
        updatedAt: new Date().toISOString(),
        reason: 'Items allocated and processing started',
        updatedFields: ['status']
      });

      const orderUpdatedParams = new OrderLifecycleParameters({ action: 'updated' });

      await kafka.produceToPublishOrderUpdated({
        message: orderUpdatedMessage,
        parameters: orderUpdatedParams,
        kafka: this.kafkaClient
      });
    }
  }

  private async processFulfillment(order: any): Promise<{success: boolean}> {
    // Warehouse fulfillment logic
    console.log(`[Warehouse] Allocating inventory for order ${order.orderId}`);
    return { success: true };
  }
}
\n

Advanced Protocol Features​

\n

NATS JetStream Integration​

\n
import { connect, jetstreamManager } from 'nats';
import { Protocols } from './generated';

const { nats } = Protocols;

class OrderOrchestrator {
  private connection!: NatsConnection;
  private jetStream!: any;

  async initialize() {
    this.connection = await connect({ servers: 'nats://localhost:4222' });
    const jsm = await jetstreamManager(this.connection);
    this.jetStream = this.connection.jetstream();
    
    // Create stream for order events
    await jsm.streams.add({
      name: 'ORDER_EVENTS',
      subjects: ['orders.*'],
      retention: 'limits',
      max_age: 7 * 24 * 60 * 60 * 1000_000_000 // 7 days in nanoseconds
    });
  }

  async orchestrateOrderFlow(order: OrderCreated): Promise<void> {
    const orderCreatedParams = new OrderLifecycleParameters({ action: 'created' });

    // Publish to JetStream for durability
    await nats.jetStreamPublishToPublishOrderCreated({
      message: order,
      parameters: orderCreatedParams,
      js: this.jetStream
    });

    // Set up durable subscription for processing
    await nats.jetStreamPullSubscribeToSubscribeToOrderEvents({
      onDataCallback: (err, message, parameters, natsMsg) => {
        if (err) {
          console.error('[JetStream] Error processing order event:', err.message);
          return;
        }
        this.processOrderEvent(message);
      },
      parameters: orderCreatedParams,
      js: this.jetStream,
      options: { durable_name: 'order-processor' }
    });
  }
}
\n

Multi-Protocol Support​

\n
import { Protocols } from './generated';

const { nats, kafka } = Protocols;

class HybridOrderService {
  private natsConnection!: NatsConnection;
  private kafkaClient!: Kafka;

  // Use NATS for real-time order updates
  async publishRealTimeOrderUpdate(event: OrderUpdated) {
    const params = new OrderLifecycleParameters({ action: 'updated' });
    await nats.publishToPublishOrderUpdated({
      message: event,
      parameters: params,
      nc: this.natsConnection
    });
  }

  // Use Kafka for order analytics and reporting
  async publishOrderAnalytics(event: OrderCreated) {
    const params = new OrderLifecycleParameters({ action: 'created' });
    await kafka.produceToPublishOrderCreated({
      message: event,
      parameters: params,
      kafka: this.kafkaClient
    });
  }
}
\n

Configuration Options​

\n

The channels generator provides several options to customize the generated functions:

\n

Reverse Operations for Testing​

\n

In case you wish to generate the reverse operations for, usually great for integration or system testing:

\n
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-event-channels.yaml',
  generators: [
    {
      preset: 'channels',
      outputPath: './src/generated',
      language: 'typescript',
      protocols: ['nats'],
      // Reverse operations - send becomes receive and vice versa
      asyncapiReverseOperations: true
    }
  ]
};
\n

Custom Function Types​

\n

Instead of relying on operations, you can also use the configuration file to define explicitly what protocol functions to include.

\n
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-event-channels.yaml',
  generators: [
    {
      preset: 'channels',
      outputPath: './src/generated',
      language: 'typescript',
      protocols: ['nats'],
      // Generate for channels and ignore operations
      asyncapiGenerateForOperations: false,
      // Generate specific function types for channels
      functionTypeMapping: {
        'order-lifecycle': ['nats_publish', 'kafka_publish']
      }
    }
  ]
};
\n

Benefits of This Approach​

\n
    \n
  1. Protocol Abstraction: Clean, consistent APIs across different messaging systems
    2. \n
  2. Type Safety: Full TypeScript support with compile-time validation
    3. \n
  3. Parameter Handling: Automatic construction of channel addresses with parameters using getChannelWithParameters()
    4. \n
  4. Payload Integration: Seamless integration with generated payload models using marshal() and unmarshal()
    5. \n
  5. Protocol Flexibility: Use the same AsyncAPI spec with multiple protocols
    6. \n
  6. Infrastructure Freedom: Integrate with existing connections and configurations
    7. \n
  7. Operation-Based: Generate functions based on your defined operations with descriptive names
    8. \n
  8. Runtime Validation: Built-in message validation with error handling
    9. \n
  9. Callback-Based APIs: Event-driven architecture with error-first callbacks
    10. \n
\n

Conclusion​

\n

By generating protocol-specific functions from your AsyncAPI specification, you create clean abstractions over complex messaging systems. These functions handle parameter substitution, type safety, protocol-specific integration patterns, and runtime validation automatically.

\n

The generated functions work seamlessly with popular messaging systems like NATS, Kafka, MQTT, and AMQP, providing consistent APIs regardless of your chosen protocol. Combined with automatic payload and parameter generation, you get a complete messaging solution that evolves with your API specifications.

\n

Ready to try it yourself? Check out the channels generator documentation and start building your protocol-specific messaging functions today!

\n

Try It Yourself​

\n

Want to see this in action? Clone our ecommerce-asyncapi-channels example and run:

\n
cd examples/ecommerce-asyncapi-channels
npm install
npm run generate
npm run demo
\n

This will generate the protocol-specific functions and run a comprehensive demonstration showing how they work with NATS, Kafka, and other messaging systems.

\n

Additional Resources​

\n

Documentation​

\n", "url": "https://the-codegen-project.org/blog/asyncapi-channel-generator", "title": "AsyncAPI - Protocol-Specific Messaging Functions", "summary": "Building scalable event-driven applications requires robust messaging infrastructure that works seamlessly with your chosen protocols. We've covered payload generation, header management, and type-safe routing. Now let's explore how The Codegen Project's channels generator creates protocol-specific functions that streamline your messaging architecture while working with your favorite messaging systems.", "date_modified": "2025-07-08T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Channels", "TypeScript", "Messaging", "Protocols", "Automation" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-parameters-generator", "content_html": "

Building event-driven applications often requires dynamic channel routing based on parameters like user IDs, tenant identifiers, or resource keys. Manually constructing these parameterized channels is error-prone and makes your code fragile. We've explored generating payload models, headers, and type-safe channels. Now let's see how The Codegen Project's parameters generator creates type-safe models for dynamic channel construction.

\n

The Problem: Manual Channel Parameter Management​

\n

In event-driven e-commerce systems, you typically have parameterized channels for different resources:

\n
// Without type safety - error-prone manual construction
const orderChannel = `orders.${orderId}.events`;
const userChannel = `users.${userId}.notifications`;
const tenantChannel = `tenants.${tenantId}.${region}.updates`;
const inventoryChannel = `inventory.${warehouseId}.${productId}.updates`;

// What happens when parameters are missing or wrong?
const brokenChannel = `orders..events`;  // Empty orderId!
const wrongChannel = `orders.${userId}.events`;  // Wrong parameter!
const malformedChannel = `inventory.${warehouseId}.updates`; // Missing productId!
\n

This leads to several problems:

\n
    \n
  1. Runtime Failures: Missing or wrong parameters create invalid channels that fail silently
    2. \n
  2. No Validation: No way to ensure parameters match the expected format or constraints
    3. \n
  3. Hard to Extract: Parsing parameters from received channel names is manual and error-prone
    4. \n
  4. Maintenance Burden: Channel structure changes require updates throughout the codebase
    5. \n
  5. Type Safety: No compile-time checking for parameter correctness
    6. \n
  6. Documentation Drift: Parameter requirements aren't self-documenting in code
    7. \n
\n

The Solution: Generated Parameter Models​

\n

The Codegen Project's parameters preset generates TypeScript classes that handle parameter validation, channel construction, and parameter extraction automatically from your AsyncAPI specification.

\n

Real-World Example: E-commerce Messaging System​

\n

Let's build parameter models for a comprehensive e-commerce parameter system. Here's our AsyncAPI specification (ecommerce-messaging-system.yaml):

\n
\n

💡 Complete Example: You can find the full working example, including all files mentioned in this post, in our ecommerce-parameters example.

\n
\n
Show me the AsyncAPI document!

asyncapi: 3.0.0
info:
  title: E-commerce Messaging System
  version: 1.0.0
  description: Event-driven e-commerce system with comprehensive parameter handling for dynamic channel routing

channels:
  # Order Management - Multiple parameters
  order-events:
    address: 'ecommerce.orders.{orderId}.{eventType}'
    description: Order-specific events with event type classification
    parameters:
      orderId:
        description: Unique order identifier (UUID format)
        examples: ['123e4567-e89b-12d3-a456-426614174000']
      eventType:
        description: Type of order event
        enum: [created, updated, shipped, delivered, cancelled, refunded]
    messages:
      OrderEvent:
        payload:
          type: object
          properties:
            orderId: { type: string }
            eventType: { type: string }
            timestamp: { type: string, format: date-time }

  # User Management - Hierarchical parameters
  user-notifications:
    address: 'ecommerce.users.{region}.{userId}.{notificationType}'
    description: User notifications with regional routing
    parameters:
      region:
        description: Geographic region for routing
        enum: [us-east, us-west, eu-central, ap-southeast]
      userId:
        description: User identifier (UUID format)
        examples: ['987fcdeb-51a2-43d1-9c4f-123456789abc']
      notificationType:
        description: Type of notification
        enum: [email, sms, push, webhook]
    messages:
      UserNotification:
        payload:
          type: object
          properties:
            userId: { type: string }
            message: { type: string }
            notificationType: { type: string }

  # Product Management - Category-based routing
  product-updates:
    address: 'ecommerce.products.{category}.{productId}.updates'
    description: Product updates organized by category
    parameters:
      category:
        description: Product category for efficient routing
        enum: [electronics, clothing, books, home, sports]
      productId:
        description: Product identifier (format PROD-XXXXXXXX)
        examples: ['PROD-12AB34CD']
    messages:
      ProductUpdate:
        payload:
          type: object
          properties:
            productId: { type: string }
            category: { type: string }
            changes: { type: object }

  # Multi-tenant Analytics - Complex parameter structure
  tenant-analytics:
    address: 'analytics.{tenantId}.{environmentType}.{metricType}.{aggregationPeriod}'
    description: Multi-dimensional analytics with tenant isolation
    parameters:
      tenantId:
        description: Tenant identifier for data isolation (format tenant-xxxxxxxx)
        examples: ['tenant-abc123', 'tenant-xyz789def']
      environmentType:
        description: Environment for proper data segregation
        enum: [production, staging, development]
      metricType:
        description: Type of metric being tracked
        enum: [sales, inventory, user-behavior, performance]
      aggregationPeriod:
        description: Time period for metric aggregation
        enum: [minute, hour, day, week, month]
    messages:
      AnalyticsEvent:
        payload:
          type: object
          properties:
            tenantId: { type: string }
            metricType: { type: string }
            value: { type: number }
            timestamp: { type: string, format: date-time }

  # Inventory Management - Location-based parameters
  inventory-updates:
    address: 'inventory.{warehouseId}.{zone}.{productId}'
    description: Inventory updates with precise location tracking
    parameters:
      warehouseId:
        description: Warehouse identifier (format WH-XX-000)
        examples: ['WH-US-001', 'WH-EU-042']
      zone:
        description: Zone within warehouse (format X-00)
        examples: ['A-01', 'B-15', 'C-23']
      productId:
        description: Product being updated (format PROD-XXXXXXXX)
        examples: ['PROD-12AB34CD']
    messages:
      InventoryUpdate:
        payload:
          type: object
          properties:
            warehouseId: { type: string }
            zone: { type: string }
            productId: { type: string }
            quantityChange: { type: integer }

  # Customer Support - Priority-based routing
  support-tickets:
    address: 'support.{priority}.{department}.{ticketId}'
    description: Support tickets with priority and department routing
    parameters:
      priority:
        description: Ticket priority for routing
        enum: [low, medium, high, critical]
      department:
        description: Support department
        enum: [technical, billing, general, returns]
      ticketId:
        description: Support ticket identifier (format TICKET-00000000)
        examples: ['TICKET-12345678']
    messages:
      SupportTicket:
        payload:
          type: object
          properties:
            ticketId: { type: string }
            priority: { type: string }
            department: { type: string }
            description: { type: string }

  # Simple parameter example
  user-activity:
    address: 'activity.{userId}'
    description: Simple user activity tracking
    parameters:
      userId:
        description: User performing the activity (UUID format)
        examples: ['550e8400-e29b-41d4-a716-446655440000']
    messages:
      UserActivity:
        payload:
          type: object
          properties:
            userId: { type: string }
            action: { type: string }
            timestamp: { type: string, format: date-time }

\n

Generating the Parameter Models​

\n

Create a configuration file to generate TypeScript parameter models:

\n
// codegen.config.js
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-messaging-system.yaml',
  generators: [
    {
      preset: 'parameters',
      outputPath: './src/generated/parameters',
      language: 'typescript',
    }
  ]
};
\n
\n

📁 See the complete configuration: codegen.config.js

\n
\n

Run the generator:

\n
npx @the-codegen-project/cli generate codegen.config.js
\n

This generates TypeScript classes for each channel's parameters with built-in channel construction and parameter extraction:

\n
// Generated: src/generated/parameters/OrderEventsParameters.ts
import { EventType } from './EventType';

export class OrderEventsParameters {
  private _orderId: string;
  private _eventType: EventType;

  constructor(input: {
    orderId: string,
    eventType: EventType,
  }) {
    this._orderId = input.orderId;
    this._eventType = input.eventType;
  }

  /**
   * Unique order identifier (UUID format)
   * @example 123e4567-e89b-12d3-a456-426614174000
   */
  get orderId(): string { return this._orderId; }
  set orderId(orderId: string) { this._orderId = orderId; }

  /**
   * Type of order event
   */
  get eventType(): EventType { return this._eventType; }
  set eventType(eventType: EventType) { this._eventType = eventType; }

  /**
   * Realize the channel/topic with the parameters added to this class.
   */
  public getChannelWithParameters(channel: string): string {
    // Implementation
  }
  
  /**
   * Extract parameters from a channel name using regex pattern matching
   */
  public static createFromChannel(msgSubject: string, channel: string, regex: RegExp): OrderEventsParameters {
    // Implementation
  }
}
\n

Using Generated Parameter Models in Your Infrastructure​

\n

Now you can use these generated parameter models with any messaging infrastructure for dynamic channel routing:

\n

With NATS​

\n
import { connect } from 'nats';
import { OrderEventsParameters } from './generated/parameters/OrderEventsParameters';
import { InventoryUpdatesParameters } from './generated/parameters/InventoryUpdatesParameters';
import { EventType } from './generated/parameters/EventType';

const nc = await connect({ servers: 'nats://localhost:4222' });

// Publishing to dynamic channels with type-safe parameters
async function publishOrderEvent(orderId: string, eventType: EventType, payload: any) {
  const params = new OrderEventsParameters({ orderId, eventType });
  const channelTemplate = 'ecommerce.orders.{orderId}.{eventType}';
  const channelName = params.getChannelWithParameters(channelTemplate);
  // Result: \"ecommerce.orders.123e4567-e89b-12d3-a456-426614174000.created\"
  
  await nc.publish(channelName, JSON.stringify(payload));
}

// Subscribing with wildcard patterns and parameter extraction
const orderSub = nc.subscribe('ecommerce.orders.*.>');
for await (const msg of orderSub) {
  try {
    // Extract parameters from received channel
    const regex = /^ecommerce\\.orders\\.([^.]+)\\.([^.]+)$/;
    const channelTemplate = 'ecommerce.orders.{orderId}.{eventType}';
    const params = OrderEventsParameters.createFromChannel(msg.subject, channelTemplate, regex);
    
    console.log(`Processing ${params.eventType} event for order: ${params.orderId}`);
    await processOrderEvent(params.orderId, params.eventType, msg.data);
  } catch (error) {
    console.error('Failed to extract parameters:', error.message);
  }
}
\n

With Kafka​

\n
import { Kafka } from 'kafkajs';
import { OrderEventsParameters } from './generated/parameters/OrderEventsParameters';
import { EventType } from './generated/parameters/EventType';

const kafka = new Kafka({ clientId: 'order-service', brokers: ['localhost:9092'] });
const producer = kafka.producer();

async function publishOrderStatusChange(orderId: string, eventType: EventType, payload: any) {
  const params = new OrderEventsParameters({ orderId, eventType });
  const channel = 'ecommerce_orders_{orderId}_{eventType}';
  const channelName = params.getChannelWithParameters(channelTemplate);
  
  await producer.send({
    topic: channel,
    messages: [{
      key: orderId,
      value: JSON.stringify(payload),
      // Store original channel name for parameter extraction
      headers: {
        'x-channel-name': Buffer.from(channelName),
        'x-order-id': Buffer.from(orderId),
        'x-event-type': Buffer.from(eventType)
      }
    }]
  });
}

// Consumer with parameter extraction
const consumer = kafka.consumer({ groupId: 'order-processor' });
await consumer.run({
  eachMessage: async ({ topic, message }) => {
    try {
      // Extract parameters from headers or reconstruct from topic name
      const channelName = message.headers?.['x-channel-name']?.toString()
      
      const regex = /^ecommerce\\.orders\\.([^.]+)\\.([^.]+)$/;
      const channelTemplate = 'ecommerce_orders_{orderId}_{eventType}';
      const params = OrderEventsParameters.createFromChannel(channelName, channelTemplate, regex);
      
      await processOrderEvent(params.orderId, params.eventType, message.value);
    } catch (error) {
      console.error('Failed to extract parameters from Kafka message:', error.message);
    }
  }
});
\n

Practical Examples from Our Demo​

\n

Here are some real examples from our working demonstration that show the generated parameter models in action:

\n

Order Processing Pipeline​

\n
import { OrderEventsParameters } from './generated/parameters/OrderEventsParameters';
import { EventType } from './generated/parameters/EventType';

// Process order through its lifecycle with type-safe parameters
async function processOrderLifecycle(orderId: string) {
  const orderEvents: EventType[] = ['created', 'updated', 'shipped', 'delivered'];
  const orderChannelTemplate = 'ecommerce.orders.{orderId}.{eventType}';
  
  for (const eventType of orderEvents) {
    const params = new OrderEventsParameters({ orderId, eventType });
    const channel = params.getChannelWithParameters(orderChannelTemplate);
    
    console.log(`Step ${orderEvents.indexOf(eventType) + 1}: ${channel}`);
    await publishOrderEvent(channel, { orderId, eventType, timestamp: new Date() });
  }
}

// Extract parameters from received order events
async function handleOrderEvent(channelName: string, message: any) {
  try {
    const regex = /^ecommerce\\.orders\\.([^.]+)\\.([^.]+)$/;
    const channelTemplate = 'ecommerce.orders.{orderId}.{eventType}';
    const params = OrderEventsParameters.createFromChannel(channelName, channelTemplate, regex);
    
    console.log(`Processing ${params.eventType} event for order: ${params.orderId}`);
    
    // Route to appropriate handler based on event type
    switch (params.eventType) {
      case 'created':
        await processNewOrder(params.orderId, message);
        break;
      case 'shipped':
        await notifyCustomerShipped(params.orderId, message);
        break;
      case 'delivered':
        await finalizeOrder(params.orderId, message);
        break;
    }
  } catch (error) {
    console.error('Failed to process order event:', error.message);
  }
}
\n

Error Handling and Parameter Extraction​

\n
// Safe parameter extraction with comprehensive error handling
async function safeProcessMessage(channelName: string, message: any) {
  // Try to extract order parameters
  try {
    const orderRegex = /^ecommerce\\.orders\\.([^.]+)\\.([^.]+)$/;
    if (orderRegex.test(channelName)) {
      const params = OrderEventsParameters.createFromChannel(
        channelName, 
        'ecommerce.orders.{orderId}.{eventType}', 
        orderRegex
      );
      return await processOrderEvent(params, message);
    }
  } catch (error) {
    console.warn('Not an order event, trying other patterns...');
  }
  
  // Try to extract notification parameters
  try {
    const notificationRegex = /^ecommerce\\.users\\.([^.]+)\\.([^.]+)\\.([^.]+)$/;
    if (notificationRegex.test(channelName)) {
      const params = UserNotificationsParameters.createFromChannel(
        channelName,
        'ecommerce.users.{region}.{userId}.{notificationType}',
        notificationRegex
      );
      return await processNotification(params, message);
    }
  } catch (error) {
    console.warn('Not a notification event, trying other patterns...');
  }
  
  console.error(`Unknown channel pattern: ${channelName}`);
}
\n

Conclusion​

\n

By generating parameter models from your AsyncAPI specification, you eliminate the fragility and errors that come with manual channel construction. This approach provides type-safe, that scales with your application's complexity.

\n

Whether you're building simple user notification systems or complex multi-tenant analytics platforms, generated parameter models ensure your channel routing is reliable, type-safe, and maintainable.

\n

Try It Yourself​

\n

Want to see this in action? Checkout the ecommerce-parameters example and run:

\n
cd examples/ecommerce-asyncapi-parameters
npm install
npm run generate
npm run demo
\n

This will generate the parameter models and run a comprehensive demonstration showing how they handle complex channel parameterization, validation, and extraction patterns.

\n

Additional Resources​

\n

Documentation​

\n\n

Related Protocols​

\n\n

Related Generators​

\n", "url": "https://the-codegen-project.org/blog/asyncapi-parameters-generator", "title": "AsyncAPI - Dynamic Channel Routing Made Type-Safe", "summary": "Building event-driven applications often requires dynamic channel routing based on parameters like user IDs, tenant identifiers, or resource keys. Manually constructing these parameterized channels is error-prone and makes your code fragile. We've explored generating payload models, headers, and type-safe channels. Now let's see how The Codegen Project's parameters generator creates type-safe models for dynamic channel construction.", "date_modified": "2025-07-01T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Parameters", "TypeScript", "Channels", "Routing" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-types-generator", "content_html": "

Building event-driven applications with multiple channels often leads to a common but critical problem: hardcoded channel names scattered throughout your codebase. One typo in a channel name can send events to the wrong destination or create silent failures. We've already explored generating models for payloads and headers. Now let's see how The Codegen Project's types generator provides compile-time safety for all your channel routing.

\n

The Problem: Channel Name Chaos​

\n

In event-driven e-commerce systems, you typically have numerous channels for different business domains:

\n
// Without type safety - error-prone hardcoded strings
await publisher.publish('order.created', orderData);
await publisher.publish('order-events', statusUpdate);     // Oops! Wrong format
await publisher.publish('inventory.updated', stockData);   // Different from spec
\n

This leads to several problems:

\n
    \n
  1. Runtime Failures: Typos in channel names cause events to be lost
    2. \n
  2. Hard to Refactor: Changing channel names requires hunting through the entire codebase
    3. \n
  3. No IDE Support: No autocomplete or compile-time validation for channel names
    4. \n
\n

The Solution: Generated Channel Types​

\n

The Codegen Project's types preset generates TypeScript types and utilities that ensure you can only reference channels that actually exist in your AsyncAPI specification.

\n

Real-World Example: E-commerce Event Routing​

\n

Let's build a type-safe channel routing system for an e-commerce platform. Here's our AsyncAPI specification (ecommerce-channels.yaml):

\n
\n

💡 Complete Example: You can find the full working example, including all files mentioned in this post, in our ecommerce-types example.

\n
\n
Show me the AsyncAPI document!

asyncapi: 3.0.0
info:
  title: E-commerce Event Channels
  version: 1.0.0
  description: Channel definitions for e-commerce event routing

channels:
  order-events:
    address: 'ecommerce.orders.{orderId}'
    description: Order lifecycle events
    parameters:
      orderId:
        description: The order identifier
    messages:
      OrderCreated:
        name: OrderCreated
        title: Order Created
        summary: Fired when a new order is created
        payload:
          type: object
          properties:
            orderId:
              type: string
              format: uuid
            customerId:
              type: string
              format: uuid
            totalAmount:
              type: number
      OrderUpdated:
        name: OrderUpdated
        title: Order Updated
        summary: Fired when order details are modified
        payload:
          type: object
          properties:
            orderId:
              type: string
              format: uuid
            changes:
              type: object

  payment-events:
    address: 'ecommerce.payments.{paymentId}'
    description: Payment processing events
    parameters:
      paymentId:
        description: The payment identifier
    messages:
      PaymentProcessed:
        name: PaymentProcessed
        title: Payment Processed
        summary: Fired when payment is successfully processed
        payload:
          type: object
          properties:
            paymentId:
              type: string
              format: uuid
            orderId:
              type: string
              format: uuid
            amount:
              type: number
      PaymentFailed:
        name: PaymentFailed
        title: Payment Failed
        summary: Fired when payment processing fails
        payload:
          type: object
          properties:
            paymentId:
              type: string
              format: uuid
            orderId:
              type: string
              format: uuid
            reason:
              type: string

  inventory-events:
    address: 'ecommerce.inventory.{productId}'
    description: Product inventory changes
    parameters:
      productId:
        description: The product identifier
    messages:
      StockUpdated:
        name: StockUpdated
        title: Stock Updated
        summary: Fired when product stock levels change
        payload:
          type: object
          properties:
            productId:
              type: string
            oldQuantity:
              type: integer
            newQuantity:
              type: integer

  customer-notifications:
    address: 'ecommerce.notifications.{customerId}'
    description: Customer notification events
    parameters:
      customerId:
        description: The customer identifier
    messages:
      NotificationSent:
        name: NotificationSent
        title: Notification Sent
        summary: Fired when a notification is sent to customer
        payload:
          type: object
          properties:
            customerId:
              type: string
              format: uuid
            type:
              type: string
              enum: [email, sms, push]
            message:
              type: string

  analytics-events:
    address: 'ecommerce.analytics.events'
    description: Business analytics and metrics
    messages:
      UserAction:
        name: UserAction
        title: User Action
        summary: Tracks user interactions and behaviors
        payload:
          type: object
          properties:
            userId:
              type: string
            action:
              type: string
            timestamp:
              type: string
              format: date-time
      ConversionEvent:
        name: ConversionEvent
        title: Conversion Event
        summary: Tracks conversion funnel events
        payload:
          type: object
          properties:
            sessionId:
              type: string
            event:
              type: string
            value:
              type: number

\n

Generating Type-Safe Channel Types​

\n

Create a configuration file to generate TypeScript channel types:

\n
// codegen.config.js
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-channels.yaml',
  generators: [
    {
      preset: 'types',
      outputPath: './src/generated/types',
      language: 'typescript',
    }
  ]
};
\n
\n

📁 See the complete configuration: codegen.config.js

\n
\n

Run the generator:

\n
npx @the-codegen-project/cli generate codegen.config.js
\n

This generates TypeScript types and utility functions:

\n
// Generated: src/generated/types/Types.ts
export type Topics = 'ecommerce.orders.{orderId}' | 'ecommerce.payments.{paymentId}' | 'ecommerce.inventory.{productId}' | 'ecommerce.notifications.{customerId}' | 'ecommerce.analytics.events';
export type TopicIds = 'order-events' | 'payment-events' | 'inventory-events' | 'customer-notifications' | 'analytics-events';
export function ToTopicIds(topic: Topics): TopicIds {
  switch (topic) {
    case 'ecommerce.orders.{orderId}':
    return 'order-events';
  case 'ecommerce.payments.{paymentId}':
    return 'payment-events';
  case 'ecommerce.inventory.{productId}':
    return 'inventory-events';
  case 'ecommerce.notifications.{customerId}':
    return 'customer-notifications';
  case 'ecommerce.analytics.events':
    return 'analytics-events';
    default:
      throw new Error('Unknown topic: ' + topic);
  }
}
export function ToTopics(topicId: TopicIds): Topics {
  switch (topicId) {
    case 'order-events':
    return 'ecommerce.orders.{orderId}';
  case 'payment-events':
    return 'ecommerce.payments.{paymentId}';
  case 'inventory-events':
    return 'ecommerce.inventory.{productId}';
  case 'customer-notifications':
    return 'ecommerce.notifications.{customerId}';
  case 'analytics-events':
    return 'ecommerce.analytics.events';
    default:
      throw new Error('Unknown topic ID: ' + topicId);
  }
}
\n

Using Generated Types in Your Application​

\n

Now you can build type-safe event publishers and subscribers:

\n

Type-Safe Event Publisher​

\n
import { TopicIds, ToTopics } from './generated/types/Types';

export class EventPublisher {
  constructor(private messagingClient: any) {}

  async publish(topicId: TopicIds, data: any, parameters?: Record<string, string>) {
    let address = ToTopics(topicId);
    
    // Replace parameters in address template
    if (parameters) {
      for (const [key, value] of Object.entries(parameters)) {
        address = address.replace(`{${key}}`, value) as any;
      }
    }
    
    await this.messagingClient.publish(address, data);
  }
}

// Usage with compile-time safety
const publisher = new EventPublisher(messagingClient);

// ✅ These work - TypeScript validates channel names
await publisher.publish('order-events', orderData, { orderId: '123' });
await publisher.publish('payment-events', paymentData, { paymentId: 'pay-456' });
await publisher.publish('analytics-events', analyticsData);

// ❌ This fails at compile time - unknown channel
await publisher.publish('unknown-channel', data); // TypeScript error!
\n

Type-Safe Event Router​

\n
import { TopicIds } from './generated/types/Types';

type EventHandler = (data: any) => Promise<void>;

export class EventRouter {
  private handlers = new Map<TopicIds, EventHandler[]>();

  register(topicId: TopicIds, handler: EventHandler) {
    if (!this.handlers.has(topicId)) {
      this.handlers.set(topicId, []);
    }
    this.handlers.get(topicId)!.push(handler);
  }

  async route(topicId: TopicIds, data: any) {
    const handlers = this.handlers.get(topicId) || [];
    await Promise.all(handlers.map(handler => handler(data)));
  }
}

// Usage
const router = new EventRouter();

// ✅ Type-safe handler registration
router.register('order-events', async (data) => {
  console.log('Processing order event:', data);
});

router.register('payment-events', async (data) => {
  console.log('Processing payment event:', data);
});

// ❌ This fails at compile time
router.register('invalid-channel', handler); // TypeScript error!
\n

Integration with Message Brokers​

\n

The generated types work seamlessly with any messaging infrastructure:

\n

With NATS​

\n
import { connect } from 'nats';
import { TopicIds, ToTopics } from './generated/types/Types';

class NATSEventService {
  constructor(private nc: any) {}

  async subscribe(topicId: TopicIds, handler: (data: any) => void) {
    const addressTemplate = ToTopics(topicId);
    // Convert template to NATS subject pattern
    const subject = addressTemplate.replace(/\\{[^}]+\\}/g, '*');
    
    const sub = this.nc.subscribe(subject);
    for await (const msg of sub) {
      const data = JSON.parse(msg.data.toString());
      handler(data);
    }
  }

  async publish(topicId: TopicIds, data: any, parameters: Record<string, string>) {
    let subject = ToTopics(topicId);
    for (const [key, value] of Object.entries(parameters)) {
      subject = subject.replace(`{${key}}`, value);
    }
    this.nc.publish(subject, JSON.stringify(data));
  }
}
\n

Advanced Use Cases​

\n

Environment-Specific Channel Mapping​

\n
import { TopicIds, ToTopics } from './generated/types/Types';

class EnvironmentAwarePublisher {
  private getEnvironmentPrefix(): string {
    return process.env.NODE_ENV === 'production' ? 'prod' : 'dev';
  }

  async publish(topicId: TopicIds, data: any, parameters?: Record<string, string>) {
    let address = ToTopics(topicId);
    
    // Add environment prefix
    const envPrefix = this.getEnvironmentPrefix();
    address = `${envPrefix}.${address}` as any;
    
    // Replace parameters
    if (parameters) {
      for (const [key, value] of Object.entries(parameters)) {
        address = address.replace(`{${key}}`, value) as any;
      }
    }
    
    await this.messagingClient.publish(address, data);
  }
}
\n

Channel Health Monitoring​

\n
import { TopicIds } from './generated/types/Types';

export class ChannelMonitor {
  private metrics = new Map<TopicIds, { published: number; errors: number }>();

  constructor() {
    // Initialize metrics for all known channels
    const channels: TopicIds[] = [
      'order-events', 
      'payment-events', 
      'inventory-events',
      'customer-notifications', 
      'analytics-events'
    ];
    
    channels.forEach(channel => {
      this.metrics.set(channel, { published: 0, errors: 0 });
    });
  }

  recordPublish(topicId: TopicIds) {
    const metric = this.metrics.get(topicId)!;
    metric.published++;
  }

  recordError(topicId: TopicIds) {
    const metric = this.metrics.get(topicId)!;
    metric.errors++;
  }

  getHealthReport() {
    const report: Record<string, any> = {};
    this.metrics.forEach((metric, topicId) => {
      report[topicId] = {
        published: metric.published,
        errors: metric.errors,
        errorRate: metric.published > 0 ? metric.errors / metric.published : 0
      };
    });
    return report;
  }
}
\n

Benefits of Generated Channel Types​

\n
    \n
  1. Compile-Time Safety: TypeScript catches channel name errors before runtime
    2. \n
  2. IDE Support: Full autocomplete and IntelliSense for channel names
    3. \n
  3. Refactoring Safety: Renaming channels in your spec automatically updates all usage
    4. \n
  4. Documentation: Channel types serve as living documentation of your event architecture
    5. \n
  5. Maintainability: Central source of truth for all channel definitions
    6. \n
\n

Conclusion​

\n

Channel routing errors are among the most frustrating bugs in event-driven systems - they're easy to introduce and hard to debug. By generating TypeScript types from your AsyncAPI specification, you can eliminate these errors entirely while gaining the benefits of IDE support and safer refactoring.

\n

The types generator creates a bridge between your API documentation and your implementation, ensuring they never drift apart. This small investment in code generation pays dividends in reduced debugging time and increased developer confidence.

\n

Ready to make your channel routing bulletproof? Check out the types generator documentation and start generating your channel types today!

\n

Try It Yourself​

\n

Want to see this in action? Clone our ecommerce-types example and run:

\n
cd examples/ecommerce-asyncapi-types
npm install
npm run generate
npm run demo
\n

This will generate the channel types and run a demonstration showing how they prevent common routing errors while providing excellent developer experience.

\n

Additional Resources​

\n

Documentation​

\n", "url": "https://the-codegen-project.org/blog/asyncapi-types-generator", "title": "AsyncAPI - Type safety Never Publish to Wrong Channels Again", "summary": "Building event-driven applications with multiple channels often leads to a common but critical problem: hardcoded channel names scattered throughout your codebase. One typo in a channel name can send events to the wrong destination or create silent failures. We've already explored generating models for payloads and headers. Now let's see how The Codegen Project's types generator provides compile-time safety for all your channel routing.", "date_modified": "2025-06-20T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Types", "TypeScript", "Channels", "Routing" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-headers-generator", "content_html": "

Building robust event-driven applications requires more than just payload validation - you need proper header management for authentication, tracing, routing, and metadata. In our previous post about payload generation, we showed how to generate type-safe data models. Now let's explore how The Codegen Project's headers generator can streamline your messaging infrastructure by handling the metadata side of your messages.

\n

The Problem: Manual Header Management​

\n

When building event-driven systems, message headers are crucial for:

\n
    \n
  1. Authentication & Authorization - JWT tokens, API keys, permission levels
    2. \n
  2. Distributed Tracing - Correlation IDs, request IDs, timestamps
    3. \n
  3. Message Routing - Tenant IDs, event types, priorities
    4. \n
  4. Metadata Management - Actor information, reason codes, audit trails
    5. \n
  5. Performance Optimization - Retry counts, idempotency keys, batch operations
    6. \n
\n

Managing these headers manually leads to:

\n\n

The Solution: Generated Header Models + Custom Infrastructure​

\n

The Codegen Project's headers preset generates type-safe TypeScript classes for your message headers, leaving you free to implement your messaging infrastructure however you prefer - whether that's NATS, Kafka, RabbitMQ, or HTTP APIs.

\n

Real-World Example: E-commerce Messaging System​

\n

Let's build header models for a comprehensive e-commerce messaging system. Here's our AsyncAPI specification (ecommerce-messaging-system.yaml):

\n
\n

💡 Complete Example: You can find the full working example, including all files mentioned in this post, in our ecommerce-headers example.

\n
\n
Show me the AsyncAPI document!

asyncapi: 3.0.0
info:
  title: E-commerce Messaging System
  version: 1.0.0
  description: Event-driven e-commerce system with comprehensive header management for authentication, tracing, routing, and metadata

channels:
  order-events:
    messages:
      OrderCreated:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/AuthHeaders'
            - $ref: '#/components/schemas/ServiceHeaders'
            - type: object
              required: [x-user-id]
              properties:
                x-user-id:
                  type: string
                  format: uuid
                  description: ID of the user who created the order
        payload:
          $ref: '#/components/schemas/OrderCreatedPayload'

      OrderStatusChanged:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/ActorHeaders'
            - type: object
              required: [x-event-type]
              properties:
                x-event-type:
                  $ref: '#/components/schemas/OrderEventType'
                x-previous-status:
                  $ref: '#/components/schemas/OrderStatus'
                x-reason-code:
                  $ref: '#/components/schemas/OrderReasonCode'
                x-priority:
                  $ref: '#/components/schemas/Priority'
        payload:
          $ref: '#/components/schemas/OrderStatusChangedPayload'

  payment-events:
    messages:
      PaymentProcessed:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/PaymentHeaders'
            - $ref: '#/components/schemas/SecurityHeaders'
        payload:
          $ref: '#/components/schemas/PaymentProcessedPayload'

  inventory-events:
    messages:
      InventoryUpdated:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/InventoryHeaders'
            - $ref: '#/components/schemas/AuditHeaders'
        payload:
          $ref: '#/components/schemas/InventoryUpdatedPayload'

  notification-events:
    messages:
      NotificationSent:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/NotificationHeaders'
            - $ref: '#/components/schemas/LocalizationHeaders'
        payload:
          $ref: '#/components/schemas/NotificationSentPayload'

  analytics-events:
    messages:
      UserBehaviorTracked:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/SessionHeaders'
            - $ref: '#/components/schemas/DeviceHeaders'
            - $ref: '#/components/schemas/PrivacyHeaders'
        payload:
          $ref: '#/components/schemas/UserBehaviorTrackedPayload'

  admin-events:
    messages:
      AdminActionPerformed:
        headers:
          allOf:
            - $ref: '#/components/schemas/CommonHeaders'
            - $ref: '#/components/schemas/AdminHeaders'
            - $ref: '#/components/schemas/SecurityHeaders'
            - $ref: '#/components/schemas/ComplianceHeaders'
        payload:
          $ref: '#/components/schemas/AdminActionPerformedPayload'

components:
  schemas:
    # Base header schemas
    CommonHeaders:
      type: object
      required: [x-correlation-id, x-tenant-id]
      properties:
        x-correlation-id:
          type: string
          format: uuid
          description: Unique correlation ID for request tracing
        x-tenant-id:
          type: string
          description: Multi-tenant identifier
        x-timestamp:
          type: string
          format: date-time
          description: Event creation timestamp

    AuthHeaders:
      type: object
      properties:
        authorization:
          type: string
          pattern: '^Bearer [A-Za-z0-9\\-\\._~\\+\\/]+=*$'
          description: JWT token for authentication

    ServiceHeaders:
      type: object
      properties:
        x-source-service:
          $ref: '#/components/schemas/SourceService'
        x-api-version:
          type: string
          pattern: '^v[0-9]+$'
          description: API version used
          default: v1
        x-request-id:
          type: string
          format: uuid
          description: Original request ID from the client

    ActorHeaders:
      type: object
      properties:
        x-actor-id:
          type: string
          format: uuid
          description: ID of user/system that triggered the change
        x-actor-type:
          $ref: '#/components/schemas/ActorType'

    PaymentHeaders:
      type: object
      required: [x-payment-provider]
      properties:
        x-payment-provider:
          $ref: '#/components/schemas/PaymentProvider'
        x-payment-method:
          $ref: '#/components/schemas/PaymentMethod'
        x-risk-score:
          type: number
          minimum: 0
          maximum: 100
          description: Fraud risk score (0-100)
        x-processor-transaction-id:
          type: string
          description: Transaction ID from payment processor
        x-retry-count:
          type: integer
          minimum: 0
          maximum: 5
          default: 0
          description: Number of retry attempts
        x-idempotency-key:
          type: string
          format: uuid
          description: Ensures payment processing idempotency

    SecurityHeaders:
      type: object
      properties:
        x-webhook-signature:
          type: string
          description: Webhook signature for verification
        x-ip-address:
          type: string
          format: ipv4
          description: IP address

    InventoryHeaders:
      type: object
      required: [x-warehouse-id]
      properties:
        x-warehouse-id:
          type: string
          description: Warehouse where inventory changed
        x-update-type:
          $ref: '#/components/schemas/InventoryUpdateType'
        x-batch-id:
          type: string
          format: uuid
          description: Batch ID for bulk operations
        x-location:
          type: string
          description: Specific location within warehouse

    AuditHeaders:
      type: object
      properties:
        x-operator-id:
          type: string
          format: uuid
          description: ID of person/system making the change
        x-audit-required:
          type: boolean
          default: false
          description: Whether this change requires audit

    NotificationHeaders:
      type: object
      required: [x-notification-type]
      properties:
        x-notification-type:
          $ref: '#/components/schemas/NotificationType'
        x-template-id:
          type: string
          description: Template used for notification
        x-channel-preference:
          $ref: '#/components/schemas/NotificationChannel'
        x-delivery-attempt:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Delivery attempt number
        x-scheduled-time:
          type: string
          format: date-time
          description: When notification was scheduled to be sent
        x-provider:
          $ref: '#/components/schemas/NotificationProvider'

    LocalizationHeaders:
      type: object
      properties:
        x-language:
          type: string
          pattern: '^[a-z]{2}(-[A-Z]{2})?$'
          description: Language code (e.g., en-US, fr-FR)
          default: en-US

    SessionHeaders:
      type: object
      required: [x-session-id]
      properties:
        x-session-id:
          type: string
          format: uuid
          description: User session identifier

    DeviceHeaders:
      type: object
      properties:
        x-user-agent:
          type: string
          description: Browser/app user agent string
        x-device-type:
          $ref: '#/components/schemas/DeviceType'
        x-platform:
          $ref: '#/components/schemas/Platform'

    PrivacyHeaders:
      type: object
      properties:
        x-ab-test-groups:
          type: array
          items:
            type: string
          description: A/B test groups user belongs to
        x-feature-flags:
          type: array
          items:
            type: string
          description: Active feature flags for user
        x-gdpr-consent:
          type: boolean
          description: Whether user has given GDPR consent
        x-data-retention-days:
          type: integer
          minimum: 1
          maximum: 2555
          default: 365
          description: How long to retain this data

    AdminHeaders:
      type: object
      required: [x-admin-id, x-action-type]
      properties:
        x-admin-id:
          type: string
          format: uuid
          description: ID of admin performing action
        x-action-type:
          $ref: '#/components/schemas/AdminActionType'
        x-permission-level:
          $ref: '#/components/schemas/PermissionLevel'
        x-audit-level:
          $ref: '#/components/schemas/AuditLevel'
        x-approval-required:
          type: boolean
          default: false
          description: Whether action requires approval
        x-approved-by:
          type: string
          format: uuid
          description: ID of approving admin (if applicable)

    ComplianceHeaders:
      type: object
      properties:
        x-compliance-tags:
          type: array
          items:
            type: string
          description: Compliance/regulatory tags

    # Enum schemas
    SourceService:
      type: string
      enum: [web-app, mobile-app, admin-panel]
      description: Service that originated the event

    ActorType:
      type: string
      enum: [user, system, admin]
      description: Type of actor that triggered the change

    OrderEventType:
      type: string
      enum: [status-change, cancellation, refund]
      description: Type of status change event

    OrderStatus:
      type: string
      enum: [pending, confirmed, processing, shipped, delivered, cancelled]
      description: Order status values

    OrderReasonCode:
      type: string
      enum: [customer-request, payment-failed, inventory-unavailable, fraud-detected]
      description: Reason code for status change

    Priority:
      type: string
      enum: [low, normal, high, urgent]
      default: normal
      description: Processing priority

    PaymentProvider:
      type: string
      enum: [stripe, paypal, square, adyen]
      description: Payment processor used

    PaymentMethod:
      type: string
      enum: [credit-card, debit-card, bank-transfer, digital-wallet]
      description: Payment method used

    InventoryUpdateType:
      type: string
      enum: [restock, sale, adjustment, damage, return]
      description: Type of inventory update

    NotificationType:
      type: string
      enum: [email, sms, push, webhook]
      description: Type of notification sent

    NotificationChannel:
      type: string
      enum: [email, sms, push, none]
      description: User's preferred notification channel

    NotificationProvider:
      type: string
      enum: [sendgrid, twilio, firebase, custom]
      description: Notification service provider

    DeviceType:
      type: string
      enum: [desktop, mobile, tablet, tv, watch]
      description: Type of device used

    Platform:
      type: string
      enum: [web, ios, android, api]
      description: Platform/app used

    AdminActionType:
      type: string
      enum: [user-management, order-management, inventory-management, system-config]
      description: Category of admin action

    PermissionLevel:
      type: string
      enum: [read, write, admin, super-admin]
      description: Permission level required for action

    AuditLevel:
      type: string
      enum: [low, medium, high, critical]
      description: Audit importance level

    # Payload schemas
    OrderCreatedPayload:
      type: object
      properties:
        orderId:
          type: string
        customerId:
          type: string
        totalAmount:
          type: number

    OrderStatusChangedPayload:
      type: object
      properties:
        orderId:
          type: string
        newStatus:
          type: string
        timestamp:
          type: string

    PaymentProcessedPayload:
      type: object
      properties:
        paymentId:
          type: string
        orderId:
          type: string
        amount:
          type: number
        status:
          type: string

    InventoryUpdatedPayload:
      type: object
      properties:
        productId:
          type: string
        quantityChange:
          type: integer
        newQuantity:
          type: integer

    NotificationSentPayload:
      type: object
      properties:
        recipientId:
          type: string
        message:
          type: string
        status:
          type: string

    UserBehaviorTrackedPayload:
      type: object
      properties:
        userId:
          type: string
        action:
          type: string
        timestamp:
          type: string

    AdminActionPerformedPayload:
      type: object
      properties:
        action:
          type: string
        targetId:
          type: string
        details:
          type: object

\n

Generating the Header Models​

\n

Create a configuration file to generate TypeScript header models:

\n
// codegen.config.js
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-messaging-system.yaml',
  generators: [
    {
      preset: 'headers',
      outputPath: './src/generated/headers',
      language: 'typescript',
    }
  ]
};
\n
\n

📁 See the complete configuration: codegen.config.js

\n
\n

Run the generator:

\n
npx @the-codegen-project/cli generate codegen.config.js
\n

This generates TypeScript classes with built-in serialization for each message's headers:

\n
// Generated: src/generated/headers/OrderCreatedHeaders.ts
export class OrderCreatedHeaders {
  private _xCorrelationId: string;
  private _xTenantId: string;
  private _xTimestamp?: string;
  private _authorization?: string;
  private _xSourceService?: SourceService;
  private _xApiVersion?: string;
  private _xRequestId?: string;
  private _xUserId: string;
  private _additionalProperties?: Map<string, any>;

  constructor(input: {
    xCorrelationId: string,
    xTenantId: string,
    xTimestamp?: string,
    authorization?: string,
    xSourceService?: SourceService,
    xApiVersion?: string,
    xRequestId?: string,
    xUserId: string,
    additionalProperties?: Map<string, any>,
  }) {
    this._xCorrelationId = input.xCorrelationId;
    this._xTenantId = input.xTenantId;
    this._xTimestamp = input.xTimestamp;
    this._authorization = input.authorization;
    this._xSourceService = input.xSourceService;
    this._xApiVersion = input.xApiVersion;
    this._xRequestId = input.xRequestId;
    this._xUserId = input.xUserId;
    this._additionalProperties = input.additionalProperties;
  }

  // Getters and setters...
  get xCorrelationId(): string { return this._xCorrelationId; }
  get xUserId(): string { return this._xUserId; }
  get xTenantId(): string { return this._xTenantId; }
  // ... more getters

  // JSON serialization
  public marshal(): string {
    // Generated marshalling logic
  }

  // JSON deserialization
  public static unmarshal(json: string | object): OrderCreatedHeaders {
    // Generated un-marshalling logic
  }

  // Validation methods
  public static validate(context?: {data: any, ajvValidatorFunction?: ValidateFunction, ajvInstance?: Ajv, ajvOptions?: AjvOptions}): { valid: boolean; errors?: ErrorObject[]; } {
    // Generated AJV validation logic
  }

  public static createValidator(context?: {ajvInstance?: Ajv, ajvOptions?: AjvOptions}): ValidateFunction {
    // Returns reusable validator function
  }
}
\n

Using Generated Header Models in Your Infrastructure​

\n

Now you can use these generated header models with any messaging infrastructure:

\n

With NATS​

\n
import { connect } from 'nats';
import { OrderCreatedHeaders } from './generated/headers/OrderCreatedHeaders';
import { PaymentProcessedHeaders } from './generated/headers/PaymentProcessedHeaders';

const nc = await connect({ servers: 'nats://localhost:4222' });

// Publishing with type-safe headers
async function publishOrderCreated(payload: any, headers: OrderCreatedHeaders) {
  await nc.publish('orders.created', JSON.stringify(payload), {
    headers: JSON.parse(headers.marshal())
  });
}

// Consuming with header validation
const sub = nc.subscribe('payments.processed');
for await (const msg of sub) {
  try {
    const headers = PaymentProcessedHeaders.unmarshal(msg.headers);
    
    // Validate required headers
    if (!headers.xCorrelationId || !headers.xPaymentProvider) {
      console.error('Missing required headers');
      continue;
    }
    
    // Route based on payment provider
    switch (headers.xPaymentProvider) {
      case 'stripe':
        await processStripePayment(msg.data, headers);
        break;
      case 'paypal':
        await processPayPalPayment(msg.data, headers);
        break;
    }
  } catch (error) {
    console.error('Error processing payment:', error);
  }
}
\n

With Kafka​

\n
import { Kafka } from 'kafkajs';
import { PaymentProcessedHeaders } from './generated/headers/PaymentProcessedHeaders';

const kafka = new Kafka({ clientId: 'payment-service', brokers: ['localhost:9092'] });
const producer = kafka.producer();

async function publishPaymentProcessed(payment: any, headers: PaymentProcessedHeaders) {
  await producer.send({
    topic: 'payments.processed',
    messages: [{
      key: payment.paymentId,
      value: JSON.stringify(payment),
      headers: JSON.parse(headers.marshal())
    }]
  });
}

// Consumer with header-based routing
const consumer = kafka.consumer({ groupId: 'payment-processor' });
await consumer.run({
  eachMessage: async ({ message }) => {
    const headers = PaymentProcessedHeaders.unmarshal(message.headers);
    
    // Use risk score for processing decisions
    if (headers.xRiskScore && headers.xRiskScore > 50) {
      await flagForManualReview(message.value, headers);
    } else {
      await processAutomatically(message.value, headers);
    }
  }
});
\n

Advanced Header Patterns​

\n

Multi-tenant Routing​

\n
import { OrderCreatedHeaders } from './generated/headers/OrderCreatedHeaders';

// Route messages based on tenant
function routeByTenant(headers: OrderCreatedHeaders) {
  const tenantConfig = getTenantConfig(headers.xTenantId);
  
  return {
    topic: `orders.created.${tenantConfig.region}`,
    partition: tenantConfig.partition,
    headers: headers.marshal()
  };
}
\n

Distributed Tracing​

\n
import { PaymentProcessedHeaders } from './generated/headers/PaymentProcessedHeaders';

// Link events across services
async function processPayment(paymentData: any, incomingHeaders: OrderCreatedHeaders) {
  const paymentHeaders = new PaymentProcessedHeaders({
    xCorrelationId: incomingHeaders.xCorrelationId, // Preserve correlation
    xPaymentProvider: 'stripe',
    xTenantId: incomingHeaders.xTenantId,
    xIdempotencyKey: generateIdempotencyKey(),
    xRetryCount: 0
  });
  
  // Process payment with linked tracing
  await publishPaymentEvent(paymentData, paymentHeaders);
}
\n

Authentication & Security​

\n
import { AdminActionPerformedHeaders } from './generated/headers/AdminActionPerformedHeaders';

// Validate JWT and extract claims
function validateAdminHeaders(headers: AdminActionPerformedHeaders): boolean {
  // Verify JWT token structure
  if (!headers.authorization?.startsWith('Bearer ')) {
    return false;
  }
  
  // Check permission level matches action type
  const requiredLevel = getRequiredPermissionLevel(headers.xActionType);
  return hasPermission(headers.xPermissionLevel, requiredLevel);
}
\n

Performance Optimization​

\n
import { NotificationSentHeaders } from './generated/headers/NotificationSentHeaders';

// Batch notifications by provider
const notificationBatches = new Map<string, NotificationSentHeaders[]>();

function batchNotification(headers: NotificationSentHeaders) {
  const provider = headers.xProvider || 'default';
  
  if (!notificationBatches.has(provider)) {
    notificationBatches.set(provider, []);
  }
  
  notificationBatches.get(provider)!.push(headers);
  
  // Process batch when full
  if (notificationBatches.get(provider)!.length >= 100) {
    processBatch(provider, notificationBatches.get(provider)!);
    notificationBatches.set(provider, []);
  }
}
\n

Error Handling and Validation​

\n

The generated header models include robust validation capabilities that help catch errors before they propagate through your system:

\n
import { OrderCreatedHeaders } from './generated/headers/OrderCreatedHeaders';

// Validate raw header data before creating model instances
function validateAndCreateOrderHeaders(rawHeaders: any): OrderCreatedHeaders | null {
  // First, validate the raw data structure
  const validation = OrderCreatedHeaders.validate({
    data: rawHeaders
  });
  
  if (!validation.valid) {
    console.error('Header validation failed:', validation.errors);
    return null;
  }
  // If validation passes, safely create the header instance
  const headers = OrderCreatedHeaders.unmarshal(rawHeaders);
  return headers;
}
\n

Benefits of This Approach​

\n
    \n
  1. Type Safety: Full TypeScript support with compile-time checking for headers
    2. \n
  2. Automatic Serialization: Built-in JSON marshalling/unmarshalling
    3. \n
  3. Header Validation: Ensure required headers are present and correctly formatted
    4. \n
  4. Infrastructure Freedom: Use any messaging system or HTTP framework
    5. \n
  5. Maintainability: Schema changes automatically update your header models
    6. \n
  6. Performance: Optimized validation for high-throughput systems
    7. \n
\n

Conclusion​

\n

By generating header models from your AsyncAPI specification, you eliminate manual header management while gaining type safety and consistency across your entire messaging infrastructure. This approach gives you robust, maintainable code that handles authentication, tracing, routing, and metadata seamlessly.

\n

The generated header models integrate with any messaging system and provide the foundation for building scalable, observable, and secure event-driven applications. Combined with automatic serialization and validation, you get production-ready header management that evolves with your API specifications.

\n

Ready to try it yourself? Check out the headers generator documentation and start generating your header models today!

\n

Try It Yourself​

\n

Want to see this in action? Clone our ecommerce-headers example and run:

\n
cd examples/ecommerce-asyncapi-headers
npm install
npm run generate
npm run demo
\n

This will generate the header models and run a comprehensive demonstration showing how they work with authentication, tracing, routing, and metadata management across different messaging patterns.

\n

Additional Resources​

\n", "url": "https://the-codegen-project.org/blog/asyncapi-headers-generator", "title": "AsyncAPI - Type-Safe Headers", "summary": "Building robust event-driven applications requires more than just payload validation - you need proper header management for authentication, tracing, routing, and metadata. In our previous post about payload generation, we showed how to generate type-safe data models. Now let's explore how The Codegen Project's headers generator can streamline your messaging infrastructure by handling the metadata side of your messages.", "date_modified": "2025-06-11T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Headers", "TypeScript", "Messaging", "Automation" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-payload-generator", "content_html": "

Building event-driven applications often means spending countless hours writing and maintaining payload models. What if you could generate these models automatically from your AsyncAPI specification while keeping full control over your infrastructure code? In this post, we'll explore how The Codegen Project's payload generator can save you time and reduce errors.

\n

The Problem: Manual Model Maintenance​

\n

When building event-driven systems, you typically need:

\n
    \n
  1. Payload models - TypeScript interfaces/classes representing your message structures
    2. \n
  2. Validation logic - Ensuring incoming data matches expected schemas
    3. \n
  3. Serialization/deserialization - Converting between JSON and typed objects
    4. \n
  4. Infrastructure code - Your custom message handling, routing, and business logic
    5. \n
\n

The first three are pure boilerplate that can be generated. The fourth is where your business value lies and is where you should spend the most time.

\n

The Solution: Generated Models + Custom Infrastructure​

\n

The Codegen Project's payloads preset generates only the payload representation, leaving you free to implement infrastructure however you prefer - whether that's using NATS, Kafka, RabbitMQ, or any other messaging system.

\n

Real-World Example: E-commerce Order System​

\n

Let's take a real world example, an e-commerce order processing system. Here's our AsyncAPI specification (ecommerce-order-system.yaml):

\n
\n

💡 Complete Example: You can find the full working example, including all files mentioned in this post, in our ecommerce-payloads example.

\n
\n
Show me the AsyncAPI document!

asyncapi: 3.0.0
info:
  title: E-commerce Order System
  version: 1.0.0
  description: Event-driven order processing system

channels:
  order-events:
    # ...
    messages:
      OrderCreated:
        payload:
          $ref: '#/components/schemas/OrderCreated'

      OrderStatusChanged:
        payload:
          $ref: '#/components/schemas/OrderStatusChanged'

  payment-events:
    # ...
    messages:
      PaymentProcessed:
        payload:
          $ref: '#/components/schemas/PaymentProcessed'

  notification-events:
    # ...
    messages:
      # Edge case: Union types for different notification channels
      NotificationSent:
        payload:
          $ref: '#/components/schemas/NotificationSent'

components:
  schemas:
    OrderCreated:
      type: object
      required: [orderId, customerId, items, totalAmount, currency]
      properties:
        orderId:
          type: string
          format: uuid
          description: Unique order identifier
        customerId:
          type: string
          format: uuid
          description: Customer who placed the order
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        totalAmount:
          type: number
          minimum: 0
          description: Total order amount in cents
        currency:
          $ref: '#/components/schemas/Currency'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        metadata:
          $ref: '#/components/schemas/Metadata'

    OrderItem:
      type: object
      required: [productId, quantity, unitPrice]
      properties:
        productId:
          type: string
          description: Product identifier
        quantity:
          type: integer
          minimum: 1
          description: Number of items ordered
        unitPrice:
          type: number
          minimum: 0
          description: Price per unit in cents
        metadata:
          $ref: '#/components/schemas/Metadata'

    OrderStatusChanged:
      type: object
      required: [orderId, previousStatus, newStatus, timestamp]
      properties:
        orderId:
          type: string
          format: uuid
        previousStatus:
          $ref: '#/components/schemas/OrderStatus'
        newStatus:
          $ref: '#/components/schemas/OrderStatus'
        timestamp:
          type: string
          format: date-time
        reason:
          type: string
          description: Reason for status change

    PaymentProcessed:
      type: object
      required: [paymentId, orderId, amount, currency, status]
      properties:
        paymentId:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        amount:
          type: number
          minimum: 0
        currency:
          $ref: '#/components/schemas/Currency'
        status:
          $ref: '#/components/schemas/PaymentStatus'
        processorResponse:
          $ref: '#/components/schemas/Metadata'

    NotificationSent:
      oneOf:
        - $ref: '#/components/schemas/EmailNotification'
        - $ref: '#/components/schemas/SmsNotification'
        - $ref: '#/components/schemas/PushNotification'
      discriminator: 'type'

    EmailNotification:
      type: object
      required: [type, recipientId, subject, body]
      properties:
        type:
          const: email
        recipientId:
          type: string
        subject:
          type: string
        body:
          type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'

    SmsNotification:
      type: object
      required: [type, recipientId, message]
      properties:
        type:
          const: sms
        recipientId:
          type: string
        message:
          type: string
          maxLength: 160

    PushNotification:
      type: object
      required: [type, recipientId, title, body]
      properties:
        type:
          const: push
        recipientId:
          type: string
        title:
          type: string
        body:
          type: string
        badge:
          type: integer
          minimum: 0

    Attachment:
      type: object
      properties:
        filename:
          type: string
        contentType:
          type: string
        data:
          type: string
          contentEncoding: base64

    Currency:
      type: string
      enum: [USD, EUR, GBP]
      description: Currency code

    PaymentStatus:
      type: string
      enum: [success, failed, pending]
      description: Payment processing status

    Metadata:
      type: object
      additionalProperties: true
      description: Additional metadata

    Address:
      type: object
      required: [street, city, country, postalCode]
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code
        postalCode:
          type: string

    OrderStatus:
      type: string
      enum: [pending, confirmed, processing, shipped, delivered, cancelled, refunded]

    # Edge case: Circular reference example
    Category:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        parentCategory:
          $ref: '#/components/schemas/Category'
        subcategories:
          type: array
          items:
            $ref: '#/components/schemas/Category'

\n

Generating the Models​

\n

Create a configuration file to generate TypeScript payload models:

\n
// codegen.config.js
export default {
  inputType: 'asyncapi',
  inputPath: './ecommerce-order-system.yaml',
  generators: [
    {
      preset: 'payloads',
      outputPath: './src/generated/models',
      language: 'typescript',
      includeValidation: true
    }
  ]
};
\n
\n

📁 See the complete configuration: codegen.config.js

\n
\n

Run the generator:

\n
npx @the-codegen-project/cli generate codegen.config.js
\n

This generates TypeScript classes with built-in validation for each message type:

\n
// Generated: src/generated/models/OrderCreated.ts
export class OrderCreated {
  private _orderId: string;
  private _customerId: string;
  private _items: OrderItem[];
  private _totalAmount: number;
  private _currency: Currency;
  private _shippingAddress?: Address;
  private _metadata?: Record<string, any>;
  private _additionalProperties?: Record<string, any>;

  constructor(input: {
    orderId: string,
    customerId: string,
    items: OrderItem[],
    totalAmount: number,
    currency: Currency,
    shippingAddress?: Address,
    metadata?: Record<string, any>,
    additionalProperties?: Record<string, any>,
  }) {
    this._orderId = input.orderId;
    this._customerId = input.customerId;
    this._items = input.items;
    this._totalAmount = input.totalAmount;
    this._currency = input.currency;
    this._shippingAddress = input.shippingAddress;
    this._metadata = input.metadata;
    this._additionalProperties = input.additionalProperties;
  }

  // Getters and setters...
  get orderId(): string { return this._orderId; }
  get customerId(): string { return this._customerId; }
  // ... more getters

  // JSON serialization
  public marshal(): string {
    // Generated marshalling logic
  }

  // JSON deserialization
  public static unmarshal(json: string | object): OrderCreated {
    // Generated un-marshalling logic
  }

  // Validation methods
  public static validate(context?: {data: any, ajvValidatorFunction?: ValidateFunction, ajvInstance?: Ajv, ajvOptions?: AjvOptions}): { valid: boolean; errors?: ErrorObject[]; } {
    // Generated AJV validation logic
  }

  public static createValidator(context?: {ajvInstance?: Ajv, ajvOptions?: AjvOptions}): ValidateFunction {
    // Returns reusable validator function
  }
}
\n

Using Generated Models in Your Infrastructure​

\n

Now you can use these generated models with any messaging infrastructure:

\n

With NATS​

\n
import { connect } from 'nats';
import { OrderCreated, PaymentProcessed } from './generated/models';

const nc = await connect({ servers: 'nats://localhost:4222' });

// Publishing with type safety
async function publishOrderCreated(order: OrderCreated) {
  const jsonString = order.marshal();
  const validation = OrderCreated.validate({data: jsonString});
  if (!validation.valid) {
    throw new Error(`Invalid order data: ${validation.errors}`);
  }
  
  await nc.publish('orders.created', jsonString);
}

// Consuming with validation
const sub = nc.subscribe('payments.processed');
for await (const msg of sub) {
  try {
    const data = msg.data.toString();
    const validation = PaymentProcessed.validate({data});
    
    if (!validation.valid) {
      console.error('Invalid payment data:', validation.errors);
      continue;
    }
    
    const payment = PaymentProcessed.unmarshal(data);
    await handlePaymentProcessed(payment);
  } catch (error) {
    console.error('Error processing payment:', error);
  }
}
\n

With Kafka​

\n
import { Kafka } from 'kafkajs';
import { OrderStatusChanged } from './generated/models';

const kafka = new Kafka({ clientId: 'order-service', brokers: ['localhost:9092'] });
const producer = kafka.producer();

async function publishStatusChange(statusChange: OrderStatusChanged) {
  const jsonString = statusChange.marshal();
  const validation = OrderStatusChanged.validate({data: jsonString});
  if (!validation.valid) {
    throw new Error(`Invalid status change: ${validation.errors}`);
  }

  await producer.send({
    topic: 'order-status-changes',
    messages: [{
      key: statusChange.orderId,
      value: jsonString
    }]
  });
}
\n

Handling Edge Cases​

\n

Union Types and Polymorphism​

\n

The generated NotificationSent model handles the union type elegantly:

\n
import { 
  EmailNotification, 
  SmsNotification, 
  PushNotification,
  NotificationSent
} from './generated/models';

function process(data: any) {
  // Validate it generically
  if (!NotificationSent.validate({data}).valid) {
    throw new Error('Not a valid notification object');
  }
  const notificationData = NotificationSent.unmarshal(data);

  if(notificationData instanceof EmailNotification){
    // Do something with email notification data
    return sendEmail(notification);
  } else if(notificationData instanceof SmsNotification){
    // Do something with sms notification data
    return sendSms(notification);
  } else if(notificationData instanceof PushNotification){
    // Do something with push notification data
    return sendPushNotification(notification);
  }

  // Or do it for each variant
  if (EmailNotification.validate({data}).valid) {
    const notification = NotificationSentEmail.unmarshal(data);
    return sendEmail(notification);
  }

  throw new Error('Unknown notification type');
}
\n

Complex Nested Objects​

\n

The generator handles nested objects and arrays seamlessly:

\n
const order = new OrderCreated({
  orderId: '123e4567-e89b-12d3-a456-426614174000',
  customerId: '987fcdeb-51a2-43d1-9f12-345678901234',
  items: [
    new OrderItem({
      productId: 'LAPTOP-001',
      quantity: 1,
      unitPrice: 249900
    }),
    new OrderItem({
      productId: 'MOUSE-001',
      quantity: 2,
      unitPrice: 7900
    })
  ],
  totalAmount: 99999,
  currency: Currency.USD,
  shippingAddress: new Address({
    street: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94105',
    country: 'US'
  })
});
\n

Circular References​

\n

The generator can of course handle circular references in schemas:

\n
# In your AsyncAPI spec
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        parentCategory:
          $ref: '#/components/schemas/Category'
        subcategories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
\n

Validation Performance Optimization​

\n

For high-throughput scenarios, create validators once and reuse them:

\n
// Create validators at startup
const orderCreatedValidator = OrderCreated.createValidator();

// Reuse in message processing
function processOrderMessage(data: any) {
  const validation = OrderCreated.validate({ 
    data, 
    ajvValidatorFunction: orderCreatedValidator 
  });
  
  if (!validation.valid) {
    throw new Error(`Invalid order: ${validation.errors}`);
  }
  
  return OrderCreated.unmarshal(data);
}
\n

Benefits of This Approach​

\n
    \n
  1. Type Safety: Full TypeScript support with compile-time checking
    2. \n
  2. Runtime Validation: Built-in JSON Schema validation prevents runtime errors
    3. \n
  3. Single Source of Truth: Your AsyncAPI spec drives both documentation and code
    4. \n
  4. Infrastructure Freedom: Use any messaging system or framework
    5. \n
  5. Maintainability: Schema changes automatically update your models
    6. \n
  6. Performance: Optimized validation with reusable validators
    7. \n
\n

Conclusion​

\n

By generating payload models from your AsyncAPI specification, you eliminate boilerplate code while maintaining full control over your infrastructure. This approach gives you the best of both worlds: automated, type-safe data models and the flexibility to implement your messaging infrastructure exactly how you need it.

\n

The generated models handle complex scenarios like union types, nested objects, and circular references, making them suitable for real-world applications. Combined with built-in validation, you get robust, maintainable code that evolves with your API specifications.

\n

Ready to try it yourself? Check out the payload generator documentation and start generating your models today!

\n

Try It Yourself​

\n

Want to see this in action? Clone our ecommerce-payloads example and run:

\n
cd examples/ecommerce-asyncapi-payloads
npm install
npm run generate
npm run demo
\n

This will generate the payload models and run a demonstration showing how they work with validation and serialization.

\n

Additional Resources​

\n", "url": "https://the-codegen-project.org/blog/asyncapi-payload-generator", "title": "AsyncAPI - Stop wasting time on payloads", "summary": "Building event-driven applications often means spending countless hours writing and maintaining payload models. What if you could generate these models automatically from your AsyncAPI specification while keeping full control over your infrastructure code? In this post, we'll explore how The Codegen Project's payload generator can save you time and reduce errors.", "date_modified": "2025-06-02T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Payloads", "TypeScript", "Automation" ] }, { "id": "https://the-codegen-project.org/blog/update-2", "content_html": "

Since the release of v0.33, we've been diligently enhancing the Codegen CLI to make generated code safer, more intuitive, and aligned with real-world development practices. Spanning versions v0.34.0 through v0.39.0, this update introduces significant improvements, including automatic payload validation enabled by default and unified parameters.

\n

TLDR:

\n\n

Payload Validation by Default​

\n

A cornerstone of this update is the automatic payload validation feature for the channel and client generators. Now, every message consumed message is validated against its schema using the AJV JSON Schema validator. This ensures that only well-formed messages are processed, enhancing the reliability of your services.

\n

For instance, attempting to consume a message not conforming to the schema, will return a validation error:

\n
await subscribeToUserSignedup({
  onDataCallback: (err, msg) => {
    if(err) return console.error(err);
    // Continue doing what you want
  }
});
\n

This validation is seamlessly integrated across all supported protocols - NATS, Kafka, AMQP, MQTT, and EventSource. While it's enabled by default, you can opt out using the skipMessageValidation flag when necessary.

\n

Beyond that, if you just use the payloads generator, you can directly use the validation feature.

\n

Unified Parameters​

\n

Alongside validation, we’ve streamlined how you interact with the generated clients and channel APIs. All functions — whether subscribing to messages or publishing them — now accept a single options object. This replaces the old style of passing multiple positional arguments, which could become unwieldy and error-prone as more parameters were added.

\n

Where you previously had to write:

\n
await publishToSendUserSignedup(message, parameters, connection);
\n

you now write:

\n
await publishToSendUserSignedup({ message, parameters, connection });
\n

This change makes generated code cleaner, easier to read, and more future-proof. Adding new options like validation toggles or runtime configs no longer forces breaking changes to the function signature. It also aligns better with modern JavaScript and TypeScript practices, where objects are preferred for configuration and function input.

\n

Naturally, this is a breaking change if you’ve generated clients using earlier versions of the CLI. But we’ve updated the documentation with before/after code samples and a new migration guide to make the transition painless.

\n

Smarter Logs, Sharper Types​

\n

Improving the runtime experience doesn’t stop at validation. We’ve also refined our logging output to be more concise and informative. Error messages now tell you exactly what’s missing or invalid, and log output during code generation is easier to scan. The CLI feels more polished as a result.

\n

Under the hood, we took care to strengthen the TypeScript types that power both the generator and the generated output. These type improvements catch issues earlier and provide better autocompletion and type safety in your editor. It’s a quieter kind of upgrade, but one that makes every project feel more solid.

\n

Docs, Fixes, and Behind-the-Scenes Polish​

\n

The improvements in this release go beyond features. We’ve also spent time fixing edge-case bugs, updating our dependencies, and tightening up the release pipeline. A longstanding issue that prevented some website updates from appearing after new releases has been resolved — so the docs you read will always match the CLI version you’re using.

\n

We’ve added clearer error handling when required inputs (like an AsyncAPI document) are missing, smoothed out some inconsistencies in template output, and improved how empty payloads and unusual channel names are handled in generated code.

\n

You’ll also find updated documentation throughout — especially around the new payload validation behavior and the object-style function parameters. These updates ensure that as the CLI evolves, learning and adopting the new workflows is as smooth as possible.

\n
\n

This release marks a turning point for Codegen CLI: your generated clients are now not only protocol-aware, but schema-aware by default. We’re excited about what this enables — safer microservices, more reliable messaging, and less defensive coding on your part.

\n

Give v0.39.0 a try, and as always, let us know how we can keep making Codegen better.

\n

Until next time, happy coding!

", "url": "https://the-codegen-project.org/blog/update-2", "title": "The Codegen Project - 1 Months of Progress", "summary": "Since the release of v0.33, we've been diligently enhancing the Codegen CLI to make generated code safer, more intuitive, and aligned with real-world development practices. Spanning versions v0.34.0 through v0.39.0, this update introduces significant improvements, including automatic payload validation enabled by default and unified parameters.", "date_modified": "2025-05-01T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project" ] }, { "id": "https://the-codegen-project.org/blog/asyncapi-customizing-outputs", "content_html": "

The Codegen Project provides several ways to customize the generated code output through AsyncAPI extensions. In this post, we'll explore the available customization options and how to use them effectively.

\n

Channel naming​

\n

The channelName extension property allows you to override the default naming conventions used by the generator. This is particularly useful in several scenarios:

\n
    \n
  1. When working with AsyncAPI 2.x documents where channel names are derived from addresses
    2. \n
  2. When you want to enforce specific naming conventions in your codebase
    3. \n
  3. When the auto-generated names don't match your team's preferences
    4. \n
\n
asyncapi: 3.0.0
channels:
  user-events:
    address: user/signedup/v1
    x-the-codegen-project:
      # Override the auto-generated channel name
      channelName: UserEvents
\n

The channelName property affects several aspects of code generation:

\n\n

This is primarily used for channels and client generators as they generate helper functions, and payload, parameters, and headers model names.

\n

Function type mapping​

\n

The functionTypeMapping property allows you to specify which types of protocol functions should be generated for a channel. For example for event source, you have the option to define:

\n\n

The reason why this extension is needed, especially for channels, is because there is no other way to specify what protocol functions you need. In conjunction with operations, this means that if multiple different types of protocol functions are available, you can selectively decide which ones are relevant.

\n

See the full list here: https://the-codegen-project.org/docs/api/enumerations/ChannelFunctionTypes

\n

Example usage:

\n
asyncapi: 3.0.0
channels:
  user-events:
    x-the-codegen-project:
      functionTypeMapping: 
        - event_source_fetch
\n

With the corresponding configuration:

\n
export default {
  generators: [
    {
      preset: 'channels',
      outputPath: './src/__gen__/',
      language: 'typescript',
      protocols: ['event_source'],
      asyncapiGenerateForOperations: false
    }
  ]
};
\n

It will only generate event source fetch (client) functions for that specific channel.

\n

As mentioned earlier, this can also be defined for operations, the same as for channels. Here specifying event source does not make much sense, but for something like NATS, you can specify whether it's for JetStream or core NATS:

\n
asyncapi: 3.0.0
operations:
  publishUserEvent:
    x-the-codegen-project:
      functionTypeMapping: 
        - nats_jetstream_publish
\n

With the corresponding configuration:

\n
export default {
  generators: [
    {
      preset: 'channels',
      outputPath: './src/__gen__/',
      language: 'typescript',
      protocols: ['nats']
    }
  ]
};
\n

Future?​

\n

There will probably in the future be a unification of these extensions, as all code generations mature and can benefit from these types of extensions.

\n

For now, The Codegen Project's extensions will provide a robust foundation for allowing you to customize the generated code even further. In the future, we will definitely also see more extensions emerge as more use cases get uncovered.

\n

Remember to check the official documentation for the latest updates and additional customization options as they become available.

\n

I will also make sure to update you whenever extensions come to life.

", "url": "https://the-codegen-project.org/blog/asyncapi-customizing-outputs", "title": "The Codegen Project - AsyncAPI Extensions", "summary": "The Codegen Project provides several ways to customize the generated code output through AsyncAPI extensions. In this post, we'll explore the available customization options and how to use them effectively.", "date_modified": "2025-04-04T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project", "AsyncAPI", "Customization" ] }, { "id": "https://the-codegen-project.org/blog/update-1", "content_html": "

It has been a while since the last update, almost 5 months to be exact, all these improvements have been happening while building the SDK platform, using the CLI as it's pillars.

\n

Since our last update in October 2024, we've evolved the project with new features, expanded protocol support, crucial fixes, and improved documentation. Instead of just listing the changes, we want to share the journey of how we grew The Codegen Project CLI from version 0.23.0 to 0.33.0.

\n

🚀 Wrapping Up 2024: Headers & Stability​

\n

When we left off in October, the Codegen CLI was already powerful, but it soon gained an important new ability: TypeScript Headers Generation. This feature allowed us to generate strongly-typed models for message headers defined in AsyncAPI specs, alongside payload models. We introduced a new headers preset to produce header models for each channel, initially supporting AsyncAPI input and TypeScript output. Some of the next steps is integrating it into the channels and client presets for all the protocols like payload.

\n
export default {
  ...,
  generators: [
    {
      preset: 'headers',
      outputPath: './src/headers',
      language: 'typescript',
    }
  ]
};
\n

After adding this big feature, we focused on stability. In early November, we tackled an issue with weird payload generation that led to unexpected behaviors. This bugfix ensured that the CLI generated cleaner, more reliable output. Then, on December 1st, we performed a refactor and cleanup pass, resolving lingering issues and improving maintainability. With header generation in place and a wave of bug fixes, we ended 2024 on a solid foundation.

\n

🔄 December: NATS Request-Reply Refactor​

\n

As the holiday season arrived, we turned our attention to NATS request/reply support. Previously, the CLI’s generation logic focused primarily on pub-sub, but NATS’s request-reply pattern required a more operation-aware approach. To achieve this, we refactored how the generator processes AsyncAPI operations, introducing conditional channel functions and an asyncapiReverseOperations flag to support flexible and complex scenarios.

\n

The result? The CLI could now generate request sender and response listener code for NATS with correct message handling in both directions. Along the way, we fixed edge cases where response messages weren’t generated correctly, making NATS a much more powerful integration within Codegen. By December 21, these changes landed in version 0.25.0, wrapping up the year with a major protocol enhancement.

\n

🌍 New Year, New Protocols: Kafka, MQTT, and AMQP​

\n

With 2025 underway, we set our sights on broadening protocol support. By mid-January, Kafka, MQTT, and AMQP all became part of the CLI’s repertoire.

\n
export default {
  ...,
  generators: [
    {
      preset: 'channels',
      outputPath: './src/__gen__/', 
      language: 'typescript',
      protocols: ['kafka', 'mqtt', 'amqp']
    }
  ]
};
\n

These messaging protocols each have their own nuances—Kafka’s consumer groups, MQTT’s lightweight pub-sub model, and AMQP’s queue/exchange semantics. We carefully implemented support for each, ensuring the CLI could correctly generate code for these backends. By version 0.28.0, developers could generate TypeScript code for Kafka, MQTT, or AMQP streams using AsyncAPI, expanding the CLI’s reach across the messaging ecosystem.

\n

📡 February: Server-Sent Events & Function Types​

\n

In the platform we had the need to use Server-Sent Events (SSE) for our frontend live update functionality, which started in early February. The CLI could now generate both Event Source clients (fetch) and servers (express), allowing users to describe real-time HTTP SSE endpoints in AsyncAPI and generate corresponding TypeScript implementations. This filled a key gap, making the CLI not just for brokered messaging, but for real-time web streams as well.

\n
export default {
  ...,
  generators: [
    {
      preset: 'channels',
      outputPath: './src/__gen__/', 
      language: 'typescript',
      protocols: ['event_source']
    }
  ]
};
\n

At the same time, we added custom function type mappings, enabling AsyncAPI operations and functions to influence function signatures. This flexibility was particularly useful for advanced use cases—like tweaking request-reply functions or applying custom channel configurations.

\n
{
  \"asyncapi\": \"3.0.0\",
  ...,
  \"channels\": {
    \"test-channel\": {
      \"x-the-codegen-project\": {
        \"channelName\": \"Test\",
        \"functionTypeMapping\": [\"event_source_express\"]
      }
    }
  },
  \"operation\": {
    \"test-operation\": {
      \"x-the-codegen-project\": {
        \"functionTypeMapping\": [\"event_source_express\"]
      }
    }
  }
}
\n

By the end of February, The Codegen Project CLI had become more versatile than ever, with powerful function mappings, and robust SSE support.

\n

🛠️ March: Documentation, Queue Subscriptions & a Generator Rewrite​

\n

With many major features shipped, March was about polishing the experience and tying up loose ends. We gave our documentation a major overhaul, updating guides and examples to ensure new features were easy to understand and use. The refreshed AsyncAPI usage guide, headers guide, and AMQP guide made it easier than ever to adopt the CLI’s latest capabilities.

\n

On the development side, we fine-tuned AMQP queue subscriptions, ensuring seamless consumer binding to durable queues. Finally, we conducted a complete rewrite of the channel generator logic — not to add a new feature, but to clean up and streamline how each channel is processed. This refactor eliminated redundancies, improved maintainability, and laid the groundwork for future enhancements.

\n
\n

🎯 Wrapping Up: A More Powerful Codegen CLI​

\n

Looking back, the period from October 2024 to March 2025 has been one of remarkable growth. We've transformed the CLI into a multi-protocol powerhouse, supporting Kafka, MQTT, AMQP, NATS (including request/reply), and SSE. Features like typed headers, customizable function types, and detailed documentation have made it more robust and developer-friendly than ever.

\n

These last five months have been about eating your own tool while we have been working on the SDK platform. Whether you're working with pub-sub, request-reply, or real-time streaming, Codegen now has you covered or will in the future. And with our recent generator refactor, we're well-positioned to keep improving and innovating in the months ahead.

\n

Thanks for following along — we’re excited to see what the next chapter brings! 🚀

", "url": "https://the-codegen-project.org/blog/update-1", "title": "The Codegen Project - 5 Months of Progress", "summary": "It has been a while since the last update, almost 5 months to be exact, all these improvements have been happening while building the SDK platform, using the CLI as it's pillars.", "date_modified": "2025-03-22T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project" ] }, { "id": "https://the-codegen-project.org/blog/the-codegen-project", "content_html": "

\"The

\n

The Idea 💡​

\n

Apollo GraphQL code generator has always been a pleasure to use, but when it comes to standards such as OpenAPI and AsyncAPI, the same level of code generator or simplicity during the implemenation phase is non-existing.

\n

That is what this project wants to bring;

\n\n

A bit ambitious perhaps... So how?

\n

How❓​

\n

We want to achieve it through three main parts, open source, extensive testing, and sustainability.

\n

🔓 Open source​

\n

Build on and for open source. Use it however you like in your projects enterprise or not, build your software with ease and peace in mind with Apache License 2.0. It is built for multiple use-cases, as we all know, there will always be another standard. So high likelyhood that we already support what you are switching to.

\n

🔎 Testing makes the dream work​

\n

The worst part about any code generator is if the generated code is either syntantically unusable or sematically incorrect. Thats why all generators are run through a set of tests, blackbox, runtime and regular unit testing.

\n\n

🔗 Long term sustainability​

\n

Relying only on peoples spare time is not a very good long term strategy. We want to ensure the longevity of the project and ensure that those who contribute most also can get paid by it, or even employed to work on open source.

\n

More on that later ;)

\n

Where we are 📅​

\n

Right this second, we are laying the foundation for the project, but it's already usable. Take it for a spin!

\n

If you want to take a look at current project planning, take a look at the Milestones for a better overview of whats now and next.

", "url": "https://the-codegen-project.org/blog/the-codegen-project", "title": "The Codegen Project", "summary": "The Codegen Project banner", "date_modified": "2024-10-25T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project" ] }, { "id": "https://the-codegen-project.org/blog/welcome", "content_html": "

Welcome to The Codegen Project, we are really excited to show you what we have started 🔥

\n

Stay tuned!

", "url": "https://the-codegen-project.org/blog/welcome", "title": "Welcome", "summary": "Welcome to The Codegen Project, we are really excited to show you what we have started", "date_modified": "2024-10-04T00:00:00.000Z", "author": { "name": "Jonas Lagoni", "url": "https://github.com/jonaslagoni" }, "tags": [ "The Codegen Project" ] } ] }