befly-shared 1.1.1

package/dist/scanConfig.js

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { mergeAndConcat } from 'merge-anything';
+import { isPlainObject } from 'es-toolkit';
+import { get, set } from 'es-toolkit/compat';
+/**
+ * 扫描并合并配置文件（矩阵搜索：dirs × files）
+ * @param options - 加载选项
+ * @returns 合并后的配置对象（或第一个找到的配置）
+ */
+export async function scanConfig(options) {
+    const { 
+    //
+    cwd = process.cwd(), dirs, files, extensions = ['.js', '.ts', '.json'], mode = 'first', paths } = options;
+    // 参数验证
+    if (!Array.isArray(dirs) || dirs.length === 0) {
+        throw new Error('dirs 必须是非空数组');
+    }
+    if (!Array.isArray(files) || files.length === 0) {
+        throw new Error('files 必须是非空数组');
+    }
+    const configs = [];
+    // 矩阵搜索：dirs × files × extensions
+    for (const dir of dirs) {
+        // 如果是绝对路径则直接使用，否则拼接 cwd
+        const fullDir = isAbsolute(dir) ? dir : join(cwd, dir);
+        for (const file of files) {
+            for (const ext of extensions) {
+                const fileName = file.endsWith(ext) ? file : file + ext;
+                const filePath = join(fullDir, fileName);
+                if (existsSync(filePath)) {
+                    try {
+                        // 动态导入配置文件（使用 import 断言处理 JSON）
+                        let data;
+                        if (ext === '.json') {
+                            // JSON 文件使用 import 断言
+                            const module = await import(filePath, { with: { type: 'json' } });
+                            data = module.default;
+                        }
+                        else {
+                            // JS/TS 文件使用动态导入
+                            const module = await import(filePath);
+                            data = module.default || module;
+                            // 处理 async 函数导出（如 defineAddonConfig）
+                            if (data instanceof Promise) {
+                                data = await data;
+                            }
+                        }
+                        // 验证配置数据
+                        if (!isPlainObject(data)) {
+                            continue;
+                        }
+                        configs.push(data);
+                        // 如果模式为 'first'，找到第一个配置后立即返回
+                        if (mode === 'first') {
+                            return data;
+                        }
+                        // 找到后跳过同名文件的其他扩展名
+                        break;
+                    }
+                    catch (error) {
+                        console.error(`加载配置文件失败: ${filePath}`, error.message);
+                    }
+                }
+            }
+        }
+    }
+    // 合并配置（使用 mergeAndConcat 深度合并）
+    const finalConfig = configs.length > 0 ? mergeAndConcat({}, ...configs) : {};
+    // 如果指定了 paths，则只返回指定路径的字段
+    if (paths && paths.length > 0) {
+        const result = {};
+        for (const path of paths) {
+            const value = get(finalConfig, path);
+            if (value !== undefined) {
+                set(result, path, value);
+            }
+        }
+        return result;
+    }
+    return finalConfig;
+}

package/dist/scanFiles.js

@@ -0,0 +1,39 @@
+import { existsSync } from 'node:fs';
+import { relative, basename, normalize } from 'pathe';
+/**
+ * 扫描指定目录下的文件
+ * @param dir 目录路径
+ * @param pattern Glob 模式
+ * @param ignoreUnderline 是否忽略下划线开头的文件/目录
+ */
+export async function scanFiles(dir, pattern = '**/*.{ts,js}', ignoreUnderline = true) {
+    if (!existsSync(dir))
+        return [];
+    const normalizedDir = normalize(dir);
+    const glob = new Bun.Glob(pattern);
+    const results = [];
+    for await (const file of glob.scan({ cwd: dir, onlyFiles: true, absolute: true })) {
+        if (file.endsWith('.d.ts'))
+            continue;
+        // 使用 pathe.normalize 统一路径分隔符为 /
+        const normalizedFile = normalize(file);
+        // 获取文件名（去除扩展名）
+        const fileName = basename(normalizedFile).replace(/\.[^.]+$/, '');
+        // 计算相对路径（pathe.relative 返回的已经是正斜杠路径）
+        const relativePath = relative(normalizedDir, normalizedFile).replace(/\.[^/.]+$/, '');
+        if (ignoreUnderline) {
+            // 检查文件名是否以下划线开头
+            if (fileName.startsWith('_'))
+                continue;
+            // 检查路径中是否包含下划线开头的目录
+            if (relativePath.split('/').some((part) => part.startsWith('_')))
+                continue;
+        }
+        results.push({
+            filePath: normalizedFile,
+            relativePath,
+            fileName
+        });
+    }
+    return results;
+}

package/dist/scanViews.js

@@ -0,0 +1,48 @@
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 扫描项目和所有 @befly-addon 包的 views 目录
+ * 用于 unplugin-vue-router 的 routesFolder 配置
+ * 注意:此函数只能在 vite.config.js 中使用(Node.js 环境),不能在浏览器中使用
+ * @returns 路由文件夹配置数组
+ */
+export function scanViews() {
+    // 使用绝对路径：基于项目根目录（process.cwd()）
+    const projectRoot = process.cwd();
+    const addonBasePath = join(projectRoot, 'node_modules', '@befly-addon');
+    const routesFolders = [];
+    // 1. 先添加项目自己的 views 目录
+    const projectViewsPath = join(projectRoot, 'src', 'views');
+    if (existsSync(projectViewsPath)) {
+        routesFolders.push({
+            src: projectViewsPath,
+            path: '',
+            exclude: ['**/components/**']
+        });
+    }
+    // 2. 扫描 @befly-addon 包的 views 目录
+    if (!existsSync(addonBasePath)) {
+        return routesFolders;
+    }
+    try {
+        const addonDirs = readdirSync(addonBasePath);
+        for (const addonName of addonDirs) {
+            const addonPath = join(addonBasePath, addonName);
+            // 检查是否为目录（包括符号链接）
+            if (!existsSync(addonPath))
+                continue;
+            const viewsPath = join(addonPath, 'views');
+            if (existsSync(viewsPath)) {
+                routesFolders.push({
+                    src: viewsPath,
+                    path: `addon/${addonName}/`,
+                    exclude: ['**/components/**']
+                });
+            }
+        }
+    }
+    catch (error) {
+        console.error('扫描 @befly-addon 目录失败:', error);
+    }
+    return routesFolders;
+}

package/dist/types.js

@@ -0,0 +1,46 @@
+/**
+ * Befly 共享类型定义
+ * 这些类型可以在 core、tpl、admin 等多个包中复用
+ */
+// ============================================
+// 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/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "befly-shared",
+    "version": "1.1.1",
+    "type": "module",
+    "exports": {
+        ".": {
+            "bun": "./src/index.ts",
+            "import": "./dist/index.js",
+            "types": "./types/index.d.ts"
+        },
+        "./*": {
+            "bun": "./src/*.ts",
+            "import": "./dist/*.js",
+            "types": "./types/*.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "types",
+        "tests",
+        "package.json",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "rimraf dist && tsc",
+        "test": "bun test"
+    },
+    "devDependencies": {
+        "@types/bun": "latest",
+        "rimraf": "^6.1.2",
+        "typescript": "^5.7.2"
+    },
+    "dependencies": {
+        "es-toolkit": "^1.42.0",
+        "merge-anything": "^6.0.6",
+        "pathe": "^2.0.3"
+    },
+    "gitHead": "2031550167896390ac58c50aeb52b8c23426844e"
+}

package/src/addonHelper.ts

@@ -0,0 +1,88 @@
+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: string = process.cwd()): string[] => {
+    const addons = new Set<string>();
+    // 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: string, subDir: string, cwd: string = process.cwd()): string => {
+    // 优先使用本地 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: string, subDir: string, cwd: string = process.cwd()): boolean => {
+    const dir = getAddonDir(name, subDir, cwd);
+    return existsSync(dir) && statSync(dir).isDirectory();
+};

package/src/arrayKeysToCamel.ts

@@ -0,0 +1,18 @@
+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 = <T = any>(arr: Record<string, any>[]): T[] => {
+    if (!arr || !Array.isArray(arr)) return arr as T[];
+    return arr.map((item) => keysToCamel<T>(item));
+};

package/src/arrayToTree.ts

@@ -0,0 +1,31 @@
+// arrayToTree 工具函数实现
+
+export interface ArrayToTreeOptions<T = any> {
+    idField?: string; // 节点 id 字段名，默认 'id'
+    pidField?: string; // 父节点 id 字段名，默认 'pid'
+    childrenField?: string; // 子节点字段名，默认 'children'
+    rootPid?: any; // 根节点的父 id，默认 0
+    mapFn?: (node: T) => T; // 节点转换函数
+}
+
+export function arrayToTree<T = any>(items: T[], options: ArrayToTreeOptions<T> = {}): T[] {
+    const { idField = 'id', pidField = 'pid', childrenField = 'children', rootPid = 0, mapFn } = options;
+    const tree: T[] = [];
+    for (const item of items) {
+        const pid = (item as any)[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 as any)[idField]
+            });
+            if (children.length > 0) {
+                (node as any)[childrenField] = children;
+            }
+            tree.push(node);
+        }
+    }
+    return tree;
+}

package/src/calcPerfTime.ts

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

package/src/configTypes.ts

@@ -0,0 +1,27 @@
+/**
+ * 加载配置选项
+ */
+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/src/defineAddonConfig.ts

@@ -0,0 +1,45 @@
+import { join, basename } from 'pathe';
+
+import { mergeAndConcat } from 'merge-anything';
+
+import { scanConfig } from './scanConfig.js';
+
+/**
+ * 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 async function defineAddonConfig(metaDirname: string, addonConfig: Record<string, any> = {}): Promise<Record<string, any>> {
+    try {
+        // 1. 使用 pathe 的 basename 获取完整的目录名（保留 addon 前缀）
+        const addonName = basename(metaDirname);
+
+        // 2. 从当前执行目录的 config 目录查找配置
+        const projectConfigDir = join(process.cwd(), 'config');
+
+        // 3. 使用 scanConfig 加载项目配置
+        const projectConfig = await scanConfig({
+            dirs: [projectConfigDir],
+            files: [addonName]
+        });
+
+        // 4. 合并 addon 配置和项目配置（项目配置优先级更高）
+        return mergeAndConcat({}, addonConfig, projectConfig);
+    } catch (error: any) {
+        console.error('defineAddonConfig 失败:', error.message);
+        return addonConfig;
+    }
+}

package/src/fieldClear.ts

@@ -0,0 +1,75 @@
+// fieldClear 工具函数实现
+// 支持 pick/omit/keepValues/excludeValues，处理对象和数组
+
+export interface FieldClearOptions {
+    pickKeys?: string[]; // 只保留这些字段
+    omitKeys?: string[]; // 排除这些字段
+    keepValues?: any[]; // 只保留这些值
+    excludeValues?: any[]; // 排除这些值
+    keepMap?: Record<string, any>; // 强制保留的键值对（优先级最高，忽略 excludeValues）
+}
+
+export type FieldClearResult<T> = T extends Array<infer U> ? Array<FieldClearResult<U>> : T extends object ? { [K in keyof T]?: T[K] } : T;
+
+function isObject(val: unknown): val is Record<string, any> {
+    return val !== null && typeof val === 'object' && !Array.isArray(val);
+}
+
+function isArray(val: unknown): val is any[] {
+    return Array.isArray(val);
+}
+
+export function fieldClear<T = any>(data: T | T[], options: FieldClearOptions = {}): FieldClearResult<T> {
+    const { pickKeys, omitKeys, keepValues, excludeValues, keepMap } = options;
+
+    const filterObj = (obj: Record<string, any>) => {
+        let result: Record<string, any> = {};
+        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 as any[])
+            .map((item) => (isObject(item) ? filterObj(item) : item))
+            .filter((item) => {
+                if (isObject(item)) {
+                    // 只保留有内容的对象
+                    return Object.keys(item).length > 0;
+                }
+                // 原始值直接保留
+                return true;
+            }) as FieldClearResult<T>;
+    }
+    if (isObject(data)) {
+        return filterObj(data as Record<string, any>) as FieldClearResult<T>;
+    }
+    return data as FieldClearResult<T>;
+}

package/src/genShortId.ts

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

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 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/src/keysToCamel.ts

@@ -0,0 +1,22 @@
+import { isPlainObject } from 'es-toolkit/compat';
+import { camelCase } from 'es-toolkit/string';
+
+/**
+ * 对象字段名转小驼峰
+ * @param obj - 源对象
+ * @returns 字段名转为小驼峰格式的新对象
+ *
+ * @example
+ * keysToCamel({ user_id: 123, user_name: 'John' }) // { userId: 123, userName: 'John' }
+ * keysToCamel({ created_at: 1697452800000 }) // { createdAt: 1697452800000 }
+ */
+export const keysToCamel = <T = any>(obj: Record<string, any>): T => {
+    if (!obj || !isPlainObject(obj)) return obj as T;
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const camelKey = camelCase(key);
+        result[camelKey] = value;
+    }
+    return result;
+};

package/src/keysToSnake.ts

@@ -0,0 +1,22 @@
+import { isPlainObject } from 'es-toolkit/compat';
+import { snakeCase } from 'es-toolkit/string';
+
+/**
+ * 对象字段名转下划线
+ * @param obj - 源对象
+ * @returns 字段名转为下划线格式的新对象
+ *
+ * @example
+ * keysToSnake({ userId: 123, userName: 'John' }) // { user_id: 123, user_name: 'John' }
+ * keysToSnake({ createdAt: 1697452800000 }) // { created_at: 1697452800000 }
+ */
+export const keysToSnake = <T = any>(obj: Record<string, any>): T => {
+    if (!obj || !isPlainObject(obj)) return obj as T;
+
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const snakeKey = snakeCase(key);
+        result[snakeKey] = value;
+    }
+    return result;
+};