# OffsetsByTopicPartition

**Kind:** Interface

**Source:** [`packages/microservices/external/kafka.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/external/kafka.interface.ts#L990)

**Part of:** [Microservices](subsystem-packages-microservices)

`OffsetsByTopicPartition` groups Kafka offset information by topic and partition. It is used when reading, committing, or reporting consumer positions across one or more Kafka topics in the microservices Kafka integration.

## Properties

| Property | Type |
|---|---|
| `topics` | `TopicOffsets[]` |

## Diagram

```mermaid
graph LR
  A[OffsetsByTopicPartition] --> B[topics: TopicOffsets[]]
  B --> C[Topic offset entry]
  C --> D[Kafka topic]
  C --> E[Partition offsets]
```

## Usage

```ts
import type { OffsetsByTopicPartition } from './kafka.interface';

const offsets: OffsetsByTopicPartition = {
  topics: [
    {
      topic: 'orders',
      partitions: [
        { partition: 0, offset: '142' },
        { partition: 1, offset: '98' },
      ],
    },
    {
      topic: 'payments',
      partitions: [{ partition: 0, offset: '51' }],
    },
  ],
};

// Pass the grouped offsets to Kafka consumer offset handling logic.
await consumer.commitOffsets(offsets.topics.flatMap((topic) => topic.partitions));
```

## AI Coding Instructions

- Populate `topics` with `TopicOffsets` entries; do not place partition offsets directly on `OffsetsByTopicPartition`.
- Preserve Kafka offsets as strings when required by the underlying client to avoid JavaScript integer precision issues.
- Group offsets by their Kafka topic before constructing this interface.
- Validate that each partition belongs to the topic named by its corresponding `TopicOffsets` entry.
- Use this type at Kafka consumer integration boundaries for offset commit, seek, or lag-reporting workflows.