befly 3.0.0 → 3.1.1

package/utils/errorHandler.ts

@@ -1,68 +0,0 @@
-/**
- * 错误处理器
- * 提供统一的错误处理策略
- */
-
-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/objectHelper.ts

@@ -1,68 +0,0 @@
-/**
- * Befly 对象操作工具
- * 提供对象和数组的处理功能
- */
-
-import { isType } from './typeHelper.js';
-
-/**
- * 挑选指定字段
- * @param obj - 源对象
- * @param keys - 要挑选的字段名数组
- * @returns 包含指定字段的新对象
- *
- * @example
- * pickFields({ a: 1, b: 2, c: 3 }, ['a', 'c']) // { a: 1, c: 3 }
- * pickFields({ name: 'John', age: 30 }, ['name']) // { name: 'John' }
- */
-export const pickFields = <T extends Record<string, any>>(obj: T, keys: string[]): Partial<T> => {
-    if (!obj || (!isType(obj, 'object') && !isType(obj, 'array'))) {
-        return {};
-    }
-
-    const result: any = {};
-    for (const key of keys) {
-        if (key in obj) {
-            result[key] = obj[key];
-        }
-    }
-
-    return result;
-};
-
-/**
- * 排除指定字段和值
- * @param data - 源数据（对象或数组）
- * @param excludeKeys - 要排除的字段名数组
- * @param excludeValues - 要排除的值数组
- * @returns 排除指定字段和值后的新数据
- *
- * @example
- * omitFields({ a: 1, b: 2, c: 3 }, ['b']) // { a: 1, c: 3 }
- * omitFields({ a: 1, b: null, c: 3 }, [], [null]) // { a: 1, c: 3 }
- * omitFields([{ a: 1 }, { a: 2 }], ['a']) // [{}, {}]
- */
-export const omitFields = <T = any>(data: T, excludeKeys: string[] = [], excludeValues: any[] = []): T | Partial<T> => {
-    const shouldDropValue = (v: any): boolean => excludeValues.some((x) => x === v);
-
-    const cleanObject = (obj: any): any => {
-        if (!isType(obj, 'object')) return obj;
-        const result: any = {};
-        for (const [k, v] of Object.entries(obj)) {
-            if (excludeKeys.includes(k)) continue;
-            if (shouldDropValue(v)) continue;
-            result[k] = v;
-        }
-        return result;
-    };
-
-    if (isType(data, 'array')) {
-        return (data as any).filter((item: any) => !shouldDropValue(item)).map((item: any) => (isType(item, 'object') ? cleanObject(item) : item));
-    }
-
-    if (isType(data, 'object')) {
-        return cleanObject(data);
-    }
-
-    return data;
-};

package/utils/pluginHelper.ts

@@ -1,62 +0,0 @@
-/**
- * Befly 插件系统工具
- * 提供插件依赖排序功能
- */
-
-import type { Plugin } from '../types/plugin.js';
-
-/**
- * 排序插件（根据依赖关系）
- * 使用拓扑排序算法，确保依赖的插件先加载
- *
- * @param plugins - 插件数组
- * @returns 排序后的插件数组，如果存在循环依赖则返回 false
- *
- * @example
- * const plugins = [
- *   { name: 'logger', dependencies: [] },
- *   { name: 'db', dependencies: ['logger'] },
- *   { name: 'api', dependencies: ['db', 'logger'] }
- * ];
- *
- * const sorted = sortPlugins(plugins);
- * // [
- * //   { name: 'logger', dependencies: [] },
- * //   { name: 'db', dependencies: ['logger'] },
- * //   { name: 'api', dependencies: ['db', 'logger'] }
- * // ]
- *
- * // 循环依赖示例
- * const badPlugins = [
- *   { name: 'a', dependencies: ['b'] },
- *   { name: 'b', dependencies: ['a'] }
- * ];
- * sortPlugins(badPlugins); // false
- */
-export const sortPlugins = (plugins: Plugin[]): Plugin[] | false => {
-    const result: Plugin[] = [];
-    const visited = new Set<string>();
-    const visiting = new Set<string>();
-    const pluginMap: Record<string, Plugin> = Object.fromEntries(plugins.map((p) => [p.name, p]));
-    let isPass = true;
-
-    const visit = (name: string): void => {
-        if (visited.has(name)) return;
-        if (visiting.has(name)) {
-            isPass = false;
-            return;
-        }
-
-        const plugin = pluginMap[name];
-        if (!plugin) return; // 依赖不存在时跳过
-
-        visiting.add(name);
-        (plugin.dependencies || []).forEach(visit);
-        visiting.delete(name);
-        visited.add(name);
-        result.push(plugin);
-    };
-
-    plugins.forEach((p) => visit(p.name));
-    return isPass ? result : false;
-};

package/utils/response.ts

@@ -1,38 +0,0 @@
-/**
- * Befly API 响应工具
- * 提供统一的成功和失败响应格式
- */
-
-import type { KeyValue } from '../types/common.js';
-
-/**
- * 成功响应
- * @param msg - 响应消息
- * @param data - 响应数据
- * @param other - 其他字段
- * @returns 成功响应对象 { code: 0, msg, data, ...other }
- */
-export const Yes = <T = any>(msg: string = '', data: T | {} = {}, other: KeyValue = {}): { code: 0; msg: string; data: T | {} } & KeyValue => {
-    return {
-        ...other,
-        code: 0,
-        msg: msg,
-        data: data
-    };
-};
-
-/**
- * 失败响应
- * @param msg - 错误消息
- * @param data - 错误数据
- * @param other - 其他字段
- * @returns 失败响应对象 { code: 1, msg, data, ...other }
- */
-export const No = <T = any>(msg: string = '', data: T | {} = {}, other: KeyValue = {}): { code: 1; msg: string; data: T | {} } & KeyValue => {
-    return {
-        ...other,
-        code: 1,
-        msg: msg,
-        data: data
-    };
-};

package/utils/sqlHelper.ts

@@ -1,447 +0,0 @@
-/**
- * SQL 助手 - TypeScript 版本
- * 提供数据库 CRUD 操作的封装
- */
-
-import { SqlBuilder } from './sqlBuilder.js';
-import type { WhereConditions } from '../types/common.js';
-import type { BeflyContext } from '../types/befly.js';
-import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, TransactionCallback } from '../types/database.js';
-
-/**
- * SQL 助手类
- */
-export class SqlHelper {
-    private befly: BeflyContext;
-    private sql: any = null;
-    private isTransaction: boolean = false;
-
-    /**
-     * 构造函数
-     * @param befly - Befly 上下文
-     * @param sql - Bun SQL 客户端（可选，用于事务）
-     */
-    constructor(befly: BeflyContext, sql: any = null) {
-        this.befly = befly;
-        this.sql = sql;
-        this.isTransaction = !!sql;
-    }
-
-    /**
-     * 处理插入数据（强制生成系统字段，用户不可覆盖）
-     */
-    private async processDataForInsert(data: Record<string, any>): Promise<Record<string, any>> {
-        // 复制用户数据，但移除系统字段（防止用户尝试覆盖）
-        const { id, created_at, updated_at, deleted_at, state, ...userData } = data;
-
-        const processed: Record<string, any> = { ...userData };
-
-        // 强制生成 ID（不可被用户覆盖）
-        try {
-            processed.id = await this.befly.redis.genTimeID();
-        } catch (error: any) {
-            throw new Error(`生成 ID 失败，Redis 可能不可用：${error.message}`);
-        }
-
-        // 强制生成时间戳（不可被用户覆盖）
-        const now = Date.now();
-        processed.created_at = now;
-        processed.updated_at = now;
-
-        // 强制设置 state 为 1（激活状态，不可被用户覆盖）
-        processed.state = 1;
-
-        // 注意：deleted_at 字段不在插入时生成，只在软删除时设置
-
-        return processed;
-    }
-
-    /**
-     * 添加默认 state 过滤（排除已删除数据）
-     */
-    private addDefaultStateFilter(where: WhereConditions | undefined, includeDeleted: boolean = false, customState?: WhereConditions): WhereConditions {
-        if (includeDeleted) {
-            return where || {};
-        }
-
-        // 如果有自定义 state 条件，使用自定义条件
-        if (customState) {
-            return where ? { ...where, ...customState } : customState;
-        }
-
-        // 检查用户是否已经在 where 中指定了 state 条件
-        if (where && 'state' in where) {
-            // 用户已指定 state 条件，直接返回，不覆盖
-            return where;
-        }
-
-        // 默认排除已删除（state = 0）
-        const stateFilter: WhereConditions = { state: { $gt: 0 } };
-        return where ? { ...where, ...stateFilter } : stateFilter;
-    }
-
-    /**
-     * 执行 SQL（使用 sql.unsafe，带慢查询日志）
-     */
-    private async executeWithConn(sqlStr: string, params?: any[]): Promise<any> {
-        if (!this.sql) {
-            throw new Error('数据库连接未初始化');
-        }
-
-        // 记录开始时间
-        const startTime = Date.now();
-
-        // 使用 sql.unsafe 执行查询
-        let result;
-        if (params && params.length > 0) {
-            result = await this.sql.unsafe(sqlStr, params);
-        } else {
-            result = await this.sql.unsafe(sqlStr);
-        }
-
-        // 计算执行时间
-        const duration = Date.now() - startTime;
-
-        // 慢查询警告（超过 1000ms）
-        if (duration > 1000) {
-            const sqlPreview = sqlStr.length > 100 ? sqlStr.substring(0, 100) + '...' : sqlStr;
-            console.warn(`🐌 检测到慢查询 (${duration}ms): ${sqlPreview}`);
-        }
-
-        return result;
-    }
-
-    /**
-     * 查询单条数据
-     */
-    async getDetail<T = any>(options: QueryOptions): Promise<T | null> {
-        const { table, fields = ['*'], where, includeDeleted = false, customState } = options;
-
-        const builder = new SqlBuilder().select(fields).from(table).where(this.addDefaultStateFilter(where, includeDeleted, customState)).limit(1);
-
-        const { sql, params } = builder.toSelectSql();
-        const result = await this.executeWithConn(sql, params);
-
-        return result?.[0] || null;
-    }
-
-    /**
-     * 查询列表（带分页）
-     */
-    async getList<T = any>(options: QueryOptions): Promise<ListResult<T>> {
-        const { table, fields = ['*'], where, orderBy = [], page = 1, limit = 10, includeDeleted = false, customState } = options;
-
-        // P1: 添加参数上限校验
-        if (page < 1 || page > 10000) {
-            throw new Error('页码必须在 1 到 10000 之间');
-        }
-        if (limit < 1 || limit > 1000) {
-            throw new Error('每页数量必须在 1 到 1000 之间');
-        }
-
-        // 构建查询
-        const whereFiltered = this.addDefaultStateFilter(where, includeDeleted, customState);
-
-        // 查询总数
-        const countBuilder = new SqlBuilder().select(['COUNT(*) as total']).from(table).where(whereFiltered);
-
-        const { sql: countSql, params: countParams } = countBuilder.toSelectSql();
-        const countResult = await this.executeWithConn(countSql, countParams);
-        const total = countResult?.[0]?.total || 0;
-
-        // P1: 如果总数为 0，直接返回，不执行第二次查询
-        if (total === 0) {
-            return {
-                list: [],
-                total: 0,
-                page,
-                limit,
-                pages: 0
-            };
-        }
-
-        // 查询数据
-        const offset = (page - 1) * limit;
-        const dataBuilder = new SqlBuilder().select(fields).from(table).where(whereFiltered).limit(limit).offset(offset);
-
-        // P1: 只有用户明确指定了 orderBy 才添加排序
-        if (orderBy && orderBy.length > 0) {
-            dataBuilder.orderBy(orderBy);
-        }
-
-        const { sql: dataSql, params: dataParams } = dataBuilder.toSelectSql();
-        const list = (await this.executeWithConn(dataSql, dataParams)) || [];
-
-        return {
-            list,
-            total,
-            page,
-            limit,
-            pages: Math.ceil(total / limit)
-        };
-    }
-
-    /**
-     * 查询所有数据（不分页，有上限保护）
-     * ⚠️ 警告：此方法会查询大量数据，建议使用 getList 分页查询
-     */
-    async getAll<T = any>(options: Omit<QueryOptions, 'page' | 'limit'>): Promise<T[]> {
-        const { table, fields = ['*'], where, orderBy, includeDeleted = false, customState } = options;
-
-        // 添加硬性上限保护，防止内存溢出
-        const MAX_LIMIT = 10000;
-        const WARNING_LIMIT = 1000;
-
-        const builder = new SqlBuilder().select(fields).from(table).where(this.addDefaultStateFilter(where, includeDeleted, customState)).limit(MAX_LIMIT); // 强制添加上限
-
-        if (orderBy) {
-            builder.orderBy(orderBy);
-        }
-
-        const { sql, params } = builder.toSelectSql();
-        const result = (await this.executeWithConn(sql, params)) || [];
-
-        // 警告日志：返回数据超过警告阈值
-        if (result.length >= WARNING_LIMIT) {
-            console.warn(`⚠️ getAll 从表 \`${table}\` 返回了 ${result.length} 行数据，建议使用 getList 分页查询以获得更好的性能。`);
-        }
-
-        // 如果达到上限，额外警告
-        if (result.length >= MAX_LIMIT) {
-            console.warn(`🚨 getAll 达到了最大限制 (${MAX_LIMIT})，可能还有更多数据。请使用 getList 分页查询。`);
-        }
-
-        return result;
-    }
-
-    /**
-     * 插入数据（自动生成 ID、时间戳、state）
-     */
-    async insData(options: InsertOptions): Promise<number> {
-        const { table, data } = options;
-
-        // 处理数据（自动添加必要字段）
-        const processed = await this.processDataForInsert(data);
-
-        // 构建 SQL
-        const builder = new SqlBuilder();
-        const { sql, params } = builder.toInsertSql(table, processed);
-
-        // 执行
-        const result = await this.executeWithConn(sql, params);
-        return processed.id || result?.lastInsertRowid || 0;
-    }
-
-    /**
-     * 批量插入数据（真正的批量操作）
-     * 使用 INSERT INTO ... VALUES (...), (...), (...) 语法
-     * 自动生成系统字段并包装在事务中
-     */
-    async insDataBatch(table: string, dataList: Record<string, any>[]): Promise<number[]> {
-        // 空数组直接返回
-        if (dataList.length === 0) {
-            return [];
-        }
-
-        // 限制批量大小
-        const MAX_BATCH_SIZE = 1000;
-        if (dataList.length > MAX_BATCH_SIZE) {
-            throw new Error(`批量插入数量 ${dataList.length} 超过最大限制 ${MAX_BATCH_SIZE}，请分批插入。`);
-        }
-
-        // 批量生成 ID（一次性从 Redis 获取 N 个 ID）
-        const ids = await this.befly.redis.genTimeIDBatch(dataList.length);
-        const now = Date.now();
-
-        // 处理所有数据（自动添加系统字段）
-        const processedList = dataList.map((data, index) => {
-            // 移除系统字段（防止用户尝试覆盖）
-            const { id, created_at, updated_at, deleted_at, state, ...userData } = data;
-
-            // 强制生成系统字段（不可被用户覆盖）
-            return {
-                ...userData,
-                id: ids[index],
-                created_at: now,
-                updated_at: now,
-                state: 1
-            };
-        });
-
-        // 构建批量插入 SQL
-        const builder = new SqlBuilder();
-        const { sql, params } = builder.toInsertSql(table, processedList);
-
-        // 在事务中执行批量插入
-        try {
-            await this.executeWithConn(sql, params);
-            return ids;
-        } catch (error: any) {
-            // 批量插入失败，记录错误
-            console.error(`表 \`${table}\` 批量插入失败:`, error.message);
-            throw error;
-        }
-    }
-
-    /**
-     * 更新数据（强制更新时间戳，系统字段不可修改）
-     */
-    async updData(options: UpdateOptions): Promise<number> {
-        const { table, data, where, includeDeleted = false } = options;
-
-        // 移除系统字段（防止用户尝试修改）
-        const { id, created_at, updated_at, deleted_at, state, ...userData } = data;
-
-        // 强制更新时间戳（不可被用户覆盖）
-        const processed: Record<string, any> = {
-            ...userData,
-            updated_at: Date.now()
-        };
-
-        // 构建 SQL
-        const whereFiltered = this.addDefaultStateFilter(where, includeDeleted);
-        const builder = new SqlBuilder().where(whereFiltered);
-        const { sql, params } = builder.toUpdateSql(table, processed);
-
-        // 执行
-        const result = await this.executeWithConn(sql, params);
-        return result?.changes || 0;
-    }
-
-    /**
-     * 删除数据（软删除会记录删除时间）
-     */
-    async delData(options: DeleteOptions): Promise<number> {
-        const { table, where, hard = false } = options;
-
-        if (hard) {
-            // 物理删除
-            const builder = new SqlBuilder().where(where);
-            const { sql, params } = builder.toDeleteSql(table);
-
-            const result = await this.executeWithConn(sql, params);
-            return result?.changes || 0;
-        } else {
-            // 软删除（设置 state=0 并记录删除时间）
-            const now = Date.now();
-            const data: Record<string, any> = {
-                state: 0,
-                updated_at: now,
-                deleted_at: now // 记录删除时间
-            };
-
-            return await this.updData({
-                table,
-                data,
-                where,
-                includeDeleted: true // 软删除时允许操作已删除数据
-            });
-        }
-    }
-
-    /**
-     * 执行事务
-     */
-    async trans<T = any>(callback: TransactionCallback<T>): Promise<T> {
-        if (this.isTransaction) {
-            // 已经在事务中，直接执行回调
-            return await callback(this);
-        }
-
-        // 开启新事务
-        const conn = await this.befly.db.transaction();
-
-        try {
-            const trans = new SqlHelper(this.befly, conn);
-            const result = await callback(trans);
-            await conn.query('COMMIT');
-            return result;
-        } catch (error) {
-            await conn.query('ROLLBACK');
-            throw error;
-        }
-    }
-
-    /**
-     * 执行原始 SQL
-     */
-    async query(sql: string, params?: any[]): Promise<any> {
-        return await this.executeWithConn(sql, params);
-    }
-
-    /**
-     * 检查数据是否存在（优化性能）
-     */
-    async exists(options: Omit<QueryOptions, 'fields' | 'orderBy' | 'page' | 'limit'>): Promise<boolean> {
-        const { table, where, includeDeleted = false, customState } = options;
-
-        // 使用 COUNT(1) 性能更好
-        const builder = new SqlBuilder().select(['COUNT(1) as cnt']).from(table).where(this.addDefaultStateFilter(where, includeDeleted, customState)).limit(1);
-
-        const { sql, params } = builder.toSelectSql();
-        const result = await this.executeWithConn(sql, params);
-
-        return (result?.[0]?.cnt || 0) > 0;
-    }
-
-    /**
-     * 查询单个字段值（带字段名验证）
-     */
-    async getFieldValue<T = any>(options: Omit<QueryOptions, 'fields'> & { field: string }): Promise<T | null> {
-        const { field, ...queryOptions } = options;
-
-        // 验证字段名格式（只允许字母、数字、下划线）
-        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
-            throw new Error(`无效的字段名: ${field}，只允许字母、数字和下划线。`);
-        }
-
-        const result = await this.getDetail({
-            ...queryOptions,
-            fields: [field]
-        });
-
-        return result ? result[field] : null;
-    }
-
-    /**
-     * 自增字段（安全实现，防止 SQL 注入）
-     */
-    async increment(table: string, field: string, where: WhereConditions, value: number = 1): Promise<number> {
-        // 验证表名格式（只允许字母、数字、下划线）
-        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) {
-            throw new Error(`无效的表名: ${table}`);
-        }
-
-        // 验证字段名格式（只允许字母、数字、下划线）
-        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
-            throw new Error(`无效的字段名: ${field}`);
-        }
-
-        // 验证 value 必须是数字
-        if (typeof value !== 'number' || isNaN(value)) {
-            throw new Error(`自增值必须是有效的数字`);
-        }
-
-        // 使用 SqlBuilder 构建安全的 WHERE 条件
-        const whereFiltered = this.addDefaultStateFilter(where, false);
-        const builder = new SqlBuilder().where(whereFiltered);
-        const { sql: selectSql, params: whereParams } = builder.toSelectSql();
-
-        // 提取 WHERE 子句（找到 WHERE 关键字后的部分）
-        const whereIndex = selectSql.indexOf('WHERE');
-        const whereClause = whereIndex > -1 ? selectSql.substring(whereIndex + 6).trim() : '1=1';
-
-        // 构建安全的 UPDATE SQL（表名和字段名使用反引号转义）
-        const sql = `UPDATE \`${table}\` SET \`${field}\` = \`${field}\` + ? WHERE ${whereClause}`;
-
-        const result = await this.executeWithConn(sql, [value, ...whereParams]);
-        return result?.changes || 0;
-    }
-
-    /**
-     * 自减字段
-     */
-    async decrement(table: string, field: string, where: WhereConditions, value: number = 1): Promise<number> {
-        return await this.increment(table, field, where, -value);
-    }
-}