mqtt-plus 1.4.13 → 1.4.15

package/etc/c8.json

@@ -0,0 +1,16 @@
+{
+    "all":                 false,
+    "reports-dir":         "tst/.c8",
+    "extension":           [ ".ts", ".js" ],
+    "src":                 [ "." ],
+    "include":             [ "src/**/*.ts" ],
+    "exclude":             [ "node_modules/**/*" ],
+    "exclude-after-remap": true,
+    "check-coverage":      true,
+    "statements":          95,
+    "branches":            75,
+    "functions":           95,
+    "lines":               95,
+    "reporter":            [ "text", "html" ],
+    "clean":               true
+}

package/etc/knip.jsonc

@@ -37,6 +37,8 @@
         "tst/mqtt-plus-4-sink.spec.ts",
         "tst/mqtt-plus-5-source.spec.ts",
         "tst/mqtt-plus-6-misc.spec.ts",
+        "tst/mqtt-plus-7-spool.spec.ts",
+        "tst/mqtt-plus-8-run.spec.ts",
         "etc/vite.mts",
         "etc/d2.mts"
     ],
@@ -46,7 +48,11 @@
     ],
     "ignoreDependencies": [
         "shx",
-        "chokidar-cli"
+        "chokidar-cli",
+        "patch-package",
+        "c8",
+        "source-map-support",
+        "open-cli"
     ]
 }
 

package/etc/stx.conf

@@ -22,6 +22,16 @@
 ##  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ##
 
+#   make patches
+patch-make
+    npm shrinkwrap && \
+    patch-package --patch-dir package.d && \
+    shx rm -f npm-shrinkwrap.json
+
+#   (internal) apply patches
+patch-apply
+    patch-package --patch-dir package.d
+
 #   static code analysis (linting)
 lint
     tsc --project etc/tsc.json --noEmit && \
@@ -33,6 +43,11 @@ build : lint
     VITE_BUILD_FORMATS=es,cjs vite --config etc/vite.mts build --mode production
     VITE_BUILD_FORMATS=umd    vite --config etc/vite.mts build --mode production
 
+#   code compilation/transpiling (building, development)
+build-dev : lint
+    VITE_BUILD_FORMATS=es,cjs vite --config etc/vite.mts build --mode development
+    VITE_BUILD_FORMATS=umd    vite --config etc/vite.mts build --mode development
+
 #   documentation compilation
 build-doc
     node etc/d2.mts etc/d2.theme.d2 doc/mqtt-plus-comm-event-emission.d2 doc/mqtt-plus-comm-event-emission.svg
@@ -44,19 +59,36 @@ build-doc
 #   development loop
 dev
     chokidar \
-        "etc/*" "src/*" "tst/*" \
-        -c "npm start build" \
+        "etc/*" "src/*.ts" "tst/*.ts" \
+        -c "npm start build-dev" \
         --debounce 1000 --throttle 1000 \
         --initial --verbose
 
 #   run test suite
 test
-    tsc --project tst/tsc.json --noEmit && \
+    tsc --project tst/tsc.std.json --noEmit && \
+    eslint --config etc/eslint.mts tst/mqtt-plus-0-*.ts tst/*.spec.ts && \
+    if [ ".$MQTT_BROKER" = . ]; then if [ ".`which docker 2>&1`" != . ]; then MQTT_BROKER=mosquitto; fi; else MQTT_BROKER=aedes; fi && \
+    MQTT_BROKER="$MQTT_BROKER" \
+    TSX_TSCONFIG_PATH="tst/tsc.std.json" \
+    NODE_OPTIONS="--import=tsx --trace-warnings -r source-map-support/register" \
+    mocha --require tst/mqtt-plus-0-fixture.ts tst/*.spec.ts
+
+#   run test suite (with code coverage)
+test-cov
+    tsc --project tst/tsc.cov.json --noEmit && \
     eslint --config etc/eslint.mts tst/mqtt-plus-0-*.ts tst/*.spec.ts && \
     if [ ".$MQTT_BROKER" = . ]; then if [ ".`which docker 2>&1`" != . ]; then MQTT_BROKER=mosquitto; fi; else MQTT_BROKER=aedes; fi && \
-    MQTT_BROKER="$MQTT_BROKER" NODE_OPTIONS="--import=tsx --trace-warnings" \
+    MQTT_BROKER="$MQTT_BROKER" \
+    TSX_TSCONFIG_PATH="tst/tsc.cov.json" \
+    NODE_OPTIONS="--import=tsx --trace-warnings -r source-map-support/register" \
+    c8 --config etc/c8.json \
     mocha --require tst/mqtt-plus-0-fixture.ts tst/*.spec.ts
 
+#   open code coverage report
+open-cov
+    open-cli tst/.c8/index.html
+
 #   execute simple sample for testing
 sample
     npx tsx sample/sample.ts

package/etc/tsc.json

@@ -12,7 +12,7 @@
         "resolveJsonModule":       false,
         "isolatedModules":         false,
         "esModuleInterop":         false,
-        "lib":                     [ "es2022", "dom" ],
+        "lib":                     [ "es2022" ],
         "skipLibCheck":            true,
         "declaration":             true,
         "noEmit":                  false,

package/etc/vite.mts

@@ -25,6 +25,7 @@
 import * as Vite             from "vite"
 import { tscPlugin }         from "@wroud/vite-plugin-tsc"
 import { nodePolyfills }     from "vite-plugin-node-polyfills"
+import replace               from "@rollup/plugin-replace"
 import pkg                   from "../package.json"
 
 const formats = process.env.VITE_BUILD_FORMATS ?? "es"
@@ -34,12 +35,12 @@ export default Vite.defineConfig(({ command, mode }) => ({
     appType:  "custom",
     base:     "",
     root:     "",
-    define: {
-        "__VERSION__": `"${pkg.version.replace(/\.\d+$/, "")}"`
-    },
     plugins: [
         tscPlugin({
-            tscArgs:        [ "--build", "etc/tsc.json" ],
+            tscArgs: [
+                "--build", "etc/tsc.json",
+                ...(mode === "development" ? [ "--sourceMap" ] : [])
+            ],
             packageManager: "npx",
             prebuild:       true
         }),
@@ -47,7 +48,12 @@ export default Vite.defineConfig(({ command, mode }) => ({
             include: [ "events", "stream", "buffer" ],
             globals: {},
             protocolImports: true
-        }) ] : [])
+        }) ] : []),
+        replace({
+            "\"0.0\"": `"${pkg.version.replace(/\.\d+$/, "")}"`,
+            delimiters: [ "", "" ],
+            preventAssignment: true
+        })
     ],
     build: {
         rollupOptions: {

package/package.d/vite+8.0.0.patch

@@ -0,0 +1,12 @@
+diff --git a/node_modules/vite/dist/node/chunks/node.js b/node_modules/vite/dist/node/chunks/node.js
+index 8901df3..1f0f344 100644
+--- a/node_modules/vite/dist/node/chunks/node.js
++++ b/node_modules/vite/dist/node/chunks/node.js
+@@ -34548,7 +34548,6 @@ async function runConfigHook(config, plugins, configEnv) {
+ 		const res = await getHookHandler(hook).call(context, conf, configEnv);
+ 		if (res && res !== conf) {
+ 			if (hasBothRollupOptionsAndRolldownOptions(res)) context.warn(`Both \`rollupOptions\` and \`rolldownOptions\` were specified by ${JSON.stringify(p.name)} plugin. \`rollupOptions\` specified by that plugin will be ignored.`);
+-			if (res.esbuild) context.warn(`\`esbuild\` option was specified by ${JSON.stringify(p.name)} plugin. This option is deprecated, please use \`oxc\` instead.`);
+ 			if (res.optimizeDeps?.esbuildOptions) context.warn(`\`optimizeDeps.esbuildOptions\` option was specified by ${JSON.stringify(p.name)} plugin. This option is deprecated, please use \`optimizeDeps.rolldownOptions\` instead.`);
+ 			conf = mergeConfig(conf, res);
+ 		}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":                           "mqtt-plus",
-    "version":                        "1.4.13",
+    "version":                        "1.4.15",
     "description":                    "MQTT Communication Patterns",
     "keywords":                       [   "mqtt",
                                           "event", "emit",
@@ -30,6 +30,7 @@
         "./umd":                      { "types": "./dst-stage1/mqtt-plus.d.ts", "default": "./dst-stage2/mqtt-plus.umd.js" }
     },
     "devDependencies": {
+        "patch-package":              "8.0.1",
         "@rse/stx":                   "1.1.4",
         "shx":                        "0.4.0",
         "eslint":                     "10.0.3",
@@ -43,6 +44,8 @@
         "chai":                       "6.2.2",
         "sinon-chai":                 "4.0.1",
         "sinon":                      "21.0.2",
+        "c8":                         "11.0.0",
+        "source-map-support":         "0.5.21",
         "typescript":                 "5.9.3",
         "typescript-eslint":          "8.57.0",
         "@typescript-eslint/parser":  "8.57.0",
@@ -50,14 +53,16 @@
         "aedes":                      "1.0.1",
         "mosquitto":                  "1.0.2",
         "textframe":                  "1.2.1",
-        "vite":                       "7.3.1",
+        "vite":                       "8.0.0",
         "vite-plugin-node-polyfills": "0.25.0",
+        "@rollup/plugin-replace":     "6.0.3",
         "@wroud/vite-plugin-tsc":     "0.12.2",
         "@terrastruct/d2":            "0.1.33",
         "chokidar-cli":               "3.0.0",
         "chalk":                      "5.6.2",
+        "open-cli":                   "8.0.0",
 
-        "@types/node":                "25.4.0",
+        "@types/node":                "25.5.0",
         "@types/mocha":               "10.0.10",
         "@types/chai":                "5.2.3",
         "@types/sinon-chai":          "4.0.0",
@@ -66,6 +71,9 @@
     "peerDependencies": {
         "mqtt":                       ">=4.0.0"
     },
+    "overrides": {
+        "vite-plugin-node-polyfills": { "vite": ">=7.0.0" }
+    },
     "dependencies": {
         "nanoid":                     "5.1.6",
         "cbor2":                      "2.3.0",
@@ -79,6 +87,7 @@
         "node":                       ">=16.0.0"
     },
     "scripts": {
+        "postinstall":                "npm start patch-apply",
         "prepublishOnly":             "npm start build",
         "start":                      "stx -v4 -c etc/stx.conf",
         "test":                       "npm start test"

package/src/mqtt-plus-sink.ts

@@ -162,6 +162,8 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 /*  utility functions for timeout management  */
                 const pushTimerId = `sink-push-recv:${requestId}`
                 const refreshPushTimeout = () => this.timerRefresh(pushTimerId, () => {
+                    if (streamEnded)
+                        return
                     const stream = this.pushStreams.get(requestId)
                     if (stream !== undefined)
                         stream.destroy(new Error("push stream timeout"))
@@ -201,6 +203,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                         return
                     if (chunkParsed.error !== undefined) {
                         streamEnded = true
+                        clearPushTimeout()
                         readable.destroy(new Error(chunkParsed.error))
                     }
                     else {
@@ -212,6 +215,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                         }
                         if (chunkParsed.final) {
                             streamEnded = true
+                            clearPushTimeout()
                             readable.push(null)
                         }
                     }
@@ -248,6 +252,10 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                 /*  call handler  */
                 await callback(...params, info)
 
+                /*  ensure stream is consumed or destroyed to prevent hang  */
+                if (readable.readableFlowing !== true && !readable.destroyed)
+                    readable.resume()
+
                 /*  await full stream consumption before confirming success  */
                 await streamDone
 
@@ -382,6 +390,7 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
         let remoteError           = false
         let pushAcked             = false
         let pushFinalized         = false
+        let pushDataFinalSent     = false
         let pushFinalizeResolve!: () => void
         let pushFinalizeReject!:  (reason?: any) => void
         const pushFinalize        = new Promise<void>((resolve, reject) => {
@@ -465,6 +474,8 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
                     name, chunk, error, final, this.options.id, receiver)
                 const message = this.codec.encode(chunkMsg)
                 await this.publishToTopic(chunkTopic, message, { qos: 2, ...options })
+                if (error === undefined && final)
+                    pushDataFinalSent = true
             }
 
             /*  iterate over all chunks of the buffer  */
@@ -491,8 +502,9 @@ export class SinkTrait<T extends APISchema = APISchema> extends SourceTrait<T> {
             abortController.abort(error)
 
             /*  send error chunk only if push was acked and error did not originate from receiver
-                (before ack, the sink has no chunk handler yet and will time out on its own)  */
-            if (pushAcked && !remoteError) {
+                (before ack, the sink has no chunk handler yet and will time out on its own;
+                after final data chunk, no additional terminal chunk should be sent)  */
+            if (pushAcked && !remoteError && !pushDataFinalSent) {
                 const chunkTopic = this.options.topicMake(name, "sink-push-request", receiver)
                 const chunkMsg = this.msg.makeSinkPushChunk(requestId,
                     name, undefined, error.message, true, this.options.id, receiver)

package/src/mqtt-plus-source.ts

@@ -142,6 +142,13 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                 await this.publishToTopic(responseTopic, message, { qos: options.qos ?? 2 })
             }
 
+            /*  create a resource spool for request cleanup  */
+            const reqSpool = new Spool()
+            reqSpool.roll(() => {
+                this.onResponse.delete(`source-fetch-credit:${requestId}`)
+                this.sourceControllers.delete(requestId)
+            })
+
             /*  define abort controller and signal  */
             const abortController = new AbortController()
             this.sourceControllers.set(requestId, abortController)
@@ -163,11 +170,11 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                     gate.abort()
                     this.sourceCreditGates.delete(requestId)
                 }
-                this.sourceControllers.delete(requestId)
-                this.onResponse.delete(`source-fetch-credit:${requestId}`)
+                reqSpool.unroll()
             })
             const clearSourceTimeout   = () => this.timerClear(sourceTimerId)
             refreshSourceTimeout()
+            reqSpool.roll(() => { clearSourceTimeout() })
 
             /*  callback for creating and sending a chunk message  */
             const sendChunk = async (
@@ -185,6 +192,7 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
             /*  call the handler callback  */
             let ackSent = false
             let creditGate: CreditGate | undefined
+            let cancelledByFetcher = false
             try {
                 if (topicName !== request.name)
                     throw new Error(`source name mismatch (topic: "${topicName}", payload: "${request.name}")`)
@@ -197,13 +205,19 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                 const initialCredit = request.credit
                 creditGate = (initialCredit !== undefined && initialCredit > 0)
                     ? new CreditGate(initialCredit) : undefined
-                if (creditGate)
+                if (creditGate) {
                     this.sourceCreditGates.set(requestId, creditGate)
+                    reqSpool.roll(() => {
+                        creditGate!.abort()
+                        this.sourceCreditGates.delete(requestId)
+                    })
+                }
 
                 /*  register credit/cancel handler (unconditional for cancel support)  */
                 this.onResponse.set(`source-fetch-credit:${requestId}`, (creditParsed: SourceFetchCredit) => {
                     if (creditParsed.credit === 0) {
                         /*  cancel signal from fetcher  */
+                        cancelledByFetcher = true
                         abortController.abort(new Error(`source fetch "${name}" cancelled by fetcher`))
                         return
                     }
@@ -238,22 +252,19 @@ export class SourceTrait<T extends APISchema = APISchema> extends ServiceTrait<T
                 const error = ensureError(err, `handler for source "${name}" failed`)
                 abortController.abort(error)
 
-                /*  send error as nak response or as error chunk  */
-                this.error(error)
-                if (ackSent)
-                    await sendChunk(undefined, error.message, true).catch(() => {})
-                else
-                    await sendResponse(error.message).catch(() => {})
+                /*  on explicit fetcher cancellation, abort silently without emitting error responses  */
+                if (!cancelledByFetcher) {
+                    /*  send error as nak response or as error chunk  */
+                    this.error(error)
+                    if (ackSent)
+                        await sendChunk(undefined, error.message, true).catch(() => {})
+                    else
+                        await sendResponse(error.message).catch(() => {})
+                }
             }
             finally {
                 /*  cleanup resources  */
-                clearSourceTimeout()
-                if (creditGate) {
-                    creditGate.abort()
-                    this.sourceCreditGates.delete(requestId)
-                }
-                this.sourceControllers.delete(requestId)
-                this.onResponse.delete(`source-fetch-credit:${requestId}`)
+                await reqSpool.unroll()
             }
         })
         spool.roll(() => { this.onRequest.delete(`source-fetch-request:${name}`) })

package/src/mqtt-plus-version.ts

@@ -33,9 +33,8 @@ export const versionToNum = (str: string) => {
     return parseInt(m[1], 10) * 100 + minor
 }
 
-/*  package version (string format, injected)  */
-declare const __VERSION__: string
-export const VERSION = __VERSION__
+/*  package version (string format, overridden)  */
+export const VERSION = "0.0"
 
 /*  package version (numeric format)  */
 export const version = versionToNum(VERSION)

package/tst/.c8/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}