You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/12/04 09:57:25 UTC
[GitHub] [pulsar-client-node] tisonkun commented on a diff in pull request #255: Change the require path in examples and refactor README
tisonkun commented on code in PR #255:
URL: https://github.com/apache/pulsar-client-node/pull/255#discussion_r1038941160
##########
README.md:
##########
@@ -26,77 +26,119 @@ 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.
-
-### Use `npm`
+To use the Pulsar Node.js client in your project, run:
```shell
npm install pulsar-client
```
-### Use `yarn`
+for `npm` users or
```shell
yarn add pulsar-client
```
-After install, you can run the [examples](https://github.com/apache/pulsar-client-node/tree/master/examples).
+for `yarn` users.
+
+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")
+ });
-### Prebuilt binaries
+ // Receive the message
+ const msg = await consumer.receive();
+ console.log(msg.getData().toString());
+ consumer.acknowledge(msg);
-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:
+ 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 will see the following output:
-`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
-```
-
-#### Install C++ client on Linux:
-```shell
+```bash
build-support/install-cpp-client.sh
```
-#### Install C++ client on Windows (required preinstall `curl` and `7z`):
-```shell
+- Install C++ client on Windows:
+
+```
pkg\windows\download-cpp-client.bat
```
-### 3. Build NAPI from source
+- Install C++ client on macOS:
+
+```
Review Comment:
````suggestion
```bash
````
ditto other code block. Please go through.
##########
README.md:
##########
@@ -26,77 +26,119 @@ 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.
-
-### Use `npm`
+To use the Pulsar Node.js client in your project, run:
```shell
npm install pulsar-client
```
-### Use `yarn`
+for `npm` users or
```shell
yarn add pulsar-client
```
-After install, you can run the [examples](https://github.com/apache/pulsar-client-node/tree/master/examples).
+for `yarn` users.
Review Comment:
```suggestion
```
##########
README.md:
##########
@@ -26,77 +26,119 @@ 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.
-
-### Use `npm`
+To use the Pulsar Node.js client in your project, run:
```shell
npm install pulsar-client
```
-### Use `yarn`
+for `npm` users or
```shell
yarn add pulsar-client
```
-After install, you can run the [examples](https://github.com/apache/pulsar-client-node/tree/master/examples).
+for `yarn` users.
+
+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")
+ });
-### Prebuilt binaries
+ // Receive the message
+ const msg = await consumer.receive();
+ console.log(msg.getData().toString());
+ consumer.acknowledge(msg);
-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:
+ 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 will see the following output:
-`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
-```
-
-#### Install C++ client on Linux:
-```shell
+```bash
build-support/install-cpp-client.sh
```
-#### Install C++ client on Windows (required preinstall `curl` and `7z`):
-```shell
+- Install C++ client on Windows:
+
+```
pkg\windows\download-cpp-client.bat
```
-### 3. Build NAPI from source
+- Install C++ client on macOS:
+
+```
+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 --build-from-source
+npm install
```
+To verify it has been installed successfully, you can run an example like:
+
+```bash
+$ node examples/producer
Review Comment:
````suggestion
node examples/producer
```
You should find the output as:
```
````
##########
README.md:
##########
@@ -26,77 +26,119 @@ 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.
-
-### Use `npm`
+To use the Pulsar Node.js client in your project, run:
```shell
npm install pulsar-client
```
-### Use `yarn`
+for `npm` users or
Review Comment:
```suggestion
or
```
I believe either `npm` users or `yarn `users can read this section. And basically we write:
```
npm:
... npm stuff
yarn:
... yarn stuff
```
instead of here:
```
... npm stuff
for npm users
... yarn stuff
for yarn users
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org