mqtt-plus 0.9.2 → 0.9.3

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.
@@ -60,21 +74,34 @@ communication patterns with optional type safety:
 > [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
@@ -128,12 +155,15 @@ The **MQTT+** API provides the following methods:
               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, clientId?: string }
-              topicServiceRequestMatch:  { name: string, clientId?: string }
-              topicServiceResponseMatch: { name: string, clientId?: string }
+              topicEventNoticeMatch:     { name: string, peerId?: string }
+              topicStreamChunkMatch:     { name: string, peerId?: string }
+              topicServiceRequestMatch:  { name: string, peerId?: string }
+              topicServiceResponseMatch: { name: string, peerId?: string }
           }
       )
 
@@ -149,18 +179,23 @@ 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`).
+  - `chunkSize`: Chunk size in bytes for stream transfers (default: `16384`).
   - `topicEventNoticeMake`: Custom topic generation for event notices.
-    (default: `` (name, clientId) => clientId ? `${name}/event-notice/${clientId}` : `${name}/event-notice` ``)
+    (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, clientId) => clientId ? `${name}/service-request/${clientId}` : `${name}/service-request` ``)
+    (default: `` (name, peerId) => peerId ? `${name}/service-request/${peerId}` : `${name}/service-request` ``)
   - `topicServiceResponseMake`): Custom topic generation for service responses.
-    (default: `` (name, clientId) => clientId ? `${name}/service-response/${clientId}` : `${name}/service-response` ``)
+    (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], clientId: m[2] } : null } ``)
+    (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], clientId: m[2] } : null } ``)
+    (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], clientId: m[2] } : null } ``)
+    (default: `` (topic) => { const m = topic.match(/^(.+?)\/service-response\/(.+)$/); return m ? { name: m[1], peerId: m[2] } : null } ``)
 
 - **Event Subscription**:<br/>
 
@@ -168,7 +203,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.
@@ -179,16 +217,43 @@ The **MQTT+** API provides the following methods:
 
   Internally, on the MQTT broker, the topics generated by
   `topicEventNoticeMake()` (default: `${event}/event-notice` and
-  `${event}/event-notice/${clientId}`) are subscribed. Returns a
+  `${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
+  `topicStreamChunkMake()` (default: `${stream}/stream-chunk` 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.
@@ -199,7 +264,7 @@ The **MQTT+** API provides the following methods:
 
   Internally, on the MQTT broker, the topics by
   `topicServiceRequestMake()` (default: `${service}/service-request` and
-  `${service}/service-request/${clientId}`) are subscribed. Returns a
+  `${service}/service-request/${peerId}`) are subscribed. Returns a
   `Registration` object with an `unregister()` method.
 
 - **Event Emission**:<br/>
@@ -219,8 +284,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 `topicEventNoticeMake(event, peerId)`
+  (default: `${event}/event-notice` 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 `topicStreamChunkMake(stream, peerId)`
+  (default: `${stream}/stream-chunk` or `${stream}/stream-chunk/${peerId}`).
 
 - **Service Call**:<br/>
 
@@ -240,8 +332,8 @@ 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 `topicServiceResponseMake(service, peerId)`
+  (default: `${service}/service-response/${peerId}`) is temporarily subscribed
   for receiving the response.
 
 - **Receiver Wrapping**:<br/>
@@ -382,9 +474,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 +489,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" })

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

@@ -9,6 +9,12 @@ export declare class EventEmission extends Base {
     params?: any[] | undefined;
     constructor(id: string, event: string, params?: any[] | undefined, sender?: string, receiver?: string);
 }
+export declare class StreamChunk extends Base {
+    stream: string;
+    chunk: Buffer | null;
+    params?: any[] | undefined;
+    constructor(id: string, stream: string, chunk: Buffer | null, params?: any[] | undefined, sender?: string, receiver?: string);
+}
 export declare class ServiceRequest extends Base {
     service: string;
     params?: any[] | undefined;
@@ -24,8 +30,9 @@ export declare class ServiceResponseError extends Base {
 }
 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 | ServiceRequest | ServiceResponseSuccess | ServiceResponseError;
+    parse(obj: any): EventEmission | StreamChunk | ServiceRequest | ServiceResponseSuccess | ServiceResponseError;
 }

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

@@ -37,6 +37,15 @@ export class EventEmission extends Base {
         this.params = params;
     }
 }
+/*  stream chunk  */
+export class StreamChunk extends Base {
+    constructor(id, stream, chunk, params, sender, receiver) {
+        super(id, sender, receiver);
+        this.stream = stream;
+        this.chunk = chunk;
+        this.params = params;
+    }
+}
 /*  service request  */
 export class ServiceRequest extends Base {
     constructor(id, service, params, sender, receiver) {
@@ -65,6 +74,10 @@ export default class Msg {
     makeEventEmission(id, event, params, sender, receiver) {
         return new EventEmission(id, event, params, sender, receiver);
     }
+    /*  factory for stream chunk  */
+    makeStreamChunk(id, stream, chunk, params, sender, receiver) {
+        return new StreamChunk(id, stream, chunk, params, sender, receiver);
+    }
     /*  factory for service request  */
     makeServiceRequest(id, service, params, sender, receiver) {
         return new ServiceRequest(id, service, params, sender, receiver);
@@ -100,6 +113,18 @@ export default class Msg {
                 throw new Error("invalid EventEmission object: \"params\" field must be an array");
             return this.makeEventEmission(obj.id, obj.event, obj.params, obj.sender, obj.receiver);
         }
+        if ("stream" in obj) {
+            /*  detect and parse stream chunk  */
+            if (typeof obj.stream !== "string")
+                throw new Error("invalid StreamChunk object: \"stream\" field must be a string");
+            if (anyFieldsExcept(obj, ["type", "id", "stream", "chunk", "params", "sender", "receiver"]))
+                throw new Error("invalid StreamChunk object: contains unknown fields");
+            if (obj.chunk !== undefined && typeof obj.chunk !== "object")
+                throw new Error("invalid StreamChunk object: \"chunk\" field must be an object or null");
+            if (obj.params !== undefined && (typeof obj.params !== "object" || !Array.isArray(obj.params)))
+                throw new Error("invalid StreamChunk object: \"params\" field must be an array");
+            return this.makeStreamChunk(obj.id, obj.stream, obj.chunk, obj.params, obj.sender, obj.receiver);
+        }
         else if ("service" in obj) {
             /*  detect and parse service request  */
             if (typeof obj.service !== "string")

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

@@ -1,3 +1,4 @@
+import stream from "stream";
 import { MqttClient, IClientPublishOptions, IClientSubscribeOptions } from "mqtt";
 export type Receiver = {
     __receiver: string;
@@ -12,30 +13,53 @@ export interface APIOptions {
     id: string;
     codec: "cbor" | "json";
     timeout: number;
+    chunkSize: number;
     topicEventNoticeMake: TopicMake;
+    topicStreamChunkMake: TopicMake;
     topicServiceRequestMake: TopicMake;
     topicServiceResponseMake: TopicMake;
     topicEventNoticeMatch: TopicMatch;
+    topicStreamChunkMatch: TopicMatch;
     topicServiceRequestMatch: TopicMatch;
     topicServiceResponseMatch: TopicMatch;
 }
 export interface Registration {
     unregister(): Promise<void>;
 }
+export interface Attachment {
+    unattach(): Promise<void>;
+}
 export interface Subscription {
     unsubscribe(): Promise<void>;
 }
-export interface Info {
+export interface InfoBase {
     sender: string;
     receiver?: string;
 }
-export type WithInfo<F> = F extends (...args: infer P) => infer R ? (...args: [...P, info: Info]) => R : never;
-export type APISchema = Record<string, ((...args: any[]) => void) | ((...args: any[]) => any)>;
+export interface InfoEvent extends InfoBase {
+}
+export interface InfoStream extends InfoBase {
+    stream: stream.Readable;
+}
+export interface InfoService extends InfoBase {
+}
+export type WithInfo<F, I extends InfoBase> = F extends (...args: infer P) => infer R ? (...args: [...P, info: I]) => R : never;
+type Brand<T> = T & {
+    readonly __brand: unique symbol;
+};
+export type APIEndpoint = ((...args: any[]) => void) | ((...args: any[]) => any);
+export type Event<T extends APIEndpoint> = Brand<T>;
+export type Stream<T extends APIEndpoint> = Brand<T>;
+export type Service<T extends APIEndpoint> = Brand<T>;
+export type APISchema = Record<string, APIEndpoint>;
 export type EventKeys<T> = string extends keyof T ? string : {
-    [K in keyof T]: T[K] extends (...args: any[]) => infer R ? [R] extends [void] ? K : never : never;
+    [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 (...args: any[]) => infer R ? [R] extends [void] ? never : K : never;
+    [K in keyof T]: T[K] extends Service<infer _F> ? K : never;
 }[keyof T];
 export default class MQTTp<T extends APISchema = APISchema> {
     private mqtt;
@@ -45,13 +69,16 @@ export default class MQTTp<T extends APISchema = APISchema> {
     private registry;
     private requests;
     private subscriptions;
+    private streams;
     constructor(mqtt: MqttClient, options?: Partial<APIOptions>);
     private _subscribeTopic;
     private _unsubscribeTopic;
-    subscribe<K extends EventKeys<T> & string>(event: K, callback: WithInfo<T[K]>): Promise<Subscription>;
-    subscribe<K extends EventKeys<T> & string>(event: K, options: Partial<IClientSubscribeOptions>, callback: WithInfo<T[K]>): Promise<Subscription>;
-    register<K extends ServiceKeys<T> & string>(service: K, callback: WithInfo<T[K]>): Promise<Registration>;
-    register<K extends ServiceKeys<T> & string>(service: K, options: Partial<IClientSubscribeOptions>, callback: WithInfo<T[K]>): Promise<Registration>;
+    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>;
+    attach<K extends StreamKeys<T> & string>(stream: K, callback: WithInfo<T[K], InfoStream>): Promise<Attachment>;
+    attach<K extends StreamKeys<T> & string>(stream: K, options: Partial<IClientSubscribeOptions>, callback: WithInfo<T[K], InfoStream>): Promise<Attachment>;
+    register<K extends ServiceKeys<T> & string>(service: K, callback: WithInfo<T[K], InfoService>): Promise<Registration>;
+    register<K extends ServiceKeys<T> & string>(service: K, options: Partial<IClientSubscribeOptions>, callback: WithInfo<T[K], InfoService>): Promise<Registration>;
     private _isIClientPublishOptions;
     receiver(id: string): {
         __receiver: string;
@@ -63,6 +90,10 @@ export default class MQTTp<T extends APISchema = APISchema> {
     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;
+    transfer<K extends StreamKeys<T> & string>(stream: K, readable: stream.Readable, ...params: Parameters<T[K]>): Promise<void>;
+    transfer<K extends StreamKeys<T> & string>(stream: K, readable: stream.Readable, receiver: Receiver, ...params: Parameters<T[K]>): Promise<void>;
+    transfer<K extends StreamKeys<T> & string>(stream: K, readable: stream.Readable, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<void>;
+    transfer<K extends StreamKeys<T> & string>(stream: K, readable: stream.Readable, receiver: Receiver, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<void>;
     call<K extends ServiceKeys<T> & string>(service: K, ...params: Parameters<T[K]>): Promise<Awaited<ReturnType<T[K]>>>;
     call<K extends ServiceKeys<T> & string>(service: K, receiver: Receiver, ...params: Parameters<T[K]>): Promise<Awaited<ReturnType<T[K]>>>;
     call<K extends ServiceKeys<T> & string>(service: K, options: IClientPublishOptions, ...params: Parameters<T[K]>): Promise<Awaited<ReturnType<T[K]>>>;
@@ -71,3 +102,4 @@ export default class MQTTp<T extends APISchema = APISchema> {
     private _responseUnsubscribe;
     private _onMessage;
 }
+export {};

package/dst-stage1/mqtt-plus.js

@@ -21,10 +21,12 @@
 **  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 stream from "stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
 import Codec from "./mqtt-plus-codec";
-import Msg, { EventEmission, ServiceRequest, ServiceResponseSuccess, ServiceResponseError } from "./mqtt-plus-msg";
+import Msg, { EventEmission, StreamChunk, ServiceRequest, ServiceResponseSuccess, ServiceResponseError } from "./mqtt-plus-msg";
 /*  MQTTp API class  */
 export default class MQTTp {
     /*  construct API class  */
@@ -34,16 +36,23 @@ export default class MQTTp {
         this.registry = new Map();
         this.requests = new Map();
         this.subscriptions = new Map();
+        this.streams = new Map();
         /*  determine options and provide defaults  */
         this.options = {
             id: nanoid(),
             codec: "cbor",
             timeout: 10 * 1000,
+            chunkSize: 16 * 1024,
             topicEventNoticeMake: (name, peerId) => {
                 return peerId
                     ? `${name}/event-notice/${peerId}`
                     : `${name}/event-notice`;
             },
+            topicStreamChunkMake: (name, peerId) => {
+                return peerId
+                    ? `${name}/stream-chunk/${peerId}`
+                    : `${name}/stream-chunk`;
+            },
             topicServiceRequestMake: (name, peerId) => {
                 return peerId
                     ? `${name}/service-request/${peerId}`
@@ -58,6 +67,10 @@ export default class MQTTp {
                 const m = topic.match(/^(.+?)\/event-notice(?:\/(.+))?$/);
                 return m ? { name: m[1], peerId: m[2] } : null;
             },
+            topicStreamChunkMatch: (topic) => {
+                const m = topic.match(/^(.+?)\/stream-chunk(?:\/(.+))?$/);
+                return m ? { name: m[1], peerId: m[2] } : null;
+            },
             topicServiceRequestMatch: (topic) => {
                 const m = topic.match(/^(.+?)\/service-request(?:\/(.+))?$/);
                 return m ? { name: m[1], peerId: m[2] } : null;
@@ -137,6 +150,46 @@ export default class MQTTp {
         };
         return subscription;
     }
+    async attach(stream, ...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.registry.has(stream))
+            throw new Error(`attach: stream "${stream}" already attached`);
+        /*  generate the corresponding MQTT topics for broadcast and direct use  */
+        const topicB = this.options.topicStreamChunkMake(stream);
+        const topicD = this.options.topicStreamChunkMake(stream, 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.registry.set(stream, callback);
+        /*  provide an attachment for subsequent unattaching  */
+        const self = this;
+        const attachment = {
+            async unattach() {
+                if (!self.registry.has(stream))
+                    throw new Error(`unattach: stream "${stream}" not attached`);
+                self.registry.delete(stream);
+                return Promise.all([
+                    self._unsubscribeTopic(topicB),
+                    self._unsubscribeTopic(topicD)
+                ]).then(() => { });
+            }
+        };
+        return attachment;
+    }
     async register(service, ...args) {
         /*  determine parameters  */
         let options = {};
@@ -224,7 +277,7 @@ export default class MQTTp {
         const { receiver, options, params } = this._parseCallArgs(args);
         /*  generate unique request id  */
         const rid = nanoid();
-        /*  generate encoded Msg message  */
+        /*  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  */
@@ -232,6 +285,52 @@ export default class MQTTp {
         /*  publish message to MQTT topic  */
         this.mqtt.publish(topic, message, { qos: 2, ...options });
     }
+    transfer(stream, readable, ...args) {
+        /*  determine actual parameters  */
+        const { receiver, options, params } = this._parseCallArgs(args);
+        /*  generate unique request id  */
+        const rid = nanoid();
+        /*  generate corresponding MQTT topic  */
+        const topic = this.options.topicStreamChunkMake(stream, receiver);
+        /*  utility function for converting a chunk to a Buffer  */
+        const chunkToBuffer = (chunk) => {
+            let buffer;
+            if (Buffer.isBuffer(chunk))
+                buffer = chunk;
+            else if (typeof chunk === "string")
+                buffer = Buffer.from(chunk);
+            else if (chunk instanceof Uint8Array)
+                buffer = Buffer.from(chunk);
+            else
+                buffer = Buffer.from(String(chunk));
+            return buffer;
+        };
+        /*  iterate over all chunks of the buffer  */
+        return new Promise((resolve, reject) => {
+            readable.on("readable", () => {
+                let chunk;
+                while ((chunk = readable.read(this.options.chunkSize)) !== null) {
+                    /*  ensure data is a Buffer  */
+                    const buffer = chunkToBuffer(chunk);
+                    /*  generate encoded message  */
+                    const request = this.msg.makeStreamChunk(rid, stream, buffer, params, this.options.id, receiver);
+                    const message = this.codec.encode(request);
+                    /*  publish message to MQTT topic  */
+                    this.mqtt.publish(topic, message, { qos: 2, ...options });
+                }
+            });
+            readable.on("end", () => {
+                /*  send "null" chunk to signal end of stream  */
+                const request = this.msg.makeStreamChunk(rid, stream, null, params, this.options.id, receiver);
+                const message = this.codec.encode(request);
+                this.mqtt.publish(topic, message, { qos: 2, ...options });
+                resolve();
+            });
+            readable.on("error", () => {
+                reject(new Error("readable stream error"));
+            });
+        });
+    }
     call(service, ...args) {
         /*  determine actual parameters  */
         const { receiver, options, params } = this._parseCallArgs(args);
@@ -313,14 +412,19 @@ export default class MQTTp {
     _onMessage(topic, message) {
         /*  ensure we handle only valid messages  */
         let eventMatch = null;
+        let streamMatch = null;
         let requestMatch = null;
         let responseMatch = null;
         if ((eventMatch = this.options.topicEventNoticeMatch(topic)) === null
+            && (streamMatch = this.options.topicStreamChunkMatch(topic)) === null
             && (requestMatch = this.options.topicServiceRequestMatch(topic)) === null
             && (responseMatch = this.options.topicServiceResponseMatch(topic)) === null)
             return;
         /*  ensure we really handle only messages for us  */
-        const peerId = eventMatch?.peerId ?? requestMatch?.peerId ?? responseMatch?.peerId;
+        const peerId = eventMatch?.peerId ??
+            streamMatch?.peerId ??
+            requestMatch?.peerId ??
+            responseMatch?.peerId;
         if (peerId !== undefined && peerId !== this.options.id)
             return;
         /*  try to parse payload as payload  */
@@ -348,6 +452,26 @@ export default class MQTTp {
             const info = { sender: parsed.sender ?? "", receiver: parsed.receiver };
             handler?.(...params, info);
         }
+        else if (parsed instanceof StreamChunk) {
+            /*  just handle stream chunk  */
+            const id = parsed.id;
+            let chunk = parsed.chunk;
+            let readable = this.streams.get(id);
+            if (readable === undefined) {
+                const name = parsed.stream;
+                const params = parsed.params ?? [];
+                readable = new stream.Readable({ read(_size) { } });
+                this.streams.set(id, readable);
+                const info = { sender: parsed.sender ?? "", receiver: parsed.receiver, stream: readable };
+                const handler = this.registry.get(name);
+                handler?.(...params, info);
+            }
+            if (chunk !== null && !Buffer.isBuffer(chunk))
+                chunk = Buffer.from(chunk);
+            readable.push(chunk);
+            if (chunk === null)
+                this.streams.delete(id);
+        }
         else if (parsed instanceof ServiceRequest) {
             /*  deliver service request and send response  */
             const rid = parsed.id;