electron-infra-kit 0.0.2

package/dist/core/lifecycle/LifecycleManager.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"LifecycleManager.mjs","sources":["../../../src/core/lifecycle/LifecycleManager.ts"],"sourcesContent":["import { Logger, ILogger } from '@/infrastructure/logger';\nimport WindowManager from '@/core/window/WindowManager';\nimport IpcRouter from '@/core/ipc/IpcRouter';\nimport { MessageBus } from '@/core/message-bus/MessageBus';\nimport { WindowManagerConfig } from '@/core/window/window-manager.type';\nimport { DebugHelper } from '@/infrastructure/debug';\n\n/**\n * Lifecycle Configuration\n * 生命周期配置\n */\nexport interface LifecycleConfig extends WindowManagerConfig {\n  /**\n   * Whether to automatically start on instantiation (default: false)\n   * 是否在实例化时自动启动 (默认: false)\n   */\n  autoStart?: boolean;\n\n  /**\n   * Existing IpcRouter instance\n   * 现有的 IpcRouter 实例\n   */\n  ipcRouter?: IpcRouter;\n\n  /**\n   * Existing WindowManager instance\n   * 现有的 WindowManager 实例\n   */\n  windowManager?: WindowManager;\n\n  /**\n   * Existing MessageBus instance\n   * 现有的 MessageBus 实例\n   */\n  messageBus?: MessageBus;\n}\n\n/**\n * Lifecycle Manager\n * 生命周期管理器\n *\n * Orchestrates the startup and shutdown of the Electron Toolkit modules.\n * 编排 Electron Toolkit 模块的启动和关闭。\n */\nexport class LifecycleManager {\n  public windowManager?: WindowManager;\n  public ipcRouter?: IpcRouter;\n  public messageBus?: MessageBus;\n  private logger: ILogger;\n  private isStarted = false;\n  private config: LifecycleConfig;\n\n  /**\n   * Create LifecycleManager instance\n   * 创建 LifecycleManager 实例\n   * @param config - Configuration object\n   */\n  constructor(config: LifecycleConfig = {}) {\n    this.config = config;\n    this.logger = config.logger || new Logger({ appName: 'LifecycleManager' });\n\n    if (config.autoStart) {\n      this.startup().catch((err) => {\n        this.logger.error(`Auto-startup failed: ${err}`);\n      });\n    }\n  }\n\n  /**\n   * Start up all services\n   * 启动所有服务\n   */\n  async startup(): Promise<void> {\n    if (this.isStarted) {\n      this.logger.warn('LifecycleManager already started');\n      return;\n    }\n\n    try {\n      this.logger.info('Starting up Electron Toolkit services...');\n\n      // 1. Initialize IpcRouter (Foundation for communication)\n      // 1. 初始化 IpcRouter (通信基础)\n      this.ipcRouter = this.config.ipcRouter || new IpcRouter({ logger: this.config.logger });\n      this.logger.info('IpcRouter initialized');\n\n      // 2. Initialize MessageBus (Cross-window communication)\n      // 2. 初始化 MessageBus (跨窗口通信)\n      this.messageBus = this.config.messageBus || new MessageBus({ logger: this.config.logger });\n\n      // 3. Initialize WindowManager (Core window management)\n      // 3. 初始化 WindowManager (核心窗口管理)\n      this.windowManager =\n        this.config.windowManager ||\n        new WindowManager({\n          ...this.config,\n          ipcRouter: this.ipcRouter,\n          messageBus: this.messageBus,\n        });\n      // Wait for WindowManager initialization (plugins, etc.)\n      await this.windowManager.ready();\n      this.logger.info('WindowManager initialized');\n\n      // 4. Connect MessageBus to WindowManager\n      // 4. 连接 MessageBus 到 WindowManager\n      this.messageBus.autoRegisterWindows(this.windowManager);\n      this.logger.info('MessageBus initialized');\n\n      // 4. Setup Debug Mode if enabled\n      // 4. 如果启用，设置调试模式\n      if (this.config.isDevelopment || process.env.NODE_ENV === 'development') {\n        DebugHelper.enableDebugMode();\n        DebugHelper.register('windowManager', this.windowManager);\n        DebugHelper.register('ipcRouter', this.ipcRouter);\n        DebugHelper.register('messageBus', this.messageBus);\n        DebugHelper.register('lifecycleManager', this);\n        this.logger.info('Debug mode enabled');\n      }\n\n      this.isStarted = true;\n      this.logger.info('Startup completed successfully');\n    } catch (error) {\n      this.logger.error(`Startup failed: ${error}`);\n      await this.shutdown(); // Cleanup partial initialization\n      throw error;\n    }\n  }\n\n  /**\n   * Shut down all services gracefully\n   * 优雅地关闭所有服务\n   */\n  async shutdown(): Promise<void> {\n    this.logger.info('Shutting down Electron Toolkit services...');\n\n    // Shutdown in reverse order of initialization\n    // 按初始化的逆序关闭\n\n    // 1. Dispose MessageBus\n    if (this.messageBus) {\n      try {\n        this.messageBus.dispose();\n        this.logger.info('MessageBus disposed');\n      } catch (e) {\n        this.logger.warn(`MessageBus dispose error: ${e}`);\n      }\n      this.messageBus = undefined;\n    }\n\n    // 2. Dispose WindowManager (closes all windows)\n    if (this.windowManager) {\n      try {\n        if (typeof this.windowManager.dispose === 'function') {\n          await this.windowManager.dispose();\n          this.logger.info('WindowManager disposed');\n        } else {\n          // Fallback if dispose is not implemented\n          this.windowManager.stopCleanupProtection();\n          // Ideally we should close all windows here, but we rely on WindowManager's dispose\n        }\n      } catch (e) {\n        this.logger.warn(`WindowManager dispose error: ${e}`);\n      }\n      this.windowManager = undefined;\n    }\n\n    // 3. Dispose IpcRouter\n    if (this.ipcRouter) {\n      try {\n        this.ipcRouter.dispose();\n        this.logger.info('IpcRouter disposed');\n      } catch (e) {\n        this.logger.warn(`IpcRouter dispose error: ${e}`);\n      }\n      this.ipcRouter = undefined;\n    }\n\n    this.isStarted = false;\n    this.logger.info('Shutdown completed');\n  }\n\n  /**\n   * Get initialization status\n   * 获取初始化状态\n   */\n  public get started(): boolean {\n    return this.isStarted;\n  }\n}\n"],"names":["Logger"],"mappings":"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"}

package/dist/core/message-bus/MessageBus.d.ts

@@ -0,0 +1,282 @@
+import { BrowserWindow } from 'electron';
+import { EventEmitter } from 'events';
+import { ILogger } from '@/infrastructure/logger';
+import { MessageDispatcher } from '@/internal/utils/MessageDispatcher';
+import { FieldPermission, MessageBusHandler, BusMessageHandler, MessageBusOptions } from './message-bus.type';
+import type WindowManager from '@/core/window/WindowManager';
+import { TransactionManager } from './core/TransactionManager';
+import { SubscriptionManager } from './core/SubscriptionManager';
+import { DataStoreManager } from './core/DataStoreManager';
+/**
+ * MessageBus - Multi-window state synchronization and communication bridge
+ * MessageBus - 多窗口状态同步与通信桥梁
+ *
+ * Design patterns / 设计模式:
+ * - Shared State (Instance-based): Singleton instance holds shared state (单例实例持有共享状态)
+ * - Transport Layer Abstraction: Decouples communication mechanism (传输层抽象：解耦通信机制)
+ * - Permission Control: Field-level + Window-level dual permission (权限控制：字段级 + 窗口级双重权限)
+ * - Message Proxy: Unified communication interface (消息代理：统一的通信接口)
+ * - Componentized: Delegates responsibilities to core managers (组件化：将职责委托给核心管理器)
+ */
+export declare class MessageBus extends EventEmitter {
+    private eventName;
+    protected logger: ILogger;
+    protected subscriptionManager: SubscriptionManager;
+    protected transactionManager: TransactionManager;
+    protected dataStoreManager: DataStoreManager;
+    private transport;
+    private transportMode;
+    private windows;
+    protected dispatcher: MessageDispatcher<MessageBus>;
+    private groupResolver?;
+    private watchCallbacks;
+    private windowSubscriptions;
+    /**
+     * Create a new MessageBus instance
+     * 创建一个新的 MessageBus 实例
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: MessageBusOptions);
+    /**
+     * Select transport mode
+     * 选择传输模式
+     */
+    private selectTransportMode;
+    /**
+     * Create transport instance
+     * 创建传输实例
+     */
+    private createTransport;
+    /**
+     * Handle incoming message from transport
+     * 处理来自传输层的消息
+     */
+    private handleTransportMessage;
+    /**
+     * Register a window with MessageBus
+     * 注册窗口到 MessageBus
+     * @param windowId - Window ID (窗口 ID)
+     * @param window - BrowserWindow instance (BrowserWindow 实例)
+     */
+    registerWindow(windowId: string, window: BrowserWindow): void;
+    /**
+     * Unregister a window from MessageBus
+     * 从 MessageBus 注销窗口
+     * @param windowId - Window ID (窗口 ID)
+     */
+    unregisterWindow(windowId: string): void;
+    /**
+     * Auto register/unregister windows with WindowManager
+     * 自动注册/注销窗口与 WindowManager
+     * @param windowManager - WindowManager instance (WindowManager 实例)
+     */
+    autoRegisterWindows(windowManager: WindowManager): void;
+    /**
+     * Dispose all resources
+     * 释放所有资源
+     */
+    dispose(): void;
+    /**
+     * Register a single event handler
+     * 注册单个事件处理器
+     * @param handler - Event handler (事件处理器)
+     */
+    registerHandler(handler: MessageBusHandler): void;
+    /**
+     * Batch register event handlers
+     * 批量注册事件处理器
+     * @param handlers - Array of event handlers (事件处理器数组)
+     */
+    registerHandlers(handlers: MessageBusHandler[]): void;
+    /**
+     * Unregister a single event handler
+     * 注销单个事件处理器
+     * @param handler - Event handler (事件处理器)
+     */
+    unregisterHandler(handler: MessageBusHandler): void;
+    /**
+     * Batch unregister event handlers
+     * 批量注销事件处理器
+     * @param handlers - Array of event handlers (事件处理器数组)
+     */
+    unregisterHandlers(handlers: MessageBusHandler[]): void;
+    /**
+     * Get data
+     * 获取数据
+     * @param key - Data key, returns all data if not provided (数据键，不传则返回所有数据)
+     * @returns Data value or all data (数据值或所有数据)
+     */
+    getData(key?: string): any;
+    /**
+     * Check permission
+     * 检查权限
+     * @param key - Data key (数据键)
+     * @param windowId - Operation window ID (操作窗口 ID)
+     * @param operation - Operation type (操作类型)
+     * @returns Result object with success flag and error message (包含成功标志和错误消息的结果对象)
+     */
+    private checkPermission;
+    /**
+     * Set data (with permission check and transaction support)
+     * 设置数据（带权限验证和事务支持）
+     * @param key - Data key (数据键)
+     * @param value - Data value (数据值)
+     * @param windowId - Operation window ID (操作窗口 ID)
+     * @param eventName - Optional event name (可选的事件名称)
+     * @param skipTransaction - Whether to skip transaction check (是否跳过事务检查)
+     * @returns Result object with success flag and error message (包含成功标志和错误消息的结果对象)
+     */
+    setData(key: string, value: any, windowId?: string, eventName?: string, skipTransaction?: boolean): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Delete data
+     * 删除数据
+     * @param key - Data key (数据键)
+     * @param windowId - Operation window ID (操作窗口 ID)
+     * @param eventName - Optional event name (可选的事件名称)
+     * @param skipTransaction - Whether to skip transaction check (是否跳过事务检查)
+     * @returns Result object with success flag and error message (包含成功标志和错误消息的结果对象)
+     */
+    deleteData(key: string, windowId?: string, eventName?: string, skipTransaction?: boolean): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Start a transaction
+     * 开启事务
+     * @param windowId - Window ID (窗口 ID)
+     */
+    startTransaction(windowId: string): void;
+    /**
+     * Commit a transaction
+     * 提交事务
+     * @param windowId - Window ID (窗口 ID)
+     */
+    commitTransaction(windowId: string): void;
+    /**
+     * Rollback a transaction
+     * 回滚事务
+     * @param windowId - Window ID (窗口 ID)
+     */
+    rollbackTransaction(windowId: string): void;
+    /**
+     * Watch for data changes (Main Process)
+     * 监听数据变化（主进程）
+     *
+     * ⚠️ IMPORTANT: You must call the returned unsubscribe function to prevent memory leaks
+     * ⚠️ 重要：必须调用返回的取消订阅函数以防止内存泄漏
+     *
+     * @param key - Data key to watch (监听的键)
+     * @param callback - Callback function (回调函数)
+     * @param windowId - Optional window ID to bind lifecycle (可选的窗口 ID，用于绑定生命周期)
+     * @returns Unsubscribe function (取消订阅函数)
+     */
+    watch(key: string, callback: (newValue: any, oldValue: any) => void, windowId?: string): () => void;
+    /**
+     * Atomic update
+     * 原子更新
+     * @param key - Data key (数据键)
+     * @param updater - Updater function or new value (更新函数或新值)
+     * @param windowId - Window ID (窗口 ID)
+     */
+    updateData(key: string, updater: (oldVal: any) => any, windowId?: string): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Set field permission
+     * 设置字段权限
+     * @param key - Data key (数据键)
+     * @param permission - Permission object (权限对象)
+     */
+    setFieldPermission(key: string, permission: FieldPermission): void;
+    /**
+     * Get registered windows list (for debugging)
+     * 获取已注册的窗口列表（调试用）
+     * @returns Array of registered window IDs (已注册的窗口 ID 数组)
+     */
+    getRegisteredWindows(): string[];
+    /**
+     * Register message handler
+     * 注册消息处理器
+     * @param handler - Bus message handler (总线消息处理器)
+     */
+    registerMessageHandler(handler: BusMessageHandler): void;
+    /**
+     * Register default handlers
+     * 注册默认处理器
+     */
+    private registerDefaultHandlers;
+    /**
+     * Handle message
+     * 处理消息
+     * @param name - Message name (消息名称)
+     * @param data - Message data (消息数据)
+     * @returns Result of handler (处理器结果)
+     */
+    handleMessage(name: string, data: any): any;
+    /**
+     * Initialize communication listener (optional)
+     * 初始化通信监听器（可选）
+     *
+     * Allows renderer process to read/write data directly via unified channel.
+     * 允许渲染进程通过统一通道直接读写数据。
+     */
+    initializeListener(): void;
+    /**
+     * Set group resolver
+     * 设置分组解析器
+     * @param resolver - Group resolver function (分组解析函数)
+     */
+    setGroupResolver(resolver: (group: string) => string[]): void;
+    /**
+     * Send message to specific window
+     * 发送消息到指定窗口
+     * @param windowId - Target window ID (目标窗口 ID)
+     * @param channel - Channel name (频道名称)
+     * @param data - Message data (消息数据)
+     * @returns Success or not (是否成功)
+     */
+    sendToWindow(windowId: string, channel: string, data: any): boolean;
+    /**
+     * Send message to a group of windows
+     * 发送消息到一组窗口
+     * @param group - Group name (组名)
+     * @param channel - Channel name (频道名称)
+     * @param data - Message data (消息数据)
+     * @returns Number of successful sends (成功发送的数量)
+     */
+    sendToGroup(group: string, channel: string, data: any): number;
+    /**
+     * Broadcast message to specific windows
+     * 广播消息到指定的一组窗口
+     * @param windowIds - Target window IDs (目标窗口 ID 列表)
+     * @param channel - Channel name (频道名称)
+     * @param data - Message data (消息数据)
+     * @returns Number of successful sends (成功发送的数量)
+     */
+    broadcastToWindows(windowIds: string[], channel: string, data: any): number;
+    /**
+     * Subscribe to specific keys
+     * 订阅特定的 key
+     * @param windowId - Window ID (窗口 ID)
+     * @param keys - Keys to subscribe (订阅的 key 列表)
+     */
+    subscribe(windowId: string, keys: string[]): void;
+    /**
+     * Unsubscribe from specific keys
+     * 取消订阅特定的 key
+     * @param windowId - Window ID (窗口 ID)
+     * @param keys - Keys to unsubscribe (取消订阅的 key 列表)
+     */
+    unsubscribe(windowId: string, keys: string[]): void;
+    /**
+     * Broadcast changes to all windows via Transport
+     * 通过传输层广播变更到所有窗口
+     * @param event - Data change event (数据变更事件)
+     */
+    private broadcastChange;
+}