@gct-paas/core 0.1.4-dev.9 → 0.1.5-dev.0

package/es/modules/mqtt/enums/mqtt-status.enum.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MQTT 连接状态枚举
+ *
+ * @description 描述 MQTT 客户端当前的连接生命周期状态
+ *
+ * @export
+ * @enum {string}
+ */
+export declare enum MqttConnectionStatus {
+    /** 正在连接中 */
+    CONNECTING = "connecting",
+    /** 已成功连接 */
+    CONNECTED = "connected",
+    /** 正在断开连接中 */
+    DISCONNECTING = "disconnecting",
+    /** 已断开连接 */
+    DISCONNECTED = "disconnected",
+    /** 正在重连中 */
+    RECONNECTING = "reconnecting"
+}

package/es/modules/mqtt/enums/mqtt-status.enum.mjs

@@ -0,0 +1,24 @@
+//#region src/modules/mqtt/enums/mqtt-status.enum.ts
+/**
+* MQTT 连接状态枚举
+*
+* @description 描述 MQTT 客户端当前的连接生命周期状态
+*
+* @export
+* @enum {string}
+*/
+var MqttConnectionStatus = /* @__PURE__ */ function(MqttConnectionStatus) {
+	/** 正在连接中 */
+	MqttConnectionStatus["CONNECTING"] = "connecting";
+	/** 已成功连接 */
+	MqttConnectionStatus["CONNECTED"] = "connected";
+	/** 正在断开连接中 */
+	MqttConnectionStatus["DISCONNECTING"] = "disconnecting";
+	/** 已断开连接 */
+	MqttConnectionStatus["DISCONNECTED"] = "disconnected";
+	/** 正在重连中 */
+	MqttConnectionStatus["RECONNECTING"] = "reconnecting";
+	return MqttConnectionStatus;
+}({});
+//#endregion
+export { MqttConnectionStatus };

package/es/modules/mqtt/index.d.ts

@@ -0,0 +1,5 @@
+export * from './constants/mqtt.const';
+export * from './enums/mqtt-status.enum';
+export * from './interfaces/i-mqtt';
+export * from './mqtt-client';
+export * from './mqtt-manager';

package/es/modules/mqtt/index.mjs

@@ -0,0 +1,4 @@
+import "./constants/mqtt.const.mjs";
+import "./enums/mqtt-status.enum.mjs";
+import "./mqtt-client.mjs";
+import "./mqtt-manager.mjs";

package/es/modules/mqtt/interfaces/i-mqtt.d.ts

@@ -0,0 +1,139 @@
+import { IClientOptions } from 'mqtt';
+import { MqttConnectionStatus } from '../enums/mqtt-status.enum';
+/**
+ * MQTT 消息回调函数类型
+ *
+ * @param topic 消息所属的主题
+ * @param payload 消息内容
+ */
+export type IMqttMessageCallback = (topic: string, payload: Buffer) => void;
+/**
+ * MQTT 客户端事件回调函数类型映射
+ */
+export interface IMqttClientEventMap {
+    /** 连接成功事件 */
+    connect: () => void;
+    /** 断开连接事件 */
+    disconnect: () => void;
+    /** 重连中事件 */
+    reconnect: () => void;
+    /** 连接错误事件 */
+    error: (err: Error) => void;
+}
+/**
+ * MQTT 连接选项接口
+ *
+ * @description 用于创建 MQTT 客户端实例时传入的配置参数
+ *
+ * @interface IMqttConnectOptions
+ */
+export type IMqttConnectOptions = Partial<IClientOptions>;
+/**
+ * MQTT 消息发布选项接口
+ *
+ * @interface IMqttPublishOptions
+ */
+export interface IMqttPublishOptions {
+    /** 服务质量等级：0 最多一次, 1 至少一次, 2 恰好一次，默认 0 */
+    qos?: 0 | 1 | 2;
+    /** 是否保留消息，默认 false */
+    retain?: boolean;
+}
+/**
+ * MQTT 客户端接口
+ *
+ * @description 封装单个 MQTT 连接的操作
+ *
+ * @interface IMqttClient
+ */
+export interface IMqttClient {
+    /** 客户端唯一标识 */
+    readonly instanceId: string;
+    /** 当前连接状态 */
+    readonly status: MqttConnectionStatus;
+    /**
+     * 建立 MQTT 连接
+     */
+    connect(): void;
+    /**
+     * 断开 MQTT 连接
+     */
+    disconnect(): void;
+    /**
+     * 订阅一个或多个主题
+     *
+     * @param topics 主题或主题数组
+     * @param callback 消息回调函数
+     * @returns 取消订阅函数
+     */
+    subscribe(topics: string | string[], callback: IMqttMessageCallback): () => void;
+    /**
+     * 取消订阅一个或多个主题
+     *
+     * @param topics 主题或主题数组
+     */
+    unsubscribe(topics: string | string[]): void;
+    /**
+     * 向指定主题发布消息
+     *
+     * @param topic 目标主题
+     * @param payload 消息内容（字符串或 Buffer）
+     * @param options 发布选项
+     */
+    publish(topic: string, payload: string | Buffer, options?: IMqttPublishOptions): Promise<void>;
+    /**
+     * 监听连接级事件
+     *
+     * @param event 事件名
+     * @param listener 监听函数
+     */
+    on<E extends keyof IMqttClientEventMap>(event: E, listener: IMqttClientEventMap[E]): void;
+    /**
+     * 取消监听连接级事件
+     *
+     * @param event 事件名
+     * @param listener 监听函数
+     */
+    off<E extends keyof IMqttClientEventMap>(event: E, listener: IMqttClientEventMap[E]): void;
+}
+/**
+ * MQTT 管理器接口
+ *
+ * @description 管理多个 MQTT 客户端实例的生命周期
+ *
+ * @interface IMqttManager
+ */
+export interface IMqttManager {
+    /**
+     * 创建并注册一个新的 MQTT 客户端实例
+     *
+     * @param instanceId 实例唯一标识
+     * @param options 连接选项
+     * @returns 已创建的客户端实例
+     * @throws 若 instanceId 已存在则抛出错误
+     */
+    create(instanceId: string, options: IMqttConnectOptions): IMqttClient;
+    /**
+     * 获取已注册的 MQTT 客户端实例
+     *
+     * @param instanceId 实例唯一标识
+     * @returns 客户端实例，若不存在则返回 undefined
+     */
+    get(instanceId: string): IMqttClient | undefined;
+    /**
+     * 判断指定实例是否已存在
+     *
+     * @param instanceId 实例唯一标识
+     */
+    has(instanceId: string): boolean;
+    /**
+     * 销毁指定的 MQTT 客户端实例（会先断开连接）
+     *
+     * @param instanceId 实例唯一标识
+     */
+    destroy(instanceId: string): void;
+    /**
+     * 销毁全部 MQTT 客户端实例
+     */
+    destroyAll(): void;
+}

package/es/modules/mqtt/mqtt-client.d.ts

@@ -0,0 +1,117 @@
+import { MqttConnectionStatus } from './enums/mqtt-status.enum';
+import { IMqttClient, IMqttClientEventMap, IMqttConnectOptions, IMqttMessageCallback, IMqttPublishOptions } from './interfaces/i-mqtt';
+/**
+ * MQTT 客户端
+ *
+ * @description 封装单个 MQTT 连接，提供连接、断连、订阅、取消订阅、发布等功能。
+ * 重连逻辑完全委托给 mqtt.js 内置机制（reconnectPeriod），本类仅负责
+ * 状态同步、消息分发与事件转发。
+ *
+ * @export
+ * @class MqttClient
+ * @implements {IMqttClient}
+ */
+export declare class MqttClient implements IMqttClient {
+    /** 客户端唯一标识 */
+    readonly instanceId: string;
+    /** 连接 URL（即 brokerUrl） */
+    readonly url: string;
+    /** 内部 mqtt.js 客户端实例 */
+    private _client;
+    /** 当前连接状态 */
+    private _status;
+    /** topic -> 消息回调集合 */
+    private readonly _subscriptions;
+    /** 用户注册的连接级事件监听器集合 */
+    private readonly _eventListeners;
+    /** 内部保存的连接选项 */
+    private readonly _options;
+    /**
+     * 创建 MQTT 客户端实例
+     *
+     * @param instanceId 实例唯一标识
+     * @param options 连接选项
+     */
+    constructor(instanceId: string, url: string, options: IMqttConnectOptions);
+    /** 获取当前连接状态 */
+    get status(): MqttConnectionStatus;
+    /**
+     * 建立 MQTT 连接
+     *
+     * @description 若当前已连接或正在连接中则不重复建链
+     */
+    connect(): void;
+    /**
+     * 断开 MQTT 连接
+     *
+     * @description 主动断开并停止 mqtt.js 内置重连
+     */
+    disconnect(): void;
+    /**
+     * 订阅一个或多个主题
+     *
+     * @param topics 主题或主题数组
+     * @param callback 消息回调函数
+     * @returns 取消订阅函数
+     */
+    subscribe(topics: string | string[], callback: IMqttMessageCallback): () => void;
+    /**
+     * 取消订阅一个或多个主题
+     *
+     * @param topics 主题或主题数组
+     */
+    unsubscribe(topics: string | string[]): void;
+    /**
+     * 向指定主题发布消息
+     *
+     * @param topic 目标主题
+     * @param payload 消息内容
+     * @param options 发布选项
+     * @returns Promise，发布成功后 resolve
+     */
+    publish(topic: string, payload: string | Buffer, options?: IMqttPublishOptions): Promise<void>;
+    /**
+     * 监听连接级事件
+     *
+     * @param event 事件名
+     * @param listener 监听函数
+     */
+    on<E extends keyof IMqttClientEventMap>(event: E, listener: IMqttClientEventMap[E]): void;
+    /**
+     * 取消监听连接级事件
+     *
+     * @param event 事件名
+     * @param listener 监听函数
+     */
+    off<E extends keyof IMqttClientEventMap>(event: E, listener: IMqttClientEventMap[E]): void;
+    /**
+     * 绑定 mqtt.js 内部事件
+     *
+     * @private
+     */
+    private _bindClientEvents;
+    /**
+     * 向所有已订阅该 topic 的回调函数分发消息
+     *
+     * @private
+     * @param topic 消息主题
+     * @param payload 消息内容
+     */
+    private _dispatchMessage;
+    /**
+     * MQTT 通配符主题匹配
+     *
+     * @private
+     * @param pattern 订阅时使用的通配符 pattern（支持 + 和 #）
+     * @param topic 实际消息的主题
+     */
+    private _matchTopic;
+    /**
+     * 触发连接级事件
+     *
+     * @private
+     * @param event 事件名
+     * @param arg 可选参数（如 Error）
+     */
+    private _emitEvent;
+}

package/es/modules/mqtt/mqtt-client.mjs

@@ -0,0 +1,229 @@
+import { MQTT_CLIENT_EVENT, MQTT_DEFAULT_CONNECT_OPTIONS } from "./constants/mqtt.const.mjs";
+import { MqttConnectionStatus } from "./enums/mqtt-status.enum.mjs";
+import mqtt from "mqtt";
+//#region src/modules/mqtt/mqtt-client.ts
+/**
+* MQTT 客户端
+*
+* @description 封装单个 MQTT 连接，提供连接、断连、订阅、取消订阅、发布等功能。
+* 重连逻辑完全委托给 mqtt.js 内置机制（reconnectPeriod），本类仅负责
+* 状态同步、消息分发与事件转发。
+*
+* @export
+* @class MqttClient
+* @implements {IMqttClient}
+*/
+var MqttClient = class {
+	/** 客户端唯一标识 */
+	instanceId;
+	/** 连接 URL（即 brokerUrl） */
+	url;
+	/** 内部 mqtt.js 客户端实例 */
+	_client = null;
+	/** 当前连接状态 */
+	_status = MqttConnectionStatus.DISCONNECTED;
+	/** topic -> 消息回调集合 */
+	_subscriptions = /* @__PURE__ */ new Map();
+	/** 用户注册的连接级事件监听器集合 */
+	_eventListeners = {
+		connect: /* @__PURE__ */ new Set(),
+		disconnect: /* @__PURE__ */ new Set(),
+		reconnect: /* @__PURE__ */ new Set(),
+		error: /* @__PURE__ */ new Set()
+	};
+	/** 内部保存的连接选项 */
+	_options;
+	/**
+	* 创建 MQTT 客户端实例
+	*
+	* @param instanceId 实例唯一标识
+	* @param options 连接选项
+	*/
+	constructor(instanceId, url, options) {
+		if (!instanceId) throw new Error("MqttClient: instanceId 不能为空");
+		if (!url) throw new Error("MqttClient: url 不能为空");
+		if (!options.clientId) throw new Error("MqttClient: options.clientId 不能为空");
+		this.instanceId = instanceId;
+		this.url = url;
+		this._options = {
+			...options,
+			keepalive: options.keepalive ?? MQTT_DEFAULT_CONNECT_OPTIONS.keepalive,
+			connectTimeout: options.connectTimeout ?? MQTT_DEFAULT_CONNECT_OPTIONS.connectTimeout,
+			reconnectPeriod: options.reconnectPeriod ?? MQTT_DEFAULT_CONNECT_OPTIONS.reconnectPeriod,
+			clean: options.clean ?? MQTT_DEFAULT_CONNECT_OPTIONS.clean
+		};
+	}
+	/** 获取当前连接状态 */
+	get status() {
+		return this._status;
+	}
+	/**
+	* 建立 MQTT 连接
+	*
+	* @description 若当前已连接或正在连接中则不重复建链
+	*/
+	connect() {
+		if (this._status === MqttConnectionStatus.CONNECTED || this._status === MqttConnectionStatus.CONNECTING) return;
+		this._status = MqttConnectionStatus.CONNECTING;
+		this._client = mqtt.connect(this.url, this._options);
+		this._bindClientEvents();
+	}
+	/**
+	* 断开 MQTT 连接
+	*
+	* @description 主动断开并停止 mqtt.js 内置重连
+	*/
+	disconnect() {
+		if (!this._client) {
+			this._status = MqttConnectionStatus.DISCONNECTED;
+			return;
+		}
+		this._status = MqttConnectionStatus.DISCONNECTING;
+		this._client.end(false, {}, () => {
+			this._status = MqttConnectionStatus.DISCONNECTED;
+			this._emitEvent(MQTT_CLIENT_EVENT.DISCONNECT);
+		});
+	}
+	/**
+	* 订阅一个或多个主题
+	*
+	* @param topics 主题或主题数组
+	* @param callback 消息回调函数
+	* @returns 取消订阅函数
+	*/
+	subscribe(topics, callback) {
+		const topicList = Array.isArray(topics) ? topics : [topics];
+		topicList.forEach((topic) => {
+			if (!this._subscriptions.has(topic)) {
+				this._subscriptions.set(topic, /* @__PURE__ */ new Set());
+				if (this._client && this._status === MqttConnectionStatus.CONNECTED) this._client.subscribe(topic);
+			}
+			this._subscriptions.get(topic).add(callback);
+		});
+		return () => this.unsubscribe(topicList);
+	}
+	/**
+	* 取消订阅一个或多个主题
+	*
+	* @param topics 主题或主题数组
+	*/
+	unsubscribe(topics) {
+		(Array.isArray(topics) ? topics : [topics]).forEach((topic) => {
+			this._subscriptions.delete(topic);
+			if (this._client && this._status === MqttConnectionStatus.CONNECTED) this._client.unsubscribe(topic);
+		});
+	}
+	/**
+	* 向指定主题发布消息
+	*
+	* @param topic 目标主题
+	* @param payload 消息内容
+	* @param options 发布选项
+	* @returns Promise，发布成功后 resolve
+	*/
+	publish(topic, payload, options) {
+		return new Promise((resolve, reject) => {
+			if (!this._client || this._status !== MqttConnectionStatus.CONNECTED) {
+				reject(/* @__PURE__ */ new Error(`MqttClient [${this.instanceId}]: 尚未建立连接，无法发布消息`));
+				return;
+			}
+			const publishOptions = {
+				qos: options?.qos ?? 0,
+				retain: options?.retain ?? false
+			};
+			this._client.publish(topic, payload, publishOptions, (err) => {
+				if (err) reject(err);
+				else resolve();
+			});
+		});
+	}
+	/**
+	* 监听连接级事件
+	*
+	* @param event 事件名
+	* @param listener 监听函数
+	*/
+	on(event, listener) {
+		this._eventListeners[event].add(listener);
+	}
+	/**
+	* 取消监听连接级事件
+	*
+	* @param event 事件名
+	* @param listener 监听函数
+	*/
+	off(event, listener) {
+		this._eventListeners[event].delete(listener);
+	}
+	/**
+	* 绑定 mqtt.js 内部事件
+	*
+	* @private
+	*/
+	_bindClientEvents() {
+		if (!this._client) return;
+		this._client.on("connect", (_connack) => {
+			this._status = MqttConnectionStatus.CONNECTED;
+			this._emitEvent(MQTT_CLIENT_EVENT.CONNECT);
+		});
+		this._client.on("reconnect", () => {
+			this._status = MqttConnectionStatus.RECONNECTING;
+			this._emitEvent(MQTT_CLIENT_EVENT.RECONNECT);
+		});
+		this._client.on("error", (err) => {
+			this._emitEvent(MQTT_CLIENT_EVENT.ERROR, err);
+		});
+		this._client.on("close", () => {
+			if (this._status !== MqttConnectionStatus.DISCONNECTING) this._status = MqttConnectionStatus.DISCONNECTED;
+		});
+		this._client.on("message", (topic, payload) => {
+			this._dispatchMessage(topic, payload);
+		});
+	}
+	/**
+	* 向所有已订阅该 topic 的回调函数分发消息
+	*
+	* @private
+	* @param topic 消息主题
+	* @param payload 消息内容
+	*/
+	_dispatchMessage(topic, payload) {
+		const callbacks = this._subscriptions.get(topic);
+		if (callbacks) callbacks.forEach((cb) => cb(topic, payload));
+		this._subscriptions.forEach((cbSet, pattern) => {
+			if (pattern !== topic && this._matchTopic(pattern, topic)) cbSet.forEach((cb) => cb(topic, payload));
+		});
+	}
+	/**
+	* MQTT 通配符主题匹配
+	*
+	* @private
+	* @param pattern 订阅时使用的通配符 pattern（支持 + 和 #）
+	* @param topic 实际消息的主题
+	*/
+	_matchTopic(pattern, topic) {
+		const patternSegments = pattern.split("/");
+		const topicSegments = topic.split("/");
+		for (let i = 0; i < patternSegments.length; i++) {
+			const p = patternSegments[i];
+			if (p === "#") return true;
+			if (p !== "+" && p !== topicSegments[i]) return false;
+		}
+		return patternSegments.length === topicSegments.length;
+	}
+	/**
+	* 触发连接级事件
+	*
+	* @private
+	* @param event 事件名
+	* @param arg 可选参数（如 Error）
+	*/
+	_emitEvent(event, arg) {
+		if (event === MQTT_CLIENT_EVENT.ERROR && arg) this._eventListeners.error.forEach((fn) => fn(arg));
+		else if (event === MQTT_CLIENT_EVENT.CONNECT) this._eventListeners.connect.forEach((fn) => fn());
+		else if (event === MQTT_CLIENT_EVENT.DISCONNECT) this._eventListeners.disconnect.forEach((fn) => fn());
+		else if (event === MQTT_CLIENT_EVENT.RECONNECT) this._eventListeners.reconnect.forEach((fn) => fn());
+	}
+};
+//#endregion
+export { MqttClient };

package/es/modules/mqtt/mqtt-manager.d.ts

@@ -0,0 +1,87 @@
+import { IMqttClient, IMqttConnectOptions, IMqttManager } from './interfaces/i-mqtt';
+/**
+ * MQTT 实例管理中心
+ *
+ * @description 管理多个 MQTT 客户端实例的生命周期，提供创建、获取、销毁等操作。
+ * 该类通常作为全局单例挂载在 window._gct.mqtt 上，供各业务模块共享使用。
+ *
+ * @example
+ * ```typescript
+ * // 获取全局管理器
+ * const manager = window._gct.mqtt;
+ *
+ * // 创建一个 MQTT 客户端实例
+ * const client = manager.create('device-001', {
+ *   brokerUrl: 'ws://localhost:8083/mqtt',
+ *   username: 'admin',
+ *   password: 'password',
+ * });
+ *
+ * // 连接
+ * client.connect();
+ *
+ * // 订阅
+ * const unsubscribe = client.subscribe('sensor/+/temperature', (topic, payload) => {
+ *   console.log(topic, payload.toString());
+ * });
+ *
+ * // 发布
+ * await client.publish('sensor/001/cmd', 'on');
+ *
+ * // 取消订阅
+ * unsubscribe();
+ *
+ * // 销毁实例
+ * manager.destroy('device-001');
+ * ```
+ *
+ * @export
+ * @class MqttManager
+ * @implements {IMqttManager}
+ */
+export declare class MqttManager implements IMqttManager {
+    /**
+     * 管理器唯一标识
+     *
+     * @private
+     */
+    private readonly uuid;
+    /** 已注册的 MQTT 客户端实例注册表，key 为 instanceId */
+    private readonly _clients;
+    /**
+     * 创建并注册一个新的 MQTT 客户端实例
+     *
+     * @param instanceId 实例唯一标识，全局唯一
+     * @param options MQTT 连接选项
+     * @returns 创建的 MqttClient 实例
+     * @throws 若 instanceId 已存在则抛出错误
+     */
+    create(instanceId: string, options: IMqttConnectOptions): IMqttClient;
+    /**
+     * 获取已注册的 MQTT 客户端实例
+     *
+     * @param instanceId 实例唯一标识
+     * @returns 客户端实例，若不存在则返回 undefined
+     */
+    get(instanceId: string): IMqttClient | undefined;
+    /**
+     * 判断指定实例是否已存在
+     *
+     * @param instanceId 实例唯一标识
+     * @returns 是否存在
+     */
+    has(instanceId: string): boolean;
+    /**
+     * 销毁指定的 MQTT 客户端实例
+     *
+     * @description 会先断开连接，再从管理器中移除
+     * @param instanceId 实例唯一标识
+     */
+    destroy(instanceId: string): void;
+    /**
+     * 销毁全部 MQTT 客户端实例
+     *
+     * @description 依次断开所有连接并清空注册表
+     */
+    destroyAll(): void;
+}