befly 2.3.2 → 3.0.0

package/utils/datetime.ts

@@ -0,0 +1,51 @@
+/**
+ * Befly 日期时间工具
+ * 提供日期格式化和性能计时功能
+ */
+
+/**
+ * 格式化日期
+ * @param date - 日期对象、时间戳或日期字符串
+ * @param format - 格式化模板（支持 YYYY, MM, DD, HH, mm, ss）
+ * @returns 格式化后的日期字符串
+ *
+ * @example
+ * formatDate(new Date('2025-10-11 15:30:45')) // '2025-10-11 15:30:45'
+ * formatDate(new Date('2025-10-11'), 'YYYY-MM-DD') // '2025-10-11'
+ * formatDate(1728648645000, 'YYYY/MM/DD HH:mm') // '2025/10/11 15:30'
+ * formatDate('2025-10-11', 'MM-DD') // '10-11'
+ */
+export const formatDate = (date: Date | string | number = new Date(), format: string = 'YYYY-MM-DD HH:mm:ss'): string => {
+    const d = new Date(date);
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    const hour = String(d.getHours()).padStart(2, '0');
+    const minute = String(d.getMinutes()).padStart(2, '0');
+    const second = String(d.getSeconds()).padStart(2, '0');
+
+    return format.replace('YYYY', String(year)).replace('MM', month).replace('DD', day).replace('HH', hour).replace('mm', minute).replace('ss', second);
+};
+
+/**
+ * 计算性能时间差
+ * 用于测量代码执行时间（使用 Bun.nanoseconds()）
+ * @param startTime - 开始时间（Bun.nanoseconds()返回值）
+ * @param endTime - 结束时间（可选，默认为当前时间）
+ * @returns 时间差（毫秒或秒）
+ *
+ * @example
+ * const start = Bun.nanoseconds();
+ * // ... 执行代码 ...
+ * const elapsed = calcPerfTime(start); // '15.23 毫秒' 或 '2.45 秒'
+ */
+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/utils/dbHelper.ts

@@ -0,0 +1,142 @@
+/**
+ * Befly 数据库工具
+ * 提供数据库连接和表名转换功能
+ */
+
+import { SQL } from 'bun';
+import { Env } from '../config/env.js';
+import { Logger } from './logger.js';
+import type { SqlClientOptions } from '../types/database.js';
+
+/**
+ * 转换为蛇形命名（snake_case）
+ * 用于将小驼峰命名的表名转换为数据库约定的蛇形命名
+ * @param name - 小驼峰命名的字符串
+ * @returns 蛇形命名的字符串
+ *
+ * @example
+ * toSnakeTableName('userTable') // 'user_table'
+ * toSnakeTableName('testNewFormat') // 'test_new_format'
+ * toSnakeTableName('common') // 'common'
+ * toSnakeTableName('APIKey') // 'api_key'
+ */
+export const toSnakeTableName = (name: string): string => {
+    if (!name) return name;
+    return String(name)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z0-9]+)/g, '$1_$2')
+        .toLowerCase();
+};
+
+/**
+ * 构建数据库连接字符串
+ * 根据环境变量自动构建 SQLite、PostgreSQL 或 MySQL 的连接 URL
+ * @returns 数据库连接字符串
+ * @throws 如果配置不完整或数据库类型不支持
+ *
+ * @example
+ * // SQLite 内存数据库
+ * buildDatabaseUrl() // 'sqlite://:memory:' (当 DB_NAME 为空或 ':memory:')
+ *
+ * // SQLite 文件数据库
+ * buildDatabaseUrl() // 'sqlite://database.db'
+ * buildDatabaseUrl() // 'sqlite://./data/app.db'
+ * buildDatabaseUrl() // 'sqlite:///absolute/path/db.sqlite'
+ *
+ * // PostgreSQL
+ * buildDatabaseUrl() // 'postgres://user:pass@localhost:5432/dbname'
+ *
+ * // MySQL
+ * buildDatabaseUrl() // 'mysql://user:pass@localhost:3306/dbname'
+ */
+export const buildDatabaseUrl = (): string => {
+    const type = Env.DB_TYPE || '';
+    const host = Env.DB_HOST || '';
+    const port = Env.DB_PORT;
+    const user = encodeURIComponent(Env.DB_USER || '');
+    const pass = encodeURIComponent(Env.DB_PASS || '');
+    const name = Env.DB_NAME || '';
+
+    if (!type) throw new Error('DB_TYPE 未配置');
+    if (!name && type !== 'sqlite') throw new Error('DB_NAME 未配置');
+
+    if (type === 'sqlite') {
+        // 支持内存数据库
+        if (!name || name === ':memory:') {
+            return 'sqlite://:memory:';
+        }
+        // 支持绝对路径（以 / 或盘符开头，如 /path 或 C:\path）
+        if (name.startsWith('/') || /^[a-zA-Z]:/.test(name)) {
+            return `sqlite://${name}`;
+        }
+        // 相对路径和普通文件名
+        return `sqlite://${name}`;
+    }
+
+    if (type === 'postgresql' || type === 'postgres') {
+        if (!host || !port) throw new Error('DB_HOST/DB_PORT 未配置');
+        const auth = user || pass ? `${user}:${pass}@` : '';
+        return `postgres://${auth}${host}:${port}/${encodeURIComponent(name)}`;
+    }
+
+    if (type === 'mysql') {
+        if (!host || !port) throw new Error('DB_HOST/DB_PORT 未配置');
+        const auth = user || pass ? `${user}:${pass}@` : '';
+        return `mysql://${auth}${host}:${port}/${encodeURIComponent(name)}`;
+    }
+
+    throw new Error(`不支持的 DB_TYPE: ${type}`);
+};
+
+/**
+ * 创建 SQL 客户端
+ * 根据配置创建并测试数据库连接
+ * @param options - SQL 客户端选项
+ * @returns SQL 客户端实例
+ * @throws 如果连接失败
+ *
+ * @example
+ * const sql = await createSqlClient();
+ * const users = await sql`SELECT * FROM users`;
+ *
+ * // 自定义连接池大小
+ * const sql = await createSqlClient({ max: 10 });
+ */
+export async function createSqlClient(options: SqlClientOptions = {}): Promise<any> {
+    const finalUrl = buildDatabaseUrl();
+    let sql: any = null;
+
+    if (Env.DB_TYPE === 'sqlite') {
+        sql = new SQL(finalUrl);
+    } else {
+        sql = new SQL({
+            url: finalUrl,
+            max: options.max ?? 1,
+            bigint: options.bigint ?? true,
+            ...options
+        });
+    }
+
+    try {
+        // 连接健康检查
+        let version = '';
+        if (Env.DB_TYPE === 'sqlite') {
+            const v = await sql`SELECT sqlite_version() AS version`;
+            version = v?.[0]?.version;
+        } else if (Env.DB_TYPE === 'postgresql' || Env.DB_TYPE === 'postgres') {
+            const v = await sql`SELECT version() AS version`;
+            version = v?.[0]?.version;
+        } else {
+            const v = await sql`SELECT VERSION() AS version`;
+            version = v?.[0]?.version;
+        }
+        Logger.info(`数据库连接成功，version: ${version}`);
+        return sql;
+    } catch (error) {
+        Logger.error('数据库连接测试失败:', error);
+        try {
+            await sql.close();
+        } catch {}
+        throw error;
+    }
+}

package/utils/errorHandler.ts

@@ -0,0 +1,68 @@
+/**
+ * 错误处理器
+ * 提供统一的错误处理策略
+ */
+
+import { Logger } from './logger.js';
+
+/**
+ * 错误处理器类
+ * 提供两种简单的错误处理方式：
+ * - critical: 关键错误，记录日志并退出进程
+ * - warning: 警告错误，只记录日志继续运行
+ */
+export class ErrorHandler {
+    /**
+     * 处理关键错误（会退出进程）
+     * 用于：系统检查失败、核心插件失败、配置错误等
+     *
+     * @param message - 错误消息
+     * @param error - 错误对象（可选）
+     * @param meta - 额外的元数据（可选）
+     */
+    static critical(message: string, error?: Error, meta?: Record<string, any>): never {
+        Logger.error({
+            level: 'CRITICAL',
+            msg: message,
+            error: error?.message,
+            stack: error?.stack,
+            ...meta
+        });
+
+        Logger.error('系统即将退出...');
+        process.exit(1);
+    }
+
+    /**
+     * 处理警告错误（记录但继续运行）
+     * 用于：用户插件失败、单个API加载失败等非关键错误
+     *
+     * @param message - 警告消息
+     * @param error - 错误对象（可选）
+     * @param meta - 额外的元数据（可选）
+     */
+    static warning(message: string, error?: Error, meta?: Record<string, any>): void {
+        Logger.warn({
+            level: 'WARNING',
+            msg: message,
+            error: error?.message,
+            stack: error?.stack,
+            ...meta
+        });
+    }
+
+    /**
+     * 处理信息级别的提示
+     * 用于：非错误的重要信息提示
+     *
+     * @param message - 信息消息
+     * @param meta - 额外的元数据（可选）
+     */
+    static info(message: string, meta?: Record<string, any>): void {
+        Logger.info({
+            level: 'INFO',
+            msg: message,
+            ...meta
+        });
+    }
+}

package/utils/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Befly 工具函数集 - TypeScript 版本
+ *
+ * 本文件作为统一导出入口，从各个专用工具模块重新导出功能
+ * 保持向后兼容性，支持从 utils/index.js 导入所有工具函数
+ */
+
+// ========== API 响应工具 ==========
+export { Yes, No } from './response.js';
+
+// ========== 类型判断工具 ==========
+export { isType, isEmptyObject, isEmptyArray } from './typeHelper.js';
+
+// ========== 对象操作工具 ==========
+export { pickFields, omitFields } from './objectHelper.js';
+
+// ========== 日期时间工具 ==========
+export { formatDate, calcPerfTime } from './datetime.js';
+
+// ========== 数据库工具 ==========
+export { toSnakeTableName, buildDatabaseUrl, createSqlClient } from './dbHelper.js';
+
+// ========== 表定义工具 ==========
+export { parseRule, loadTableFields, pickTableFields } from './tableHelper.js';
+
+// ========== 插件系统工具 ==========
+export { sortPlugins } from './pluginHelper.js';
+
+// 导出其他模块
+export { Colors } from './colors.js';
+export { Logger } from './logger.js';
+export { Validator } from './validate.js';
+export { SqlBuilder } from './sqlBuilder.js';
+export { SqlHelper } from './sqlHelper.js';
+export { RedisHelper, initRedisClient, getRedisClient, closeRedisClient } from './redisHelper.js';
+export { Jwt } from './jwt.js';
+export { Crypto2 } from './crypto.js';
+export { Xml } from './xml.js';
+export { Api } from './api.js';
+export { Tool } from './tool.js';
+
+// 类型导出
+export type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, TransactionCallback } from './sqlHelper.js';
+export type { JwtPayload } from './jwt.js';
+export type { EncodingType, HashAlgorithm } from './crypto.js';
+export type { XmlParseOptions } from './xml.js';