befly 3.10.18 → 3.11.1

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

@@ -2,41 +2,33 @@
  * Befly 框架通用类型定义
  * 框架核心通用类型定义
  */
-
 /**
  * SQL 值类型
  */
-export type SqlValue = string | number | boolean | null | Date;
-
+export type SqlValue = string | number | boolean | null | Date | Record<string, any> | any[];
 /**
  * 通用键值对类型
  */
 export type KeyValue<T = any> = Record<string, T>;
-
-// ============================================
-// SQL 查询相关类型
-// ============================================
-
 /**
  * WHERE 条件操作符
  */
 export type WhereOperator = "$eq" | "$ne" | "$not" | "$gt" | "$gte" | "$lt" | "$lte" | "$like" | "$notLike" | "$in" | "$notIn" | "$nin" | "$isNull" | "$isNotNull" | "$null" | "$notNull" | "$between" | "$notBetween";
-
 /**
  * WHERE 条件类型
  */
 export type WhereConditions = Record<string, any>;
-
 /**
  * 排序方向
  */
 export type OrderDirection = "ASC" | "DESC";
-
 /**
  * 排序字段
  */
-export type OrderByField = string | { field: string; direction: OrderDirection };
-
+export type OrderByField = string | {
+    field: string;
+    direction: OrderDirection;
+};
 /**
  * SQL 查询结果
  */
@@ -44,26 +36,18 @@ export interface SqlQuery {
     sql: string;
     params: SqlValue[];
 }
-
 /**
  * 插入数据类型
  */
 export type InsertData = Record<string, SqlValue> | Record<string, SqlValue>[];
-
 /**
  * 更新数据类型
  */
 export type UpdateData = Record<string, SqlValue>;
-
 /**
  * 任意对象类型
  */
 export type AnyObject = Record<string, any>;
-
-// ============================================
-// Core 专用类型（不适合放在 shared 中的类型）
-// ============================================
-
 /**
  * 字段规则字符串（已废弃，保留用于兼容）
  * 格式: "字段名|类型|最小值|最大值|默认值|是否索引|正则约束"
@@ -74,7 +58,6 @@ export type AnyObject = Record<string, any>;
  * "年龄|number|0|150|18|0|null"
  */
 export type FieldRule = string;
-
 /**
  * 解析后的字段规则（已废弃，保留用于兼容）
  *
@@ -89,17 +72,14 @@ export interface ParsedFieldRule {
     index: 0 | 1;
     regex: string | null;
 }
-
 /**
  * 比较运算符
  */
 export type ComparisonOperator = "=" | ">" | "<" | ">=" | "<=" | "!=" | "<>" | "LIKE" | "IN" | "NOT IN" | "IS NULL" | "IS NOT NULL";
-
 /**
  * JOIN 类型
  */
 export type JoinType = "INNER" | "LEFT" | "RIGHT" | "FULL";
-
 /**
  * JOIN 选项
  * 用于简化多表联查的写法
@@ -112,7 +92,6 @@ export interface JoinOption {
     /** JOIN 条件（如 'order.user_id = user.id'） */
     on: string;
 }
-
 /**
  * 工具函数返回类型
  */
@@ -121,17 +100,16 @@ export interface ToolResponse<T = any> {
     data?: T;
     error?: string;
 }
-
 /**
  * 可选字段
  */
 export type Optional<T> = T | null | undefined;
-
 /**
  * 深度可选
  */
-export type DeepPartial<T> = T extends object ? { [P in keyof T]?: DeepPartial<T[P]> } : T;
-
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
 /**
  * 数据库记录基础类型
  */
@@ -142,17 +120,14 @@ export interface BaseRecord {
     deleted_at: Date | null;
     state: number;
 }
-
 /**
  * 异步函数类型
  */
 export type AsyncFunction<T = any> = (...args: any[]) => Promise<T>;
-
 /**
  * 同步函数类型
  */
 export type SyncFunction<T = any> = (...args: any[]) => T;
-
 /**
  * 通用回调函数
  */

package/dist/types/common.js

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

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

@@ -1,17 +1,15 @@
 /**
  * 请求上下文类型定义
  */
-
-import type { ApiRoute } from "./api.ts";
-
+import type { ApiRoute } from "./api";
 /**
  * 请求上下文接口
  */
-export interface RequestContext {
+export interface RequestContext<TBody = Record<string, any>> {
     /** 请求方法 (GET/POST) */
     method: string;
     /** 请求体参数 */
-    body: Record<string, any>;
+    body: TBody;
     /** 用户信息 */
     user: Record<string, any>;
     /** 原始请求对象 */

package/dist/types/context.js

@@ -0,0 +1,4 @@
+/**
+ * 请求上下文类型定义
+ */
+export {};

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

@@ -1,17 +1,14 @@
 /**
  * 加密相关类型定义
  */
-
 /**
  * 编码类型
  */
 export type EncodingType = "hex" | "base64" | "base64url";
-
 /**
  * 哈希算法类型
  */
 export type HashAlgorithm = "md5" | "sha1" | "sha256" | "sha512" | "sha384" | "sha224";
-
 /**
  * 密码哈希选项
  */

package/dist/types/crypto.js

@@ -0,0 +1,4 @@
+/**
+ * 加密相关类型定义
+ */
+export {};

package/dist/types/database.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 数据库操作相关类型定义
+ */
+import type { JoinOption, SqlValue, WhereConditions } from "./common";
+/**
+ * 数据库类型
+ */
+export type DatabaseType = "mysql" | "postgres" | "sqlite";
+/**
+ * 查询选项
+ */
+export interface QueryOptions {
+    /** 表名 */
+    table: string;
+    /** 查询字段 */
+    fields?: string[];
+    /** 查询条件 */
+    where?: WhereConditions;
+    /** 多表联查选项 */
+    joins?: JoinOption[];
+    /** 排序 */
+    orderBy?: string[];
+    /** 页码（从 1 开始） */
+    page?: number;
+    /** 每页数量 */
+    limit?: number;
+}
+/**
+ * 插入选项
+ */
+export interface InsertOptions {
+    /** 表名 */
+    table: string;
+    /** 插入数据 */
+    data: Record<string, SqlValue> | Record<string, SqlValue>[];
+    /** 是否返回插入 ID */
+    returnId?: boolean;
+}
+/**
+ * 更新选项
+ */
+export interface UpdateOptions {
+    /** 表名 */
+    table: string;
+    /** 更新数据 */
+    data: Record<string, SqlValue>;
+    /** 更新条件 */
+    where: WhereConditions;
+}
+/**
+ * 删除选项
+ */
+export interface DeleteOptions {
+    /** 表名 */
+    table: string;
+    /** 删除条件 */
+    where: WhereConditions;
+    /** 是否物理删除（默认逻辑删除） */
+    hard?: boolean;
+}
+/**
+ * SQL 执行信息
+ */
+export interface SqlInfo {
+    sql: string;
+    params: any[];
+    duration: number;
+}
+/**
+ * getList/getAll 的 SQL 信息（count/data 两段）
+ */
+export interface ListSql {
+    count: SqlInfo;
+    data?: SqlInfo;
+}
+/**
+ * 统一返回结构
+ */
+export interface DbResult<T = any, SqlT = SqlInfo> {
+    data: T;
+    sql: SqlT;
+}
+/**
+ * 分页结果
+ */
+export interface ListResult<T = any> {
+    lists: T[];
+    total: number;
+    page: number;
+    limit: number;
+    pages: number;
+}
+/**
+ * 不分页结果（带 total）
+ */
+export interface AllResult<T = any> {
+    lists: T[];
+    total: number;
+}
+/**
+ * 事务回调
+ */
+export type TransactionCallback<T = any> = (db: any) => Promise<T>;
+/**
+ * DbHelper 公开接口（类型层）。
+ *
+ * 说明：runtime 的实现位于 core 内部（dist/lib），但对外类型应只从 `befly/types/*` 获取。
+ * 这里提供一个与实际实现对齐的接口，用于 BeflyContext.db 的类型标注。
+ */
+export interface DbHelper {
+    tableExists(tableName: string): Promise<DbResult<boolean>>;
+    getCount(options: Omit<QueryOptions, "fields" | "page" | "limit" | "orderBy">): Promise<DbResult<number>>;
+    getOne<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<DbResult<T | null>>;
+    getList<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<DbResult<ListResult<T>, ListSql>>;
+    getAll<T extends Record<string, any> = Record<string, any>>(options: Omit<QueryOptions, "page" | "limit">): Promise<DbResult<AllResult<T>, ListSql>>;
+    exists(options: Omit<QueryOptions, "fields" | "orderBy" | "page" | "limit">): Promise<DbResult<boolean>>;
+    getFieldValue<T = any>(options: Omit<QueryOptions, "fields"> & {
+        field: string;
+    }): Promise<DbResult<T | null>>;
+    insData(options: InsertOptions): Promise<DbResult<number>>;
+    insBatch(table: string, dataList: Record<string, any>[]): Promise<DbResult<number[]>>;
+    updData(options: UpdateOptions): Promise<DbResult<number>>;
+    updBatch(table: string, dataList: Array<{
+        id: number;
+        data: Record<string, any>;
+    }>): Promise<DbResult<number>>;
+    delData(options: DeleteOptions): Promise<DbResult<number>>;
+    delForce(options: Omit<DeleteOptions, "hard">): Promise<DbResult<number>>;
+    delForceBatch(table: string, ids: number[]): Promise<DbResult<number>>;
+    enableData(options: Omit<DeleteOptions, "hard">): Promise<DbResult<number>>;
+    disableData(options: Omit<DeleteOptions, "hard">): Promise<DbResult<number>>;
+    query(sql: string, params?: any[]): Promise<DbResult<any>>;
+    unsafe(sqlStr: string, params?: any[]): Promise<DbResult<any>>;
+    trans<T = any>(callback: TransactionCallback<T>): Promise<T>;
+    increment(table: string, field: string, where: WhereConditions, value?: number): Promise<DbResult<number>>;
+    decrement(table: string, field: string, where: WhereConditions, value?: number): Promise<DbResult<number>>;
+    [key: string]: any;
+}

package/dist/types/database.js

@@ -0,0 +1,4 @@
+/**
+ * 数据库操作相关类型定义
+ */
+export {};

package/dist/types/hook.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hook 类型定义
+ *
+ * 说明：当前 core 的 hook 执行模型是“顺序执行 handler(befly, ctx)”，无 next / 洋葱链。
+ */
+import type { BeflyContext } from "./befly";
+import type { RequestContext } from "./context";
+export interface Hook {
+    /** 运行时由 loader 注入（默认导出对象中通常不需要写） */
+    name?: string;
+    /** 是否启用该 Hook；必填（true/false） */
+    enable: boolean;
+    /** 依赖的 hook（按文件名推导的 hookName），用于排序 */
+    deps?: string[];
+    /** hook 处理函数 */
+    handler: (befly: BeflyContext, ctx: RequestContext) => Promise<void> | void;
+}

package/dist/types/hook.js

@@ -0,0 +1,6 @@
+/**
+ * Hook 类型定义
+ *
+ * 说明：当前 core 的 hook 执行模型是“顺序执行 handler(befly, ctx)”，无 next / 洋葱链。
+ */
+export {};

package/dist/types/jwt.d.ts

@@ -0,0 +1,75 @@
+/**
+ * JWT 相关类型定义
+ */
+/**
+ * JWT Payload 类型
+ */
+export interface JwtPayload {
+    /** 用户 ID */
+    id: number;
+    /** 角色代码 */
+    roleCode: string;
+    /** 角色类型 */
+    roleType: string;
+    /** 用户昵称 */
+    nickname: string;
+    /** 过期时间戳 */
+    exp?: number;
+    /** 签发时间 */
+    iat?: number;
+    /** 其他字段 */
+    [key: string]: any;
+}
+/**
+ * JWT header（最常用字段）
+ */
+export interface JwtHeader {
+    alg?: string;
+    typ?: string;
+    kid?: string;
+    [key: string]: any;
+}
+/**
+ * sign() 选项（映射 fast-jwt 的 signer 参数）
+ */
+export interface JwtSignOptions {
+    secret?: string;
+    expiresIn?: string | number;
+    algorithm?: string;
+    issuer?: string;
+    audience?: string | string[];
+    subject?: string;
+    jwtId?: string;
+    notBefore?: number | string;
+}
+/**
+ * verify() 选项（映射 fast-jwt 的 verifier 参数）
+ */
+export interface JwtVerifyOptions {
+    secret?: string;
+    algorithms?: string[];
+    issuer?: string | string[];
+    audience?: string | string[];
+    subject?: string | string[];
+    ignoreExpiration?: boolean;
+    ignoreNotBefore?: boolean;
+}
+/**
+ * decode(complete=true) 返回
+ */
+export interface JwtDecoded {
+    header: JwtHeader;
+    payload: JwtPayload;
+    signature: string;
+}
+/**
+ * Jwt 实例接口（类型层）。
+ *
+ * runtime 实现位于 core 内部，但对外类型应从 `befly/types/*` 获取。
+ */
+export interface Jwt {
+    sign(payload: JwtPayload, options?: JwtSignOptions): string;
+    verify<T = JwtPayload>(token: string, options?: JwtVerifyOptions): T;
+    decode(token: string, complete?: false): JwtPayload;
+    decode(token: string, complete: true): JwtDecoded;
+}

package/dist/types/jwt.js

@@ -0,0 +1,4 @@
+/**
+ * JWT 相关类型定义
+ */
+export {};

package/dist/types/logger.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 日志相关类型定义
+ *
+ * 说明：这里的类型需要与 core/runtime 的 logger 实现保持一致（大量配置项以 0/1 表示开关）。
+ */
+export type LoggerFlag = 0 | 1;
+/**
+ * Logger 插件配置
+ */
+export interface LoggerConfig {
+    /** 是否开启 debug 输出（0/1） */
+    debug?: LoggerFlag;
+    /** 日志目录（相对路径会以初始化 cwd 为锚点解析） */
+    dir?: string;
+    /** 是否输出到控制台（0/1） */
+    console?: LoggerFlag;
+    /** 单文件大小（MB） */
+    maxSize?: number;
+    /** 日志清洗深度限制（1..10） */
+    sanitizeDepth?: number;
+    /** 日志清洗节点数限制（50..20000） */
+    sanitizeNodes?: number;
+    /** 日志对象 key 数量限制（10..5000） */
+    sanitizeObjectKeys?: number;
+    /** 单条字符串最大长度（20..200000） */
+    maxStringLen?: number;
+    /** 数组最大展开元素数（10..5000） */
+    maxArrayItems?: number;
+    /**
+     * 自定义脱敏字段匹配（支持通配，如 *password*）
+     */
+    excludeFields?: string[];
+}
+/**
+ * Logger 接口（类型层）。
+ *
+ * 说明：core/runtime 内部使用的是 Bun 环境的自定义 Logger 实现（异步批量写入）。
+ * 对外只承诺常用的 `info/warn/error/debug` 等调用形式（兼容常见 pino 调用风格）。
+ */
+export interface Logger {
+    info(...args: any[]): any;
+    warn(...args: any[]): any;
+    error(...args: any[]): any;
+    debug(...args: any[]): any;
+    configure(cfg: LoggerConfig): void;
+    setMock(mock: any | null): void;
+    /**
+     * 将当前 buffer 尽快刷入 sink（不会关闭文件句柄）。
+     *
+     * 说明：主要用于测试或进程即将退出前的“尽快落盘”。
+     */
+    flush(): Promise<void>;
+    /**
+     * 刷新并关闭 sink（会关闭文件句柄）。
+     *
+     * 说明：主要用于测试（避免 Windows 句柄占用导致的删除/轮转失败）。
+     */
+    shutdown(): Promise<void>;
+}

package/dist/types/logger.js

@@ -0,0 +1,6 @@
+/**
+ * 日志相关类型定义
+ *
+ * 说明：这里的类型需要与 core/runtime 的 logger 实现保持一致（大量配置项以 0/1 表示开关）。
+ */
+export {};

package/dist/types/plugin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 插件类型定义
+ *
+ * 说明：当前 core 插件的默认导出形态是：{ deps?: string[], handler(ctx): any }
+ */
+import type { BeflyContext } from "./befly";
+export interface Plugin {
+    /** 运行时由 loader 注入（默认导出对象中通常不需要写） */
+    name?: string;
+    /** 是否启用该插件；必填（true/false） */
+    enable: boolean;
+    /** 依赖的插件名（由文件名推导出的插件名），用于排序 */
+    deps?: string[];
+    /** 插件初始化函数（返回会被挂到 befly 上） */
+    handler: (context: BeflyContext) => Promise<any> | any;
+}

package/dist/types/plugin.js

@@ -0,0 +1,6 @@
+/**
+ * 插件类型定义
+ *
+ * 说明：当前 core 插件的默认导出形态是：{ deps?: string[], handler(ctx): any }
+ */
+export {};

package/dist/types/redis.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Redis 助手类型定义
+ */
+/**
+ * Redis Key 类型
+ */
+export type RedisKey = string;
+/**
+ * Redis Value 类型
+ */
+export type RedisValue = string | number | boolean | object | null;
+/**
+ * Redis 配置选项
+ */
+export interface RedisOptions {
+    host: string;
+    port: number;
+    password?: string;
+    db?: number;
+    prefix?: string;
+}
+/**
+ * Redis 助手接口
+ */
+export interface RedisHelper {
+    setObject<T = any>(key: string, obj: T, ttl?: number | null): Promise<string | null>;
+    getObject<T = any>(key: string): Promise<T | null>;
+    delObject(key: string): Promise<void>;
+    genTimeID(): Promise<number>;
+    setString(key: string, value: string, ttl?: number | null): Promise<string | null>;
+    getString(key: string): Promise<string | null>;
+    exists(key: string): Promise<boolean>;
+    incr(key: string): Promise<number>;
+    incrWithExpire(key: string, seconds: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    ttlBatch(keys: string[]): Promise<number[]>;
+    sadd(key: string, members: string[]): Promise<number>;
+    sismember(key: string, member: string): Promise<boolean>;
+    scard(key: string): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    saddBatch(items: Array<{
+        key: string;
+        members: string[];
+    }>): Promise<number>;
+    sismemberBatch(items: Array<{
+        key: string;
+        member: string;
+    }>): Promise<boolean[]>;
+    del(key: string): Promise<number>;
+    delBatch(keys: string[]): Promise<number>;
+    setBatch<T = any>(items: Array<{
+        key: string;
+        value: T;
+        ttl?: number | null;
+    }>): Promise<number>;
+    getBatch<T = any>(keys: string[]): Promise<Array<T | null>>;
+    existsBatch(keys: string[]): Promise<boolean[]>;
+    expireBatch(items: Array<{
+        key: string;
+        seconds: number;
+    }>): Promise<number>;
+    ping(): Promise<string>;
+    [key: string]: any;
+}
+/**
+ * RedisHelper 构造函数类型
+ */
+export interface RedisHelperConstructor {
+    new (prefix?: string): RedisHelper;
+}

package/dist/types/redis.js

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

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

@@ -5,7 +5,6 @@
  * - active/ready 用于全局版本切换与就绪门槛
  * - role meta 用于单角色增量刷新后的可观测性
  */
-
 export type RoleApisCacheMeta = {
     hash: string;
     at: number;
@@ -14,7 +13,6 @@ export type RoleApisCacheMeta = {
     /** 可选：用于和 DB 侧的更新时间做一致性对比 */
     updatedAt?: number;
 };
-
 export type RoleApisRoleMeta = {
     roleCode: string;
     at: number;

package/dist/types/roleApisCache.js

@@ -0,0 +1,8 @@
+/**
+ * 角色接口权限缓存（Redis）元信息类型
+ *
+ * 说明：
+ * - active/ready 用于全局版本切换与就绪门槛
+ * - role meta 用于单角色增量刷新后的可观测性
+ */
+export {};