@gylautorun/dev-proxy-cookie 1.0.0 → 1.0.2

package/dist/index.d.ts

@@ -1,7 +1,13 @@
 import * as net from 'net';
 import { IncomingMessage, ServerResponse } from 'http';
-import { ViteDevServer, Plugin } from 'vite';
+import { ViteDevServer } from 'vite';
 
+/**
+ * 错误回调函数类型
+ * @param err - 错误对象
+ * @param req - 请求对象
+ * @param res - 响应对象或 Socket
+ */
 type ErrorCallback = (err: Error, req: IncomingMessage, res: ServerResponse | net.Socket) => void;
 interface ProxyHooks {
     onProxyReq?: (proxyReq: any, req: IncomingMessage, res: ServerResponse) => void;
@@ -16,6 +22,12 @@ interface AutoProxyCookieOptions {
     autoRestart?: boolean;
     restartMarkerFile?: string;
     proxyMap?: Record<string, string>;
+    /**
+     * 需要代理的路径前缀列表（默认代理到 target）
+     * 例如: ['/api', '/digital-platform']
+     * 如果请求路径匹配这些前缀之一，将被代理到 target
+     */
+    proxyPaths?: string[];
     ignorePaths?: string[];
     ws?: boolean;
     changeOrigin?: boolean;
@@ -34,128 +46,432 @@ interface AutoProxyCookieOptions {
         [header: string]: string;
     };
     hooks?: ProxyHooks;
+    /**
+     * 是否启用文件监听
+     * - 'auto': 自动（如果 isDev 为 true，则启用监听）
+     * - true: 强制启用监听
+     * - false: 禁用监听
+     *
+     * 默认值: 'auto'
+     */
+    watch?: 'auto' | boolean;
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
+/**
+ * 自动代理 Cookie 类
+ *
+ * 提供完整的开发环境代理解决方案，支持 HTTP 和 WebSocket 代理，
+ * 自动从文件读取 Cookie 并注入到代理请求中。
+ */
 declare class AutoProxyCookie {
+    /** 合并后的配置选项 */
     private options;
+    /** 当前 Cookie 值 */
     private currentCookie;
+    /** Vite 开发服务器实例 */
     private server;
+    /** HTTP 代理服务器实例 */
     private proxyServer;
+    /** Cookie 文件监听器 */
     private watcher;
+    /** Cookie 文件读取器 */
     private cookieReader;
+    /**
+     * 构造函数
+     * @param options - 配置选项
+     */
     constructor(options: AutoProxyCookieOptions);
+    /**
+     * Cookie 变化处理函数
+     * @param newCookie - 新的 Cookie 值
+     */
     private handleCookieChange;
+    /**
+     * 根据请求路径获取代理目标 URL
+     * @param req - HTTP 请求对象
+     * @returns 代理目标 URL
+     */
     private getProxyUrl;
+    /**
+     * 判断路径是否应该被忽略（不代理）
+     * @param pathname - 请求路径
+     * @returns 是否忽略
+     */
     private isIgnoredPath;
+    /**
+     * 日志输出函数
+     * @param level - 日志级别
+     * @param args - 日志参数
+     */
     private log;
+    /**
+     * 创建代理服务器配置选项
+     * @param target - 代理目标地址
+     * @returns 代理服务器配置
+     */
     private createProxyOptions;
+    /**
+     * 代理请求处理函数
+     * @param proxyReq - 代理请求对象
+     * @param req - 原始请求对象
+     * @param res - 响应对象
+     * @param _options - 服务器选项
+     */
     private handleOnProxyReq;
+    /**
+     * 代理响应处理函数
+     * @param proxyRes - 代理响应对象
+     * @param req - 原始请求对象
+     * @param res - 响应对象
+     */
     private handleOnProxyRes;
+    /**
+     * HTTP 代理错误处理函数
+     * @param err - 错误对象
+     * @param req - 请求对象
+     * @param res - 响应对象或 Socket
+     */
     private handleOnError;
+    /**
+     * WebSocket 代理错误处理函数
+     * @param err - 错误对象
+     * @param req - 请求对象
+     * @param socket - WebSocket 连接的 Socket
+     */
     private handleOnWsError;
+    /**
+     * 初始化代理中间件
+     * @param server - Vite 开发服务器实例
+     */
     setup(server: ViteDevServer): Promise<void>;
+    /**
+     * 启动 Cookie 文件监听
+     */
     private startFileWatch;
+    /**
+     * 停止代理服务
+     */
     stop(): void;
+    /**
+     * 获取当前 Cookie 值
+     * @returns 当前 Cookie 字符串
+     */
     getCurrentCookie(): string;
 }
+/**
+ * 创建 AutoProxyCookie 实例
+ * @param options - 配置选项
+ * @returns AutoProxyCookie 实例
+ */
 declare function createAutoProxyCookie(options: AutoProxyCookieOptions): AutoProxyCookie;
 
-interface ViteAutoProxyCookiePluginOptions extends AutoProxyCookieOptions {
-    name?: string;
-}
-declare function viteAutoProxyCookie(options: ViteAutoProxyCookiePluginOptions): Plugin;
-
-interface ViteDevProxyCookieOptions {
+/**
+ * Vite 中间件代理 Cookie 插件配置选项
+ */
+interface ViteMiddlewareProxyOptions {
+    /** Cookie 文件路径 */
     cookieFile: string;
+    /** 默认代理目标地址 */
+    target: string;
+    /** 是否启用调试日志 */
     debug?: boolean;
-    onCookieChange?: (cookie: string) => void;
+    /**
+     * 代理路径映射表
+     * 键：路径前缀，值：代理目标地址
+     */
+    proxyMap?: Record<string, string>;
+    /**
+     * 需要代理的路径前缀列表（使用默认 target）
+     */
+    proxyPaths?: string[];
+    /**
+     * 需要忽略的路径前缀列表（不代理）
+     */
+    ignorePaths?: string[];
 }
-declare function viteDevProxyCookie(options: ViteDevProxyCookieOptions): Plugin;
+/**
+ * 创建 Vite 中间件代理 Cookie 插件
+ *
+ * @param options - 插件配置选项
+ * @returns Vite 插件对象
+ */
+declare function viteMiddlewareProxy(options: ViteMiddlewareProxyOptions): any;
+
+/**
+ * Vue CLI 代理配置模块
+ *
+ * 提供 Vue CLI 开发服务器的代理配置功能，支持从文件读取 Cookie 并注入代理请求。
+ * 核心函数包括 createFileCookieGetter 和 createVueProxyConfig。
+ *
+ * @module vue-proxy-config
+ */
 
 /** Options for {@link createFileCookieGetter}. */
 interface CreateFileCookieGetterOptions {
     /**
-     * Watch the file for logging when it changes. Cookie value is always read from disk on each proxy request,
-     * so you do not need a dev-server restart when this is false.
-     * @default true
+     * 是否监听文件变化
+     * - true: 始终监听
+     * - false: 从不监听
+     * - 'auto': 根据环境自动判断（默认）
+     *
+     * Cookie 值每次代理请求时都会从磁盘读取，因此即使 watch 为 false，
+     * 修改 cookie 文件后也不需要重启开发服务器。
+     * @default 'auto'
      */
-    watch?: boolean;
+    watch?: boolean | 'auto';
     /** Log when the cookie file changes (only if `watch` is true). @default false */
     debug?: boolean;
+    /**
+     * 自定义生产环境变量名称列表，用于判断是否禁用监听
+     * 例如: ['MY_APP_ENV', 'BUILD_TYPE']
+     */
+    productionEnvs?: string[];
+    /**
+     * 是否为开发环境（优先级最高）
+     * 设置此参数后，将直接决定是否启用文件监听：
+     * - true: 启用监听（开发模式）
+     * - false: 禁用监听（生产模式）
+     *
+     * 使用示例: isDev: process.env.NODE_ENV === 'development'
+     */
+    isDev?: boolean;
 }
+/**
+ * Vue 代理配置选项
+ */
 interface VueProxyConfigOptions {
+    /** Cookie 获取函数 */
     getCookie?: () => string;
+    /** 是否输出调试日志 */
     debug?: boolean;
+    /** 自定义请求头 */
     headers?: Record<string, string>;
+    /** 是否启用 WebSocket 代理 */
     ws?: boolean;
+    /** 是否修改请求头中的 Origin */
     changeOrigin?: boolean;
+    /** 是否验证 SSL 证书 */
     secure?: boolean;
+    /** 错误回调函数 */
     onError?: (err: Error) => void;
 }
+/**
+ * Vue CLI 代理配置接口
+ *
+ * 符合 Vue CLI 代理配置格式的对象结构
+ */
 interface ProxyConfig {
+    /** 是否启用 WebSocket 代理 */
     ws: boolean;
+    /** 代理目标地址 */
     target: string;
+    /** 是否修改请求头中的 Origin */
     changeOrigin: boolean;
+    /** 是否验证 SSL 证书 */
     secure: boolean;
+    /** 代理请求前的回调函数 */
     onProxyReq: (proxyReq: any, req: IncomingMessage) => void;
+    /** 代理响应后的回调函数（可选） */
     onProxyRes?: (proxyRes: any, req: IncomingMessage) => void;
+    /** 错误处理回调函数 */
     onError: (err: Error) => void;
+    /** 自定义请求头 */
     headers?: Record<string, string>;
 }
+/**
+ * 创建 Vue CLI 代理配置
+ *
+ * @param target - 代理目标地址
+ * @param options - 配置选项
+ * @returns Vue CLI 代理配置对象
+ */
 declare function createVueProxyConfig(target: string, options?: VueProxyConfigOptions): ProxyConfig;
+/**
+ * 创建文件 Cookie 获取器
+ *
+ * 从指定文件读取 Cookie 值，支持文件监听功能。
+ *
+ * @param cookieFile - Cookie 文件路径
+ * @param options - 配置选项
+ * @returns Cookie 获取函数
+ */
 declare function createFileCookieGetter(cookieFile: string, options?: CreateFileCookieGetterOptions): () => string;
+/**
+ * 自动代理配置选项
+ */
 interface AutoProxyConfigOptions extends VueProxyConfigOptions {
+    /** 代理目标地址 */
     target: string;
+    /** 忽略的路径列表（不代理这些路径） */
     ignorePaths?: string[];
+    /** 包含的路径列表（只代理这些路径） */
     includePaths?: string[];
+    /** 额外的代理配置 */
     additionalProxies?: Record<string, string>;
 }
+/**
+ * 创建自动代理配置
+ *
+ * 根据配置自动生成 Vue CLI 代理配置对象，支持忽略路径和包含路径两种模式。
+ *
+ * @param options - 配置选项
+ * @returns Vue CLI 代理配置对象映射
+ */
 declare function createAutoProxyConfig(options: AutoProxyConfigOptions): Record<string, ProxyConfig>;
 
-interface UnifiedProxyCookieOptions {
-    cookieFile: string;
-    target?: string;
-    debug?: boolean;
-    autoRestart?: boolean;
-    restartMarkerFile?: string;
-    proxyMap?: Record<string, string>;
-    ignorePaths?: string[];
-    includePaths?: string[];
-    onCookieChange?: (cookie: string) => void;
-    mode?: 'auto' | 'proxy' | 'cookie';
-}
-declare function createDevProxyCookie(options: UnifiedProxyCookieOptions): Plugin;
-declare function getViteVersion(): string | null;
-declare function getViteMajorVersion(): number;
-
+/**
+ * Cookie 读取器配置选项
+ */
 interface CookieReaderOptions {
     cookieFile: string;
     encoding?: BufferEncoding;
 }
+/**
+ * Cookie 文件读取器类
+ *
+ * 提供从文件读取 Cookie 的功能，支持注释过滤和自动文件创建。
+ */
 declare class CookieReader {
+    /** 配置选项 */
     protected options: CookieReaderOptions;
-    constructor(options: CookieReaderOptions);
+    /** 是否启用调试模式 */
+    protected debug: boolean;
+    /**
+     * 构造函数
+     * @param options - 配置选项
+     * @param debug - 是否启用调试模式
+     */
+    constructor(options: CookieReaderOptions, debug?: boolean);
+    /**
+     * 读取 Cookie 文件内容
+     *
+     * 支持过滤注释行（以 # 开头）和空行，将有效行用分号连接。
+     *
+     * @returns Cookie 字符串
+     */
     readCookie(): string;
+    /**
+     * 确保 Cookie 文件存在
+     *
+     * 如果文件不存在，会自动创建空文件。
+     * 如果父目录不存在，会自动创建目录。
+     */
     ensureCookieFile(): void;
 }
+/**
+ * 创建 Cookie 获取器函数
+ *
+ * 返回一个函数，每次调用时从文件读取最新的 Cookie 值。
+ *
+ * @param cookieFile - Cookie 文件路径
+ * @returns Cookie 获取函数
+ */
 declare function createCookieGetter(cookieFile: string): () => string;
 
+/**
+ * Cookie 监听器配置选项
+ */
 interface CookieWatcherOptions {
     cookieFile: string;
     onCookieChange: (cookie: string) => void;
     onError?: (error: Error) => void;
     autoCreateFile?: boolean;
 }
+/**
+ * Cookie 文件监听器类
+ *
+ * 使用 chokidar 监听 Cookie 文件变化，当文件内容改变时触发回调。
+ * 支持自动创建文件和稳定性阈值配置。
+ */
 declare class CookieWatcher {
+    /** 文件监听器实例 */
     private watcher;
+    /** 配置选项 */
     private options;
+    /** Cookie 读取器 */
     private cookieReader;
+    /** 上次读取的 Cookie 内容 */
     private lastContent;
+    /**
+     * 构造函数
+     * @param options - 配置选项
+     */
     constructor(options: CookieWatcherOptions);
+    /**
+     * 文件变化处理函数
+     *
+     * 读取新的 Cookie 内容，如果与上次不同则触发回调。
+     */
     private handleChange;
+    /**
+     * 启动文件监听
+     */
     start(): void;
+    /**
+     * 停止文件监听
+     */
     stop(): void;
+    /**
+     * 获取当前 Cookie 值
+     * @returns 当前 Cookie 字符串
+     */
     getCurrentCookie(): string;
 }
+/**
+ * 创建并启动 Cookie 文件监听器
+ *
+ * @param cookieFile - Cookie 文件路径
+ * @param onCookieChange - Cookie 变化回调函数
+ * @param onError - 错误回调函数（可选）
+ * @returns CookieWatcher 实例
+ */
 declare function watchCookieFile(cookieFile: string, onCookieChange: (cookie: string) => void, onError?: (error: Error) => void): CookieWatcher;
 
-export { type AutoProxyConfigOptions, AutoProxyCookie, type AutoProxyCookieOptions, CookieReader, type CookieReaderOptions, CookieWatcher, type CookieWatcherOptions, type CreateFileCookieGetterOptions, type ErrorCallback, type ProxyConfig, type ProxyHooks, type UnifiedProxyCookieOptions, type ViteAutoProxyCookiePluginOptions, type ViteDevProxyCookieOptions, type VueProxyConfigOptions, createAutoProxyConfig, createAutoProxyCookie, createCookieGetter, createDevProxyCookie, createFileCookieGetter, createVueProxyConfig, getViteMajorVersion, getViteVersion, viteAutoProxyCookie, viteDevProxyCookie, watchCookieFile };
+/**
+ * 环境检测工具模块
+ *
+ * 提供智能环境检测功能，用于判断当前是否为生产构建环境，
+ * 从而决定是否启用文件监听等开发环境特性。
+ *
+ * @module env-detector
+ */
+/**
+ * 判断环境变量值是否表示生产环境
+ *
+ * @param value - 环境变量值
+ * @returns 是否为生产环境值
+ */
+declare function isProductionValue(value: string): boolean;
+/**
+ * 智能检测当前是否为生产构建环境
+ * 通过多种方式综合判断，避免依赖单一环境变量
+ *
+ * @param customEnvs 用户自定义的环境变量名称列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀，用于区分不同模块
+ * @returns 是否为生产环境
+ */
+declare function detectProductionEnvironment(customEnvs?: string[], debug?: boolean, loggerPrefix?: string): boolean;
+/**
+ * 判断是否应该启用文件监听
+ *
+ * 注意：此函数仅在 isDev 参数未设置时调用，用于智能判断环境
+ * 如果用户已通过 isDev 参数明确指定环境，则不会调用此函数
+ *
+ * @param watch 用户设置的 watch 选项
+ * @param customEnvs 用户自定义的环境变量列表
+ * @param debug 是否输出调试日志
+ * @param loggerPrefix 日志前缀
+ * @returns 是否应该启用监听
+ */
+declare function shouldEnableWatch(watch: boolean | 'auto', customEnvs?: string[], debug?: boolean, loggerPrefix?: string): boolean;
+
+export { type AutoProxyConfigOptions, AutoProxyCookie, type AutoProxyCookieOptions, CookieReader, type CookieReaderOptions, CookieWatcher, type CookieWatcherOptions, type CreateFileCookieGetterOptions, type ErrorCallback, type ProxyConfig, type ProxyHooks, type ViteMiddlewareProxyOptions, type VueProxyConfigOptions, createAutoProxyConfig, createAutoProxyCookie, createCookieGetter, createFileCookieGetter, createVueProxyConfig, detectProductionEnvironment, isProductionValue, shouldEnableWatch, viteMiddlewareProxy, watchCookieFile };