mqtt-plus 0.9.0 → 0.9.2

package/README.md

@@ -22,28 +22,26 @@ $ npm install mqtt mqtt-plus
 About
 -----
 
-This is **MQTT+**, an addon JavaScript/TypeScript API for the excellent
-[MQTT.js](https://www.npmjs.com/package/mqtt), for additional
-communication patterns like [Remote Procedure
-Call](https://en.wikipedia.org/wiki/Remote_procedure_call) (RPC).
-This allows a bi-directional request/response-style
-communication over the technically uni-directional message protocol
-[MQTT](http://mqtt.org).
-
-Conceptually, the **MQTT+** API provides two types of communication patterns:
+This is **MQTT+**, an addon API for the excellent
+[MQTT](http://mqtt.org/) client TypeScript/JavaScript API
+[MQTT.js](https://www.npmjs.com/package/mqtt), provoding additional
+communication patterns with optional type safety:
 
 - **Event Emission**:
+
   Event Emission is a *uni-directional* communication pattern.
   An Event is the combination of an event name and optionally zero or more arguments.
   You *subscribe* to events.
   When an event is *emitted*, either a single particular subscriber (in case of
   a directed event emission) or all subscribers are called and receive the
   arguments as extra information.
+
   In contrast to the regular MQTT message publish/subscribe, this
   pattern allows to direct the event to particular subscribers and
   provides optional information about the sender to subscribers.
 
 - **Service Call**:
+
   Service Call is a *bi-directional* communication pattern.
   A Service is the combination of a service name and optionally zero or more arguments.
   You *register* for a service.
@@ -52,6 +50,11 @@ Conceptually, the **MQTT+** API provides two types of communication patterns:
   receives the arguments as the request. The registrator then has to
   provide the service response.
 
+  In contrast to the regular uni-directional MQTT message
+  publish/subscribe communication, this allows a bi-directional [Remote
+  Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call)
+  (RPC) style communication.
+
 > [!Note]
 > **MQTT+** is similar to and derived from
 > [MQTT-JSON-RPC](https://github.com/rse/mqtt-json-rpc) of the same
@@ -115,11 +118,11 @@ mqtt.on("connect", () => {
 Application Programming Interface
 ---------------------------------
 
-The MQTT+ API provides the following methods:
+The **MQTT+** API provides the following methods:
 
 - **Construction**:<br/>
 
-      constructor(
+      constructor<API>(
           mqtt: MqttClient,
           options?: {
               id:                        string
@@ -134,8 +137,14 @@ The MQTT+ API provides the following methods:
           }
       )
 
+  The `API` is an optional TypeScript type `Record<string, ((...args:
+  any[]) => void) | ((...args: any[]) => any)>`, describing the
+  available events and services. Callbacks without return values
+  describe events, callbacks with return values describe services.
+
   The `mqtt` is the [MQTT.js](https://www.npmjs.com/package/mqtt) instance,
-  which has to be establish separately.
+  which has to be established separately.
+
   The optional `options` object supports the following fields:
   - `id`: Custom MQTT peer identifier (default: auto-generated NanoID).
   - `codec`: Encoding format (default: `cbor`).
@@ -159,7 +168,7 @@ The MQTT+ API provides the following methods:
       subscribe(
           event:    string,
           options?: MQTT::IClientSubscribeOptions
-          callback: (...params: any[], info?: sender: string, receiver?: string) => void
+          callback: (...params: any[], info: { sender: string, receiver?: string }) => void
       ): Promise<Subscription>
 
   Subscribe to an event.
@@ -179,7 +188,7 @@ The MQTT+ API provides the following methods:
       register(
           service:  string,
           options?: MQTT::IClientSubscribeOptions
-          callback: (...params: any[], info?: sender: string, receiver?: string) => any
+          callback: (...params: any[], info: { sender: string, receiver?: string }) => any
       ): Promise<Registration>
 
   Register a service.
@@ -247,7 +256,7 @@ The MQTT+ API provides the following methods:
 Internals
 ---------
 
-In the following, assume that an MQTT+ instance is created with:
+In the following, we assume that an **MQTT+** instance is created with:
 
 ```ts
 import MQTT  from "mqtt"
@@ -272,8 +281,8 @@ ones):
 
 ```json
 {
-    "id":      "RRRRRRRRRRRRRRRRRRRRR",
-    "sender":  "SSSSSSSSSSSSSSSSSSSSS",
+    "id":      "vwLzfQDu2uEeOdOfIlT42",
+    "sender":  "2IBMSk0NPnrz1AeTERoea",
     "method":  "example/hello",
     "params":  [ "world", 42 ]
 }
@@ -290,12 +299,12 @@ mqttp.register("example/hello", (a1, a2) => {
 ...and then its result, in the above `mqttp.call()` example `"world:42"`, is then
 sent back as the following success response
 message to the temporary (client-specific) MQTT topic
-`example/hello/service-response/SSSSSSSSSSSSSSSSSSSSS`:
+`example/hello/service-response/2IBMSk0NPnrz1AeTERoea`:
 
 ```json
 {
-    "id":      "RRRRRRRRRRRRRRRRRRRRR",
-    "sender":  "SSSSSSSSSSSSSSSSSSSSS",
+    "id":      "vwLzfQDu2uEeOdOfIlT42",
+    "sender":  "2IBMSk0NPnrz1AeTERoea",
     "result":  "world:42"
 }
 ```
@@ -422,8 +431,6 @@ The output will be:
 ```
 $ node sample.ts
 CONNECT
-example/sample: info:  world 42 undefined
-RECEIVED example/sample/event-notice {"id":"GraDZnA4BLrF66g9qmpPX","sender":"2IBMSk0NPnrz1AeTERoea","event":"example/sample","params":["world",42]}
 RECEIVED example/hello/service-request {"id":"vwLzfQDu2uEeOdOfIlT42","sender":"2IBMSk0NPnrz1AeTERoea","service":"example/hello","params":["world",42]}
 example/hello: request:  world 42 undefined
 RECEIVED example/hello/service-response/2IBMSk0NPnrz1AeTERoea {"id":"vwLzfQDu2uEeOdOfIlT42","sender":"2IBMSk0NPnrz1AeTERoea","receiver":"2IBMSk0NPnrz1AeTERoea","result":"world:42"}

package/dst-stage1/mqtt-plus.d.ts

@@ -30,7 +30,7 @@ export interface Info {
     receiver?: string;
 }
 export type WithInfo<F> = F extends (...args: infer P) => infer R ? (...args: [...P, info: Info]) => R : never;
-export type APISchema = Record<string, (...args: any[]) => any>;
+export type APISchema = Record<string, ((...args: any[]) => void) | ((...args: any[]) => any)>;
 export type EventKeys<T> = string extends keyof T ? string : {
     [K in keyof T]: T[K] extends (...args: any[]) => infer R ? [R] extends [void] ? K : never : never;
 }[keyof T];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                           "mqtt-plus",
-    "version":                        "0.9.0",
+    "version":                        "0.9.2",
     "description":                    "MQTT Communication Patterns",
     "keywords":                       [ "mqtt", "event", "service", "rpc", "request", "response" ],
     "license":                        "MIT",

package/src/mqtt-plus.ts

@@ -78,7 +78,11 @@ export type WithInfo<F> = F extends (...args: infer P) => infer R
     : never
 
 /*  type utilities for generic API  */
-export type APISchema = Record<string, (...args: any[]) => any>
+export type APISchema = Record<
+    string,
+    ((...args: any[]) => void) |
+    ((...args: any[]) => any)
+>
 
 /*  extract event keys where return type IS void (events: subscribe/notify/control)  */
 export type EventKeys<T> = string extends keyof T ? string : {