befly 3.9.37 → 3.9.39

package/tsconfig.json

@@ -1,4 +1,5 @@
 {
+    "extends": "../../tsconfig.base.json",
     "compilerOptions": {
         // 基础配置
         "target": "ESNext",
@@ -39,9 +40,7 @@
 
         // 高级
         "skipLibCheck": true,
-        "allowJs": true,
-        "checkJs": false,
-
+        "allowJs": false,
         // Bun 特定
         "types": ["bun"],
 
@@ -50,6 +49,6 @@
             "@/*": ["./*"]
         }
     },
-    "include": ["**/*.ts", "**/*.js"],
-    "exclude": ["node_modules", "dist", "logs", "temp", "main.single.ts", "**/*.test.ts", "**/*.test.js"]
+    "include": ["**/*.ts"],
+    "exclude": ["node_modules", "dist", "logs", "temp", "tests", "main.single.ts"]
 }

package/types/api.d.ts

@@ -1,16 +1,17 @@
-/**
+/**
  * Befly API 类型定义
  */
 
-import type { BeflyContext } from './befly.js';
-import type { KeyValue, TableDefinition } from './common.js';
-import type { RequestContext } from './context.js';
+import type { BeflyContext } from "./befly.js";
+import type { KeyValue } from "./common.js";
+import type { RequestContext } from "./context.js";
+import type { TableDefinition } from "./validate.js";
 
 /**
  * HTTP 方法类型
  * 支持 GET、POST 或逗号分隔的组合
  */
-export type HttpMethod = 'GET' | 'POST' | 'GET,POST' | 'POST,GET';
+export type HttpMethod = "GET" | "POST" | "GET,POST" | "POST,GET";
 
 /**
  * 用户信息类型
@@ -31,7 +32,7 @@ export interface UserInfo {
  * - 'user': 需要普通用户权限
  * - string[]: 需要特定角色
  */
-export type AuthType = boolean | 'admin' | 'user' | string[];
+export type AuthType = boolean | "admin" | "user" | string[];
 
 /**
  * API 处理器函数类型
@@ -91,12 +92,6 @@ export interface ApiRoute<T = any, R = any> {
      */
     rawBody?: boolean;
 
-    /** 缓存配置（可选，单位：秒） */
-    cache?: number;
-
-    /** 限流配置（可选，格式：次数/秒，如 "10/60" 表示 60秒内10次） */
-    rateLimit?: string;
-
     /** 路由路径（运行时生成） */
     route?: string;
 }

package/types/befly.d.ts

@@ -1,19 +1,19 @@
-/**
+/**
  * Befly 核心框架类型定义
  */
 
-import type { Plugin } from './plugin.js';
-import type { ApiRoute, HttpMethod } from './api.js';
-import type { KeyValue } from './common.js';
-import type { LoggerConfig } from './logger.js';
-import type { Logger } from '../lib/logger.js';
-import type { Jwt } from '../lib/jwt.js';
-import type { Validator } from '../lib/validator.js';
-import type { Database } from 'bun:sqlite';
-import type { DbHelper } from '../lib/dbHelper.js';
-import type { RedisHelper } from '../lib/redisHelper.js';
-import type { Cipher } from '../lib/cipher.js';
-import type { CacheHelper } from '../lib/cacheHelper.js';
+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";
 
 export type { LoggerConfig };
 
@@ -87,6 +87,44 @@ export interface CorsConfig {
     credentials?: string;
 }
 
+/**
+ * 全局请求限流配置（Hook）
+ */
+export interface RateLimitRule {
+    /**
+     * 路由匹配串
+     * - 精确："POST/api/auth/login"
+     * - 前缀："POST/api/auth/*" 或 "/api/auth/*"
+     * - 全量："*"
+     */
+    route: string;
+    /** 窗口期内允许次数 */
+    limit: number;
+    /** 窗口期秒数 */
+    window: number;
+    /** 计数维度（默认 ip） */
+    key?: "ip" | "user" | "ip_user";
+}
+
+export interface RateLimitConfig {
+    /** 是否启用 (0/1) */
+    enable?: number;
+    /** 未命中 rules 时的默认次数（<=0 表示不启用默认规则） */
+    defaultLimit?: number;
+    /** 未命中 rules 时的默认窗口秒数（<=0 表示不启用默认规则） */
+    defaultWindow?: number;
+    /** 默认计数维度（默认 ip） */
+    key?: "ip" | "user" | "ip_user";
+    /**
+     * 直接跳过限流的路由列表（优先级最高）
+     * - 精确："POST/api/health" 或 "/api/health"
+     * - 前缀："POST/api/health/*" 或 "/api/health/*"
+     */
+    skipRoutes?: string[];
+    /** 路由规则列表 */
+    rules?: RateLimitRule[];
+}
+
 /**
  * Befly 构造函数选项（最多 2 级结构）
  */
@@ -120,10 +158,19 @@ export interface BeflyOptions {
     auth?: AuthConfig;
     /** CORS 插件配置 */
     cors?: CorsConfig;
+
+    /** 全局请求限流配置（Hook） */
+    rateLimit?: RateLimitConfig;
     /** 禁用的钩子列表 */
     disableHooks?: string[];
     /** 禁用的插件列表 */
     disablePlugins?: string[];
+
+    /** 是否启用组件钩子扫描（默认 false，仅加载 core hooks） */
+    enableAddonHooks?: boolean;
+
+    /** 是否启用项目钩子扫描（默认 false，仅加载 core hooks） */
+    enableAppHooks?: boolean;
     /** 隐藏的菜单路径列表（不同步到数据库） */
     hiddenMenus?: string[];
     /**

package/types/cache.d.ts

@@ -2,7 +2,7 @@
  * 缓存助手类型定义
  */
 
-import type { BeflyContext } from './befly.js';
+import type { BeflyContext } from "./befly.js";
 
 /**
  * 缓存助手类
@@ -20,10 +20,14 @@ export interface CacheHelper {
     cacheMenus(): Promise<void>;
 
     /**
-     * 缓存所有角色的接口权限到 Redis
-     * 优化：使用 Promise.all 利用 Bun Redis 自动 pipeline 特性
+     * 全量重建所有角色的接口权限缓存
      */
-    cacheRolePermissions(): Promise<void>;
+    rebuildRoleApiPermissions(): Promise<void>;
+
+    /**
+     * 增量刷新单个角色的接口权限缓存
+     */
+    refreshRoleApiPermissions(roleCode: string, apiIds: number[]): Promise<void>;
 
     /**
      * 缓存所有数据（接口、菜单、角色权限）

package/types/common.d.ts

@@ -1,9 +1,17 @@
-/**
+/**
  * Befly 框架通用类型定义
- * Core 专用类型，通用类型请直接从 befly-shared/types 导入
+ * 框架核心通用类型定义
+ */
+
+/**
+ * SQL 值类型
  */
+export type SqlValue = string | number | boolean | null | Date;
 
-import type { SqlValue } from 'befly-shared/types';
+/**
+ * 通用键值对类型
+ */
+export type KeyValue<T = any> = Record<string, T>;
 
 // ============================================
 // SQL 查询相关类型
@@ -12,7 +20,7 @@ import type { SqlValue } from 'befly-shared/types';
 /**
  * WHERE 条件操作符
  */
-export type WhereOperator = '$eq' | '$ne' | '$not' | '$gt' | '$gte' | '$lt' | '$lte' | '$like' | '$notLike' | '$in' | '$notIn' | '$nin' | '$isNull' | '$isNotNull' | '$null' | '$notNull' | '$between' | '$notBetween';
+export type WhereOperator = "$eq" | "$ne" | "$not" | "$gt" | "$gte" | "$lt" | "$lte" | "$like" | "$notLike" | "$in" | "$notIn" | "$nin" | "$isNull" | "$isNotNull" | "$null" | "$notNull" | "$between" | "$notBetween";
 
 /**
  * WHERE 条件类型
@@ -22,7 +30,7 @@ export type WhereConditions = Record<string, any>;
 /**
  * 排序方向
  */
-export type OrderDirection = 'ASC' | 'DESC';
+export type OrderDirection = "ASC" | "DESC";
 
 /**
  * 排序字段
@@ -74,7 +82,7 @@ export type FieldRule = string;
  */
 export interface ParsedFieldRule {
     name: string;
-    type: 'string' | 'number' | 'text' | 'array_string' | 'array_text';
+    type: "string" | "number" | "text" | "array_string" | "array_text";
     min: number | null;
     max: number | null;
     default: any;
@@ -85,12 +93,12 @@ export interface ParsedFieldRule {
 /**
  * 比较运算符
  */
-export type ComparisonOperator = '=' | '>' | '<' | '>=' | '<=' | '!=' | '<>' | 'LIKE' | 'IN' | 'NOT IN' | 'IS NULL' | 'IS NOT NULL';
+export type ComparisonOperator = "=" | ">" | "<" | ">=" | "<=" | "!=" | "<>" | "LIKE" | "IN" | "NOT IN" | "IS NULL" | "IS NOT NULL";
 
 /**
  * JOIN 类型
  */
-export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+export type JoinType = "INNER" | "LEFT" | "RIGHT" | "FULL";
 
 /**
  * JOIN 选项
@@ -98,7 +106,7 @@ export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
  */
 export interface JoinOption {
     /** JOIN 类型，默认 'left' */
-    type?: 'left' | 'right' | 'inner';
+    type?: "left" | "right" | "inner";
     /** 要联接的表名（不支持别名） */
     table: string;
     /** JOIN 条件（如 'order.user_id = user.id'） */

package/types/context.d.ts

@@ -1,8 +1,8 @@
-/**
+/**
  * 请求上下文类型定义
  */
 
-import type { ApiRoute } from './api.js';
+import type { ApiRoute } from "./api.js";
 
 /**
  * 请求上下文接口

package/types/crypto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 加密相关类型定义
+ */
+
+/**
+ * 编码类型
+ */
+export type EncodingType = "hex" | "base64" | "base64url";
+
+/**
+ * 哈希算法类型
+ */
+export type HashAlgorithm = "md5" | "sha1" | "sha256" | "sha512" | "sha384" | "sha224";
+
+/**
+ * 密码哈希选项
+ */
+export interface PasswordHashOptions {
+    algorithm?: "argon2" | "bcrypt";
+    memoryCost?: number;
+    timeCost?: number;
+    [key: string]: any;
+}

package/types/database.d.ts

@@ -1,13 +1,13 @@
-/**
+/**
  * 数据库相关类型定义
  */
 
-import type { SqlValue } from 'befly-shared/types';
-import type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdateType, TypedWhereConditions } from './table';
-import type { JoinOption } from './common';
+import type { SqlValue } from "./common";
+import type { JoinOption } from "./common";
+import type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdateType, TypedWhereConditions } from "./table";
 
 // 重新导出表类型工具
-export type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdateType, SystemFields, BaseTable, InsertType, UpdateType, SelectType, TypedWhereConditions } from './table';
+export type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdateType, SystemFields, BaseTable, InsertType, UpdateType, SelectType, TypedWhereConditions } from "./table";
 
 // ============================================
 // SQL 查询相关类型
@@ -16,7 +16,7 @@ export type { DatabaseTables, TableName, TableType, TableInsertType, TableUpdate
 /**
  * WHERE 条件操作符
  */
-export type WhereOperator = '$eq' | '$ne' | '$not' | '$gt' | '$gte' | '$lt' | '$lte' | '$like' | '$notLike' | '$in' | '$notIn' | '$nin' | '$isNull' | '$isNotNull' | '$null' | '$notNull' | '$between' | '$notBetween';
+export type WhereOperator = "$eq" | "$ne" | "$not" | "$gt" | "$gte" | "$lt" | "$lte" | "$like" | "$notLike" | "$in" | "$notIn" | "$nin" | "$isNull" | "$isNotNull" | "$null" | "$notNull" | "$between" | "$notBetween";
 
 /**
  * WHERE 条件类型
@@ -26,7 +26,7 @@ export type WhereConditions = Record<string, any>;
 /**
  * 排序方向
  */
-export type OrderDirection = 'ASC' | 'DESC';
+export type OrderDirection = "ASC" | "DESC";
 
 /**
  * 排序字段
@@ -199,7 +199,7 @@ export type UpdateData = Record<string, SqlValue>;
 /**
  * 数据库类型
  */
-export type DbType = 'mysql' | 'postgresql' | 'sqlite';
+export type DbType = "mysql" | "postgresql" | "sqlite";
 
 /**
  * 列信息
@@ -258,7 +258,7 @@ export interface DbHelper {
      * 查询记录数（类型安全版本）
      * @template K - 表名类型
      */
-    getCount<K extends TableName>(options: Omit<TypedQueryOptions<K>, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number>;
+    getCount<K extends TableName>(options: Omit<TypedQueryOptions<K>, "fields" | "page" | "limit" | "orderBy">): Promise<number>;
 
     /**
      * 查询单条数据（类型安全版本）
@@ -279,7 +279,7 @@ export interface DbHelper {
      * @template K - 表名类型
      * @returns 返回类型自动推断为对应表的记录数组
      */
-    getAll<K extends TableName>(options: Omit<TypedQueryOptions<K>, 'page' | 'limit'>): Promise<AllResult<TableType<K>>>;
+    getAll<K extends TableName>(options: Omit<TypedQueryOptions<K>, "page" | "limit">): Promise<AllResult<TableType<K>>>;
 
     /**
      * 插入数据（类型安全版本）
@@ -306,7 +306,7 @@ export interface DbHelper {
     /**
      * 查询记录数（兼容版本）
      */
-    getCount(options: Omit<QueryOptions, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number>;
+    getCount(options: Omit<QueryOptions, "fields" | "page" | "limit" | "orderBy">): Promise<number>;
 
     /**
      * 查询单条数据（兼容版本，需手动指定泛型）
@@ -324,7 +324,7 @@ export interface DbHelper {
      * 查询所有数据（兼容版本，需手动指定泛型）
      * @template T - 返回类型
      */
-    getAll<T = any>(options: Omit<QueryOptions, 'page' | 'limit'>): Promise<AllResult<T>>;
+    getAll<T = any>(options: Omit<QueryOptions, "page" | "limit">): Promise<AllResult<T>>;
 
     /**
      * 插入数据（兼容版本）
@@ -359,7 +359,7 @@ export interface DbHelper {
     /**
      * 检查数据是否存在
      */
-    exists(options: Omit<QueryOptions, 'fields' | 'orderBy' | 'page' | 'limit'>): Promise<boolean>;
+    exists(options: Omit<QueryOptions, "fields" | "orderBy" | "page" | "limit">): Promise<boolean>;
 
     /**
      * 检查表是否存在
@@ -374,17 +374,17 @@ export interface DbHelper {
     /**
      * 禁用数据（设置 state=2）
      */
-    disableData(options: Omit<DeleteOptions, 'hard'>): Promise<number>;
+    disableData(options: Omit<DeleteOptions, "hard">): Promise<number>;
 
     /**
      * 启用数据（设置 state=1）
      */
-    enableData(options: Omit<DeleteOptions, 'hard'>): Promise<number>;
+    enableData(options: Omit<DeleteOptions, "hard">): Promise<number>;
 
     /**
      * 硬删除数据（物理删除）
      */
-    delForce(options: Omit<DeleteOptions, 'hard'>): Promise<number>;
+    delForce(options: Omit<DeleteOptions, "hard">): Promise<number>;
 
     /**
      * 自增字段
@@ -399,7 +399,7 @@ export interface DbHelper {
     /**
      * 查询单个字段值
      */
-    getFieldValue<T = any>(options: Omit<QueryOptions, 'fields'> & { field: string }): Promise<T | null>;
+    getFieldValue<T = any>(options: Omit<QueryOptions, "fields"> & { field: string }): Promise<T | null>;
 
     /**
      * 清理数据或 where 条件（默认排除 null 和 undefined）
@@ -454,7 +454,7 @@ export interface IndexInfo {
  */
 export interface FieldChange {
     /** 变更类型 */
-    type: 'length' | 'comment' | 'datatype' | 'default';
+    type: "length" | "comment" | "datatype" | "default";
     /** 当前值 */
     current: any;
     /** 新值 */
@@ -466,7 +466,7 @@ export interface FieldChange {
  */
 export interface IndexAction {
     /** 操作类型：create（创建）或 drop（删除） */
-    action: 'create' | 'drop';
+    action: "create" | "drop";
     /** 索引名称 */
     indexName: string;
     /** 字段名称 */

package/types/hook.d.ts

@@ -2,8 +2,8 @@
  * Befly 钩子系统类型定义
  */
 
-import type { BeflyContext } from './befly.js';
-import type { RequestContext } from './context.js';
+import type { BeflyContext } from "./befly.js";
+import type { RequestContext } from "./context.js";
 
 /**
  * 钩子处理函数类型（串联模式，无 next 参数）

package/types/jwt.d.ts

@@ -0,0 +1,118 @@
+/**
+ * JWT 相关类型定义
+ */
+
+/**
+ * JWT 算法类型
+ */
+export type JwtAlgorithm = "HS256" | "HS384" | "HS512";
+
+/**
+ * JWT Header 接口
+ */
+export interface JwtHeader {
+    alg: JwtAlgorithm;
+    typ: "JWT";
+}
+
+/**
+ * JWT 载荷
+ */
+export interface JwtPayload {
+    /**
+     * 注意：JWT payload 的业务字段来自 `befly.jwt.sign(payload)` 的入参。
+     * 也就是说：你在 sign 时放了什么字段，verify/decode 时就能取到什么字段。
+     *
+     * 另外，JWT 标准 claim（如 iat/exp/nbf/iss/aud/sub/jti）可能由 signer 注入。
+     */
+
+    /** 用户 ID（历史字段：部分代码用 userId） */
+    userId?: string | number;
+
+    /** 用户 ID（推荐字段：部分项目使用 id） */
+    id?: string | number;
+
+    /** 角色编码 */
+    roleCode?: string;
+
+    /** 昵称 */
+    nickname?: string;
+
+    /** 角色类型 */
+    roleType?: string;
+
+    /** 签发时间（秒级或毫秒级取决于实现，当前由底层库决定） */
+    iat?: number;
+
+    /** 过期时间（秒级或毫秒级取决于实现，当前由底层库决定） */
+    exp?: number;
+
+    /** 生效时间 */
+    nbf?: number;
+
+    /** 签发者 */
+    iss?: string;
+
+    /** 受众 */
+    aud?: string | string[];
+
+    /** 主题 */
+    sub?: string;
+
+    /** JWT ID */
+    jti?: string;
+
+    /** 其他自定义字段（由 sign 入参决定） */
+    [key: string]: unknown;
+}
+
+/**
+ * JWT 完整解码结果
+ */
+export interface JwtDecoded {
+    header: JwtHeader;
+    payload: JwtPayload;
+    signature: string;
+}
+
+/**
+ * JWT 签名选项
+ */
+export interface JwtSignOptions {
+    /** 密钥 */
+    secret?: string;
+    /** 算法 */
+    algorithm?: JwtAlgorithm;
+    /** 过期时间 */
+    expiresIn?: string | number;
+    /** 签发者 */
+    issuer?: string;
+    /** 受众 */
+    audience?: string;
+    /** 主题 */
+    subject?: string;
+    /** 生效时间 */
+    notBefore?: string | number;
+    /** JWT ID */
+    jwtId?: string;
+}
+
+/**
+ * JWT 验证选项
+ */
+export interface JwtVerifyOptions {
+    /** 密钥 */
+    secret?: string;
+    /** 算法列表 */
+    algorithms?: JwtAlgorithm[];
+    /** 签发者 */
+    issuer?: string;
+    /** 受众 */
+    audience?: string;
+    /** 主题 */
+    subject?: string;
+    /** 是否忽略过期 */
+    ignoreExpiration?: boolean;
+    /** 是否忽略生效时间 */
+    ignoreNotBefore?: boolean;
+}

package/types/logger.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 日志相关类型定义
+ */
+
+/**
+ * 日志级别
+ */
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+/**
+ * 日志配置
+ */
+export interface LoggerConfig {
+    /** 是否开启调试模式 (0: 关闭, 1: 开启) @default 0 */
+    debug?: number;
+    /**
+     * 需要在日志中脱敏/排除的字段（仅支持数组）
+     * - 支持模糊匹配："token" 可命中 "accessToken" / "user_token" 等
+     * - 支持后缀匹配："*Secret" 可命中 "mySecret" / "appSecret" 等
+     * - 支持前缀匹配："auth*" 可命中 "authorization" 等
+     * - 支持包含匹配："*token*" 可命中包含 token 的任意 key
+     */
+    excludeFields?: string[];
+    /** 日志目录 @default './logs' */
+    dir?: string;
+    /** 是否输出到控制台 (0: 关闭, 1: 开启) @default 1 */
+    console?: number;
+    /** 单个日志文件最大大小 (MB) @default 10 */
+    maxSize?: number;
+}

package/types/plugin.d.ts

@@ -1,9 +1,9 @@
-/**
+/**
  * Befly 插件系统类型定义
  */
 
-import type { BeflyContext } from './befly.js';
-import type { RequestContext } from './context.js';
+import type { BeflyContext } from "./befly.js";
+import type { RequestContext } from "./context.js";
 
 /**
  * 插件初始化函数类型
@@ -83,7 +83,7 @@ export interface PluginContext {
     endTime?: number;
 
     /** 执行状态 */
-    status: 'pending' | 'running' | 'success' | 'error';
+    status: "pending" | "running" | "success" | "error";
 
     /** 错误信息 */
     error?: Error;

package/types/redis.d.ts

@@ -1,8 +1,8 @@
-/**
+/**
  * Redis 相关类型定义
  */
 
-import { RedisClient as BunRedisClient } from 'bun';
+import { RedisClient as BunRedisClient } from "bun";
 
 /**
  * Redis 客户端类型
@@ -35,7 +35,11 @@ export interface RedisHelper {
     /** 获取字符串值 */
     getString(key: string): Promise<string | null>;
     /** 检查键是否存在 */
-    exists(key: string): Promise<number>;
+    exists(key: string): Promise<boolean>;
+    /** 原子自增 */
+    incr(key: string): Promise<number>;
+    /** 原子自增并在首次自增时设置过期时间 */
+    incrWithExpire(key: string, seconds: number): Promise<number>;
     /** 设置过期时间 */
     expire(key: string, seconds: number): Promise<number>;
     /** 获取剩余过期时间 */