confluentinc / confluentinc/confluent-kafka-javascript

Incorrect Kafka Initialization Example in README Causing TypeScript Error

Open
#225 4 comments 1 reaction 0 assignees View on GitHub
documentation
Dominant language
TypeScript
Stars
304
Forks
45
Avg merge
11h 47m
Merged PRs (30d)
5

Description

**Environment Information**
- OS [e.g. Mac, Arch, Windows 10]: Mac
- Node Version [e.g. 8.2.1]: 22.12.0
- NPM Version [e.g. 5.4.2]: 10.9.0
- C++ Toolchain [e.g. Visual Studio, llvm, g++]: -
- confluent-kafka-javascript version [e.g. 2.3.3]: 1.0.0

### Overview

To connect to Kafka, the `class Kafka` from `('@confluentinc/kafka-javascript').KafkaJS` is used to manage connections and create Producers and Consumers. However, incorrect initialization methods are presented in the README and some example codes, causing errors.

### Problematic Code

Extracted and slightly modified from the [README](https://github.com/confluentinc/confluent-kafka-javascript?tab=readme-ov-file#getting-started) and Confluent Kafka Node.js Client examples

```ts
import {KafkaJS} from "@confluentinc/kafka-javascript";

const {Kafka} = KafkaJS;

async function produce(config?: ProducerConstructorConfig): Promise {
// create a new producer instance
const producer = new Kafka().producer(config);
}

async function consume(config: ConsumerConstructorConfig) {
const consumer = new Kafka().consumer(config);
}
```

### Error Message

```text
TS2554: Expected 1 arguments, but got 0

kafkajs.d.ts(97, 15): An argument for config was not provided.
```

The `class Kafka` requires `CommonConstructorConfig` as a mandatory argument in its constructor. However, the examples
omit this argument, leading to errors.

### Cause Analysis

`CommonConstructorConfig` is a mandatory parameter that defines the detailed connection settings for the Kafka cluster. While omitting this argument does not cause issues in JavaScript, it results in a type error in TypeScript.

### Proposed Solutions

1. Make `CommonConstructorConfig` Optional in `class Kafka`
- **Pros**: Ensures compatibility with the existing example code and prevents type errors.
- **Cons**: It may make it difficult to validate the configuration at the higher code level. Additionally, this pattern is not adopted by libraries like KafkaJS or node-rdkafka.
2. Modify the Example Code to Use `new Kafka({})`
- **Pros**: The problem can be resolved by updating the examples without changing the codebase.
- [Some examples in the repository](https://github.com/confluentinc/confluent-kafka-javascript/blob/65451d9058442d12c24d391684fb2cd1a3753dd1/examples/kafkajs/producer.js#L5-L15) and the [migration guide](https://github.com/confluentinc/confluent-kafka-javascript/blob/master/MIGRATION.md#kafkajs) already use this approach. This ensures consistent conventions without requiring code-level changes.
- **Cons**: May not be backward-compatible with existing users. Additionally, it is necessary to verify if this
approach aligns with the philosophy of the library.

### Additional Questions
The `confluent-kafka-javascript` library appears to be designed based on `node-rdkafka` and `KafkaJS`. Is it a long-term goal to migrate all functionalities of KafkaJS into this library?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.