![\"Nest](\"https://nestjs.com/img/logo-small.svg\"){kind=logo}
\n\n \n
A progressive Node.js framework for building efficient and scalable server-side applications.
\n\n## Description\n\n[Apache Pulsar](https://pulsar.apache.org) module for [Nest](https://nestjs.com).\n\nBased on https://www.npmjs.com/package/nest-pulsar with dependency updates and small improvements.\n\n## Installation\n\n```bash\n$ npm i @dev5c32373043/nestjs-pulsar\n```\n\n> **Note**\n>\n> Pulsar Node.js client library is based on the C++ client library. You must install the Pulsar C++ client library before installing a Node.js client. For more details, see [pulsar-client-node on GitHub](https://github.com/apache/pulsar-client-node) or [The Pulsar Node.js client dedicated page](https://pulsar.apache.org/docs/3.0.x/client-libraries-node/) on [Apache Pulsar documentation](https://pulsar.apache.org/docs/3.0.x/).\n\n## Getting started\n\nOnce the installation process (npm install) is complete, we can import the `PulsarModule` into the root `AppModule`.\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forRoot({\n serviceUrl: 'pulsar://localhost:6650',\n }),\n ],\n})\nexport class AppModule {}\n```\n\nThe `forRoot()` method supports all the configuration properties exposed by the Client class constructor from the [`pulsar-client`](https://www.npmjs.com/package/pulsar-client) package.\n\n> **Note**\n>\n> `forRoot()` inject the Pulsar Client provider globally.\n\nNext, let's look at another module, let's say the `UsersModule`.\n\nOnce the pulsar Client configured. You can inject the needed `Producer`, `Consumer`, `Reader` using the `forFeature()` method:\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule, MessageId } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forFeature('producer', 'my-producer', {\n topic: 'my-topic',\n }),\n PulsarModule.forFeature('consumer', 'my-consumer', {\n topic: 'my-topic',\n subscription: 'my-sub',\n }),\n PulsarModule.forFeature('reader', 'my-reader', {\n topic: 'my-topic',\n startMessageId: MessageId.earliest(),\n }),\n ],\n})\nexport class UsersModule {}\n```\n\n> **Warning**\n>\n> Producer, consumer, reader name (2nd param) is mandatory. Please note that you shouldn't have multiple producers, consumers or readers with the same name, otherwise they will get overridden.\n\nThe `forFeature()` method third param supports all the configuration properties exposed by the following Pulsar `Client` factory methods:\n\n- `producer` feature configuration object corresponds to `client.createProducer()` configuration object.\n- `consumer` feature configuration object corresponds to `client.subscribe()` configuration object.\n- `reader` feature configuration object corresponds to `client.createReader()` configuration object.\n\nThis module uses the `forFeature()` method to define which features (producer, consumer or reader) are registered in the current scope. With that in place, we can inject the `Producer`, `Consumer` and `Reader` Pulsar objects into the UsersService using the @PulsarInject() decorator:\n\n```ts\nimport { Injectable } from '@nestjs/common';\nimport { InjectPulsar, Producer, Consumer, Reader } from '@dev5c32373043/nestjs-pulsar';\n\n@Injectable()\nexport class UsersService {\n constructor(\n @InjectPulsar('producer', 'my-producer')\n private readonly producer: Producer,\n @InjectPulsar('consumer', 'my-consumer')\n private readonly consumer: Consumer,\n @InjectPulsar('reader', 'my-reader')\n private readonly reader: Reader,\n ) {}\n\n async publish(data: any) {\n await this.producer.send({ data: Buffer.from(JSON.stringify(data)) });\n }\n\n async consume(timeout: number = 1000) {\n const rawMessage = await this.consumer.receive(timeout); // timeout is optional\n const data = JSON.parse(rawMessage.getData().toString());\n await this.consumer.acknowledge(rawMessage);\n\n return data;\n }\n\n async read() {\n if (!this.reader.hasNext()) return;\n\n const rawMessage = await this.reader.readNext();\n const data = JSON.parse(rawMessage.getData().toString());\n\n return data;\n }\n}\n```\n\nIf you want to use the producer, consumer or reader outside of the module which imports `PulsarModule.forFeature()`, you'll need to re-export the providers generated by it. You can do this by exporting the whole module, like this:\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forFeature('producer', 'my-producer', {\n topic: 'my-topic',\n }),\n PulsarModule.forFeature('consumer', 'my-consumer', {\n topic: 'my-topic',\n subscription: 'my-sub',\n }),\n PulsarModule.forFeature('reader', 'my-reader', {\n topic: 'my-topic',\n }),\n ],\n exports: [PulsarModule],\n})\nexport class UsersModule {}\n```\n\n## Async configuration\n\nYou may want to pass your module options asynchronously instead of statically. In this case, use the `forRootAsync()` method:\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forRootAsync({\n useFactory: () => ({\n serviceUrl: 'pulsar://localhost:6650',\n }),\n }),\n ],\n})\nexport class AppModule {}\n```\n\nOur factory behaves like any other asynchronous provider (e.g., it can be async and it's able to inject dependencies through inject):\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forRootAsync({\n imports: [ConfigModule],\n inject: [ConfigService],\n useFactory: (config: ConfigService) => ({\n serviceUrl: config.get('SERVICE_URL'),\n }),\n }),\n ],\n})\nexport class AppModule {}\n```\n\n## Multiple clients\n\nSome projects require multiple pulsar clients. This can also be achieved with this module. To work with multiple clients, first create the clients. In this case, client naming becomes mandatory.\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forRoot({\n serviceUrl: 'pulsar://localhost:6650',\n }),\n PulsarModule.forRoot(\n {\n serviceUrl: 'pulsar://other.client:6650',\n },\n 'other-client', // client name\n ),\n ],\n})\nexport class AppModule {}\n```\n\n> **Warning**\n>\n> If you don't set the name for a client, its name is set to default. Please note that you shouldn't have multiple clients without a name, or with the same name, otherwise they will get overridden.\n\nIf you are using `PulsarModule.forRootAsync()`, you have to also set the client name the same way:\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { PulsarModule } from '@dev5c32373043/nestjs-pulsar';\n\n@Module({\n imports: [\n PulsarModule.forRootAsync({\n useFactory: () => ({\n serviceUrl: 'pulsar://localhost:6650',\n }),\n }),\n PulsarModule.forRootAsync(\n {\n useFactory: () => ({\n serviceUrl: 'pulsar://other.client:6650',\n }),\n },\n 'other-client',\n ),\n ],\n})\nexport class AppModule {}\n```\n\n## Testing\n\nWhen it comes to unit testing an application, we usually want to avoid making a real Pulsar connection, keeping our test suites independent and their execution process as fast as possible. But our classes might depend on producers, consumers or readears that are pulled that are created from the client instance. How do we handle that? The solution is to create mocks. In order to achieve that, we set up custom providers. Each registered producer, consumer or reader is automatically represented by an auto-generated token.\n\nThe @dev5c32373043/nestjs-pulsar package exposes the `getFeatureToken()` function which returns a prepared token based on a given feature type and name.\n\n```ts\n@Module({\n providers: [\n UsersService,\n {\n provide: getFeatureToken('consumer', 'my-consumer'),\n useValue: mockConsumer,\n },\n ],\n})\nexport class UsersModule {}\n```\n\nNow a substitute mockConsumer will be used as the `Consumer` named `myConsumer`. Whenever any class asks for `myConsumer` using an `@PulsarInject()` decorator, Nest will use the registered mockConsumer object.\n\n## License\n\nNest Pulsar is [MIT licensed](LICENSE).\n","readmeFilename":"README.md"}