mqtt-plus 1.4.0 → 1.4.2

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

@@ -25,47 +25,15 @@
 import { Readable } from "node:stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
-import { CreditGate, RefCountedSubscription, streamToBuffer, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields } from "./mqtt-plus-util";
+import { CreditGate, streamToBuffer, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields } from "./mqtt-plus-util";
 import { run, Spool, ensureError } from "./mqtt-plus-error";
-import { SourceFetchRequest, SourceFetchResponse, SourceFetchChunk, SourceFetchCredit } from "./mqtt-plus-msg";
 import { ServiceTrait } from "./mqtt-plus-service";
 /*  Source Fetch Trait  */
 export class SourceTrait extends ServiceTrait {
     constructor() {
         super(...arguments);
         /*  source state  */
-        this.sources = new Map();
-        this.fetchResponseCallbacks = new Map();
-        this.fetchChunkCallbacks = new Map();
-        this.sourceCreditCallbacks = new Map();
         this.sourceCreditGates = new Map();
-        this.sourceTimers = new Map();
-        this.fetchSubscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic));
-    }
-    /*  refresh source timer for a specific request  */
-    _refreshSourceTimer(requestId) {
-        const timer = this.sourceTimers.get(requestId);
-        if (timer !== undefined)
-            clearTimeout(timer);
-        this.sourceTimers.set(requestId, setTimeout(() => {
-            this.sourceTimers.delete(requestId);
-            const gate = this.sourceCreditGates.get(requestId);
-            if (gate !== undefined)
-                gate.abort();
-        }, this.options.timeout));
-    }
-    /*  clear source timer for a specific request  */
-    _clearSourceTimer(requestId) {
-        const timer = this.sourceTimers.get(requestId);
-        if (timer !== undefined) {
-            clearTimeout(timer);
-            this.sourceTimers.delete(requestId);
-        }
-    }
-    /*  destroy source trait  */
-    destroy() {
-        super.destroy();
-        this.fetchSubscriptions.flush();
     }
     async source(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -90,7 +58,7 @@ export class SourceTrait extends ServiceTrait {
         /*  create a resource spool  */
         const spool = new Spool();
         /*  sanity check situation  */
-        if (this.sources.has(name))
+        if (this.onRequest.has(`source-fetch-request:${name}`))
             throw new Error(`source: source "${name}" already established`);
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
         const topicS = `$share/${share}/${name}`;
@@ -98,7 +66,7 @@ export class SourceTrait extends ServiceTrait {
         const topicReqD = this.options.topicMake(name, "source-fetch-request", this.options.id);
         const topicCreditD = this.options.topicMake(name, "source-fetch-credit", this.options.id);
         /*  remember the registration  */
-        this.sources.set(name, (request, topicName) => {
+        this.onRequest.set(`source-fetch-request:${name}`, (request, topicName) => {
             /*  determine information  */
             const requestId = request.id;
             const params = request.params ?? [];
@@ -123,8 +91,12 @@ export class SourceTrait extends ServiceTrait {
                 await this._publishToTopic(responseTopic, message, { qos: 2 });
             };
             /*  utility functions for timeout management  */
-            const refreshSourceTimeout = () => this._refreshSourceTimer(requestId);
-            const clearSourceTimeout = () => this._clearSourceTimer(requestId);
+            const refreshSourceTimeout = () => this.timerRefresh(requestId, () => {
+                const gate = this.sourceCreditGates.get(requestId);
+                if (gate !== undefined)
+                    gate.abort();
+            });
+            const clearSourceTimeout = () => this.timerClear(requestId);
             refreshSourceTimeout();
             /*  callback for creating and sending a chunk message  */
             const sendChunk = async (chunk, error, final) => {
@@ -139,9 +111,9 @@ export class SourceTrait extends ServiceTrait {
                 ? new CreditGate(initialCredit) : undefined;
             if (creditGate) {
                 this.sourceCreditGates.set(requestId, creditGate);
-                this.sourceCreditCallbacks.set(requestId, (creditParsed) => {
+                this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed) => {
                     creditGate.replenish(creditParsed.credit);
-                    this._refreshSourceTimer(requestId);
+                    refreshSourceTimeout();
                 });
             }
             /*  call the handler callback  */
@@ -185,10 +157,10 @@ export class SourceTrait extends ServiceTrait {
                     creditGate.abort();
                     this.sourceCreditGates.delete(requestId);
                 }
-                this.sourceCreditCallbacks.delete(requestId);
+                this.onResponse.delete(`source-fetch-credit:${requestId}`);
             });
         });
-        spool.roll(() => { this.sources.delete(name); });
+        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(() => { }));
@@ -199,7 +171,7 @@ export class SourceTrait extends ServiceTrait {
         /*  provide a registration for subsequent destruction  */
         return {
             destroy: async () => {
-                if (!this.sources.has(name))
+                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}`);
@@ -234,10 +206,10 @@ export class SourceTrait extends ServiceTrait {
         /*  subscribe to response topic (for ack/nak) and chunk topic (for data)  */
         const responseTopic = this.options.topicMake(name, "source-fetch-response", this.options.id);
         const chunkTopic = this.options.topicMake(name, "source-fetch-chunk", this.options.id);
-        await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.fetchSubscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-        spool.roll(() => this.fetchSubscriptions.unsubscribe(responseTopic));
-        await run(`subscribe to MQTT topic "${chunkTopic}"`, spool, () => this.fetchSubscriptions.subscribe(chunkTopic, { qos: options.qos ?? 2 }));
-        spool.roll(() => this.fetchSubscriptions.unsubscribe(chunkTopic));
+        await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
+        spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+        await run(`subscribe to MQTT topic "${chunkTopic}"`, spool, () => this.subscriptions.subscribe(chunkTopic, { qos: options.qos ?? 2 }));
+        spool.roll(() => this.subscriptions.unsubscribe(chunkTopic));
         /*  credit-based flow control state  */
         const chunkCredit = this.options.chunkCredit;
         let chunksReceived = 0;
@@ -247,7 +219,7 @@ export class SourceTrait extends ServiceTrait {
         const stream = new Readable({
             highWaterMark: chunkCredit > 0 ? chunkCredit * this.options.chunkSize : 16 * 1024,
             read: (_size) => {
-                if (chunkCredit <= 0 || !this.fetchChunkCallbacks.has(requestId))
+                if (chunkCredit <= 0 || !this.onResponse.has(`source-fetch-chunk:${requestId}`))
                     return;
                 const targetId = serverId ?? receiver;
                 if (!targetId)
@@ -295,7 +267,7 @@ export class SourceTrait extends ServiceTrait {
         stream.once("close", () => spool.unroll());
         stream.once("error", () => spool.unroll());
         /*  register response dispatch callback  */
-        this.fetchResponseCallbacks.set(requestId, (response) => {
+        this.onResponse.set(`source-fetch-response:${requestId}`, (response) => {
             if (response.sender)
                 serverId = response.sender;
             metaResolve?.(response.meta);
@@ -307,7 +279,7 @@ export class SourceTrait extends ServiceTrait {
                 refreshTimeout();
         });
         /*  register chunk dispatch callback  */
-        this.fetchChunkCallbacks.set(requestId, (response) => {
+        this.onResponse.set(`source-fetch-chunk:${requestId}`, (response) => {
             if (response.sender)
                 serverId = response.sender;
             if (response.error) {
@@ -327,8 +299,8 @@ export class SourceTrait extends ServiceTrait {
             }
         });
         spool.roll(() => {
-            this.fetchResponseCallbacks.delete(requestId);
-            this.fetchChunkCallbacks.delete(requestId);
+            this.onResponse.delete(`source-fetch-response:${requestId}`);
+            this.onResponse.delete(`source-fetch-chunk:${requestId}`);
         });
         /*  generate encoded message  */
         const auth = this.authenticate();
@@ -348,41 +320,4 @@ export class SourceTrait extends ServiceTrait {
         makeMutuallyExclusiveFields(result, "stream", "buffer");
         return result;
     }
-    /*  dispatch message (Source Fetch pattern handling)  */
-    async _dispatchMessage(topic, message) {
-        await super._dispatchMessage(topic, message);
-        const topicMatch = this.options.topicMatch(topic);
-        /*  handle source fetch request (on server-side)  */
-        if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-request"
-            && message instanceof SourceFetchRequest) {
-            const handler = this.sources.get(message.name);
-            if (handler !== undefined)
-                handler(message, topicMatch.name);
-        }
-        /*  handle source fetch response (on client-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-response"
-            && message instanceof SourceFetchResponse) {
-            const handler = this.fetchResponseCallbacks.get(message.id);
-            if (handler !== undefined)
-                handler(message);
-        }
-        /*  handle source fetch chunk (on client-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-chunk"
-            && message instanceof SourceFetchChunk) {
-            const handler = this.fetchChunkCallbacks.get(message.id);
-            if (handler !== undefined)
-                handler(message);
-        }
-        /*  handle source fetch credit (on server-side)  */
-        else if (topicMatch !== null
-            && topicMatch.operation === "source-fetch-credit"
-            && message instanceof SourceFetchCredit) {
-            const handler = this.sourceCreditCallbacks.get(message.id);
-            if (handler !== undefined)
-                handler(message);
-        }
-    }
 }

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

@@ -0,0 +1,20 @@
+import type { IClientSubscribeOptions } from "mqtt";
+import type { APISchema } from "./mqtt-plus-api";
+import { BaseTrait } from "./mqtt-plus-base";
+declare class RefCountedSubscription {
+    private subscribeFn;
+    private unsubscribeFn;
+    private lingerMs;
+    private counts;
+    private pending;
+    private lingers;
+    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>;
+    flush(): Promise<void>;
+}
+export declare class SubscriptionTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
+    protected subscriptions: RefCountedSubscription;
+    destroy(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,126 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+import { BaseTrait } from "./mqtt-plus-base";
+/*  reference-counted subscription helper  */
+class RefCountedSubscription {
+    constructor(subscribeFn, unsubscribeFn, lingerMs = 30 * 1000) {
+        this.subscribeFn = subscribeFn;
+        this.unsubscribeFn = unsubscribeFn;
+        this.lingerMs = lingerMs;
+        this.counts = new Map();
+        this.pending = new Map();
+        this.lingers = new Map();
+    }
+    /*  subscribe to a topic (reference-counted)  */
+    async subscribe(topic, options = { qos: 2 }) {
+        /*  increment count first to reserve our interest  */
+        const count = this.counts.get(topic) ?? 0;
+        this.counts.set(topic, count + 1);
+        /*  optionally just cancel a pending linger unsubscription
+            (subscription is still kept active on the broker)  */
+        const linger = this.lingers.get(topic);
+        if (linger) {
+            clearTimeout(linger);
+            this.lingers.delete(topic);
+            return;
+        }
+        /*  if we are the first, we must perform the actual subscription  */
+        if (count === 0) {
+            const promise = this.subscribeFn(topic, options).finally(() => {
+                this.pending.delete(topic);
+            }).catch((err) => {
+                const count = this.counts.get(topic);
+                if (count) {
+                    if (count <= 1)
+                        this.counts.delete(topic);
+                    else
+                        this.counts.set(topic, count - 1);
+                }
+                throw err;
+            });
+            this.pending.set(topic, promise);
+            return promise;
+        }
+        else {
+            /*  perhaps still need to wait for a pending subscription  */
+            const pending = this.pending.get(topic);
+            if (pending)
+                return pending.catch((err) => {
+                    const count = this.counts.get(topic);
+                    if (count) {
+                        if (count <= 1)
+                            this.counts.delete(topic);
+                        else
+                            this.counts.set(topic, count - 1);
+                    }
+                    throw err;
+                });
+        }
+    }
+    /*  unsubscribe from a topic (reference-counted)  */
+    async unsubscribe(topic) {
+        const count = this.counts.get(topic);
+        if (count) {
+            if (count <= 1) {
+                this.counts.delete(topic);
+                if (this.lingerMs > 0) {
+                    /*  defer the actual broker unsubscription  */
+                    const timer = setTimeout(() => {
+                        this.lingers.delete(topic);
+                        this.unsubscribeFn(topic).catch(() => { });
+                    }, this.lingerMs);
+                    this.lingers.set(topic, timer);
+                }
+                else
+                    await this.unsubscribeFn(topic).catch(() => { });
+            }
+            else
+                this.counts.set(topic, count - 1);
+        }
+    }
+    /*  flush all pending linger timers and unsubscribe  */
+    async flush() {
+        /*  cancel all pending linger timers first (synchronously)  */
+        const topics = [...this.lingers.keys()];
+        for (const topic of topics) {
+            clearTimeout(this.lingers.get(topic));
+            this.lingers.delete(topic);
+        }
+        /*  then unsubscribe from all lingered topics  */
+        for (const topic of topics)
+            await this.unsubscribeFn(topic).catch(() => { });
+    }
+}
+/*  Subscription trait with shared MQTT subscription management  */
+export class SubscriptionTrait extends BaseTrait {
+    constructor() {
+        super(...arguments);
+        this.subscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic));
+    }
+    /*  destroy topic trait  */
+    async destroy() {
+        await this.subscriptions.flush();
+        await super.destroy();
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { APISchema } from "./mqtt-plus-api";
+import { SubscriptionTrait } from "./mqtt-plus-subscription";
+export declare class TimerTrait<T extends APISchema = APISchema> extends SubscriptionTrait<T> {
+    private timers;
+    destroy(): Promise<void>;
+    protected timerRefresh(id: string, onTimeout: () => void): void;
+    protected timerClear(id: string): void;
+}

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

@@ -0,0 +1,57 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+import { SubscriptionTrait } from "./mqtt-plus-subscription";
+/*  Timer trait with reusable timer management  */
+export class TimerTrait extends SubscriptionTrait {
+    constructor() {
+        super(...arguments);
+        /*  internal state  */
+        this.timers = new Map();
+    }
+    /*  destroy timer trait  */
+    async destroy() {
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        await super.destroy();
+    }
+    /*  refresh (or start) a named timer  */
+    timerRefresh(id, onTimeout) {
+        const timer = this.timers.get(id);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.set(id, setTimeout(() => {
+            this.timers.delete(id);
+            onTimeout();
+        }, this.options.timeout));
+    }
+    /*  clear a named timer  */
+    timerClear(id) {
+        const timer = this.timers.get(id);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            this.timers.delete(id);
+        }
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { IClientSubscribeOptions } from "mqtt";
+import type { APISchema } from "./mqtt-plus-api";
+import { BaseTrait } from "./mqtt-plus-base";
+declare class RefCountedSubscription {
+    private subscribeFn;
+    private unsubscribeFn;
+    private lingerMs;
+    private counts;
+    private pending;
+    private lingers;
+    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>;
+    flush(): Promise<void>;
+}
+export declare class TopicTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
+    protected subscriptions: RefCountedSubscription;
+    destroy(): void;
+}
+export {};

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

@@ -0,0 +1,112 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+import { BaseTrait } from "./mqtt-plus-base";
+/*  reference-counted subscription helper  */
+class RefCountedSubscription {
+    constructor(subscribeFn, unsubscribeFn, lingerMs = 30 * 1000) {
+        this.subscribeFn = subscribeFn;
+        this.unsubscribeFn = unsubscribeFn;
+        this.lingerMs = lingerMs;
+        this.counts = new Map();
+        this.pending = new Map();
+        this.lingers = new Map();
+    }
+    async subscribe(topic, options = { qos: 2 }) {
+        /*  increment count first to reserve our interest  */
+        const count = this.counts.get(topic) ?? 0;
+        this.counts.set(topic, count + 1);
+        /*  optionally just cancel a pending linger unsubscription
+            (subscription is still kept active on the broker)  */
+        const linger = this.lingers.get(topic);
+        if (linger) {
+            clearTimeout(linger);
+            this.lingers.delete(topic);
+            return;
+        }
+        /*  if we are the first, we must perform the actual subscription  */
+        if (count === 0) {
+            const promise = this.subscribeFn(topic, options).finally(() => {
+                this.pending.delete(topic);
+            }).catch((err) => {
+                const count = this.counts.get(topic);
+                if (count) {
+                    if (count <= 1)
+                        this.counts.delete(topic);
+                    else
+                        this.counts.set(topic, count - 1);
+                }
+                throw err;
+            });
+            this.pending.set(topic, promise);
+            return promise;
+        }
+        else {
+            /*  perhaps still need to wait for a pending subscription  */
+            const pending = this.pending.get(topic);
+            if (pending)
+                return pending;
+        }
+    }
+    async unsubscribe(topic) {
+        const count = this.counts.get(topic);
+        if (count) {
+            if (count <= 1) {
+                this.counts.delete(topic);
+                if (this.lingerMs > 0) {
+                    /*  defer the actual broker unsubscription  */
+                    const timer = setTimeout(() => {
+                        this.lingers.delete(topic);
+                        this.unsubscribeFn(topic).catch(() => { });
+                    }, this.lingerMs);
+                    this.lingers.set(topic, timer);
+                }
+                else
+                    await this.unsubscribeFn(topic).catch(() => { });
+            }
+            else
+                this.counts.set(topic, count - 1);
+        }
+    }
+    async flush() {
+        /*  flush all pending linger timers and unsubscribe immediately  */
+        const topics = [...this.lingers.keys()];
+        for (const topic of topics) {
+            clearTimeout(this.lingers.get(topic));
+            this.lingers.delete(topic);
+            await this.unsubscribeFn(topic).catch(() => { });
+        }
+    }
+}
+/*  Topic trait with shared subscription management  */
+export class TopicTrait extends BaseTrait {
+    constructor() {
+        super(...arguments);
+        this.subscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic));
+    }
+    /*  destroy topic trait  */
+    destroy() {
+        this.subscriptions.flush();
+        super.destroy();
+    }
+}

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

@@ -33,6 +33,7 @@ class LogEvent {
         this.msg = msg;
         this.data = data;
     }
+    /*  resolve all pending promises in the log event  */
     async resolve() {
         if (this.msg instanceof Promise)
             this.msg = await this.msg.catch(() => "<resolve-failed>");
@@ -41,6 +42,7 @@ class LogEvent {
                 if (this.data[field] instanceof Promise)
                     this.data[field] = await this.data[field].catch(() => "<resolve-failed>");
     }
+    /*  render log event as string  */
     toString() {
         /*  render time  */
         const timestamp = new Date(this.timestamp);

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

@@ -1,17 +1,4 @@
 import { Readable } from "node:stream";
-import type { IClientSubscribeOptions } from "mqtt";
-export declare class RefCountedSubscription {
-    private subscribeFn;
-    private unsubscribeFn;
-    private lingerMs;
-    private counts;
-    private pending;
-    private lingers;
-    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>;
-    flush(): Promise<void>;
-}
 export declare class CreditGate {
     private remaining;
     private waiters;