mqtt-plus 0.9.15 → 0.9.17

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+
+ChangeLog
+=========
+
+0.9.17 (2026-01-25)
+-------------------
+
+- IMPROVEMENT: add Dry-Run mode will null MQTT client
+- IMPROVEMENT: add Dry-Run mode for emit() to generate last-will message
+
+0.9.16 (2026-01-24)
+-------------------
+
+- CLEANUP: cleanup subscription handling
+- UPDATE: upgrade NPM dependencies
+
+0.9.15 (2026-01-24)
+-------------------
+
+- IMPROVEMENT: provide unpkg.com sample
+- IMPROVEMENT: provide esm/cjs/umd import sub-paths
+
+0.9.14 (2026-01-24)
+-------------------
+
+- REFACTORING: change external API from Buffer to Uint8Array to better support browsers
+- IMPROVEMENT: add "dev" STX target for convenient development
+
+0.9.14 (2026-01-24)
+-------------------
+
+- IMPROVEMENT: use Base64 for encoding buffers in JSON encoding
+- IMPROVEMENT: switch from "cbor" to "cbor2" for CBOR encoding
+
+[...]
+
+0.9.0 (2026-01-05)
+------------------
+
+(first rough cut of library)
+

package/README.md

@@ -286,10 +286,20 @@ The **MQTT+** API provides the following methods:
           receiver?: string,
           options?:  MQTT::IClientSubscribeOptions
       }): void
+      emit({
+          event:     string,
+          params:    any[],
+          receiver?: string,
+          options?:  MQTT::IClientSubscribeOptions,
+          dry:       true
+      }): { topic: string, payload: Buffer, options: IClientPublishOptions }
 
   Emit an event to all subscribers or a specific subscriber ("fire and forget").
   The optional `receiver` directs the event to a specific subscriber only.
   The optional `options` allows setting MQTT.js `publish()` options like `qos` or `retain`.
+  The optional `dry` flag, when set to `true`, returns the publish information
+  (`topic`, `payload`, `options`) instead of actually publishing to the MQTT broker.
+  This is useful for generating MQTT "last will" messages (see example below).
 
   The remote `subscribe()` `callback` is called with `params` and its
   return value is silently ignored.
@@ -297,6 +307,32 @@ The **MQTT+** API provides the following methods:
   Internally, publishes to the MQTT topic by `topicMake(event, "event-emission", peerId)`
   (default: `${event}/event-emission/any` or `${event}/event-emission/${peerId}`).
 
+  **Dry-Run Publishing for MQTT Last-Will:**
+  When you need to set up an MQTT "last will" message (automatically published
+  by the broker when a client disconnects *unexpectedly*), you can use `dry: true`
+  together with a `null` MQTT client:
+
+      type API = {
+          "example/connection": Event<(state: "open" | "close") => void>
+          [...]
+      }
+      const mqttpDry = new MQTTp<API>(null, { id: "my-client" })
+      const will = mqttpDry.emit({
+          dry:    true,
+          event:  "example/connection",
+          params: [ "close" ],
+          [...]
+      })
+      mqttpDry.destroy()
+      const mqtt = MQTT.connect("[...]", {
+          will: {
+              topic:   will.topic,
+              payload: will.payload,
+              qos:     will.options.qos
+          },
+          [...]
+      })
+
 - **Service Call**:<br/>
 
       /*  (simplified TypeScript API method signature)  */

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

@@ -1,11 +1,11 @@
-import { MqttClient, IClientSubscribeOptions } from "mqtt";
+import type { MqttClient, IClientSubscribeOptions } from "mqtt";
 import { APISchema } from "./mqtt-plus-api";
 import { MsgTrait } from "./mqtt-plus-msg";
 import { APIOptions } from "./mqtt-plus-options";
 export declare class BaseTrait<T extends APISchema = APISchema> extends MsgTrait<T> {
     protected mqtt: MqttClient;
     private _messageHandler;
-    constructor(mqtt: MqttClient, options?: Partial<APIOptions>);
+    constructor(mqtt: MqttClient | null, options?: Partial<APIOptions>);
     destroy(): void;
     protected _subscribeTopic(topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
     protected _unsubscribeTopic(topic: string): Promise<void>;

package/dst-stage1/mqtt-plus-base.js

@@ -27,6 +27,17 @@ export class BaseTrait extends MsgTrait {
     /*  construct API class  */
     constructor(mqtt, options = {}) {
         super(options);
+        /*  optionally provide a fake proxy for the MQTT client
+            (mainly for using emit({ ..., dry: true }) to just make MQTT "last will")  */
+        if (mqtt === null)
+            mqtt = new Proxy({}, {
+                get(_target, prop, _receiver) {
+                    if (prop === "isFakeProxy")
+                        return true;
+                    else
+                        return (...args) => { };
+                }
+            });
         /*  store MQTT client  */
         this.mqtt = mqtt;
         /*  hook into the MQTT message processing  */

package/dst-stage1/mqtt-plus-codec.js

@@ -42,7 +42,7 @@ class JSONX {
             : value);
     }
     static parse(json) {
-        return JSON.parse(json, (_, value) => value?.__Uint8Array
+        return JSON.parse(json, (_, value) => typeof value?.__Uint8Array === "string"
             ? this.base64ToUint8Array(value.__Uint8Array)
             : value);
     }

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

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import { IClientPublishOptions, IClientSubscribeOptions } from "mqtt";
 import { APISchema, EventKeys } from "./mqtt-plus-api";
 import type { WithInfo, InfoEvent } from "./mqtt-plus-info";
@@ -16,5 +17,16 @@ export declare class EventTrait<T extends APISchema = APISchema> extends BaseTra
         receiver?: string;
         options?: IClientPublishOptions;
     }): void;
+    emit<K extends EventKeys<T> & string>(config: {
+        event: K;
+        params: Parameters<T[K]>;
+        receiver?: string;
+        options?: IClientPublishOptions;
+        dry: true;
+    }): {
+        topic: string;
+        payload: Buffer;
+        options: IClientPublishOptions;
+    };
     protected _dispatchMessage(topic: string, parsed: any): void;
 }

package/dst-stage1/mqtt-plus-event.js

@@ -80,12 +80,14 @@ export class EventTrait extends BaseTrait {
         let params;
         let receiver;
         let options = {};
+        let dry;
         if (typeof eventOrConfig === "object" && eventOrConfig !== null) {
             /*  object-based API  */
             event = eventOrConfig.event;
             params = eventOrConfig.params;
             receiver = eventOrConfig.receiver;
             options = eventOrConfig.options ?? {};
+            dry = eventOrConfig.dry;
         }
         else {
             /*  positional API  */
@@ -99,8 +101,13 @@ export class EventTrait extends BaseTrait {
         const message = this.codec.encode(request);
         /*  generate corresponding MQTT topic  */
         const topic = this.options.topicMake(event, "event-emission", receiver);
-        /*  publish message to MQTT topic  */
-        this.mqtt.publish(topic, Buffer.from(message), { qos: 0, ...options });
+        /*  produce result  */
+        if (dry)
+            /*  return publish information  */
+            return { topic, payload: Buffer.from(message), options: { qos: 0, ...options } };
+        else
+            /*  publish message to MQTT topic  */
+            this.mqtt.publish(topic, Buffer.from(message), { qos: 0, ...options });
     }
     /*  dispatch message (Event pattern handling)  */
     _dispatchMessage(topic, parsed) {

package/dst-stage1/mqtt-plus-service.js

@@ -147,8 +147,14 @@ export class ServiceTrait extends EventTrait {
         if (!this.responseSubscriptions.has(topic)) {
             this.responseSubscriptions.set(topic, 0);
             this.mqtt.subscribe(topic, options, (err) => {
-                if (err)
+                if (err) {
+                    const count = this.responseSubscriptions.get(topic) ?? 0;
+                    if (count > 1)
+                        this.responseSubscriptions.set(topic, count - 1);
+                    else
+                        this.responseSubscriptions.delete(topic);
                     this.mqtt.emit("error", err);
+                }
             });
         }
         const count = this.responseSubscriptions.get(topic) ?? 0;
@@ -163,8 +169,9 @@ export class ServiceTrait extends EventTrait {
             return;
         /*  unsubscribe from MQTT topic and forget subscription  */
         const count = this.responseSubscriptions.get(topic) ?? 0;
-        this.responseSubscriptions.set(topic, count - 1);
-        if (this.responseSubscriptions.get(topic) === 0) {
+        if (count > 1)
+            this.responseSubscriptions.set(topic, count - 1);
+        else {
             this.responseSubscriptions.delete(topic);
             this.mqtt.unsubscribe(topic, (err) => {
                 if (err)

package/dst-stage2/mqtt-plus.cjs.js

@@ -125,7 +125,7 @@ class JSONX {
     return JSON.stringify(obj, (_, value) => value instanceof Uint8Array ? { __Uint8Array: this.uint8ArrayToBase64(value) } : value);
   }
   static parse(json) {
-    return JSON.parse(json, (_, value) => value?.__Uint8Array ? this.base64ToUint8Array(value.__Uint8Array) : value);
+    return JSON.parse(json, (_, value) => typeof value?.__Uint8Array === "string" ? this.base64ToUint8Array(value.__Uint8Array) : value);
   }
 }
 class Codec {
@@ -336,6 +336,16 @@ class BaseTrait extends MsgTrait {
   /*  construct API class  */
   constructor(mqtt, options = {}) {
     super(options);
+    if (mqtt === null)
+      mqtt = new Proxy({}, {
+        get(_target, prop, _receiver) {
+          if (prop === "isFakeProxy")
+            return true;
+          else
+            return (...args) => {
+            };
+        }
+      });
     this.mqtt = mqtt;
     this._messageHandler = (topic, message, packet) => {
       this._onMessage(topic, message, packet);
@@ -436,11 +446,13 @@ class EventTrait extends BaseTrait {
     let params;
     let receiver;
     let options = {};
+    let dry;
     if (typeof eventOrConfig === "object" && eventOrConfig !== null) {
       event = eventOrConfig.event;
       params = eventOrConfig.params;
       receiver = eventOrConfig.receiver;
       options = eventOrConfig.options ?? {};
+      dry = eventOrConfig.dry;
     } else {
       event = eventOrConfig;
       params = args;
@@ -449,7 +461,10 @@ class EventTrait extends BaseTrait {
     const request = this.msg.makeEventEmission(rid, event, params, this.options.id, receiver);
     const message = this.codec.encode(request);
     const topic = this.options.topicMake(event, "event-emission", receiver);
-    this.mqtt.publish(topic, node_buffer.Buffer.from(message), { qos: 0, ...options });
+    if (dry)
+      return { topic, payload: node_buffer.Buffer.from(message), options: { qos: 0, ...options } };
+    else
+      this.mqtt.publish(topic, node_buffer.Buffer.from(message), { qos: 0, ...options });
   }
   /*  dispatch message (Event pattern handling)  */
   _dispatchMessage(topic, parsed) {
@@ -570,8 +585,14 @@ class ServiceTrait extends EventTrait {
     if (!this.responseSubscriptions.has(topic)) {
       this.responseSubscriptions.set(topic, 0);
       this.mqtt.subscribe(topic, options, (err) => {
-        if (err)
+        if (err) {
+          const count2 = this.responseSubscriptions.get(topic) ?? 0;
+          if (count2 > 1)
+            this.responseSubscriptions.set(topic, count2 - 1);
+          else
+            this.responseSubscriptions.delete(topic);
           this.mqtt.emit("error", err);
+        }
       });
     }
     const count = this.responseSubscriptions.get(topic) ?? 0;
@@ -583,8 +604,9 @@ class ServiceTrait extends EventTrait {
     if (!this.responseSubscriptions.has(topic))
       return;
     const count = this.responseSubscriptions.get(topic) ?? 0;
-    this.responseSubscriptions.set(topic, count - 1);
-    if (this.responseSubscriptions.get(topic) === 0) {
+    if (count > 1)
+      this.responseSubscriptions.set(topic, count - 1);
+    else {
       this.responseSubscriptions.delete(topic);
       this.mqtt.unsubscribe(topic, (err) => {
         if (err)

package/dst-stage2/mqtt-plus.esm.js

@@ -107,7 +107,7 @@ class JSONX {
     return JSON.stringify(obj, (_, value) => value instanceof Uint8Array ? { __Uint8Array: this.uint8ArrayToBase64(value) } : value);
   }
   static parse(json) {
-    return JSON.parse(json, (_, value) => value?.__Uint8Array ? this.base64ToUint8Array(value.__Uint8Array) : value);
+    return JSON.parse(json, (_, value) => typeof value?.__Uint8Array === "string" ? this.base64ToUint8Array(value.__Uint8Array) : value);
   }
 }
 class Codec {
@@ -318,6 +318,16 @@ class BaseTrait extends MsgTrait {
   /*  construct API class  */
   constructor(mqtt, options = {}) {
     super(options);
+    if (mqtt === null)
+      mqtt = new Proxy({}, {
+        get(_target, prop, _receiver) {
+          if (prop === "isFakeProxy")
+            return true;
+          else
+            return (...args) => {
+            };
+        }
+      });
     this.mqtt = mqtt;
     this._messageHandler = (topic, message, packet) => {
       this._onMessage(topic, message, packet);
@@ -418,11 +428,13 @@ class EventTrait extends BaseTrait {
     let params;
     let receiver;
     let options = {};
+    let dry;
     if (typeof eventOrConfig === "object" && eventOrConfig !== null) {
       event = eventOrConfig.event;
       params = eventOrConfig.params;
       receiver = eventOrConfig.receiver;
       options = eventOrConfig.options ?? {};
+      dry = eventOrConfig.dry;
     } else {
       event = eventOrConfig;
       params = args;
@@ -431,7 +443,10 @@ class EventTrait extends BaseTrait {
     const request = this.msg.makeEventEmission(rid, event, params, this.options.id, receiver);
     const message = this.codec.encode(request);
     const topic = this.options.topicMake(event, "event-emission", receiver);
-    this.mqtt.publish(topic, Buffer$1.from(message), { qos: 0, ...options });
+    if (dry)
+      return { topic, payload: Buffer$1.from(message), options: { qos: 0, ...options } };
+    else
+      this.mqtt.publish(topic, Buffer$1.from(message), { qos: 0, ...options });
   }
   /*  dispatch message (Event pattern handling)  */
   _dispatchMessage(topic, parsed) {
@@ -552,8 +567,14 @@ class ServiceTrait extends EventTrait {
     if (!this.responseSubscriptions.has(topic)) {
       this.responseSubscriptions.set(topic, 0);
       this.mqtt.subscribe(topic, options, (err) => {
-        if (err)
+        if (err) {
+          const count2 = this.responseSubscriptions.get(topic) ?? 0;
+          if (count2 > 1)
+            this.responseSubscriptions.set(topic, count2 - 1);
+          else
+            this.responseSubscriptions.delete(topic);
           this.mqtt.emit("error", err);
+        }
       });
     }
     const count = this.responseSubscriptions.get(topic) ?? 0;
@@ -565,8 +586,9 @@ class ServiceTrait extends EventTrait {
     if (!this.responseSubscriptions.has(topic))
       return;
     const count = this.responseSubscriptions.get(topic) ?? 0;
-    this.responseSubscriptions.set(topic, count - 1);
-    if (this.responseSubscriptions.get(topic) === 0) {
+    if (count > 1)
+      this.responseSubscriptions.set(topic, count - 1);
+    else {
       this.responseSubscriptions.delete(topic);
       this.mqtt.unsubscribe(topic, (err) => {
         if (err)