@easy-electron/preload 1.0.1-alpha.1

package/dist/index.d.cts

@@ -0,0 +1,234 @@
+export { EVENT_MODULE_KEY, EventHandlerConfig, EventHandlerMap, IPC_MODULE_KEY, IpcHandleFunction, IpcHandlerConfig, IpcHandlerMap, IpcHandlerValue, IpcOnFunction, defineEvents, defineIpc } from './runtime-entry.cjs';
+import 'electron';
+
+/**
+ * EasyPreload 生成器配置
+ */
+interface EasyPreloadGeneratorConfig {
+    /**
+     * 扫描目录（默认 './electron'）
+     */
+    dir?: string;
+    /**
+     * IPC 源文件匹配模式（支持数组和 glob 格式）
+     * 默认 ['**\/*.ipc.ts']
+     */
+    source?: string | string[];
+    /**
+     * 事件源文件匹配模式（支持数组和 glob 格式）
+     * 默认 ['**\/*.events.ts']
+     */
+    events?: string | string[];
+    /**
+     * 忽略的文件模式（glob 格式）
+     * 默认 ['\*\*\/node_modules\/\*\*', '\*\*\/dist\/\*\*', '\*\*\/dist-electron\/\*\*']
+     */
+    ignores?: string[];
+    /**
+     * preload 输出路径
+     * 默认 ./electron/preload.ts
+     */
+    output: string;
+    /**
+     * 类型定义输出路径
+     * 默认 ./types/electron.d.ts
+     */
+    typesOutput: string;
+    /**
+     * 全局对象名称（默认 'elec'）
+     */
+    globalName?: string;
+    /**
+     * 是否在生成的类型定义中保留方法注释（默认 true）
+     */
+    preserveComments?: boolean;
+}
+
+/**
+ * EasyPreload 生成器
+ *
+ * 扫描项目中的 IPC 和 Event 定义文件，自动生成：
+ * 1. preload.ts — contextBridge 桥接文件，暴露 IPC 调用和事件监听到渲染进程
+ * 2. electron.d.ts — 类型定义文件，为 window.elec 提供完整的类型提示
+ */
+declare class EasyPreloadGenerator {
+    private readonly config;
+    private readonly logger;
+    constructor(config: EasyPreloadGeneratorConfig);
+    /**
+     * 执行生成，扫描 IPC 和 Event 定义文件，输出 preload 和类型文件
+     */
+    generate(): void;
+    /**
+     * 扫描 IPC 定义文件
+     */
+    private scanIpc;
+    /**
+     * 扫描 Event 定义文件
+     */
+    private scanEvents;
+    /**
+     * 生成 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) => { ... } },
+     *   },
+     * })
+     * ```
+     */
+    private generatePreload;
+    /**
+     * 生成 preload 中的 IPC 调用代码
+     *
+     * 无模块的处理器直接放在顶层，有模块的嵌套在模块名对象下。
+     * 根据 handlerType 选择 invoke（handle/handleOnce）或 send（on/once）。
+     */
+    private generatePreloadIpc;
+    /**
+     * 生成单个 IPC 方法的 preload 代码
+     *
+     * @param name 方法名
+     * @param channel IPC 通道名
+     * @param handler 处理器信息
+     * @returns 方法代码字符串（不含尾部逗号）
+     */
+    private generatePreloadIpcMethod;
+    /**
+     * 生成 preload 中的事件监听代码
+     *
+     * 所有事件嵌套在 `events` 对象下。
+     * 无模块的事件直接放在 events 下，有模块的嵌套在 events.module 下。
+     */
+    private generatePreloadEvents;
+    /**
+     * 生成单个事件的监听/移除方法代码
+     *
+     * 根据 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 缩进字符串
+     */
+    private generatePreloadEventMethods;
+    /**
+     * 生成事件的 remove 方法代码
+     */
+    private generatePreloadRemoveMethods;
+    /**
+     * 生成类型定义文件内容
+     *
+     * 结构:
+     * ```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 {}
+     * ```
+     */
+    private generateTypes;
+    /**
+     * 生成 ElecApi 接口中的 IPC 方法类型
+     */
+    private generateTypesIpc;
+    /**
+     * 生成单个 IPC 方法的类型签名
+     *
+     * @param name 方法名
+     * @param handler 处理器信息
+     * @param lines 输出行数组
+     * @param indent 缩进字符串
+     */
+    private generateTypesIpcMethod;
+    /**
+     * 生成 ElecEvents 接口中的事件方法类型
+     */
+    private generateTypesEvents;
+    /**
+     * 生成单个事件的类型签名（监听 + remove 方法）
+     */
+    private generateTypesEventMethods;
+    /**
+     * 收集所有 IPC 和 Event 定义中引用的类型导入语句
+     *
+     * 将各文件的 imports 映射合并，按模块路径分组，
+     * 生成相对于输出文件的 import type 语句。
+     *
+     * @param ipcDefs IPC 定义列表
+     * @param eventDefs Event 定义列表
+     * @returns import 语句列表
+     */
+    private collectTypeImports;
+    /**
+     * 将源文件中的模块路径转换为相对于输出文件的路径
+     *
+     * 支持三种输入：
+     * - 相对路径（以 . 开头）: 相对于源文件解析后再转换
+     * - 绝对路径: 直接计算相对于输出文件的路径
+     * - 包导入（非相对/绝对路径）: 直接返回
+     *
+     * @param sourceFilePath 源文件绝对路径
+     * @param modulePath 模块路径（相对、绝对或包名）
+     * @returns 相对于输出文件的模块路径
+     */
+    private resolveImportPath;
+    /**
+     * 将事件名转换为 IPC 通道名（camelCase → kebab-case）
+     *
+     * 去掉 on/once 前缀后转换:
+     * - onDownloadProgress → download-progress
+     * - onceReady → ready
+     *
+     * @param name 事件名
+     * @returns 通道名
+     */
+    private toEventChannel;
+    /**
+     * 去掉事件名的 on/once 前缀，返回大写开头的基础名
+     *
+     * - onDownloadProgress → DownloadProgress
+     * - onceReady → Ready
+     *
+     * @param name 事件名
+     * @returns 基础名（首字母大写）
+     */
+    private stripEventPrefix;
+    /**
+     * 确保返回类型被 Promise 包裹
+     *
+     * - 已经是 Promise<T> → 原样返回
+     * - 其他类型 → 包裹为 Promise<T>
+     *
+     * @param returnType 原始返回类型
+     * @returns Promise 包裹后的返回类型
+     */
+    private ensurePromise;
+    /**
+     * 写入文件，自动创建目录
+     */
+    private writeFile;
+}
+
+export { EasyPreloadGenerator };

package/dist/index.d.mts

@@ -0,0 +1,234 @@
+export { EVENT_MODULE_KEY, EventHandlerConfig, EventHandlerMap, IPC_MODULE_KEY, IpcHandleFunction, IpcHandlerConfig, IpcHandlerMap, IpcHandlerValue, IpcOnFunction, defineEvents, defineIpc } from './runtime-entry.mjs';
+import 'electron';
+
+/**
+ * EasyPreload 生成器配置
+ */
+interface EasyPreloadGeneratorConfig {
+    /**
+     * 扫描目录（默认 './electron'）
+     */
+    dir?: string;
+    /**
+     * IPC 源文件匹配模式（支持数组和 glob 格式）
+     * 默认 ['**\/*.ipc.ts']
+     */
+    source?: string | string[];
+    /**
+     * 事件源文件匹配模式（支持数组和 glob 格式）
+     * 默认 ['**\/*.events.ts']
+     */
+    events?: string | string[];
+    /**
+     * 忽略的文件模式（glob 格式）
+     * 默认 ['\*\*\/node_modules\/\*\*', '\*\*\/dist\/\*\*', '\*\*\/dist-electron\/\*\*']
+     */
+    ignores?: string[];
+    /**
+     * preload 输出路径
+     * 默认 ./electron/preload.ts
+     */
+    output: string;
+    /**
+     * 类型定义输出路径
+     * 默认 ./types/electron.d.ts
+     */
+    typesOutput: string;
+    /**
+     * 全局对象名称（默认 'elec'）
+     */
+    globalName?: string;
+    /**
+     * 是否在生成的类型定义中保留方法注释（默认 true）
+     */
+    preserveComments?: boolean;
+}
+
+/**
+ * EasyPreload 生成器
+ *
+ * 扫描项目中的 IPC 和 Event 定义文件，自动生成：
+ * 1. preload.ts — contextBridge 桥接文件，暴露 IPC 调用和事件监听到渲染进程
+ * 2. electron.d.ts — 类型定义文件，为 window.elec 提供完整的类型提示
+ */
+declare class EasyPreloadGenerator {
+    private readonly config;
+    private readonly logger;
+    constructor(config: EasyPreloadGeneratorConfig);
+    /**
+     * 执行生成，扫描 IPC 和 Event 定义文件，输出 preload 和类型文件
+     */
+    generate(): void;
+    /**
+     * 扫描 IPC 定义文件
+     */
+    private scanIpc;
+    /**
+     * 扫描 Event 定义文件
+     */
+    private scanEvents;
+    /**
+     * 生成 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) => { ... } },
+     *   },
+     * })
+     * ```
+     */
+    private generatePreload;
+    /**
+     * 生成 preload 中的 IPC 调用代码
+     *
+     * 无模块的处理器直接放在顶层，有模块的嵌套在模块名对象下。
+     * 根据 handlerType 选择 invoke（handle/handleOnce）或 send（on/once）。
+     */
+    private generatePreloadIpc;
+    /**
+     * 生成单个 IPC 方法的 preload 代码
+     *
+     * @param name 方法名
+     * @param channel IPC 通道名
+     * @param handler 处理器信息
+     * @returns 方法代码字符串（不含尾部逗号）
+     */
+    private generatePreloadIpcMethod;
+    /**
+     * 生成 preload 中的事件监听代码
+     *
+     * 所有事件嵌套在 `events` 对象下。
+     * 无模块的事件直接放在 events 下，有模块的嵌套在 events.module 下。
+     */
+    private generatePreloadEvents;
+    /**
+     * 生成单个事件的监听/移除方法代码
+     *
+     * 根据 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 缩进字符串
+     */
+    private generatePreloadEventMethods;
+    /**
+     * 生成事件的 remove 方法代码
+     */
+    private generatePreloadRemoveMethods;
+    /**
+     * 生成类型定义文件内容
+     *
+     * 结构:
+     * ```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 {}
+     * ```
+     */
+    private generateTypes;
+    /**
+     * 生成 ElecApi 接口中的 IPC 方法类型
+     */
+    private generateTypesIpc;
+    /**
+     * 生成单个 IPC 方法的类型签名
+     *
+     * @param name 方法名
+     * @param handler 处理器信息
+     * @param lines 输出行数组
+     * @param indent 缩进字符串
+     */
+    private generateTypesIpcMethod;
+    /**
+     * 生成 ElecEvents 接口中的事件方法类型
+     */
+    private generateTypesEvents;
+    /**
+     * 生成单个事件的类型签名（监听 + remove 方法）
+     */
+    private generateTypesEventMethods;
+    /**
+     * 收集所有 IPC 和 Event 定义中引用的类型导入语句
+     *
+     * 将各文件的 imports 映射合并，按模块路径分组，
+     * 生成相对于输出文件的 import type 语句。
+     *
+     * @param ipcDefs IPC 定义列表
+     * @param eventDefs Event 定义列表
+     * @returns import 语句列表
+     */
+    private collectTypeImports;
+    /**
+     * 将源文件中的模块路径转换为相对于输出文件的路径
+     *
+     * 支持三种输入：
+     * - 相对路径（以 . 开头）: 相对于源文件解析后再转换
+     * - 绝对路径: 直接计算相对于输出文件的路径
+     * - 包导入（非相对/绝对路径）: 直接返回
+     *
+     * @param sourceFilePath 源文件绝对路径
+     * @param modulePath 模块路径（相对、绝对或包名）
+     * @returns 相对于输出文件的模块路径
+     */
+    private resolveImportPath;
+    /**
+     * 将事件名转换为 IPC 通道名（camelCase → kebab-case）
+     *
+     * 去掉 on/once 前缀后转换:
+     * - onDownloadProgress → download-progress
+     * - onceReady → ready
+     *
+     * @param name 事件名
+     * @returns 通道名
+     */
+    private toEventChannel;
+    /**
+     * 去掉事件名的 on/once 前缀，返回大写开头的基础名
+     *
+     * - onDownloadProgress → DownloadProgress
+     * - onceReady → Ready
+     *
+     * @param name 事件名
+     * @returns 基础名（首字母大写）
+     */
+    private stripEventPrefix;
+    /**
+     * 确保返回类型被 Promise 包裹
+     *
+     * - 已经是 Promise<T> → 原样返回
+     * - 其他类型 → 包裹为 Promise<T>
+     *
+     * @param returnType 原始返回类型
+     * @returns Promise 包裹后的返回类型
+     */
+    private ensurePromise;
+    /**
+     * 写入文件，自动创建目录
+     */
+    private writeFile;
+}
+
+export { EasyPreloadGenerator };

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+export { EVENT_MODULE_KEY, EventHandlerConfig, EventHandlerMap, IPC_MODULE_KEY, IpcHandleFunction, IpcHandlerConfig, IpcHandlerMap, IpcHandlerValue, IpcOnFunction, defineEvents, defineIpc } from './runtime-entry.js';
+import 'electron';
+
+/**
+ * EasyPreload 生成器配置
+ */
+interface EasyPreloadGeneratorConfig {
+    /**
+     * 扫描目录（默认 './electron'）
+     */
+    dir?: string;
+    /**
+     * IPC 源文件匹配模式（支持数组和 glob 格式）
+     * 默认 ['**\/*.ipc.ts']
+     */
+    source?: string | string[];
+    /**
+     * 事件源文件匹配模式（支持数组和 glob 格式）
+     * 默认 ['**\/*.events.ts']
+     */
+    events?: string | string[];
+    /**
+     * 忽略的文件模式（glob 格式）
+     * 默认 ['\*\*\/node_modules\/\*\*', '\*\*\/dist\/\*\*', '\*\*\/dist-electron\/\*\*']
+     */
+    ignores?: string[];
+    /**
+     * preload 输出路径
+     * 默认 ./electron/preload.ts
+     */
+    output: string;
+    /**
+     * 类型定义输出路径
+     * 默认 ./types/electron.d.ts
+     */
+    typesOutput: string;
+    /**
+     * 全局对象名称（默认 'elec'）
+     */
+    globalName?: string;
+    /**
+     * 是否在生成的类型定义中保留方法注释（默认 true）
+     */
+    preserveComments?: boolean;
+}
+
+/**
+ * EasyPreload 生成器
+ *
+ * 扫描项目中的 IPC 和 Event 定义文件，自动生成：
+ * 1. preload.ts — contextBridge 桥接文件，暴露 IPC 调用和事件监听到渲染进程
+ * 2. electron.d.ts — 类型定义文件，为 window.elec 提供完整的类型提示
+ */
+declare class EasyPreloadGenerator {
+    private readonly config;
+    private readonly logger;
+    constructor(config: EasyPreloadGeneratorConfig);
+    /**
+     * 执行生成，扫描 IPC 和 Event 定义文件，输出 preload 和类型文件
+     */
+    generate(): void;
+    /**
+     * 扫描 IPC 定义文件
+     */
+    private scanIpc;
+    /**
+     * 扫描 Event 定义文件
+     */
+    private scanEvents;
+    /**
+     * 生成 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) => { ... } },
+     *   },
+     * })
+     * ```
+     */
+    private generatePreload;
+    /**
+     * 生成 preload 中的 IPC 调用代码
+     *
+     * 无模块的处理器直接放在顶层，有模块的嵌套在模块名对象下。
+     * 根据 handlerType 选择 invoke（handle/handleOnce）或 send（on/once）。
+     */
+    private generatePreloadIpc;
+    /**
+     * 生成单个 IPC 方法的 preload 代码
+     *
+     * @param name 方法名
+     * @param channel IPC 通道名
+     * @param handler 处理器信息
+     * @returns 方法代码字符串（不含尾部逗号）
+     */
+    private generatePreloadIpcMethod;
+    /**
+     * 生成 preload 中的事件监听代码
+     *
+     * 所有事件嵌套在 `events` 对象下。
+     * 无模块的事件直接放在 events 下，有模块的嵌套在 events.module 下。
+     */
+    private generatePreloadEvents;
+    /**
+     * 生成单个事件的监听/移除方法代码
+     *
+     * 根据 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 缩进字符串
+     */
+    private generatePreloadEventMethods;
+    /**
+     * 生成事件的 remove 方法代码
+     */
+    private generatePreloadRemoveMethods;
+    /**
+     * 生成类型定义文件内容
+     *
+     * 结构:
+     * ```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 {}
+     * ```
+     */
+    private generateTypes;
+    /**
+     * 生成 ElecApi 接口中的 IPC 方法类型
+     */
+    private generateTypesIpc;
+    /**
+     * 生成单个 IPC 方法的类型签名
+     *
+     * @param name 方法名
+     * @param handler 处理器信息
+     * @param lines 输出行数组
+     * @param indent 缩进字符串
+     */
+    private generateTypesIpcMethod;
+    /**
+     * 生成 ElecEvents 接口中的事件方法类型
+     */
+    private generateTypesEvents;
+    /**
+     * 生成单个事件的类型签名（监听 + remove 方法）
+     */
+    private generateTypesEventMethods;
+    /**
+     * 收集所有 IPC 和 Event 定义中引用的类型导入语句
+     *
+     * 将各文件的 imports 映射合并，按模块路径分组，
+     * 生成相对于输出文件的 import type 语句。
+     *
+     * @param ipcDefs IPC 定义列表
+     * @param eventDefs Event 定义列表
+     * @returns import 语句列表
+     */
+    private collectTypeImports;
+    /**
+     * 将源文件中的模块路径转换为相对于输出文件的路径
+     *
+     * 支持三种输入：
+     * - 相对路径（以 . 开头）: 相对于源文件解析后再转换
+     * - 绝对路径: 直接计算相对于输出文件的路径
+     * - 包导入（非相对/绝对路径）: 直接返回
+     *
+     * @param sourceFilePath 源文件绝对路径
+     * @param modulePath 模块路径（相对、绝对或包名）
+     * @returns 相对于输出文件的模块路径
+     */
+    private resolveImportPath;
+    /**
+     * 将事件名转换为 IPC 通道名（camelCase → kebab-case）
+     *
+     * 去掉 on/once 前缀后转换:
+     * - onDownloadProgress → download-progress
+     * - onceReady → ready
+     *
+     * @param name 事件名
+     * @returns 通道名
+     */
+    private toEventChannel;
+    /**
+     * 去掉事件名的 on/once 前缀，返回大写开头的基础名
+     *
+     * - onDownloadProgress → DownloadProgress
+     * - onceReady → Ready
+     *
+     * @param name 事件名
+     * @returns 基础名（首字母大写）
+     */
+    private stripEventPrefix;
+    /**
+     * 确保返回类型被 Promise 包裹
+     *
+     * - 已经是 Promise<T> → 原样返回
+     * - 其他类型 → 包裹为 Promise<T>
+     *
+     * @param returnType 原始返回类型
+     * @returns Promise 包裹后的返回类型
+     */
+    private ensurePromise;
+    /**
+     * 写入文件，自动创建目录
+     */
+    private writeFile;
+}
+
+export { EasyPreloadGenerator };