mqtt-plus 0.9.2 → 0.9.4

package/README.md

@@ -22,7 +22,7 @@ $ npm install mqtt mqtt-plus
 About
 -----
 
-This is **MQTT+**, an addon API for the excellent
+This is **MQTT+**, an companion addon API for the excellent
 [MQTT](http://mqtt.org/) client TypeScript/JavaScript API
 [MQTT.js](https://www.npmjs.com/package/mqtt), provoding additional
 communication patterns with optional type safety:
@@ -40,6 +40,20 @@ communication patterns with optional type safety:
   pattern allows to direct the event to particular subscribers and
   provides optional information about the sender to subscribers.
 
+- **Stream Transfer**:
+
+  Stream Transfer is a *uni-directional* communication pattern.
+  A stream is the combination of a stream name, a `Readable` stream object and optionally zero or more arguments.
+  You *attach* to a stream.
+  When a stream is *transferred*, either a single particular attacher (in case of
+  a directed stream transfer) or all attachers are called and receive the
+  arguments as extra information. The `Readable` stream is available via
+  `info.stream` in the attacher callback.
+
+  In contrast to the regular MQTT message publish/subscribe, this
+  pattern allows to transfer arbitrary amounts of arbitrary data by
+  chunking the data via a stream.
+
 - **Service Call**:
 
   Service Call is a *bi-directional* communication pattern.
@@ -55,26 +69,48 @@ communication patterns with optional type safety:
   Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call)
   (RPC) style communication.
 
+- **Resource Transfer**:
+
+  Resource Transfer is a *bi-directional* communication pattern.
+  A Resource is the combination of a resource name and optionally zero or more arguments.
+  You *provision* for a resource transfer.
+  When a resource is *fetched* or *pushed*, a single particular provisioner (in case
+  of a directed resource transfer) or one arbitrary provisioner is called and
+  sends or receives the resource and its arguments.
+
 > [!Note]
 > **MQTT+** is similar to and derived from
 > [MQTT-JSON-RPC](https://github.com/rse/mqtt-json-rpc) of the same
 > author, but instead of just JSON, MQTT+ encodes packets as JSON
 > or CBOR (default), uses an own packet format (allowing sender and
-> receiver information) and uses shorter NanoIDs instead of longer UUIDs
-> for identification of sender, receiver and requests.
+> receiver information), uses shorter NanoIDs instead of longer UUIDs
+> for identification of sender, receiver and requests, and has
+> no support for stream transfers.
 
 Usage
 -----
 
 ### API:
 
+The API type defines the available endpoints. Use the marker types
+`Event<T>`, `Stream<T>`, and `Service<T>` to declare the communication
+pattern of each endpoint:
+
 ```ts
+import type * as MQTTpt from "mqtt-plus"
+
 export type API = {
-    "example/sample": (a1: string, a2: boolean) => void
-    "example/hello":  (a1: string, a2: number)  => string
+    "example/sample": MQTTpt.Event<(a1: string, a2: boolean) => void>    /*  event   */
+    "example/upload": MQTTpt.Stream<(a1: string, a2: number) => void>    /*  stream  */
+    "example/hello":  MQTTpt.Service<(a1: string, a2: number) => string> /*  service */
 }
 ```
 
+The marker types ensure that `subscribe()` and `emit()` only accept
+`Event<T>` endpoints, `attach()` and `transfer()` only accept
+`Stream<T>` endpoints, and `register()` and `call()` only accept
+`Service<T>` endpoints.
+
 ### Server:
 
 ```ts
@@ -125,15 +161,12 @@ The **MQTT+** API provides the following methods:
       constructor<API>(
           mqtt: MqttClient,
           options?: {
-              id:                        string
-              codec:                     "cbor" | "json"
-              timeout:                   number
-              topicEventNoticeMake:      (topic: string) => TopicMatching | null
-              topicServiceRequestMake:   (topic: string) => TopicMatching | null
-              topicServiceResponseMake:  (topic: string) => TopicMatching | null
-              topicEventNoticeMatch:     { name: string, clientId?: string }
-              topicServiceRequestMatch:  { name: string, clientId?: string }
-              topicServiceResponseMatch: { name: string, clientId?: string }
+              id:         string
+              codec:      "cbor" | "json"
+              timeout:    number
+              chunkSize:  number
+              topicMake:  (name: string, operation: string, peerId?: string) => string
+              topicMatch: (topic: string) => { name: string, operation: string, peerId?: string } | null
           }
       )
 
@@ -149,18 +182,13 @@ The **MQTT+** API provides the following methods:
   - `id`: Custom MQTT peer identifier (default: auto-generated NanoID).
   - `codec`: Encoding format (default: `cbor`).
   - `timeout`: Communication timeout in milliseconds (default: `10000`).
-  - `topicEventNoticeMake`: Custom topic generation for event notices.
-    (default: `` (name, clientId) => clientId ? `${name}/event-notice/${clientId}` : `${name}/event-notice` ``)
-  - `topicServiceRequestMake`: Custom topic generation for service requests.
-    (default: `` (name, clientId) => clientId ? `${name}/service-request/${clientId}` : `${name}/service-request` ``)
-  - `topicServiceResponseMake`): Custom topic generation for service responses.
-    (default: `` (name, clientId) => clientId ? `${name}/service-response/${clientId}` : `${name}/service-response` ``)
-  - `topicEventNoticeMatch`: Custom topic matching for event notices.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/event-notice(?:\/(.+))?$/); return m ? { name: m[1], clientId: m[2] } : null } ``)
-  - `topicServiceRequestMatch`: Custom topic matching for service requests.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/service-request(?:\/(.+))?$/); return m ? { name: m[1], clientId: m[2] } : null } ``)
-  - `topicServiceResponseMatch`: Custom topic matching for service responses.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/service-response\/(.+)$/); return m ? { name: m[1], clientId: m[2] } : null } ``)
+  - `chunkSize`: Chunk size in bytes for stream transfers (default: `16384`).
+  - `topicMake`: Custom topic generation function.
+    The `operation` parameter is one of: `event-notice`, `stream-chunk`, `service-call`, `resource-transfer`.
+    (default: `` (name, operation, peerId) => `${name}/${operation}` + (peerId ? `/${peerId}` : "/any") ``)
+  - `topicMatch`: Custom topic matching function.
+    Returns `{ name, operation, peerId? }` or `null` if no match. The `peerId` is `undefined` for broadcast topics (ending with `/any`).
+    (default: `` (topic) => { const m = topic.match(/^(.+)\/([^/]+)\/([^/]+)$/); return m ? { name: m[1], operation: m[2], peerId: m[3] === "any" ? undefined : m[3] } : null } ``)
 
 - **Event Subscription**:<br/>
 
@@ -168,7 +196,10 @@ The **MQTT+** API provides the following methods:
       subscribe(
           event:    string,
           options?: MQTT::IClientSubscribeOptions
-          callback: (...params: any[], info: { sender: string, receiver?: string }) => void
+          callback: (
+              ...params: any[],
+              info: { sender: string, receiver?: string }
+          ) => void
       ): Promise<Subscription>
 
   Subscribe to an event.
@@ -178,17 +209,44 @@ The **MQTT+** API provides the following methods:
   There is no return value of `callback`.
 
   Internally, on the MQTT broker, the topics generated by
-  `topicEventNoticeMake()` (default: `${event}/event-notice` and
-  `${event}/event-notice/${clientId}`) are subscribed. Returns a
+  `topicMake(event, "event-notice")` (default: `${event}/event-notice/any` and
+  `${event}/event-notice/${peerId}`) are subscribed. Returns a
   `Subscription` object with an `unsubscribe()` method.
 
+- **Stream Attachment**:<br/>
+
+      /*  (simplified TypeScript API method signature)  */
+      attach(
+          stream:   string,
+          options?: MQTT::IClientSubscribeOptions
+          callback: (
+              ...params: any[],
+              info: { sender: string, receiver?: string, stream: stream.Readable }
+          ) => void
+      ): Promise<Attachment>
+
+  Attach to (observe) a stream.
+  The `stream` has to be a valid MQTT topic name.
+  The optional `options` allows setting MQTT.js `subscribe()` options like `qos`.
+  The `callback` is called with the `params` passed to a remote `transfer()`.
+  The `info.stream` provides a Node.js `Readable` stream for consuming the transferred data.
+  There is no return value of `callback`.
+
+  Internally, on the MQTT broker, the topics generated by
+  `topicMake(stream, "stream-chunk")` (default: `${stream}/stream-chunk/any` and
+  `${stream}/stream-chunk/${peerId}`) are subscribed. Returns an
+  `Attachment` object with an `unattach()` method.
+
 - **Service Registration**:<br/>
 
       /*  (simplified TypeScript API method signature)  */
       register(
           service:  string,
           options?: MQTT::IClientSubscribeOptions
-          callback: (...params: any[], info: { sender: string, receiver?: string }) => any
+          callback: (
+              ...params: any[],
+              info: { sender: string, receiver?: string }
+          ) => any
       ): Promise<Registration>
 
   Register a service.
@@ -198,10 +256,33 @@ The **MQTT+** API provides the following methods:
   The return value of `callback` will resolve the `Promise` returned by the remote `call()`.
 
   Internally, on the MQTT broker, the topics by
-  `topicServiceRequestMake()` (default: `${service}/service-request` and
-  `${service}/service-request/${clientId}`) are subscribed. Returns a
+  `topicMake(service, "service-call")` (default: `${service}/service-call/any` and
+  `${service}/service-call/${peerId}`) are subscribed. Returns a
   `Registration` object with an `unregister()` method.
 
+- **Resource Provisioning**:<br/>
+
+      /*  (simplified TypeScript API method signature)  */
+      provision(
+          resource: string,
+          options?: MQTT::IClientSubscribeOptions
+          callback: (
+              ...params: any[],
+              info: { sender: string, receiver?: string }
+          ) => any
+      ): Promise<Provisioning>
+
+  Provision a resource.
+  The `resource` has to be a valid MQTT topic name.
+  The optional `options` allows setting MQTT.js `subscribe()` options like `qos`.
+  The `callback` is called with the `params` passed to a remote `call()`.
+  The return value of `callback` will resolve the `Promise` returned by the remote `fetch()` call.
+
+  Internally, on the MQTT broker, the topics by
+  `topicMake(resource, "resource-transfer")` (default: `${resource}/resource-transfer/any` and
+  `${resource}/resource-transfer/${peerId}`) are subscribed. Returns a
+  `Provisioning` object with an `unprovision()` method.
+
 - **Event Emission**:<br/>
 
       /*  (simplified TypeScript API method signature)  */
@@ -219,8 +300,35 @@ The **MQTT+** API provides the following methods:
   The remote `subscribe()` `callback` is called with `params` and its
   return value is silently ignored.
 
-  Internally, publishes to the MQTT topic by `topicEventNoticeMake(event, clientId)`
-  (default: `${event}/event-notice` or `${event}/event-notice/${clientId}`).
+  Internally, publishes to the MQTT topic by `topicMake(event, "event-notice", peerId)`
+  (default: `${event}/event-notice/any` or `${event}/event-notice/${peerId}`).
+
+- **Stream Transfer**:<br/>
+
+      /*  (simplified TypeScript API method signature)  */
+      transfer(
+          stream:    string,
+          readable:  stream.Readable,
+          receiver?: Receiver,
+          options?:  MQTT::IClientPublishOptions,
+          ...params: any[]
+      ): Promise<void>
+
+  Transfer a stream to all attachers or a specific attacher.
+  The `readable` is a Node.js `Readable` stream providing the data to transfer.
+  The optional `receiver` directs the transfer to a specific attacher only.
+  The optional `options` allows setting MQTT.js `publish()` options like `qos` or `retain`.
+
+  The data is read from `readable` in chunks (default: 16KB,
+  configurable via `chunkSize` option) and sent over MQTT until the
+  stream is closed. The returned `Promise` resolves when the entire
+  stream has been transferred.
+
+  The remote `attach()` `callback` is called with `params` and an `info` object
+  containing a `stream.Readable` for consuming the transferred data.
+
+  Internally, publishes to the MQTT topic by `topicMake(stream, "stream-chunk", peerId)`
+  (default: `${stream}/stream-chunk/any` or `${stream}/stream-chunk/${peerId}`).
 
 - **Service Call**:<br/>
 
@@ -240,8 +348,31 @@ The **MQTT+** API provides the following methods:
   return value resolves the returned `Promise`. If the remote `callback`
   throws an exception, this rejects the returned `Promise`.
 
-  Internally, on the MQTT broker, the topic by `topicServiceResponseMake(service, clientId)`
-  (default: `${service}/service-response/${clientId}`) is temporarily subscribed
+  Internally, on the MQTT broker, the topic by `topicMake(service, "service-call", peerId)`
+  (default: `${service}/service-call/${peerId}`) is temporarily subscribed
+  for receiving the response.
+
+- **Resource Transfer**:<br/>
+
+      /*  (simplified TypeScript API method signature)  */
+      fetch(
+          blob:      string,
+          receiver?: Receiver,
+          options?:  MQTT::IClientSubscribeOptions,
+          ...params: any[]
+      ): Promise<Buffer>
+
+  Fetches a resource from any resource provisioner or from a specific provisioner.
+  The optional `receiver` directs the call to a specific provisioner only.
+  The optional `options` allows setting MQTT.js `publish()` options like `qos` or `retain`.
+
+  The remote `provision()` `callback` is called with `params` and its
+  return value resolves the returned `Promise`. If the remote `callback`
+  throws an exception, this rejects the returned `Promise`.
+
+  Internally, on the MQTT broker, the topic by
+  `topicMake(resource, "resource-transfer", peerId)` (default:
+  `${resource}/resource-transfer/${peerId}`) is temporarily subscribed
   for receiving the response.
 
 - **Receiver Wrapping**:<br/>
@@ -276,7 +407,7 @@ mqttp.call("example/hello", "world", 42).then((result) => {
 ```
 
 ...the following message is sent to the permanent MQTT topic
-`example/hello/service-request` (the shown NanoIDs are just pseudo
+`example/hello/service-call/any` (the shown NanoIDs are just pseudo
 ones):
 
 ```json
@@ -299,7 +430,7 @@ mqttp.register("example/hello", (a1, a2) => {
 ...and then its result, in the above `mqttp.call()` example `"world:42"`, is then
 sent back as the following success response
 message to the temporary (client-specific) MQTT topic
-`example/hello/service-response/2IBMSk0NPnrz1AeTERoea`:
+`example/hello/service-call/2IBMSk0NPnrz1AeTERoea`:
 
 ```json
 {
@@ -382,9 +513,10 @@ it in action and tracing its communication (the typing of the `MQTTp`
 class with `API` is optional, but strongly suggested):
 
 ```ts
-import Mosquitto from "mosquitto"
-import MQTT      from "mqtt"
-import MQTTp     from "mqtt-plus"
+import Mosquitto        from "mosquitto"
+import MQTT             from "mqtt"
+import MQTTp            from "mqtt-plus"
+import type * as MQTTpt from "mqtt-plus"
 
 const mosquitto = new Mosquitto()
 await mosquitto.start()
@@ -396,8 +528,8 @@ const mqtt = MQTT.connect("mqtt://127.0.0.1:1883", {
 })
 
 type API = {
-    "example/sample": (a1: string, a2: number) => void
-    "example/hello":  (a1: string, a2: number) => string
+    "example/sample": MQTTpt.Event<(a1: string, a2: number) => void>
+    "example/hello":  MQTTpt.Service<(a1: string, a2: number) => string>
 }
 
 const mqttp = new MQTTp<API>(mqtt, { codec: "json" })
@@ -431,9 +563,9 @@ The output will be:
 ```
 $ node sample.ts
 CONNECT
-RECEIVED example/hello/service-request {"id":"vwLzfQDu2uEeOdOfIlT42","sender":"2IBMSk0NPnrz1AeTERoea","service":"example/hello","params":["world",42]}
+RECEIVED example/hello/service-call/any {"id":"vwLzfQDu2uEeOdOfIlT42","sender":"2IBMSk0NPnrz1AeTERoea","service":"example/hello","params":["world",42]}
 example/hello: request:  world 42 undefined
-RECEIVED example/hello/service-response/2IBMSk0NPnrz1AeTERoea {"id":"vwLzfQDu2uEeOdOfIlT42","sender":"2IBMSk0NPnrz1AeTERoea","receiver":"2IBMSk0NPnrz1AeTERoea","result":"world:42"}
+RECEIVED example/hello/service-call/2IBMSk0NPnrz1AeTERoea {"id":"vwLzfQDu2uEeOdOfIlT42","sender":"2IBMSk0NPnrz1AeTERoea","receiver":"2IBMSk0NPnrz1AeTERoea","result":"world:42"}
 example/hello success:  world:42
 CLOSE
 ```

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

@@ -0,0 +1,26 @@
+type Brand<T> = T & {
+    readonly __brand: unique symbol;
+};
+export type APIEndpoint = APIEndpointEvent | APIEndpointStream | APIEndpointService | APIEndpointResource;
+export type APIEndpointEvent = (...args: any[]) => void;
+export type APIEndpointStream = (...args: any[]) => any;
+export type APIEndpointService = (...args: any[]) => any;
+export type APIEndpointResource = (...args: any[]) => Promise<Buffer>;
+export type Event<T extends APIEndpointEvent> = Brand<T>;
+export type Stream<T extends APIEndpointStream> = Brand<T>;
+export type Service<T extends APIEndpointService> = Brand<T>;
+export type Resource<T extends APIEndpointResource> = Brand<T>;
+export type APISchema = Record<string, APIEndpoint>;
+export type EventKeys<T> = string extends keyof T ? string : {
+    [K in keyof T]: T[K] extends Event<infer _F> ? K : never;
+}[keyof T];
+export type StreamKeys<T> = string extends keyof T ? string : {
+    [K in keyof T]: T[K] extends Stream<infer _F> ? K : never;
+}[keyof T];
+export type ServiceKeys<T> = string extends keyof T ? string : {
+    [K in keyof T]: T[K] extends Service<infer _F> ? K : never;
+}[keyof T];
+export type ResourceKeys<T> = string extends keyof T ? string : {
+    [K in keyof T]: T[K] extends Resource<infer _F> ? K : never;
+}[keyof T];
+export {};

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

@@ -0,0 +1,24 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+export {};

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

@@ -0,0 +1,19 @@
+import { MqttClient, IClientPublishOptions, IClientSubscribeOptions } from "mqtt";
+import { APISchema } from "./mqtt-plus-api";
+import { APIOptions } from "./mqtt-plus-options";
+import { ReceiverTrait } from "./mqtt-plus-receiver";
+export declare class BaseTrait<T extends APISchema = APISchema> extends ReceiverTrait<T> {
+    protected mqtt: MqttClient;
+    constructor(mqtt: MqttClient, options?: Partial<APIOptions>);
+    destroy(): void;
+    protected _subscribeTopic(topic: string, options?: Partial<IClientSubscribeOptions>): Promise<void>;
+    protected _unsubscribeTopic(topic: string): Promise<void>;
+    private _isIClientPublishOptions;
+    protected _parseCallArgs<U extends any[]>(args: any[]): {
+        receiver?: string;
+        options: IClientPublishOptions;
+        params: U;
+    };
+    private _onMessage;
+    protected _dispatchMessage(_topic: string, _parsed: any): void;
+}

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

@@ -0,0 +1,114 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+import { ReceiverTrait } from "./mqtt-plus-receiver";
+/*  MQTTp Base class with shared infrastructure  */
+export class BaseTrait extends ReceiverTrait {
+    /*  construct API class  */
+    constructor(mqtt, options = {}) {
+        super(options);
+        /*  store MQTT client  */
+        this.mqtt = mqtt;
+        /*  hook into the MQTT message processing  */
+        this.mqtt.on("message", (topic, message, packet) => {
+            this._onMessage(topic, message, packet);
+        });
+    }
+    /*  destroy API class  */
+    destroy() {
+        this.mqtt.removeAllListeners();
+    }
+    /*  subscribe to an MQTT topic (Promise-based)  */
+    async _subscribeTopic(topic, options = {}) {
+        return new Promise((resolve, reject) => {
+            this.mqtt.subscribe(topic, { qos: 2, ...options }, (err, _granted) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    /*  unsubscribe from an MQTT topic (Promise-based)  */
+    async _unsubscribeTopic(topic) {
+        return new Promise((resolve, reject) => {
+            this.mqtt.unsubscribe(topic, (err, _packet) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    /*  check whether argument has structure of interface IClientPublishOptions  */
+    _isIClientPublishOptions(arg) {
+        if (typeof arg !== "object")
+            return false;
+        const keys = ["qos", "retain", "dup", "properties", "cbStorePut"];
+        return Object.keys(arg).every((key) => keys.includes(key));
+    }
+    /*  parse optional peerId and options from variadic arguments  */
+    _parseCallArgs(args) {
+        let receiver;
+        let options = {};
+        let params = args;
+        if (args.length >= 2 && this._isReceiver(args[0]) && this._isIClientPublishOptions(args[1])) {
+            receiver = this._getReceiver(args[0]);
+            options = args[1];
+            params = args.slice(2);
+        }
+        else if (args.length >= 1 && this._isReceiver(args[0])) {
+            receiver = this._getReceiver(args[0]);
+            params = args.slice(1);
+        }
+        else if (args.length >= 1 && this._isIClientPublishOptions(args[0])) {
+            options = args[0];
+            params = args.slice(1);
+        }
+        return { receiver, options, params };
+    }
+    /*  handle incoming MQTT message  */
+    _onMessage(topic, message, packet) {
+        /*  try to parse payload as payload  */
+        let parsed;
+        try {
+            let input = message;
+            if (this.options.codec === "json")
+                input = message.toString();
+            const payload = this.codec.decode(input);
+            parsed = this.msg.parse(payload);
+        }
+        catch (_err) {
+            const err = _err instanceof Error
+                ? new Error(`failed to parse message: ${_err.message}`)
+                : new Error("failed to parse message");
+            this.mqtt.emit("error", err);
+            return;
+        }
+        /*  dispatch to trait handlers  */
+        this._dispatchMessage(topic, parsed);
+    }
+    /*  dispatch parsed message to appropriate handler
+        (base implementation, to be overridden in super-traits)  */
+    _dispatchMessage(_topic, _parsed) { }
+}

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

@@ -1,6 +1,12 @@
+import { APISchema } from "./mqtt-plus-api";
+import { APIOptions, OptionsTrait } from "./mqtt-plus-options";
 export default class Codec {
     private type;
     constructor(type: "cbor" | "json");
     encode(data: unknown): Buffer | string;
     decode(data: Buffer | string): unknown;
 }
+export declare class CodecTrait<T extends APISchema = APISchema> extends OptionsTrait<T> {
+    protected codec: Codec;
+    constructor(options?: Partial<APIOptions>);
+}

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

@@ -21,7 +21,9 @@
 **  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
+/*  external requirements  */
 import CBOR from "cbor";
+import { OptionsTrait } from "./mqtt-plus-options";
 /*  the encoder/decoder abstraction  */
 export default class Codec {
     constructor(type) {
@@ -72,3 +74,12 @@ export default class Codec {
         return result;
     }
 }
+/*  Codec trait  */
+export class CodecTrait extends OptionsTrait {
+    /*  construct API class  */
+    constructor(options = {}) {
+        super(options);
+        /*  establish a codec  */
+        this.codec = new Codec(this.options.codec);
+    }
+}

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

@@ -0,0 +1,18 @@
+import { IClientPublishOptions, IClientSubscribeOptions } from "mqtt";
+import { APISchema, EventKeys } from "./mqtt-plus-api";
+import type { WithInfo, InfoEvent } from "./mqtt-plus-info";
+import type { Receiver } from "./mqtt-plus-receiver";
+import { BaseTrait } from "./mqtt-plus-base";
+export interface Subscription {
+    unsubscribe(): Promise<void>;
+}
+export declare class EventTrait<T extends APISchema = APISchema> extends BaseTrait<T> {
+    private subscriptions;
+    subscribe<K extends EventKeys<T> & string>(event: K, callback: WithInfo<T[K], InfoEvent>): Promise<Subscription>;
+    subscribe<K extends EventKeys<T> & string>(event: K, options: Partial<IClientSubscribeOptions>, callback: WithInfo<T[K], InfoEvent>): Promise<Subscription>;
+    emit<K extends EventKeys<T> & string>(event: K, ...params: Parameters<T[K]>): void;
+    emit<K extends EventKeys<T> & string>(event: K, receiver: Receiver, ...params: Parameters<T[K]>): void;
+    emit<K extends EventKeys<T> & string>(event: K, options: IClientPublishOptions, ...params: Parameters<T[K]>): void;
+    emit<K extends EventKeys<T> & string>(event: K, receiver: Receiver, options: IClientPublishOptions, ...params: Parameters<T[K]>): void;
+    protected _dispatchMessage(topic: string, parsed: any): void;
+}