befly-shared 1.2.7 → 1.3.0

package/README.md

@@ -1,439 +0,0 @@
-# Befly Shared
-
-Befly 框架的共享模块，包含跨包共享的工具函数、常量、类型定义和配置。
-
-## 安装
-
-```bash
-bun add befly-shared
-```
-
-## 类型定义
-
-所有类型统一从 `befly-shared/types` 导入，按功能分类：
-
-| 分类   | 类型                                                                          |
-| ------ | ----------------------------------------------------------------------------- |
-| 验证   | `ValidateResult`, `SingleResult`, `FieldDefinition`, `FieldRules`             |
-| API    | `ResponseResult`, `PaginatedResult`, `ApiCode`, `ErrorMessages`               |
-| 数据库 | `DatabaseConfig`, `SqlValue`, `WhereConditions`                               |
-| 上下文 | `RequestContext`, `ApiRoute`                                                  |
-| 菜单   | `MenuItem`, `MenuTree`                                                        |
-| 加密   | `EncodingType`, `HashAlgorithm`, `PasswordHashOptions`                        |
-| JWT    | `JwtPayload`, `JwtSignOptions`, `JwtVerifyOptions`, `JwtDecoded`, `JwtHeader` |
-| 日志   | `LogLevel`, `LoggerConfig`                                                    |
-| 工具   | `DateFormat`, `PaginationParams`, `PaginationResult`                          |
-| 表     | `SystemFields`, `BaseTable`, `InsertType`, `UpdateType`, `SelectType`         |
-| Addon  | `AddonAuthor`, `AddonConfig`                                                  |
-| 通用   | `ReservedFields`, `ExcludeReserved`                                           |
-
-### 响应类型
-
-```typescript
-import type { ResponseResult, PaginatedResult, ValidationResult } from 'befly-shared/types';
-
-// API 响应
-const result: ResponseResult<{ id: number }> = {
-    code: 0,
-    msg: '操作成功',
-    data: { id: 1 }
-};
-
-// 分页响应
-const list: PaginatedResult<User> = {
-    code: 0,
-    msg: '查询成功',
-    data: users,
-    total: 100,
-    page: 1,
-    limit: 10,
-    pages: 10
-};
-```
-
-### 常量
-
-```typescript
-import { ApiCode, ErrorMessages } from 'befly-shared/types';
-
-// 响应码
-ApiCode.SUCCESS; // 0
-ApiCode.FAIL; // 1
-ApiCode.UNAUTHORIZED; // 401
-ApiCode.FORBIDDEN; // 403
-ApiCode.NOT_FOUND; // 404
-ApiCode.SERVER_ERROR; // 500
-
-// 错误消息
-ErrorMessages.UNAUTHORIZED; // '请先登录'
-ErrorMessages.FORBIDDEN; // '无访问权限'
-ErrorMessages.TOKEN_EXPIRED; // 'Token 已过期'
-```
-
-### 配置类型
-
-```typescript
-import type { DatabaseConfig, RedisConfig } from 'befly-shared/types';
-
-const dbConfig: DatabaseConfig = {
-    type: 'mysql',
-    host: 'localhost',
-    port: 3306,
-    username: 'root',
-    password: 'password',
-    database: 'befly'
-};
-
-const redisConfig: RedisConfig = {
-    host: 'localhost',
-    port: 6379,
-    password: 'password',
-    db: 0,
-    prefix: 'befly:'
-};
-```
-
-> **注意**：这些类型主要用于类型检查和文档，实际连接时框架会自动从 `beflyConfig` 获取配置。
-
-### Redis 键和 TTL
-
-```typescript
-import { RedisKeys, RedisTTL } from 'befly-shared/redisKeys';
-
-// 生成 Redis 键
-RedisKeys.apisAll(); // 'befly:apis:all'
-RedisKeys.menusAll(); // 'befly:menus:all'
-RedisKeys.roleInfo('admin'); // 'befly:role:info:admin'
-RedisKeys.roleApis('admin'); // 'befly:role:apis:admin'
-RedisKeys.tableColumns('user'); // 'befly:table:columns:user'
-
-// TTL 配置（秒）
-RedisTTL.tableColumns; // 3600 (1小时)
-RedisTTL.roleApis; // 86400 (24小时)
-RedisTTL.roleInfo; // 86400 (24小时)
-RedisTTL.apisAll; // null (永久)
-RedisTTL.menusAll; // null (永久)
-```
-
-## 配置管理
-
-### mergeConfig
-
-加载并合并配置文件（矩阵搜索：dirs × files）。
-
-**参数：**
-
-- `dirs`: 目录数组（绝对路径）
-- `files`: 文件名数组（不含扩展名）
-- `required`: 是否必填，默认 `false`
-- `extensions`: 扩展名数组，默认 `['.js', '.ts', '.json']`
-
-**返回：** `Promise<Record<string, any>>`
-
-**示例：**
-
-```typescript
-import { mergeConfig } from 'befly-shared/scanConfig';
-
-const config = await mergeConfig({
-    dirs: ['/path/to/config1', '/path/to/config2'],
-    files: ['app', 'database'],
-    required: false
-});
-```
-
-## 字段名转换
-
-### keysToCamel
-
-将对象字段名转为小驼峰格式。
-
-**参数：**
-
-- `obj`: 源对象
-
-**返回：** `T`
-
-**示例：**
-
-```typescript
-import { keysToCamel } from 'befly-shared/keysToCamel';
-
-keysToCamel({ user_id: 123, user_name: 'John' });
-// { userId: 123, userName: 'John' }
-```
-
-### keysToSnake
-
-将对象字段名转为下划线格式。
-
-**参数：**
-
-- `obj`: 源对象
-
-**返回：** `T`
-
-**示例：**
-
-```typescript
-import { keysToSnake } from 'befly-shared/keysToSnake';
-
-keysToSnake({ userId: 123, userName: 'John' });
-// { user_id: 123, user_name: 'John' }
-```
-
-### arrayKeysToCamel
-
-批量将数组对象的字段名转为小驼峰格式。
-
-**参数：**
-
-- `arr`: 源数组
-
-**返回：** `T[]`
-
-**示例：**
-
-```typescript
-import { arrayKeysToCamel } from 'befly-shared/arrayKeysToCamel';
-
-arrayKeysToCamel([
-    { user_id: 1, user_name: 'John' },
-    { user_id: 2, user_name: 'Jane' }
-]);
-// [{ userId: 1, userName: 'John' }, { userId: 2, userName: 'Jane' }]
-```
-
-## 数据处理
-
-### arrayToTree
-
-将扁平数组转为树形结构。
-
-**参数：**
-
-- `items`: 数组
-- `options`: 配置项
-    - `idField`: 节点 id 字段名，默认 `'id'`
-    - `pidField`: 父节点 id 字段名，默认 `'pid'`
-    - `childrenField`: 子节点字段名，默认 `'children'`
-    - `rootPid`: 根节点的父 id，默认 `0`
-    - `mapFn`: 节点转换函数（可选）
-
-**返回：** `T[]`
-
-**示例：**
-
-```typescript
-import { arrayToTree } from 'befly-shared/arrayToTree';
-
-const items = [
-    { id: 1, pid: 0, name: '根节点' },
-    { id: 2, pid: 1, name: '子节点1' },
-    { id: 3, pid: 1, name: '子节点2' }
-];
-
-const tree = arrayToTree(items);
-// [
-//   {
-//     id: 1, pid: 0, name: '根节点',
-//     children: [
-//       { id: 2, pid: 1, name: '子节点1' },
-//       { id: 3, pid: 1, name: '子节点2' }
-//     ]
-//   }
-// ]
-```
-
-### fieldClear
-
-字段过滤和清理工具，支持字段挑选、排除、值保留、值排除等操作。
-
-**参数：**
-
-- `data`: 数据（对象或数组）
-- `options`: 配置项
-    - `pickKeys`: 只保留这些字段
-    - `omitKeys`: 排除这些字段
-    - `keepValues`: 只保留这些值
-    - `excludeValues`: 排除这些值
-    - `keepMap`: 强制保留的键值对（优先级最高）
-
-**返回：** `FieldClearResult<T>`
-
-**示例：**
-
-```typescript
-import { fieldClear } from 'befly-shared/fieldClear';
-
-// 只保留指定字段
-fieldClear({ id: 1, name: 'John', age: 30 }, { pickKeys: ['id', 'name'] });
-// { id: 1, name: 'John' }
-
-// 排除指定字段
-fieldClear({ id: 1, name: 'John', age: 30 }, { omitKeys: ['age'] });
-// { id: 1, name: 'John' }
-
-// 排除指定值
-fieldClear({ id: 1, name: null, age: undefined }, { excludeValues: [null, undefined] });
-// { id: 1 }
-```
-
-### pickFields
-
-挑选对象中的指定字段。
-
-**参数：**
-
-- `obj`: 源对象
-- `keys`: 字段名数组
-
-**返回：** `Partial<T>`
-
-**示例：**
-
-```typescript
-import { pickFields } from 'befly-shared/pickFields';
-
-pickFields({ id: 1, name: 'John', age: 30 }, ['id', 'name']);
-// { id: 1, name: 'John' }
-```
-
-## 文件扫描
-
-### scanFiles
-
-扫描指定目录下的文件。
-
-**参数：**
-
-- `dir`: 目录路径
-- `pattern`: Glob 模式，默认 `'**/*.{ts,js}'`
-- `ignoreUnderline`: 是否忽略下划线开头的文件/目录，默认 `true`
-
-**返回：** `Promise<ScanFileResult[]>`
-
-**示例：**
-
-```typescript
-import { scanFiles } from 'befly-shared/scanFiles';
-
-const files = await scanFiles('/path/to/dir', '**/*.ts');
-// [
-//   { filePath: '/path/to/dir/file1.ts', relativePath: 'file1', fileName: 'file1' },
-//   { filePath: '/path/to/dir/sub/file2.ts', relativePath: 'sub/file2', fileName: 'file2' }
-// ]
-```
-
-### scanViews
-
-扫描项目和所有 `@befly-addon` 包的 views 目录，用于 unplugin-vue-router 的 routesFolder 配置。
-
-**注意：** 此函数只能在 vite.config.js 中使用（Node.js 环境），不能在浏览器中使用。
-
-**返回：** 路由文件夹配置数组
-
-**示例：**
-
-```typescript
-import { scanViews } from 'befly-shared/scanViews';
-
-// 在 vite.config.js 中使用
-export default defineConfig({
-    plugins: [
-        VueRouter({
-            routesFolder: scanViews()
-        })
-    ]
-});
-```
-
-### scanAddons
-
-扫描所有可用的 addon，从 `node_modules/@befly-addon/` 加载。
-
-**参数：**
-
-- `cwd`: 项目根目录，默认 `process.cwd()`
-
-**返回：** `string[]` - addon 名称数组
-
-**示例：**
-
-```typescript
-import { scanAddons } from 'befly-shared/addonHelper';
-
-const addons = scanAddons();
-// ['admin', 'blog', 'shop']
-```
-
-## 路由处理
-
-### layouts
-
-自定义布局处理函数，根据文件名后缀判断使用哪个布局。
-
-**参数：**
-
-- `routes`: 原始路由配置
-- `inheritLayout`: 继承的布局名称（来自父级目录）
-
-**返回：** 处理后的布局配置
-
-**示例：**
-
-```typescript
-import { layouts } from 'befly-shared/layouts';
-
-// 根据文件名后缀判断布局：
-// - index.vue -> 默认布局
-// - login_n.vue -> n 布局
-// - admin_a.vue -> a 布局
-```
-
-## 性能工具
-
-### calcPerfTime
-
-计算性能时间差（支持纳秒级精度）。
-
-**参数：**
-
-- `startTime`: 开始时间（纳秒）
-- `endTime`: 结束时间（纳秒），默认 `Bun.nanoseconds()`
-
-**返回：** `string` - 格式化的时间字符串
-
-**示例：**
-
-```typescript
-import { calcPerfTime } from 'befly-shared/calcPerfTime';
-
-const start = Bun.nanoseconds();
-// ... 执行操作 ...
-const duration = calcPerfTime(start);
-// "12.34 毫秒" 或 "1.23 秒"
-```
-
-## Addon 辅助
-
-### addonHelper
-
-提供 addon 相关的辅助功能，包括扫描、路径解析等。
-
-**导出函数：**
-
-- `scanAddons(cwd?)`: 扫描所有可用的 addon
-- 其他辅助函数...
-
-## 类型定义
-
-所有类型定义自动生成到 `types/` 目录下，可直接导入使用：
-
-```typescript
-import type { LoadConfigOptions, MergeConfigOptions } from 'befly-shared/configTypes';
-```
-
-## License
-
-Apache-2.0

package/dist/addonHelper.js

@@ -1,83 +0,0 @@
-import fs from 'node:fs';
-import { join } from 'pathe';
-import { statSync, existsSync } from 'node:fs';
-/**
- * 扫描所有可用的 addon
- * 优先从本地 addons/ 目录加载，其次从 node_modules/@befly-addon/ 加载
- * @param cwd - 项目根目录，默认为 process.cwd()
- * @returns addon 名称数组
- */
-export const scanAddons = (cwd = process.cwd()) => {
-    const addons = new Set();
-    // const projectAddonsDir = join(cwd, 'addons');
-    // 1. 扫描本地 addons 目录（优先级高）
-    // if (existsSync(projectAddonsDir)) {
-    //     try {
-    //         const localAddons = fs.readdirSync(projectAddonsDir).filter((name) => {
-    //             const fullPath = join(projectAddonsDir, name);
-    //             try {
-    //                 const stat = statSync(fullPath);
-    //                 return stat.isDirectory() && !name.startsWith('_');
-    //             } catch {
-    //                 return false;
-    //             }
-    //         });
-    //         localAddons.forEach((name) => addons.add(name));
-    //     } catch (err) {
-    //         // 忽略本地目录读取错误
-    //     }
-    // }
-    // 2. 扫描 node_modules/@befly-addon 目录
-    const beflyDir = join(cwd, 'node_modules', '@befly-addon');
-    if (existsSync(beflyDir)) {
-        try {
-            const npmAddons = fs.readdirSync(beflyDir).filter((name) => {
-                // 如果本地已存在，跳过 npm 包版本
-                if (addons.has(name))
-                    return false;
-                const fullPath = join(beflyDir, name);
-                try {
-                    const stat = statSync(fullPath);
-                    return stat.isDirectory();
-                }
-                catch {
-                    return false;
-                }
-            });
-            npmAddons.forEach((name) => addons.add(name));
-        }
-        catch {
-            // 忽略 npm 目录读取错误
-        }
-    }
-    return Array.from(addons).sort();
-};
-/**
- * 获取 addon 的指定子目录路径
- * 优先返回本地 addons 目录，其次返回 node_modules 目录
- * @param name - addon 名称
- * @param subDir - 子目录名称
- * @param cwd - 项目根目录，默认为 process.cwd()
- * @returns 完整路径
- */
-export const getAddonDir = (name, subDir, cwd = process.cwd()) => {
-    // 优先使用本地 addons 目录
-    // const projectAddonsDir = join(cwd, 'addons');
-    // const localPath = join(projectAddonsDir, name, subDir);
-    // if (existsSync(localPath)) {
-    //     return localPath;
-    // }
-    // 降级使用 node_modules 目录
-    return join(cwd, 'node_modules', '@befly-addon', name, subDir);
-};
-/**
- * 检查 addon 子目录是否存在
- * @param name - addon 名称
- * @param subDir - 子目录名称
- * @param cwd - 项目根目录，默认为 process.cwd()
- * @returns 是否存在
- */
-export const addonDirExists = (name, subDir, cwd = process.cwd()) => {
-    const dir = getAddonDir(name, subDir, cwd);
-    return existsSync(dir) && statSync(dir).isDirectory();
-};

package/dist/arrayKeysToCamel.js

@@ -1,18 +0,0 @@
-import { keysToCamel } from './keysToCamel.js';
-/**
- * 数组对象字段名批量转小驼峰
- * @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 const arrayKeysToCamel = (arr) => {
-    if (!arr || !Array.isArray(arr))
-        return arr;
-    return arr.map((item) => keysToCamel(item));
-};

package/dist/arrayToTree.js

@@ -1,23 +0,0 @@
-// arrayToTree 工具函数实现
-export function arrayToTree(items, options = {}) {
-    const { idField = 'id', pidField = 'pid', childrenField = 'children', rootPid = 0, mapFn } = options;
-    const tree = [];
-    for (const item of items) {
-        const pid = item[pidField];
-        // 用 Object.is 判断，兼容 null/undefined/0
-        if (Object.is(pid, rootPid)) {
-            let node = { ...item };
-            if (mapFn)
-                node = mapFn(node);
-            const children = arrayToTree(items, {
-                ...options,
-                rootPid: node[idField]
-            });
-            if (children.length > 0) {
-                node[childrenField] = children;
-            }
-            tree.push(node);
-        }
-    }
-    return tree;
-}

package/dist/calcPerfTime.js

@@ -1,13 +0,0 @@
-/**
- * 计算性能时间差
- */
-export const calcPerfTime = (startTime, endTime = Bun.nanoseconds()) => {
-    const elapsedMs = (endTime - startTime) / 1_000_000;
-    if (elapsedMs < 1000) {
-        return `${elapsedMs.toFixed(2)} 毫秒`;
-    }
-    else {
-        const elapsedSeconds = elapsedMs / 1000;
-        return `${elapsedSeconds.toFixed(2)} 秒`;
-    }
-};

package/dist/configTypes.js

@@ -1 +0,0 @@
-export {};

package/dist/constants.js

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

package/dist/fieldClear.js

@@ -1,57 +0,0 @@
-// fieldClear 工具函数实现
-// 支持 pick/omit/keepValues/excludeValues，处理对象和数组
-function isObject(val) {
-    return val !== null && typeof val === 'object' && !Array.isArray(val);
-}
-function isArray(val) {
-    return Array.isArray(val);
-}
-export function fieldClear(data, options = {}) {
-    const { pickKeys, omitKeys, keepValues, excludeValues, keepMap } = options;
-    const filterObj = (obj) => {
-        let result = {};
-        let keys = Object.keys(obj);
-        if (pickKeys && pickKeys.length) {
-            keys = keys.filter((k) => pickKeys.includes(k));
-        }
-        if (omitKeys && omitKeys.length) {
-            keys = keys.filter((k) => !omitKeys.includes(k));
-        }
-        for (const key of keys) {
-            const value = obj[key];
-            // 1. 优先检查 keepMap
-            if (keepMap && key in keepMap) {
-                if (Object.is(keepMap[key], value)) {
-                    result[key] = value;
-                    continue;
-                }
-            }
-            // 2. 检查 keepValues (只保留指定值)
-            if (keepValues && keepValues.length && !keepValues.includes(value)) {
-                continue;
-            }
-            // 3. 检查 excludeValues (排除指定值)
-            if (excludeValues && excludeValues.length && excludeValues.includes(value)) {
-                continue;
-            }
-            result[key] = value;
-        }
-        return result;
-    };
-    if (isArray(data)) {
-        return data
-            .map((item) => (isObject(item) ? filterObj(item) : item))
-            .filter((item) => {
-            if (isObject(item)) {
-                // 只保留有内容的对象
-                return Object.keys(item).length > 0;
-            }
-            // 原始值直接保留
-            return true;
-        });
-    }
-    if (isObject(data)) {
-        return filterObj(data);
-    }
-    return data;
-}

package/dist/genShortId.js

@@ -1,12 +0,0 @@
-/**
- * 生成短 ID
- * 由时间戳（base36）+ 随机字符组成，约 13 位
- * - 前 8 位：时间戳（可排序）
- * - 后 5 位：随机字符（防冲突）
- * @returns 短 ID 字符串
- * @example
- * genShortId() // "lxyz1a2b3c4"
- */
-export function genShortId() {
-    return Date.now().toString(36) + Math.random().toString(36).slice(2, 7);
-}