@xuzhiyang/syncvar 1.1.1

package/dist/types.d.ts

@@ -0,0 +1,317 @@
+/**
+ * WaterBear SDK - WebSocket 变量同步 SDK
+ * @version 1.1.1
+ */
+
+/**
+ * 数据传输格式
+ */
+export const NetPackFormat: Readonly<{
+    JsonString: 0;
+    MessagePack: 1;
+}>;
+
+/**
+ * WebSocketClient 连接配置
+ */
+export interface WebSocketClientOptions {
+    /** WebSocket 服务地址，默认 wss://varserver.popx.com/ws/syncvar */
+    url?: string;
+    /** 命名空间/房间，隔离不同业务 */
+    namespace?: string;
+    /** 客户端 GUID，用于恢复会话或追踪 */
+    guid?: string;
+    /** 数据传输格式，0 为 JSON，1 为 MessagePack，默认 1 */
+    packFormat?: 0 | 1;
+    /** 连接成功后的回调 */
+    onopen?: (ws: WebSocket, event: Event) => void;
+    /** 连接关闭时的回调 */
+    onclose?: (event: CloseEvent) => void;
+    /** 连接或消息处理异常时的回调 */
+    onerror?: (error: Error) => void;
+    /** 连接超时时间（毫秒），默认 5000 */
+    timeout?: number;
+    /** 最大重连次数，默认 100 */
+    maxReconnectCount?: number;
+}
+
+/**
+ * WebSocket 实例扩展接口
+ */
+export interface WebSocketWithExtensions extends WebSocket {
+    /** 客户端 ID */
+    id?: string;
+}
+
+/**
+ * 创建 WebSocket 客户端
+ */
+export function WebSocketClient(options: WebSocketClientOptions): Promise<WebSocketWithExtensions>;
+export function WebSocketClient(host: string, params?: WebSocketClientOptions): Promise<WebSocketWithExtensions>;
+
+/**
+ * SyncVar 配置选项
+ */
+export interface SyncVarOptions {
+    /** 变更打包延迟（毫秒），合并频繁修改，默认 50 */
+    delay?: number;
+    /** 与服务端交互的 Promise 超时时间（毫秒），默认 10000 */
+    promiseTimeout?: number;
+}
+
+/**
+ * SyncVar 同步选项
+ */
+export interface SyncVarSyncOptions {
+    /** 重置变量的初始值 */
+    reset?: Record<string, any>;
+    /** 存储变量到本地 */
+    store?: boolean;
+}
+
+/**
+ * 代理对象扩展接口
+ */
+export interface ProxyObject {
+    /** 获取分布式锁 */
+    lock?(options?: { timeout?: number }): Promise<ProxyObject>;
+    /** 释放锁 */
+    unlock?(): void;
+    /** 注册更新回调 */
+    watch(callback: (value: any) => void): void;
+}
+
+/**
+ * 变量同步类
+ */
+export class SyncVar {
+    /** 获取 WebSocket 实例 */
+    get ws(): WebSocketWithExtensions | null;
+    /** 获取客户端 ID */
+    get id(): string | undefined;
+
+    /**
+     * 创建 SyncVar 实例
+     */
+    constructor(options?: SyncVarOptions);
+
+    /**
+     * 绑定 WebSocket 连接
+     */
+    bind(ws: WebSocketWithExtensions): Promise<SyncVar>;
+
+    /**
+     * 关闭 WebSocket 连接
+     */
+    close(): void;
+
+    /**
+     * 销毁 SyncVar 实例
+     */
+    destroy(): void;
+
+    /**
+     * 等待服务器确认写入完成
+     */
+    waitUpdated(): Promise<void>;
+
+    /**
+     * 绑定 RPC 函数（必须使用命名函数）
+     */
+    rpcBind(func: Function): Promise<void>;
+
+    /**
+     * 调用远程 RPC 函数
+     */
+    rpcCall<T = any>(name: string, params: any): Promise<T>;
+
+    /**
+     * 同步变量
+     */
+    sync<T extends Record<string, any>>(
+        names: string | string[],
+        options?: SyncVarSyncOptions
+    ): Promise<T>;
+}
+
+/**
+ * Worker 配置选项
+ */
+export interface WorkerOptions {
+    /** 接收服务端日志 */
+    onlog?: (...args: any[]) => void;
+    /** 接收服务端错误 */
+    onerror?: (error: any) => void;
+    /** 接收 worker 退出事件 */
+    onexit?: (exitInfo: any) => void;
+    /** 操作超时时间（毫秒），默认 10000 */
+    promiseTimeout?: number;
+}
+
+/**
+ * Worker 运行参数
+ */
+export interface WorkerRunOptions {
+    /** 要执行的代码 */
+    code: string;
+    /** Worker 名称 */
+    name: string;
+    /** Worker 数据 */
+    workerData?: any;
+}
+
+/**
+ * Worker 执行类
+ */
+export class Worker {
+    /**
+     * 创建 Worker 实例
+     */
+    constructor(options?: WorkerOptions);
+
+    /**
+     * 绑定 WebSocket 连接
+     */
+    bind(ws: WebSocketWithExtensions): Promise<Worker>;
+
+    /**
+     * 处理 WebSocket 消息
+     */
+    onMessage(msg: any): void;
+
+    /**
+     * 运行 Worker
+     */
+    run(options: WorkerRunOptions): Promise<string>;
+
+    /**
+     * 终止 Worker
+     */
+    kill(options: { name: string }): Promise<void>;
+
+    /**
+     * 关联到已存在的 Worker
+     */
+    attach(options: { name: string }): Promise<void>;
+
+    /**
+     * 获取所有 Worker 列表
+     */
+    lists(): Promise<any[]>;
+}
+
+/**
+ * SSE 配置选项
+ */
+export interface SSEOptions {
+    /** SSE 服务地址 */
+    host?: string;
+    /** 命名空间 */
+    namespace?: string;
+    /** 错误回调 */
+    onError?: (error: Error) => void;
+}
+
+/**
+ * SSE 监听配置
+ */
+export interface SSEWatchOptions {
+    /** 变量监听配置（字符串数组、函数数组或对象） */
+    vars?: string[] | Function[] | Record<string, Function>;
+    /** 事件监听配置（字符串数组、函数数组或对象） */
+    events?: string[] | Function[] | Record<string, Function>;
+}
+
+/**
+ * SSE 变量更新回调参数
+ */
+export interface SSEVariableUpdate {
+    /** 变量名 */
+    name: string;
+    /** 变量值 */
+    value: any;
+}
+
+/**
+ * SSE（服务器发送事件）类
+ */
+export class SSE {
+    /**
+     * 创建 SSE 实例
+     */
+    constructor(options?: SSEOptions);
+
+    /**
+     * 发送事件到服务器（静态方法）
+     */
+    static emit(event: string, data: any, options?: SSEOptions): Promise<Response>;
+
+    /**
+     * 监听变量和事件
+     */
+    watch(options: SSEWatchOptions): Promise<SSE>;
+
+    /**
+     * 注册事件监听器
+     */
+    onEvent(event: string, listener: Function, options?: any): void;
+
+    /**
+     * 移除事件监听器
+     */
+    offEvent(event: string, listener: Function, options?: any): void;
+
+    /**
+     * 发送事件到服务器
+     */
+    emit(event: string, data: any): Promise<Response>;
+
+    /**
+     * 关闭 SSE 连接
+     */
+    close(): void;
+
+    /**
+     * 获取所有变量快照
+     */
+    getAll(): Map<string, any>;
+
+    /**
+     * 获取单个变量的当前值
+     */
+    get(name: string): any;
+}
+
+/**
+ * 版本信息类
+ */
+export class VersionInfo {
+    /** SDK 版本号 */
+    static readonly Version: string;
+    /** 构建时间 */
+    static readonly BuildTime: string;
+
+    /**
+     * 打印版本信息到控制台
+     */
+    static printInfo(): void;
+}
+
+/**
+ * 全局类型扩展（浏览器环境）
+ */
+declare global {
+    interface Window {
+        /** WaterBear SDK 全局对象（UMD 模式） */
+        WaterBear?: {
+            WebSocketClient: typeof WebSocketClient;
+            SyncVar: typeof SyncVar;
+            Worker: typeof Worker;
+            SSE: typeof SSE;
+            VersionInfo: typeof VersionInfo;
+            NetPackFormat: typeof NetPackFormat;
+        };
+    }
+}
+
+export {};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@xuzhiyang/syncvar",
+  "version": "1.1.1",
+  "description": "WaterBear SDK - WebSocket 变量同步、锁、RPC、事件订阅和 Worker 执行能力",
+  "main": "./dist/syncvar.mjs",
+  "module": "./dist/syncvar.mjs",
+  "browser": "./dist/syncvar.js",
+  "types": "./dist/types.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/syncvar.mjs",
+      "require": "./dist/syncvar.js",
+      "types": "./dist/types.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "public": "npm publish --access=public",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "websocket",
+    "realtime",
+    "sync",
+    "variables",
+    "rpc",
+    "sse",
+    "worker",
+    "messagepack",
+    "collaboration",
+    "state-sync"
+  ],
+  "author": "xuzhiyang",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://webdev.popx.com/v3/project/xuzhiyang/SyncVar"
+  },
+  "homepage": "https://webdev.popx.com/v3/project/xuzhiyang/SyncVar",
+  "bugs": {
+    "url": "https://webdev.popx.com/v3/project/xuzhiyang/SyncVar"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "eventsource": "^4.1.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@rollup/plugin-babel": "^6.1.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "dts-bundle-generator": "^9.5.1",
+    "rollup": "^4.54.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-dts": "^6.3.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.3"
+  }
+}