confluentinc / confluentinc/confluent-kafka-javascript
Incorrect Kafka Initialization Example in README Causing TypeScript Error
- 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
Assessment
This issue has not been assessed yet.