befly-shared 1.1.1 → 1.2.0

package/types/index.d.ts

@@ -2,10 +2,9 @@
  * Befly Shared 统一导出
  * 跨包共享的工具函数、常量、类型定义
  */
-export * from './types.js';
+export * from './constants.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';

package/types/jwt.d.ts

@@ -0,0 +1,99 @@
+/**
+ * JWT 相关类型定义
+ */
+
+/**
+ * JWT 算法类型
+ */
+export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512';
+
+/**
+ * JWT Header 接口
+ */
+export interface JwtHeader {
+    alg: JwtAlgorithm;
+    typ: 'JWT';
+}
+
+/**
+ * JWT 完整解码结果
+ */
+export interface JwtDecoded {
+    header: JwtHeader;
+    payload: JwtPayload;
+    signature: string;
+}
+
+/**
+ * JWT 载荷
+ */
+export interface JwtPayload {
+    /** 用户 ID */
+    userId?: string;
+    /** 用户名 */
+    username?: string;
+    /** 角色 */
+    role?: string;
+    /** 角色列表 */
+    roles?: string[];
+    /** 权限列表 */
+    permissions?: string[];
+    /** 签发时间 */
+    iat?: number;
+    /** 过期时间 */
+    exp?: number;
+    /** 主题 */
+    sub?: string;
+    /** 签发者 */
+    iss?: string;
+    /** 受众 */
+    aud?: string | string[];
+    /** JWT ID */
+    jti?: string;
+    /** 生效时间 */
+    nbf?: number;
+    /** 其他自定义字段 */
+    [key: string]: any;
+}
+
+/**
+ * JWT 签名选项
+ */
+export interface JwtSignOptions {
+    /** 密钥 */
+    secret?: string;
+    /** 算法 */
+    algorithm?: JwtAlgorithm;
+    /** 过期时间 */
+    expiresIn?: string | number;
+    /** 签发者 */
+    issuer?: string;
+    /** 受众 */
+    audience?: string;
+    /** 主题 */
+    subject?: string;
+    /** 生效时间 */
+    notBefore?: string | number;
+    /** JWT ID */
+    jwtId?: string;
+}
+
+/**
+ * JWT 验证选项
+ */
+export interface JwtVerifyOptions {
+    /** 密钥 */
+    secret?: string;
+    /** 算法列表 */
+    algorithms?: JwtAlgorithm[];
+    /** 签发者 */
+    issuer?: string;
+    /** 受众 */
+    audience?: string;
+    /** 主题 */
+    subject?: string;
+    /** 是否忽略过期 */
+    ignoreExpiration?: boolean;
+    /** 是否忽略生效时间 */
+    ignoreNotBefore?: boolean;
+}

package/types/logger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 日志相关类型定义
+ */
+
+/**
+ * 日志级别
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/**
+ * 日志配置
+ */
+export interface LoggerConfig {
+    /** 是否开启调试模式 (0: 关闭, 1: 开启) @default 0 */
+    debug?: number;
+    /** 日志目录 @default './logs' */
+    dir?: string;
+    /** 是否输出到控制台 (0: 关闭, 1: 开启) @default 1 */
+    console?: number;
+    /** 单个日志文件最大大小 (MB) @default 10 */
+    maxSize?: number;
+}

package/types/menu.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 菜单权限相关类型定义
+ */
+
+/**
+ * 菜单项类型
+ */
+export interface MenuItem {
+    /** 菜单 ID */
+    id: number;
+    /** 父级 ID */
+    pid: number;
+    /** 菜单名称 */
+    name: string;
+    /** 菜单路径 */
+    path: string;
+    /** 菜单图标 */
+    icon?: string;
+    /** 排序 */
+    sort: number;
+    /** 是否隐藏 */
+    hidden?: boolean;
+    /** 子菜单 */
+    children?: MenuItem[];
+}
+
+/**
+ * 权限项类型
+ */
+export interface PermissionItem {
+    /** API 路由（如 POST/api/user/list） */
+    route: string;
+    /** 权限名称 */
+    name: string;
+}
+
+/**
+ * 角色信息类型
+ */
+export interface RoleInfo {
+    /** 角色 ID */
+    id: number;
+    /** 角色代码 */
+    code: string;
+    /** 角色名称 */
+    name: string;
+    /** 角色描述 */
+    desc?: string;
+}

package/types/regex.d.ts

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

package/types/table.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 表结构相关类型定义
+ */
+
+/**
+ * 保留字段（系统自动管理）
+ */
+export type ReservedFields = 'id' | 'created_at' | 'updated_at' | 'deleted_at' | 'state';
+
+/**
+ * 系统字段（所有表都有的字段）
+ */
+export interface SystemFields {
+    /** 主键 ID（雪花 ID） */
+    id: number;
+    /** 状态：0=已删除, 1=正常, 2=禁用 */
+    state: number;
+    /** 创建时间（毫秒时间戳） */
+    createdAt: number;
+    /** 更新时间（毫秒时间戳） */
+    updatedAt: number;
+    /** 删除时间（毫秒时间戳，软删除时设置） */
+    deletedAt: number | null;
+}
+
+/**
+ * 基础表类型（包含系统字段）
+ */
+export type BaseTable<T extends Record<string, any>> = T & SystemFields;
+
+/**
+ * 插入类型：排除系统自动生成的字段
+ */
+export type InsertType<T> = Omit<T, keyof SystemFields>;
+
+/**
+ * 更新类型：所有字段可选，排除不可修改的系统字段
+ */
+export type UpdateType<T> = Partial<Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'deletedAt'>>;
+
+/**
+ * 查询结果类型：完整的表记录
+ */
+export type SelectType<T> = T;
+
+/**
+ * 排除保留字段
+ */
+export type ExcludeReserved<T> = Omit<T, ReservedFields>;

package/types/tool.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 工具函数相关类型定义
+ */
+
+/**
+ * 日期格式化类型
+ */
+export type DateFormat = 'YYYY-MM-DD' | 'YYYY-MM-DD HH:mm:ss' | 'HH:mm:ss' | 'YYYY/MM/DD' | 'MM-DD' | string;
+
+/**
+ * 颜色代码
+ */
+export type ColorCode = 'reset' | 'bright' | 'dim' | 'underscore' | 'blink' | 'reverse' | 'hidden' | 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white';
+
+/**
+ * 分页参数
+ */
+export interface PaginationParams {
+    /** 页码（从 1 开始） */
+    page?: number;
+    /** 每页数量 */
+    limit?: number;
+}
+
+/**
+ * 分页结果
+ */
+export interface PaginationResult<T = any> {
+    /** 数据列表 */
+    list: T[];
+    /** 总条数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    limit: number;
+    /** 总页数 */
+    pages: number;
+    /** 是否有下一页 */
+    hasNext: boolean;
+    /** 是否有上一页 */
+    hasPrev: boolean;
+}
+
+/**
+ * 文件类型
+ */
+export type FileType = 'image' | 'video' | 'audio' | 'document' | 'archive' | 'other';
+
+/**
+ * MIME 类型
+ */
+export type MimeType = string;
+
+/**
+ * 文件上传选项
+ */
+export interface FileUploadOptions {
+    /** 允许的文件类型 */
+    allowedTypes?: string[];
+    /** 最大文件大小（字节） */
+    maxSize?: number;
+    /** 保存目录 */
+    saveDir?: string;
+    /** 文件名生成函数 */
+    filename?: (originalName: string) => string;
+}

package/types/types.d.ts

@@ -1,274 +1,44 @@
 /**
- * Befly 共享类型定义
+ * Befly 共享类型定义 - 统一导出入口
  * 这些类型可以在 core、tpl、admin 等多个包中复用
  */
-/**
- * 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;
-}
-/**
- * 验证结果类型
- */
-export interface ValidationResult {
-    /** 验证状态：0 成功，1 失败 */
-    code: 0 | 1;
-    /** 字段错误信息 */
-    fields: Record<string, string>;
-}
-/**
- * HTTP 方法类型
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
-/**
- * 通用键值对类型
- */
-export type KeyValue<T = any> = Record<string, T>;
-/**
- * 字段类型
- */
-export type FieldType = 'string' | 'number' | 'text' | 'array_string' | 'array_text';
-/**
- * 字段定义类型（对象格式）
- */
-export interface FieldDefinition {
-    /** 字段标签/描述 */
-    name: string;
-    /** 字段详细说明 */
-    detail: string;
-    /** 字段类型 */
-    type: FieldType;
-    /** 最小值/最小长度 */
-    min: number | null;
-    /** 最大值/最大长度 */
-    max: number | null;
-    /** 默认值 */
-    default: any;
-    /** 是否创建索引 */
-    index: boolean;
-    /** 是否唯一 */
-    unique: boolean;
-    /** 字段注释 */
-    comment: string;
-    /** 是否允许为空 */
-    nullable: boolean;
-    /** 是否无符号（仅 number 类型） */
-    unsigned: boolean;
-    /** 正则验证 */
-    regexp: string | null;
-}
-/**
- * 表定义类型（对象格式）
- */
-export type TableDefinition = Record<string, FieldDefinition>;
-/**
- * 用户信息类型
- */
-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;
-}
-/**
- * API 路由基础配置
- * 用于跨包共享的最小路由定义
- */
-export interface BaseApiRoute {
-    /** 接口名称（必填） */
-    name: string;
-    /** HTTP 方法（可选，默认 POST） */
-    method?: HttpMethod;
-    /** 认证类型（可选，默认 true） */
-    auth?: boolean;
-    /** 字段定义（验证规则） */
-    fields?: TableDefinition;
-    /** 必填字段 */
-    required?: string[];
-    /** 路由路径（运行时生成） */
-    route?: string;
-}
-/**
- * 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;
-}
-/**
- * 菜单项类型
- */
-export interface MenuItem {
-    /** 菜单 ID */
-    id: number;
-    /** 父级 ID */
-    pid: number;
-    /** 菜单名称 */
-    name: string;
-    /** 菜单路径 */
-    path: string;
-    /** 菜单图标 */
-    icon?: string;
-    /** 排序 */
-    sort: number;
-    /** 是否隐藏 */
-    hidden?: boolean;
-    /** 子菜单 */
-    children?: MenuItem[];
-}
-/**
- * 权限项类型
- */
-export interface PermissionItem {
-    /** API 路由（如 POST/api/user/list） */
-    route: string;
-    /** 权限名称 */
-    name: string;
-}
-/**
- * 角色信息类型
- */
-export interface RoleInfo {
-    /** 角色 ID */
-    id: number;
-    /** 角色代码 */
-    code: string;
-    /** 角色名称 */
-    name: string;
-    /** 角色描述 */
-    desc?: string;
-}
-/**
- * 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];
+
+// 常量（从 constants 导出）
+export { ApiCode, ErrorMessages } from './constants';
+export type { ApiCodeType, ErrorMessageType } from './constants';
+
+// 验证相关
+export type { FieldType, FieldDefinition, TableDefinition, ValidateResult, SingleResult } from './validate';
+
+// API 相关
+export type { HttpMethod, ResponseResult, PaginatedResult, BaseApiRoute } from './api';
+
+// 数据库相关
+export type { SqlValue, SqlParams, OrderDirection, DatabaseType, DatabaseConfig, RedisConfig } from './database';
+
+// 上下文相关
+export type { UserInfo, BaseRequestContext } from './context';
+
+// 菜单权限相关
+export type { MenuItem, PermissionItem, RoleInfo } from './menu';
+
+// 通用类型
+export type { KeyValue } from './common';
+
+// Addon 相关
+export type { AddonAuthor, AddonConfig } from './addon';
+
+// 日志相关
+export type { LogLevel, LoggerConfig } from './logger';
+
+// 加密相关
+export type { EncodingType, HashAlgorithm, PasswordHashOptions } from './crypto';
+
+// JWT 相关
+export type { JwtAlgorithm, JwtHeader, JwtDecoded, JwtPayload, JwtSignOptions, JwtVerifyOptions } from './jwt';
+
+// 工具相关
+export type { DateFormat, ColorCode, PaginationParams, PaginationResult, FileType, MimeType, FileUploadOptions } from './tool';
+
+// 表结构相关
+export type { ReservedFields, SystemFields, BaseTable, InsertType, UpdateType, SelectType, ExcludeReserved } from './table';

package/types/validate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 验证相关类型定义
+ */
+
+/**
+ * 字段类型
+ */
+export type FieldType = 'string' | 'number' | 'text' | 'array_string' | 'array_text';
+
+/**
+ * 字段定义类型（对象格式）
+ */
+export interface FieldDefinition {
+    /** 字段标签/描述 */
+    name: string;
+    /** 字段详细说明 */
+    detail: string;
+    /** 字段类型 */
+    type: FieldType;
+    /** 最小值/最小长度 */
+    min: number | null;
+    /** 最大值/最大长度 */
+    max: number | null;
+    /** 默认值 */
+    default: any;
+    /** 是否创建索引 */
+    index: boolean;
+    /** 是否唯一 */
+    unique: boolean;
+    /** 字段注释 */
+    comment: string;
+    /** 是否允许为空 */
+    nullable: boolean;
+    /** 是否无符号（仅 number 类型） */
+    unsigned: boolean;
+    /** 正则验证 */
+    regexp: string | null;
+}
+
+/**
+ * 表定义类型（对象格式）
+ */
+export type TableDefinition = Record<string, FieldDefinition>;
+
+/**
+ * 验证结果类型
+ */
+export interface ValidateResult {
+    /** 状态码：0=通过，1=失败 */
+    code: 0 | 1;
+    /** 是否失败 */
+    failed: boolean;
+    /** 第一个错误 */
+    firstError: string | null;
+    /** 所有错误 */
+    errors: string[];
+    /** 错误字段列表 */
+    errorFields: string[];
+    /** 字段错误映射 */
+    fieldErrors: Record<string, string>;
+}
+
+/**
+ * 单值验证结果
+ */
+export interface SingleResult {
+    /** 转换后的值 */
+    value: any;
+    /** 错误信息（null 表示通过） */
+    error: string | null;
+}