@ray-js/wechat-mqtt 0.1.2-beta-2 → 0.1.3-beta-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/wechat-mqtt",
-  "version": "0.1.2-beta-2",
+  "version": "0.1.3-beta-1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -25,8 +25,8 @@
     }
   },
   "dependencies": {
-    "@ray-js/wechat-helper": "^0.1.2-beta-2",
-    "@ray-js/wechat-event": "^0.1.2-beta-2"
+    "@ray-js/wechat-helper": "^0.1.3-beta-1",
+    "@ray-js/wechat-event": "^0.1.3-beta-1"
   },
   "peerDependencies": {}
 }

package/src/index.d.ts

@@ -1,4 +1,9 @@
 import { Options, Client } from './lib/interface';
 import './lib/adapter';
 export * from './lib/interface';
+/**
+ * 创建一个MQTT实例
+ * @param options
+ * @returns
+ */
 export declare const createMQTT: (options: Options) => Promise<Client>;

package/src/lib/auth.d.ts

@@ -1,2 +1,5 @@
 import { ClientConntroller, AuthOptions } from "./interface";
+/**
+ * 取消订阅
+ */
 export declare const auth: (client: ClientConntroller, options: AuthOptions) => void;

package/src/lib/connect.d.ts

@@ -1,2 +1,7 @@
 import { ClientConntroller, Options } from "./interface";
+/**
+ * mqtt 连接
+ * @param client
+ * @param options
+ */
 export declare const connect: (client: ClientConntroller, options: Options) => Promise<unknown>;

package/src/lib/constant.d.ts

@@ -1,3 +1,6 @@
+/**
+ * 控制报文类型
+ */
 export declare enum PacketType {
     Reserved = 0,
     CONNECT = 1,
@@ -16,6 +19,9 @@ export declare enum PacketType {
     DISCONNECT = 14,
     AUTH = 15
 }
+/**
+ * 属性标记
+ */
 export declare enum PropertySign {
     sessionExpiryInterval = 17,
     receiveMaximum = 33,

package/src/lib/disconnect.d.ts

@@ -1,2 +1,7 @@
 import { ClientConntroller, DisconnectOptions } from "./interface";
+/**
+ * mqtt 连接
+ * @param client
+ * @param options
+ */
 export declare const disconnect: (client: ClientConntroller, options: DisconnectOptions) => Promise<void>;

package/src/lib/factory.d.ts

@@ -1,6 +1,17 @@
 import { Adapter, ClientConntroller, Options } from "./interface";
 declare type Judge = () => boolean;
 declare type Connect = (url: string, version?: number) => Promise<Adapter>;
+/**
+ * 添加 Websocket 适配器
+ * 用于适配不同平台下 WebSocket
+ * @param judge 适配器是否生效判断
+ * @param creater 适配器生成函数
+ * @param priority 适配器是否优先，若为 true，则会优先尝试判断适配器
+ */
 export declare const addAdapter: (judge: Judge, creater: Connect, priority?: boolean) => void;
+/**
+ * 创建适配器
+ * @returns
+ */
 export declare const createClient: (options: Options) => Promise<ClientConntroller>;
 export {};

package/src/lib/interface.d.ts

@@ -1,11 +1,33 @@
 export interface Adapter {
+    /**
+     * 关闭连接
+     */
     close: () => void;
+    /**
+     * 监听连接关闭
+     * @param cb
+     */
     onClose(cb: (ev: any) => void): void;
+    /**
+     * 发送消息
+     * @param data
+     */
     send(data: ArrayBuffer | ArrayBufferView): void;
+    /**
+     * 接收到消息监听
+     */
     onMessage(cb: (res: {
         data: ArrayBuffer;
     }) => void): void;
+    /**
+     * 网络连接成功
+     * @param cb
+     */
     onOpen(cb: (data: any) => void): void;
+    /**
+     * 连接出错
+     * @param cb
+     */
     onError(cb: (ev: any) => void): void;
 }
 export interface MQTTMessage {
@@ -13,46 +35,151 @@ export interface MQTTMessage {
     payload: Uint8Array;
 }
 export interface ClientConntroller {
+    /**
+     * 配置
+     */
     options: Options;
+    /**
+     * 协议版本
+     */
     protocolVersion: number;
+    /**
+     * 服务端是否保存了会话
+     * 值为0|1
+     */
     sessionPresent: number;
     connect(isReconnect?: boolean): Promise<any>;
     isClose(): boolean;
+    /**
+     * 是否在线
+     */
     isOnline(): boolean;
+    /**
+     * 0 表示等待连接或连接中，1 为连接成功，2 为未连接
+     */
     getStatus(): 0 | 1 | 2;
+    /**
+    * 关闭连接
+    */
     close: () => void;
+    /**
+     * 监听连接关闭
+     * @param cb
+     */
     onClose(cb: (ev: any) => void): void;
+    /**
+     * 发送消息
+     * @param data
+     */
     send(data: ArrayBuffer | ArrayBufferView): void;
+    /**
+     * 连接出错
+     * @param cb
+     */
     onError(cb: (ev: any) => void): void;
+    /**
+     * 接收到消息监听
+     */
     onMessage(cb: (data: Uint8Array) => void): void;
     offMessage(cb: (data: Uint8Array) => void): void;
     offClose(cb: (ev: any) => void): void;
     offError(cb: (ev: any) => void): void;
     emitError(data: any): void;
+    /**
+     * mqtt 收到消息触发
+     * @param cb
+     */
     emitMqttMessage(data: MQTTMessage): void;
+    /**
+     * 注册 mqtt 收到消息事件
+     * @param cb
+     */
     onMqttMessage(cb: (data: MQTTMessage) => void): void;
+    /**
+    * 移除 mqtt 收到消息事件
+    * @param cb
+    */
     offMqttMessage(cb: (data: MQTTMessage) => void): void;
+    /**
+     * topic 别名处理
+     */
     applyTopic: (topicAlias: number, topicName: string) => void;
+    /**
+     * 通过别名获取 Topic
+     */
     getTopic: (topicAlias: number) => string;
+    /**
+     * 验证主题正确性
+     */
     checkTopic: (topicName: string) => boolean;
+    /**
+     * 加入主题
+     * @param topic
+     * @returns
+     */
     addTopic: (topic: string) => void;
+    /**
+     * 移除主题
+     * @param topic
+     * @returns
+     */
     removeTopic: (topic: string) => void;
+    /**
+     * 清除所有主题
+     * @returns
+     */
     clearTopic: () => void;
 }
 export declare type QoS = 0 | 1 | 2;
 export declare type UserProperties = Record<string, string | string[]>;
 export interface Options {
+    /**
+     * mqtt 连接地址
+     */
     url: string;
+    /**
+     * 账号
+     */
     username?: string;
+    /**
+     * 账号密码
+     */
     password?: string;
+    /**
+     * 客户端id
+     */
     clientId: string;
+    /**
+     * 协议版本
+     */
     protocolVersion?: number;
+    /**
+     * 心跳间隔时间
+     */
     keepalive?: number;
+    /**
+     * 是否为新会话
+     */
     clean?: boolean;
+    /**
+     * 遗嘱消息配置
+     */
     will?: {
+        /**
+         * 遗嘱主题
+         */
         topic: string;
+        /**
+         * 遗嘱数据
+         */
         payload: Uint8Array | string;
+        /**
+         * the QoS
+         */
         qos: QoS;
+        /**
+         * the retain flag
+         */
         retain: boolean;
         properties?: {
             willDelayInterval?: number;
@@ -64,6 +191,9 @@ export interface Options {
             userProperties?: UserProperties;
         };
     };
+    /**
+     * 协议版本 5 properties
+     */
     properties?: {
         sessionExpiryInterval?: number;
         receiveMaximum?: number;
@@ -75,19 +205,55 @@ export interface Options {
         authenticationMethod?: string;
         authenticationData?: Uint8Array;
     };
+    /**
+     *
+     * 连接超时时间
+     * 单位秒，默认 10 秒
+     */
     connectTimeout?: number;
+    /**
+     * 认证处理方法
+     * 在收到auth报文时触发
+     */
     onAuth?: (options: AuthOptions) => AuthOptions;
+    /**
+     * 当接收到消息且 qos 为 1 时的处理函数
+     * 如果不定义，则默认返回原因码 0
+     */
     onPuback?: (options: Message) => PuplishResponse;
+    /**
+      * 在收到 Pubrec 报文时用于返回 Pubrel 的处理函数，
+      * 如果不定义，则默认返回原因码 0
+      *
+      */
     onPubrel?: (options: PuplishResponse) => PuplishResponse;
+    /**
+      * 在收到 publish 报文时触发，用于返回 Pubrec 的处理函数
+      * 如果不定义，则默认返回原因码 0
+      */
     onPubrec?: (options: Message) => PuplishResponse;
+    /**
+      * 在接收到Pubrel时，用于处理 Pubcomp 返回
+      * 如果不定义，则默认返回原因码 0
+      */
     onPubcomp?: (options: PuplishResponse) => PuplishResponse;
 }
 export declare type QOS = 0 | 1 | 2;
 export interface Message {
+    /**
+     * 消息标识
+     * qos > 0时必填
+     */
     id?: number;
     dup?: boolean;
     qos?: QOS;
+    /**
+     * 主题名
+     */
     topicName: string;
+    /**
+     * 协议5版本需要此值
+     */
     properties?: {
         payloadFormatIndicator?: boolean;
         messageExpiryInterval?: number;
@@ -115,7 +281,13 @@ export interface MessageOption {
     };
 }
 export interface DisconnectOptions {
+    /**
+     * 原因码，默认为0
+     */
     reasonCode?: number;
+    /**
+     * 属性，协议版本5支持
+     */
     properties?: {
         sessionExpiryInterval?: number;
         reasonString?: string;
@@ -124,7 +296,13 @@ export interface DisconnectOptions {
     };
 }
 export interface AuthOptions {
+    /**
+     * 原因码
+     */
     reasonCode: number;
+    /**
+     * 属性，协议版本5支持
+     */
     properties?: {
         authenticationMethod: string;
         authenticationData: string;
@@ -134,25 +312,63 @@ export interface AuthOptions {
 }
 export interface PuplishResponse {
     id: number;
+    /**
+     * 原因码
+     */
     reasonCode?: number;
+    /**
+     * 属性，协议版本5支持
+     */
     properties?: {
         reasonString?: string;
         userProperties?: UserProperties;
     };
 }
 export interface Client {
+    /**
+     * 0 表示等待连接或连接中，1 为连接成功，2 为未连接
+     */
     getStatus(): 0 | 1 | 2;
+    /**
+     * 接收消息监听
+     */
     onMessage(cb: (data: MQTTMessage) => void): void;
+    /**
+     * 取消接收消息监听
+     */
     offMessage(cb: (data: MQTTMessage) => void): void;
+    /**
+     * 发送消息
+     */
     publish(topic: string, message: string | Uint8Array, option?: MessageOption): void;
+    /**
+     * 重新认证
+     */
     reAuth(option: AuthOptions): void;
+    /**
+     * 断开连接
+     */
     disconnect(option?: DisconnectOptions): void;
+    /**
+     * 关闭事件
+     * @param cb
+     */
     onClose(cb: () => void): void;
+    /**
+     * 错误监听
+     * @param cb
+     */
     onError(cb: (e: any) => void): void;
+    /**
+     * 订阅
+     */
     subscribe: (topics: Topic[], options?: SubscribeOption) => Promise<{
         err?: Record<string, number>;
         properties?: any;
     }>;
+    /**
+     * 取消订阅
+     */
     unsubscribe: (topic: string[], options?: UnsubscribeOption) => Promise<{
         err?: Record<string, number>;
         properties?: any;

package/src/lib/packet.d.ts

@@ -1,17 +1,34 @@
 import { PropertySign } from "./constant";
 declare type WriteData = (data: string | number | number[] | Uint8Array) => void;
+/**
+ * 创建数据包
+ * @param cmd 控制报文
+ * @param fixHeader 固定报文中，4个低字节位数值
+ * @returns
+ */
 export declare const createPacket: (cmd: number, fixHeader?: number) => {
     header: (data: number | number[] | Uint8Array, needLen?: boolean, isVariable?: boolean) => void;
     payload: (data: string | number | number[] | Uint8Array, needLen?: boolean, isVariable?: boolean) => void;
     cleanCache(): void;
+    /**
+     *
+     * @param data
+     */
     cache: (data: string | number | number[] | Uint8Array, needLen?: boolean, isVariable?: boolean) => void;
     putHeader(): void;
     putPayload(): void;
     getCache(): Uint8Array;
+    /**
+     * 获取 packet 数据
+     * @returns
+     */
     getPacket: () => Uint8Array;
 };
 export declare const writeString: (sign: PropertySign) => (v: string, write: WriteData) => void;
 export declare const writePair: (sign: PropertySign) => (properies: Record<string, string | string[]>, write: WriteData) => void;
+/**
+ * 属性值类型
+ */
 export declare const writeProperty: {
     sessionExpiryInterval: (value: number, write: WriteData) => void;
     receiveMaximum: (value: number, write: WriteData) => void;
@@ -31,5 +48,10 @@ export declare const writeProperty: {
     correlationData: (value: Uint8Array, write: WriteData) => void;
     subscriptionIdentifier: (value: number, write: WriteData) => void;
 };
+/**
+ * 转化 properties 的数据
+ * @param properies
+ * @param write
+ */
 export declare const packetProperties: (properies: any, write: WriteData) => void;
 export {};

package/src/lib/parse.d.ts

@@ -1,4 +1,7 @@
 import { AuthOptions, ClientConntroller, Message, PuplishResponse } from "./interface";
+/**
+ * 属性值类型
+ */
 export declare const parseProperty: {
     sessionExpiryInterval: (data: Uint8Array, offset: number) => number[];
     receiveMaximum: (data: Uint8Array, offset: number) => number[];
@@ -18,7 +21,21 @@ export declare const parseProperty: {
     correlationData: (data: Uint8Array, offset: number) => [Uint8Array, number];
     subscriptionIdentifier: (data: Uint8Array, offset: number) => number[];
 };
+/**
+ * 解析 properties
+ * @param data
+ * @returns
+ */
 export declare const parseProperties: (data: Uint8Array) => Record<string, any>;
+/**
+ * 解析认证授权数据
+ * @param data
+ * @returns
+ */
 export declare const parseAuth: (data: Uint8Array) => AuthOptions;
+/**
+ * 解析消息数据
+ * @param data
+ */
 export declare const parsePublish: (data: Uint8Array, client: ClientConntroller) => Message;
 export declare const parsePublishResponse: (data: Uint8Array, client: ClientConntroller) => PuplishResponse;

package/src/lib/ping.d.ts

@@ -1,2 +1,5 @@
 import { ClientConntroller } from "./interface";
+/**
+ * 取消订阅
+ */
 export declare const ping: (client: ClientConntroller) => Promise<true>;

package/src/lib/publish.d.ts

@@ -1,4 +1,9 @@
 import { ClientConntroller, Message, PuplishResponse } from "./interface";
+/**
+ * 发布消息
+ * @param client
+ * @param data
+ */
 export declare const publish: (client: ClientConntroller, message: Message) => Promise<void>;
 export declare const puback: (client: ClientConntroller, message: PuplishResponse) => Promise<void>;
 export declare const pubrel: (client: ClientConntroller, message: PuplishResponse) => Promise<void>;

package/src/lib/subscribe.d.ts

@@ -20,10 +20,18 @@ interface UnSubscribeOptions {
     };
     topics: string[];
 }
+/**
+ * 订阅消息
+ * @param client
+ * @param options
+ */
 export declare const subscribe: (client: ClientConntroller, options: SubscribeOptions) => Promise<{
     reasonCode: Uint8Array;
     properties?: any;
 }>;
+/**
+ * 取消订阅
+ */
 export declare const unsubscribe: (client: ClientConntroller, subscribe: UnSubscribeOptions) => Promise<{
     reasonCode: Uint8Array;
     properties?: any;