befly-shared 1.1.1 → 1.2.0

package/README.md

@@ -10,6 +10,23 @@ 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
@@ -62,7 +79,7 @@ const dbConfig: DatabaseConfig = {
     type: 'mysql',
     host: 'localhost',
     port: 3306,
-    user: 'root',
+    username: 'root',
     password: 'password',
     database: 'befly'
 };
@@ -71,10 +88,13 @@ const redisConfig: RedisConfig = {
     host: 'localhost',
     port: 6379,
     password: 'password',
-    db: 0
+    db: 0,
+    prefix: 'befly:'
 };
 ```
 
+> **注意**：这些类型主要用于类型检查和文档，实际连接时框架会自动从 `beflyConfig` 获取配置。
+
 ### Redis 键和 TTL
 
 ```typescript
@@ -122,29 +142,6 @@ const config = await mergeConfig({
 });
 ```
 
-### addonConfigMerge
-
-Addon 配置自动合并函数，自动读取 addon 的 `addon.config.js` 和项目 `config/` 目录下的同名配置文件进行合并。
-
-**参数：**
-
-- `options`: 合并选项（可选）
-
-**返回：** `Promise<Record<string, any>>`
-
-**示例：**
-
-```typescript
-import { addonConfigMerge } from 'befly-shared/scanConfig';
-
-// 在 @befly-addon/admin 包根目录文件中调用
-const config = await addonConfigMerge();
-// 自动读取：
-// 1. @befly-addon/admin/addon.config.js
-// 2. 项目根目录/config/admin.{js,ts,json}
-// 3. 合并后返回
-```
-
 ## 字段名转换
 
 ### keysToCamel

package/dist/{types.js → constants.js}

@@ -1,6 +1,6 @@
 /**
- * Befly 共享类型定义
- * 这些类型可以在 core、tpl、admin 等多个包中复用
+ * Befly 共享常量定义
+ * 运行时使用的常量（非纯类型）
  */
 // ============================================
 // API 响应码常量

package/dist/defineAddonConfig.js

@@ -1,40 +1,21 @@
-import { join, basename } from 'pathe';
-import { mergeAndConcat } from 'merge-anything';
-import { scanConfig } from './scanConfig.js';
 /**
  * Addon 配置定义函数
- * 接受 addon 配置对象，从当前执行目录的 config 目录下查找同名配置文件进行合并
+ * 用于定义 addon 的静态配置（如菜单）
  * 只能在 addon.config.js 文件中使用
- * @param metaDirname - import.meta.dirname
+ *
+ * @param _metaDirname - import.meta.dirname（保留参数，便于未来扩展）
  * @param addonConfig - addon 配置对象
- * @returns 合并后的配置对象
+ * @returns addon 配置对象
  * @example
  * ```ts
  * // 在 packages/addonAdmin/addon.config.js 中
- * import { defineAddonConfig } from 'befly-shared';
+ * 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, addonConfig = {}) {
-    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) {
-        console.error('defineAddonConfig 失败:', error.message);
-        return addonConfig;
-    }
+export function defineAddonConfig(_metaDirname, addonConfig = {}) {
+    return addonConfig;
 }

package/dist/defineBeflyConfig.js

@@ -0,0 +1,28 @@
+/**
+ * Befly 配置定义函数
+ * 提供类型提示，不做任何处理，直接返回配置对象
+ */
+/**
+ * 定义 Befly 配置
+ * 提供类型提示，不做任何处理，直接返回配置对象
+ * @param config 配置对象
+ * @returns 配置对象
+ * @example
+ * ```ts
+ * // app.config.ts
+ * import { defineBeflyConfig } from 'befly-shared/defineBeflyConfig';
+ *
+ * export default defineBeflyConfig({
+ *     appName: '我的应用',
+ *     appPort: 3000,
+ *     addons: {
+ *         admin: {
+ *             email: { host: 'smtp.qq.com' }
+ *         }
+ *     }
+ * });
+ * ```
+ */
+export function defineBeflyConfig(config) {
+    return config;
+}

package/dist/index.js

@@ -2,13 +2,14 @@
  * Befly Shared 统一导出
  * 跨包共享的工具函数、常量、类型定义
  */
-// 类型定义
-export * from './types.js';
-// 常量配置
+// 常量（运行时）
+export * from './constants.js';
+// Redis 键和正则
 export * from './redisKeys.js';
 export * from './regex.js';
 // 工具函数
 export * from './defineAddonConfig.js';
+export * from './defineBeflyConfig.js';
 export * from './addonHelper.js';
 export * from './arrayKeysToCamel.js';
 export * from './arrayToTree.js';

package/dist/regex.js

@@ -27,7 +27,9 @@ export const RegexAliases = {
     /** 字母和数字 */
     alphanumeric: '^[a-zA-Z0-9]+$',
     /** 字母、数字和下划线 */
-    alphanumericUnderscore: '^[a-zA-Z0-9_]+$',
+    alphanumeric_: '^[a-zA-Z0-9_]+$',
+    /** 字母、数字、下划线和短横线 */
+    alphanumericDash_: '^[a-zA-Z0-9_-]+$',
     /** 小写字母 */
     lowercase: '^[a-z]+$',
     /** 大写字母 */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly-shared",
-    "version": "1.1.1",
+    "version": "1.2.0",
     "type": "module",
     "exports": {
         ".": {
@@ -36,5 +36,5 @@
         "merge-anything": "^6.0.6",
         "pathe": "^2.0.3"
     },
-    "gitHead": "2031550167896390ac58c50aeb52b8c23426844e"
+    "gitHead": "ebb51601e566ac01ef09824309a6ec60a5d32388"
 }

package/src/configTypes.ts

@@ -10,10 +10,12 @@ export interface LoadConfigOptions {
     files: string[];
     /** 文件扩展名，默认 ['.js', '.ts', '.json'] */
     extensions?: string[];
-    /** 加载模式：'first' = 返回第一个找到的配置（默认），'all' = 合并所有配置 */
-    mode?: 'all' | 'first';
+    /** 加载模式：'first' = 返回第一个找到的配置（默认），'merge' = 合并所有配置 */
+    mode?: 'merge' | 'first';
     /** 指定要提取的字段路径数组，如 ['menus', 'database.host']，为空则返回完整对象 */
     paths?: string[];
+    /** 默认配置，会与找到的配置合并（优先级最低） */
+    defaults?: Record<string, any>;
 }
 
 /**

package/src/constants.ts

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

package/src/index.ts

@@ -3,15 +3,14 @@
  * 跨包共享的工具函数、常量、类型定义
  */
 
-// 类型定义
-export * from './types.js';
+// 常量（运行时）
+export * from './constants.js';
 
-// 常量配置
+// Redis 键和正则
 export * from './redisKeys.js';
 export * from './regex.js';
 
 // 工具函数
-export * from './defineAddonConfig.js';
 export * from './addonHelper.js';
 export * from './arrayKeysToCamel.js';
 export * from './arrayToTree.js';

package/src/regex.ts

@@ -28,7 +28,9 @@ export const RegexAliases = {
     /** 字母和数字 */
     alphanumeric: '^[a-zA-Z0-9]+$',
     /** 字母、数字和下划线 */
-    alphanumericUnderscore: '^[a-zA-Z0-9_]+$',
+    alphanumeric_: '^[a-zA-Z0-9_]+$',
+    /** 字母、数字、下划线和短横线 */
+    alphanumericDash_: '^[a-zA-Z0-9_-]+$',
     /** 小写字母 */
     lowercase: '^[a-z]+$',
     /** 大写字母 */

package/src/scanConfig.ts

@@ -20,7 +20,8 @@ export async function scanConfig(options: LoadConfigOptions): Promise<Record<str
         files,
         extensions = ['.js', '.ts', '.json'],
         mode = 'first',
-        paths
+        paths,
+        defaults = {}
     } = options;
 
     // 参数验证
@@ -86,7 +87,8 @@ export async function scanConfig(options: LoadConfigOptions): Promise<Record<str
     }
 
     // 合并配置（使用 mergeAndConcat 深度合并）
-    const finalConfig = configs.length > 0 ? mergeAndConcat({}, ...configs) : {};
+    // 合并顺序：defaults ← configs[0] ← configs[1] ← ...
+    const finalConfig = mergeAndConcat(defaults, ...configs);
 
     // 如果指定了 paths，则只返回指定路径的字段
     if (paths && paths.length > 0) {

package/tests/regex.test.ts

@@ -44,9 +44,9 @@ describe('RegexAliases - 正则别名常量', () => {
             expect(new RegExp(RegexAliases.alphanumeric).test('Hello_123')).toBe(false);
         });
 
-        it('alphanumericUnderscore - 字母、数字和下划线', () => {
-            expect(new RegExp(RegexAliases.alphanumericUnderscore).test('Hello_123')).toBe(true);
-            expect(new RegExp(RegexAliases.alphanumericUnderscore).test('Hello-123')).toBe(false);
+        it('alphanumeric_ - 字母、数字和下划线', () => {
+            expect(new RegExp(RegexAliases.alphanumeric_).test('Hello_123')).toBe(true);
+            expect(new RegExp(RegexAliases.alphanumeric_).test('Hello-123')).toBe(false);
         });
     });
 

package/tests/types.test.ts

@@ -3,7 +3,14 @@
  */
 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';
+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 类型', () => {
@@ -241,7 +248,6 @@ describe('befly-shared 类型定义', () => {
 
     describe('BaseRequestContext 类型', () => {
         it('请求上下文基础结构正确', () => {
-            const { BaseRequestContext } = require('../src/types.js') as { BaseRequestContext: any };
             // BaseRequestContext 是接口，只验证可以创建符合结构的对象
             const ctx = {
                 body: { username: 'test' },

package/types/addon.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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/api.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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/common.d.ts

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

package/types/configTypes.d.ts

@@ -14,6 +14,8 @@ export interface LoadConfigOptions {
     mode?: 'all' | 'first';
     /** 指定要提取的字段路径数组，如 ['menus', 'database.host']，为空则返回完整对象 */
     paths?: string[];
+    /** 默认配置对象，会与加载的配置合并 */
+    defaults?: Record<string, any>;
 }
 /**
  * Addon 配置合并选项（已废弃，仅用于向后兼容）

package/types/constants.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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

@@ -0,0 +1,38 @@
+/**
+ * 请求上下文相关类型定义
+ */
+
+/**
+ * 用户信息类型
+ */
+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

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

package/types/database.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 数据库相关类型定义
+ */
+
+/**
+ * SQL 值类型
+ */
+export type SqlValue = string | number | boolean | null | Date;
+
+/**
+ * SQL 参数数组类型
+ */
+export type SqlParams = SqlValue[];
+
+/**
+ * 排序方向
+ */
+export type OrderDirection = 'ASC' | 'DESC' | 'asc' | 'desc';
+
+/**
+ * 数据库类型
+ */
+export type DatabaseType = 'mysql' | 'postgresql' | 'sqlite';
+
+/**
+ * 数据库配置类型
+ */
+export interface DatabaseConfig {
+    /** 数据库类型 */
+    type: DatabaseType;
+    /** 主机地址 */
+    host: string;
+    /** 端口号 */
+    port: number;
+    /** 用户名 */
+    user: string;
+    /** 密码 */
+    password: string;
+    /** 数据库名 */
+    database: string;
+}
+
+/**
+ * Redis 配置类型
+ */
+export interface RedisConfig {
+    /** 主机地址 */
+    host: string;
+    /** 端口号 */
+    port: number;
+    /** 密码 */
+    password?: string;
+    /** 数据库索引 */
+    db?: number;
+}