mqtt-plus 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 ChangeLog
 =========
 
+1.2.0 (2026-02-06)
+------------------
+
+- IMPROVEMENT: use Valibot for more robust object validation
+- IMPROVEMENT: support concurrent operations
+- IMPROVEMENT: improve chunk sending
+- IMPROVEMENT: improve buffer handling and decoding
+- IMPROVEMENT: use derived keys to have enough entropy
+- IMPROVEMENT: report failures and log errors on dispatching messages
+- IMPROVEMENT: await subscribes and super calls in dispatching messages
+- IMPROVEMENT: log failing destroy operations
+- BUGFIX: fix share option handling in event()
+- BUGFIX: fix error handling
+- BUGFIX: fix return values of promises
+- CLEANUP: improve type safety (use unknown type, remove Awaited type)
+- CLEANUP: simplify code by using closures and conversions
+- CLEANUP: various code cleanups (rename variables, reduce whitespaces)
+- UPDATE: upgrade NPM dependencies
+
+1.1.4 (2026-02-02)
+------------------
+
+- CLEANUP: various cleanups
+
 1.1.3 (2026-02-02)
 ------------------
 

package/README.md

@@ -238,6 +238,40 @@ The **MQTT+** API provides the following functionalities:
   Call this method when the instance is no longer needed.
   The companion MQTT.js instance has to be destroyed separately.
 
+- **Event Handling**:<br/>
+
+      /*  listen for error or log events  */
+      on(event: "error", callback: (error: Error) => void): void
+      on(event: "log",   callback: (log: LogEvent) => void): void
+
+      /*  remove error or log event listener  */
+      off(event: "error", callback: (error: Error) => void): void
+      off(event: "log",   callback: (log: LogEvent) => void): void
+
+  MQTT+ emits `error` and `log` events for monitoring and debugging.
+
+  - The `on()` method registers an event listener.
+    The `"error"` event is emitted when an error occurs during
+    message processing, subscription, or publishing.
+    The `"log"` event is emitted for informational and debug-level
+    messages with a `LogEvent` object containing `timestamp`, `level`,
+    `msg`, and optional `data` fields.
+
+  - The `off()` method removes a previously registered event listener.
+
+  - The `LogEvent` object provides `resolve()` for resolving lazy
+    promise-based fields and `toString()` for rendering log entries
+    as formatted strings.
+
+  Example:
+
+      mqttp.on("error", (err) => {
+          console.error("MQTT+ error:", err.message)
+      })
+      mqttp.on("log", (log) => {
+          console.log(log.toString())
+      })
+
 - **Authentication**:<br/>
 
       /*  store server-side secret credential  */
@@ -282,8 +316,11 @@ The **MQTT+** API provides the following functionalities:
       /*  set meta information by key  */
       meta(key: string, value: any): void
 
+      /*  retrieve meta information by key  */
+      meta(key: string): any
+
       /*  delete meta information by key  */
-      meta(key: string): void
+      meta(key: string, value: null): void
 
   MQTT+ allows attaching persistent meta-data to an instance that is
   automatically included in all outgoing messages. This is useful for
@@ -291,8 +328,9 @@ The **MQTT+** API provides the following functionalities:
   identity to every request.
 
   - The `meta()` method manages instance-level meta-data:
-    called with a key only, deletes the meta-data entry for that key;
-    called with a key and value, sets the meta-data entry.
+    called with a key only, retrieves the meta-data entry for that key;
+    called with a key and non-null value, sets the meta-data entry;
+    called with a key and `null`, deletes the meta-data entry.
 
   - Instance-level meta-data set via `meta()` is merged with any per-request
     `meta` option passed to `emit()`, `call()`, `push()`, or `fetch()`.
@@ -309,8 +347,11 @@ The **MQTT+** API provides the following functionalities:
       mqttp.meta("clientVersion", "1.0.0")
       mqttp.meta("environment", "production")
 
+      /*  client: retrieve a metadata entry  */
+      const environment = mqttp.meta("environment")
+
       /*  client: delete a metadata entry  */
-      mqttp.meta("environment")
+      mqttp.meta("environment", null)
 
       /*  client: per-request metadata (merged with instance-level)  */
       mqttp.call({ name: "example/hello", params: [ "world" ], meta: { requestId: "123" } })
@@ -590,14 +631,14 @@ The **MQTT+** API provides the following functionalities:
           event:     string,
           params:    any[],
           receiver?: string,
-          options?:  MQTT::IClientSubscribeOptions,
+          options?:  MQTT::IClientPublishOptions,
           meta?:     Record<string, any>
       }): void
       emit({
           event:     string,
           params:    any[],
           receiver?: string,
-          options?:  MQTT::IClientSubscribeOptions,
+          options?:  MQTT::IClientPublishOptions,
           meta?:     Record<string, any>,
           dry:       true
       }): { topic: string, payload: string | Uint8Array, options: IClientPublishOptions }
@@ -695,7 +736,7 @@ The **MQTT+** API provides the following functionalities:
           name:      string,
           params:    any[],
           receiver?: string,
-          options?:  MQTT::IClientSubscribeOptions,
+          options?:  MQTT::IClientPublishOptions,
           meta?:     Record<string, any>
       }): Promise<{
           stream:    Readable,
@@ -974,7 +1015,7 @@ pattern read      example/client/+/sink-push-request/%c
 pattern write     example/client/+/sink-push-response/%c
 pattern read      example/client/+/sink-push-chunk/%c
 
-#   ==== server/autenticated ACL ====
+#   ==== server/authenticated ACL ====
 
 user    example
 

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

@@ -6,7 +6,7 @@ export type AuthOption = AuthRole | {
     mode: AuthMode;
     roles: AuthRole[];
 };
-export type TokenPayload = {
+type TokenPayload = {
     roles: AuthRole[];
     id?: string;
 };
@@ -21,3 +21,4 @@ export declare class AuthTrait<T extends APISchema = APISchema> extends MetaTrai
     private validateToken;
     protected authenticated(clientId: string | undefined, tokens: string[] | undefined, option: AuthOption): Promise<boolean>;
 }
+export {};

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

@@ -24,6 +24,8 @@
 /*  external requirements  */
 import { SignJWT } from "jose/jwt/sign";
 import { jwtVerify } from "jose/jwt/verify";
+import * as pbkdf2 from "@stablelib/pbkdf2";
+import * as sha256 from "@stablelib/sha256";
 import { MetaTrait } from "./mqtt-plus-meta";
 /*  authentication trait  */
 export class AuthTrait extends MetaTrait {
@@ -35,7 +37,13 @@ export class AuthTrait extends MetaTrait {
     }
     /*  store server-side secret credential  */
     credential(credential) {
-        this._credential = credential;
+        /*  sanity check argument  */
+        if (credential.length === 0)
+            throw new Error("credential must not be empty");
+        /*  use a derived key with minimum length of 32 for JWT HS256  */
+        const pw = new TextEncoder().encode(credential);
+        const st = new TextEncoder().encode("mqtt-plus");
+        this._credential = pbkdf2.deriveKey(sha256.SHA256, pw, st, 100000, 32);
     }
     /*  issue client-side token on server-side  */
     async issue(payload) {
@@ -43,8 +51,7 @@ export class AuthTrait extends MetaTrait {
             throw new Error("credential has to be provided before issuing tokens");
         const jwt = new SignJWT(payload);
         jwt.setProtectedHeader({ alg: "HS256", typ: "JWT" });
-        const key = new TextEncoder().encode(this._credential);
-        const token = await jwt.sign(key);
+        const token = await jwt.sign(this._credential);
         return token;
     }
     authenticate(token, remove) {
@@ -59,8 +66,7 @@ export class AuthTrait extends MetaTrait {
     async validateToken(token) {
         if (this._credential === null)
             throw new Error("credential has to be provided before validating tokens");
-        const key = new TextEncoder().encode(this._credential);
-        const result = await jwtVerify(token, key).catch(() => null);
+        const result = await jwtVerify(token, this._credential).catch(() => null);
         return result?.payload ?? null;
     }
     /*  check whether request is authenticated  */
@@ -77,9 +83,11 @@ export class AuthTrait extends MetaTrait {
             mode = option.mode;
             roles = option.roles;
         }
-        /*  iterate over all roles and try to authenticate token (first-match)  */
+        /*  iterate over all roles and try to authenticate token (first-match, max 8)  */
         if (tokens !== undefined) {
-            for (const token of tokens) {
+            for (const token of tokens.slice(0, 8)) {
+                if (token.length > 8192)
+                    continue;
                 const payload = await this.validateToken(token);
                 if (payload === null)
                     continue;

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

@@ -154,7 +154,9 @@ export class BaseTrait extends TraceTrait {
         }
         this.log("debug", `received from MQTT topic "${topic}"`, { message: parsed });
         /*  dispatch to trait handlers  */
-        this._dispatchMessage(topic, parsed).catch(() => { });
+        this._dispatchMessage(topic, parsed).catch((err) => {
+            this.error(err, `dispatching message from MQTT topic "${topic}" failed`);
+        });
     }
     /*  dispatch parsed message to appropriate handler
         (base implementation, to be overridden in sub-traits)  */

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

@@ -3,10 +3,10 @@ import { APIOptions, OptionsTrait } from "./mqtt-plus-options";
 export declare class JSONX {
     private static uint8ArrayToBase64;
     private static base64ToUint8Array;
-    static stringify(obj: any): string;
-    static parse(json: string): any;
+    static stringify(obj: unknown): string;
+    static parse(json: string): unknown;
 }
-export default class Codec {
+declare class Codec {
     private type;
     private types;
     private tags;
@@ -18,3 +18,4 @@ export declare class CodecTrait<T extends APISchema = APISchema> extends Options
     protected codec: Codec;
     constructor(options?: Partial<APIOptions>);
 }
+export {};

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

@@ -22,19 +22,16 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 /*  external requirements  */
+import { Buffer } from "node:buffer";
 import * as CBOR from "cbor2";
 import { OptionsTrait } from "./mqtt-plus-options";
 /*  JSON encode/decode with Uint8Array support  */
 export class JSONX {
     static uint8ArrayToBase64(arr) {
-        return btoa(String.fromCharCode(...arr));
+        return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength).toString("base64");
     }
     static base64ToUint8Array(base64) {
-        const binary = atob(base64);
-        const arr = new Uint8Array(binary.length);
-        for (let i = 0; i < binary.length; i++)
-            arr[i] = binary.charCodeAt(i);
-        return arr;
+        return new Uint8Array(Buffer.from(base64, "base64"));
     }
     static stringify(obj) {
         return JSON.stringify(obj, (_, value) => value instanceof Uint8Array
@@ -48,7 +45,7 @@ export class JSONX {
     }
 }
 /*  the encoder/decoder abstraction  */
-export default class Codec {
+class Codec {
     constructor(type) {
         this.type = type;
         this.types = new CBOR.TypeEncoderMap();
@@ -68,42 +65,46 @@ export default class Codec {
             try {
                 result = CBOR.encode(data, { types: this.types });
             }
-            catch (_ex) {
-                throw new Error("failed to encode CBOR format");
+            catch (ex) {
+                throw new Error("failed to encode CBOR format", { cause: ex });
             }
         }
         else if (this.type === "json") {
             try {
                 result = JSONX.stringify(data);
             }
-            catch (_ex) {
-                throw new Error("failed to encode JSON format");
+            catch (ex) {
+                throw new Error("failed to encode JSON format", { cause: ex });
             }
         }
         else
-            throw new Error("invalid format");
+            throw new Error(`invalid format "${this.type}"`);
         return result;
     }
     decode(data) {
         let result;
-        if (this.type === "cbor" && data instanceof Uint8Array) {
+        if (this.type === "cbor") {
+            if (!(data instanceof Uint8Array))
+                throw new Error("failed to decode CBOR format (data type is not Uint8Array)");
             try {
                 result = CBOR.decode(data, { tags: this.tags });
             }
-            catch (_ex) {
-                throw new Error("failed to decode CBOR format");
+            catch (ex) {
+                throw new Error("failed to decode CBOR format", { cause: ex });
             }
         }
-        else if (this.type === "json" && typeof data === "string") {
+        else if (this.type === "json") {
+            if (typeof data !== "string")
+                throw new Error("failed to decode JSON format (data type is not string)");
             try {
                 result = JSONX.parse(data);
             }
-            catch (_ex) {
-                throw new Error("failed to decode JSON format");
+            catch (ex) {
+                throw new Error("failed to decode JSON format", { cause: ex });
             }
         }
         else
-            throw new Error("invalid format or wrong data type");
+            throw new Error(`invalid format "${this.type}"`);
         return result;
     }
 }

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

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import { APISchema } from "./mqtt-plus-api";
 import { CodecTrait } from "./mqtt-plus-codec";
 export declare class EncodeTrait<T extends APISchema = APISchema> extends CodecTrait<T> {

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

@@ -21,6 +21,8 @@
 **  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
+/*  built-in requirements  */
+import { Buffer } from "node:buffer";
 import { CodecTrait } from "./mqtt-plus-codec";
 /*  encoding trait  */
 export class EncodeTrait extends CodecTrait {
@@ -43,7 +45,7 @@ export class EncodeTrait extends CodecTrait {
     }
     buf2arr(data, cons) {
         let arr;
-        if (cons === Buffer)
+        if (typeof Buffer !== "undefined" && cons === Buffer)
             arr = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
         else if (cons === Uint8Array)
             arr = data;

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

@@ -44,6 +44,7 @@ export class EventTrait extends AuthTrait {
             name = nameOrConfig.name;
             callback = nameOrConfig.callback;
             options = nameOrConfig.options ?? {};
+            share = nameOrConfig.share;
             auth = nameOrConfig.auth;
         }
         else {
@@ -73,16 +74,17 @@ export class EventTrait extends AuthTrait {
             auth
         });
         /*  provide a registration for subsequent destruction  */
-        const self = this;
         const registration = {
-            async destroy() {
-                if (!self.events.has(name))
+            destroy: async () => {
+                if (!this.events.has(name))
                     throw new Error(`destroy: event "${name}" not registered`);
-                self.events.delete(name);
+                this.events.delete(name);
                 return Promise.all([
-                    self._unsubscribeTopic(topicB),
-                    self._unsubscribeTopic(topicD)
-                ]).then(() => { });
+                    this._unsubscribeTopic(topicB),
+                    this._unsubscribeTopic(topicD)
+                ]).then(() => { }).catch((err) => {
+                    this.error(err, `destroy: failed to unsubscribe from topics for event "${name}"`);
+                });
             }
         };
         return registration;
@@ -110,11 +112,11 @@ export class EventTrait extends AuthTrait {
             params = args;
         }
         /*  generate unique request id  */
-        const rid = nanoid();
+        const requestId = nanoid();
         /*  generate encoded message  */
         const auth = this.authenticate();
         const metaStore = this.metaStore(meta);
-        const request = this.msg.makeEventEmission(rid, event, params, this.options.id, receiver, auth, metaStore);
+        const request = this.msg.makeEventEmission(requestId, event, 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);
@@ -124,17 +126,21 @@ export class EventTrait extends AuthTrait {
             return { topic, payload: message, options: { qos: 0, ...options } };
         else
             /*  publish message to MQTT topic  */
-            this._publishToTopic(topic, message, { qos: 0, ...options }).catch(() => { });
+            this._publishToTopic(topic, message, { qos: 0, ...options }).catch((err) => {
+                this.error(err, `emitting event "${event}" failed`);
+            });
     }
     /*  dispatch message (Event pattern handling)  */
     async _dispatchMessage(topic, parsed) {
-        super._dispatchMessage(topic, parsed);
+        await super._dispatchMessage(topic, parsed);
         const topicMatch = this.options.topicMatch(topic);
         if (topicMatch !== null
             && topicMatch.operation === "event-emission"
             && parsed instanceof EventEmission) {
             /*  just deliver event  */
             const name = parsed.name;
+            if (topicMatch.name !== name)
+                throw new Error(`event name mismatch between topic "${topicMatch.name}" and payload "${name}"`);
             const handler = this.events.get(name);
             const params = parsed.params ?? [];
             const info = { sender: parsed.sender ?? "" };
@@ -142,16 +148,17 @@ export class EventTrait extends AuthTrait {
                 info.receiver = parsed.receiver;
             if (parsed.meta)
                 info.meta = parsed.meta;
-            if (handler?.auth)
+            if (handler === undefined)
+                throw new Error(`handler for event "${name}" not found`);
+            if (handler.auth)
                 info.authenticated = await this.authenticated(parsed.sender, parsed.auth, handler.auth);
-            if (info.authenticated !== undefined && !info.authenticated)
-                this.error(new Error(`authentication on event "${name}" failed`));
-            else
-                Promise.resolve()
-                    .then(() => handler?.callback?.(...params, info))
-                    .catch((err) => {
-                    this.error(err);
-                });
+            Promise.resolve().then(() => {
+                if (info.authenticated !== undefined && !info.authenticated)
+                    throw new Error(`authentication on event "${name}" failed`);
+                return handler.callback(...params, info);
+            }).catch((err) => {
+                this.error(err, `handler for event "${name}" failed`);
+            });
         }
     }
 }

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

@@ -3,7 +3,7 @@ import { BaseTrait } from "./mqtt-plus-base";
 export declare class MetaTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
     private _meta;
     meta(): Record<string, any>;
-    meta(key: string): void;
+    meta(key: string): any;
     meta(key: string, value: any): void;
     protected metaStore(extra?: Record<string, any>): Record<string, any> | undefined;
 }

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

@@ -32,6 +32,8 @@ export class MetaTrait extends BaseTrait {
     meta(key, value) {
         if (key === undefined)
             return Object.fromEntries(this._meta);
+        else if (arguments.length === 1)
+            return this._meta.get(key);
         else if (value === undefined || value === null)
             this._meta.delete(key);
         else