befly 3.10.17 → 3.10.19

package/{types → dist/types}/api.d.ts

@@ -1,18 +1,15 @@
 /**
  * Befly API 类型定义
  */
-
-import type { BeflyContext } from "./befly.js";
-import type { KeyValue } from "./common.js";
-import type { RequestContext } from "./context.js";
-import type { TableDefinition } from "./validate.js";
-
+import type { BeflyContext } from "./befly.ts";
+import type { KeyValue } from "./common.ts";
+import type { RequestContext } from "./context.ts";
+import type { TableDefinition } from "./validate.ts";
 /**
  * HTTP 方法类型
  * 支持 GET、POST 或逗号分隔的组合
  */
 export type HttpMethod = "GET" | "POST" | "GET,POST";
-
 /**
  * 用户信息类型
  */
@@ -23,7 +20,6 @@ export interface UserInfo {
     role?: string;
     [key: string]: any;
 }
-
 /**
  * 认证类型
  * - false: 不需要认证
@@ -33,22 +29,19 @@ export interface UserInfo {
  * - string[]: 需要特定角色
  */
 export type AuthType = boolean | "admin" | "user" | string[];
-
 /**
  * API 处理器函数类型
  */
-export type ApiHandler<T = any, R = any> = (befly: BeflyContext, ctx: RequestContext) => Promise<Response | R> | Response | R;
-
+export type ApiHandler<TBody = any, R = any> = (befly: BeflyContext, ctx: RequestContext<TBody>) => Promise<Response | R> | Response | R;
 /**
  * 字段规则定义
  * 键为字段名，值为字段规则字符串
  */
 export type FieldRules = Record<string, string>;
-
 /**
  * API 配置选项
  */
-export interface ApiOptions {
+export interface ApiOptions<TBody = any, R = any> {
     /** HTTP 方法 */
     method: HttpMethod;
     /** 是否需要认证（true/false/角色数组） */
@@ -58,126 +51,95 @@ export interface ApiOptions {
     /** 必填字段 */
     required?: string[];
     /** 处理函数 */
-    handler: ApiHandler;
+    handler: ApiHandler<TBody, R>;
 }
-
 /**
  * API 路由配置
  */
-export interface ApiRoute<T = any, R = any> {
+export interface ApiRoute<TBody = any, R = any> {
     /** 接口名称（必填） */
     name: string;
-
     /** 处理器函数（必填） */
-    handler: ApiHandler<T, R>;
-
+    handler: ApiHandler<TBody, R>;
     /** HTTP 方法（可选，默认 POST，支持逗号分隔多个方法） */
     method?: HttpMethod;
-
-    /** 认证类型（可选，默认 true）
+    /** 认证类型（可选，默认 true)
      * - true: 需要登录
      * - false: 公开访问（无需登录）
      */
     auth?: boolean;
-
     /** 字段定义（验证规则）（可选，默认 {}） */
     fields?: TableDefinition;
-
     /** 必填字段（可选，默认 []） */
     required?: string[];
-
-    /** 是否保留原始请求体（可选，默认 false）
+    /** 是否保留原始请求体（可选，默认 false)
      * - true: 不过滤字段，保留完整请求体（适用于微信回调、webhook 等场景）
      * - false: 根据 fields 定义过滤字段
      */
     rawBody?: boolean;
-
     /** 路由路径（运行时生成） */
     route?: string;
 }
-
 /**
  * API 构建器接口
  */
 export interface ApiBuilder {
     /** 设置 HTTP 方法 */
     method(method: HttpMethod): this;
-
     /** 设置路径 */
     path(path: string): this;
-
     /** 设置描述 */
     description(desc: string): this;
-
     /** 设置认证 */
     auth(auth: AuthType): this;
-
     /** 设置验证规则 */
     rules(rules: KeyValue<string>): this;
-
     /** 设置必填字段 */
     required(fields: string[]): this;
-
     /** 设置处理器 */
-    handler(handler: ApiHandler): this;
-
+    handler<TBody = any, R = any>(handler: ApiHandler<TBody, R>): this;
     /** 构建路由 */
     build(): ApiRoute;
 }
-
 /**
  * API 响应辅助函数
  */
 export interface ApiResponse {
     /** 成功响应 */
     success<T = any>(message: string, data?: T): Response;
-
     /** 失败响应 */
     error(message: string, error?: any): Response;
-
     /** JSON 响应 */
     json<T = any>(data: T, status?: number): Response;
-
     /** 文本响应 */
     text(text: string, status?: number): Response;
-
     /** HTML 响应 */
     html(html: string, status?: number): Response;
-
     /** 重定向 */
     redirect(url: string, status?: number): Response;
 }
-
 /**
  * 路由匹配结果
  */
 export interface RouteMatch {
     /** 路由配置 */
     route: ApiRoute;
-
     /** 路径参数 */
     params: KeyValue<string>;
 }
-
 /**
  * 路由器接口
  */
 export interface Router {
     /** 添加路由 */
     add(route: ApiRoute): void;
-
     /** 匹配路由 */
     match(method: HttpMethod, path: string): RouteMatch | null;
-
     /** 获取所有路由 */
     getRoutes(): ApiRoute[];
-
     /** 删除路由 */
     remove(method: HttpMethod, path: string): boolean;
 }
-
-// ========== API 响应数据类型 ==========
-
 /**
  * 令牌检测响应数据
  */
@@ -189,7 +151,6 @@ export interface TokenCheckData {
     /** 过期时间（秒） */
     expiresIn?: number;
 }
-
 /**
  * 健康检查响应数据
  */

package/dist/types/api.js

@@ -0,0 +1,4 @@
+/**
+ * Befly API 类型定义
+ */
+export {};

package/{types → dist/types}/befly.d.ts

@@ -1,22 +1,15 @@
 /**
  * Befly 核心框架类型定义
  */
-
-import type { CacheHelper } from "../lib/cacheHelper.js";
-import type { Cipher } from "../lib/cipher.js";
-import type { DbHelper } from "../lib/dbHelper.js";
-import type { Jwt } from "../lib/jwt.js";
-import type { Logger } from "../lib/logger.js";
-import type { RedisHelper } from "../lib/redisHelper.js";
-import type { Validator } from "../lib/validator.js";
-import type { ApiRoute, HttpMethod } from "./api.js";
-import type { KeyValue } from "./common.js";
-import type { LoggerConfig } from "./logger.js";
-import type { Plugin } from "./plugin.js";
-import type { Database } from "bun:sqlite";
-
+import type { CacheHelper } from "./cache.ts";
+import type { CipherStatic } from "./cipher.ts";
+import type { KeyValue } from "./common.ts";
+import type { DbHelper } from "./database.ts";
+import type { Jwt } from "./jwt.ts";
+import type { Logger, LoggerConfig } from "./logger.ts";
+import type { RedisHelper } from "./redis.ts";
+import type { ValidatorStatic } from "./validate.ts";
 export type { LoggerConfig };
-
 /**
  * 数据库配置
  */
@@ -38,7 +31,6 @@ export interface DatabaseConfig {
     /** 连接池最大连接数 @default 1 */
     poolMax?: number;
 }
-
 /**
  * Redis 配置
  */
@@ -56,7 +48,6 @@ export interface RedisConfig {
     /** Redis Key 前缀 @default 'befly:' */
     prefix?: string;
 }
-
 /**
  * JWT 配置
  */
@@ -68,7 +59,6 @@ export interface AuthConfig {
     /** 签名算法 @default 'HS256' */
     algorithm?: string;
 }
-
 /**
  * CORS 配置
  */
@@ -86,15 +76,14 @@ export interface CorsConfig {
     /** 是否允许凭证 @default 'true' */
     credentials?: string;
 }
-
 /**
  * 全局请求限流配置（Hook）
  */
 export interface RateLimitRule {
     /**
      * 路由匹配串
-    * - 精确："/api/auth/login"
-    * - 前缀："/api/auth/*"
+     * - 精确："/api/auth/login"
+     * - 前缀："/api/auth/*"
      * - 全量："*"
      */
     route: string;
@@ -105,7 +94,6 @@ export interface RateLimitRule {
     /** 计数维度（默认 ip） */
     key?: "ip" | "user" | "ip_user";
 }
-
 export interface RateLimitConfig {
     /** 是否启用 (0/1) */
     enable?: number;
@@ -124,12 +112,10 @@ export interface RateLimitConfig {
     /** 路由规则列表 */
     rules?: RateLimitRule[];
 }
-
 /**
  * Befly 构造函数选项（最多 2 级结构）
  */
 export interface BeflyOptions {
-    // ========== 核心参数 ==========
     /** 运行环境 ('development' | 'production') @default 'development' */
     nodeEnv?: string;
     /** 应用名称 @default 'Befly App' */
@@ -146,8 +132,6 @@ export interface BeflyOptions {
     bodyLimit?: number;
     /** 时区 @default 'Asia/Shanghai' */
     tz?: string;
-
-    // ========== 插件配置 ==========
     /** 日志插件配置 */
     logger?: LoggerConfig;
     /** 数据库插件配置 */
@@ -158,7 +142,6 @@ export interface BeflyOptions {
     auth?: AuthConfig;
     /** CORS 插件配置 */
     cors?: CorsConfig;
-
     /** 全局请求限流配置（Hook） */
     rateLimit?: RateLimitConfig;
     /** 禁用的钩子列表 */
@@ -166,12 +149,12 @@ export interface BeflyOptions {
     /** 禁用的插件列表 */
     disablePlugins?: string[];
     /**
-        * 禁用的菜单 path 规则（用于菜单同步与加载前过滤）
-        *
-        * 仅支持 Bun.Glob 的 glob pattern 语法与 API（即把每条规则当作 glob 模式匹配菜单 path）。
-        * 示例：
-        * - 精确："/addon/admin/login"
-        * - 通配："/addon/admin/log/*"、"/addon/admin/**"、"**\/login"
+     * 禁用的菜单 path 规则（用于菜单同步与加载前过滤）
+     *
+     * 仅支持 Bun.Glob 的 glob pattern 语法与 API（即把每条规则当作 glob 模式匹配菜单 path）。
+     * 示例：
+     * - 精确："/addon/admin/login"
+     * - 通配："/addon/admin/log/*"、"/addon/admin/**"、"**\/login"
      */
     disableMenus?: string[];
     /**
@@ -182,219 +165,45 @@ export interface BeflyOptions {
     /** 其他插件配置 */
     [key: string]: any;
 }
-
 /**
  * Befly 应用上下文
  * 包含所有插件挂载的实例
  */
 export interface BeflyContext extends KeyValue {
-    // ========== 核心插件 ==========
     /** 数据库助手 */
     db: DbHelper;
-
     /** Redis 助手 */
     redis: RedisHelper;
-
     /** 日志器 */
-    logger: typeof Logger;
-
+    logger: Logger;
     /** 缓存助手 */
     cache: CacheHelper;
-
     /** 工具函数 */
     tool: {
-        Yes: (msg: string, data?: any, other?: Record<string, any>) => { code: 0; msg: string; data: any };
-        No: (msg: string, data?: any, other?: Record<string, any>) => { code: 1; msg: string; data: any };
+        Yes: (msg: string, data?: any, other?: Record<string, any>) => {
+            code: 0;
+            msg: string;
+            data: any;
+        };
+        No: (msg: string, data?: any, other?: Record<string, any>) => {
+            code: 1;
+            msg: string;
+            data: any;
+        };
     };
-
     /** 加密解密 */
-    cipher: typeof Cipher;
-
+    cipher: CipherStatic;
     /** JWT 令牌 */
     jwt: Jwt;
-
     /** 项目配置 */
     config: BeflyOptions;
-
-    // ========== 动态插件 ==========
     /** 组件插件：addon_{addonName}_{pluginName} */
     /** 项目插件：app_{pluginName} */
     [key: string]: any;
 }
-
-/**
- * Befly 核心类
- */
-export interface Befly {
-    /** API 路由映射 */
-    apis: Map<string, ApiRoute>;
-
-    /** 插件列表 */
-    plugins: Plugin[];
-
-    /** 应用上下文 */
-    context: KeyValue;
-
-    /** 应用选项 */
-    appOptions: BeflyOptions;
-
-    /** 日志器 */
-    logger: Logger;
-
-    /** JWT 工具 */
-    jwt: Jwt;
-
-    /** 验证器 */
-    validator: Validator;
-
-    /** SQL 管理器 */
-    sql: DbHelper;
-
-    /** 加密工具 */
-    crypto: Cipher;
-
-    /** 数据库连接 */
-    db: any;
-
-    /** Redis 连接 */
-    redis: any;
-
-    /**
-     * 初始化检查器
-     */
-    initCheck(): Promise<void>;
-
-    /**
-     * 加载插件
-     */
-    loadPlugins(): Promise<void>;
-
-    /**
-     * 加载 API 路由
-     */
-    loadApis(): Promise<void>;
-
-    /**
-     * 启动服务器
-     */
-    start(): Promise<void>;
-
-    /**
-     * 停止服务器
-     */
-    stop(): Promise<void>;
-
-    /**
-     * 处理请求
-     */
-    handleRequest(request: Request): Promise<Response>;
-
-    /**
-     * 注册钩子
-     */
-    use(hook: Function): void;
-
-    /**
-     * 获取配置
-     */
-    getConfig(key: string): any;
-
-    /**
-     * 设置配置
-     */
-    setConfig(key: string, value: any): void;
-}
-
-/**
- * Befly 构造函数类型
- */
-export interface BeflyConstructor {
-    new (options?: BeflyOptions): Befly;
-}
-
-/**
- * 服务器启动选项
- */
-export interface ServerOptions {
-    /** 主机名 */
-    hostname: string;
-
-    /** 端口 */
-    port: number;
-
-    /** 请求处理函数 */
-    fetch: (request: Request) => Promise<Response>;
-
-    /** 错误处理函数 */
-    error?: (error: Error) => Response;
-
-    /** 开发模式 */
-    development?: boolean;
-}
-
-/**
- * 服务器实例
- */
-export interface Server {
-    /** 主机名 */
-    hostname: string;
-
-    /** 端口 */
-    port: number;
-
-    /** 停止服务器 */
-    stop(): Promise<void>;
-
-    /** 重启服务器 */
-    reload(options: ServerOptions): void;
-}
-
-/**
- * 检查函数类型
- */
-export type CheckFunction = (befly: Befly) => Promise<void> | void;
-
-/**
- * 检查结果
- */
-export interface CheckResult {
-    /** 文件名 */
-    filename: string;
-
-    /** 检查名称 */
-    checkName: string;
-
-    /** 是否通过 */
-    passed: boolean;
-
-    /** 执行时间（纳秒） */
-    duration: number;
-
-    /** 错误信息 */
-    error?: Error;
-}
-
-/**
- * 性能统计
- */
-export interface PerformanceStats {
-    /** 启动时间 */
-    startTime: number;
-
-    /** 检查时间 */
-    checkTime: number;
-
-    /** 插件加载时间 */
-    pluginTime: number;
-
-    /** API 加载时间 */
-    apiTime: number;
-
-    /** 总时间 */
-    totalTime: number;
-}
-
 /**
- * 导出 Befly 实例创建函数
+ * Validator 静态类（注入到 ctx 的用法）
+ *
+ * 说明：这不是 befly 默认入口的运行时导出；仅用于在框架内部/插件中提供类型约束。
  */
-export function createBefly(options?: BeflyOptions): Befly;
+export type Validator = ValidatorStatic;

package/dist/types/befly.js

@@ -0,0 +1,4 @@
+/**
+ * Befly 核心框架类型定义
+ */
+export {};

package/{types → dist/types}/cache.d.ts

@@ -1,9 +1,8 @@
 /**
  * 缓存助手类型定义
  */
-
-import type { BeflyContext } from "./befly.js";
-
+import type { DbHelper } from "./database.ts";
+import type { RedisHelper } from "./redis.ts";
 /**
  * 缓存助手类
  * 负责在服务器启动时缓存接口、菜单和角色权限到 Redis
@@ -13,54 +12,45 @@ export interface CacheHelper {
      * 缓存所有接口到 Redis
      */
     cacheApis(): Promise<void>;
-
     /**
      * 缓存所有菜单到 Redis（从数据库读取）
      */
     cacheMenus(): Promise<void>;
-
     /**
      * 全量重建所有角色的接口权限缓存
      */
     rebuildRoleApiPermissions(): Promise<void>;
-
     /**
      * 增量刷新单个角色的接口权限缓存
      */
     refreshRoleApiPermissions(roleCode: string, apiPaths: string[]): Promise<void>;
-
     /**
      * 缓存所有数据（接口、菜单、角色权限）
      */
     cacheAll(): Promise<void>;
-
     /**
      * 获取缓存的所有接口
      * @returns 接口列表
      */
     getApis(): Promise<any[]>;
-
     /**
      * 获取缓存的所有菜单
      * @returns 菜单列表
      */
     getMenus(): Promise<any[]>;
-
     /**
      * 获取角色的接口权限
      * @param roleCode - 角色代码
      * @returns 接口路径列表
      */
     getRolePermissions(roleCode: string): Promise<string[]>;
-
     /**
      * 检查角色是否有指定接口权限
      * @param roleCode - 角色代码
-        * @param apiPath - 接口路径（url.pathname，例如 /api/user/login；与 method 无关）
+     * @param apiPath - 接口路径（url.pathname，例如 /api/user/login；与 method 无关）
      * @returns 是否有权限
      */
     checkRolePermission(roleCode: string, apiPath: string): Promise<boolean>;
-
     /**
      * 删除角色的接口权限缓存
      * @param roleCode - 角色代码
@@ -68,10 +58,12 @@ export interface CacheHelper {
      */
     deleteRolePermissions(roleCode: string): Promise<boolean>;
 }
-
 /**
  * CacheHelper 构造函数类型
  */
 export interface CacheHelperConstructor {
-    new (befly: BeflyContext): CacheHelper;
+    new (deps: {
+        db: DbHelper;
+        redis: RedisHelper;
+    }): CacheHelper;
 }

package/dist/types/cache.js

@@ -0,0 +1,4 @@
+/**
+ * 缓存助手类型定义
+ */
+export {};

package/dist/types/cipher.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cipher 类型定义（对外）。
+ *
+ * 说明：runtime 实现位于 core 内部（dist/lib），但对外类型应只从 `befly/types/*` 获取。
+ * 此处仅描述 Befly 注入的 `befly.cipher`（静态方法集合）。
+ */
+import type { EncodingType, HashAlgorithm, PasswordHashOptions } from "./crypto.ts";
+export interface CipherStatic {
+    md5(data: string | Uint8Array, encoding?: EncodingType): string;
+    hmacMd5(key: string | Uint8Array, data: string | Uint8Array, encoding?: EncodingType): string;
+    sha1(data: string | Uint8Array, encoding?: EncodingType): string;
+    hmacSha1(key: string | Uint8Array, data: string | Uint8Array, encoding?: EncodingType): string;
+    sha256(data: string | Uint8Array, encoding?: EncodingType): string;
+    hmacSha256(key: string | Uint8Array, data: string | Uint8Array, encoding?: EncodingType): string;
+    sha512(data: string | Uint8Array, encoding?: EncodingType): string;
+    hmacSha512(key: string | Uint8Array, data: string | Uint8Array, encoding?: EncodingType): string;
+    rsaSha256(data: string, privateKey: string | Buffer, encoding?: "hex" | "base64" | "base64url"): string;
+    hash(algorithm: HashAlgorithm, data: string | Uint8Array, encoding?: EncodingType): string;
+    hmac(algorithm: HashAlgorithm, key: string | Uint8Array, data: string | Uint8Array, encoding?: EncodingType): string;
+    hashFile(filePath: string, algorithm?: HashAlgorithm, encoding?: EncodingType): Promise<string>;
+    hashPassword(password: string, options?: PasswordHashOptions): Promise<string>;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    base64Encode(data: string): string;
+    base64Decode(data: string): string;
+    randomString(length: number): string;
+    fastHash(data: string | Uint8Array, seed?: number): number;
+}

package/dist/types/cipher.js

@@ -0,0 +1,7 @@
+/**
+ * Cipher 类型定义（对外）。
+ *
+ * 说明：runtime 实现位于 core 内部（dist/lib），但对外类型应只从 `befly/types/*` 获取。
+ * 此处仅描述 Befly 注入的 `befly.cipher`（静态方法集合）。
+ */
+export {};