befly-shared 1.1.1

package/tests/types.test.ts

@@ -0,0 +1,283 @@
+/**
+ * befly-shared 类型定义测试
+ */
+import { describe, expect, it } from 'bun:test';
+
+import { ApiCode, ErrorMessages, type DatabaseConfig, type FieldDefinition, type HttpMethod, type MenuItem, type PaginatedResult, type RedisConfig, type ResponseResult, type RoleInfo, type UserInfo, type ValidationResult } from '../src/types.js';
+
+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('请求上下文基础结构正确', () => {
+            const { BaseRequestContext } = require('../src/types.js') as { BaseRequestContext: any };
+            // 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/addonConfigMerge.d.ts

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,24 @@
+/**
+ * 扫描所有可用的 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/arrayKeysToCamel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 数组对象字段名批量转小驼峰
+ * @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

@@ -0,0 +1,8 @@
+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

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

package/types/configMerge.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 配置来源信息
+ */
+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

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

package/types/defineAddonConfig.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Addon 配置定义函数
+ * 接受 addon 配置对象，从当前执行目录的 config 目录下查找同名配置文件进行合并
+ * 只能在 addon.config.js 文件中使用
+ * @param metaDirname - import.meta.dirname
+ * @param addonConfig - addon 配置对象
+ * @returns 合并后的配置对象
+ * @example
+ * ```ts
+ * // 在 packages/addonAdmin/addon.config.js 中
+ * import { defineAddonConfig } from 'befly-shared/defineAddonConfig';
+ *
+ * export default defineAddonConfig(import.meta.dirname, {
+ *     menus: [...]
+ * });
+ * // 自动从目录名提取 addon 名称，并从 process.cwd()/config/addonAdmin.{js,ts,json} 读取配置并合并
+ * ```
+ */
+export declare function defineAddonConfig(metaDirname: string, addonConfig?: Record<string, any>): Promise<Record<string, any>>;

package/types/fieldClear.d.ts

@@ -0,0 +1,16 @@
+export interface FieldClearOptions {
+    pickKeys?: string[];
+    omitKeys?: string[];
+    keepValues?: any[];
+    excludeValues?: any[];
+    keepMap?: Record<string, any>;
+}
+export type FieldClearResult<T> =
+    T extends Array<infer U>
+        ? Array<FieldClearResult<U>>
+        : T extends object
+          ? {
+                [K in keyof T]?: T[K];
+            }
+          : T;
+export declare function fieldClear<T = any>(data: T | T[], options?: FieldClearOptions): FieldClearResult<T>;

package/types/genShortId.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 生成短 ID
+ * 由时间戳（base36）+ 随机字符组成，约 13 位
+ * - 前 8 位：时间戳（可排序）
+ * - 后 5 位：随机字符（防冲突）
+ * @returns 短 ID 字符串
+ * @example
+ * genShortId() // "lxyz1a2b3c4"
+ */
+export declare function genShortId(): string;

package/types/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Befly Shared 统一导出
+ * 跨包共享的工具函数、常量、类型定义
+ */
+export * from './types.js';
+export * from './redisKeys.js';
+export * from './regex.js';
+export * from './defineAddonConfig.js';
+export * from './addonHelper.js';
+export * from './arrayKeysToCamel.js';
+export * from './arrayToTree.js';
+export * from './calcPerfTime.js';
+export * from './configTypes.js';
+export * from './genShortId.js';
+export * from './scanConfig.js';
+export * from './fieldClear.js';
+export * from './keysToCamel.js';
+export * from './keysToSnake.js';
+export * from './layouts.js';
+export * from './pickFields.js';
+export * from './scanFiles.js';
+export * from './scanViews.js';

package/types/keysToCamel.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 对象字段名转小驼峰
+ * @param obj - 源对象
+ * @returns 字段名转为小驼峰格式的新对象
+ *
+ * @example
+ * keysToCamel({ user_id: 123, user_name: 'John' }) // { userId: 123, userName: 'John' }
+ * keysToCamel({ created_at: 1697452800000 }) // { createdAt: 1697452800000 }
+ */
+export declare const keysToCamel: <T = any>(obj: Record<string, any>) => T;

package/types/keysToSnake.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 对象字段名转下划线
+ * @param obj - 源对象
+ * @returns 字段名转为下划线格式的新对象
+ *
+ * @example
+ * keysToSnake({ userId: 123, userName: 'John' }) // { user_id: 123, user_name: 'John' }
+ * keysToSnake({ createdAt: 1697452800000 }) // { created_at: 1697452800000 }
+ */
+export declare const keysToSnake: <T = any>(obj: Record<string, any>) => T;

package/types/layouts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 路由配置接口
+ */
+export interface RouteConfig {
+    path?: string;
+    component?: any;
+    children?: RouteConfig[];
+    meta?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * 布局配置接口
+ */
+export interface LayoutConfig {
+    path: string;
+    layoutName: string;
+    component: any;
+    children?: LayoutConfig[];
+    meta?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * 自定义布局处理函数
+ * 根据文件名后缀判断使用哪个布局
+ * @param routes - 原始路由配置
+ * @param inheritLayout - 继承的布局名称（来自父级目录）
+ * @returns 处理后的布局配置（不包含实际的布局组件导入）
+ */
+export declare function Layouts(routes: RouteConfig[], inheritLayout?: string): LayoutConfig[];

package/types/loadAndMergeConfig.d.ts

@@ -0,0 +1,7 @@
+import type { LoadConfigOptions } from './configTypes.js';
+/**
+ * 加载并合并配置文件（矩阵搜索：dirs × files）
+ * @param options - 加载选项
+ * @returns 合并后的配置对象
+ */
+export declare function loadAndMergeConfig(options: LoadConfigOptions): Promise<Record<string, any>>;

package/types/mergeConfig.d.ts

@@ -0,0 +1,7 @@
+import type { LoadConfigOptions } from './configTypes.js';
+/**
+ * 加载并合并配置文件（矩阵搜索：dirs × files）
+ * @param options - 加载选项
+ * @returns 合并后的配置对象
+ */
+export declare function mergeConfig(options: LoadConfigOptions): Promise<Record<string, any>>;

package/types/pickFields.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 挑选指定字段
+ */
+export declare const pickFields: <T extends Record<string, any>>(obj: T, keys: string[]) => Partial<T>;

package/types/redisKeys.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Redis Key 统一管理
+ * 所有 Redis 缓存键在此统一定义，避免硬编码分散
+ */
+/**
+ * Redis Key 生成函数集合
+ */
+export declare const RedisKeys: {
+    /** 所有接口缓存 */
+    readonly apisAll: () => string;
+    /** 所有菜单缓存 */
+    readonly menusAll: () => string;
+    /** 角色信息缓存（完整角色对象） */
+    readonly roleInfo: (roleCode: string) => string;
+    /** 角色接口权限缓存（Set 集合） */
+    readonly roleApis: (roleCode: string) => string;
+    /** 表结构缓存 */
+    readonly tableColumns: (table: string) => string;
+};
+/**
+ * Redis TTL（过期时间）常量配置（单位：秒）
+ */
+export declare const RedisTTL: {
+    /** 表结构缓存 - 1小时 */
+    readonly tableColumns: 3600;
+    /** 角色接口权限 - 24小时 */
+    readonly roleApis: 86400;
+    /** 角色信息 - 24小时 */
+    readonly roleInfo: 86400;
+    /** 接口列表 - 永久（不过期） */
+    readonly apisAll: null;
+    /** 菜单列表 - 永久（不过期） */
+    readonly menusAll: null;
+};