You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by xy...@apache.org on 2022/12/05 04:38:50 UTC
[pulsar-client-node] branch master updated: Change the require path in examples and refactor README (#255)
This is an automated email from the ASF dual-hosted git repository.
xyz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar-client-node.git
The following commit(s) were added to refs/heads/master by this push:
new 7b267d4 Change the require path in examples and refactor README (#255)
7b267d4 is described below
commit 7b267d48d323f174c6c432be5d6210958bb2eb92
Author: Yunze Xu <xy...@163.com>
AuthorDate: Mon Dec 5 12:38:45 2022 +0800
Change the require path in examples and refactor README (#255)
* Change the require path in examples and simplify README
### Motivation
Currently, the scripts in `examples` directory all requires a
`pulsar-client` module installed. However, they might use some latest
APIs that were not included in official releases. We should force users
to build the client before running the examples.
### Modifications
Change `require('pulsar-client')` to `require('..')` in all `*.js`
scripts under the `examples` directory.
Simplify the README to two parts:
1. How to install the official released `pulsar-client` module.
2. How to build the artifacts and run the examples based on latest code.
Co-authored-by: tison <wa...@gmail.com>
---
README.md | 113 +++++++++++++++++++++++++++++-----------
examples/consumer.js | 2 +-
examples/consumer_listener.js | 2 +-
examples/consumer_tls_auth.js | 2 +-
examples/encryption-consumer.js | 2 +-
examples/encryption-producer.js | 2 +-
examples/producer.js | 2 +-
examples/producer_tls_auth.js | 2 +-
examples/reader.js | 2 +-
examples/reader_listener.js | 2 +-
10 files changed, 91 insertions(+), 40 deletions(-)
diff --git a/README.md b/README.md
index 8068ec6..c52e4a5 100644
--- a/README.md
+++ b/README.md
@@ -26,77 +26,128 @@ The Pulsar Node.js client can be used to create Pulsar producers and consumers i
This library works only in Node.js 10.x or later because it uses the
[node-addon-api](https://github.com/nodejs/node-addon-api) module to wrap the C++ library.
-## How to install
+## 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.
-### Use `npm`
+To use the Pulsar Node.js client in your project, run:
```shell
npm install pulsar-client
```
-### Use `yarn`
+or
```shell
yarn add pulsar-client
```
-After install, you can run the [examples](https://github.com/apache/pulsar-client-node/tree/master/examples).
-
-### Prebuilt binaries
-
-The module uses [node-pre-gyp](https://github.com/mapbox/node-pre-gyp) to download the prebuilt binary for your platform, if it exists.
-These binaries are hosted on ASF dist subversion. The following targets are currently provided:
+Then you can run the following simple end-to-end example:
+
+```javascript
+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();
+})();
+```
-Format: `napi-{platform}-{libc}-{arch}`
-- napi-darwin-unknown-x64.tar.gz
-- napi-linux-glibc-arm64.tar.gz
-- napi-linux-glibc-x64.tar.gz
-- napi-linux-musl-arm64.tar.gz
-- napi-linux-musl-x64.tar.gz
-- napi-win32-unknown-ia32.tar.gz
-- napi-win32-unknown-x64.tar.gz
+You should find the output as:
-`darwin-arm64` systems are not currently supported, you can refer `How to build` to build from source.
+```
+hello
+```
+You can see more examples in the [examples](./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
-### 1. Clone repository.
+First, clone the repository.
+
```shell
git clone https://github.com/apache/pulsar-client-node.git
cd pulsar-client-node
```
-### 2. Install C++ client.
+Since this client is a [C++ addon](https://nodejs.org/api/addons.html#c-addons) that depends on the [Pulsar C++ client](https://github.com/apache/pulsar-client-cpp), 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.
-Select the appropriate installation method from below depending on your operating system:
+- Install C++ client on Linux:
-#### Install C++ client on macOS:
```shell
-pkg/mac/build-cpp-deps-lib.sh
-pkg/mac/build-cpp-lib.sh
+build-support/install-cpp-client.sh
```
-#### Install C++ client on Linux:
+- Install C++ client on Windows:
+
```shell
-build-support/install-cpp-client.sh
+pkg\windows\download-cpp-client.bat
```
-#### Install C++ client on Windows (required preinstall `curl` and `7z`):
+- Install C++ client on macOS:
+
```shell
-pkg\windows\download-cpp-client.bat
+pkg/mac/build-cpp-deps-lib.sh
+pkg/mac/build-cpp-lib.sh
+```
+
+After the C++ client is installed, run the following command to build this C++ addon.
+
+```shell
+npm install
```
-### 3. Build NAPI from source
+To verify it has been installed successfully, you can run an example like:
```shell
-npm install --build-from-source
+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
-* Please see https://pulsar.apache.org/docs/client-libraries-node/ for more details about the Pulsar Node.js client.
+* Please see https://pulsar.apache.org/docs/client-libraries-node/ for more details about the Pulsar Node.js client.
diff --git a/examples/consumer.js b/examples/consumer.js
index 5d124a1..f1c130d 100644
--- a/examples/consumer.js
+++ b/examples/consumer.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client
diff --git a/examples/consumer_listener.js b/examples/consumer_listener.js
index 8db2e7d..df3c4ed 100644
--- a/examples/consumer_listener.js
+++ b/examples/consumer_listener.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client
diff --git a/examples/consumer_tls_auth.js b/examples/consumer_tls_auth.js
index bc706f7..b4e5cec 100644
--- a/examples/consumer_tls_auth.js
+++ b/examples/consumer_tls_auth.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
const auth = new Pulsar.AuthenticationTls({
diff --git a/examples/encryption-consumer.js b/examples/encryption-consumer.js
index df3cc37..4b00a24 100644
--- a/examples/encryption-consumer.js
+++ b/examples/encryption-consumer.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client
diff --git a/examples/encryption-producer.js b/examples/encryption-producer.js
index b6dff9e..a3e2bd8 100644
--- a/examples/encryption-producer.js
+++ b/examples/encryption-producer.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client
diff --git a/examples/producer.js b/examples/producer.js
index cdd6c9c..b859a17 100644
--- a/examples/producer.js
+++ b/examples/producer.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client
diff --git a/examples/producer_tls_auth.js b/examples/producer_tls_auth.js
index dca5fd9..790a85f 100644
--- a/examples/producer_tls_auth.js
+++ b/examples/producer_tls_auth.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
const auth = new Pulsar.AuthenticationTls({
diff --git a/examples/reader.js b/examples/reader.js
index fdd9fa1..00c168e 100644
--- a/examples/reader.js
+++ b/examples/reader.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client
diff --git a/examples/reader_listener.js b/examples/reader_listener.js
index 63809a6..2cb1cd2 100644
--- a/examples/reader_listener.js
+++ b/examples/reader_listener.js
@@ -17,7 +17,7 @@
* under the License.
*/
-const Pulsar = require('pulsar-client');
+const Pulsar = require('../');
(async () => {
// Create a client