mqtt-json-rpc 1.3.7 → 2.1.0

package/README.md

@@ -20,13 +20,13 @@ $ npm install mqtt mqtt-json-rpc
 About
 -----
 
-This is a small wrapper around the
+This is an addon API for the
 [MQTT.js](https://www.npmjs.com/package/mqtt) API of
 [Node.js](https://nodejs.org/), for
 [Remote Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call) (RPC)
 communication based on the [JSON-RPC](http://www.jsonrpc.org/)
 protocol. This allows a bi-directional request/response-style communication over
-the uni-directional message protocol [MQTT](http://mqtt.org).
+the technically uni-directional message protocol [MQTT](http://mqtt.org).
 
 Usage
 -----
@@ -40,7 +40,7 @@ const RPC  = require("mqtt-json-rpc")
 const mqtt = MQTT.connect("wss://127.0.0.1:8889", { ... })
 const rpc  = new RPC(mqtt)
 
-rpc.on("connect", () => {
+mqtt.on("connect", () => {
     rpc.register("example/hello", (a1, a2) => {
         console.log("example/hello: request: ", a1, a2)
         return `${a1}:${a2}`
@@ -57,10 +57,10 @@ const RPC  = require("mqtt-json-rpc")
 const mqtt = MQTT.connect("wss://127.0.0.1:8889", { ... })
 const rpc  = new RPC(mqtt)
 
-rpc.on("connect", () => {
+mqtt.on("connect", () => {
     rpc.call("example/hello", "world", 42).then((response) => {
         console.log("example/hello response: ", response)
-        rpc.end()
+        mqtt.end()
     })
 })
 ```
@@ -68,21 +68,20 @@ rpc.on("connect", () => {
 Application Programming Interface
 ---------------------------------
 
-The API of MQTT-JSON-RPC is a superset of the original
-[MQTT.js](https://www.npmjs.com/package/mqtt) API because it is just a
-wrapper around it with the following additional methods:
+The MQTT-JSON-RPC API provides the following methods (check out the
+corresponding [TypeScript definition](mqtt-json-rpc.d.ts)) file):
 
-- `constructor(mqtt: MQTT, encoding?: string]): MQTT-JSON-RPC`:<br/>
-  Create the [MQTT.js](https://www.npmjs.com/package/mqtt) API wrapper.
+- `constructor(mqtt: MQTT, options?: { encoding?: string, timeout?: number }): MQTT-JSON-RPC`:<br/>
   The `mqtt` is the [MQTT.js](https://www.npmjs.com/package/mqtt) instance.
-  The optional `encoding` can be either `json` (default), `msgpack` or `cbor`.
+  The optional `encoding` option can be either `json` (default), `msgpack` or `cbor`.
+  The optional `timeout` option is the timeout in seconds.
 
 - `MQTT-JSON-RPC#registered(method: string): boolean`:<br/>
   Check for the previous registration of a method. The `method` has to
   be a valid MQTT topic name. The method returns `true` if `method` is
   already registered, else it returns `false`.
 
-- `MQTT-JSON-RPC#register(method: string, callback: (...args: any[]) => any): Promise`:<br/>
+- `MQTT-JSON-RPC#register(method: string, callback: (...args: any[]) => any): Promise<boolean>`:<br/>
   Register a method. The `method` has to be a valid MQTT topic
   name. The `callback` is called with the `params` passed to
   the remote `MQTT-JSON-RPC#notify()` or `MQTT-JSON-RPC#call()`. For
@@ -92,7 +91,7 @@ wrapper around it with the following additional methods:
   Internally, on the MQTT broker the topic `${method}/request` is
   subscribed.
 
-- `MQTT-JSON-RPC#unregister(method: string): Promise`:<br/>
+- `MQTT-JSON-RPC#unregister(method: string): Promise<void>`:<br/>
   Unregister a previously registered method.
   Internally, on the MQTT broker the topic `${method}/request` is unsubscribed.
 
@@ -100,7 +99,7 @@ wrapper around it with the following additional methods:
   Notify a method. The remote `MQTT-JSON-RPC#register()` `callback` is called
   with `params` and its return value is silently ignored.
 
-- `MQTT-JSON-RPC#call(method: string, ...params: any[]): Promise`:<br/>
+- `MQTT-JSON-RPC#call(method: string, ...params: any[]): Promise<any>`:<br/>
   Call a method. The remote `MQTT-JSON-RPC#register()` `callback` is
   called with `params` and its return value resolves the returned
   `Promise`. If the remote `callback` throws an exception, this rejects
@@ -141,7 +140,7 @@ rpc.register("example/hello", (a1, a2) => {
 })
 ```
 
-...and then its result, here `"world:42"`, is then
+...and then its result, in the above `rpc.call` example `"world:42"`, is then
 sent back as the following JSON-RPC 2.0 success response
 message to the temporary (client-specific) MQTT topic
 `example/hello/response/d1acc980-0e4e-11e8-98f0-ab5030b47df4`:
@@ -155,9 +154,10 @@ message to the temporary (client-specific) MQTT topic
 ```
 
 The JSON-RPC 2.0 `id` field always consists of `<cid>:<rid>`, where
-`<cid>` is the UUID v1 of the MQTT-JSON-RPC instance and `<rid>` is
+`<cid>` is the UUID v1 of the MQTT-JSON-RPC client instance and `<rid>` is
 the UUID v1 of the particular method request. The `<cid>` is used for
 sending back the JSON-RPC 2.0 response message to the requestor only.
+The `<rid>` is used for correlating the response to the request only.
 
 Example
 -------
@@ -193,7 +193,7 @@ user    example
 topic   readwrite example/#
 ```
 
-...and an `example` user in `mosquitto-pwd.txt` like:
+...and an `example` user (with password `example`) in `mosquitto-pwd.txt` like:
 
 ```
 example:$6$awYNe6oCAi+xlvo5$mWIUqyy4I0O3nJ99lP1mkRVqsDGymF8en5NChQQxf7KrVJLUp1SzrrVDe94wWWJa3JGIbOXD9wfFGZdi948e6A==
@@ -214,13 +214,13 @@ const mqtt = MQTT.connect("wss://127.0.0.1:8889", {
 
 const rpc = new RPC(mqtt)
 
-rpc.on("error",     (err)            => { console.log("ERROR", err) })
-rpc.on("offline",   ()               => { console.log("OFFLINE") })
-rpc.on("close",     ()               => { console.log("CLOSE") })
-rpc.on("reconnect", ()               => { console.log("RECONNECT") })
-rpc.on("message",   (topic, message) => { console.log("RECEIVED", topic, message.toString()) })
+mqtt.on("error",     (err)            => { console.log("ERROR", err) })
+mqtt.on("offline",   ()               => { console.log("OFFLINE") })
+mqtt.on("close",     ()               => { console.log("CLOSE") })
+mqtt.on("reconnect", ()               => { console.log("RECONNECT") })
+mqtt.on("message",   (topic, message) => { console.log("RECEIVED", topic, message.toString()) })
 
-rpc.on("connect", () => {
+mqtt.on("connect", () => {
     console.log("CONNECT")
     rpc.register("example/hello", (a1, a2) => {
         console.log("example/hello: request: ", a1, a2)
@@ -228,7 +228,7 @@ rpc.on("connect", () => {
     })
     rpc.call("example/hello", "world", 42).then((result) => {
         console.log("example/hello sucess: ", result)
-        rpc.end()
+        mqtt.end()
     }).catch((err) => {
         console.log("example/hello error: ", err)
     })
@@ -250,7 +250,7 @@ CLOSE
 License
 -------
 
-Copyright (c) 2018-2023 Dr. Ralf S. Engelschall (http://engelschall.com/)
+Copyright (c) 2018-2025 Dr. Ralf S. Engelschall (http://engelschall.com/)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the