# PartitionerArgs

**Kind:** Interface

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

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

`PartitionerArgs` describes the inputs provided to a Kafka partitioning strategy when selecting a partition for an outgoing message. It combines the target topic, available partition metadata, and the message being published so custom partitioners can make deterministic routing decisions.

## Properties

| Property | Type |
|---|---|
| `topic` | `string` |
| `partitionMetadata` | `PartitionMetadata[]` |
| `message` | `Message` |

## Diagram

```mermaid
graph LR
  P[PartitionerArgs] --> T[topic: string]
  P --> PM[partitionMetadata: PartitionMetadata[]]
  P --> M[message: Message]

  T --> K[Kafka topic]
  PM --> AP[Available partitions]
  M --> PS[Custom partitioning strategy]
  AP --> PS
  K --> PS
```

## Usage

```ts
import type { PartitionerArgs } from '@nestjs/microservices';

function selectPartition({
  topic,
  partitionMetadata,
  message,
}: PartitionerArgs): number {
  const key = message.key?.toString() ?? topic;

  let hash = 0;
  for (const character of key) {
    hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
  }

  const availablePartitions = partitionMetadata.filter(
    (partition) => partition.leader !== -1,
  );

  return hash % availablePartitions.length;
}
```

## AI Coding Instructions

- Use `message.key` when possible to ensure messages with the same key are consistently routed to the same partition.
- Filter or account for unavailable partitions in `partitionMetadata` before returning a partition index.
- Return a valid partition index based on the available metadata; avoid hardcoding partition counts.
- Keep custom partitioning deterministic, since non-deterministic routing can break ordering guarantees.
- Ensure the partitioner is registered through the Kafka client or producer configuration where custom partitioning is supported.

## How it works

`PartitionerArgs` is an exported TypeScript interface representing the argument passed to the function returned by an `ICustomPartitioner`. The surrounding file is explicitly a KafkaJS type representation and says it must not contain NestJS logic. [`packages/microservices/external/kafka.interface.ts:1-8`](packages/microservices/external/kafka.interface.ts#L1-L8) [`packages/microservices/external/kafka.interface.ts:129-135`](packages/microservices/external/kafka.interface.ts#L129-L135)

It requires three fields:

- `topic`: a `string`. [`packages/microservices/external/kafka.interface.ts:129-131`](packages/microservices/external/kafka.interface.ts#L129-L131)
- `partitionMetadata`: an array of `PartitionMetadata`, whose entries include a partition ID, leader, replicas, in-sync replicas, and an optional offline-replica list. [`packages/microservices/external/kafka.interface.ts:131`](packages/microservices/external/kafka.interface.ts#L131) [`packages/microservices/external/kafka.interface.ts:151-158`](packages/microservices/external/kafka.interface.ts#L151-L158)
- `message`: a `Message` with a required `value`; it may also contain a key, explicit partition, headers, and timestamp. [`packages/microservices/external/kafka.interface.ts:132`](packages/microservices/external/kafka.interface.ts#L132) [`packages/microservices/external/kafka.interface.ts:121-127`](packages/microservices/external/kafka.interface.ts#L121-L127)

A custom partitioner has the shape `() => (args: PartitionerArgs) => number`; therefore, its returned function receives this object and returns a numeric partition selection. `ProducerConfig.createPartitioner` optionally accepts that custom-partitioner factory. [`packages/microservices/external/kafka.interface.ts:110-119`](packages/microservices/external/kafka.interface.ts#L110-L119) [`packages/microservices/external/kafka.interface.ts:135-137`](packages/microservices/external/kafka.interface.ts#L135-L137)

For example, an integration controller destructures `message` from `PartitionerArgs` and returns the numeric value of the `toPartition` message header; it assigns that function to `producer.createPartitioner`. [`integration/microservices/src/kafka-concurrent/kafka-concurrent.controller.ts:18-22`](integration/microservices/src/kafka-concurrent/kafka-concurrent.controller.ts#L18-L22) [`integration/microservices/src/kafka-concurrent/kafka-concurrent.controller.ts:39-41`](integration/microservices/src/kafka-concurrent/kafka-concurrent.controller.ts#L39-L41)

`PartitionerArgs` itself declares no methods, validation, thrown errors, or runtime side effects. [`packages/microservices/external/kafka.interface.ts:129-133`](packages/microservices/external/kafka.interface.ts#L129-L133)