mqtt-plus 1.4.9 → 1.4.11

package/AGENTS.md

@@ -33,11 +33,13 @@ npm start sample        # run sample/sample.ts via `tsx`
 
 npm start clean         # remove dst-stage1/ and dst-stage2/
 npm start distclean     # remove node_modules/ and package-lock.json
+npm start publish       # publish to npm (restricted to maintainer host)
 
 ```
 
-Tests require a Mosquitto MQTT broker under run-time; the `mosquitto`
-npm package provides one that the test suite starts/stops automatically.
+Tests require an MQTT broker under run-time; the test suite starts/stops
+one automatically. If Docker is available, a Mosquitto broker is used;
+otherwise, the Aedes in-process broker serves as the fallback.
 
 Build Pipeline
 --------------
@@ -51,7 +53,7 @@ Two-stage build:
    `mqtt-plus.esm.js`, `mqtt-plus.cjs.js`, `mqtt-plus.umd.js`.
    UMD build includes Node polyfills (events, stream, buffer).
 
-Configuration lives in `etc/`: `tsc.json`, `vite.mts`, `eslint.mts`, `knip.jsonc`, `stx.conf`, `d2.mts`.
+Configuration lives in `etc/`: `tsc.json`, `vite.mts`, `eslint.mts`, `knip.jsonc`, `stx.conf`, `d2.mts`, `d2.theme.d2`, `logo.ai`, `logo.svg`.
 
 Architecture
 ------------
@@ -70,6 +72,7 @@ the bottom of this chain:
   ↓ TraceTrait          — EventEmitter + structured logging
   ↓ BaseTrait           — MQTT client hookup, subscription management, message routing
   ↓ SubscriptionTrait   — ref-counted MQTT topic subscription management
+  ↓ TimerTrait          — named timer management (refresh/clear)
   ↓ MetaTrait           — instance/per-request metadata
   ↓ AuthTrait           — JWT authentication (jose), role-based access
   ↓ EventTrait          — Event Emission pattern (event/emit)
@@ -98,6 +101,7 @@ Each trait lives in its own file: `src/mqtt-plus-<trait>.ts`.
 | `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-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 |
 | `src/mqtt-plus-event.ts`        | EventTrait — Event Emission communication pattern (event/emit) |

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 ChangeLog
 =========
 
+1.4.11 (2026-03-05)
+-------------------
+
+- IMPROVEMENT: improve error handling and use error ensure function consistently
+- IMPROVEMENT: improve cleanup handling and correctly track resources
+- IMPROVEMENT: improve typing and fix overloads
+- IMPROVEMENT: avoid warning in Vite
+- BUGFIX: fix building for Vite compatibility
+- BUGFIX: avoid unhandled rejection error
+- BUGFIX: fix test
+- UPDATE: update documentation
+- UPDATE: upgrade NPM dependencies
+- CLEANUP: rename emit() parameter "event" to "name" for consistency
+- CLEANUP: cleanup code
+
+1.4.10 (2026-03-01)
+-------------------
+
+- IMPROVEMENT: improve performance
+- IMPROVEMENT: improve typing and export more public API types
+- IMPROVEMENT: improve description
+- BUGFIX: fix error handling and destruction problems
+- BUGFIX: fix name of module
+- BUGFIX: do not make fields exclusive
+- UPDATE: upgrade NPM dependencies
+- CLEANUP: various code cleanups (simplification, formatting, comments, output polishing)
+- CLEANUP: cleanups for error handling
+
 1.4.9 (2026-02-22)
 ------------------
 

package/doc/mqtt-plus-api.md

@@ -65,7 +65,7 @@ describing the available events, services, sources, and sinks.
 Destruction
 -----------
 
-    destroy(): void
+    destroy(): Promise<void>
 
 Clean up the MQTT+ instance by removing all event listeners.
 Call this method when the instance is no longer needed.
@@ -265,18 +265,18 @@ Event Emission
 
     /*  (simplified TypeScript API method signature)  */
     emit(
-        event:     string,
+        name:      string,
         ...params: any[]
     ): void
     emit({
-        event:     string,
+        name:      string,
         params:    any[],
         receiver?: string,
         options?:  MQTT::IClientPublishOptions,
         meta?:     Record<string, any>
     }): void
     emit({
-        event:     string,
+        name:      string,
         params:    any[],
         receiver?: string,
         options?:  MQTT::IClientPublishOptions,
@@ -300,8 +300,8 @@ Emit an event to all subscribers or a specific subscriber ("fire and forget").
 - The remote `event()` `callback` is called with `params` and its
   return value is silently ignored.
 
-- Internally, publishes to the MQTT topic by `topicMake(event, "event-emission", peerId)`
-  (default: `${event}/event-emission/any` or `${event}/event-emission/${peerId}`).
+- Internally, publishes to the MQTT topic by `topicMake(name, "event-emission", peerId)`
+  (default: `${name}/event-emission/any` or `${name}/event-emission/${peerId}`).
 
 - *Dry-Run Publishing for MQTT Last-Will:*
   When you need to set up an MQTT "last will" message (automatically published
@@ -315,7 +315,7 @@ Emit an event to all subscribers or a specific subscriber ("fire and forget").
     const mqttpDry = new MQTTp<API>(null, { id: "my-client" })
     const will = mqttpDry.emit({
         dry:    true,
-        event:  "example/connection",
+        name:   "example/connection",
         params: [ "close" ],
         [...]
     })

package/doc/mqtt-plus-internals.md

@@ -122,8 +122,6 @@ Exactly one of `result` or `error` is present.
 |----------|------------------------|----------|-------------------------------|
 | `name`   | `string`               | yes      | Sink endpoint name            |
 | `error`  | `string`               | no       | Error message (nak) or absent (ack) |
-| `auth`   | `string[]`             | no       | JWT tokens (max 8)            |
-| `meta`   | `Record<string, any>`  | no       | Arbitrary metadata            |
 | `credit` | `integer`              | no       | Initial flow control credit (min 1) |
 
 ### `sink-push-chunk`
@@ -158,7 +156,6 @@ Exactly one of `result` or `error` is present.
 |----------|------------------------|----------|-------------------------------|
 | `name`   | `string`               | yes      | Source endpoint name          |
 | `error`  | `string`               | no       | Error message (nak) or absent (ack) |
-| `auth`   | `string[]`             | no       | JWT tokens (max 8)            |
 | `meta`   | `Record<string, any>`  | no       | Arbitrary metadata            |
 
 ### `source-fetch-chunk`

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

@@ -1,4 +1,4 @@
-import { MqttClient, type IClientSubscribeOptions, type IClientPublishOptions } from "mqtt";
+import { type MqttClient, type IClientSubscribeOptions, type IClientPublishOptions } from "mqtt";
 import type { APISchema, Registration } from "./mqtt-plus-api";
 import type { APIOptions } from "./mqtt-plus-options";
 import { TraceTrait } from "./mqtt-plus-trace";

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

@@ -11,16 +11,16 @@ export declare class EventTrait<T extends APISchema = APISchema> extends AuthTra
         share?: string;
         auth?: AuthOption;
     }): Promise<Registration>;
-    emit<K extends EventKeys<T> & string>(event: K, ...params: Parameters<T[K]>): void;
+    emit<K extends EventKeys<T> & string>(name: K, ...params: Parameters<T[K]>): void;
     emit<K extends EventKeys<T> & string>(config: {
-        event: K;
+        name: K;
         params: Parameters<T[K]>;
         receiver?: string;
         options?: IClientPublishOptions;
         meta?: Record<string, any>;
     }): void;
     emit<K extends EventKeys<T> & string>(config: {
-        event: K;
+        name: K;
         params: Parameters<T[K]>;
         receiver?: string;
         options?: IClientPublishOptions;

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

@@ -92,7 +92,7 @@ export class EventTrait extends AuthTrait {
     }
     emit(eventOrConfig, ...args) {
         /*  determine actual parameters  */
-        let event;
+        let name;
         let params;
         let receiver;
         let options = {};
@@ -100,7 +100,7 @@ export class EventTrait extends AuthTrait {
         let dry;
         if (typeof eventOrConfig === "object" && eventOrConfig !== null) {
             /*  object-based API  */
-            event = eventOrConfig.event;
+            name = eventOrConfig.name;
             params = eventOrConfig.params;
             receiver = eventOrConfig.receiver;
             options = eventOrConfig.options ?? {};
@@ -109,7 +109,7 @@ export class EventTrait extends AuthTrait {
         }
         else {
             /*  positional API  */
-            event = eventOrConfig;
+            name = eventOrConfig;
             params = args;
         }
         /*  generate unique request id  */
@@ -117,10 +117,10 @@ export class EventTrait extends AuthTrait {
         /*  generate encoded message  */
         const auth = this.authenticate();
         const metaStore = this.metaStore(meta);
-        const request = this.msg.makeEventEmission(requestId, event, params, this.options.id, receiver, auth, metaStore);
+        const request = this.msg.makeEventEmission(requestId, name, params, this.options.id, receiver, auth, metaStore);
         const message = this.codec.encode(request);
         /*  generate corresponding MQTT topic  */
-        const topic = this.options.topicMake(event, "event-emission", receiver);
+        const topic = this.options.topicMake(name, "event-emission", receiver);
         /*  produce result  */
         if (dry)
             /*  return publish information  */
@@ -128,7 +128,7 @@ export class EventTrait extends AuthTrait {
         else
             /*  publish message to MQTT topic  */
             this.publishToTopic(topic, message, { qos: 2, ...options }).catch((err) => {
-                this.error(err, `emitting event "${event}" failed`);
+                this.error(err, `emitting event "${name}" failed`);
             });
     }
 }

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

@@ -98,7 +98,7 @@ export class ServiceTrait extends EventTrait {
                     await this.publishToTopic(topic, encoded, { qos: options.qos ?? 2 });
                 }
                 catch (err2) {
-                    this.error(ensureError(err2), `handler for service "${name}" failed`);
+                    this.error(ensureError(err2), `sending error response for service "${name}" failed`);
                 }
             }
         });

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

@@ -39,7 +39,7 @@ export class SinkTrait extends SourceTrait {
     /*  destroy sink trait  */
     async destroy() {
         for (const stream of this.pushStreams.values())
-            stream.destroy();
+            stream.destroy(new Error("sink destroyed"));
         for (const spool of this.pushSpools.values())
             await spool.unroll();
         this.pushStreams.clear();
@@ -178,6 +178,7 @@ export class SinkTrait extends SourceTrait {
                 reqSpool.roll(() => { clearPushTimeout(); });
                 /*  prepare info object  */
                 const promise = streamToBuffer(readable);
+                promise.catch(() => { }); /*  avoid unhandled promise rejection  */
                 const info = {
                     sender,
                     stream: readable,
@@ -194,22 +195,21 @@ export class SinkTrait extends SourceTrait {
                 await sendResponse();
                 ackSent = true;
                 /*  call handler  */
-                return await callback(...params, info);
+                await callback(...params, info);
             }
             catch (err) {
-                const error = ensureError(err);
+                const error = ensureError(err, `handler for sink "${name}" failed`);
                 /*  cleanup resources  */
                 const stream = this.pushStreams.get(requestId);
                 if (stream !== undefined)
                     stream.destroy(error);
-                reqSpool.unroll();
-                /*  send error as nak response or as error chunk  */
+                await reqSpool.unroll();
+                /*  send error as nak response or as mid-stream error response  */
                 this.error(error);
                 if (ackSent) {
-                    const chunkTopic = this.options.topicMake(name, "sink-push-chunk", sender);
-                    const chunkMsg = this.msg.makeSinkPushChunk(requestId, name, undefined, error.message, true, this.options.id, sender);
-                    const message = this.codec.encode(chunkMsg);
-                    await this.publishToTopic(chunkTopic, message, { qos: options.qos ?? 2 }).catch(() => { });
+                    const responseMsg = this.msg.makeSinkPushResponse(requestId, name, error.message, this.options.id, sender);
+                    const message = this.codec.encode(responseMsg);
+                    await this.publishToTopic(responseTopic, message, { qos: options.qos ?? 2 }).catch(() => { });
                 }
                 else
                     await sendResponse(error.message).catch(() => { });
@@ -263,10 +263,19 @@ export class SinkTrait extends SourceTrait {
         /*  define abort controller and signal  */
         const abortController = new AbortController();
         const abortSignal = abortController.signal;
+        /*  ensure stream gets destroyed on abort  */
+        if (data instanceof Readable) {
+            const stream = data;
+            abortSignal.addEventListener("abort", () => {
+                if (!stream.destroyed)
+                    stream.destroy(ensureError(abortSignal.reason));
+            }, { once: true });
+        }
         /*  utility function for timeout refresh  */
         const pushTimerId = `sink-push-send:${requestId}`;
         const refreshTimeout = () => this.timerRefresh(pushTimerId, () => {
-            abortController.abort(new Error(`push to sink "${name}" timed out`));
+            const error = new Error(`push to sink "${name}" timed out`);
+            abortController.abort(error);
             spool.unroll();
         });
         spool.roll(() => { this.timerClear(pushTimerId); });
@@ -275,6 +284,7 @@ export class SinkTrait extends SourceTrait {
         /*  send request and wait for response before sending chunks  */
         let initialCredit;
         let creditGate;
+        let remoteError = false;
         try {
             await new Promise((resolve, reject) => {
                 /*  handle abort signal  */
@@ -293,10 +303,6 @@ export class SinkTrait extends SourceTrait {
                     }
                 });
                 spool.roll(() => { this.onResponse.delete(`sink-push-response:${requestId}`); });
-                this.onResponse.set(`sink-push-credit:${requestId}`, (_response) => {
-                    refreshTimeout();
-                });
-                spool.roll(() => { this.onResponse.delete(`sink-push-credit:${requestId}`); });
                 /*  generate and send request message  */
                 const auth = this.authenticate();
                 const metaStore = this.metaStore(meta);
@@ -309,8 +315,10 @@ export class SinkTrait extends SourceTrait {
             });
             /*  override handler for mid-stream (error) responses  */
             this.onResponse.set(`sink-push-response:${requestId}`, (response) => {
-                if (response.error)
+                if (response.error) {
+                    remoteError = true;
                     abortController.abort(new Error(response.error));
+                }
             });
             /*  create credit gate for flow control (if server granted credit)  */
             if (initialCredit !== undefined && initialCredit > 0)
@@ -327,6 +335,7 @@ export class SinkTrait extends SourceTrait {
                     gate.replenish(response.credit);
                     refreshTimeout();
                 });
+                spool.roll(() => { this.onResponse.delete(`sink-push-credit:${requestId}`); });
             }
             /*  generate corresponding MQTT topic for chunks  */
             const chunkTopic = this.options.topicMake(name, "sink-push-chunk", receiver);
@@ -346,12 +355,13 @@ export class SinkTrait extends SourceTrait {
                 await sendBufferAsChunks(data, this.options.chunkSize, sendChunk, creditGate, abortSignal);
         }
         catch (err) {
-            /*  send error chunk only if receiver is known
+            const error = ensureError(err);
+            abortController.abort(error);
+            /*  send error chunk only if receiver is known and error did not originate from receiver
                 (otherwise the sink already received the error via the nak response)  */
-            if (receiver !== undefined) {
-                const error = ensureError(err).message;
+            if (receiver !== undefined && !remoteError) {
                 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 chunkMsg = this.msg.makeSinkPushChunk(requestId, name, undefined, error.message, true, this.options.id, receiver);
                 const message = this.codec.encode(chunkMsg);
                 await this.publishToTopic(chunkTopic, message, { qos: 2, ...options }).catch(() => { });
             }

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;
+    private sourceControllers;
     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: {

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

@@ -34,9 +34,13 @@ export class SourceTrait extends ServiceTrait {
         super(...arguments);
         /*  source state  */
         this.sourceCreditGates = new Map();
+        this.sourceControllers = new Map();
     }
     /*  destroy source trait  */
     async destroy() {
+        for (const controller of this.sourceControllers.values())
+            controller.abort(new Error("source destroyed"));
+        this.sourceControllers.clear();
         for (const gate of this.sourceCreditGates.values())
             gate.abort();
         this.sourceCreditGates.clear();
@@ -96,12 +100,27 @@ export class SourceTrait extends ServiceTrait {
                 const message = this.codec.encode(response);
                 await this.publishToTopic(responseTopic, message, { qos: options.qos ?? 2 });
             };
+            /*  define abort controller and signal  */
+            const abortController = new AbortController();
+            this.sourceControllers.set(requestId, abortController);
+            const abortSignal = abortController.signal;
+            /*  ensure stream gets destroyed on abort  */
+            abortSignal.addEventListener("abort", () => {
+                if (info.stream instanceof Readable && !info.stream.destroyed)
+                    info.stream.destroy(ensureError(abortSignal.reason));
+            }, { once: true });
             /*  utility functions for timeout management  */
             const sourceTimerId = `source-fetch-send:${requestId}`;
             const refreshSourceTimeout = () => this.timerRefresh(sourceTimerId, () => {
+                const error = new Error(`source fetch "${name}" timed out`);
+                abortController.abort(error);
                 const gate = this.sourceCreditGates.get(requestId);
-                if (gate !== undefined)
+                if (gate !== undefined) {
                     gate.abort();
+                    this.sourceCreditGates.delete(requestId);
+                }
+                this.sourceControllers.delete(requestId);
+                this.onResponse.delete(`source-fetch-credit:${requestId}`);
             });
             const clearSourceTimeout = () => this.timerClear(sourceTimerId);
             refreshSourceTimeout();
@@ -112,19 +131,9 @@ export class SourceTrait extends ServiceTrait {
                 const message = this.codec.encode(chunkMsg);
                 await this.publishToTopic(chunkTopic, message, { qos: options.qos ?? 2 });
             };
-            /*  handle credit-based flow control (if credit provided in request)  */
-            const initialCredit = request.credit;
-            const creditGate = (initialCredit !== undefined && initialCredit > 0)
-                ? new CreditGate(initialCredit) : undefined;
-            if (creditGate) {
-                this.sourceCreditGates.set(requestId, creditGate);
-                this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed) => {
-                    creditGate.replenish(creditParsed.credit);
-                    refreshSourceTimeout();
-                });
-            }
             /*  call the handler callback  */
             let ackSent = false;
+            let creditGate;
             try {
                 if (topicName !== request.name)
                     throw new Error(`source name mismatch (topic: "${topicName}", payload: "${request.name}")`);
@@ -132,6 +141,18 @@ export class SourceTrait extends ServiceTrait {
                     info.authenticated = await this.authenticated(request.sender, request.auth, auth);
                 if (info.authenticated !== undefined && !info.authenticated)
                     throw new Error(`source "${name}" failed authentication`);
+                /*  handle credit-based flow control (if credit provided in request)  */
+                const initialCredit = request.credit;
+                creditGate = (initialCredit !== undefined && initialCredit > 0)
+                    ? new CreditGate(initialCredit) : undefined;
+                if (creditGate) {
+                    const gate = creditGate;
+                    this.sourceCreditGates.set(requestId, gate);
+                    this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed) => {
+                        gate.replenish(creditParsed.credit);
+                        refreshSourceTimeout();
+                    });
+                }
                 await callback(...params, info);
                 /*  check for valid data source  */
                 if (!(info.stream instanceof Readable) && !(info.buffer instanceof Promise))
@@ -144,15 +165,17 @@ export class SourceTrait extends ServiceTrait {
                 /*  dispatch according to data type  */
                 if (info.stream instanceof Readable)
                     /*  handle Readable stream result  */
-                    await sendStreamAsChunks(info.stream, this.options.chunkSize, sendChunk, creditGate);
+                    await sendStreamAsChunks(info.stream, this.options.chunkSize, sendChunk, creditGate, abortSignal);
                 else if (info.buffer instanceof Promise)
                     /*  handle Buffer result  */
-                    await sendBufferAsChunks(await info.buffer, this.options.chunkSize, sendChunk, creditGate);
+                    await sendBufferAsChunks(await info.buffer, this.options.chunkSize, sendChunk, creditGate, abortSignal);
             }
             catch (err) {
+                /*  cleanup stream resource (if provided by handler)  */
+                const error = ensureError(err, `handler for source "${name}" failed`);
+                abortController.abort(error);
                 /*  send error as nak response or as error chunk  */
-                const error = ensureError(err);
-                this.error(error, `handler for source "${name}" failed`);
+                this.error(error);
                 if (ackSent)
                     await sendChunk(undefined, error.message, true).catch(() => { });
                 else
@@ -165,6 +188,7 @@ export class SourceTrait extends ServiceTrait {
                     creditGate.abort();
                     this.sourceCreditGates.delete(requestId);
                 }
+                this.sourceControllers.delete(requestId);
                 this.onResponse.delete(`source-fetch-credit:${requestId}`);
             }
         });
@@ -233,11 +257,13 @@ export class SourceTrait extends ServiceTrait {
                     this.publishToTopic(creditTopic, encoded, { qos: options.qos ?? 2 }).catch((err) => {
                         this.error(err, `sending credit for fetch "${name}" failed`);
                     });
+                    refreshTimeout();
                 }
             }
         });
         /*  create promise for collecting stream chunks  */
         const buffer = streamToBuffer(stream);
+        buffer.catch(() => { }); /*  avoid unhandled promise rejection  */
         /*  create promise for meta (resolved on first chunk)  */
         let metaResolve;
         const metaP = new Promise((resolve) => {
@@ -267,13 +293,14 @@ export class SourceTrait extends ServiceTrait {
             }
             if (response.sender)
                 serverId = response.sender;
-            metaResolve(response.meta);
             if (response.error) {
                 stream.destroy(new Error(response.error));
                 spool.unroll();
             }
-            else
+            else {
+                metaResolve(response.meta);
                 refreshTimeout();
+            }
         });
         /*  register chunk dispatch callback  */
         this.onResponse.set(`source-fetch-chunk:${requestId}`, (response) => {

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

@@ -143,15 +143,14 @@ class RefCountedSubscription {
             ...this.unsubbing.keys()
         ]);
         /*  cancel all pending linger timers first (synchronously)  */
-        for (const topic of this.lingers.keys())
-            clearTimeout(this.lingers.get(topic));
+        for (const timer of this.lingers.values())
+            clearTimeout(timer);
         this.lingers.clear();
         this.counts.clear();
         /*  wait for any in-flight subscribe/unsubscribe operations to settle first  */
         await Promise.allSettled([...this.pending.values(), ...this.unsubbing.values()]);
         /*  then unsubscribe from all potentially active topics  */
-        for (const topic of topics)
-            await this.unsubscribeFn(topic).catch(() => { });
+        await Promise.allSettled([...topics].map((topic) => this.unsubscribeFn(topic).catch(() => { })));
         /*  clear remaining internal state  */
         this.pending.clear();
         this.unsubbing.clear();

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

@@ -3,6 +3,6 @@ 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 timerRefresh(id: string, onTimeout: () => void | Promise<void>): void;
     protected timerClear(id: string): void;
 }

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

@@ -22,6 +22,7 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 import { SubscriptionTrait } from "./mqtt-plus-subscription";
+import { ensureError } from "./mqtt-plus-error";
 /*  Timer trait with reusable timer management  */
 export class TimerTrait extends SubscriptionTrait {
     constructor() {
@@ -41,9 +42,14 @@ export class TimerTrait extends SubscriptionTrait {
         const timer = this.timers.get(id);
         if (timer !== undefined)
             clearTimeout(timer);
-        this.timers.set(id, setTimeout(() => {
+        this.timers.set(id, setTimeout(async () => {
             this.timers.delete(id);
-            onTimeout();
+            try {
+                await onTimeout();
+            }
+            catch (err) {
+                this.error(ensureError(err), `timer "${id}" failed`);
+            }
         }, this.options.timeout));
     }
     /*  clear a named timer  */

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

@@ -25,8 +25,8 @@
 import { Buffer } from "node:buffer";
 /*  external requirements  */
 import PLazyAPI from "p-lazy";
-/*  workaround for ESM-only module "plazy" which, when used in the context
-    of MQTT+'s CJS built (e.g. inside test suite), exports via "default"  */
+/*  workaround for ESM-only module "p-lazy" which, when used in the context
+    of MQTT+'s CJS build (e.g. inside test suite), exports via "default"  */
 export const PLazy = (PLazyAPI.default ?? PLazyAPI);
 /*  credit-based flow control gate for chunk producers  */
 export class CreditGate {
@@ -49,7 +49,9 @@ export class CreditGate {
             /*  wait for credit to be replenished  */
             await new Promise((resolve, reject) => {
                 const onAbort = () => {
-                    this.waiters.splice(this.waiters.indexOf(waiter), 1);
+                    const idx = this.waiters.indexOf(waiter);
+                    if (idx !== -1)
+                        this.waiters.splice(idx, 1);
                     reject(abortSignal?.reason ?? new Error("aborted"));
                 };
                 if (abortSignal)