mqtt-plus 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 ChangeLog
 =========
 
+1.4.6 (2026-02-22)
+------------------
+
+- IMPROVEMENT: improve rendering of about information and add chalk for sample code
+- DOCUMENTATION: update sample code
+- DOCUMENTATION: adjust about description
+
+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

@@ -16,12 +16,25 @@ 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
-[communication patterns](doc/mqtt-plus-comm.md)
-*Event Emission*, *Service Call*, *Sink Push* and *Source Fetch* are
-supported.
+API [MQTT.js](https://www.npmjs.com/package/mqtt), designed to
+extend [MQTT](http://mqtt.org/) with higher-level
+[communication patterns](doc/mqtt-plus-comm.md) while preserving full type-safety.
+It provides four core communication patterns: fire-and-forget *Event
+Emission*, RPC-style *Service Call*, stream-based *Sink Push*, and
+stream-based *Source Fetch*.
+These patterns enable structured,
+bi-directional client/server and server/server communication
+on top of [MQTT](http://mqtt.org/)’s inherently uni-directional publish/subscribe model.
+Internally, the communication is based on the exchange of typed [CBOR](https://www.rfc-editor.org/rfc/rfc8949.html)
+or [JSON](https://ecma-international.org/publications-and-standards/standards/ecma-404/) messages.
+
+The result is a more expressive and maintainable messaging layer
+without sacrificing [MQTT](http://mqtt.org/)’s excellent robustness and
+scalability.
+**MQTT+** is particularly well suited for systems built around a
+[*Hub & Spoke*](https://en.wikipedia.org/wiki/Spoke%E2%80%93hub_distribution_paradigm)
+communication architecture, where typed API contracts and controlled interaction flows are
+critical for reliability and long-term maintainability.
 
 Installation
 ------------
@@ -33,16 +46,25 @@ $ npm install mqtt mqtt-plus
 Usage
 -----
 
-### API:
-
-The API type defines the available endpoints. Use the marker types
-`Event<T>`, `Service<T>`, `Source<T>`, and `Sink<T>` to declare the
-communication pattern of each endpoint:
+The following is a simple but self-contained example usage of
+**MQTT+** based on a common API, a server part, a client part,
+and a MQTT infrastructure. It can be found in the file
+[sample.ts](sample/sample.ts) and can be executed from the **MQTT+**
+source tree via `npm start sample` (assuming the prerequisite *Docker* is
+available for the underlying *Mosquitto* broker based infrastructure):
 
 ```ts
+import { Readable }                          from "node:stream"
+import chalk                                 from "chalk"
+import Mosquitto                             from "mosquitto"
+import MQTT                                  from "mqtt"
+import MQTTp                                 from "mqtt-plus"
 import type { Event, Service, Source, Sink } from "mqtt-plus"
+```
 
-export type API = {
+```ts
+/*  ==== SAMPLE COMMON API ====  */
+type API = {
     "example/sample":   Event<(a1: string, a2: number) => void>
     "example/hello":    Service<(a1: string, a2: number) => string>
     "example/download": Source<(filename: string) => void>
@@ -50,67 +72,84 @@ export type API = {
 }
 ```
 
-The marker types ensure that `event()` and `emit()` only accept
-`Event<T>` endpoints, `service()` and `call()` only accept
-`Service<T>` endpoints, `source()` and `fetch()` only
-accept `Source<T>` endpoints, and `sink()` and `push()` only
-accept `Sink<T>` endpoints.
-
-### Server:
-
 ```ts
-import MQTT         from "mqtt"
-import MQTTp        from "mqtt-plus"
-import type { API } from [...]
-
-const mqtt  = MQTT.connect("wss://127.0.0.1:8883", { [...] })
-const mqttp = new MQTTp<API>(mqtt)
-
-mqtt.on("connect", async () => {
-    await mqttp.event("example/sample", (a1, a2, info) => {
-        console.log("example/sample: SERVER:", a1, a2, info.sender)
+/*  ==== SAMPLE SERVER ====  */
+const Server = async (api: MQTTp<API>, log: (msg: string, ...args: any[]) => void) => {
+    await api.event("example/sample", (a1, a2) => {
+        log("example/sample: SERVER:", a1, a2)
     })
-    await mqttp.service("example/hello", (a1, a2, info) => {
-        console.log("example/hello: SERVER:", a1, a2, info.sender)
+    await api.service("example/hello", (a1, a2) => {
+        log("example/hello: SERVER:", a1, a2)
         return `${a1}:${a2}`
     })
-    await mqttp.source("example/download", async (filename, info) => {
-        console.log("example/download: SERVER:", filename, info.sender)
-        info.buffer = Promise.resolve(mqttp.str2buf(`the ${filename} content`))
+    await api.source("example/download", async (filename, info) => {
+        log("example/download: SERVER:", filename)
+        const input = new Readable()
+        input.push(api.str2buf(`the ${filename} content`))
+        input.push(null)
+        info.stream = readable
     })
-    await mqttp.sink("example/upload", async (filename, info) => {
-        console.log("example/upload: SERVER:", filename, info.sender)
-        const data = await info.buffer
-        console.log("received", data.length, "bytes")
+    await api.sink("example/upload", async (filename, info) => {
+        log("example/upload: SERVER:", filename)
+        const chunks: Uint8Array[] = []
+        info.stream!.on("data", (chunk: Uint8Array) => { chunks.push(chunk) })
+        await new Promise<void>((resolve) => { info.stream!.once("end", resolve) })
+        const total = chunks.reduce((n, c) => n + c.length, 0)
+        log("received", total, "bytes")
     })
-})
+}
 ```
 
-### Client:
-
 ```ts
-import MQTT         from "mqtt"
-import MQTTp        from "mqtt-plus"
-import type { API } from [...]
-
-const mqtt = MQTT.connect("wss://127.0.0.1:8883", { [...] })
-const mqttp = new MQTTp<API>(mqtt)
+/*  ==== SAMPLE CLIENT ====  */
+const Client = async (api: MQTTp<API>, log: (msg: string, ...args: any[]) => void) => {
+    api.emit("example/sample", "world", 42)
+
+    const callOutput = await api.call("example/hello", "world", 42)
+    log("example/hello: CLIENT:", callOutput)
+
+    const output = await api.fetch("example/download", "foo")
+    const chunks: Uint8Array[] = []
+    output.stream.on("data", (chunk: Uint8Array) => { chunks.push(chunk) })
+    await new Promise<void>((resolve) => { output.stream.on("end", resolve) })
+    const data = api.buf2str(Buffer.concat(chunks))
+    log("example/download: CLIENT:", data)
+
+    const input = new Readable()
+    input.push(api.str2buf("uploaded content"))
+    input.push(null)
+    await api.push("example/upload", input, "myfile.txt")
+}
+```
 
+```ts
+/*  ==== SAMPLE INFRASTRUCTURE ====  */
+process.on("uncaughtException", (err: Error): void => {
+    console.error(chalk.red(`ERROR: ${err.stack ?? err.message}`))
+    console.log(chalk.yellow(mosquitto.logs()))
+    process.exit(1)
+})
+const mosquitto = new Mosquitto({
+    listen: [ { protocol: "mqtt", address: "127.0.0.1", port: 1883 } ]
+})
+await mosquitto.start()
+const mqtt = MQTT.connect("mqtt://127.0.0.1:1883", {
+    username: "example", password: "example"
+})
+const api = new MQTTp<API>(mqtt)
+api.on("log", async (entry) => {
+    await entry.resolve()
+    console.log(chalk.grey(`api: ${entry}`))
+})
+const log = (msg: string, ...args: any[]) => {
+    console.log(chalk.bold.blue("app:"), chalk.blue(msg), chalk.red(JSON.stringify(args)))
+}
 mqtt.on("connect", async () => {
-    mqttp.emit("example/sample", "world", 42)
-
-    const callOutput = await mqttp.call("example/hello", "world", 42)
-    console.log("example/hello: CLIENT:", callOutput)
-
-    const fetchOutput = await mqttp.fetch("example/download", "foo")
-    const data = mqttp.buf2str(await fetchOutput.buffer)
-    console.log("example/download: CLIENT:", data)
-
-    const pushInput = mqttp.str2buf("uploaded content")
-    await mqttp.push("example/upload", pushInput, "myfile.txt")
-
-    mqttp.destroy()
-    mqtt.end()
+    await Server(api, log)
+    await Client(api, log)
+    await api.destroy()
+    await mqtt.endAsync()
+    await mosquitto.stop()
 })
 ```
 

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>;