@mindbase/express-common 1.0.0 → 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,375 @@
+import { Express, Request, Response, NextFunction } from 'express';
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+export { default as dayjs } from 'dayjs';
+import { ZodSchema } from 'zod';
+
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+declare const logger: {
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    startup(tagOrMessage: string, ...args: any[]): void;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+};
+
+/**
+ * IP 解析结果数据结构
+ */
+interface IpInfo {
+    address: string;
+    location: string;
+    country: string;
+    province: string;
+    city: string;
+    isp: string;
+    latitude: string;
+    longitude: string;
+    isLocal: boolean;
+}
+
+interface UaInfo {
+    ua: string;
+    browser: {
+        name?: string;
+        version?: string;
+        major?: string;
+    };
+    engine: {
+        name?: string;
+        version?: string;
+    };
+    os: {
+        name?: string;
+        version?: string;
+    };
+    device: {
+        model?: string;
+        type?: string;
+        vendor?: string;
+    };
+    cpu: {
+        architecture?: string;
+    };
+    isMobile: boolean;
+}
+
+/**
+ * 扫描结果接口
+ */
+interface ScanResult {
+    fileName: string;
+    defaultExport: any;
+    allExports?: any;
+    type: "route" | "middleware" | "schema";
+    filePath: string;
+    /** 缓存命中标志（文档已在数据库） */
+    cacheHit?: boolean;
+}
+
+interface CronConfig {
+    timezone?: string;
+}
+declare function addCron(pattern: string, handler: () => void | Promise<void>, customId?: string): string;
+declare function stopCron(id: string): boolean;
+declare function stopAllCron(): void;
+
+/**
+ * 标准 API 响应结构
+ */
+interface ApiResponse<T = any> {
+    code: number;
+    data: T;
+    msg: string;
+}
+/**
+ * 字段约束规则
+ */
+interface FieldConstraints {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    email?: boolean;
+    url?: boolean;
+    uuid?: boolean;
+    int?: boolean;
+    positive?: boolean;
+    nonnegative?: boolean;
+    custom?: string[];
+}
+/**
+ * 字段验证规则
+ */
+interface FieldValidation {
+    type: "string" | "number" | "boolean" | "array" | "object" | "date" | "file" | "any";
+    required: boolean;
+    optional?: boolean;
+    nullable?: boolean;
+    defaultValue?: any;
+    constraints?: FieldConstraints;
+    items?: FieldValidation;
+    properties?: Record<string, FieldValidation>;
+}
+/**
+ * 请求 Schema 结构
+ */
+interface RequestSchema {
+    target: "body" | "query" | "params";
+    fields: Record<string, FieldValidation>;
+}
+/**
+ * 响应 Schema 结构
+ */
+interface ResponseSchema {
+    description?: string;
+    fields: Record<string, FieldValidation>;
+}
+/**
+ * 路由文档配置
+ */
+interface RouteDocConfig<TRequest = any, TResponse = any> {
+    summary?: string;
+    description?: string;
+    request?: TRequest;
+    response?: TResponse;
+}
+/**
+ * 路由信息接口
+ */
+interface RouteInfo {
+    id?: number;
+    module: string;
+    method: string;
+    path: string;
+    fullPath: string;
+    summary: string;
+    description: string;
+    requestSchema?: RequestSchema;
+    responseSchema?: ResponseSchema;
+    middlewares?: string[];
+    filePath: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * 标记路由文档配置
+ */
+declare function RouteDoc<TRequest = any, TResponse = any>(config: RouteDocConfig<TRequest, TResponse>): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * 模块列表项接口
+ */
+interface ModuleItem {
+    name: string;
+    count: number;
+}
+/**
+ * 文档数据库配置接口
+ */
+interface DocDatabaseConfig {
+    path: string;
+}
+
+interface MindBaseAppOptions {
+    /**
+     * 启动模式:
+     * - normal: 正常启动服务
+     * - sync: 同步数据库 Schema（仅收集）
+     * - migrate: 执行数据库迁移
+     * @default "normal"
+     */
+    mode?: "normal" | "sync" | "migrate";
+    /** 服务监听端口 @default 3000 */
+    port?: number;
+    /** 是否启用请求日志 @default true */
+    logging?: boolean;
+    /** 静态文件目录路径 */
+    staticPath?: string;
+    /** 是否解析 User-Agent 信息 @default true */
+    userAgent?: boolean;
+    /** 是否解析 IP 地理位置信息 @default true */
+    ip?: boolean;
+    /** 是否启用 CORS 跨域 @default true */
+    cors?: boolean;
+    /** API 路由前缀，如 "/api" */
+    apiPrefix?: string;
+    /**
+     * 日志级别（优先级从低到高）:
+     * - debug: 调试信息（显示所有）
+     * - info: 普通信息（隐藏 debug）
+     * - warn: 警告信息（隐藏 debug、info）
+     * - error: 错误信息（隐藏 debug、info、warn）
+     * - silent: 静默模式（隐藏所有）
+     * @default "info"
+     */
+    logLevel?: LogLevel;
+    /** 数据库配置 */
+    database?: {
+        /** SQLite 数据库文件路径 @default "./data/app.db" */
+        path?: string;
+    };
+    /** 认证白名单路径（支持字符串和正则表达式） */
+    authWhitelist?: (string | RegExp)[];
+}
+interface AppState {
+    options: MindBaseAppOptions;
+    express: Express;
+    db?: BetterSQLite3Database<Record<string, any>>;
+    schemas?: Record<string, any>;
+}
+
+/**
+ * MindBase 应用实例
+ */
+interface MindBaseApp {
+    /** 注册插件模块 */
+    use(plugin: any): void;
+    /** 启动应用（初始化数据库、注册路由、启动 HTTP 服务） */
+    startup(): Promise<void>;
+    /** 获取 Express 实例 */
+    getApp(): Express;
+    /** 获取 Drizzle 数据库实例 */
+    getDB(): any;
+    /** 获取应用配置选项 */
+    getOptions(): MindBaseAppOptions;
+}
+/**
+ * 创建 MindBase 应用实例
+ * @param options 应用配置选项
+ * @returns MindBase 应用实例
+ * @example
+ * const app = createApp({
+ *   port: 3000,
+ *   logLevel: "debug",
+ * });
+ * app.use(auth);
+ * await app.startup();
+ */
+declare function createApp(options?: MindBaseAppOptions): MindBaseApp;
+
+/**
+ * 准备命令
+ *
+ * 初始化数据库并预热缓存，但不启动服务器
+ * 用于在构建/初始化阶段准备环境
+ */
+declare function prepare(cwd?: string): Promise<void>;
+declare function precache(cwd?: string): Promise<void>;
+
+interface LightUpModule {
+    install(app: MindBaseApp): Promise<void>;
+    __modulePath: string;
+}
+/**
+ * 创建一个 LightUp 模块
+ * @param install 模块安装函数
+ * @param callerPath 调用者的文件路径（通常是 __filename），如果不提供则尝试通过调用栈获取
+ * @returns LightUp 模块实例
+ * @throws 如果模块创建失败
+ */
+declare function createModule(install: any, callerPath?: string): LightUpModule;
+
+/**
+ * 文档管理器
+ * 管理文档数据，与独立的 SQLite 数据库交互
+ */
+declare class DocManager {
+    private db;
+    private config;
+    constructor(config: DocDatabaseConfig);
+    /**
+     * 初始化数据库
+     */
+    init(): void;
+    /**
+     * 创建表结构
+     */
+    private createTables;
+    /**
+     * 保存路由信息
+     * @param routeInfo 路由信息
+     * @param apiPrefix API 前缀
+     * @param moduleName 模块名称
+     */
+    saveRoute(routeInfo: RouteInfo, apiPrefix: string, moduleName: string): void;
+    /**
+     * 获取模块列表
+     * @returns 模块列表
+     */
+    getModules(): ModuleItem[];
+    /**
+     * 获取路由列表
+     * @param module 模块名称（可选）
+     * @returns 路由列表
+     */
+    getRoutes(module?: string): RouteInfo[];
+    /**
+     * 获取路由详情
+     * @param id 路由 ID
+     * @returns 路由详情
+     */
+    getRouteById(id: number): RouteInfo | null;
+    /**
+     * 清空所有路由数据
+     */
+    clearAllRoutes(): void;
+    /**
+     * 关闭数据库连接
+     */
+    close(): void;
+}
+declare let docManager: DocManager;
+/**
+ * 初始化文档管理器
+ * @param config 配置
+ */
+declare function initDocManager(config: DocDatabaseConfig): DocManager;
+
+/**
+ * 验证位置类型
+ */
+type ValidationTarget = "body" | "query" | "params";
+/**
+ * Zod 验证中间件
+ * @param schema Zod Schema
+ * @param target 验证目标 (默认 body)
+ */
+declare const validate: (schema: ZodSchema, target?: ValidationTarget) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * 创建业务错误
+ * @param code HTTP 状态码
+ * @param msg 错误消息
+ */
+declare function createAppError(code: number, msg: string): Error;
+/**
+ * 便捷工厂函数
+ */
+declare const Errors: {
+    badRequest: (msg: string) => Error;
+    unauthorized: (msg: string) => Error;
+    forbidden: (msg: string) => Error;
+    notFound: (msg: string) => Error;
+};
+
+/**
+ * 初始化 SQLite 数据库
+ * @param options 配置选项
+ * @returns 数据库实例
+ * @throws 如果数据库初始化失败
+ */
+declare function initDatabase(options: {
+    schemas: Record<string, any>;
+    dbPath?: string;
+    state?: AppState;
+}): any;
+
+/**
+ * 处理数据库迁移（Schema 同步 + Drizzle Push）
+ * 这是 migrate 模式的核心逻辑
+ */
+declare function handleSchemaMigrate(): Promise<void>;
+
+export { type ApiResponse, type AppState, type CronConfig, type DocDatabaseConfig, DocManager, Errors, type FieldConstraints, type FieldValidation, type IpInfo, type LogLevel, type MindBaseApp, type MindBaseAppOptions, type ModuleItem, type RequestSchema, type ResponseSchema, RouteDoc, type RouteDocConfig, type RouteInfo, type ScanResult, type UaInfo, addCron, createApp, createAppError, createModule, docManager, handleSchemaMigrate, initDatabase, initDocManager, logger, precache, prepare, stopAllCron, stopCron, validate };