mqtt-plus 0.9.3 → 0.9.4

package/README.md

@@ -69,6 +69,15 @@ 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
@@ -152,18 +161,12 @@ The **MQTT+** API provides the following methods:
       constructor<API>(
           mqtt: MqttClient,
           options?: {
-              id:                        string
-              codec:                     "cbor" | "json"
-              timeout:                   number
-              chunkSize:                 number
-              topicEventNoticeMake:      (topic: string) => TopicMatching | null
-              topicStreamChunkMake:      (topic: string) => TopicMatching | null
-              topicServiceRequestMake:   (topic: string) => TopicMatching | null
-              topicServiceResponseMake:  (topic: string) => TopicMatching | null
-              topicEventNoticeMatch:     { name: string, peerId?: string }
-              topicStreamChunkMatch:     { name: string, peerId?: string }
-              topicServiceRequestMatch:  { name: string, peerId?: string }
-              topicServiceResponseMatch: { name: string, peerId?: 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
           }
       )
 
@@ -180,22 +183,12 @@ The **MQTT+** API provides the following methods:
   - `codec`: Encoding format (default: `cbor`).
   - `timeout`: Communication timeout in milliseconds (default: `10000`).
   - `chunkSize`: Chunk size in bytes for stream transfers (default: `16384`).
-  - `topicEventNoticeMake`: Custom topic generation for event notices.
-    (default: `` (name, peerId) => peerId ? `${name}/event-notice/${peerId}` : `${name}/event-notice` ``)
-  - `topicStreamChunkMake`: Custom topic generation for stream chunks.
-    (default: `` (name, peerId) => peerId ? `${name}/stream-chunk/${peerId}` : `${name}/stream-chunk` ``)
-  - `topicServiceRequestMake`: Custom topic generation for service requests.
-    (default: `` (name, peerId) => peerId ? `${name}/service-request/${peerId}` : `${name}/service-request` ``)
-  - `topicServiceResponseMake`): Custom topic generation for service responses.
-    (default: `` (name, peerId) => peerId ? `${name}/service-response/${peerId}` : `${name}/service-response` ``)
-  - `topicEventNoticeMatch`: Custom topic matching for event notices.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/event-notice(?:\/(.+))?$/); return m ? { name: m[1], peerId: m[2] } : null } ``)
-  - `topicStreamChunkMatch`: Custom topic matching for stream chunks.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/stream-chunk(?:\/(.+))?$/); return m ? { name: m[1], peerId: m[2] } : null } ``)
-  - `topicServiceRequestMatch`: Custom topic matching for service requests.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/service-request(?:\/(.+))?$/); return m ? { name: m[1], peerId: m[2] } : null } ``)
-  - `topicServiceResponseMatch`: Custom topic matching for service responses.
-    (default: `` (topic) => { const m = topic.match(/^(.+?)\/service-response\/(.+)$/); return m ? { name: m[1], peerId: m[2] } : null } ``)
+  - `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/>
 
@@ -216,7 +209,7 @@ 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
+  `topicMake(event, "event-notice")` (default: `${event}/event-notice/any` and
   `${event}/event-notice/${peerId}`) are subscribed. Returns a
   `Subscription` object with an `unsubscribe()` method.
 
@@ -240,7 +233,7 @@ The **MQTT+** API provides the following methods:
   There is no return value of `callback`.
 
   Internally, on the MQTT broker, the topics generated by
-  `topicStreamChunkMake()` (default: `${stream}/stream-chunk` and
+  `topicMake(stream, "stream-chunk")` (default: `${stream}/stream-chunk/any` and
   `${stream}/stream-chunk/${peerId}`) are subscribed. Returns an
   `Attachment` object with an `unattach()` method.
 
@@ -263,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/${peerId}`) 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)  */
@@ -284,8 +300,8 @@ 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, peerId)`
-  (default: `${event}/event-notice` or `${event}/event-notice/${peerId}`).
+  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/>
 
@@ -311,8 +327,8 @@ The **MQTT+** API provides the following methods:
   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 `topicStreamChunkMake(stream, peerId)`
-  (default: `${stream}/stream-chunk` or `${stream}/stream-chunk/${peerId}`).
+  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/>
 
@@ -332,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, peerId)`
-  (default: `${service}/service-response/${peerId}`) 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/>
@@ -368,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
@@ -391,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
 {
@@ -524,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;
+}

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

@@ -0,0 +1,103 @@
+/*
+**  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 { nanoid } from "nanoid";
+/*  internal requirements  */
+import { EventEmission } from "./mqtt-plus-msg";
+import { BaseTrait } from "./mqtt-plus-base";
+/*  Event Communication Trait  */
+export class EventTrait extends BaseTrait {
+    constructor() {
+        super(...arguments);
+        /*  internal state  */
+        this.subscriptions = new Map();
+    }
+    async subscribe(event, ...args) {
+        /*  determine parameters  */
+        let options = {};
+        let callback = args[0];
+        if (args.length === 2 && typeof args[0] === "object") {
+            options = args[0];
+            callback = args[1];
+        }
+        /*  sanity check situation  */
+        if (this.subscriptions.has(event))
+            throw new Error(`subscribe: event "${event}" already subscribed`);
+        /*  generate the corresponding MQTT topics for broadcast and direct use  */
+        const topicB = this.options.topicMake(event, "event-emission");
+        const topicD = this.options.topicMake(event, "event-emission", this.options.id);
+        /*  subscribe to MQTT topics  */
+        await Promise.all([
+            this._subscribeTopic(topicB, { qos: 0, ...options }),
+            this._subscribeTopic(topicD, { qos: 0, ...options })
+        ]).catch((err) => {
+            this._unsubscribeTopic(topicB).catch(() => { });
+            this._unsubscribeTopic(topicD).catch(() => { });
+            throw err;
+        });
+        /*  remember the subscription  */
+        this.subscriptions.set(event, callback);
+        /*  provide a subscription for subsequent unsubscribing  */
+        const self = this;
+        const subscription = {
+            async unsubscribe() {
+                if (!self.subscriptions.has(event))
+                    throw new Error(`unsubscribe: event "${event}" not subscribed`);
+                self.subscriptions.delete(event);
+                return Promise.all([
+                    self._unsubscribeTopic(topicB),
+                    self._unsubscribeTopic(topicD)
+                ]).then(() => { });
+            }
+        };
+        return subscription;
+    }
+    emit(event, ...args) {
+        /*  determine actual parameters  */
+        const { receiver, options, params } = this._parseCallArgs(args);
+        /*  generate unique request id  */
+        const rid = nanoid();
+        /*  generate encoded message  */
+        const request = this.msg.makeEventEmission(rid, event, params, this.options.id, receiver);
+        const message = this.codec.encode(request);
+        /*  generate corresponding MQTT topic  */
+        const topic = this.options.topicMake(event, "event-emission", receiver);
+        /*  publish message to MQTT topic  */
+        this.mqtt.publish(topic, message, { qos: 2, ...options });
+    }
+    /*  dispatch message (Event pattern handling)  */
+    _dispatchMessage(topic, parsed) {
+        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.event;
+            const handler = this.subscriptions.get(name);
+            const params = parsed.params ?? [];
+            const info = { sender: parsed.sender ?? "", receiver: parsed.receiver };
+            handler?.(...params, info);
+        }
+    }
+}

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

@@ -0,0 +1,15 @@
+import stream from "stream";
+export interface InfoBase {
+    sender: string;
+    receiver?: string;
+}
+export interface InfoEvent extends InfoBase {
+}
+export interface InfoStream extends InfoBase {
+    stream: stream.Readable;
+}
+export interface InfoService extends InfoBase {
+}
+export interface InfoResource extends InfoBase {
+}
+export type WithInfo<F, I extends InfoBase> = F extends (...args: infer P) => infer R ? (...args: [...P, info: I]) => R : never;

package/dst-stage1/mqtt-plus-info.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-msg.d.ts

@@ -1,8 +1,11 @@
+import { APISchema } from "./mqtt-plus-api";
+import { CodecTrait } from "./mqtt-plus-codec";
 export declare class Base {
+    type: string;
     id: string;
     sender?: string | undefined;
     receiver?: string | undefined;
-    constructor(id: string, sender?: string | undefined, receiver?: string | undefined);
+    constructor(type: string, id: string, sender?: string | undefined, receiver?: string | undefined);
 }
 export declare class EventEmission extends Base {
     event: string;
@@ -20,19 +23,30 @@ export declare class ServiceRequest extends Base {
     params?: any[] | undefined;
     constructor(id: string, service: string, params?: any[] | undefined, sender?: string, receiver?: string);
 }
-export declare class ServiceResponseSuccess extends Base {
-    result: any;
-    constructor(id: string, result: any, sender?: string, receiver?: string);
+export declare class ServiceResponse extends Base {
+    result?: any | undefined;
+    error?: string | undefined;
+    constructor(id: string, result?: any | undefined, error?: string | undefined, sender?: string, receiver?: string);
 }
-export declare class ServiceResponseError extends Base {
-    error: string;
-    constructor(id: string, error: string, sender?: string, receiver?: string);
+export declare class ResourceRequest extends Base {
+    resource: string;
+    params?: any[] | undefined;
+    constructor(id: string, resource: string, params?: any[] | undefined, sender?: string, receiver?: string);
+}
+export declare class ResourceResponse extends Base {
+    chunk: Buffer | null | undefined;
+    error: string | undefined;
+    constructor(id: string, chunk: Buffer | null | undefined, error: string | undefined, sender?: string, receiver?: string);
 }
 export default class Msg {
     makeEventEmission(id: string, event: string, params?: any[], sender?: string, receiver?: string): EventEmission;
     makeStreamChunk(id: string, stream: string, chunk: Buffer | null, params?: any[], sender?: string, receiver?: string): StreamChunk;
     makeServiceRequest(id: string, service: string, params?: any[], sender?: string, receiver?: string): ServiceRequest;
-    makeServiceResponseSuccess(id: string, result: any, sender?: string, receiver?: string): ServiceResponseSuccess;
-    makeServiceResponseError(id: string, error: string, sender?: string, receiver?: string): ServiceResponseError;
-    parse(obj: any): EventEmission | StreamChunk | ServiceRequest | ServiceResponseSuccess | ServiceResponseError;
+    makeServiceResponse(id: string, result?: any, error?: string, sender?: string, receiver?: string): ServiceResponse;
+    makeResourceRequest(id: string, resource: string, params?: any[], sender?: string, receiver?: string): ResourceRequest;
+    makeResourceResponse(id: string, chunk?: Buffer | null, error?: string, sender?: string, receiver?: string): ResourceResponse;
+    parse(obj: any): EventEmission | StreamChunk | ServiceRequest | ServiceResponse | ResourceRequest | ResourceResponse;
+}
+export declare class MsgTrait<T extends APISchema = APISchema> extends CodecTrait<T> {
+    protected msg: Msg;
 }