mqtt-plus 1.4.25 → 1.4.27

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

@@ -25,7 +25,7 @@
 import { Readable } from "node:stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
-import { CreditGate, ReadableTee, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields } from "./mqtt-plus-util";
+import { CreditGate, ReadableTee, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields, alignHandlerParams } from "./mqtt-plus-util";
 import { run, Spool, ensureError } from "./mqtt-plus-error";
 import { SourceTrait } from "./mqtt-plus-source";
 /*  Sink Push Trait  */
@@ -115,7 +115,7 @@ export class SinkTrait extends SourceTrait {
                 return;
             /*  determine information  */
             const requestId = request.id;
-            const params = request.params ?? [];
+            const params = alignHandlerParams(request.params ?? [], callback);
             const sender = request.sender;
             const receiver = request.receiver;
             /*  create a resource spool for request cleanup  */
@@ -483,9 +483,14 @@ export class SinkTrait extends SourceTrait {
         /*  ensure stream gets destroyed on abort  */
         if (data instanceof Readable) {
             const stream = data;
+            const noopError = () => { }; /*  prevent unhandled error exception  */
             abortSignal.addEventListener("abort", () => {
-                if (!stream.destroyed)
+                if (!stream.destroyed) {
+                    /*  guard the caller's stream, as it still carries no "error"
+                        listener when the abort precedes the chunk sending phase  */
+                    stream.on("error", noopError);
                     stream.destroy(ensureError(abortSignal.reason));
+                }
             }, { once: true });
         }
         /*  utility function for timeout refresh  */
@@ -521,20 +526,24 @@ export class SinkTrait extends SourceTrait {
             pushFinalizeReject = reject;
         });
         pushFinalize.catch(() => { }); /*  avoid unhandled promise rejection  */
+        /*  abort the push and settle the pending initial/finalize promises  */
+        const failPush = (error) => {
+            abortController.abort(error);
+            if (!pushAcked) {
+                pushInitialSettled = true;
+                pushInitialReject(error);
+            }
+            else if (!pushFinalized) {
+                pushFinalized = true;
+                pushFinalizeReject(error);
+            }
+        };
         /*  lock the responder for this communication  */
         const lockResponder = (kind, sender) => {
             if (sender === undefined || sender === "") {
                 const error = new Error(`received ${kind} without sender`);
                 remoteErrorObject = error;
-                abortController.abort(error);
-                if (!pushAcked) {
-                    pushInitialSettled = true;
-                    pushInitialReject(error);
-                }
-                else if (!pushFinalized) {
-                    pushFinalized = true;
-                    pushFinalizeReject(error);
-                }
+                failPush(error);
                 return false;
             }
             if (responderId === undefined)
@@ -555,15 +564,7 @@ export class SinkTrait extends SourceTrait {
             if (response.name !== name) {
                 const error = new Error(`sink response name mismatch (expected "${name}", got "${response.name}")`);
                 remoteErrorObject = error;
-                abortController.abort(error);
-                if (!pushAcked) {
-                    pushInitialSettled = true;
-                    pushInitialReject(error);
-                }
-                else if (!pushFinalized) {
-                    pushFinalized = true;
-                    pushFinalizeReject(error);
-                }
+                failPush(error);
                 return;
             }
             if (!lockResponder("sink response", response.sender))
@@ -571,15 +572,7 @@ export class SinkTrait extends SourceTrait {
             if (response.error) {
                 const error = new Error(response.error);
                 remoteErrorObject = error;
-                abortController.abort(error);
-                if (!pushAcked) {
-                    pushInitialSettled = true;
-                    pushInitialReject(error);
-                }
-                else if (!pushFinalized) {
-                    pushFinalized = true;
-                    pushFinalizeReject(error);
-                }
+                failPush(error);
             }
             else if (!pushAcked) {
                 initialCredit = response.credit;
@@ -604,15 +597,7 @@ export class SinkTrait extends SourceTrait {
             if (response.name !== name) {
                 const error = new Error(`sink credit name mismatch (expected "${name}", got "${response.name}")`);
                 remoteErrorObject = error;
-                abortController.abort(error);
-                if (!pushAcked) {
-                    pushInitialSettled = true;
-                    pushInitialReject(error);
-                }
-                else if (!pushFinalized) {
-                    pushFinalized = true;
-                    pushFinalizeReject(error);
-                }
+                failPush(error);
                 return;
             }
             if (!lockResponder("sink credit", response.sender))
@@ -621,15 +606,7 @@ export class SinkTrait extends SourceTrait {
                 /*  cancel signal from receiver  */
                 cancelledByReceiver = true;
                 const error = new Error(`push to sink "${name}" cancelled by receiver`);
-                abortController.abort(error);
-                if (!pushAcked) {
-                    pushInitialSettled = true;
-                    pushInitialReject(error);
-                }
-                else if (!pushFinalized) {
-                    pushFinalized = true;
-                    pushFinalizeReject(error);
-                }
+                failPush(error);
                 return;
             }
             if (creditGate !== undefined) {
@@ -641,11 +618,7 @@ export class SinkTrait extends SourceTrait {
                     not granting initial credit during ack  */
                 const error = new Error(`push to sink "${name}" received unsolicited credit (credit-flow disabled)`);
                 remoteErrorObject = error;
-                abortController.abort(error);
-                if (!pushFinalized) {
-                    pushFinalized = true;
-                    pushFinalizeReject(error);
-                }
+                failPush(error);
             }
             else
                 pendingCredit += response.credit;
@@ -751,7 +724,7 @@ export class SinkTrait extends SourceTrait {
                 response from the receiver to be processed, making the
                 error outcome deterministic (only when race is possible)  */
             if (pushAcked && !remoteErrorObject)
-                await new Promise((resolve) => { setImmediate(resolve); });
+                await new Promise((resolve) => { setTimeout(resolve, 0); });
             if (remoteErrorObject)
                 throw remoteErrorObject;
             throw err;

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

@@ -25,7 +25,7 @@
 import { Readable } from "node:stream";
 import { nanoid } from "nanoid";
 /*  internal requirements  */
-import { CreditGate, ReadableTee, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields } from "./mqtt-plus-util";
+import { CreditGate, ReadableTee, sendBufferAsChunks, sendStreamAsChunks, makeMutuallyExclusiveFields, alignHandlerParams } from "./mqtt-plus-util";
 import { run, Spool, ensureError } from "./mqtt-plus-error";
 import { ServiceTrait } from "./mqtt-plus-service";
 /*  Source Fetch Trait  */
@@ -99,7 +99,7 @@ export class SourceTrait extends ServiceTrait {
                 return;
             /*  determine information  */
             const requestId = request.id;
-            const params = request.params ?? [];
+            const params = alignHandlerParams(request.params ?? [], callback);
             const sender = request.sender;
             const receiver = request.receiver;
             /*  create a resource spool for request cleanup  */
@@ -156,16 +156,20 @@ export class SourceTrait extends ServiceTrait {
                 }
             });
             /*  ensure stream gets destroyed on abort  */
-            abortSignal.addEventListener("abort", () => {
-                if (info.stream instanceof Readable && !info.stream.destroyed)
+            const noopError = () => { }; /*  prevent unhandled error exception  */
+            const destroyStream = () => {
+                if (info.stream instanceof Readable && !info.stream.destroyed) {
+                    /*  guard the handler's stream, as it still carries no "error"
+                        listener when the abort precedes the chunk sending phase  */
+                    info.stream.on("error", noopError);
                     info.stream.destroy(ensureError(abortSignal.reason));
-            }, { once: true });
+                }
+            };
+            abortSignal.addEventListener("abort", destroyStream, { once: true });
             /*  safety net: destroy a stream assigned after the abort event fired  */
             reqSpool.roll(() => {
-                if (abortSignal.aborted
-                    && info.stream instanceof Readable
-                    && !info.stream.destroyed)
-                    info.stream.destroy(ensureError(abortSignal.reason));
+                if (abortSignal.aborted)
+                    destroyStream();
             });
             let abortReject;
             const abortPromise = new Promise((_resolve, reject) => {

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

@@ -29,5 +29,6 @@ export declare class ReadableTee extends Readable {
 type SendChunkCallback = (chunk: Uint8Array | undefined, error: string | undefined, final: boolean) => Promise<void>;
 export declare function sendBufferAsChunks(buffer: Uint8Array, chunkSize: number, sendChunk: SendChunkCallback, creditGate?: CreditGate, abortSignal?: AbortSignal): Promise<void>;
 export declare function sendStreamAsChunks(readable: Readable, chunkSize: number, sendChunk: SendChunkCallback, creditGate?: CreditGate, abortSignal?: AbortSignal): Promise<void>;
+export declare function alignHandlerParams(params: any[], handler: unknown): any[];
 export declare function makeMutuallyExclusiveFields<T extends object>(obj: T, f1Name: keyof T & string, f2Name: keyof T & string, onConsumed?: (field: string) => void): void;
 export {};

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

@@ -164,6 +164,8 @@ export class ReadableTee extends Readable {
 }
 /*  utility function for sending a buffer as chunks  */
 export async function sendBufferAsChunks(buffer, chunkSize, sendChunk, creditGate, abortSignal) {
+    if (!(Number.isFinite(chunkSize) && chunkSize > 0))
+        throw new Error("invalid chunk size");
     if (buffer.byteLength === 0)
         await sendChunk(undefined, undefined, true);
     else {
@@ -181,6 +183,8 @@ export async function sendBufferAsChunks(buffer, chunkSize, sendChunk, creditGat
 }
 /*  utility function for sending a Readable stream as chunks  */
 export async function sendStreamAsChunks(readable, chunkSize, sendChunk, creditGate, abortSignal) {
+    if (!(Number.isFinite(chunkSize) && chunkSize > 0))
+        throw new Error("invalid chunk size");
     let pending;
     for await (const raw of readable) {
         if (abortSignal?.aborted)
@@ -211,13 +215,28 @@ export async function sendStreamAsChunks(readable, chunkSize, sendChunk, creditG
     else
         await sendChunk(undefined, undefined, true);
 }
+/*  utility function for aligning received parameters to the parameter arity a
+    handler declares, as the handler receives its trailing "info" argument
+    positionally and a sender omitting trailing optional parameters would
+    otherwise shift that argument into a data parameter slot  */
+export function alignHandlerParams(params, handler) {
+    if (typeof handler !== "function")
+        return params;
+    const arity = handler.length - 1;
+    if (params.length >= arity)
+        return params;
+    return [...params, ...Array(arity - params.length).fill(undefined)];
+}
 /*  utility function for making two object fields mutually exclusive  */
 export function makeMutuallyExclusiveFields(obj, f1Name, f2Name, onConsumed) {
     if (!(typeof obj === "object" && obj !== null))
         throw new Error("invalid object");
     let consumed;
-    const f1Value = obj[f1Name];
-    const f2Value = obj[f2Name];
+    let f1Value = obj[f1Name];
+    let f2Value = obj[f2Name];
+    /*  both fields are intentionally non-enumerable, as any enumeration
+        (object spread, Object.values(), JSON.stringify(), etc) would
+        otherwise consume the first field and then throw on the second  */
     Object.defineProperty(obj, f1Name, {
         get: () => {
             if (consumed === "f2")
@@ -228,7 +247,8 @@ export function makeMutuallyExclusiveFields(obj, f1Name, f2Name, onConsumed) {
             consumed = "f1";
             return f1Value;
         },
-        enumerable: true,
+        set: (value) => { f1Value = value; },
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(obj, f2Name, {
@@ -241,7 +261,8 @@ export function makeMutuallyExclusiveFields(obj, f1Name, f2Name, onConsumed) {
             consumed = "f2";
             return f2Value;
         },
-        enumerable: true,
+        set: (value) => { f2Value = value; },
+        enumerable: false,
         configurable: true
     });
 }

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

@@ -2,6 +2,10 @@ import type { APISchema } from "./mqtt-plus-api";
 import { SinkTrait } from "./mqtt-plus-sink";
 export type * from "./mqtt-plus-api";
 export type * from "./mqtt-plus-info";
-export type * from "./mqtt-plus-version";
 export default class MQTTp<T extends APISchema = APISchema> extends SinkTrait<T> {
+    static readonly VERSION = "0.0";
+    static readonly MIN_VERSION = "0.0";
+    static readonly version: number;
+    static readonly minVersion: number;
+    static readonly versionToNum: (str: string) => number;
 }

package/dst-stage1/mqtt-plus.js

@@ -22,6 +22,15 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 import { SinkTrait } from "./mqtt-plus-sink";
-/*  export the default API class  */
+import { VERSION, MIN_VERSION, version, minVersion, versionToNum } from "./mqtt-plus-version";
+/*  export the default API class (as the sole export of this module, as an
+    additional named run-time export would force CJS/UMD consumers into
+    the awkward "MQTTp.default" access path)  */
 export default class MQTTp extends SinkTrait {
+    /*  expose the version information  */
+    static { this.VERSION = VERSION; }
+    static { this.MIN_VERSION = MIN_VERSION; }
+    static { this.version = version; }
+    static { this.minVersion = minVersion; }
+    static { this.versionToNum = versionToNum; }
 }