ProducerRecord

Kind: Interface

Source: packages/microservices/external/kafka.interface.ts

Part of: Microservices

ProducerRecord defines the payload and delivery options for publishing one or more messages to an Apache Kafka topic. It groups the target topic, message batch, acknowledgement behavior, request timeout, and compression strategy used by the Kafka producer.

Properties

Diagram

mermaid
graph LR
  ProducerRecord[ProducerRecord]
  Topic[topic: string]
  Messages[messages: Message[]]
  Acks[acks: number]
  Timeout[timeout: number]
  Compression[compression: CompressionTypes]

  ProducerRecord --> Topic
  ProducerRecord --> Messages
  ProducerRecord --> Acks
  ProducerRecord --> Timeout
  ProducerRecord --> Compression
  Messages --> Kafka[Kafka topic]

Usage

ts
import { CompressionTypes } from 'kafkajs';
import type { ProducerRecord } from '@nestjs/microservices';

const record: ProducerRecord = {
  topic: 'orders.created',
  messages: [
    {
      key: 'order-123',
      value: JSON.stringify({
        orderId: 'order-123',
        customerId: 'customer-456',
        total: 99.95,
      }),
      headers: {
        eventType: 'order.created',
      },
    },
  ],
  acks: -1,
  timeout: 30_000,
  compression: CompressionTypes.GZIP,
};

await producer.send(record);

AI Coding Instructions

• Provide a valid Kafka topic name and include at least one item in messages.
• Serialize structured message values with JSON.stringify() unless the producer integration handles serialization.
• Use acks: -1 when durability is important; lower acknowledgement settings can improve throughput but reduce delivery guarantees.
• Set timeout according to expected broker/network latency, especially for larger message batches.
• Select a CompressionTypes value supported by the configured Kafka client and cluster.

How it works

ProducerRecord is an exported TypeScript interface in the KafkaJS type-only declaration surface; the file explicitly says it represents KafkaJS package types and should not contain NestJS logic. packages/microservices/external/kafka.interface.ts:1-8

It describes the record object passed to a Kafka Producer or Transaction sender:

• topic is required and has type string. packages/microservices/external/kafka.interface.ts:740-742
• messages is required and is an array of Message objects. packages/microservices/external/kafka.interface.ts:740-742 A Message requires a value of Buffer | string | null; it can also carry an optional key, partition, headers, and timestamp. packages/microservices/external/kafka.interface.ts:121-127
• acks, timeout, and compression are optional record-level fields. acks and timeout are numbers; compression is typed as CompressionTypes. packages/microservices/external/kafka.interface.ts:740-746

ProducerRecord is the argument to Sender.send(), which returns a Promise<RecordMetadata[]>. packages/microservices/external/kafka.interface.ts:785-788 Producer and Transaction both include that sender contract. packages/microservices/external/kafka.interface.ts:798-829 Each returned metadata entry includes a topic name, partition, and error code, with optional offset and timestamp-related fields. packages/microservices/external/kafka.interface.ts:748-757

For Nest Kafka transport configuration, KafkaOptions.options.send accepts ProducerRecord fields except topic and messages. packages/microservices/interfaces/microservice-configuration.interface.ts:333-355 The Kafka client constructs records with a normalized pattern as topic and serialized event data as messages, merges options.send into that object, then calls producer.send(). packages/microservices/client/client-kafka.ts:339-360 The same construction occurs for individual events and request messages. packages/microservices/client/client-kafka.ts:363-376 packages/microservices/client/client-kafka.ts:407-424 Server replies likewise form a record from the reply topic and serialized message, merge options.send, and send it. packages/microservices/server/server-kafka.ts:304-326

This interface contains no runtime validation, error handling, or side-effecting implementation; it only declares the object shape. packages/microservices/external/kafka.interface.ts:740-746