@gct-paas/core 0.1.4-dev.1 → 0.1.4-dev.11

package/es/modules/mqtt/constants/mqtt.const.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MQTT 默认连接选项
+ *
+ * @description 连接时未显式指定的选项将使用以下默认值
+ */
+export declare const MQTT_DEFAULT_CONNECT_OPTIONS: {
+    /** 心跳保活间隔（秒），0 表示禁用 */
+    readonly keepalive: 60;
+    /** 连接超时时间（毫秒） */
+    readonly connectTimeout: 30000;
+    /**
+     * 重连间隔（毫秒），由 mqtt.js 内置重连机制使用
+     * 设为 0 可禁用自动重连
+     */
+    readonly reconnectPeriod: 5000;
+    /** 是否清除会话，true 表示每次重连后订阅信息不保留 */
+    readonly clean: false;
+};
+/**
+ * MQTT 连接级事件名称常量
+ */
+export declare const MQTT_CLIENT_EVENT: {
+    /** 成功建立连接 */
+    readonly CONNECT: "connect";
+    /** 重连中 */
+    readonly RECONNECT: "reconnect";
+    /** 连接已断开 */
+    readonly DISCONNECT: "disconnect";
+    /** 发生错误 */
+    readonly ERROR: "error";
+    /** 收到消息 */
+    readonly MESSAGE: "message";
+};

package/es/modules/mqtt/constants/mqtt.const.mjs

@@ -0,0 +1,27 @@
+const MQTT_DEFAULT_CONNECT_OPTIONS = {
+  /** 心跳保活间隔（秒），0 表示禁用 */
+  keepalive: 60,
+  /** 连接超时时间（毫秒） */
+  connectTimeout: 3e4,
+  /**
+   * 重连间隔（毫秒），由 mqtt.js 内置重连机制使用
+   * 设为 0 可禁用自动重连
+   */
+  reconnectPeriod: 5e3,
+  /** 是否清除会话，true 表示每次重连后订阅信息不保留 */
+  clean: false
+};
+const MQTT_CLIENT_EVENT = {
+  /** 成功建立连接 */
+  CONNECT: "connect",
+  /** 重连中 */
+  RECONNECT: "reconnect",
+  /** 连接已断开 */
+  DISCONNECT: "disconnect",
+  /** 发生错误 */
+  ERROR: "error",
+  /** 收到消息 */
+  MESSAGE: "message"
+};
+
+export { MQTT_CLIENT_EVENT, MQTT_DEFAULT_CONNECT_OPTIONS };

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,10 @@
+var MqttConnectionStatus = /* @__PURE__ */ ((MqttConnectionStatus2) => {
+  MqttConnectionStatus2["CONNECTING"] = "connecting";
+  MqttConnectionStatus2["CONNECTED"] = "connected";
+  MqttConnectionStatus2["DISCONNECTING"] = "disconnecting";
+  MqttConnectionStatus2["DISCONNECTED"] = "disconnected";
+  MqttConnectionStatus2["RECONNECTING"] = "reconnecting";
+  return MqttConnectionStatus2;
+})(MqttConnectionStatus || {});
+
+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/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,262 @@
+import mqtt from 'mqtt';
+import { MqttConnectionStatus } from './enums/mqtt-status.enum.mjs';
+import { MQTT_DEFAULT_CONNECT_OPTIONS, MQTT_CLIENT_EVENT } from './constants/mqtt.const.mjs';
+
+class MqttClient {
+  /** 客户端唯一标识 */
+  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) {
+    const topicList = Array.isArray(topics) ? topics : [topics];
+    topicList.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(
+          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());
+    }
+  }
+}
+
+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;
+}