mqtt-plus 1.4.11 → 1.4.12

package/AGENTS.md

@@ -65,10 +65,10 @@ each extending the previous. The final exported class `MQTTp` sits at
 the bottom of this chain:
 
 ```
-    OptionsTrait        — configuration (id, codec, timeout, chunkSize, chunkCredit, topicMake/topicMatch)
+    OptionsTrait        — configuration (id, codec, timeout, share, chunkSize, chunkCredit, topicMake/topicMatch)
   ↓ CodecTrait          — CBOR/JSON codec handling
-  ↓ EncodeTrait         — message encoding/validation (valibot schemas)
-  ↓ MsgTrait            — message class definitions and parsing
+  ↓ EncodeTrait         — string/buffer conversion utilities (str2buf, buf2str)
+  ↓ MsgTrait            — message class definitions, valibot schemas, and parsing
   ↓ TraceTrait          — EventEmitter + structured logging
   ↓ BaseTrait           — MQTT client hookup, subscription management, message routing
   ↓ SubscriptionTrait   — ref-counted MQTT topic subscription management
@@ -92,15 +92,15 @@ Each trait lives in its own file: `src/mqtt-plus-<trait>.ts`.
 | `src/mqtt-plus-api.ts`          | Branded endpoint type definitions (Event, Service, Source, Sink) and APISchema generic |
 | `src/mqtt-plus-info.ts`         | Info/context object types passed to pattern callbacks (sender metadata, etc.) |
 | `src/mqtt-plus-error.ts`        | Spool (resource cleanup) and run (error handling) utilities |
-| `src/mqtt-plus-util.ts`         | Stream/buffer conversion, RefCountedSubscription, and CreditGate flow control |
+| `src/mqtt-plus-util.ts`         | PLazy, CreditGate flow control, and stream/buffer collection utilities |
 | `src/mqtt-plus-version.ts`      | Version utility for converting version strings to numeric format |
-| `src/mqtt-plus-options.ts`      | OptionsTrait — configuration (id, codec, timeout, chunkSize, chunkCredit, topicMake/topicMatch) |
+| `src/mqtt-plus-options.ts`      | OptionsTrait — configuration (id, codec, timeout, share, chunkSize, chunkCredit, topicMake/topicMatch) |
 | `src/mqtt-plus-codec.ts`        | CodecTrait — CBOR and JSON codec encoding/decoding |
-| `src/mqtt-plus-encode.ts`       | EncodeTrait — message validation and encoding via valibot schemas |
-| `src/mqtt-plus-msg.ts`          | MsgTrait — message class definitions and parsing logic |
+| `src/mqtt-plus-encode.ts`       | EncodeTrait — string/buffer conversion utilities (str2buf, buf2str) |
+| `src/mqtt-plus-msg.ts`          | MsgTrait — message class definitions, valibot schemas, and parsing logic |
 | `src/mqtt-plus-trace.ts`        | TraceTrait — EventEmitter and structured logging |
 | `src/mqtt-plus-base.ts`         | BaseTrait — MQTT client connection, subscription management, message routing |
-| `src/mqtt-plus-subscription.ts` | SubscriptionTrait — ref-counted MQTT topic subscription management |
+| `src/mqtt-plus-subscription.ts` | SubscriptionTrait — RefCountedSubscription class and ref-counted MQTT topic subscription management |
 | `src/mqtt-plus-timer.ts`        | TimerTrait — named timer management (refresh/clear) |
 | `src/mqtt-plus-meta.ts`         | MetaTrait — instance and per-request metadata management |
 | `src/mqtt-plus-auth.ts`         | AuthTrait — JWT authentication (jose) and role-based access control |

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 ChangeLog
 =========
 
+1.4.12 (2026-03-05)
+-------------------
+
+- IMPROVEMENT: make all subscriptions ref-counted and spooled
+- UPDATE: update documentation
+- UPDATE: upgrade NPM dependencies
+- CLEANUP: cleanup code
+
 1.4.11 (2026-03-05)
 -------------------
 

package/README.md

@@ -176,7 +176,7 @@ Notice
 
 > [!Note]
 > **MQTT+** and its peer dependency **MQTT.js** provide a powerful
-> functionality, but are not small in size. **MQTT+** is 3.500 LoC
+> functionality, but are not small in size. **MQTT+** is 3.900 LoC
 > and 75 KB in size (ESM and CJS format). When bundled with all its
 > dependencies, it is 220 KB in size (UMD format). Its peer dependency
 > **MQTT.js** is 370 KB (ESM and CJS format) and 860 KB (UMD format) in

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

@@ -11,7 +11,6 @@ export declare class BaseTrait<T extends APISchema = APISchema> extends TraceTra
     constructor(mqtt: MqttClient | null, options?: Partial<APIOptions>);
     destroy(): Promise<void>;
     protected makeRegistration(spool: Spool, kind: string, name: string, key: string): Registration;
-    protected subscribeTopicAndSpool(spool: Spool, topic: string, options?: Partial<IClientSubscribeOptions>): 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>;

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

@@ -22,7 +22,7 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 import { TraceTrait } from "./mqtt-plus-trace";
-import { run, ensureError } from "./mqtt-plus-error";
+import { ensureError } from "./mqtt-plus-error";
 import { PLazy } from "./mqtt-plus-util";
 /*  MQTTp Base class with shared infrastructure  */
 export class BaseTrait extends TraceTrait {
@@ -94,11 +94,6 @@ export class BaseTrait extends TraceTrait {
             }
         };
     }
-    /*  subscribe to an MQTT topic and spool the unsubscription  */
-    async subscribeTopicAndSpool(spool, topic, options = {}) {
-        await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscribeTopic(topic, { qos: 2, ...options }));
-        spool.roll(() => this.unsubscribeTopic(topic).catch(() => { }));
-    }
     /*  subscribe to an MQTT topic (Promise-based)  */
     async subscribeTopic(topic, options = {}) {
         this.log("info", `subscribing to MQTT topic "${topic}"`);

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

@@ -137,8 +137,7 @@ export class ServiceTrait extends EventTrait {
             requestId = nanoid();
         /*  subscribe to MQTT response topic  */
         const responseTopic = this.options.topicMake(name, "service-call-response", this.options.id);
-        await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-        spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+        await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
         /*  create promise for MQTT response handling  */
         const timerId = `service-call:${requestId}`;
         const promise = new Promise((resolve, reject) => {

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

@@ -36,13 +36,13 @@ export class SinkTrait extends SourceTrait {
         this.pushStreams = new Map();
         this.pushSpools = new Map();
     }
-    /*  destroy sink trait  */
+    /*  destroy trait  */
     async destroy() {
         for (const stream of this.pushStreams.values())
             stream.destroy(new Error("sink destroyed"));
+        this.pushStreams.clear();
         for (const spool of this.pushSpools.values())
             await spool.unroll();
-        this.pushStreams.clear();
         this.pushSpools.clear();
         await super.destroy();
     }
@@ -76,7 +76,7 @@ export class SinkTrait extends SourceTrait {
         const topicReqB = this.options.topicMake(topicS, "sink-push-request");
         const topicReqD = this.options.topicMake(name, "sink-push-request", this.options.id);
         const topicChunkD = this.options.topicMake(name, "sink-push-chunk", this.options.id);
-        /*  remember the registration  */
+        /*  react on sink push request  */
         this.onRequest.set(`sink-push-request:${name}`, async (request, topicName) => {
             /*  determine information  */
             const requestId = request.id;
@@ -258,8 +258,7 @@ export class SinkTrait extends SourceTrait {
             requestId = nanoid();
         /*  subscribe to response topic (for ack/nak)  */
         const responseTopic = this.options.topicMake(name, "sink-push-response", this.options.id);
-        await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-        spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+        await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
         /*  define abort controller and signal  */
         const abortController = new AbortController();
         const abortSignal = abortController.signal;
@@ -326,8 +325,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: options.qos ?? 2 }));
-                spool.roll(() => this.subscriptions.unsubscribe(creditTopic));
+                await this.subscribeTopicAndSpool(spool, creditTopic, { qos: options.qos ?? 2 });
                 const gate = creditGate;
                 spool.roll(() => { gate.abort(); });
                 /*  update credit callback to include gate replenish  */

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

@@ -230,10 +230,8 @@ 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.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));
+        await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
+        await this.subscribeTopicAndSpool(spool, chunkTopic, { qos: options.qos ?? 2 });
         /*  credit-based flow control state  */
         const chunkCredit = this.options.chunkCredit;
         let chunksReceived = 0;

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

@@ -1,6 +1,7 @@
 import type { IClientSubscribeOptions } from "mqtt";
 import type { APISchema } from "./mqtt-plus-api";
 import { BaseTrait } from "./mqtt-plus-base";
+import { Spool } from "./mqtt-plus-error";
 declare class RefCountedSubscription {
     private subscribeFn;
     private unsubscribeFn;
@@ -18,6 +19,7 @@ declare class RefCountedSubscription {
 }
 export declare class SubscriptionTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
     protected subscriptions: RefCountedSubscription;
+    protected subscribeTopicAndSpool(spool: Spool, topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
     destroy(): Promise<void>;
 }
 export {};

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

@@ -22,6 +22,7 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 import { BaseTrait } from "./mqtt-plus-base";
+import { run } from "./mqtt-plus-error";
 /*  reference-counted subscription helper  */
 class RefCountedSubscription {
     /*  initial construction with configuration  */
@@ -162,6 +163,11 @@ export class SubscriptionTrait extends BaseTrait {
         super(...arguments);
         this.subscriptions = new RefCountedSubscription((topic, options) => this.subscribeTopic(topic, options), (topic) => this.unsubscribeTopic(topic));
     }
+    /*  subscribe to an MQTT topic (reference-counted) and spool the unsubscription  */
+    async subscribeTopicAndSpool(spool, topic, options = {}) {
+        await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscriptions.subscribe(topic, { qos: 2, ...options }));
+        spool.roll(() => this.subscriptions.unsubscribe(topic));
+    }
     /*  destroy subscription trait  */
     async destroy() {
         await this.subscriptions.flush();

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

@@ -972,12 +972,6 @@ class BaseTrait extends TraceTrait {
       }
     };
   }
-  /*  subscribe to an MQTT topic and spool the unsubscription  */
-  async subscribeTopicAndSpool(spool, topic, options = {}) {
-    await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscribeTopic(topic, { qos: 2, ...options }));
-    spool.roll(() => this.unsubscribeTopic(topic).catch(() => {
-    }));
-  }
   /*  subscribe to an MQTT topic (Promise-based)  */
   async subscribeTopic(topic, options = {}) {
     this.log("info", `subscribing to MQTT topic "${topic}"`);
@@ -1191,6 +1185,11 @@ class SubscriptionTrait extends BaseTrait {
     super(...arguments);
     this.subscriptions = new RefCountedSubscription((topic, options) => this.subscribeTopic(topic, options), (topic) => this.unsubscribeTopic(topic));
   }
+  /*  subscribe to an MQTT topic (reference-counted) and spool the unsubscription  */
+  async subscribeTopicAndSpool(spool, topic, options = {}) {
+    await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscriptions.subscribe(topic, { qos: 2, ...options }));
+    spool.roll(() => this.subscriptions.unsubscribe(topic));
+  }
   /*  destroy subscription trait  */
   async destroy() {
     await this.subscriptions.flush();
@@ -1522,8 +1521,7 @@ class ServiceTrait extends EventTrait {
     while (this.onResponse.has(`service-call-response:${requestId}`))
       requestId = nanoid.nanoid();
     const responseTopic = this.options.topicMake(name, "service-call-response", this.options.id);
-    await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-    spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+    await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
     const timerId = `service-call:${requestId}`;
     const promise = new Promise((resolve, reject) => {
       this.timerRefresh(timerId, async () => {
@@ -1719,10 +1717,8 @@ class SourceTrait extends ServiceTrait {
       requestId = nanoid.nanoid();
     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.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));
+    await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
+    await this.subscribeTopicAndSpool(spool, chunkTopic, { qos: options.qos ?? 2 });
     const chunkCredit = this.options.chunkCredit;
     let chunksReceived = 0;
     let creditGranted = chunkCredit;
@@ -1835,13 +1831,13 @@ class SinkTrait extends SourceTrait {
     this.pushStreams = /* @__PURE__ */ new Map();
     this.pushSpools = /* @__PURE__ */ new Map();
   }
-  /*  destroy sink trait  */
+  /*  destroy trait  */
   async destroy() {
     for (const stream of this.pushStreams.values())
       stream.destroy(new Error("sink destroyed"));
+    this.pushStreams.clear();
     for (const spool of this.pushSpools.values())
       await spool.unroll();
-    this.pushStreams.clear();
     this.pushSpools.clear();
     await super.destroy();
   }
@@ -2033,8 +2029,7 @@ class SinkTrait extends SourceTrait {
     while (this.onResponse.has(`sink-push-response:${requestId}`) || this.onResponse.has(`sink-push-credit:${requestId}`))
       requestId = nanoid.nanoid();
     const responseTopic = this.options.topicMake(name, "sink-push-response", this.options.id);
-    await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-    spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+    await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
     const abortController = new AbortController();
     const abortSignal = abortController.signal;
     if (data instanceof node_stream.Readable) {
@@ -2098,8 +2093,7 @@ class SinkTrait extends SourceTrait {
         creditGate = new CreditGate(initialCredit);
       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: options.qos ?? 2 }));
-        spool.roll(() => this.subscriptions.unsubscribe(creditTopic));
+        await this.subscribeTopicAndSpool(spool, creditTopic, { qos: options.qos ?? 2 });
         const gate = creditGate;
         spool.roll(() => {
           gate.abort();

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

@@ -951,12 +951,6 @@ class BaseTrait extends TraceTrait {
       }
     };
   }
-  /*  subscribe to an MQTT topic and spool the unsubscription  */
-  async subscribeTopicAndSpool(spool, topic, options = {}) {
-    await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscribeTopic(topic, { qos: 2, ...options }));
-    spool.roll(() => this.unsubscribeTopic(topic).catch(() => {
-    }));
-  }
   /*  subscribe to an MQTT topic (Promise-based)  */
   async subscribeTopic(topic, options = {}) {
     this.log("info", `subscribing to MQTT topic "${topic}"`);
@@ -1170,6 +1164,11 @@ class SubscriptionTrait extends BaseTrait {
     super(...arguments);
     this.subscriptions = new RefCountedSubscription((topic, options) => this.subscribeTopic(topic, options), (topic) => this.unsubscribeTopic(topic));
   }
+  /*  subscribe to an MQTT topic (reference-counted) and spool the unsubscription  */
+  async subscribeTopicAndSpool(spool, topic, options = {}) {
+    await run(`subscribe to MQTT topic "${topic}"`, spool, () => this.subscriptions.subscribe(topic, { qos: 2, ...options }));
+    spool.roll(() => this.subscriptions.unsubscribe(topic));
+  }
   /*  destroy subscription trait  */
   async destroy() {
     await this.subscriptions.flush();
@@ -1501,8 +1500,7 @@ class ServiceTrait extends EventTrait {
     while (this.onResponse.has(`service-call-response:${requestId}`))
       requestId = nanoid();
     const responseTopic = this.options.topicMake(name, "service-call-response", this.options.id);
-    await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-    spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+    await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
     const timerId = `service-call:${requestId}`;
     const promise = new Promise((resolve, reject) => {
       this.timerRefresh(timerId, async () => {
@@ -1698,10 +1696,8 @@ class SourceTrait extends ServiceTrait {
       requestId = nanoid();
     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.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));
+    await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
+    await this.subscribeTopicAndSpool(spool, chunkTopic, { qos: options.qos ?? 2 });
     const chunkCredit = this.options.chunkCredit;
     let chunksReceived = 0;
     let creditGranted = chunkCredit;
@@ -1814,13 +1810,13 @@ class SinkTrait extends SourceTrait {
     this.pushStreams = /* @__PURE__ */ new Map();
     this.pushSpools = /* @__PURE__ */ new Map();
   }
-  /*  destroy sink trait  */
+  /*  destroy trait  */
   async destroy() {
     for (const stream of this.pushStreams.values())
       stream.destroy(new Error("sink destroyed"));
+    this.pushStreams.clear();
     for (const spool of this.pushSpools.values())
       await spool.unroll();
-    this.pushStreams.clear();
     this.pushSpools.clear();
     await super.destroy();
   }
@@ -2012,8 +2008,7 @@ class SinkTrait extends SourceTrait {
     while (this.onResponse.has(`sink-push-response:${requestId}`) || this.onResponse.has(`sink-push-credit:${requestId}`))
       requestId = nanoid();
     const responseTopic = this.options.topicMake(name, "sink-push-response", this.options.id);
-    await run(`subscribe to MQTT topic "${responseTopic}"`, spool, () => this.subscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 }));
-    spool.roll(() => this.subscriptions.unsubscribe(responseTopic));
+    await this.subscribeTopicAndSpool(spool, responseTopic, { qos: options.qos ?? 2 });
     const abortController = new AbortController();
     const abortSignal = abortController.signal;
     if (data instanceof Readable) {
@@ -2077,8 +2072,7 @@ class SinkTrait extends SourceTrait {
         creditGate = new CreditGate(initialCredit);
       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: options.qos ?? 2 }));
-        spool.roll(() => this.subscriptions.unsubscribe(creditTopic));
+        await this.subscribeTopicAndSpool(spool, creditTopic, { qos: options.qos ?? 2 });
         const gate = creditGate;
         spool.roll(() => {
           gate.abort();