mqtt-plus 0.9.0

package/etc/logo.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 805 283">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #369;
+      }
+    </style>
+  </defs>
+  <path class="cls-1" d="M728.126,19.9971v60.9019h58.3037v31.1724h-58.3037v61.4795h-32.6162v-61.4795h-58.3047v-31.1724h58.3047V19.9971h32.6162Z"/>
+  <path class="cls-1" d="M429.6187,268.3086c-30.5801-9.0498-54.2949-18.7227-84.251-31.5166-4.9927-2.1846-10.2974-3.1201-15.2905-3.4326-46.4941-3.4326-91.7402-37.7568-91.7402-107.0303,0-61.4727,39.3174-110.4629,105.1582-110.4629,67.0894,0,101.4141,50.5508,101.4141,106.0938,0,45.2461-20.9072,78.6348-45.2466,91.1172v1.248c14.042,4.6807,29.9561,7.8008,45.8706,11.2334l-15.9146,42.75ZM342.2471,188.7373c27.1475,0,43.062-26.2119,43.062-64.5928,0-36.8213-16.2266-63.6562-43.686-63.6562-26.5234,0-43.686,26.835-43.686,63.9688-.312,38.0684,16.5381,64.2803,43.686,64.2803h.624Z"/>
+  <path d="M228.4019,126.7417c0-26.8698,7.5125-51.3542,21.4678-70.4055l-1.8526-36.7254h-73.9541l-15.9141,56.1675c-6.2407,22.1553-13.106,51.7993-19.0347,77.3867h-.936c-4.3687-25.5874-10.6094-53.6714-16.5381-77.0747l-13.73-56.4795H32.084l-13.106,210.3164h51.7988l3.4326-75.2021c.936-24.0273,1.8721-55.2314,3.1206-84.8755h.624c4.9927,28.708,11.2334,59.9121,16.8501,82.6909l17.4746,73.0181h43.9976l20.9072-73.3301c6.8647-23.0908,15.6021-54.6069,22.1548-82.3789h.936c0,32.7642.312,60.8481,1.2485,84.8755l2.4961,75.2021h54.6074l-1.2318-24.4186c-17.433-17.6805-28.9928-43.7579-28.9928-78.767Z"/>
+  <g>
+    <polygon points="568.0386 19.6108 528.2663 19.6108 547.709 67.041 568.0386 67.041 568.9517 67.041 568.9517 229.9272 625.4312 229.9272 625.4312 67.041 680.0386 67.041 680.0386 19.6108 568.0386 19.6108"/>
+    <path d="M516.378,19.6108h-113.0977v6.1184c18.5046,9.1639,32.2805,23.7489,41.2421,41.3118h12.4293v52.0095c.0134.7731.0225,1.5469.0225,2.3221,0,.5229-.0169,1.0361-.0225,1.5558v101.9045c.2156.0464.4308.0918.6465.1383l-.6465,1.7366v3.2195h56.4795V67.041h22.3896l-19.4427-47.4302Z"/>
+  </g>
+</svg>

package/etc/stx.conf

@@ -0,0 +1,47 @@
+##
+##  MQTT+ -- MQTT Communication Patterns
+##  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+##
+##  Permission is hereby granted, free of charge, to any person obtaining
+##  a copy of this software and associated documentation files (the
+##  "Software"), to deal in the Software without restriction, including
+##  without limitation the rights to use, copy, modify, merge, publish,
+##  distribute, sublicense, and/or sell copies of the Software, and to
+##  permit persons to whom the Software is furnished to do so, subject to
+##  the following conditions:
+##
+##  The above copyright notice and this permission notice shall be included
+##  in all copies or substantial portions of the Software.
+##
+##  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+##  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+##  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+##  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+##  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+##  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+##  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+##
+
+#   static code analysis (linting)
+lint
+    tsc --project etc/tsc.json --noEmit && \
+    eslint --config etc/eslint.mts src/*.ts sample/*.ts
+
+#   code compilation/transpiling (building)
+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
+
+#   execute simple sample for testing
+test
+    npx tsx sample/sample.ts
+
+#   cleanup (built artifacts)
+clean
+    shx rm -rf dst
+
+#   cleanup (bootstrap artifacts)
+distclean : clean
+    shx rm -f package-lock.json
+    shx rm -rf node_modules
+

package/etc/tsc.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        "outDir":                  "../dst-stage1",
+        "target":                  "es2022",
+        "module":                  "ESNext",
+        "moduleResolution":        "Bundler",
+        "useDefineForClassFields": false,
+        "composite":               false,
+        "strict":                  true,
+        "strictFunctionTypes":     true,
+        "resolveJsonModule":       false,
+        "isolatedModules":         false,
+        "esModuleInterop":         false,
+        "lib":                     [ "es2022", "dom" ],
+        "skipLibCheck":            true,
+        "declaration":             true,
+        "noEmit":                  false,
+        "rootDir":                 "../src"
+    },
+    "include": [
+        "../src/**/*.ts",
+        "../src/**/*.d.ts"
+    ],
+    "exclude": [
+        "../node_modules"
+    ]
+}

package/etc/tsc.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/mqtt-plus-codec.ts","../src/mqtt-plus-msg.ts","../src/mqtt-plus.ts"],"version":"5.9.3"}

package/etc/vite.mts

@@ -0,0 +1,66 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+import * as Vite             from "vite"
+import { tscPlugin }         from "@wroud/vite-plugin-tsc"
+import { viteSingleFile }    from "vite-plugin-singlefile"
+import { nodePolyfills }     from "vite-plugin-node-polyfills"
+
+const formats = process.env.VITE_BUILD_FORMATS ?? "esm"
+
+export default Vite.defineConfig(({ command, mode }) => ({
+    logLevel: "info",
+    appType:  "custom",
+    base:     "",
+    root:     "",
+    plugins: [
+        tscPlugin({
+            tscArgs:        [ "--project", "etc/tsc.json" ],
+            packageManager: "npx",
+            prebuild:       true
+        }),
+        ...(formats === "umd" ? [ nodePolyfills() ] : []),
+        viteSingleFile()
+    ],
+    build: {
+        rollupOptions: {
+            external: formats === "umd" ? [] : [ "stream" ]
+        },
+        lib: {
+            entry:    "dst-stage1/mqtt-plus.js",
+            formats:  formats.split(","),
+            name:     "MQTTp",
+            fileName: (format) => `mqtt-plus.${format === "es" ? "esm" : format}.js`
+        },
+        target:                 formats === "umd" ? "es2022" : "node20",
+        outDir:                 "dst-stage2",
+        assetsDir:              "",
+        emptyOutDir:            (mode === "production") && formats !== "umd",
+        chunkSizeWarningLimit:  5000,
+        assetsInlineLimit:      0,
+        sourcemap:              (mode === "development"),
+        minify:                 (mode === "production") && formats === "umd",
+        reportCompressedSize:   (mode === "production")
+    }
+}))

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name":                           "mqtt-plus",
+    "version":                        "0.9.0",
+    "description":                    "MQTT Communication Patterns",
+    "keywords":                       [ "mqtt", "event", "service", "rpc", "request", "response" ],
+    "license":                        "MIT",
+    "repository":                     { "type": "git", "url": "git+https://github.com/rse/mqtt-plus.git" },
+    "homepage":                       "https://github.com/rse/mqtt-plus",
+    "bugs":                           "https://github.com/rse/mqtt-plus/issues",
+    "author": {
+        "name":                       "Dr. Ralf S. Engelschall",
+        "email":                      "rse@engelschall.com",
+        "url":                        "http://engelschall.com"
+    },
+    "type":                           "module",
+    "types":                          "./dst-stage1/mqtt-plus.d.ts",
+    "module":                         "./dst-stage2/mqtt-plus.esm.js",
+    "main":                           "./dst-stage2/mqtt-plus.cjs.js",
+    "browser":                        "./dst-stage2/mqtt-plus.umd.js",
+    "exports": {
+        ".": {
+            "import":                 { "types": "./dst-stage1/mqtt-plus.d.ts", "default": "./dst-stage2/mqtt-plus.esm.js" },
+            "require":                { "types": "./dst-stage1/mqtt-plus.d.ts", "default": "./dst-stage2/mqtt-plus.cjs.js" }
+        }
+    },
+    "devDependencies": {
+        "@rse/stx":                   "1.1.4",
+        "shx":                        "0.4.0",
+        "eslint":                     "9.39.2",
+        "eslint-plugin-node":         "11.1.0",
+        "globals":                    "17.0.0",
+        "@eslint/js":                 "9.39.2",
+        "@eslint/eslintrc":           "3.3.3",
+        "jiti":                       "2.6.1",
+        "tsx":                        "4.21.0",
+        "typescript":                 "5.9.3",
+        "typescript-eslint":          "8.51.0",
+        "@typescript-eslint/parser":  "8.51.0",
+        "mqtt":                       "5.14.1",
+        "vite":                       "7.3.0",
+        "vite-plugin-singlefile":     "2.3.0",
+        "vite-plugin-node-polyfills": "0.24.0",
+        "@wroud/vite-plugin-tsc":     "0.12.2"
+    },
+    "peerDependencies": {
+        "mqtt":                       ">=4.0.0"
+    },
+    "dependencies": {
+        "nanoid":                     "5.1.6",
+        "cbor":                       "10.0.11"
+    },
+    "engines": {
+        "node":                       ">=16.0.0"
+    },
+    "scripts": {
+        "prepublishOnly":             "npm start build",
+        "start":                      "stx -v4 -c etc/stx.conf",
+        "test":                       "npm start test"
+    }
+}

package/src/mqtt-plus-codec.ts

@@ -0,0 +1,59 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+import CBOR from "cbor"
+
+/*  the encoder/decoder abstraction  */
+export default class Codec {
+    constructor (private type: "cbor" | "json") {}
+    encode (data: unknown): Buffer | string {
+        let result: Buffer | string
+        if (this.type === "cbor") {
+            try { result = CBOR.encode(data) }
+            catch (_ex) { throw new Error("failed to encode CBOR format") }
+        }
+        else if (this.type === "json") {
+            try { result = JSON.stringify(data) }
+            catch (_ex) { throw new Error("failed to encode JSON format") }
+        }
+        else
+            throw new Error("invalid format")
+        return result
+    }
+    decode (data: Buffer | string): unknown {
+        let result: unknown
+        if (this.type === "cbor" && typeof data === "object" && data instanceof Buffer) {
+            try { result = CBOR.decode(data) }
+            catch (_ex) { throw new Error("failed to decode CBOR format") }
+        }
+        else if (this.type === "json" && typeof data === "string") {
+            try { result = JSON.parse(data) }
+            catch (_ex) { throw new Error("failed to decode JSON format") }
+        }
+        else
+            throw new Error("invalid format or wrong data type")
+        return result
+    }
+}
+

package/src/mqtt-plus-msg.ts

@@ -0,0 +1,171 @@
+/*
+**  MQTT+ -- MQTT Communication Patterns
+**  Copyright (c) 2018-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**
+**  Permission is hereby granted, free of charge, to any person obtaining
+**  a copy of this software and associated documentation files (the
+**  "Software"), to deal in the Software without restriction, including
+**  without limitation the rights to use, copy, modify, merge, publish,
+**  distribute, sublicense, and/or sell copies of the Software, and to
+**  permit persons to whom the Software is furnished to do so, subject to
+**  the following conditions:
+**
+**  The above copyright notice and this permission notice shall be included
+**  in all copies or substantial portions of the Software.
+**
+**  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+**  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+**  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+**  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+**  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+**  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+**  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/*  base class  */
+export class Base {
+    constructor (
+        public id:        string,
+        public sender?:   string,
+        public receiver?: string
+    ) {}
+}
+
+/*  event emission  */
+export class EventEmission extends Base {
+    constructor (
+        id:             string,
+        public event:   string,
+        public params?: any[],
+        sender?:        string,
+        receiver?:      string,
+    ) { super(id, sender, receiver) }
+}
+
+/*  service request  */
+export class ServiceRequest extends Base {
+    constructor (
+        id:             string,
+        public service: string,
+        public params?: any[],
+        sender?:        string,
+        receiver?:      string,
+    ) { super(id, sender, receiver) }
+}
+
+/*  service response success  */
+export class ServiceResponseSuccess extends Base {
+    constructor (
+        id:             string,
+        public result:  any,
+        sender?:        string,
+        receiver?:      string
+    ) { super(id, sender, receiver) }
+}
+
+/*  service response error  */
+export class ServiceResponseError extends Base {
+    constructor (
+        id:             string,
+        public error:   string,
+        sender?:        string,
+        receiver?:      string
+    ) { super(id, sender, receiver) }
+}
+
+/*  utility class  */
+export default class Msg {
+    /*  factory for event emission  */
+    makeEventEmission (
+        id:             string,
+        event:          string,
+        params?:        any[],
+        sender?:        string,
+        receiver?:      string
+    ): EventEmission {
+        return new EventEmission(id, event, params, sender, receiver)
+    }
+
+    /*  factory for service request  */
+    makeServiceRequest (
+        id:             string,
+        service:        string,
+        params?:        any[],
+        sender?:        string,
+        receiver?:      string
+    ): ServiceRequest {
+        return new ServiceRequest(id, service, params, sender, receiver)
+    }
+
+    /*  factory for service response success  */
+    makeServiceResponseSuccess (
+        id:             string,
+        result:         any,
+        sender?:        string,
+        receiver?:      string
+    ): ServiceResponseSuccess {
+        return new ServiceResponseSuccess(id, result, sender, receiver)
+    }
+
+    /*  factory for service response error  */
+    makeServiceResponseError (
+        id:             string,
+        error:          string,
+        sender?:        string,
+        receiver?:      string
+    ): ServiceResponseError {
+        return new ServiceResponseError(id, error, sender, receiver)
+    }
+
+    /*  parse any object into typed object  */
+    parse (obj: any): EventEmission | ServiceRequest | ServiceResponseSuccess | ServiceResponseError {
+        if (typeof obj !== "object" || obj === null)
+            throw new Error("invalid argument: not an object")
+
+        /*  validate common fields  */
+        if (!("id" in obj) || typeof obj.id !== "string")
+            throw new Error("invalid object: missing or invalid \"id\" field")
+        if ("sender" in obj && typeof obj.sender !== "string")
+            throw new Error("invalid object: invalid \"sender\" field")
+        if ("receiver" in obj && typeof obj.sender !== "string")
+            throw new Error("invalid object: invalid \"receiver\" field")
+
+        /*  dispatch according to type indication by field  */
+        const anyFieldsExcept = (obj: object, allowed: string[]) =>
+            Object.keys(obj).some((key) => !allowed.includes(key))
+        if ("event" in obj) {
+            /*  detect and parse event emission  */
+            if (typeof obj.event !== "string")
+                throw new Error("invalid EventEmission object: \"event\" field must be a string")
+            if (anyFieldsExcept(obj, [ "type", "id", "event", "params", "sender", "receiver" ]))
+                throw new Error("invalid EventEmission object: contains unknown fields")
+            if (obj.params !== undefined && (typeof obj.params !== "object" || !Array.isArray(obj.params)))
+                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)
+        }
+        else if ("service" in obj) {
+            /*  detect and parse service request  */
+            if (typeof obj.service !== "string")
+                throw new Error("invalid ServiceRequest object: \"service\" field must be a string")
+            if (anyFieldsExcept(obj, [ "type", "id", "service", "params", "sender", "receiver" ]))
+                throw new Error("invalid ServiceRequest object: contains unknown fields")
+            if (obj.params !== undefined && (typeof obj.params !== "object" || !Array.isArray(obj.params)))
+                throw new Error("invalid ServiceRequest object: \"params\" field must be an array")
+            return this.makeServiceRequest(obj.id, obj.service, obj.params, obj.sender, obj.receiver)
+        }
+        else if ("result" in obj) {
+            /*  detect and parse service response success  */
+            if (anyFieldsExcept(obj, [ "type", "id", "result", "sender", "receiver" ]))
+                throw new Error("invalid ServiceResponseSuccess object: contains unknown fields")
+            return this.makeServiceResponseSuccess(obj.id, obj.result, obj.sender, obj.receiver)
+        }
+        else if ("error" in obj) {
+            /*  detect and parse service response error  */
+            if (anyFieldsExcept(obj, [ "type", "id", "error", "sender", "receiver" ]))
+                throw new Error("invalid ServiceResponseError object: contains unknown fields")
+            return this.makeServiceResponseError(obj.id, obj.error, obj.sender, obj.receiver)
+        }
+        else
+            throw new Error("invalid object: not of any known type")
+    }
+}