mqtt-plus 1.4.4 → 1.4.5

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 ChangeLog
 =========
 
+1.4.5 (2026-02-21)
+------------------
+
+- IMPROVEMENT: add a "npm start publish" target for convenient publishing
+- IMPROVEMENT: allow QoS to be overridden and change default to level 2
+- BUGFIX: properly destroy resources on cleanup
+- CLEANUP: factor out registration code into base trait
+- CLEANUP: use ensureError utility function for consistent error handling
+- CLEANUP: rename and protect internal symbols and reduce unnecessary typing
+- CLEANUP: avoid a race condition in topic unsubscription handling
+- CLEANUP: improve about information
+
 1.4.4 (2026-02-21)
 ------------------
 

package/README.md

@@ -18,10 +18,14 @@ About
 **MQTT+** is a companion add-on API for the TypeScript/JavaScript
 API [MQTT.js](https://www.npmjs.com/package/mqtt), providing
 additional communication patterns with full type safety for
-[MQTT](http://mqtt.org/). Currently the essential
+[MQTT](http://mqtt.org/). Currently, the essential
 [communication patterns](doc/mqtt-plus-comm.md)
 *Event Emission*, *Service Call*, *Sink Push* and *Source Fetch* are
-supported.
+supported. This allows you to implement complex and bi-directional
+client/server and server/server communications over the robust but
+uni-directional [MQTT](http://mqtt.org/) protocol. This is key in
+applications based on the [*Hub & Spoke*](https://en.wikipedia.org/wiki/Spoke%E2%80%93hub_distribution_paradigm)
+communication architecture pattern.
 
 Installation
 ------------

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

@@ -1,16 +1,18 @@
 import { MqttClient, type IClientSubscribeOptions, type IClientPublishOptions } from "mqtt";
-import type { APISchema } from "./mqtt-plus-api";
+import type { APISchema, Registration } from "./mqtt-plus-api";
 import type { APIOptions } from "./mqtt-plus-options";
 import { TraceTrait } from "./mqtt-plus-trace";
+import type { Spool } from "./mqtt-plus-error";
 export declare class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
-    protected mqtt: MqttClient;
-    private _messageHandler;
+    private mqtt;
+    private messageHandler;
     protected onRequest: Map<string, (message: any, topicName: string) => void>;
     protected onResponse: Map<string, (message: any, topicName: string) => void>;
     constructor(mqtt: MqttClient | null, options?: Partial<APIOptions>);
     destroy(): Promise<void>;
-    protected _subscribeTopic(topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
-    protected _unsubscribeTopic(topic: string): Promise<void>;
-    protected _publishToTopic(topic: string, message: string | Uint8Array, options?: IClientPublishOptions): Promise<void>;
+    protected makeRegistration(spool: Spool, kind: string, name: string, key: string): Registration;
+    protected subscribeTopic(topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
+    protected unsubscribeTopic(topic: string): Promise<void>;
+    protected publishToTopic(topic: string, message: string | Uint8Array, options?: IClientPublishOptions): Promise<void>;
     private _onMessage;
 }

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

@@ -56,7 +56,7 @@ export class BaseTrait extends TraceTrait {
         this.mqtt = mqtt;
         /*  hook into the MQTT message processing  */
         this.log("info", "hooking into MQTT client");
-        this._messageHandler = (topic, message, packet) => {
+        this.messageHandler = (topic, message, packet) => {
             /*  convert message to codec-specific input format
                 (NOTICE: MQTT.js uses Buffer in its handler signature only,
                 but internally supports string or Buffer, while we are
@@ -72,15 +72,27 @@ export class BaseTrait extends TraceTrait {
                 throw new Error("invalid codec configured");
             this._onMessage(topic, input, packet);
         };
-        this.mqtt.on("message", this._messageHandler);
+        this.mqtt.on("message", this.messageHandler);
     }
     /*  destroy API class  */
     async destroy() {
         this.log("info", "un-hooking from MQTT client");
-        this.mqtt.off("message", this._messageHandler);
+        this.mqtt.off("message", this.messageHandler);
+    }
+    /*  create a registration for subsequent destruction  */
+    makeRegistration(spool, kind, name, key) {
+        return {
+            destroy: async () => {
+                if (!this.onRequest.has(key))
+                    throw new Error(`destroy: ${kind} "${name}" not registered`);
+                await spool.unroll(false)?.catch((err) => {
+                    this.error(err, `destroy: failed to cleanup: ${err.message}`);
+                });
+            }
+        };
     }
     /*  subscribe to an MQTT topic (Promise-based)  */
-    async _subscribeTopic(topic, options = {}) {
+    async subscribeTopic(topic, options = {}) {
         this.log("info", `subscribing to MQTT topic "${topic}"`);
         return new Promise((resolve, reject) => {
             this.mqtt.subscribe(topic, { qos: 2, ...options }, (err, _granted) => {
@@ -94,7 +106,7 @@ export class BaseTrait extends TraceTrait {
         });
     }
     /*  unsubscribe from an MQTT topic (Promise-based)  */
-    async _unsubscribeTopic(topic) {
+    async unsubscribeTopic(topic) {
         this.log("info", `unsubscribing from MQTT topic "${topic}"`);
         return new Promise((resolve, reject) => {
             this.mqtt.unsubscribe(topic, (err, _packet) => {
@@ -108,7 +120,7 @@ export class BaseTrait extends TraceTrait {
         });
     }
     /*  publish to an MQTT topic (Promise-based)  */
-    async _publishToTopic(topic, message, options = {}) {
+    async publishToTopic(topic, message, options = {}) {
         /*  determine buffer  */
         if (typeof message === "string")
             this.log("info", `publishing to MQTT topic "${topic}" (type: string, length: ${message.length} chars)`);

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

@@ -82,20 +82,12 @@ export class EventTrait extends AuthTrait {
         });
         spool.roll(() => { this.onRequest.delete(`event-emission:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicB}"`, spool, () => this._subscribeTopic(topicB, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicD}"`, spool, () => this._subscribeTopic(topicD, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicD).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicB}"`, spool, () => this.subscribeTopic(topicB, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicB).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicD}"`, spool, () => this.subscribeTopic(topicD, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicD).catch(() => { }));
         /*  provide a registration for subsequent destruction  */
-        return {
-            destroy: async () => {
-                if (!this.onRequest.has(`event-emission:${name}`))
-                    throw new Error(`destroy: event "${name}" not registered`);
-                await spool.unroll(false)?.catch((err) => {
-                    this.error(err, `destroy: failed to cleanup: ${err.message}`);
-                });
-            }
-        };
+        return this.makeRegistration(spool, "event", name, `event-emission:${name}`);
     }
     emit(eventOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -131,10 +123,10 @@ export class EventTrait extends AuthTrait {
         /*  produce result  */
         if (dry)
             /*  return publish information  */
-            return { topic, payload: message, options: { qos: 0, ...options } };
+            return { topic, payload: message, options: { qos: 2, ...options } };
         else
             /*  publish message to MQTT topic  */
-            this._publishToTopic(topic, message, { qos: 0, ...options }).catch((err) => {
+            this.publishToTopic(topic, message, { qos: 2, ...options }).catch((err) => {
                 this.error(err, `emitting event "${event}" failed`);
             });
     }

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

@@ -91,27 +91,19 @@ export class ServiceTrait extends EventTrait {
                 /*  send response message  */
                 const encoded = this.codec.encode(rpcResponse);
                 const topic = this.options.topicMake(name, "service-call-response", senderId);
-                return this._publishToTopic(topic, encoded, { qos: 2 });
+                return this.publishToTopic(topic, encoded, { qos: options.qos ?? 2 });
             }).catch((err) => {
                 this.error(err, `handler for service "${name}" failed`);
             });
         });
         spool.roll(() => { this.onRequest.delete(`service-call-request:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicB}"`, spool, () => this._subscribeTopic(topicB, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicD}"`, spool, () => this._subscribeTopic(topicD, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicD).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicB}"`, spool, () => this.subscribeTopic(topicB, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicB).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicD}"`, spool, () => this.subscribeTopic(topicD, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicD).catch(() => { }));
         /*  provide a registration for subsequent destruction  */
-        return {
-            destroy: async () => {
-                if (!this.onRequest.has(`service-call-request:${name}`))
-                    throw new Error(`destroy: service "${name}" not registered`);
-                await spool.unroll(false)?.catch((err) => {
-                    this.error(err, `destroy: failed to cleanup: ${err.message}`);
-                });
-            }
-        };
+        return this.makeRegistration(spool, "service", name, `service-call-request:${name}`);
     }
     async call(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -171,7 +163,7 @@ export class ServiceTrait extends EventTrait {
         /*  generate corresponding MQTT topic  */
         const topic = this.options.topicMake(name, "service-call-request", receiver);
         /*  publish message to MQTT topic  */
-        await run(`publish service request as MQTT message to topic "${topic}"`, spool, () => this._publishToTopic(topic, message, { qos: 2, ...options }));
+        await run(`publish service request as MQTT message to topic "${topic}"`, spool, () => this.publishToTopic(topic, message, { qos: 2, ...options }));
         return promise;
     }
 }

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

@@ -7,6 +7,7 @@ import type { AuthOption } from "./mqtt-plus-auth";
 export declare class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
     private pushStreams;
     private pushSpools;
+    destroy(): Promise<void>;
     sink<K extends SinkKeys<T> & string>(name: K, callback: WithInfo<T[K], InfoSink>): Promise<Registration>;
     sink<K extends SinkKeys<T> & string>(config: {
         name: K;

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

@@ -26,7 +26,7 @@ import { Readable } from "node:stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
 import { CreditGate, streamToBuffer, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields } from "./mqtt-plus-util";
-import { run, Spool } from "./mqtt-plus-error";
+import { run, Spool, ensureError } from "./mqtt-plus-error";
 import { SourceTrait } from "./mqtt-plus-source";
 /*  Sink Push Trait  */
 export class SinkTrait extends SourceTrait {
@@ -36,6 +36,14 @@ export class SinkTrait extends SourceTrait {
         this.pushStreams = new Map();
         this.pushSpools = new Map();
     }
+    /*  destroy sink trait  */
+    async destroy() {
+        for (const stream of this.pushStreams.values())
+            stream.destroy();
+        this.pushStreams.clear();
+        this.pushSpools.clear();
+        await super.destroy();
+    }
     async sink(nameOrConfig, ...args) {
         /*  determine actual parameters  */
         let name;
@@ -90,7 +98,7 @@ export class SinkTrait extends SourceTrait {
                 const credit = chunkCredit > 0 ? chunkCredit : undefined;
                 const response = this.msg.makeSinkPushResponse(requestId, name, error, this.options.id, sender, authToken, metaStore, credit);
                 const message = this.codec.encode(response);
-                await this._publishToTopic(responseTopic, message, { qos: 2 });
+                await this.publishToTopic(responseTopic, message, { qos: options.qos ?? 2 });
             };
             /*  create a resource spool for stream cleanup  */
             const reqSpool = new Spool();
@@ -130,7 +138,7 @@ export class SinkTrait extends SourceTrait {
                             const creditMsg = this.msg.makeSinkPushCredit(requestId, name, creditToGrant, this.options.id, sender);
                             const encoded = this.codec.encode(creditMsg);
                             const creditTopic = this.options.topicMake(name, "sink-push-credit", sender);
-                            this._publishToTopic(creditTopic, encoded, { qos: 2 }).catch((err) => {
+                            this.publishToTopic(creditTopic, encoded, { qos: options.qos ?? 2 }).catch((err) => {
                                 this.error(err, `sending credit for push "${name}" failed`);
                             });
                             refreshPushTimeout();
@@ -189,22 +197,14 @@ export class SinkTrait extends SourceTrait {
         });
         spool.roll(() => { this.onRequest.delete(`sink-push-request:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () => this._subscribeTopic(topicReqB, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicReqB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicReqD}"`, spool, () => this._subscribeTopic(topicReqD, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicReqD).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicChunkD}"`, spool, () => this._subscribeTopic(topicChunkD, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicChunkD).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () => this.subscribeTopic(topicReqB, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicReqB).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicReqD}"`, spool, () => this.subscribeTopic(topicReqD, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicReqD).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicChunkD}"`, spool, () => this.subscribeTopic(topicChunkD, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicChunkD).catch(() => { }));
         /*  provide a registration for subsequent destruction  */
-        return {
-            destroy: async () => {
-                if (!this.onRequest.has(`sink-push-request:${name}`))
-                    throw new Error(`destroy: sink "${name}" not established`);
-                await spool.unroll(false)?.catch((err) => {
-                    this.error(err, `destroy: failed to cleanup: ${err.message}`);
-                });
-            }
-        };
+        return this.makeRegistration(spool, "sink", name, `sink-push-request:${name}`);
     }
     async push(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -290,7 +290,7 @@ export class SinkTrait extends SourceTrait {
                 const request = this.msg.makeSinkPushRequest(requestId, name, params, this.options.id, receiver, auth, metaStore);
                 const message = this.codec.encode(request);
                 const requestTopic = this.options.topicMake(name, "sink-push-request", receiver);
-                run(`publish push request as MQTT message to topic "${requestTopic}"`, spool, () => this._publishToTopic(requestTopic, message, { qos: 2, ...options })).catch((err) => {
+                run(`publish push request as MQTT message to topic "${requestTopic}"`, spool, () => this.publishToTopic(requestTopic, message, { qos: 2, ...options })).catch((err) => {
                     reject(err);
                 });
             });
@@ -305,7 +305,7 @@ export class SinkTrait extends SourceTrait {
             /*  subscribe to credit topic if flow control is active  */
             if (creditGate) {
                 const creditTopic = this.options.topicMake(name, "sink-push-credit", this.options.id);
-                await run(`subscribe to MQTT topic "${creditTopic}"`, spool, () => this.subscriptions.subscribe(creditTopic, { qos: 2 }));
+                await run(`subscribe to MQTT topic "${creditTopic}"`, spool, () => this.subscriptions.subscribe(creditTopic, { qos: options.qos ?? 2 }));
                 spool.roll(() => this.subscriptions.unsubscribe(creditTopic));
                 const gate = creditGate;
                 spool.roll(() => { gate.abort(); });
@@ -322,7 +322,7 @@ export class SinkTrait extends SourceTrait {
                 refreshTimeout();
                 const chunkMsg = this.msg.makeSinkPushChunk(requestId, name, chunk, error, final, this.options.id, receiver);
                 const message = this.codec.encode(chunkMsg);
-                await this._publishToTopic(chunkTopic, message, { qos: 2, ...options });
+                await this.publishToTopic(chunkTopic, message, { qos: 2, ...options });
             };
             /*  iterate over all chunks of the buffer  */
             if (data instanceof Readable)
@@ -333,11 +333,11 @@ export class SinkTrait extends SourceTrait {
                 await sendBufferAsChunks(data, this.options.chunkSize, sendChunk, creditGate, abortSignal);
         }
         catch (err) {
-            const error = err instanceof Error ? err.message : String(err);
+            const error = ensureError(err).message;
             const chunkTopic = this.options.topicMake(name, "sink-push-chunk", receiver);
             const chunkMsg = this.msg.makeSinkPushChunk(requestId, name, undefined, error, true, this.options.id, receiver);
             const message = this.codec.encode(chunkMsg);
-            await this._publishToTopic(chunkTopic, message, { qos: 2, ...options }).catch(() => { });
+            await this.publishToTopic(chunkTopic, message, { qos: 2, ...options }).catch(() => { });
             throw err;
         }
         finally {

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

@@ -6,6 +6,7 @@ import { ServiceTrait } from "./mqtt-plus-service";
 import type { AuthOption } from "./mqtt-plus-auth";
 export declare class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T> {
     private sourceCreditGates;
+    destroy(): Promise<void>;
     source<K extends SourceKeys<T> & string>(name: K, callback: WithInfo<T[K], InfoSource>): Promise<Registration>;
     source<K extends SourceKeys<T> & string>(config: {
         name: K;

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

@@ -35,6 +35,13 @@ export class SourceTrait extends ServiceTrait {
         /*  source state  */
         this.sourceCreditGates = new Map();
     }
+    /*  destroy source trait  */
+    async destroy() {
+        for (const gate of this.sourceCreditGates.values())
+            gate.abort();
+        this.sourceCreditGates.clear();
+        await super.destroy();
+    }
     async source(nameOrConfig, ...args) {
         /*  determine actual parameters  */
         let name;
@@ -88,7 +95,7 @@ export class SourceTrait extends ServiceTrait {
                 const metaStore = this.metaStore(info.meta);
                 const response = this.msg.makeSourceFetchResponse(requestId, name, error, this.options.id, sender, authToken, metaStore);
                 const message = this.codec.encode(response);
-                await this._publishToTopic(responseTopic, message, { qos: 2 });
+                await this.publishToTopic(responseTopic, message, { qos: options.qos ?? 2 });
             };
             /*  utility functions for timeout management  */
             const refreshSourceTimeout = () => this.timerRefresh(requestId, () => {
@@ -103,7 +110,7 @@ export class SourceTrait extends ServiceTrait {
                 refreshSourceTimeout();
                 const chunkMsg = this.msg.makeSourceFetchChunk(requestId, name, chunk, error, final, this.options.id, sender);
                 const message = this.codec.encode(chunkMsg);
-                await this._publishToTopic(chunkTopic, message, { qos: 2 });
+                await this.publishToTopic(chunkTopic, message, { qos: options.qos ?? 2 });
             };
             /*  handle credit-based flow control (if credit provided in request)  */
             const initialCredit = request.credit;
@@ -162,22 +169,14 @@ export class SourceTrait extends ServiceTrait {
         });
         spool.roll(() => { this.onRequest.delete(`source-fetch-request:${name}`); });
         /*  subscribe to MQTT topics  */
-        await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () => this._subscribeTopic(topicReqB, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicReqB).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicReqD}"`, spool, () => this._subscribeTopic(topicReqD, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicReqD).catch(() => { }));
-        await run(`subscribe to MQTT topic "${topicCreditD}"`, spool, () => this._subscribeTopic(topicCreditD, { qos: 2, ...options }));
-        spool.roll(() => this._unsubscribeTopic(topicCreditD).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicReqB}"`, spool, () => this.subscribeTopic(topicReqB, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicReqB).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicReqD}"`, spool, () => this.subscribeTopic(topicReqD, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicReqD).catch(() => { }));
+        await run(`subscribe to MQTT topic "${topicCreditD}"`, spool, () => this.subscribeTopic(topicCreditD, { qos: 2, ...options }));
+        spool.roll(() => this.unsubscribeTopic(topicCreditD).catch(() => { }));
         /*  provide a registration for subsequent destruction  */
-        return {
-            destroy: async () => {
-                if (!this.onRequest.has(`source-fetch-request:${name}`))
-                    throw new Error(`destroy: source "${name}" not established`);
-                await spool.unroll(false)?.catch((err) => {
-                    this.error(err, `destroy: failed to cleanup: ${err.message}`);
-                });
-            }
-        };
+        return this.makeRegistration(spool, "source", name, `source-fetch-request:${name}`);
     }
     async fetch(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -230,7 +229,7 @@ export class SourceTrait extends ServiceTrait {
                     const creditMsg = this.msg.makeSourceFetchCredit(requestId, name, creditToGrant, this.options.id, targetId);
                     const encoded = this.codec.encode(creditMsg);
                     const creditTopic = this.options.topicMake(name, "source-fetch-credit", targetId);
-                    this._publishToTopic(creditTopic, encoded, { qos: 2 }).catch((err) => {
+                    this.publishToTopic(creditTopic, encoded, { qos: options.qos ?? 2 }).catch((err) => {
                         this.error(err, `sending credit for fetch "${name}" failed`);
                     });
                 }
@@ -311,7 +310,7 @@ export class SourceTrait extends ServiceTrait {
         /*  generate corresponding MQTT topic  */
         const topic = this.options.topicMake(name, "source-fetch-request", receiver);
         /*  publish message to MQTT topic  */
-        run(`publish fetch request as MQTT message to topic "${topic}"`, spool, () => this._publishToTopic(topic, message, { qos: 2, ...options })).catch((err) => {
+        run(`publish fetch request as MQTT message to topic "${topic}"`, spool, () => this.publishToTopic(topic, message, { qos: 2, ...options })).catch((err) => {
             stream.destroy(ensureError(err));
             spool.unroll();
         });

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

@@ -8,6 +8,7 @@ declare class RefCountedSubscription {
     private counts;
     private pending;
     private lingers;
+    private unsubbing;
     constructor(subscribeFn: (topic: string, options: IClientSubscribeOptions) => Promise<void>, unsubscribeFn: (topic: string) => Promise<void>, lingerMs?: number);
     subscribe(topic: string, options?: IClientSubscribeOptions): Promise<void>;
     unsubscribe(topic: string): Promise<void>;

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

@@ -31,6 +31,7 @@ class RefCountedSubscription {
         this.counts = new Map();
         this.pending = new Map();
         this.lingers = new Map();
+        this.unsubbing = new Map();
     }
     /*  subscribe to a topic (reference-counted)  */
     async subscribe(topic, options = { qos: 2 }) {
@@ -47,6 +48,11 @@ class RefCountedSubscription {
         }
         /*  if we are the first, we must perform the actual subscription  */
         if (count === 0) {
+            /*  await any in-flight linger unsubscription to avoid a race
+                where the broker processes UNSUBSCRIBE after our SUBSCRIBE  */
+            const inflight = this.unsubbing.get(topic);
+            if (inflight)
+                await inflight;
             const promise = this.subscribeFn(topic, options).finally(() => {
                 this.pending.delete(topic);
             }).catch((err) => {
@@ -88,7 +94,10 @@ class RefCountedSubscription {
                     /*  defer the actual broker unsubscription  */
                     const timer = setTimeout(() => {
                         this.lingers.delete(topic);
-                        this.unsubscribeFn(topic).catch(() => { });
+                        const promise = this.unsubscribeFn(topic).catch(() => { }).finally(() => {
+                            this.unsubbing.delete(topic);
+                        });
+                        this.unsubbing.set(topic, promise);
                     }, this.lingerMs);
                     this.lingers.set(topic, timer);
                 }
@@ -116,7 +125,7 @@ class RefCountedSubscription {
 export class SubscriptionTrait extends BaseTrait {
     constructor() {
         super(...arguments);
-        this.subscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic));
+        this.subscriptions = new RefCountedSubscription((topic, options) => this.subscribeTopic(topic, options), (topic) => this.unsubscribeTopic(topic));
     }
     /*  destroy subscription trait  */
     async destroy() {

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

@@ -17,7 +17,7 @@ export declare class TraceTrait<T extends APISchema = APISchema> extends MsgTrai
     off(event: "log", callback: (log: LogEvent) => void): void;
     protected emitEvent(event: "error", error: Error): void;
     protected emitEvent(event: "log", log: LogEvent): void;
-    log(level: string, msg: string | Promise<string>, data?: Record<string, Promise<any> | any>): void;
-    error(error: Error, msg?: string): void;
+    protected log(level: string, msg: string | Promise<string>, data?: Record<string, Promise<any> | any>): void;
+    protected error(error: Error, msg?: string): void;
 }
 export {};