@open-editor/server/dist/index.d.ts

internal utils shared across @open-editor packages

import connect from 'connect';

/**
 * 服务器核心配置选项
 *
 * @remarks
 * 本配置定义了服务器启动的基础参数，支持 HTTP/HTTPS 双协议模式，
 * 证书配置遵循 TLS 标准规范，适用于本地开发和生产环境
 */
interface Options {
    /**
     * 项目源码根目录路径
     *
     * @default `process.cwd()` 进程当前工作目录
     *
     * @securityNote 需确保该路径具备可读权限
     */
    rootDir?: string;
    /**
     * HTTPS 安全传输层配置
     *
     * @see [TLS Context Options](https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions)
     *
     * @example
     * {
     *   key: '/path/to/private.key',
     *   cert: '/path/to/certificate.pem'
     * }
     */
    https?: {
        /**
         * PEM 格式的 SSL 私钥文件路径
         *
         * @fileMustExist 文件必须存在且可读
         */
        key: string;
        /**
         * PEM 格式的 SSL 证书文件路径
         *
         * @fileMustExist 文件必须存在且可读
         */
        cert: string;
    };
    /**
     * 自定义编辑器打开处理器
     *
     * @default 使用内置的 `launch-editor` 实现
     *
     * @param file - 需要打开的目标文件路径
     */
    onOpenEditor?(file: string, errorCallback: (errorMessage: string) => void): void;
}
/**
 * 创建并启动应用服务器
 *
 * @param options - 服务器配置参数集
 *
 * @returns 返回包含实际监听端口的 Promise
 *
 * @technicalProcess
 * 1. 初始化应用实例
 * 2. 根据配置创建 HTTP/HTTPS 服务器
 * 3. 动态分配可用端口并启动监听
 *
 * @example
 * ```typescript
 * setupServer({
 *   https: {
 *     key: 'key.pem',
 *     cert: 'cert.pem'
 *   }
 * }).then(port => {
 *   console.log(`Server running on port ${port}`);
 * });
 * ```
 */
declare function setupServer(options?: Options): Promise<number>;

interface OpenEditorMiddlewareOptions {
    /**
     * 项目根目录路径
     *
     * @default process.cwd()
     *
     * @remarks
     * 用于解析文件相对路径的基础目录
     */
    rootDir?: string;
    /**
     * 自定义编辑器打开处理器
     *
     * @remarks
     * 默认使用 launch-editor 库实现
     * 可通过此参数覆盖默认行为
     */
    onOpenEditor?(file: string, errorCallback: (errorMessage: string) => void): void;
}
/**
 * 创建编辑器中间件
 *
 * @param options - 中间件配置选项
 *
 * @returns connect 中间件处理函数
 */
declare function openEditorMiddleware(options?: OpenEditorMiddlewareOptions): connect.NextHandleFunction;

export { OpenEditorMiddlewareOptions, Options, openEditorMiddleware, setupServer };