@ptner/mqtt-trans-client 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# @ai-bus/mqtt-trans-client
+
+基于 mqtt.js 的 Node.js MQTT 客户端，支持 MQTT TCP、TLS、WebSocket 和安全 WebSocket URL。
+
+```ts
+import { MqttTransClient } from "@ai-bus/mqtt-trans-client";
+
+const client = new MqttTransClient({
+  url: "wss://device.example/mqtt",
+  clientId: "controller-1",
+  reconnectPeriod: 1_000,
+  onError(error) {
+    console.error(error);
+  },
+});
+
+await client.subscribe("devices/+/status", (topic, payload) => {
+  console.log(topic, payload.toString());
+}, { qos: 1 });
+
+await client.publish("devices/kitchen/command", "start", { qos: 1 });
+await client.close();
+```
+
+连接选项、认证、遗嘱、QoS、重连与 TLS 参数沿用 mqtt.js 的 `IClientOptions`。一个过滤器可注册多个处理器；移除最后一个处理器时客户端会向 broker 取消该订阅。

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { type IClientOptions, type IClientPublishOptions, type IClientSubscribeOptions, type IPublishPacket, type ISubscriptionGrant, type MqttClient } from "mqtt";
+export type MqttMessageHandler = (topic: string, payload: Buffer, packet: IPublishPacket) => void | Promise<void>;
+export interface MqttTransClientOptions extends IClientOptions {
+    url: string;
+    onError?: (error: Error) => void;
+    onReconnect?: () => void;
+    onOffline?: () => void;
+}
+export declare class MqttTransClient {
+    private readonly options;
+    private readonly handlers;
+    private clientValue;
+    private connectPromise;
+    private closePromise;
+    constructor(options: MqttTransClientOptions);
+    get connected(): boolean;
+    get client(): MqttClient | undefined;
+    connect(): Promise<void>;
+    publish(topic: string, payload: string | Buffer | Uint8Array, options?: IClientPublishOptions): Promise<void>;
+    subscribe(filter: string, handler: MqttMessageHandler, options?: IClientSubscribeOptions): Promise<ISubscriptionGrant[]>;
+    unsubscribe(filter: string, handler?: MqttMessageHandler): Promise<void>;
+    close(force?: boolean): Promise<void>;
+    private connectInternal;
+    private closeInternal;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,MAAM,CAAC;AAEd,MAAM,MAAM,kBAAkB,GAAG,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,KACnB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,qBAAa,eAAe;IAMd,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IACvE,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,YAAY,CAA4B;gBAEnB,OAAO,EAAE,sBAAsB;IAE5D,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,MAAM,IAAI,UAAU,GAAG,SAAS,CAEnC;IAED,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlB,OAAO,CACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,EACrC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAQV,SAAS,CACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAiB1B,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9E,KAAK,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnC,OAAO,CAAC,eAAe;YAuCT,aAAa;CAM5B"}

package/dist/index.js

@@ -0,0 +1,126 @@
+import { connect as createMqttClient, } from "mqtt";
+export class MqttTransClient {
+    options;
+    handlers = new Map();
+    clientValue;
+    connectPromise;
+    closePromise;
+    constructor(options) {
+        this.options = options;
+    }
+    get connected() {
+        return this.clientValue?.connected ?? false;
+    }
+    get client() {
+        return this.clientValue;
+    }
+    connect() {
+        if (this.closePromise)
+            throw new Error("Cannot connect a closed MQTT client");
+        this.connectPromise ??= this.connectInternal();
+        return this.connectPromise;
+    }
+    async publish(topic, payload, options) {
+        await this.connect();
+        const mqttPayload = payload instanceof Uint8Array && !Buffer.isBuffer(payload)
+            ? Buffer.from(payload)
+            : payload;
+        await this.clientValue.publishAsync(topic, mqttPayload, options);
+    }
+    async subscribe(filter, handler, options) {
+        await this.connect();
+        const handlers = this.handlers.get(filter) ?? new Set();
+        const isFirstHandler = handlers.size === 0;
+        handlers.add(handler);
+        this.handlers.set(filter, handlers);
+        try {
+            return isFirstHandler
+                ? await this.clientValue.subscribeAsync(filter, options)
+                : [];
+        }
+        catch (error) {
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this.handlers.delete(filter);
+            throw error;
+        }
+    }
+    async unsubscribe(filter, handler) {
+        const handlers = this.handlers.get(filter);
+        if (!handlers)
+            return;
+        if (handler)
+            handlers.delete(handler);
+        else
+            handlers.clear();
+        if (handlers.size > 0)
+            return;
+        this.handlers.delete(filter);
+        if (this.clientValue?.connected)
+            await this.clientValue.unsubscribeAsync(filter);
+    }
+    close(force = false) {
+        this.closePromise ??= this.closeInternal(force);
+        return this.closePromise;
+    }
+    connectInternal() {
+        const { url, onError, onReconnect, onOffline, ...clientOptions } = this.options;
+        const client = createMqttClient(url, clientOptions);
+        this.clientValue = client;
+        client.on("message", (topic, payload, packet) => {
+            for (const [filter, handlers] of this.handlers) {
+                if (!topicMatches(filter, topic))
+                    continue;
+                for (const handler of handlers) {
+                    Promise.resolve(handler(topic, payload, packet)).catch((error) => {
+                        onError?.(toError(error));
+                    });
+                }
+            }
+        });
+        client.on("error", (error) => onError?.(error));
+        client.on("reconnect", () => onReconnect?.());
+        client.on("offline", () => onOffline?.());
+        if (client.connected)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const handleConnect = () => {
+                client.off("error", handleInitialError);
+                resolve();
+            };
+            const handleInitialError = (error) => {
+                client.off("connect", handleConnect);
+                reject(error);
+            };
+            client.once("connect", handleConnect);
+            client.once("error", handleInitialError);
+        });
+    }
+    async closeInternal(force) {
+        const client = this.clientValue;
+        this.handlers.clear();
+        if (client && !client.disconnected)
+            await client.endAsync(force);
+        this.clientValue = undefined;
+    }
+}
+function topicMatches(filter, topic) {
+    if (topic.startsWith("$") && !filter.startsWith("$"))
+        return false;
+    const filterLevels = filter.split("/");
+    const topicLevels = topic.split("/");
+    for (let index = 0; index < filterLevels.length; index += 1) {
+        const filterLevel = filterLevels[index];
+        if (filterLevel === "#")
+            return index === filterLevels.length - 1;
+        if (index >= topicLevels.length)
+            return false;
+        if (filterLevel !== "+" && filterLevel !== topicLevels[index])
+            return false;
+    }
+    return filterLevels.length === topicLevels.length;
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ptner/mqtt-trans-client",
+  "version": "0.1.0",
+  "description": "MQTT and MQTT-over-WebSocket client for Node.js",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "check": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "mqtt": "^5.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT"
+}