@easy-electron/preload 1.0.1-alpha.1

package/dist/index.mjs

@@ -0,0 +1,1048 @@
+import { ConfigUtil } from '@easy-electron/utils';
+import { Logger } from '@easy-electron/logger';
+import { TsParser } from '@easy-electron/ts-parser';
+import fg from 'fast-glob';
+import * as fs from 'fs';
+import * as path from 'path';
+export { E as EVENT_MODULE_KEY, I as IPC_MODULE_KEY, d as defineEvents, a as defineIpc } from './shared/preload.CkLc48BZ.mjs';
+
+const DEFAULT_EASY_PRELOAD_GENERATOR_CONFIG = {
+  dir: "./electron",
+  source: ["**/*.ipc.ts", "**/ipc/**/*.ts"],
+  events: ["**/*.events.ts", "**/events/**/*.ts"],
+  ignores: ["**/node_modules/**", "**/dist/**", "**/dist-electron/**"],
+  output: "./electron/preload.ts",
+  typesOutput: "./types/electron.d.ts",
+  globalName: "elec",
+  preserveComments: true
+};
+
+class IpcFileScanner {
+  dir;
+  source;
+  ignores;
+  parser;
+  logger = Logger.scope("IpcFileScanner");
+  /**
+   * @param dir 扫描根目录
+   * @param source 文件匹配模式（glob 格式，支持数组）
+   * @param ignores 忽略的文件模式
+   */
+  constructor(dir, source, ignores) {
+    this.dir = dir;
+    this.source = source;
+    this.ignores = ignores;
+    this.parser = new TsParser();
+  }
+  /**
+   * 扫描所有匹配的 IPC 定义文件，返回解析结果列表
+   */
+  scan() {
+    const patterns = Array.isArray(this.source) ? this.source : [this.source];
+    const files = fg.sync(patterns, {
+      cwd: this.dir,
+      absolute: true,
+      ignore: this.ignores
+    });
+    const results = [];
+    for (const file of files) {
+      try {
+        const defi = this.parseFile(file);
+        if (defi) {
+          results.push(defi);
+        }
+      } catch (e) {
+        this.logger.warn(`\u89E3\u6790 IPC \u6587\u4EF6\u5931\u8D25: ${file}`, e);
+      }
+    }
+    return results;
+  }
+  /**
+   * 解析单个 IPC 定义文件
+   *
+   * 查找文件中的 `export default defineIpc(...)` 调用，
+   * 提取模块名和所有处理器定义。
+   *
+   * @param filePath 文件路径
+   * @returns IPC 定义信息，文件中无 defineIpc 调用时返回 null
+   */
+  parseFile(filePath) {
+    const parsed = this.parser.parse(filePath);
+    const defaultExport = parsed.defaultExport;
+    if (!defaultExport || defaultExport.kind !== "call" || !defaultExport.call) {
+      return null;
+    }
+    const call = defaultExport.call;
+    if (call.callee !== "defineIpc") {
+      return null;
+    }
+    return this.parseDefineIpcCall(filePath, call, parsed);
+  }
+  /**
+   * 解析 defineIpc 函数调用，提取模块名和处理器映射
+   *
+   * 支持两种调用形式:
+   * - `defineIpc({ ... })` — 无模块名
+   * - `defineIpc('moduleName', { ... })` — 有模块名
+   *
+   * @param filePath 文件路径
+   * @param call 函数调用表达式信息
+   * @param parsed 完整的文件解析结果（用于提取 import 信息）
+   * @returns IPC 定义信息
+   */
+  parseDefineIpcCall(filePath, call, parsed) {
+    const args = call.arguments;
+    if (args.length < 1) {
+      this.logger.warn(`defineIpc \u8C03\u7528\u53C2\u6570\u4E0D\u8DB3: ${filePath}`);
+      return null;
+    }
+    let moduleName;
+    let handlersArg;
+    if (args.length >= 2 && args[0].kind === "string") {
+      moduleName = String(args[0].value);
+      handlersArg = args[1];
+    } else {
+      handlersArg = args[0];
+    }
+    if (handlersArg.kind !== "object" || !handlersArg.properties) {
+      this.logger.warn(`defineIpc \u5904\u7406\u5668\u53C2\u6570\u4E0D\u662F\u5BF9\u8C61\u5B57\u9762\u91CF: ${filePath}`);
+      return null;
+    }
+    const handlers = /* @__PURE__ */ new Map();
+    for (const prop of handlersArg.properties) {
+      const handlerInfo = this.parseHandler(prop);
+      if (handlerInfo) {
+        handlers.set(prop.name, handlerInfo);
+      }
+    }
+    const imports = this.collectImports(parsed, filePath);
+    return {
+      filePath,
+      module: moduleName,
+      handlers,
+      imports
+    };
+  }
+  /**
+   * 解析单个处理器属性
+   *
+   * 支持三种写法：
+   * 1. 箭头函数（默认 handle 类型）:
+   *    `getData: async (_event, id: string): Promise<Data> => { ... }`
+   *
+   * 2. 方法简写（默认 handle 类型）:
+   *    `getUser() { return ... }`
+   *
+   * 3. 对象形式（显式指定类型）:
+   *    `logMessage: { type: 'on', handler: (_event, msg: string) => { ... } }`
+   *
+   * @param prop 对象属性信息
+   * @returns IPC 处理器信息，无法解析时返回 null
+   */
+  parseHandler(prop) {
+    const value = prop.value;
+    if (value.kind === "function" && value.function) {
+      return this.extractHandlerFromFunction(value.function, "handle", prop.comment);
+    }
+    if (value.kind === "object" && value.properties) {
+      return this.parseObjectHandler(value.properties, prop.comment);
+    }
+    return null;
+  }
+  /**
+   * 从对象形式的处理器定义中提取信息
+   *
+   * 对象中可包含:
+   * - `type`: 处理器类型字符串（'handle' | 'on' | 'handleOnce' | 'once'）
+   * - `handler`: 处理器函数
+   *
+   * @param properties 对象属性列表
+   * @param comment 外层属性的 JSDoc 注释
+   * @returns IPC 处理器信息
+   */
+  parseObjectHandler(properties, comment) {
+    let handlerType = "handle";
+    let handlerFunc;
+    for (const p of properties) {
+      if (p.name === "type" && p.value.kind === "string") {
+        handlerType = String(p.value.value);
+      } else if (p.name === "handler") {
+        handlerFunc = p.value;
+      }
+    }
+    if (!handlerFunc || handlerFunc.kind !== "function" || !handlerFunc.function) {
+      return null;
+    }
+    return this.extractHandlerFromFunction(handlerFunc.function, handlerType, comment);
+  }
+  /**
+   * 从函数表达式中提取处理器的参数和返回类型信息
+   *
+   * 智能跳过第一个 event 参数：
+   * - 参数名以 _ 开头或名为 event/e → 视为 event 参数，跳过
+   * - 否则保留所有参数
+   *
+   * @param func 函数表达式信息
+   * @param handlerType 处理器类型
+   * @param comment JSDoc 注释
+   * @returns IPC 处理器信息
+   */
+  extractHandlerFromFunction(func, handlerType, comment) {
+    const params = this.skipEventParam(func.parameters);
+    const paramNames = params.map((p) => p.name);
+    const paramTypes = params.map((p) => p.type ?? "any");
+    let returnType = func.returnType ?? (func.isAsync ? "Promise<any>" : "any");
+    if (func.isAsync && func.returnType && !func.returnType.startsWith("Promise")) {
+      returnType = `Promise<${func.returnType}>`;
+    }
+    return {
+      paramNames,
+      paramTypes,
+      returnType,
+      comment: comment ?? void 0,
+      handlerType
+    };
+  }
+  /**
+   * 智能跳过函数参数列表中的 event 参数
+   *
+   * 判断第一个参数是否为 Electron IPC 事件对象：
+   * - 参数名以 _ 开头（如 _event, _e）
+   * - 参数名为 event 或 e
+   * - 参数类型包含 Event
+   *
+   * @param params 原始参数列表
+   * @returns 跳过 event 参数后的参数列表
+   */
+  skipEventParam(params) {
+    if (params.length === 0) return params;
+    const first = params[0];
+    const name = first.name;
+    const type = first.type ?? "";
+    const isEventParam = name.startsWith("_") || name === "event" || name === "e" || type.includes("Event");
+    return isEventParam ? params.slice(1) : params;
+  }
+  /**
+   * 收集文件中引用的类型信息
+   *
+   * 包括两部分：
+   * 1. import 语句中导入的类型（过滤掉 runtime 导入）
+   * 2. 文件内定义的 export interface/type（作为同文件类型）
+   *
+   * @param parsed 文件解析结果
+   * @param filePath 文件路径（用于本地类型的模块路径）
+   * @returns 类型名 -> 模块路径 的映射
+   */
+  collectImports(parsed, filePath) {
+    const imports = /* @__PURE__ */ new Map();
+    for (const imp of parsed.imports) {
+      if (imp.moduleSpecifier.includes("epreload/runtime") || imp.namedImports.some((n) => n.name === "defineIpc")) {
+        continue;
+      }
+      if (imp.defaultImport) {
+        imports.set(imp.defaultImport, imp.moduleSpecifier);
+      }
+      for (const named of imp.namedImports) {
+        const name = named.alias ?? named.name;
+        imports.set(name, imp.moduleSpecifier);
+      }
+    }
+    const localModulePath = this.toModulePath(filePath);
+    for (const iface of parsed.interfaces) {
+      if (iface.isExported) {
+        imports.set(iface.name, localModulePath);
+      }
+    }
+    for (const typeAlias of parsed.typeAliases) {
+      if (typeAlias.isExported) {
+        imports.set(typeAlias.name, localModulePath);
+      }
+    }
+    return imports;
+  }
+  /**
+   * 将文件绝对路径转换为相对模块路径（去掉扩展名）
+   *
+   * @param filePath 文件绝对路径
+   * @returns 相对模块路径
+   */
+  toModulePath(filePath) {
+    return filePath.replace(/\.ts$/, "");
+  }
+}
+
+class EventHandlerModel {
+  /**
+   * 数据类型
+   */
+  dataType;
+  /**
+   * JSDoc 注释
+   */
+  comment;
+  /**
+   * 是否为一次性监听
+   */
+  once;
+  /**
+   * Remove 方法类型
+   */
+  remove;
+  constructor(dataType, comment, once = false, remove = false) {
+    this.dataType = dataType;
+    this.comment = comment;
+    this.once = once;
+    this.remove = remove;
+  }
+  /**
+   * 获取回调函数类型签名
+   */
+  getCallbackSignature() {
+    return `(data: ${this.dataType}) => void`;
+  }
+  /**
+   * 获取监听方法类型签名
+   */
+  getListenerSignature() {
+    return `(callback: ${this.getCallbackSignature()}) => () => void`;
+  }
+  /**
+   * 获取 remove 方法类型签名（single）
+   */
+  getRemoveSingleSignature() {
+    return `(callback: ${this.getCallbackSignature()}) => void`;
+  }
+  /**
+   * 获取 removeAll 方法类型签名
+   */
+  getRemoveAllSignature() {
+    return `() => void`;
+  }
+}
+
+class EventFileScanner {
+  dir;
+  source;
+  ignores;
+  parser;
+  logger = Logger.scope("EventFileScanner");
+  /**
+   * @param dir 扫描根目录
+   * @param source 文件匹配模式（glob 格式，支持数组）
+   * @param ignores 忽略的文件模式
+   */
+  constructor(dir, source, ignores) {
+    this.dir = dir;
+    this.source = source;
+    this.ignores = ignores;
+    this.parser = new TsParser();
+  }
+  /**
+   * 扫描所有匹配的事件定义文件，返回解析结果列表
+   */
+  scan() {
+    const patterns = Array.isArray(this.source) ? this.source : [this.source];
+    const files = fg.sync(patterns, {
+      cwd: this.dir,
+      absolute: true,
+      ignore: this.ignores
+    });
+    const results = [];
+    for (const file of files) {
+      try {
+        const defi = this.parseFile(file);
+        if (defi) {
+          results.push(defi);
+        }
+      } catch (e) {
+        this.logger.warn(`\u89E3\u6790\u4E8B\u4EF6\u6587\u4EF6\u5931\u8D25: ${file}`, e);
+      }
+    }
+    return results;
+  }
+  /**
+   * 解析单个事件定义文件
+   *
+   * 查找文件中的 `export default defineEvents(...)` 调用，
+   * 提取所有事件处理器定义。
+   *
+   * @param filePath 文件路径
+   * @returns 事件定义信息，文件中无 defineEvents 调用时返回 null
+   */
+  parseFile(filePath) {
+    const parsed = this.parser.parse(filePath);
+    const defaultExport = parsed.defaultExport;
+    if (!defaultExport || defaultExport.kind !== "call" || !defaultExport.call) {
+      return null;
+    }
+    const call = defaultExport.call;
+    if (call.callee !== "defineEvents") {
+      return null;
+    }
+    return this.parseDefineEventsCall(filePath, call, parsed);
+  }
+  /**
+   * 解析 defineEvents 函数调用，提取事件处理器映射
+   *
+   * 支持两种调用形式:
+   * - `defineEvents({ ... })` — 无模块名
+   * - `defineEvents('moduleName', { ... })` — 有模块名
+   *
+   * @param filePath 文件路径
+   * @param call 函数调用表达式信息
+   * @param parsed 完整的文件解析结果（用于提取 import 信息）
+   * @returns 事件定义信息
+   */
+  parseDefineEventsCall(filePath, call, parsed) {
+    const args = call.arguments;
+    if (args.length < 1) {
+      this.logger.warn(`defineEvents \u8C03\u7528\u53C2\u6570\u4E0D\u8DB3: ${filePath}`);
+      return null;
+    }
+    let moduleName;
+    let handlersArg;
+    if (args.length >= 2 && args[0].kind === "string") {
+      moduleName = String(args[0].value);
+      handlersArg = args[1];
+    } else {
+      handlersArg = args[0];
+    }
+    if (handlersArg.kind !== "object" || !handlersArg.properties) {
+      this.logger.warn(`defineEvents \u5904\u7406\u5668\u53C2\u6570\u4E0D\u662F\u5BF9\u8C61\u5B57\u9762\u91CF: ${filePath}`);
+      return null;
+    }
+    const handlers = /* @__PURE__ */ new Map();
+    for (const prop of handlersArg.properties) {
+      const model = this.parseEventHandler(prop);
+      if (model) {
+        handlers.set(prop.name, model);
+      }
+    }
+    const imports = this.collectImports(parsed, filePath);
+    return {
+      filePath,
+      module: moduleName,
+      handlers,
+      imports
+    };
+  }
+  /**
+   * 解析单个事件处理器属性
+   *
+   * 支持两种写法：
+   *
+   * 1. 对象形式:
+   *    ```ts
+   *    onDownloadProgress: {
+   *      sample: (data: DownloadProgressData) => data,
+   *      remove: 'single',
+   *      once: true
+   *    }
+   *    ```
+   *
+   * 2. 简写函数形式（无 remove，非 once）:
+   *    ```ts
+   *    onAlert: (data: AlertData) => data
+   *    ```
+   *
+   * @param prop 对象属性信息
+   * @returns EventHandlerModel 实例，无法解析时返回 null
+   */
+  parseEventHandler(prop) {
+    const value = prop.value;
+    if (value.kind === "object" && value.properties) {
+      return this.parseObjectEventHandler(value.properties, prop.comment);
+    }
+    if (value.kind === "function" && value.function) {
+      const dataType = this.extractDataTypeFromFunction(value.function);
+      const once = prop.name.startsWith("once");
+      return new EventHandlerModel(dataType, prop.comment, once, false);
+    }
+    return null;
+  }
+  /**
+   * 从对象形式的事件处理器中提取信息
+   *
+   * @param properties 对象属性列表
+   * @param comment 外层属性的 JSDoc 注释
+   * @returns EventHandlerModel 实例
+   */
+  parseObjectEventHandler(properties, comment) {
+    let dataType = "any";
+    let once = false;
+    let remove = false;
+    for (const p of properties) {
+      switch (p.name) {
+        case "sample":
+          if (p.value.kind === "function" && p.value.function) {
+            dataType = this.extractDataTypeFromFunction(p.value.function);
+          }
+          break;
+        case "remove":
+          remove = this.parseRemoveType(p.value);
+          break;
+        case "once":
+          once = p.value.kind === "boolean" && p.value.value === true;
+          break;
+      }
+    }
+    return new EventHandlerModel(dataType, comment, once, remove);
+  }
+  /**
+   * 从函数表达式中提取数据类型
+   *
+   * 事件 sample 函数签名: `(data: DataType) => data`
+   * 从第一个参数的类型注解中提取数据类型。
+   *
+   * @param func 函数表达式信息
+   * @returns 数据类型字符串，无法提取时返回 'any'
+   */
+  extractDataTypeFromFunction(func) {
+    const params = func.parameters;
+    if (params.length === 0) {
+      return "void";
+    }
+    return params[0].type ?? "any";
+  }
+  /**
+   * 解析 remove 属性值为 RemoveType
+   * @param arg remove 属性值
+   * @returns RemoveType 值
+   */
+  parseRemoveType(arg) {
+    if (arg.kind === "string") {
+      const val = String(arg.value);
+      if (val === "single" || val === "all" || val === "both") {
+        return val;
+      }
+    }
+    if (arg.kind === "boolean" && arg.value === false) {
+      return false;
+    }
+    return false;
+  }
+  /**
+   * 收集文件中引用的类型信息
+   *
+   * 包括两部分：
+   * 1. import 语句中导入的类型（过滤掉 runtime 导入）
+   * 2. 文件内定义的 export interface/type（作为同文件类型）
+   *
+   * @param parsed 文件解析结果
+   * @param filePath 文件路径
+   * @returns 类型名 -> 模块路径 的映射
+   */
+  collectImports(parsed, filePath) {
+    const imports = /* @__PURE__ */ new Map();
+    for (const imp of parsed.imports) {
+      if (imp.moduleSpecifier.includes("epreload/runtime") || imp.namedImports.some((n) => n.name === "defineEvents")) {
+        continue;
+      }
+      if (imp.defaultImport) {
+        imports.set(imp.defaultImport, imp.moduleSpecifier);
+      }
+      for (const named of imp.namedImports) {
+        const name = named.alias ?? named.name;
+        imports.set(name, imp.moduleSpecifier);
+      }
+    }
+    const localModulePath = filePath.replace(/\.ts$/, "");
+    for (const iface of parsed.interfaces) {
+      if (iface.isExported) {
+        imports.set(iface.name, localModulePath);
+      }
+    }
+    for (const typeAlias of parsed.typeAliases) {
+      if (typeAlias.isExported) {
+        imports.set(typeAlias.name, localModulePath);
+      }
+    }
+    return imports;
+  }
+}
+
+class EasyPreloadGenerator {
+  config;
+  logger = Logger.scope("EasyPreloadGenerator");
+  constructor(config) {
+    this.config = ConfigUtil.deepMergeConfig(DEFAULT_EASY_PRELOAD_GENERATOR_CONFIG, config);
+  }
+  /**
+   * 执行生成，扫描 IPC 和 Event 定义文件，输出 preload 和类型文件
+   */
+  generate() {
+    const ipcDefs = this.scanIpc();
+    const eventDefs = this.scanEvents();
+    const preloadContent = this.generatePreload(ipcDefs, eventDefs);
+    const typesContent = this.generateTypes(ipcDefs, eventDefs);
+    this.writeFile(this.config.output, preloadContent);
+    this.writeFile(this.config.typesOutput, typesContent);
+    this.logger.info(`\u751F\u6210\u5B8C\u6210: ${this.config.output}, ${this.config.typesOutput}`);
+  }
+  /**
+   * 扫描 IPC 定义文件
+   */
+  scanIpc() {
+    const scanner = new IpcFileScanner(this.config.dir, this.config.source, this.config.ignores);
+    return scanner.scan();
+  }
+  /**
+   * 扫描 Event 定义文件
+   */
+  scanEvents() {
+    const scanner = new EventFileScanner(this.config.dir, this.config.events, this.config.ignores);
+    return scanner.scan();
+  }
+  // ==================== Preload 文件生成 ====================
+  /**
+   * 生成 preload.ts 文件内容
+   *
+   * 结构:
+   * ```ts
+   * contextBridge.exposeInMainWorld('globalName', {
+   *   // 无模块 IPC 方法（顶层）
+   *   ping: () => ipcRenderer.invoke('ping'),
+   *   // 有模块 IPC 方法（嵌套对象）
+   *   test: {
+   *     getData: (id) => ipcRenderer.invoke('test:getData', id),
+   *   },
+   *   // 事件（嵌套在 events 下）
+   *   events: {
+   *     onXxx: (callback) => { ... },
+   *     module: { onYyy: (callback) => { ... } },
+   *   },
+   * })
+   * ```
+   */
+  generatePreload(ipcDefs, eventDefs) {
+    const lines = [];
+    const typeImports = this.collectTypeImports(ipcDefs, eventDefs, this.config.output);
+    lines.push("import { contextBridge, ipcRenderer } from 'electron'");
+    lines.push("import type { IpcRendererEvent } from 'electron'");
+    for (const imp of typeImports) {
+      lines.push(imp);
+    }
+    lines.push("");
+    lines.push("// Auto-generated preload file");
+    lines.push("// Do not edit this file manually");
+    lines.push("");
+    lines.push(`contextBridge.exposeInMainWorld('${this.config.globalName}', {`);
+    this.generatePreloadIpc(ipcDefs, lines);
+    this.generatePreloadEvents(eventDefs, lines);
+    lines.push("})");
+    lines.push("");
+    return lines.join("\n");
+  }
+  /**
+   * 生成 preload 中的 IPC 调用代码
+   *
+   * 无模块的处理器直接放在顶层，有模块的嵌套在模块名对象下。
+   * 根据 handlerType 选择 invoke（handle/handleOnce）或 send（on/once）。
+   */
+  generatePreloadIpc(ipcDefs, lines) {
+    const noModule = [];
+    const withModule = [];
+    for (const def of ipcDefs) {
+      if (def.module) {
+        withModule.push(def);
+      } else {
+        noModule.push(def);
+      }
+    }
+    for (const def of noModule) {
+      for (const [name, handler] of def.handlers) {
+        lines.push(`  ${this.generatePreloadIpcMethod(name, name, handler)},`);
+      }
+    }
+    for (const def of withModule) {
+      lines.push(`  ${def.module}: {`);
+      for (const [name, handler] of def.handlers) {
+        const channel = `${def.module}:${name}`;
+        lines.push(`    ${this.generatePreloadIpcMethod(name, channel, handler)},`);
+      }
+      lines.push("  },");
+    }
+  }
+  /**
+   * 生成单个 IPC 方法的 preload 代码
+   *
+   * @param name 方法名
+   * @param channel IPC 通道名
+   * @param handler 处理器信息
+   * @returns 方法代码字符串（不含尾部逗号）
+   */
+  generatePreloadIpcMethod(name, channel, handler) {
+    const params = handler.paramNames.map((n, i) => `${n}: ${handler.paramTypes[i]}`).join(", ");
+    const args = handler.paramNames.length > 0 ? ", " + handler.paramNames.join(", ") : "";
+    const type = handler.handlerType ?? "handle";
+    switch (type) {
+      case "handle":
+      case "handleOnce":
+        return `${name}: (${params}): ${this.ensurePromise(handler.returnType)} => ipcRenderer.invoke('${channel}'${args})`;
+      case "on":
+      case "once":
+        return `${name}: (${params}): void => ipcRenderer.send('${channel}'${args})`;
+      default:
+        return `${name}: (${params}): ${this.ensurePromise(handler.returnType)} => ipcRenderer.invoke('${channel}'${args})`;
+    }
+  }
+  /**
+   * 生成 preload 中的事件监听代码
+   *
+   * 所有事件嵌套在 `events` 对象下。
+   * 无模块的事件直接放在 events 下，有模块的嵌套在 events.module 下。
+   */
+  generatePreloadEvents(eventDefs, lines) {
+    if (eventDefs.length === 0) return;
+    const noModule = [];
+    const withModule = [];
+    for (const def of eventDefs) {
+      if (def.module) {
+        withModule.push(def);
+      } else {
+        noModule.push(def);
+      }
+    }
+    lines.push("  events: {");
+    for (const def of noModule) {
+      for (const [name, handler] of def.handlers) {
+        const channel = this.toEventChannel(name);
+        this.generatePreloadEventMethods(name, channel, handler, lines, "    ");
+      }
+    }
+    for (const def of withModule) {
+      lines.push(`    ${def.module}: {`);
+      for (const [name, handler] of def.handlers) {
+        const channel = `${def.module}:${this.toEventChannel(name)}`;
+        this.generatePreloadEventMethods(name, channel, handler, lines, "      ");
+      }
+      lines.push("    },");
+    }
+    lines.push("  },");
+  }
+  /**
+   * 生成单个事件的监听/移除方法代码
+   *
+   * 根据 handler 的 once 和 remove 属性生成：
+   * - on/once 监听方法
+   * - removeSingle 方法（remove 为 'single' 或 'both'）
+   * - removeAll 方法（remove 为 'all' 或 'both'）
+   *
+   * @param name 事件名（如 onDownloadProgress）
+   * @param channel IPC 通道名
+   * @param handler 事件处理器模型
+   * @param lines 输出行数组
+   * @param indent 缩进字符串
+   */
+  generatePreloadEventMethods(name, channel, handler, lines, indent) {
+    const dataType = handler.dataType;
+    const listenMethod = handler.once ? "once" : "on";
+    const listenerName = handler.once && !name.startsWith("once") ? name.replace(/^on/, "once") : name;
+    lines.push(`${indent}${listenerName}: (callback: (data: ${dataType}) => void) => {`);
+    lines.push(`${indent}  const listener = (_event: IpcRendererEvent, data: ${dataType}) => callback(data)`);
+    lines.push(`${indent}  ipcRenderer.${listenMethod}('${channel}', listener)`);
+    if (!handler.once) {
+      lines.push(`${indent}  return () => ipcRenderer.removeListener('${channel}', listener)`);
+    }
+    lines.push(`${indent}},`);
+    const baseName = this.stripEventPrefix(name);
+    this.generatePreloadRemoveMethods(baseName, channel, dataType, handler.remove, lines, indent);
+  }
+  /**
+   * 生成事件的 remove 方法代码
+   */
+  generatePreloadRemoveMethods(baseName, channel, dataType, remove, lines, indent) {
+    if (remove === "single" || remove === "both") {
+      lines.push(`${indent}remove${baseName}: (callback: (data: ${dataType}) => void) => {`);
+      lines.push(`${indent}  const listener = (_event: IpcRendererEvent, data: ${dataType}) => callback(data)`);
+      lines.push(`${indent}  ipcRenderer.removeListener('${channel}', listener)`);
+      lines.push(`${indent}},`);
+    }
+    if (remove === "all" || remove === "both") {
+      lines.push(`${indent}remove${baseName}All: () => {`);
+      lines.push(`${indent}  ipcRenderer.removeAllListeners('${channel}')`);
+      lines.push(`${indent}},`);
+    }
+  }
+  // ==================== 类型文件生成 ====================
+  /**
+   * 生成类型定义文件内容
+   *
+   * 结构:
+   * ```ts
+   * interface ElecApi {
+   *   ping: () => Promise<string>
+   *   test: { getData: (id: string) => Promise<Data> }
+   * }
+   * export interface ElecEvents {
+   *   onXxx: (callback: (data: T) => void) => () => void
+   * }
+   * declare global {
+   *   interface Window { elec: ElecApi & { events: ElecEvents } }
+   * }
+   * export {}
+   * ```
+   */
+  generateTypes(ipcDefs, eventDefs) {
+    const lines = [];
+    const typeImports = this.collectTypeImports(ipcDefs, eventDefs, this.config.typesOutput);
+    for (const imp of typeImports) {
+      lines.push(imp);
+    }
+    lines.push("");
+    lines.push("// Auto-generated type definitions");
+    lines.push("// Do not edit this file manually");
+    lines.push("");
+    this.generateTypesIpc(ipcDefs, lines);
+    const hasEvents = eventDefs.length > 0;
+    if (hasEvents) {
+      lines.push("");
+      this.generateTypesEvents(eventDefs, lines);
+    }
+    lines.push("");
+    lines.push("declare global {");
+    lines.push("  interface Window {");
+    if (hasEvents) {
+      lines.push(`    ${this.config.globalName}: ElecApi & { events: ElecEvents }`);
+    } else {
+      lines.push(`    ${this.config.globalName}: ElecApi`);
+    }
+    lines.push("  }");
+    lines.push("}");
+    lines.push("");
+    lines.push("export {}");
+    lines.push("");
+    return lines.join("\n");
+  }
+  /**
+   * 生成 ElecApi 接口中的 IPC 方法类型
+   */
+  generateTypesIpc(ipcDefs, lines) {
+    const noModule = [];
+    const withModule = [];
+    for (const def of ipcDefs) {
+      if (def.module) {
+        withModule.push(def);
+      } else {
+        noModule.push(def);
+      }
+    }
+    lines.push("interface ElecApi {");
+    for (const def of noModule) {
+      for (const [name, handler] of def.handlers) {
+        this.generateTypesIpcMethod(name, handler, lines, "  ");
+      }
+    }
+    for (const def of withModule) {
+      lines.push(`  ${def.module}: {`);
+      for (const [name, handler] of def.handlers) {
+        this.generateTypesIpcMethod(name, handler, lines, "    ");
+      }
+      lines.push("  }");
+    }
+    lines.push("}");
+  }
+  /**
+   * 生成单个 IPC 方法的类型签名
+   *
+   * @param name 方法名
+   * @param handler 处理器信息
+   * @param lines 输出行数组
+   * @param indent 缩进字符串
+   */
+  generateTypesIpcMethod(name, handler, lines, indent) {
+    if (this.config.preserveComments && handler.comment) {
+      const commentLines = handler.comment.split("\n");
+      for (const cl of commentLines) {
+        lines.push(`${indent}${cl.trim()}`);
+      }
+    }
+    const params = handler.paramNames.map((n, i) => `${n}: ${handler.paramTypes[i]}`).join(", ");
+    const type = handler.handlerType ?? "handle";
+    const returnType = type === "on" || type === "once" ? "void" : this.ensurePromise(handler.returnType);
+    lines.push(`${indent}${name}: (${params}) => ${returnType}`);
+  }
+  /**
+   * 生成 ElecEvents 接口中的事件方法类型
+   */
+  generateTypesEvents(eventDefs, lines) {
+    const noModule = [];
+    const withModule = [];
+    for (const def of eventDefs) {
+      if (def.module) {
+        withModule.push(def);
+      } else {
+        noModule.push(def);
+      }
+    }
+    lines.push("export interface ElecEvents {");
+    for (const def of noModule) {
+      for (const [name, handler] of def.handlers) {
+        this.generateTypesEventMethods(name, handler, lines, "  ");
+      }
+    }
+    for (const def of withModule) {
+      lines.push(`  ${def.module}: {`);
+      for (const [name, handler] of def.handlers) {
+        this.generateTypesEventMethods(name, handler, lines, "    ");
+      }
+      lines.push("  }");
+    }
+    lines.push("}");
+  }
+  /**
+   * 生成单个事件的类型签名（监听 + remove 方法）
+   */
+  generateTypesEventMethods(name, handler, lines, indent) {
+    const listenerName = handler.once && !name.startsWith("once") ? name.replace(/^on/, "once") : name;
+    if (this.config.preserveComments && handler.comment) {
+      const commentLines = handler.comment.split("\n");
+      for (const cl of commentLines) {
+        lines.push(`${indent}${cl.trim()}`);
+      }
+    }
+    if (handler.once) {
+      lines.push(`${indent}${listenerName}: ${handler.getListenerSignature()}`);
+    } else {
+      lines.push(`${indent}${listenerName}: ${handler.getListenerSignature()}`);
+    }
+    const baseName = this.stripEventPrefix(name);
+    if (handler.remove === "single" || handler.remove === "both") {
+      lines.push(`${indent}remove${baseName}: ${handler.getRemoveSingleSignature()}`);
+    }
+    if (handler.remove === "all" || handler.remove === "both") {
+      lines.push(`${indent}remove${baseName}All: ${handler.getRemoveAllSignature()}`);
+    }
+  }
+  // ==================== 工具方法 ====================
+  /**
+   * 收集所有 IPC 和 Event 定义中引用的类型导入语句
+   *
+   * 将各文件的 imports 映射合并，按模块路径分组，
+   * 生成相对于输出文件的 import type 语句。
+   *
+   * @param ipcDefs IPC 定义列表
+   * @param eventDefs Event 定义列表
+   * @returns import 语句列表
+   */
+  collectTypeImports(ipcDefs, eventDefs, outputPath) {
+    const grouped = /* @__PURE__ */ new Map();
+    const addImports = (imports, sourceFilePath) => {
+      for (const [typeName, modulePath] of imports) {
+        const resolvedPath = this.resolveImportPath(sourceFilePath, modulePath, outputPath);
+        if (!grouped.has(resolvedPath)) {
+          grouped.set(resolvedPath, /* @__PURE__ */ new Set());
+        }
+        grouped.get(resolvedPath).add(typeName);
+      }
+    };
+    for (const def of ipcDefs) {
+      addImports(def.imports, def.filePath);
+    }
+    for (const def of eventDefs) {
+      addImports(def.imports, def.filePath);
+    }
+    const result = [];
+    for (const [modulePath, types] of grouped) {
+      const typeNames = Array.from(types).sort().join(", ");
+      result.push(`import type { ${typeNames} } from '${modulePath}'`);
+    }
+    return result;
+  }
+  /**
+   * 将源文件中的模块路径转换为相对于输出文件的路径
+   *
+   * 支持三种输入：
+   * - 相对路径（以 . 开头）: 相对于源文件解析后再转换
+   * - 绝对路径: 直接计算相对于输出文件的路径
+   * - 包导入（非相对/绝对路径）: 直接返回
+   *
+   * @param sourceFilePath 源文件绝对路径
+   * @param modulePath 模块路径（相对、绝对或包名）
+   * @returns 相对于输出文件的模块路径
+   */
+  resolveImportPath(sourceFilePath, modulePath, outputPath) {
+    let absoluteModulePath;
+    if (path.isAbsolute(modulePath)) {
+      absoluteModulePath = modulePath;
+    } else if (modulePath.startsWith(".")) {
+      const sourceDir = path.dirname(sourceFilePath);
+      absoluteModulePath = path.resolve(sourceDir, modulePath);
+    } else {
+      return modulePath;
+    }
+    const outputDir = path.dirname(path.resolve(outputPath));
+    let relativePath = path.relative(outputDir, absoluteModulePath);
+    relativePath = relativePath.replace(/\\/g, "/");
+    if (!relativePath.startsWith(".")) {
+      relativePath = "./" + relativePath;
+    }
+    return relativePath;
+  }
+  /**
+   * 将事件名转换为 IPC 通道名（camelCase → kebab-case）
+   *
+   * 去掉 on/once 前缀后转换:
+   * - onDownloadProgress → download-progress
+   * - onceReady → ready
+   *
+   * @param name 事件名
+   * @returns 通道名
+   */
+  toEventChannel(name) {
+    let baseName = name;
+    if (baseName.startsWith("once")) {
+      baseName = baseName.slice(4);
+    } else if (baseName.startsWith("on")) {
+      baseName = baseName.slice(2);
+    }
+    baseName = baseName.charAt(0).toLowerCase() + baseName.slice(1);
+    return baseName.replace(/([A-Z])/g, "-$1").toLowerCase();
+  }
+  /**
+   * 去掉事件名的 on/once 前缀，返回大写开头的基础名
+   *
+   * - onDownloadProgress → DownloadProgress
+   * - onceReady → Ready
+   *
+   * @param name 事件名
+   * @returns 基础名（首字母大写）
+   */
+  stripEventPrefix(name) {
+    if (name.startsWith("once")) {
+      return name.slice(4);
+    }
+    if (name.startsWith("on")) {
+      return name.slice(2);
+    }
+    return name.charAt(0).toUpperCase() + name.slice(1);
+  }
+  /**
+   * 确保返回类型被 Promise 包裹
+   *
+   * - 已经是 Promise<T> → 原样返回
+   * - 其他类型 → 包裹为 Promise<T>
+   *
+   * @param returnType 原始返回类型
+   * @returns Promise 包裹后的返回类型
+   */
+  ensurePromise(returnType) {
+    if (returnType.startsWith("Promise<")) {
+      return returnType;
+    }
+    return `Promise<${returnType}>`;
+  }
+  /**
+   * 写入文件，自动创建目录
+   */
+  writeFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, content, "utf-8");
+    this.logger.info(`\u5DF2\u5199\u5165: ${filePath}`);
+  }
+}
+
+export { EasyPreloadGenerator };