# PartitionOffset

**Kind:** Interface

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

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

`PartitionOffset` represents a Kafka consumer position within a specific topic partition. It pairs a numeric partition identifier with a string offset, allowing Kafka-related integrations to track, commit, or seek to an exact message position.

## Properties

| Property | Type |
|---|---|
| `partition` | `number` |
| `offset` | `string` |

## Diagram

```mermaid
graph LR
  Consumer[Kafka Consumer] --> PartitionOffset
  PartitionOffset --> Partition[partition: number]
  PartitionOffset --> Offset[offset: string]
  PartitionOffset --> Commit[Commit or seek consumer position]
```

## Usage

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

const checkpoint: PartitionOffset = {
  partition: 2,
  offset: '1542',
};

// Example: use the position when committing processed messages.
await consumer.commitOffsets([
  {
    topic: 'orders',
    partition: checkpoint.partition,
    offset: checkpoint.offset,
  },
]);
```

## AI Coding Instructions

- Keep `partition` as a zero-based numeric Kafka partition index.
- Store `offset` as a string; Kafka client libraries commonly use string offsets to avoid integer precision issues.
- Use this interface when passing partition-specific checkpoints between consumer, retry, seek, or commit logic.
- Do not treat the offset as the currently processed message unless the surrounding Kafka client API explicitly defines it that way; commit semantics often expect the next offset to consume.

## How it works

`PartitionOffset` is an exported TypeScript interface representing an offset for one Kafka partition. It has two required properties:

- `partition`: a `number` identifying the partition. [packages/microservices/external/kafka.interface.ts:771-773]
- `offset`: a `string` representing that partition’s offset. [packages/microservices/external/kafka.interface.ts:771-774]

It is a type-only declaration in a file intended to represent KafkaJS package types, not NestJS logic. [packages/microservices/external/kafka.interface.ts:1-8] The interface contains no runtime implementation, validation, error handling, or side effects. [packages/microservices/external/kafka.interface.ts:771-774]

The type is used in several offset-oriented shapes:

- `TopicOffsets.partitions` is an array of `PartitionOffset` values, grouped under a topic string. [packages/microservices/external/kafka.interface.ts:776-783]
- `SeekEntry` is an alias of `PartitionOffset`. [packages/microservices/external/kafka.interface.ts:438]
- `FetchOffsetsPartition` extends it with required `metadata: string | null`. [packages/microservices/external/kafka.interface.ts:440-442]
- `Admin.fetchTopicOffsets()` returns entries containing these fields plus `high` and `low` string fields; `fetchTopicOffsetsByTimestamp()` returns `SeekEntry` values. [packages/microservices/external/kafka.interface.ts:526-532]
- `Admin.setOffsets()` and `Admin.deleteTopicRecords()` accept arrays of `SeekEntry` values in their `partitions` options. [packages/microservices/external/kafka.interface.ts:538-542] [packages/microservices/external/kafka.interface.ts:562-565]