mqtt-plus 1.4.1 → 1.4.3

package/AGENTS.md

@@ -14,17 +14,26 @@ It uses `mqtt` as a peer dependency and builds to ESM, CJS, and UMD formats.
 Commands
 --------
 
+MQTT+ plus uses NPM:
+
+```bash
+npm install             # install dependencies
+```
+
 Build and development commands use STX (`@rse/stx`) as the task runner:
 
 ```bash
-npm start lint          # type-check (tsc), lint (eslint), dead-code check (knip)
-npm start build         # lint + vite bundle (ESM, CJS, UMD into dst-stage2/)
-npm start test          # lint test file + run mocha test suite
-npm start dev           # watch mode (chokidar → rebuild on change)
-npm start sample        # run sample/sample.ts via tsx
-npm start build-doc     # generate SVG diagrams from D2 sources in doc/
+npm start lint          # standard: perform static code analysis
+npm start build         # standard: build everything
+npm start test          # standard: run unit test suite
+
+npm start build-doc     # generate SVG diagrams from D2 sources only
+npm start dev           # development watch mode (rebuild on change)
+npm start sample        # run sample/sample.ts via `tsx`
+
 npm start clean         # remove dst-stage1/ and dst-stage2/
-npm start distclean     # clean + remove node_modules/ and package-lock.json
+npm start distclean     # remove node_modules/ and package-lock.json
+
 ```
 
 Tests require a Mosquitto MQTT broker under run-time; the `mosquitto`
@@ -54,55 +63,57 @@ each extending the previous. The final exported class `MQTTp` sits at
 the bottom of this chain:
 
 ```
-    OptionsTrait   — configuration (id, codec, timeout, chunkSize, chunkCredit, topicMake/topicMatch)
-  ↓ CodecTrait     — CBOR/JSON codec handling
-  ↓ EncodeTrait    — message encoding/validation (valibot schemas)
-  ↓ MsgTrait       — message class definitions and parsing
-  ↓ TraceTrait     — EventEmitter + structured logging
-  ↓ BaseTrait      — MQTT client hookup, subscription management, message routing
-  ↓ MetaTrait      — instance/per-request metadata
-  ↓ AuthTrait      — JWT authentication (jose), role-based access
-  ↓ EventTrait     — Event Emission pattern (event/emit)
-  ↓ ServiceTrait   — Service Call / RPC pattern (service/call)
-  ↓ SourceTrait    — Source Fetch pattern (source/fetch)
-  ↓ SinkTrait      — Sink Push pattern (sink/push)
-  ↓ MQTTp          — final exported class
+    OptionsTrait        — configuration (id, codec, timeout, chunkSize, chunkCredit, topicMake/topicMatch)
+  ↓ CodecTrait          — CBOR/JSON codec handling
+  ↓ EncodeTrait         — message encoding/validation (valibot schemas)
+  ↓ MsgTrait            — message class definitions and parsing
+  ↓ TraceTrait          — EventEmitter + structured logging
+  ↓ BaseTrait           — MQTT client hookup, subscription management, message routing
+  ↓ SubscriptionTrait   — ref-counted MQTT topic subscription management
+  ↓ MetaTrait           — instance/per-request metadata
+  ↓ AuthTrait           — JWT authentication (jose), role-based access
+  ↓ EventTrait          — Event Emission pattern (event/emit)
+  ↓ ServiceTrait        — Service Call / RPC pattern (service/call)
+  ↓ SourceTrait         — Source Fetch pattern (source/fetch)
+  ↓ SinkTrait           — Sink Push pattern (sink/push)
+  ↓ MQTTp               — final exported class
 ```
 
 Each trait lives in its own file: `src/mqtt-plus-<trait>.ts`.
 
 ### Key Source Files
 
-| File                       | Role |
-|----------------------------|------|
-| `src/mqtt-plus.ts`         | Main entry point, re-exports public API types and the final MQTTp class |
-| `src/mqtt-plus-api.ts`     | Branded endpoint type definitions (Event, Service, Source, Sink) and APISchema generic |
-| `src/mqtt-plus-info.ts`    | Info/context object types passed to pattern callbacks (sender metadata, etc.) |
-| `src/mqtt-plus-error.ts`   | Spool (resource cleanup) and run (error handling) utilities |
-| `src/mqtt-plus-util.ts`    | Stream/buffer conversion, RefCountedSubscription, and CreditGate flow control |
-| `src/mqtt-plus-version.ts` | Version utility for converting version strings to numeric format |
-| `src/mqtt-plus-options.ts` | OptionsTrait — configuration (id, codec, timeout, chunkSize, chunkCredit, topicMake/topicMatch) |
-| `src/mqtt-plus-codec.ts`   | CodecTrait — CBOR and JSON codec encoding/decoding |
-| `src/mqtt-plus-encode.ts`  | EncodeTrait — message validation and encoding via valibot schemas |
-| `src/mqtt-plus-msg.ts`     | MsgTrait — message class definitions and parsing logic |
-| `src/mqtt-plus-trace.ts`   | TraceTrait — EventEmitter and structured logging |
-| `src/mqtt-plus-base.ts`    | BaseTrait — MQTT client connection, subscription management, message routing |
-| `src/mqtt-plus-meta.ts`    | MetaTrait — instance and per-request metadata management |
-| `src/mqtt-plus-auth.ts`    | AuthTrait — JWT authentication (jose) and role-based access control |
-| `src/mqtt-plus-event.ts`   | EventTrait — Event Emission communication pattern (event/emit) |
-| `src/mqtt-plus-service.ts` | ServiceTrait — Service Call / RPC communication pattern (service/call) |
-| `src/mqtt-plus-source.ts`  | SourceTrait — Source Fetch communication pattern (source/fetch) |
-| `src/mqtt-plus-sink.ts`    | SinkTrait — Sink Push communication pattern (sink/push) |
+| File                            | Role |
+|---------------------------------|------|
+| `src/mqtt-plus.ts`              | Main entry point, re-exports public API types and the final MQTTp class |
+| `src/mqtt-plus-api.ts`          | Branded endpoint type definitions (Event, Service, Source, Sink) and APISchema generic |
+| `src/mqtt-plus-info.ts`         | Info/context object types passed to pattern callbacks (sender metadata, etc.) |
+| `src/mqtt-plus-error.ts`        | Spool (resource cleanup) and run (error handling) utilities |
+| `src/mqtt-plus-util.ts`         | Stream/buffer conversion, RefCountedSubscription, and CreditGate flow control |
+| `src/mqtt-plus-version.ts`      | Version utility for converting version strings to numeric format |
+| `src/mqtt-plus-options.ts`      | OptionsTrait — configuration (id, codec, timeout, chunkSize, chunkCredit, topicMake/topicMatch) |
+| `src/mqtt-plus-codec.ts`        | CodecTrait — CBOR and JSON codec encoding/decoding |
+| `src/mqtt-plus-encode.ts`       | EncodeTrait — message validation and encoding via valibot schemas |
+| `src/mqtt-plus-msg.ts`          | MsgTrait — message class definitions and parsing logic |
+| `src/mqtt-plus-trace.ts`        | TraceTrait — EventEmitter and structured logging |
+| `src/mqtt-plus-base.ts`         | BaseTrait — MQTT client connection, subscription management, message routing |
+| `src/mqtt-plus-subscription.ts` | SubscriptionTrait — ref-counted MQTT topic subscription management |
+| `src/mqtt-plus-meta.ts`         | MetaTrait — instance and per-request metadata management |
+| `src/mqtt-plus-auth.ts`         | AuthTrait — JWT authentication (jose) and role-based access control |
+| `src/mqtt-plus-event.ts`        | EventTrait — Event Emission communication pattern (event/emit) |
+| `src/mqtt-plus-service.ts`      | ServiceTrait — Service Call / RPC communication pattern (service/call) |
+| `src/mqtt-plus-source.ts`       | SourceTrait — Source Fetch communication pattern (source/fetch) |
+| `src/mqtt-plus-sink.ts`         | SinkTrait — Sink Push communication pattern (sink/push) |
 
 ### Documentation
 
 The `doc/` directory contains D2 diagram sources and generated SVG files
 illustrating the four communication patterns:
 
-- `doc/mqtt-plus-1-event-emission.{d2,svg}`
-- `doc/mqtt-plus-2-service-call.{d2,svg}`
-- `doc/mqtt-plus-3-sink-push.{d2,svg}`
-- `doc/mqtt-plus-4-source-fetch.{d2,svg}`
+- `doc/mqtt-plus-comm-event-emission.{d2,svg}`
+- `doc/mqtt-plus-comm-service-call.{d2,svg}`
+- `doc/mqtt-plus-comm-sink-push.{d2,svg}`
+- `doc/mqtt-plus-comm-source-fetch.{d2,svg}`
 - `doc/theme.d2` — shared D2 theme
 
 Regenerate with `npm start build-doc` (requires the `etc/d2.mts` helper script).

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 ChangeLog
 =========
 
+1.4.3 (2026-02-21)
+------------------
+
+- IMPROVEMENT: allow JWT expirations
+- DOCUMENTATION: document more internals
+
+1.4.2 (2026-02-21)
+------------------
+
+- DOCUMENTATION: add architecture overview
+- CLEANUP: cleanup documentation
+- CLEANUP: simplify internal message handling
+- CLEANUP: simplify internal MQTT topic subscription handling
+
 1.4.1 (2026-02-21)
 ------------------
 

package/README.md

@@ -4,7 +4,7 @@
 MQTT+
 =====
 
-[MQTT](http://mqtt.org/) [Communication Patterns](doc/mqtt-plus-communication.md)
+[MQTT](http://mqtt.org/) [Communication Patterns](doc/mqtt-plus-comm.md)
 
 <p/>
 <img src="https://nodei.co/npm/mqtt-plus.png?downloads=true&stars=true" alt=""/>
@@ -19,7 +19,7 @@ About
 API [MQTT.js](https://www.npmjs.com/package/mqtt), providing
 additional communication patterns with full type safety for
 [MQTT](http://mqtt.org/). Currently the essential
-[communication patterns](doc/mqtt-plus-communication.md)
+[communication patterns](doc/mqtt-plus-comm.md)
 *Event Emission*, *Service Call*, *Sink Push* and *Source Fetch* are
 supported.
 
@@ -117,9 +117,15 @@ mqtt.on("connect", async () => {
 Documentation
 -------------
 
-- [**Communication Patterns**](doc/mqtt-plus-communication.md)
+Main documentation:
+
+- [**Communication Patterns**](doc/mqtt-plus-comm.md)
 - [**Application Programming Interface (API)**](doc/mqtt-plus-api.md)
-- [Extra: Internals](doc/mqtt-plus-internals.md)
+
+Additional auxilliary documentation:
+
+- [Extra: Architecture Overview](doc/mqtt-plus-architecture.md)
+- [Extra: Internal Protocol](doc/mqtt-plus-internals.md)
 - [Extra: Broker Setup](doc/mqtt-plus-broker-setup.md)
 
 Notice
@@ -138,7 +144,7 @@ Notice
 License
 -------
 
-Copyright (c) 2018-2026 Dr. Ralf S. Engelschall (http://engelschall.com/)
+Copyright &copy; 2018-2026 Dr. Ralf S. Engelschall (http://engelschall.com/)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -158,3 +164,4 @@ 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.
+