mqtt-plus 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 ChangeLog
 =========
 
+1.2.1 (2026-02-07)
+------------------
+
+- REFACTOR: use a reference counting subscription class
+- CLEANUP: improve internal validation logic
+- CLEANUP: various code cleanups
+
 1.2.0 (2026-02-06)
 ------------------
 

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

@@ -41,9 +41,9 @@ export class AuthTrait extends MetaTrait {
         if (credential.length === 0)
             throw new Error("credential must not be empty");
         /*  use a derived key with minimum length of 32 for JWT HS256  */
-        const pw = new TextEncoder().encode(credential);
-        const st = new TextEncoder().encode("mqtt-plus");
-        this._credential = pbkdf2.deriveKey(sha256.SHA256, pw, st, 100000, 32);
+        const pass = new TextEncoder().encode(credential);
+        const salt = new TextEncoder().encode("mqtt-plus");
+        this._credential = pbkdf2.deriveKey(sha256.SHA256, pass, salt, 100000, 32);
     }
     /*  issue client-side token on server-side  */
     async issue(payload) {
@@ -93,6 +93,10 @@ export class AuthTrait extends MetaTrait {
                     continue;
                 if (payload.id && payload.id !== clientId)
                     continue;
+                if (!Array.isArray(payload.roles))
+                    continue;
+                if (payload.roles.length > 64)
+                    continue;
                 for (const role of roles) {
                     if (payload.roles.includes(role)) {
                         authenticated = true;

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

@@ -7,10 +7,10 @@ export declare class JSONX {
     static parse(json: string): unknown;
 }
 declare class Codec {
-    private type;
+    private format;
     private types;
     private tags;
-    constructor(type: "cbor" | "json");
+    constructor(format: "cbor" | "json");
     encode(data: unknown): Uint8Array | string;
     decode(data: Uint8Array | string): unknown;
 }

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

@@ -46,8 +46,8 @@ export class JSONX {
 }
 /*  the encoder/decoder abstraction  */
 class Codec {
-    constructor(type) {
-        this.type = type;
+    constructor(format) {
+        this.format = format;
         this.types = new CBOR.TypeEncoderMap();
         this.tags = new Map();
         /*  support direct encoding/decoding of Buffer  */
@@ -61,7 +61,7 @@ class Codec {
     }
     encode(data) {
         let result;
-        if (this.type === "cbor") {
+        if (this.format === "cbor") {
             try {
                 result = CBOR.encode(data, { types: this.types });
             }
@@ -69,7 +69,7 @@ class Codec {
                 throw new Error("failed to encode CBOR format", { cause: ex });
             }
         }
-        else if (this.type === "json") {
+        else if (this.format === "json") {
             try {
                 result = JSONX.stringify(data);
             }
@@ -78,12 +78,12 @@ class Codec {
             }
         }
         else
-            throw new Error(`invalid format "${this.type}"`);
+            throw new Error(`invalid format "${this.format}"`);
         return result;
     }
     decode(data) {
         let result;
-        if (this.type === "cbor") {
+        if (this.format === "cbor") {
             if (!(data instanceof Uint8Array))
                 throw new Error("failed to decode CBOR format (data type is not Uint8Array)");
             try {
@@ -93,7 +93,7 @@ class Codec {
                 throw new Error("failed to decode CBOR format", { cause: ex });
             }
         }
-        else if (this.type === "json") {
+        else if (this.format === "json") {
             if (typeof data !== "string")
                 throw new Error("failed to decode JSON format (data type is not string)");
             try {
@@ -104,7 +104,7 @@ class Codec {
             }
         }
         else
-            throw new Error(`invalid format "${this.type}"`);
+            throw new Error(`invalid format "${this.format}"`);
         return result;
     }
 }

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

@@ -45,7 +45,7 @@ export class EncodeTrait extends CodecTrait {
     }
     buf2arr(data, cons) {
         let arr;
-        if (typeof Buffer !== "undefined" && cons === Buffer)
+        if (cons === Buffer)
             arr = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
         else if (cons === Uint8Array)
             arr = data;

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

@@ -56,9 +56,9 @@ export class EventTrait extends AuthTrait {
         if (this.events.has(name))
             throw new Error(`event: event "${name}" already registered`);
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
-        const topic = share ? `$share/${share}/${name}` : name;
-        const topicB = this.options.topicMake(topic, "event-emission");
-        const topicD = this.options.topicMake(topic, "event-emission", this.options.id);
+        const topicS = share ? `$share/${share}/${name}` : name;
+        const topicB = this.options.topicMake(topicS, "event-emission");
+        const topicD = this.options.topicMake(name, "event-emission", this.options.id);
         /*  subscribe to MQTT topics  */
         await Promise.all([
             this._subscribeTopic(topicB, { qos: 0, ...options }),
@@ -142,14 +142,14 @@ export class EventTrait extends AuthTrait {
             if (topicMatch.name !== name)
                 throw new Error(`event name mismatch between topic "${topicMatch.name}" and payload "${name}"`);
             const handler = this.events.get(name);
+            if (handler === undefined)
+                throw new Error(`handler for event "${name}" not found`);
             const params = parsed.params ?? [];
             const info = { sender: parsed.sender ?? "" };
             if (parsed.receiver)
                 info.receiver = parsed.receiver;
             if (parsed.meta)
                 info.meta = parsed.meta;
-            if (handler === undefined)
-                throw new Error(`handler for event "${name}" not found`);
             if (handler.auth)
                 info.authenticated = await this.authenticated(parsed.sender, parsed.auth, handler.auth);
             Promise.resolve().then(() => {

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

@@ -26,8 +26,8 @@ import * as v from "valibot";
 import { EncodeTrait } from "./mqtt-plus-encode";
 /*  meta validation schema (non-array plain object)  */
 const MetaSchema = v.pipe(v.record(v.string(), v.unknown()), v.check((data) => !Array.isArray(data)));
-/*  reusable object schema (any non-null object)  */
-const ObjectSchema = v.custom((input) => typeof input === "object" && input !== null);
+/*  reusable auth validation schema (max 8 tokens, max 8192 chars each)  */
+const AuthSchema = v.pipe(v.array(v.pipe(v.string(), v.maxLength(8192))), v.maxLength(8));
 /*  base class  */
 class Base {
     constructor(type, id, sender, receiver) {
@@ -57,8 +57,8 @@ const EventEmissionSchema = v.strictObject({
     ...BaseSchema,
     type: v.literal("event-emission"),
     name: v.string(),
-    params: v.optional(v.array(v.unknown())),
-    auth: v.optional(v.array(v.string())),
+    params: v.optional(v.pipe(v.array(v.unknown()), v.maxLength(64))),
+    auth: v.optional(AuthSchema),
     meta: v.optional(MetaSchema)
 });
 /*  service request  */
@@ -75,8 +75,8 @@ const ServiceCallRequestSchema = v.strictObject({
     ...BaseSchema,
     type: v.literal("service-call-request"),
     name: v.string(),
-    params: v.optional(v.array(v.unknown())),
-    auth: v.optional(v.array(v.string())),
+    params: v.optional(v.pipe(v.array(v.unknown()), v.maxLength(64))),
+    auth: v.optional(AuthSchema),
     meta: v.optional(MetaSchema)
 });
 /*  service response  */
@@ -107,8 +107,8 @@ const SinkPushRequestSchema = v.strictObject({
     ...BaseSchema,
     type: v.literal("sink-push-request"),
     name: v.string(),
-    params: v.optional(v.array(v.unknown())),
-    auth: v.optional(v.array(v.string())),
+    params: v.optional(v.pipe(v.array(v.unknown()), v.maxLength(64))),
+    auth: v.optional(AuthSchema),
     meta: v.optional(MetaSchema)
 });
 /*  sink push response (ack/nak)  */
@@ -126,7 +126,7 @@ const SinkPushResponseSchema = v.strictObject({
     type: v.literal("sink-push-response"),
     name: v.string(),
     error: v.optional(v.string()),
-    auth: v.optional(v.array(v.string())),
+    auth: v.optional(AuthSchema),
     meta: v.optional(MetaSchema)
 });
 /*  sink push chunk (actual data transfer)  */
@@ -143,7 +143,7 @@ const SinkPushChunkSchema = v.strictObject({
     ...BaseSchema,
     type: v.literal("sink-push-chunk"),
     name: v.string(),
-    chunk: v.optional(ObjectSchema),
+    chunk: v.optional(v.instance(Uint8Array)),
     error: v.optional(v.string()),
     final: v.optional(v.boolean())
 });
@@ -161,8 +161,8 @@ const SourceFetchRequestSchema = v.strictObject({
     ...BaseSchema,
     type: v.literal("source-fetch-request"),
     name: v.string(),
-    params: v.optional(v.array(v.unknown())),
-    auth: v.optional(v.array(v.string())),
+    params: v.optional(v.pipe(v.array(v.unknown()), v.maxLength(64))),
+    auth: v.optional(AuthSchema),
     meta: v.optional(MetaSchema)
 });
 /*  source fetch response (ack/nak)  */
@@ -180,7 +180,7 @@ const SourceFetchResponseSchema = v.strictObject({
     type: v.literal("source-fetch-response"),
     name: v.string(),
     error: v.optional(v.string()),
-    auth: v.optional(v.array(v.string())),
+    auth: v.optional(AuthSchema),
     meta: v.optional(MetaSchema)
 });
 /*  source fetch chunk (actual data transfer)  */
@@ -197,55 +197,48 @@ const SourceFetchChunkSchema = v.strictObject({
     ...BaseSchema,
     type: v.literal("source-fetch-chunk"),
     name: v.string(),
-    chunk: v.optional(ObjectSchema),
+    chunk: v.optional(v.instance(Uint8Array)),
     error: v.optional(v.string()),
     final: v.optional(v.boolean())
 });
 /*  utility class  */
 class Msg {
-    /*  factory for event emission  */
+    /*  factories for creating objects  */
     makeEventEmission(id, name, params, sender, receiver, auth, meta) {
         return new EventEmission(id, name, params, sender, receiver, auth, meta);
     }
-    /*  factory for service request  */
     makeServiceCallRequest(id, name, params, sender, receiver, auth, meta) {
         return new ServiceCallRequest(id, name, params, sender, receiver, auth, meta);
     }
-    /*  factory for service response  */
     makeServiceCallResponse(id, result, error, sender, receiver) {
         return new ServiceCallResponse(id, result, error, sender, receiver);
     }
-    /*  factory for sink push request  */
     makeSinkPushRequest(id, name, params, sender, receiver, auth, meta) {
         return new SinkPushRequest(id, name, params, sender, receiver, auth, meta);
     }
-    /*  factory for sink push response  */
     makeSinkPushResponse(id, name, error, sender, receiver, auth, meta) {
         return new SinkPushResponse(id, name, error, sender, receiver, auth, meta);
     }
-    /*  factory for sink push chunk  */
     makeSinkPushChunk(id, name, chunk, error, final, sender, receiver) {
         return new SinkPushChunk(id, name, chunk, error, final, sender, receiver);
     }
-    /*  factory for source fetch request  */
     makeSourceFetchRequest(id, name, params, sender, receiver, auth, meta) {
         return new SourceFetchRequest(id, name, params, sender, receiver, auth, meta);
     }
-    /*  factory for source fetch response  */
     makeSourceFetchResponse(id, name, error, sender, receiver, auth, meta) {
         return new SourceFetchResponse(id, name, error, sender, receiver, auth, meta);
     }
-    /*  factory for source fetch chunk  */
     makeSourceFetchChunk(id, name, chunk, error, final, sender, receiver) {
         return new SourceFetchChunk(id, name, chunk, error, final, sender, receiver);
     }
     /*  parse any object into typed object  */
     parse(obj) {
+        /*  sanity check input  */
         if (typeof obj !== "object" || obj === null)
             throw new Error("invalid argument: not an object");
         if (typeof obj.type !== "string")
             throw new Error("invalid object: missing or invalid \"type\" field");
-        /*  dispatch according to type indication by field  */
+        /*  helper function for Valibot-based validation  */
         const parseObject = (obj, name, schema) => {
             const res = v.safeParse(schema, obj);
             if (!res.success) {
@@ -254,6 +247,7 @@ class Msg {
             }
             return res.output;
         };
+        /*  dispatch according to type indication by field  */
         if (obj.type === "event-emission") {
             const out = parseObject(obj, "EventEmission", EventEmissionSchema);
             return this.makeEventEmission(out.id, out.name, out.params, out.sender, out.receiver, out.auth, out.meta);

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

@@ -23,7 +23,5 @@ export declare class ServiceTrait<T extends APISchema = APISchema> extends Event
         options?: IClientPublishOptions;
         meta?: Record<string, any>;
     }): Promise<ReturnType<T[K]>>;
-    private callSubscribe;
-    private callUnsubscribe;
     protected _dispatchMessage(topic: string, parsed: any): Promise<void>;
 }

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

@@ -23,6 +23,7 @@
 */
 import { nanoid } from "nanoid";
 /*  internal requirements  */
+import { RefCountedSubscription } from "./mqtt-plus-util";
 import { ServiceCallRequest, ServiceCallResponse } from "./mqtt-plus-msg";
 import { EventTrait } from "./mqtt-plus-event";
 /*  Service Communication Trait  */
@@ -32,7 +33,7 @@ export class ServiceTrait extends EventTrait {
         /*  internal state  */
         this.services = new Map();
         this.callCallbacks = new Map();
-        this.callSubscriptions = new Map();
+        this.callSubscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic), (err) => this.error(err));
     }
     async service(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -58,9 +59,9 @@ export class ServiceTrait extends EventTrait {
         if (this.services.has(name))
             throw new Error(`register: service "${name}" already registered`);
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
-        const topic = `$share/${share}/${name}`;
-        const topicB = this.options.topicMake(topic, "service-call-request");
-        const topicD = this.options.topicMake(topic, "service-call-request", this.options.id);
+        const topicS = `$share/${share}/${name}`;
+        const topicB = this.options.topicMake(topicS, "service-call-request");
+        const topicD = this.options.topicMake(name, "service-call-request", this.options.id);
         /*  subscribe to MQTT topics  */
         await Promise.all([
             this._subscribeTopic(topicB, { qos: 2, ...options }),
@@ -114,12 +115,13 @@ export class ServiceTrait extends EventTrait {
         /*  generate unique request id  */
         const requestId = nanoid();
         /*  subscribe to MQTT response topic  */
-        await this.callSubscribe(name, { qos: options.qos ?? 2 });
+        const responseTopic = this.options.topicMake(name, "service-call-response", this.options.id);
+        await this.callSubscriptions.subscribe(responseTopic, { qos: options.qos ?? 2 });
         /*  create promise for MQTT response handling  */
         const promise = new Promise((resolve, reject) => {
             let timer = setTimeout(() => {
                 this.callCallbacks.delete(requestId);
-                this.callUnsubscribe(name);
+                this.callSubscriptions.unsubscribe(responseTopic);
                 timer = null;
                 reject(new Error("communication timeout"));
             }, this.options.timeout);
@@ -150,49 +152,12 @@ export class ServiceTrait extends EventTrait {
             const pendingRequest = this.callCallbacks.get(requestId);
             if (pendingRequest !== undefined) {
                 this.callCallbacks.delete(requestId);
-                this.callUnsubscribe(name);
+                this.callSubscriptions.unsubscribe(responseTopic);
                 pendingRequest.callback(err, undefined);
             }
         });
         return promise;
     }
-    /*  subscribe to RPC response  */
-    async callSubscribe(service, options = { qos: 2 }) {
-        /*  generate corresponding MQTT topic  */
-        const topic = this.options.topicMake(service, "service-call-response", this.options.id);
-        /*  subscribe to MQTT topic and remember subscription  */
-        const count = this.callSubscriptions.get(topic) ?? 0;
-        this.callSubscriptions.set(topic, count + 1);
-        if (count === 0) {
-            await this._subscribeTopic(topic, options).catch((err) => {
-                const currentCount = this.callSubscriptions.get(topic) ?? 0;
-                if (currentCount > 1)
-                    this.callSubscriptions.set(topic, currentCount - 1);
-                else
-                    this.callSubscriptions.delete(topic);
-                this.error(err);
-                throw err;
-            });
-        }
-    }
-    /*  unsubscribe from RPC response  */
-    callUnsubscribe(service) {
-        /*  generate corresponding MQTT topic  */
-        const topic = this.options.topicMake(service, "service-call-response", this.options.id);
-        /*  short-circuit processing if (no longer) subscribed  */
-        if (!this.callSubscriptions.has(topic))
-            return;
-        /*  unsubscribe from MQTT topic and forget subscription  */
-        const count = this.callSubscriptions.get(topic) ?? 0;
-        if (count > 1)
-            this.callSubscriptions.set(topic, count - 1);
-        else {
-            this.callSubscriptions.delete(topic);
-            this._unsubscribeTopic(topic).catch((err) => {
-                this.error(err);
-            });
-        }
-    }
     /*  dispatch message (Service pattern handling)  */
     async _dispatchMessage(topic, parsed) {
         await super._dispatchMessage(topic, parsed);
@@ -263,7 +228,8 @@ export class ServiceTrait extends EventTrait {
                     request.callback(undefined, parsed.result);
                 /*  unsubscribe from response  */
                 this.callCallbacks.delete(requestId);
-                this.callUnsubscribe(request.name);
+                const respTopic = this.options.topicMake(request.name, "service-call-response", this.options.id);
+                this.callSubscriptions.unsubscribe(respTopic);
             }
         }
     }

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

@@ -27,7 +27,5 @@ export declare class SinkTrait<T extends APISchema = APISchema> extends SourceTr
         options?: IClientPublishOptions;
         meta?: Record<string, any>;
     }): Promise<void>;
-    private pushSubscribe;
-    private pushUnsubscribe;
     protected _dispatchMessage(topic: string, parsed: any): Promise<void>;
 }

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

@@ -25,7 +25,7 @@
 import { Readable } from "node:stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
-import { streamToBuffer, sendBufferAsChunks, sendStreamAsChunks } from "./mqtt-plus-util";
+import { RefCountedSubscription, streamToBuffer, sendBufferAsChunks, sendStreamAsChunks } from "./mqtt-plus-util";
 import { SinkPushRequest, SinkPushResponse, SinkPushChunk } from "./mqtt-plus-msg";
 import { SourceTrait } from "./mqtt-plus-source";
 /*  Sink Push Communication Trait  */
@@ -37,7 +37,7 @@ export class SinkTrait extends SourceTrait {
         this.pushStreams = new Map();
         this.pushTimers = new Map();
         this.pushCallbacks = new Map();
-        this.pushSubscriptions = new Map();
+        this.pushSubscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic), (err) => this.error(err));
     }
     async sink(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -63,10 +63,10 @@ export class SinkTrait extends SourceTrait {
         if (this.sinks.has(name))
             throw new Error(`sink: sink "${name}" already established`);
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
-        const topic = `$share/${share}/${name}`;
-        const topicReqB = this.options.topicMake(topic, "sink-push-request");
-        const topicReqD = this.options.topicMake(topic, "sink-push-request", this.options.id);
-        const topicChunkD = this.options.topicMake(topic, "sink-push-chunk", this.options.id);
+        const topicS = `$share/${share}/${name}`;
+        const topicReqB = this.options.topicMake(topicS, "sink-push-request");
+        const topicReqD = this.options.topicMake(name, "sink-push-request", this.options.id);
+        const topicChunkD = this.options.topicMake(name, "sink-push-chunk", this.options.id);
         /*  subscribe to MQTT topics  */
         await Promise.all([
             this._subscribeTopic(topicReqB, { qos: 2, ...options }),
@@ -127,7 +127,7 @@ export class SinkTrait extends SourceTrait {
         const requestId = nanoid();
         /*  subscribe to response topic (for ack/nak)  */
         const responseTopic = this.options.topicMake(name, "sink-push-response", this.options.id);
-        await this.pushSubscribe(responseTopic, { qos: 2 });
+        await this.pushSubscriptions.subscribe(responseTopic, { qos: 2 });
         /*  define timer  */
         let timer = null;
         /*  utility function for cleanup  */
@@ -136,7 +136,7 @@ export class SinkTrait extends SourceTrait {
                 clearTimeout(timer);
                 timer = null;
             }
-            this.pushUnsubscribe(responseTopic);
+            this.pushSubscriptions.unsubscribe(responseTopic);
             this.pushCallbacks.delete(requestId);
         };
         /*  send request and wait for response before sending chunks  */
@@ -188,31 +188,6 @@ export class SinkTrait extends SourceTrait {
             /*  split buffer into chunks and send them  */
             await sendBufferAsChunks(data, this.options.chunkSize, sendChunk);
     }
-    /*  subscribe to sink push response topic with reference counting  */
-    async pushSubscribe(topic, options = { qos: 2 }) {
-        const count = this.pushSubscriptions.get(topic) ?? 0;
-        this.pushSubscriptions.set(topic, count + 1);
-        if (count === 0) {
-            await this._subscribeTopic(topic, options).catch((err) => {
-                const currentCount = this.pushSubscriptions.get(topic) ?? 0;
-                if (currentCount > 1)
-                    this.pushSubscriptions.set(topic, currentCount - 1);
-                else
-                    this.pushSubscriptions.delete(topic);
-                throw err;
-            });
-        }
-    }
-    /*  unsubscribe from sink push response topic with reference counting  */
-    pushUnsubscribe(topic) {
-        const count = this.pushSubscriptions.get(topic) ?? 0;
-        if (count <= 1) {
-            this.pushSubscriptions.delete(topic);
-            this._unsubscribeTopic(topic).catch(() => { });
-        }
-        else
-            this.pushSubscriptions.set(topic, count - 1);
-    }
     /*  dispatch incoming MQTT message  */
     async _dispatchMessage(topic, parsed) {
         /*  forward dispatching to other traits  */
@@ -329,8 +304,7 @@ export class SinkTrait extends SourceTrait {
                 throw new Error(`sink name mismatch between topic "${topicMatch.name}" and payload "${parsed.name}"`);
             const error = parsed.error;
             const final = parsed.final;
-            const chunk = (parsed.chunk !== undefined && !(parsed.chunk instanceof Uint8Array))
-                ? Uint8Array.from(parsed.chunk) : parsed.chunk;
+            const chunk = parsed.chunk;
             /*  handle chunk on push  */
             const readable = this.pushStreams.get(requestId);
             if (readable !== undefined) {

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

@@ -32,7 +32,5 @@ export declare class SourceTrait<T extends APISchema = APISchema> extends Servic
         buffer: Promise<Uint8Array>;
         meta: Promise<Record<string, any> | undefined>;
     }>;
-    private fetchSubscribe;
-    private fetchUnsubscribe;
     protected _dispatchMessage(topic: string, parsed: any): Promise<void>;
 }

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

@@ -25,7 +25,7 @@
 import { Readable } from "node:stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
-import { streamToBuffer, sendBufferAsChunks, sendStreamAsChunks } from "./mqtt-plus-util";
+import { RefCountedSubscription, streamToBuffer, sendBufferAsChunks, sendStreamAsChunks } from "./mqtt-plus-util";
 import { SourceFetchRequest, SourceFetchResponse, SourceFetchChunk } from "./mqtt-plus-msg";
 import { ServiceTrait } from "./mqtt-plus-service";
 /*  Source Fetch Communication Trait  */
@@ -35,7 +35,7 @@ export class SourceTrait extends ServiceTrait {
         /*  source state  */
         this.sources = new Map();
         this.fetchCallbacks = new Map();
-        this.fetchSubscriptions = new Map();
+        this.fetchSubscriptions = new RefCountedSubscription((topic, options) => this._subscribeTopic(topic, options), (topic) => this._unsubscribeTopic(topic), (err) => this.error(err));
     }
     async source(nameOrConfig, ...args) {
         /*  determine actual parameters  */
@@ -61,9 +61,9 @@ export class SourceTrait extends ServiceTrait {
         if (this.sources.has(name))
             throw new Error(`source: source "${name}" already established`);
         /*  generate the corresponding MQTT topics for broadcast and direct use  */
-        const topic = `$share/${share}/${name}`;
-        const topicReqB = this.options.topicMake(topic, "source-fetch-request");
-        const topicReqD = this.options.topicMake(topic, "source-fetch-request", this.options.id);
+        const topicS = `$share/${share}/${name}`;
+        const topicReqB = this.options.topicMake(topicS, "source-fetch-request");
+        const topicReqD = this.options.topicMake(name, "source-fetch-request", this.options.id);
         /*  subscribe to MQTT topics  */
         await Promise.all([
             this._subscribeTopic(topicReqB, { qos: 2, ...options }),
@@ -120,11 +120,11 @@ export class SourceTrait extends ServiceTrait {
         const responseTopic = this.options.topicMake(name, "source-fetch-response", this.options.id);
         const chunkTopic = this.options.topicMake(name, "source-fetch-chunk", this.options.id);
         await Promise.all([
-            this.fetchSubscribe(responseTopic, { qos: 2 }),
-            this.fetchSubscribe(chunkTopic, { qos: 2 })
+            this.fetchSubscriptions.subscribe(responseTopic, { qos: 2 }),
+            this.fetchSubscriptions.subscribe(chunkTopic, { qos: 2 })
         ]).catch((err) => {
-            this.fetchUnsubscribe(responseTopic);
-            this.fetchUnsubscribe(chunkTopic);
+            this.fetchSubscriptions.unsubscribe(responseTopic);
+            this.fetchSubscriptions.unsubscribe(chunkTopic);
             throw err;
         });
         /*  establish readable for buffering received chunks  */
@@ -157,8 +157,8 @@ export class SourceTrait extends ServiceTrait {
                 clearTimeout(timer);
                 timer = null;
             }
-            this.fetchUnsubscribe(responseTopic);
-            this.fetchUnsubscribe(chunkTopic);
+            this.fetchSubscriptions.unsubscribe(responseTopic);
+            this.fetchSubscriptions.unsubscribe(chunkTopic);
             this.fetchCallbacks.delete(requestId);
             if (resolveMeta)
                 metaResolve?.(undefined);
@@ -213,31 +213,6 @@ export class SourceTrait extends ServiceTrait {
         /*  produce result  */
         return { stream, buffer, meta: metaP };
     }
-    /*  subscribe to fetch topics with reference counting  */
-    async fetchSubscribe(topic, options = { qos: 2 }) {
-        const count = this.fetchSubscriptions.get(topic) ?? 0;
-        this.fetchSubscriptions.set(topic, count + 1);
-        if (count === 0) {
-            await this._subscribeTopic(topic, options).catch((err) => {
-                const currentCount = this.fetchSubscriptions.get(topic) ?? 0;
-                if (currentCount > 1)
-                    this.fetchSubscriptions.set(topic, currentCount - 1);
-                else
-                    this.fetchSubscriptions.delete(topic);
-                throw err;
-            });
-        }
-    }
-    /*  unsubscribe from fetch topics with reference counting  */
-    fetchUnsubscribe(topic) {
-        const count = this.fetchSubscriptions.get(topic) ?? 0;
-        if (count <= 1) {
-            this.fetchSubscriptions.delete(topic);
-            this._unsubscribeTopic(topic).catch(() => { });
-        }
-        else
-            this.fetchSubscriptions.set(topic, count - 1);
-    }
     /*  dispatch message (Source Fetch pattern handling)  */
     async _dispatchMessage(topic, parsed) {
         await super._dispatchMessage(topic, parsed);
@@ -296,7 +271,9 @@ export class SourceTrait extends ServiceTrait {
                     await sendResponse();
                     ackSent = true;
                     /*  dispatch according to data type  */
-                    if (info.stream instanceof Readable)
+                    if (info.stream instanceof Readable && info.buffer instanceof Promise)
+                        throw new Error("handler has set both info.stream and info.buffer");
+                    else if (info.stream instanceof Readable)
                         /*  handle Readable stream result  */
                         await sendStreamAsChunks(info.stream, this.options.chunkSize, sendChunk);
                     else if (info.buffer instanceof Promise)
@@ -342,8 +319,7 @@ export class SourceTrait extends ServiceTrait {
                 throw new Error(`source name mismatch between topic "${topicMatch.name}" and payload "${parsed.name}"`);
             const error = parsed.error;
             const final = parsed.final;
-            const chunk = (parsed.chunk !== undefined && !(parsed.chunk instanceof Uint8Array))
-                ? Uint8Array.from(parsed.chunk) : parsed.chunk;
+            const chunk = parsed.chunk;
             /*  handle chunk on fetch  */
             const handler = this.fetchCallbacks.get(requestId);
             if (handler !== undefined)

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

@@ -4,8 +4,8 @@ declare class LogEvent {
     timestamp: number;
     level: string;
     msg: string | Promise<string>;
-    data?: (Record<string, any> | Record<string, Promise<any>>) | undefined;
-    constructor(timestamp: number, level: string, msg: string | Promise<string>, data?: (Record<string, any> | Record<string, Promise<any>>) | undefined);
+    data?: Record<string, Promise<any> | any> | undefined;
+    constructor(timestamp: number, level: string, msg: string | Promise<string>, data?: Record<string, Promise<any> | any> | undefined);
     resolve(): Promise<void>;
     toString(): string;
 }

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

@@ -85,7 +85,7 @@ export class TraceTrait extends MsgTrait {
             return this._events.emit(...args);
         }
         catch (_err) {
-            /*  ignore error (usually caused by no existing listeners)  */
+            /*  ignore error (caused by emitting "error" without listeners)  */
             return false;
         }
     }