Skip to content

Commit 218548c

Browse files
yeshamavaniyeshamavani
authored
Merge pull request #54 from sourcefuse/GH-53
docs(chore): copy the Readme to root as well
2 parents e042c6f + c88a289 commit 218548c

File tree

1 file changed

+181
-0
lines changed

1 file changed

+181
-0
lines changed

‎README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
<a href="https://sourcefuse.github.io/arc-docs/arc-api-docs" target="_blank"><img src="https://github.com/sourcefuse/loopback4-microservice-catalog/blob/master/docs/assets/logo-dark-bg.png?raw=true" alt="ARC By SourceFuse logo" title="ARC By SourceFuse" align="right" width="150" /></a>
2+
3+
# [loopback4-kafka-client](https://github.com/sourcefuse/loopback4-kafka-client)
4+
5+
<p align="left">
6+
<a href="https://www.npmjs.com/package/loopback4-kafka-client">
7+
<img src="https://img.shields.io/npm/v/loopback4-kafka-client.svg" alt="npm version" />
8+
</a>
9+
<a href="https://sonarcloud.io/summary/new_code?id=sourcefuse_loopback4-kafka-client" target="_blank">
10+
<img alt="Sonar Quality Gate" src="https://img.shields.io/sonar/quality_gate/sourcefuse_loopback4-kafka-client?server=https%3A%2F%2Fsonarcloud.io">
11+
</a>
12+
<a href="https://github.com/sourcefuse/loopback4-kafka-client/graphs/contributors" target="_blank">
13+
<img alt="GitHub contributors" src="https://img.shields.io/github/contributors/sourcefuse/loopback4-kafka-client">
14+
</a>
15+
<a href="https://www.npmjs.com/package/loopback4-kafka-client" target="_blank">
16+
<img alt="downloads" src="https://img.shields.io/npm/dw/loopback4-kafka-client.svg">
17+
</a>
18+
<a href="https://github.com/sourcefuse/loopback4-kafka-client/blob/master/LICENSE">
19+
<img src="https://img.shields.io/github/license/sourcefuse/loopback4-kafka-client.svg" alt="License" />
20+
</a>
21+
<a href="https://loopback.io/" target="_blank">
22+
<img alt="Powered By LoopBack 4" src="https://img.shields.io/badge/Powered%20by-LoopBack 4-brightgreen" />
23+
</a>
24+
</p>
25+
26+
27+
## Overview
28+
29+
A Kafka Client for Loopback4 built on top of [KafkaJS](https://kafka.js.org/).
30+
31+
## Installation
32+
33+
Install KafkaConnectorComponent using `npm`;
34+
35+
```sh
36+
$ [npm install | yarn add] loopback4-kafka-client
37+
```
38+
39+
## Basic Use
40+
41+
Configure and load KafkaConnectorComponent in the application constructor
42+
as shown below.
43+
44+
```ts
45+
import {
46+
KafkaClientBindings,
47+
KafkaClientComponent,
48+
KafkaClientOptions,
49+
} from 'loopback4-kafka-client';
50+
// ...
51+
export class MyApplication extends BootMixin(
52+
ServiceMixin(RepositoryMixin(RestApplication)),
53+
) {
54+
constructor(options: ApplicationConfig = {}) {
55+
this.configure<KafkaClientOptions>(KafkaClientBindings.Component).to({
56+
initObservers: true, // if you want to init consumer lifeCycleObserver
57+
topics: [Topics.First], // if you want to use producers for given topics
58+
connection: {
59+
// refer https://kafka.js.org/docs/configuration
60+
brokers: [process.env.KAFKA_SERVER ?? ''],
61+
},
62+
});
63+
this.bind(KafkaClientBindings.ProducerConfiguration).to({
64+
// your producer config
65+
// refer https://kafka.js.org/docs/producing#options
66+
});
67+
this.bind(KafkaClientBindings.ConsumerConfiguration).to({
68+
// refer https://kafka.js.org/docs/consuming#options
69+
groupId: process.env.KAFKA_CONSUMER_GROUP,
70+
});
71+
72+
this.component(KafkaClientComponent);
73+
// ...
74+
}
75+
// ...
76+
}
77+
```
78+
79+
#### Producer and Consumer
80+
81+
### Stream
82+
83+
Producers and Consumers work on a `Stream` which defines the topic and events used by the application. You can implement the `IStreamDefinition` to create your own stream class.
84+
85+
##### Example
86+
87+
```ts
88+
export class TestStream implements IStreamDefinition {
89+
topic = Topics.First;
90+
messages: {
91+
// [<event type key from enum>] : <event type or interface>
92+
[Events.start]: StartEvent;
93+
[Events.stop]: StopEvent;
94+
};
95+
}
96+
```
97+
98+
### Consumer
99+
100+
A Consumer is a [`loopback extension`](https://loopback.io/doc/en/lb4/Extension-point-and-extensions.html) that is used by the [`KafkaConsumerService`](./src/services/kafka-consumer.service.ts) to initialize consumers. It must implement the `IConsumer` interface and should be using the `@consumer()` decorator. If you want the consumers to start at the start of your application, you should pass the `initObservers` config to the Component configuration.
101+
102+
##### Example
103+
104+
```ts
105+
// application.ts
106+
this.configure(KafkaConnectorComponentBindings.COMPONENT).to({
107+
...
108+
initObservers: true
109+
...
110+
});
111+
```
112+
113+
```ts
114+
// start.consumer.ts
115+
@consumer<TestStream, Events.start>()
116+
export class StartConsumer implements IConsumer<TestStream, Events.start> {
117+
constructor(
118+
@inject('test.handler.start')
119+
public handler: StreamHandler<TestStream, Events.start>,
120+
) {}
121+
topic: Topics.First = Topics.First;
122+
event: Events.start = Events.start;
123+
// you can write the handler as a method
124+
handler(payload: StartEvent) {
125+
console.log(payload);
126+
}
127+
}
128+
```
129+
130+
If you want to write a shared handler for different events, you can use the `eventHandlerKey` to bind a handler in the application -
131+
132+
```ts
133+
// application.ts
134+
this.bind(eventHandlerKey(Events.Start)).to((payload: StartEvent) => {
135+
console.log(payload);
136+
});
137+
this.bind(eventHandlerKey<TestStream, Events.Stop>(Events.Stop)).toProvider(
138+
CustomEventHandlerProvider,
139+
);
140+
```
141+
142+
and then you can use the handler using the `@eventHandler` decorator -
143+
144+
```ts
145+
// start.consumer.ts
146+
@consumer<TestStream, Events.start>()
147+
export class StartConsumer implements IConsumer<TestStream, Events.start> {
148+
constructor(
149+
@eventHandler<TestStream>(Events.Start)
150+
public handler: StreamHandler<TestStream, Events.start>,
151+
) {}
152+
topic: Topics.First = Topics.First;
153+
event: Events.start = Events.start;
154+
}
155+
```
156+
157+
### Producer
158+
159+
A Producer is a loopback service for producing message for a particular topic, you can inject a producer using the `@producer(TOPIC_NAME)` decorator.
160+
Note: The topic name passed to decorator must be first configured in the Component configuration's topic property -
161+
162+
#### Example
163+
164+
```ts
165+
// application.ts
166+
...
167+
this.configure(KafkaConnectorComponentBindings.COMPONENT).to({
168+
...
169+
topics: [Topics.First],
170+
...
171+
});
172+
...
173+
// test.service.ts
174+
...
175+
class TestService {
176+
constructor(
177+
@producer(Topics.First)
178+
private producer: Producer<TestStream>
179+
) {}
180+
}
181+
```

0 commit comments

Comments
 (0)