@esengine/server 4.3.0 → 4.5.0

package/dist/index-lcuKuQsL.d.ts

@@ -1,470 +0,0 @@
-import { Connection } from '@esengine/rpc';
-import { IncomingMessage, ServerResponse } from 'node:http';
-
-/**
- * @zh HTTP 路由类型定义
- * @en HTTP router type definitions
- */
-
-/**
- * @zh HTTP 请求上下文
- * @en HTTP request context
- */
-interface HttpRequest {
-    /**
-     * @zh 原始请求对象
-     * @en Raw request object
-     */
-    raw: IncomingMessage;
-    /**
-     * @zh 请求方法
-     * @en Request method
-     */
-    method: string;
-    /**
-     * @zh 请求路径
-     * @en Request path
-     */
-    path: string;
-    /**
-     * @zh 路由参数（从 URL 路径提取，如 /users/:id）
-     * @en Route parameters (extracted from URL path, e.g., /users/:id)
-     */
-    params: Record<string, string>;
-    /**
-     * @zh 查询参数
-     * @en Query parameters
-     */
-    query: Record<string, string>;
-    /**
-     * @zh 请求头
-     * @en Request headers
-     */
-    headers: Record<string, string | string[] | undefined>;
-    /**
-     * @zh 解析后的 JSON 请求体
-     * @en Parsed JSON body
-     */
-    body: unknown;
-    /**
-     * @zh 客户端 IP
-     * @en Client IP
-     */
-    ip: string;
-}
-/**
- * @zh HTTP 响应工具
- * @en HTTP response utilities
- */
-interface HttpResponse {
-    /**
-     * @zh 原始响应对象
-     * @en Raw response object
-     */
-    raw: ServerResponse;
-    /**
-     * @zh 设置状态码
-     * @en Set status code
-     */
-    status(code: number): HttpResponse;
-    /**
-     * @zh 设置响应头
-     * @en Set response header
-     */
-    header(name: string, value: string): HttpResponse;
-    /**
-     * @zh 发送 JSON 响应
-     * @en Send JSON response
-     */
-    json(data: unknown): void;
-    /**
-     * @zh 发送文本响应
-     * @en Send text response
-     */
-    text(data: string): void;
-    /**
-     * @zh 发送错误响应
-     * @en Send error response
-     */
-    error(code: number, message: string): void;
-}
-/**
- * @zh HTTP 路由处理器
- * @en HTTP route handler
- */
-type HttpHandler = (req: HttpRequest, res: HttpResponse) => void | Promise<void>;
-/**
- * @zh HTTP 中间件函数
- * @en HTTP middleware function
- *
- * @example
- * ```typescript
- * const authMiddleware: HttpMiddleware = async (req, res, next) => {
- *     if (!req.headers.authorization) {
- *         res.error(401, 'Unauthorized');
- *         return;
- *     }
- *     await next();
- * };
- * ```
- */
-type HttpMiddleware = (req: HttpRequest, res: HttpResponse, next: () => Promise<void>) => void | Promise<void>;
-/**
- * @zh 带中间件和超时的路由处理器定义
- * @en Route handler definition with middleware and timeout support
- */
-interface HttpHandlerDefinition {
-    /**
-     * @zh 处理函数
-     * @en Handler function
-     */
-    handler: HttpHandler;
-    /**
-     * @zh 路由级中间件
-     * @en Route-level middlewares
-     */
-    middlewares?: HttpMiddleware[];
-    /**
-     * @zh 路由级超时时间（毫秒），覆盖全局设置
-     * @en Route-level timeout in milliseconds, overrides global setting
-     */
-    timeout?: number;
-}
-/**
- * @zh HTTP 路由方法配置（支持简单处理器或完整定义）
- * @en HTTP route method configuration (supports simple handler or full definition)
- */
-type HttpMethodHandler = HttpHandler | HttpHandlerDefinition;
-/**
- * @zh HTTP 路由方法映射
- * @en HTTP route methods mapping
- */
-interface HttpRouteMethods {
-    GET?: HttpMethodHandler;
-    POST?: HttpMethodHandler;
-    PUT?: HttpMethodHandler;
-    DELETE?: HttpMethodHandler;
-    PATCH?: HttpMethodHandler;
-    OPTIONS?: HttpMethodHandler;
-}
-/**
- * @zh HTTP 路由配置
- * @en HTTP routes configuration
- *
- * @example
- * ```typescript
- * const routes: HttpRoutes = {
- *     // 简单处理器
- *     '/health': (req, res) => res.json({ ok: true }),
- *
- *     // 按方法分开
- *     '/users': {
- *         GET: (req, res) => res.json([]),
- *         POST: (req, res) => res.json({ created: true })
- *     },
- *
- *     // 路由参数
- *     '/users/:id': {
- *         GET: (req, res) => res.json({ id: req.params.id }),
- *         DELETE: {
- *             handler: (req, res) => res.json({ deleted: true }),
- *             middlewares: [authMiddleware],
- *             timeout: 5000
- *         }
- *     }
- * };
- * ```
- */
-type HttpRoutes = Record<string, HttpMethodHandler | HttpRouteMethods>;
-/**
- * @zh CORS 配置
- * @en CORS configuration
- */
-interface CorsOptions {
-    /**
-     * @zh 允许的来源
-     * @en Allowed origins
-     */
-    origin?: string | string[] | boolean;
-    /**
-     * @zh 允许的方法
-     * @en Allowed methods
-     */
-    methods?: string[];
-    /**
-     * @zh 允许的请求头
-     * @en Allowed headers
-     */
-    allowedHeaders?: string[];
-    /**
-     * @zh 是否允许携带凭证
-     * @en Allow credentials
-     */
-    credentials?: boolean;
-    /**
-     * @zh 预检请求缓存时间（秒）
-     * @en Preflight cache max age
-     */
-    maxAge?: number;
-}
-/**
- * @zh HTTP 路由器选项
- * @en HTTP router options
- */
-interface HttpRouterOptions {
-    /**
-     * @zh CORS 配置
-     * @en CORS configuration
-     */
-    cors?: CorsOptions | boolean;
-    /**
-     * @zh 全局请求超时时间（毫秒）
-     * @en Global request timeout in milliseconds
-     */
-    timeout?: number;
-    /**
-     * @zh 全局中间件
-     * @en Global middlewares
-     */
-    middlewares?: HttpMiddleware[];
-}
-
-/**
- * @zh ESEngine Server 类型定义
- * @en ESEngine Server type definitions
- */
-
-/**
- * @zh 服务器配置
- * @en Server configuration
- */
-interface ServerConfig {
-    /**
-     * @zh 监听端口
-     * @en Listen port
-     * @default 3000
-     */
-    port?: number;
-    /**
-     * @zh API 目录路径
-     * @en API directory path
-     * @default 'src/api'
-     */
-    apiDir?: string;
-    /**
-     * @zh 消息处理器目录路径
-     * @en Message handlers directory path
-     * @default 'src/msg'
-     */
-    msgDir?: string;
-    /**
-     * @zh HTTP 路由目录路径
-     * @en HTTP routes directory path
-     * @default 'src/http'
-     *
-     * @zh 文件命名规则：
-     * - `login.ts` → POST /api/login
-     * - `users/[id].ts` → /api/users/:id
-     * - `health.ts` (method: 'GET') → GET /api/health
-     * @en File naming convention:
-     * - `login.ts` → POST /api/login
-     * - `users/[id].ts` → /api/users/:id
-     * - `health.ts` (method: 'GET') → GET /api/health
-     */
-    httpDir?: string;
-    /**
-     * @zh HTTP 路由前缀
-     * @en HTTP routes prefix
-     * @default '/api'
-     */
-    httpPrefix?: string;
-    /**
-     * @zh 游戏 Tick 速率 (每秒)
-     * @en Game tick rate (per second)
-     * @default 20
-     */
-    tickRate?: number;
-    /**
-     * @zh HTTP 路由配置（内联定义，与 httpDir 文件路由合并）
-     * @en HTTP routes configuration (inline definition, merged with httpDir file routes)
-     */
-    http?: HttpRoutes;
-    /**
-     * @zh CORS 配置
-     * @en CORS configuration
-     * @default true
-     */
-    cors?: CorsOptions | boolean;
-    /**
-     * @zh 服务器启动回调
-     * @en Server start callback
-     */
-    onStart?: (port: number) => void;
-    /**
-     * @zh 连接建立回调
-     * @en Connection established callback
-     */
-    onConnect?: (conn: ServerConnection) => void | Promise<void>;
-    /**
-     * @zh 连接断开回调
-     * @en Connection closed callback
-     */
-    onDisconnect?: (conn: ServerConnection) => void | Promise<void>;
-}
-/**
- * @zh 服务器连接（扩展 RPC Connection）
- * @en Server connection (extends RPC Connection)
- */
-interface ServerConnection<TData = Record<string, unknown>> extends Connection<TData> {
-    /**
-     * @zh 连接唯一标识（继承自 Connection）
-     * @en Connection unique identifier (inherited from Connection)
-     */
-    readonly id: string;
-    /**
-     * @zh 用户自定义数据
-     * @en User-defined data
-     */
-    data: TData;
-}
-/**
- * @zh API 处理器上下文
- * @en API handler context
- */
-interface ApiContext<TData = Record<string, unknown>> {
-    /**
-     * @zh 当前连接
-     * @en Current connection
-     */
-    conn: ServerConnection<TData>;
-    /**
-     * @zh 服务器实例
-     * @en Server instance
-     */
-    server: GameServer;
-}
-/**
- * @zh API 定义选项
- * @en API definition options
- */
-interface ApiDefinition<TReq = unknown, TRes = unknown, TData = Record<string, unknown>> {
-    /**
-     * @zh API 处理函数
-     * @en API handler function
-     */
-    handler: (req: TReq, ctx: ApiContext<TData>) => TRes | Promise<TRes>;
-    /**
-     * @zh 请求验证函数（可选）
-     * @en Request validation function (optional)
-     */
-    validate?: (req: unknown) => req is TReq;
-}
-/**
- * @zh 消息处理器上下文
- * @en Message handler context
- */
-interface MsgContext<TData = Record<string, unknown>> {
-    /**
-     * @zh 当前连接
-     * @en Current connection
-     */
-    conn: ServerConnection<TData>;
-    /**
-     * @zh 服务器实例
-     * @en Server instance
-     */
-    server: GameServer;
-}
-/**
- * @zh 消息定义选项
- * @en Message definition options
- */
-interface MsgDefinition<TMsg = unknown, TData = Record<string, unknown>> {
-    /**
-     * @zh 消息处理函数
-     * @en Message handler function
-     */
-    handler: (msg: TMsg, ctx: MsgContext<TData>) => void | Promise<void>;
-}
-/**
- * @zh 游戏服务器接口
- * @en Game server interface
- */
-interface GameServer {
-    /**
-     * @zh 启动服务器
-     * @en Start server
-     */
-    start(): Promise<void>;
-    /**
-     * @zh 停止服务器
-     * @en Stop server
-     */
-    stop(): Promise<void>;
-    /**
-     * @zh 广播消息
-     * @en Broadcast message
-     */
-    broadcast<T>(name: string, data: T): void;
-    /**
-     * @zh 发送消息给指定连接
-     * @en Send message to specific connection
-     */
-    send<T>(conn: ServerConnection, name: string, data: T): void;
-    /**
-     * @zh 获取所有连接
-     * @en Get all connections
-     */
-    readonly connections: ReadonlyArray<ServerConnection>;
-    /**
-     * @zh 当前 Tick
-     * @en Current tick
-     */
-    readonly tick: number;
-    /**
-     * @zh 注册房间类型
-     * @en Define room type
-     */
-    define(name: string, roomClass: new () => unknown): void;
-}
-/**
- * @zh HTTP 请求方法
- * @en HTTP request method
- */
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-/**
- * @zh HTTP 定义选项
- * @en HTTP definition options
- *
- * @example
- * ```typescript
- * // src/http/login.ts
- * import { defineHttp } from '@esengine/server'
- *
- * export default defineHttp({
- *     method: 'POST',
- *     handler: async (req, res) => {
- *         const { username, password } = req.body
- *         // ... authentication logic
- *         res.json({ token: '...', userId: '...' })
- *     }
- * })
- * ```
- */
-interface HttpDefinition<TBody = unknown> {
-    /**
-     * @zh 请求方法
-     * @en Request method
-     * @default 'POST'
-     */
-    method?: HttpMethod;
-    /**
-     * @zh 处理函数
-     * @en Handler function
-     */
-    handler: (req: HttpRequest & {
-        body: TBody;
-    }, res: HttpResponse) => void | Promise<void>;
-}
-
-export type { ApiDefinition as A, CorsOptions as C, GameServer as G, HttpDefinition as H, MsgDefinition as M, ServerConfig as S, HttpRoutes as a, HttpRouterOptions as b, ServerConnection as c, ApiContext as d, MsgContext as e, HttpMethod as f, HttpRequest as g, HttpResponse as h, HttpHandler as i };