tag	6c0af95ecb56b7312c1e538bf51fe9a1b3b80a2b
tagger	Baodi Shi <baodi@apache.org>	Tue Jul 02 17:52:43 2024 +0800
object	3c0c4c105516dd6a8d9d8da4516fb7412a1a9493

commit	3c0c4c105516dd6a8d9d8da4516fb7412a1a9493	[log] [tgz]
author	Baodi Shi <baodi@apache.org>	Tue Jul 02 17:52:02 2024 +0800
committer	Baodi Shi <baodi@apache.org>	Tue Jul 02 17:52:02 2024 +0800
tree	9929020cc748943f077dc23f4ca7e42928e45c50
parent	f20c2b8d1efe3e85c003e24c232820860b58134c [diff]

tree: 9929020cc748943f077dc23f4ca7e42928e45c50

README.md

Pulsar Node.js client library

The Pulsar Node.js client can be used to create Pulsar producers and consumers in Node.js. For the supported Pulsar features, see Client Feature Matrix.

This library works only in Node.js 12.3 or later because it uses:

The node-addon-api module to wrap the C++ library.
The Mozilla CA file, which is provided by Node.js v12.3.0 and subsequent versions.

Getting Started

Note
These instructions are only available for versions after 1.8.0. For versions previous to 1.8.0, you need to install the C++ client first. Please switch to the corresponding version branch of this repo to read the specific instructions.
To run the examples, skip this section.

To use the Pulsar Node.js client in your project, run:

npm install pulsar-client

yarn add pulsar-client

Then you can run the following simple end-to-end example:

const Pulsar = require('pulsar-client');

(async () => {
  // Create a client
  const client = new Pulsar.Client({
    serviceUrl: 'pulsar://localhost:6650'
  });

  // Create a producer
  const producer = await client.createProducer({
    topic: 'persistent://public/default/my-topic',
  });

  // Create a consumer
  const consumer = await client.subscribe({
    topic: 'persistent://public/default/my-topic',
    subscription: 'sub1'
  });

  // Send a message
  producer.send({
    data: Buffer.from("hello")
  });

  // Receive the message
  const msg = await consumer.receive();
  console.log(msg.getData().toString());
  consumer.acknowledge(msg);

  await producer.close();
  await consumer.close();
  await client.close();
})();

You should find the output as:

hello

You can see more examples in the examples directory. However, since these examples might use an API that was not released yet, you need to build this module. See the next section.

How to build

Note
Building from source code requires a Node.js version greater than 16.18.

First, clone the repository.

git clone https://github.com/apache/pulsar-client-node.git
cd pulsar-client-node

Since this client is a C++ addon that depends on the Pulsar C++ client, you need to install the C++ client first. You need to ensure there is a C++ compiler that supports C++11 installed in your system.

Install C++ client on Linux:

pkg/linux/download-cpp-client.sh

Install C++ client on Windows:

pkg\windows\download-cpp-client.bat

Install C++ client on macOS:

pkg/mac/download-cpp-client.sh

After the C++ client is installed, run the following command to build this C++ addon.

npm install

To verify it has been installed successfully, you can run an example like:

Note
A running Pulsar server is required. The example uses pulsar://localhost:6650 to connect to the server.

node examples/producer

You should find the output as:

Sent message: my-message-0
Sent message: my-message-1
Sent message: my-message-2
Sent message: my-message-3
Sent message: my-message-4
Sent message: my-message-5
Sent message: my-message-6
Sent message: my-message-7
Sent message: my-message-8
Sent message: my-message-9

Documentation

For more details about Pulsar Node.js clients, see Pulsar docs.

Contribute

Contributions are welcomed and greatly appreciated.

If your contribution adds Pulsar features for Node.js clients, you need to update both the Pulsar docs and the Client Feature Matrix. See Contribution Guide for more details.

Generate API docs

npm install
npx typedoc
# Documentation generated at ./apidocs