befly 3.0.0 → 3.0.1

package/utils/colors.ts

@@ -1,5 +1,6 @@
 /**
  * 终端颜色工具 - TypeScript 版本
+ * 提供 ANSI 颜色和样式支持，自动检测终端颜色能力
  */
 
 /**
@@ -11,15 +12,28 @@ type Formatter = (input: string | number) => string;
  * 颜色工具接口
  */
 interface ColorsInterface {
+    /** 是否支持颜色 */
     isColorSupported: boolean;
+
+    // 样式
+    /** 重置所有样式 */
     reset: Formatter;
+    /** 加粗 */
     bold: Formatter;
+    /** 变暗 */
     dim: Formatter;
+    /** 斜体 */
     italic: Formatter;
+    /** 下划线 */
     underline: Formatter;
+    /** 反色 */
     inverse: Formatter;
+    /** 隐藏 */
     hidden: Formatter;
+    /** 删除线 */
     strikethrough: Formatter;
+
+    // 前景色（标准）
     black: Formatter;
     red: Formatter;
     green: Formatter;
@@ -29,6 +43,18 @@ interface ColorsInterface {
     cyan: Formatter;
     white: Formatter;
     gray: Formatter;
+
+    // 前景色（高亮）
+    blackBright: Formatter;
+    redBright: Formatter;
+    greenBright: Formatter;
+    yellowBright: Formatter;
+    blueBright: Formatter;
+    magentaBright: Formatter;
+    cyanBright: Formatter;
+    whiteBright: Formatter;
+
+    // 背景色（标准）
     bgBlack: Formatter;
     bgRed: Formatter;
     bgGreen: Formatter;
@@ -37,29 +63,71 @@ interface ColorsInterface {
     bgMagenta: Formatter;
     bgCyan: Formatter;
     bgWhite: Formatter;
-}
 
-interface Process {
-    argv?: string[];
-    env?: Record<string, string | undefined>;
-    platform?: string;
-    stdout?: { isTTY?: boolean };
+    // 背景色（高亮）
+    bgBlackBright: Formatter;
+    bgRedBright: Formatter;
+    bgGreenBright: Formatter;
+    bgYellowBright: Formatter;
+    bgBlueBright: Formatter;
+    bgMagentaBright: Formatter;
+    bgCyanBright: Formatter;
+    bgWhiteBright: Formatter;
+
+    // 语义化颜色（带图标）
+    info: Formatter;
+    success: Formatter;
+    warn: Formatter;
+    error: Formatter;
 }
 
-const p: Process = (typeof process !== 'undefined' ? process : {}) as Process;
-const argv = p.argv || [];
-const env = p.env || {};
+/**
+ * 检测是否支持颜色
+ */
+const detectColorSupport = (): boolean => {
+    const env = process.env || {};
+    const argv = process.argv || [];
+
+    // 明确禁用颜色
+    if (env.NO_COLOR || argv.includes('--no-color')) {
+        return false;
+    }
+
+    // 明确启用颜色
+    if (env.FORCE_COLOR || argv.includes('--color')) {
+        return true;
+    }
+
+    // 根据平台和终端环境判断
+    return process.platform === 'win32' || (process.stdout?.isTTY && env.TERM !== 'dumb') || !!env.CI;
+};
 
-const isColorSupported = !(!!env.NO_COLOR || argv.includes('--no-color')) && (!!env.FORCE_COLOR || argv.includes('--color') || p.platform === 'win32' || ((p.stdout || {}).isTTY && env.TERM !== 'dumb') || !!env.CI);
+const isColorSupported = detectColorSupport();
 
+/**
+ * 创建格式化函数
+ * @param open - 开始 ANSI 码
+ * @param close - 结束 ANSI 码
+ * @param replace - 替换的 ANSI 码（用于嵌套）
+ * @returns 格式化函数
+ */
 const formatter =
     (open: string, close: string, replace: string = open): Formatter =>
     (input: string | number): string => {
-        const string = '' + input;
+        const string = String(input);
         const index = string.indexOf(close, open.length);
+        // 如果字符串中包含结束码，需要处理嵌套情况
         return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close;
     };
 
+/**
+ * 替换字符串中的结束码（处理嵌套颜色）
+ * @param string - 原始字符串
+ * @param close - 结束码
+ * @param replace - 替换码
+ * @param index - 起始索引
+ * @returns 处理后的字符串
+ */
 const replaceClose = (string: string, close: string, replace: string, index: number): string => {
     let result = '';
     let cursor = 0;
@@ -71,11 +139,19 @@ const replaceClose = (string: string, close: string, replace: string, index: num
     return result + string.substring(cursor);
 };
 
+/**
+ * 创建颜色工具实例
+ * @param enabled - 是否启用颜色
+ * @returns 颜色工具对象
+ */
 const createColors = (enabled: boolean = isColorSupported): ColorsInterface => {
-    const f = enabled ? formatter : (): Formatter => String as Formatter;
+    // 如果禁用颜色，返回直接转字符串的函数
+    const f = enabled ? formatter : (): Formatter => (input: string | number) => String(input);
 
-    const baseColors = {
+    return {
         isColorSupported: enabled,
+
+        // 样式 - https://en.wikipedia.org/wiki/ANSI_escape_code#SGR
         reset: f('\x1b[0m', '\x1b[0m'),
         bold: f('\x1b[1m', '\x1b[22m', '\x1b[22m\x1b[1m'),
         dim: f('\x1b[2m', '\x1b[22m', '\x1b[22m\x1b[2m'),
@@ -85,6 +161,7 @@ const createColors = (enabled: boolean = isColorSupported): ColorsInterface => {
         hidden: f('\x1b[8m', '\x1b[28m'),
         strikethrough: f('\x1b[9m', '\x1b[29m'),
 
+        // 前景色（标准） - 30-37
         black: f('\x1b[30m', '\x1b[39m'),
         red: f('\x1b[31m', '\x1b[39m'),
         green: f('\x1b[32m', '\x1b[39m'),
@@ -93,17 +170,9 @@ const createColors = (enabled: boolean = isColorSupported): ColorsInterface => {
         magenta: f('\x1b[35m', '\x1b[39m'),
         cyan: f('\x1b[36m', '\x1b[39m'),
         white: f('\x1b[37m', '\x1b[39m'),
-        gray: f('\x1b[90m', '\x1b[39m'),
-
-        bgBlack: f('\x1b[40m', '\x1b[49m'),
-        bgRed: f('\x1b[41m', '\x1b[49m'),
-        bgGreen: f('\x1b[42m', '\x1b[49m'),
-        bgYellow: f('\x1b[43m', '\x1b[49m'),
-        bgBlue: f('\x1b[44m', '\x1b[49m'),
-        bgMagenta: f('\x1b[45m', '\x1b[49m'),
-        bgCyan: f('\x1b[46m', '\x1b[49m'),
-        bgWhite: f('\x1b[47m', '\x1b[49m'),
+        gray: f('\x1b[90m', '\x1b[39m'), // 实际上是 blackBright
 
+        // 前景色（高亮） - 90-97
         blackBright: f('\x1b[90m', '\x1b[39m'),
         redBright: f('\x1b[91m', '\x1b[39m'),
         greenBright: f('\x1b[92m', '\x1b[39m'),
@@ -113,6 +182,17 @@ const createColors = (enabled: boolean = isColorSupported): ColorsInterface => {
         cyanBright: f('\x1b[96m', '\x1b[39m'),
         whiteBright: f('\x1b[97m', '\x1b[39m'),
 
+        // 背景色（标准） - 40-47
+        bgBlack: f('\x1b[40m', '\x1b[49m'),
+        bgRed: f('\x1b[41m', '\x1b[49m'),
+        bgGreen: f('\x1b[42m', '\x1b[49m'),
+        bgYellow: f('\x1b[43m', '\x1b[49m'),
+        bgBlue: f('\x1b[44m', '\x1b[49m'),
+        bgMagenta: f('\x1b[45m', '\x1b[49m'),
+        bgCyan: f('\x1b[46m', '\x1b[49m'),
+        bgWhite: f('\x1b[47m', '\x1b[49m'),
+
+        // 背景色（高亮） - 100-107
         bgBlackBright: f('\x1b[100m', '\x1b[49m'),
         bgRedBright: f('\x1b[101m', '\x1b[49m'),
         bgGreenBright: f('\x1b[102m', '\x1b[49m'),
@@ -122,20 +202,20 @@ const createColors = (enabled: boolean = isColorSupported): ColorsInterface => {
         bgCyanBright: f('\x1b[106m', '\x1b[49m'),
         bgWhiteBright: f('\x1b[107m', '\x1b[49m'),
 
-        info: '',
-        success: '',
-        warn: '',
-        error: ''
+        // 语义化颜色（函数形式，带图标前缀）
+        info: (input: string | number) => f('\x1b[34m', '\x1b[39m')(`ℹ ${input}`),
+        success: (input: string | number) => f('\x1b[32m', '\x1b[39m')(`✓ ${input}`),
+        warn: (input: string | number) => f('\x1b[33m', '\x1b[39m')(`⚠ ${input}`),
+        error: (input: string | number) => f('\x1b[31m', '\x1b[39m')(`✖ ${input}`)
     };
-
-    // 添加图标
-    baseColors.info = baseColors.blue('i');
-    baseColors.success = baseColors.green('√');
-    baseColors.warn = baseColors.yellow('‼');
-    baseColors.error = baseColors.red('x');
-
-    return baseColors;
 };
 
-export const colors = createColors();
-export { colors as Colors }; // 别名导出，保持向后兼容
+/**
+ * 默认颜色工具实例
+ */
+export const Colors = createColors();
+
+/**
+ * 导出类型
+ */
+export type { ColorsInterface, Formatter };

package/utils/database.ts

@@ -0,0 +1,348 @@
+/**
+ * 数据库统一管理工具
+ * 提供 Redis 和 SQL 连接的统一初始化和管理
+ */
+
+import { SQL, RedisClient } from 'bun';
+import { Env } from '../config/env.js';
+import { Logger } from './logger.js';
+import { DbHelper } from './dbHelper.js';
+import { RedisHelper } from './redisHelper.js';
+import type { BeflyContext } from '../types/befly.js';
+import type { SqlClientOptions } from '../types/database.js';
+
+/**
+ * 数据库连接实例
+ */
+interface DatabaseConnections {
+    redis: RedisClient | null;
+    sql: any;
+    helper: DbHelper | null;
+}
+
+/**
+ * 全局连接实例
+ */
+const connections: DatabaseConnections = {
+    redis: null,
+    sql: null,
+    helper: null
+};
+
+/**
+ * 构建 Redis 连接 URL
+ * @returns Redis 连接 URL
+ */
+export function buildRedisUrl(): string {
+    const { REDIS_HOST, REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, REDIS_DB } = Env;
+
+    // 构建认证部分
+    let auth = '';
+    if (REDIS_USERNAME && REDIS_PASSWORD) {
+        auth = `${REDIS_USERNAME}:${REDIS_PASSWORD}@`;
+    } else if (REDIS_PASSWORD) {
+        auth = `:${REDIS_PASSWORD}@`;
+    }
+
+    // 构建完整 URL
+    const url = `redis://${auth}${REDIS_HOST}:${REDIS_PORT}/${REDIS_DB}`;
+
+    return url;
+}
+
+/**
+ * 构建数据库连接字符串
+ * 根据环境变量自动构建 SQLite、PostgreSQL 或 MySQL 的连接 URL
+ * @returns 数据库连接字符串
+ * @throws 如果配置不完整或数据库类型不支持
+ */
+export function 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}`);
+}
+
+/**
+ * 创建 Redis 客户端
+ * @returns Redis 客户端实例
+ * @throws 如果连接失败
+ */
+export async function createRedisClient(): Promise<RedisClient> {
+    try {
+        const url = buildRedisUrl();
+        const redis = new RedisClient(url, {
+            // 连接超时（毫秒）
+            connectionTimeout: 10000,
+            // 空闲超时设为 0，表示永不超时
+            idleTimeout: 0,
+            // 断开连接时自动重连
+            autoReconnect: true,
+            // 最大重连次数，0 表示无限重连
+            maxRetries: 0,
+            // 断开连接时缓存命令
+            enableOfflineQueue: true,
+            // 自动管道化命令
+            enableAutoPipelining: true
+        });
+
+        // 测试连接是否成功
+        await redis.ping();
+        Logger.info('Redis 连接成功');
+
+        return redis;
+    } catch (error: any) {
+        Logger.error('Redis 连接失败', error);
+        throw new Error(`Redis 连接失败: ${error.message}`);
+    }
+}
+
+/**
+ * 创建 SQL 客户端
+ * @param options SQL 客户端选项
+ * @returns SQL 客户端实例
+ * @throws 如果连接失败
+ */
+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: false,
+            ...options
+        });
+    }
+
+    try {
+        // 连接健康检查 - 添加超时机制
+        const timeout = options.connectionTimeout ?? 5000; // 默认5秒超时
+
+        const healthCheckPromise = (async () => {
+            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;
+            }
+            return version;
+        })();
+
+        // 创建超时 Promise
+        const timeoutPromise = new Promise<never>((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`数据库连接超时 (${timeout}ms)`));
+            }, timeout);
+        });
+
+        // 使用 Promise.race 实现超时控制
+        const version = await Promise.race([healthCheckPromise, timeoutPromise]);
+
+        Logger.info(`数据库连接成功，version: ${version}`);
+        return sql;
+    } catch (error: any) {
+        Logger.error('数据库连接测试失败', error);
+
+        // 清理资源
+        try {
+            await sql.close();
+        } catch (cleanupError) {
+            // 忽略清理错误
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * 初始化数据库连接（Redis + SQL）
+ * @param options SQL 客户端选项
+ * @returns 数据库连接实例
+ */
+export async function initDatabase(options: SqlClientOptions = {}): Promise<DatabaseConnections> {
+    try {
+        // 1. 初始化 Redis
+        Logger.info('正在初始化 Redis 连接...');
+        connections.redis = await createRedisClient();
+
+        // 2. 初始化 SQL
+        Logger.info('正在初始化 SQL 连接...');
+        connections.sql = await createSqlClient(options);
+
+        // 3. 创建 DbHelper 实例
+        const befly: BeflyContext = {
+            redis: RedisHelper, // 使用 RedisHelper 对象而不是 RedisClient
+            db: null as any,
+            tool: null as any,
+            logger: null as any
+        };
+        connections.helper = new DbHelper(befly, connections.sql);
+
+        Logger.info('数据库连接初始化完成（Redis + SQL + DbHelper）');
+
+        return {
+            redis: connections.redis,
+            sql: connections.sql,
+            helper: connections.helper
+        };
+    } catch (error: any) {
+        Logger.error('数据库初始化失败', error);
+        // 清理已创建的连接
+        await closeDatabase();
+        throw error;
+    }
+}
+
+/**
+ * 关闭所有数据库连接
+ */
+export async function closeDatabase(): Promise<void> {
+    try {
+        // 关闭 SQL 连接
+        if (connections.sql) {
+            try {
+                await connections.sql.close();
+                Logger.info('SQL 连接已关闭');
+            } catch (error: any) {
+                Logger.warn('关闭 SQL 连接时出错:', error.message);
+            }
+            connections.sql = null;
+        }
+
+        // 关闭 Redis 连接
+        if (connections.redis) {
+            try {
+                connections.redis.close();
+                Logger.info('Redis 连接已关闭');
+            } catch (error: any) {
+                Logger.warn('关闭 Redis 连接时出错:', error);
+            }
+            connections.redis = null;
+        }
+
+        // 清理 DbHelper
+        connections.helper = null;
+    } catch (error: any) {
+        Logger.error('关闭数据库连接时出错', error);
+    }
+}
+
+/**
+ * 获取 Redis 客户端
+ * @returns Redis 客户端实例
+ */
+export function getRedis(): RedisClient | null {
+    return connections.redis;
+}
+
+/**
+ * 获取 SQL 客户端
+ * @returns SQL 客户端实例
+ */
+export function getSql(): any {
+    return connections.sql;
+}
+
+/**
+ * 获取 DbHelper 实例
+ * @returns DbHelper 实例
+ */
+export function getDbHelper(): DbHelper | null {
+    return connections.helper;
+}
+
+/**
+ * 检查数据库连接是否已初始化
+ * @returns 是否已初始化
+ */
+export function isDatabaseInitialized(): boolean {
+    return connections.redis !== null && connections.sql !== null && connections.helper !== null;
+}
+
+/**
+ * 仅初始化 SQL 连接（不需要 Redis 时使用）
+ * @param options SQL 客户端选项
+ * @returns SQL 客户端和 DbHelper 实例
+ */
+export async function initSqlOnly(options: SqlClientOptions = {}): Promise<{ sql: any; helper: DbHelper }> {
+    try {
+        Logger.info('正在初始化 SQL 连接（不含 Redis）...');
+        connections.sql = await createSqlClient(options);
+
+        // 创建最小化 befly 上下文（不含 redis）
+        const befly: BeflyContext = {
+            redis: null as any,
+            db: null as any,
+            tool: null as any,
+            logger: null as any
+        };
+        connections.helper = new DbHelper(befly, connections.sql);
+
+        Logger.info('SQL 连接初始化完成');
+
+        return {
+            sql: connections.sql,
+            helper: connections.helper
+        };
+    } catch (error: any) {
+        Logger.error('SQL 初始化失败', error);
+        throw error;
+    }
+}
+
+/**
+ * 仅初始化 Redis 连接（不需要 SQL 时使用）
+ * @returns Redis 客户端实例
+ */
+export async function initRedisOnly(): Promise<RedisClient> {
+    try {
+        Logger.info('正在初始化 Redis 连接（不含 SQL）...');
+        connections.redis = await createRedisClient();
+        Logger.info('Redis 连接初始化完成');
+        return connections.redis;
+    } catch (error: any) {
+        Logger.error('Redis 初始化失败', error);
+        throw error;
+    }
+}