befly-shared 1.2.7 → 1.3.0

package/tests/types.test.ts

@@ -1,289 +0,0 @@
-/**
- * befly-shared 类型定义测试
- */
-import { describe, expect, it } from 'bun:test';
-
-import { ApiCode, ErrorMessages } from '../src/constants.js';
-import type { DatabaseConfig, FieldDefinition, HttpMethod, MenuItem, PaginatedResult, RedisConfig, ResponseResult, RoleInfo, UserInfo } from '../types/types.js';
-
-// ValidationResult 在新结构中可能不存在，使用本地定义
-interface ValidationResult {
-    code: 0 | 1;
-    fields: Record<string, string>;
-}
-
-describe('befly-shared 类型定义', () => {
-    describe('ResponseResult 类型', () => {
-        it('成功响应结构正确', () => {
-            const result: ResponseResult<{ id: number }> = {
-                code: 0,
-                msg: '操作成功',
-                data: { id: 1 }
-            };
-            expect(result.code).toBe(0);
-            expect(result.msg).toBe('操作成功');
-            expect(result.data).toEqual({ id: 1 });
-        });
-
-        it('失败响应结构正确', () => {
-            const result: ResponseResult = {
-                code: 1,
-                msg: '操作失败',
-                error: 'Invalid input'
-            };
-            expect(result.code).toBe(1);
-            expect(result.error).toBe('Invalid input');
-        });
-    });
-
-    describe('PaginatedResult 类型', () => {
-        it('分页结果结构正确', () => {
-            const result: PaginatedResult<{ name: string }> = {
-                code: 0,
-                msg: '查询成功',
-                data: [{ name: 'test' }],
-                total: 100,
-                page: 1,
-                limit: 10,
-                pages: 10
-            };
-            expect(result.total).toBe(100);
-            expect(result.pages).toBe(10);
-            expect(result.data).toHaveLength(1);
-        });
-    });
-
-    describe('ValidationResult 类型', () => {
-        it('验证成功结构正确', () => {
-            const result: ValidationResult = {
-                code: 0,
-                fields: {}
-            };
-            expect(result.code).toBe(0);
-        });
-
-        it('验证失败结构正确', () => {
-            const result: ValidationResult = {
-                code: 1,
-                fields: {
-                    email: '邮箱格式不正确',
-                    password: '密码长度不足'
-                }
-            };
-            expect(result.code).toBe(1);
-            expect(Object.keys(result.fields)).toHaveLength(2);
-        });
-    });
-
-    describe('HttpMethod 类型', () => {
-        it('支持所有 HTTP 方法', () => {
-            const methods: HttpMethod[] = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'];
-            expect(methods).toHaveLength(7);
-        });
-    });
-
-    describe('FieldDefinition 类型', () => {
-        it('字段定义结构正确', () => {
-            const field: FieldDefinition = {
-                name: '用户名',
-                detail: '用户登录名',
-                type: 'string',
-                min: 2,
-                max: 50,
-                default: null,
-                index: true,
-                unique: true,
-                comment: '用户名字段',
-                nullable: false,
-                unsigned: false,
-                regexp: '^[a-zA-Z0-9_]+$'
-            };
-            expect(field.type).toBe('string');
-            expect(field.unique).toBe(true);
-        });
-    });
-
-    describe('UserInfo 类型', () => {
-        it('用户信息结构正确', () => {
-            const user: UserInfo = {
-                id: 1,
-                username: 'admin',
-                email: 'admin@example.com',
-                roleCode: 'ADMIN',
-                customField: 'custom value'
-            };
-            expect(user.id).toBe(1);
-            expect(user.customField).toBe('custom value');
-        });
-    });
-
-    describe('DatabaseConfig 类型', () => {
-        it('数据库配置结构正确', () => {
-            const config: DatabaseConfig = {
-                type: 'mysql',
-                host: 'localhost',
-                port: 3306,
-                user: 'root',
-                password: 'password',
-                database: 'befly'
-            };
-            expect(config.type).toBe('mysql');
-            expect(config.port).toBe(3306);
-        });
-    });
-
-    describe('RedisConfig 类型', () => {
-        it('Redis 配置结构正确', () => {
-            const config: RedisConfig = {
-                host: 'localhost',
-                port: 6379,
-                password: 'password',
-                db: 0
-            };
-            expect(config.port).toBe(6379);
-        });
-
-        it('Redis 配置可选字段', () => {
-            const config: RedisConfig = {
-                host: 'localhost',
-                port: 6379
-            };
-            expect(config.password).toBeUndefined();
-            expect(config.db).toBeUndefined();
-        });
-    });
-
-    describe('MenuItem 类型', () => {
-        it('菜单项结构正确', () => {
-            const menu: MenuItem = {
-                id: 1,
-                pid: 0,
-                name: '系统管理',
-                path: '/system',
-                icon: 'Settings',
-                sort: 1,
-                hidden: false,
-                children: [
-                    {
-                        id: 2,
-                        pid: 1,
-                        name: '用户管理',
-                        path: '/system/user',
-                        sort: 1
-                    }
-                ]
-            };
-            expect(menu.children).toHaveLength(1);
-            expect(menu.children![0].pid).toBe(1);
-        });
-    });
-
-    describe('RoleInfo 类型', () => {
-        it('角色信息结构正确', () => {
-            const role: RoleInfo = {
-                id: 1,
-                code: 'ADMIN',
-                name: '管理员',
-                desc: '系统管理员角色'
-            };
-            expect(role.code).toBe('ADMIN');
-        });
-    });
-
-    describe('ApiCode 常量', () => {
-        it('SUCCESS 值为 0', () => {
-            expect(ApiCode.SUCCESS).toBe(0);
-        });
-
-        it('FAIL 值为 1', () => {
-            expect(ApiCode.FAIL).toBe(1);
-        });
-
-        it('UNAUTHORIZED 值为 401', () => {
-            expect(ApiCode.UNAUTHORIZED).toBe(401);
-        });
-
-        it('FORBIDDEN 值为 403', () => {
-            expect(ApiCode.FORBIDDEN).toBe(403);
-        });
-
-        it('NOT_FOUND 值为 404', () => {
-            expect(ApiCode.NOT_FOUND).toBe(404);
-        });
-
-        it('SERVER_ERROR 值为 500', () => {
-            expect(ApiCode.SERVER_ERROR).toBe(500);
-        });
-    });
-
-    describe('ErrorMessages 常量', () => {
-        it('UNAUTHORIZED 消息正确', () => {
-            expect(ErrorMessages.UNAUTHORIZED).toBe('请先登录');
-        });
-
-        it('FORBIDDEN 消息正确', () => {
-            expect(ErrorMessages.FORBIDDEN).toBe('无访问权限');
-        });
-
-        it('NOT_FOUND 消息正确', () => {
-            expect(ErrorMessages.NOT_FOUND).toBe('资源不存在');
-        });
-
-        it('SERVER_ERROR 消息正确', () => {
-            expect(ErrorMessages.SERVER_ERROR).toBe('服务器错误');
-        });
-
-        it('INVALID_PARAMS 消息正确', () => {
-            expect(ErrorMessages.INVALID_PARAMS).toBe('参数错误');
-        });
-
-        it('TOKEN_EXPIRED 消息正确', () => {
-            expect(ErrorMessages.TOKEN_EXPIRED).toBe('Token 已过期');
-        });
-
-        it('TOKEN_INVALID 消息正确', () => {
-            expect(ErrorMessages.TOKEN_INVALID).toBe('Token 无效');
-        });
-    });
-
-    describe('BaseRequestContext 类型', () => {
-        it('请求上下文基础结构正确', () => {
-            // BaseRequestContext 是接口，只验证可以创建符合结构的对象
-            const ctx = {
-                body: { username: 'test' },
-                user: { id: 1 },
-                now: Date.now(),
-                ip: '127.0.0.1',
-                route: 'POST/api/user/login',
-                requestId: 'abc123'
-            };
-            expect(ctx.body.username).toBe('test');
-            expect(ctx.user.id).toBe(1);
-            expect(typeof ctx.now).toBe('number');
-            expect(ctx.ip).toBe('127.0.0.1');
-        });
-    });
-
-    describe('BaseApiRoute 类型', () => {
-        it('API 路由基础结构正确', () => {
-            // BaseApiRoute 是接口，只验证可以创建符合结构的对象
-            const route = {
-                name: '用户登录',
-                method: 'POST' as const,
-                auth: false,
-                fields: {},
-                required: ['username', 'password']
-            };
-            expect(route.name).toBe('用户登录');
-            expect(route.method).toBe('POST');
-            expect(route.auth).toBe(false);
-        });
-
-        it('API 路由最小配置', () => {
-            const route = {
-                name: '测试接口'
-            };
-            expect(route.name).toBe('测试接口');
-        });
-    });
-});

package/types/addon.d.ts

@@ -1,50 +0,0 @@
-/**
- * Addon 配置类型定义
- */
-
-/**
- * Addon 作者信息
- */
-export interface AddonAuthor {
-    /** 作者名称 */
-    name: string;
-    /** 作者邮箱 */
-    email?: string;
-    /** 作者网站 */
-    url?: string;
-}
-
-/**
- * Addon 配置
- */
-export interface AddonConfig {
-    /** Addon 唯一标识（小写、短横线或下划线），例如 "admin"、"demo" */
-    name: string;
-
-    /** Addon 人类可读名称，例如 "管理后台" */
-    title: string;
-
-    /** 版本号（语义化版本），例如 "1.0.0" */
-    version?: string;
-
-    /** 简短描述 */
-    description?: string;
-
-    /** 作者信息 */
-    author?: AddonAuthor | string;
-
-    /** 源码仓库链接 */
-    repo?: string;
-
-    /** 关键词（用于搜索和分类） */
-    keywords?: string[];
-
-    /** 主入口文件路径（相对于 addon 目录），例如 "index.ts" */
-    entry?: string;
-
-    /** 依赖的其他 addon 或核心包 */
-    dependencies?: Record<string, string>;
-
-    /** 许可证 */
-    license?: string;
-}

package/types/addonConfigMerge.d.ts

@@ -1,17 +0,0 @@
-import type { MergeConfigOptions } from './configTypes.js';
-/**
- * Addon 配置合并函数
- * 自动根据调用位置的 package.json 获取 addon 名称，然后加载项目 config 目录下的同名配置文件进行合并
- * @param options - 合并选项
- * @returns 合并后的配置对象
- * @example
- * ```ts
- * // 在 @befly-addon/admin 包中调用
- * const config = await addonConfigMerge();
- * // 自动读取：
- * // 1. @befly-addon/admin/package.json 的 befly 字段
- * // 2. 项目根目录/config/admin.{js,ts,json} 配置文件
- * // 3. 合并后返回
- * ```
- */
-export declare function addonConfigMerge(options?: MergeConfigOptions): Promise<Record<string, any>>;

package/types/addonHelper.d.ts

@@ -1,24 +0,0 @@
-/**
- * 扫描所有可用的 addon
- * 优先从本地 addons/ 目录加载，其次从 node_modules/@befly-addon/ 加载
- * @param cwd - 项目根目录，默认为 process.cwd()
- * @returns addon 名称数组
- */
-export declare const scanAddons: (cwd?: string) => string[];
-/**
- * 获取 addon 的指定子目录路径
- * 优先返回本地 addons 目录，其次返回 node_modules 目录
- * @param name - addon 名称
- * @param subDir - 子目录名称
- * @param cwd - 项目根目录，默认为 process.cwd()
- * @returns 完整路径
- */
-export declare const getAddonDir: (name: string, subDir: string, cwd?: string) => string;
-/**
- * 检查 addon 子目录是否存在
- * @param name - addon 名称
- * @param subDir - 子目录名称
- * @param cwd - 项目根目录，默认为 process.cwd()
- * @returns 是否存在
- */
-export declare const addonDirExists: (name: string, subDir: string, cwd?: string) => boolean;

package/types/api.d.ts

@@ -1,63 +0,0 @@
-/**
- * API 相关类型定义
- */
-
-import type { TableDefinition } from './validate';
-
-/**
- * HTTP 方法类型
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
-
-/**
- * API 响应结果类型
- */
-export interface ResponseResult<T = any> {
-    /** 状态码：0 表示成功，非 0 表示失败 */
-    code: number;
-    /** 响应消息 */
-    msg: string;
-    /** 响应数据 */
-    data?: T;
-    /** 错误信息（仅在失败时） */
-    error?: any;
-}
-
-/**
- * 分页响应结果类型
- */
-export interface PaginatedResult<T = any> {
-    /** 状态码 */
-    code: number;
-    /** 响应消息 */
-    msg: string;
-    /** 数据列表 */
-    data: T[];
-    /** 总记录数 */
-    total: number;
-    /** 当前页码 */
-    page: number;
-    /** 每页数量 */
-    limit: number;
-    /** 总页数 */
-    pages: number;
-}
-
-/**
- * API 路由基础配置
- * 用于跨包共享的最小路由定义
- */
-export interface BaseApiRoute {
-    /** 接口名称（必填） */
-    name: string;
-    /** HTTP 方法（可选，默认 POST） */
-    method?: HttpMethod;
-    /** 认证类型（可选，默认 true） */
-    auth?: boolean;
-    /** 字段定义（验证规则） */
-    fields?: TableDefinition;
-    /** 必填字段 */
-    required?: string[];
-    /** 路由路径（运行时生成） */
-    route?: string;
-}

package/types/arrayKeysToCamel.d.ts

@@ -1,13 +0,0 @@
-/**
- * 数组对象字段名批量转小驼峰
- * @param arr - 源数组
- * @returns 字段名转为小驼峰格式的新数组
- *
- * @example
- * arrayKeysToCamel([
- *   { user_id: 1, user_name: 'John' },
- *   { user_id: 2, user_name: 'Jane' }
- * ])
- * // [{ userId: 1, userName: 'John' }, { userId: 2, userName: 'Jane' }]
- */
-export declare const arrayKeysToCamel: <T = any>(arr: Record<string, any>[]) => T[];

package/types/arrayToTree.d.ts

@@ -1,8 +0,0 @@
-export interface ArrayToTreeOptions<T = any> {
-    idField?: string;
-    pidField?: string;
-    childrenField?: string;
-    rootPid?: any;
-    mapFn?: (node: T) => T;
-}
-export declare function arrayToTree<T = any>(items: T[], options?: ArrayToTreeOptions<T>): T[];

package/types/calcPerfTime.d.ts

@@ -1,4 +0,0 @@
-/**
- * 计算性能时间差
- */
-export declare const calcPerfTime: (startTime: number, endTime?: number) => string;

package/types/common.d.ts

@@ -1,8 +0,0 @@
-/**
- * 通用类型定义
- */
-
-/**
- * 通用键值对类型
- */
-export type KeyValue<T = any> = Record<string, T>;

package/types/configMerge.d.ts

@@ -1,49 +0,0 @@
-/**
- * 配置来源信息
- */
-export interface ConfigSource {
-    /** 配置文件路径 */
-    filePath: string;
-    /** 配置数据 */
-    data: Record<string, any>;
-}
-/**
- * 合并配置选项
- */
-export interface MergeConfigOptions {
-    /** 合并策略：deep 深度合并（默认），shallow 浅合并，override 覆盖 */
-    strategy?: 'deep' | 'shallow' | 'override';
-    /** 是否克隆数据（避免引用污染），默认 true */
-    clone?: boolean;
-}
-/**
- * 加载配置选项
- */
-export interface LoadConfigOptions {
-    /** 目录数组：要搜索的目录路径 */
-    dirs: string[];
-    /** 文件数组：要匹配的文件名 */
-    files: string[];
-    /** 合并选项 */
-    merge?: MergeConfigOptions;
-    /** 是否必须找到至少一个配置文件，默认 false */
-    required?: boolean;
-    /** 文件扩展名，默认 ['.js', '.ts', '.json'] */
-    extensions?: string[];
-}
-/**
- * 合并多个配置对象
- * @param configs - 配置对象数组
- * @param options - 合并选项
- * @returns 合并后的配置对象
- */
-export declare function mergeConfig(configs: Record<string, any>[], options?: MergeConfigOptions): Record<string, any>;
-/**
- * 加载并合并配置文件（矩阵搜索：dirs × files）
- * @param options - 加载选项
- * @returns 合并后的配置对象和来源信息
- */
-export declare function loadAndMergeConfig(options: LoadConfigOptions): Promise<{
-    config: Record<string, any>;
-    sources: ConfigSource[];
-}>;

package/types/configTypes.d.ts

@@ -1,28 +0,0 @@
-/**
- * 加载配置选项
- */
-export interface LoadConfigOptions {
-    /** 当前工作目录，默认 process.cwd() */
-    cwd?: string;
-    /** 目录数组：要搜索的目录路径（相对于 cwd） */
-    dirs: string[];
-    /** 文件数组：要匹配的文件名 */
-    files: string[];
-    /** 文件扩展名，默认 ['.js', '.ts', '.json'] */
-    extensions?: string[];
-    /** 加载模式：'first' = 返回第一个找到的配置（默认），'merge' = 合并所有配置 */
-    mode?: 'merge' | 'first';
-    /** 指定要提取的字段路径数组，如 ['menus', 'database.host']，为空则返回完整对象 */
-    paths?: string[];
-    /** 默认配置，会与找到的配置合并（优先级最低） */
-    defaults?: Record<string, any>;
-}
-/**
- * Addon 配置合并选项（已废弃，仅用于向后兼容）
- */
-export interface MergeConfigOptions {
-    /** 合并策略（已废弃，始终使用 deep） */
-    strategy?: 'deep' | 'shallow' | 'override';
-    /** 是否克隆数据（已废弃） */
-    clone?: boolean;
-}

package/types/constants.d.ts

@@ -1,48 +0,0 @@
-/**
- * Befly 共享常量定义
- * 运行时使用的常量（非纯类型）
- */
-/**
- * API 响应码
- */
-export declare const ApiCode: {
-    /** 成功 */
-    readonly SUCCESS: 0;
-    /** 通用失败 */
-    readonly FAIL: 1;
-    /** 未授权 */
-    readonly UNAUTHORIZED: 401;
-    /** 禁止访问 */
-    readonly FORBIDDEN: 403;
-    /** 未找到 */
-    readonly NOT_FOUND: 404;
-    /** 服务器错误 */
-    readonly SERVER_ERROR: 500;
-};
-/**
- * API 响应码类型
- */
-export type ApiCodeType = (typeof ApiCode)[keyof typeof ApiCode];
-/**
- * 通用错误消息
- */
-export declare const ErrorMessages: {
-    /** 未授权 */
-    readonly UNAUTHORIZED: "请先登录";
-    /** 禁止访问 */
-    readonly FORBIDDEN: "无访问权限";
-    /** 未找到 */
-    readonly NOT_FOUND: "资源不存在";
-    /** 服务器错误 */
-    readonly SERVER_ERROR: "服务器错误";
-    /** 参数错误 */
-    readonly INVALID_PARAMS: "参数错误";
-    /** Token 过期 */
-    readonly TOKEN_EXPIRED: "Token 已过期";
-    /** Token 无效 */
-    readonly TOKEN_INVALID: "Token 无效";
-};
-/**
- * 错误消息类型
- */
-export type ErrorMessageType = (typeof ErrorMessages)[keyof typeof ErrorMessages];

package/types/context.d.ts

@@ -1,38 +0,0 @@
-/**
- * 请求上下文相关类型定义
- */
-
-/**
- * 用户信息类型
- */
-export interface UserInfo {
-    /** 用户 ID */
-    id: number;
-    /** 用户名 */
-    username?: string;
-    /** 邮箱 */
-    email?: string;
-    /** 角色代码 */
-    roleCode?: string;
-    /** 其他自定义字段 */
-    [key: string]: any;
-}
-
-/**
- * 请求上下文基础接口
- * 用于跨包共享的最小上下文定义
- */
-export interface BaseRequestContext {
-    /** 请求体参数 */
-    body: Record<string, any>;
-    /** 用户信息 */
-    user: Record<string, any>;
-    /** 请求开始时间（毫秒） */
-    now: number;
-    /** 客户端 IP 地址 */
-    ip: string;
-    /** API 路由路径（如 POST/api/user/login） */
-    route: string;
-    /** 请求唯一 ID */
-    requestId: string;
-}

package/types/crypto.d.ts

@@ -1,23 +0,0 @@
-/**
- * 加密相关类型定义
- */
-
-/**
- * 编码类型
- */
-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;
-}