befly 2.3.3 → 3.0.0

package/types/redis.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Redis 相关类型定义
+ */
+
+import { RedisClient as BunRedisClient } from 'bun';
+
+/**
+ * Redis 客户端类型
+ */
+export type RedisClient = BunRedisClient;
+
+/**
+ * Redis 键前缀
+ */
+export type RedisKeyPrefix = string;
+
+/**
+ * Redis TTL（秒）
+ */
+export type RedisTTL = number | null;
+
+/**
+ * Redis 助手接口
+ */
+export interface RedisHelper {
+    /** 设置对象到 Redis */
+    setObject<T = any>(key: string, obj: T, ttl?: RedisTTL): Promise<string | null>;
+    /** 从 Redis 获取对象 */
+    getObject<T = any>(key: string): Promise<T | null>;
+    /** 从 Redis 删除对象 */
+    delObject(key: string): Promise<void>;
+    /** 生成基于时间的唯一 ID */
+    genTimeID(): Promise<number>;
+    /** 设置字符串值 */
+    setString(key: string, value: string, ttl?: RedisTTL): Promise<string | null>;
+    /** 获取字符串值 */
+    getString(key: string): Promise<string | null>;
+    /** 检查键是否存在 */
+    exists(key: string): Promise<number>;
+    /** 设置过期时间 */
+    expire(key: string, seconds: number): Promise<number>;
+    /** 获取剩余过期时间 */
+    ttl(key: string): Promise<number>;
+}

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/validator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 验证器相关类型定义
+ */
+
+/**
+ * 字段验证错误信息
+ */
+export type ValidationError = string | null;
+
+/**
+ * 字段类型
+ */
+export type FieldType = 'string' | 'number' | 'text' | 'array';
+
+/**
+ * 验证结果
+ */
+export interface ValidationResult {
+    /** 验证状态码：0=成功，1=失败 */
+    code: 0 | 1;
+    /** 字段验证结果 */
+    fields: Record<string, any>;
+}
+
+/**
+ * 字段规则
+ */
+export interface FieldRule {
+    /** 字段名 */
+    name: string;
+    /** 字段类型 */
+    type: FieldType;
+    /** 最小值/长度 */
+    min: number | null;
+    /** 最大值/长度 */
+    max: number | null;
+    /** 默认值 */
+    default: any;
+    /** 是否索引 */
+    index: 0 | 1;
+    /** 正则约束 */
+    regex: string | null;
+}
+
+export type FieldType = 'string' | 'number' | 'text' | 'array';

package/utils/addonHelper.ts

@@ -0,0 +1,60 @@
+/**
+ * Addon 辅助工具函数
+ * 提供 addon 扫描、路径获取等功能
+ */
+
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { getProjectRoot } from '../system.js';
+
+/**
+ * 获取 addons 目录路径
+ */
+export const getAddonsDir = (): string => {
+    return join(getProjectRoot(), 'addons');
+};
+
+/**
+ * 扫描所有可用的 addon
+ * @returns addon 名称数组（过滤掉 _ 开头的目录）
+ */
+export const scanAddons = (): string[] => {
+    const addonsDir = getAddonsDir();
+    if (!fs.existsSync(addonsDir)) {
+        return [];
+    }
+
+    try {
+        return fs
+            .readdirSync(addonsDir)
+            .filter((name) => {
+                const fullPath = join(addonsDir, name);
+                const stat = fs.statSync(fullPath);
+                const isDir = stat.isDirectory();
+                const notSkip = !name.startsWith('_'); // 跳过 _ 开头的目录
+                return isDir && notSkip;
+            })
+            .sort(); // 按字母顺序排序
+    } catch (error) {
+        return [];
+    }
+};
+
+/**
+ * 获取 addon 的指定子目录路径
+ * @param addonName - addon 名称
+ * @param subDir - 子目录名称（apis, checks, plugins, tables, types, config）
+ */
+export const getAddonDir = (addonName: string, subDir: string): string => {
+    return join(getAddonsDir(), addonName, subDir);
+};
+
+/**
+ * 检查 addon 是否存在指定子目录
+ * @param addonName - addon 名称
+ * @param subDir - 子目录名称
+ */
+export const hasAddonDir = (addonName: string, subDir: string): boolean => {
+    const dir = getAddonDir(addonName, subDir);
+    return fs.existsSync(dir) && fs.statSync(dir).isDirectory();
+};

package/utils/api.ts

@@ -0,0 +1,23 @@
+/**
+ * API 工具类 - TypeScript 版本
+ * 提供 API 路由定义的便捷方法
+ */
+
+import type { ApiRoute, ApiOptions } from '../types/api.js';
+
+/**
+ * 定义 API 路由（主函数）
+ * @param name - 接口名称
+ * @param options - 接口配置选项
+ * @returns API 路由定义
+ */
+export function Api(name: string, options: ApiOptions): ApiRoute {
+    return {
+        method: options.method || 'POST',
+        name: name,
+        auth: options.auth ?? false,
+        fields: options.fields ?? {},
+        required: options.required ?? [],
+        handler: async (befly, ctx, req) => await options.handler(befly, ctx, req)
+    };
+}

package/utils/{colors.js → colors.ts}

@@ -1,19 +1,68 @@
-const p = process || {},
-    argv = p.argv || [],
-    env = p.env || {};
+/**
+ * 终端颜色工具 - TypeScript 版本
+ */
+
+/**
+ * 格式化函数类型
+ */
+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;
+    yellow: Formatter;
+    blue: Formatter;
+    magenta: Formatter;
+    cyan: Formatter;
+    white: Formatter;
+    gray: Formatter;
+    bgBlack: Formatter;
+    bgRed: Formatter;
+    bgGreen: Formatter;
+    bgYellow: Formatter;
+    bgBlue: Formatter;
+    bgMagenta: Formatter;
+    bgCyan: Formatter;
+    bgWhite: Formatter;
+}
+
+interface Process {
+    argv?: string[];
+    env?: Record<string, string | undefined>;
+    platform?: string;
+    stdout?: { isTTY?: boolean };
+}
+
+const p: Process = (typeof process !== 'undefined' ? process : {}) as Process;
+const argv = p.argv || [];
+const env = p.env || {};
+
 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 formatter =
-    (open, close, replace = open) =>
-    (input) => {
-        let string = '' + input,
-            index = string.indexOf(close, open.length);
+    (open: string, close: string, replace: string = open): Formatter =>
+    (input: string | number): string => {
+        const string = '' + input;
+        const index = string.indexOf(close, open.length);
         return ~index ? open + replaceClose(string, close, replace, index) + close : open + string + close;
     };
 
-const replaceClose = (string, close, replace, index) => {
-    let result = '',
-        cursor = 0;
+const replaceClose = (string: string, close: string, replace: string, index: number): string => {
+    let result = '';
+    let cursor = 0;
     do {
         result += string.substring(cursor, index) + replace;
         cursor = index + close.length;
@@ -22,9 +71,10 @@ const replaceClose = (string, close, replace, index) => {
     return result + string.substring(cursor);
 };
 
-const createColors = (enabled = isColorSupported) => {
-    let f = enabled ? formatter : () => String;
-    return {
+const createColors = (enabled: boolean = isColorSupported): ColorsInterface => {
+    const f = enabled ? formatter : (): Formatter => String as Formatter;
+
+    const baseColors = {
         isColorSupported: enabled,
         reset: f('\x1b[0m', '\x1b[0m'),
         bold: f('\x1b[1m', '\x1b[22m', '\x1b[22m\x1b[1m'),
@@ -70,14 +120,22 @@ const createColors = (enabled = isColorSupported) => {
         bgBlueBright: f('\x1b[104m', '\x1b[49m'),
         bgMagentaBright: f('\x1b[105m', '\x1b[49m'),
         bgCyanBright: f('\x1b[106m', '\x1b[49m'),
-        bgWhiteBright: f('\x1b[107m', '\x1b[49m')
+        bgWhiteBright: f('\x1b[107m', '\x1b[49m'),
+
+        info: '',
+        success: '',
+        warn: '',
+        error: ''
     };
-};
 
-const colors = createColors();
-colors.info = colors.blue('i');
-colors.success = colors.green('√');
-colors.warn = colors.yellow('‼');
-colors.error = colors.red('x');
+    // 添加图标
+    baseColors.info = baseColors.blue('i');
+    baseColors.success = baseColors.green('√');
+    baseColors.warn = baseColors.yellow('‼');
+    baseColors.error = baseColors.red('x');
+
+    return baseColors;
+};
 
-export { colors };
+export const colors = createColors();
+export { colors as Colors }; // 别名导出，保持向后兼容

package/utils/crypto.ts

@@ -0,0 +1,308 @@
+/**
+ * 加密工具类 - TypeScript 版本
+ * 提供各种哈希、HMAC、密码加密等功能
+ */
+
+import { createSign } from 'node:crypto';
+import type { EncodingType, HashAlgorithm, PasswordHashOptions } from '../types/crypto';
+
+/**
+ * 加密工具类
+ */
+export class Crypto2 {
+    /**
+     * MD5 哈希
+     * @param data - 要哈希的数据
+     * @param encoding - 输出编码
+     * @returns MD5 哈希值
+     */
+    static md5(data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('md5');
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * HMAC-MD5 签名
+     * @param key - 密钥
+     * @param data - 要签名的数据
+     * @param encoding - 输出编码
+     * @returns HMAC-MD5 签名
+     */
+    static hmacMd5(key: string | Uint8Array, data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('md5', key);
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * SHA-1 哈希
+     * @param data - 要哈希的数据
+     * @param encoding - 输出编码
+     * @returns SHA-1 哈希值
+     */
+    static sha1(data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('sha1');
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * HMAC-SHA1 签名
+     * @param key - 密钥
+     * @param data - 要签名的数据
+     * @param encoding - 输出编码
+     * @returns HMAC-SHA1 签名
+     */
+    static hmacSha1(key: string | Uint8Array, data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('sha1', key);
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * SHA-256 哈希
+     * @param data - 要哈希的数据
+     * @param encoding - 输出编码
+     * @returns SHA-256 哈希值
+     */
+    static sha256(data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('sha256');
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * RSA-SHA256 签名
+     * @param data - 要签名的数据
+     * @param privateKey - 私钥
+     * @param encoding - 输出编码
+     * @returns RSA-SHA256 签名
+     */
+    static rsaSha256(data: string, privateKey: string | Buffer, encoding: BufferEncoding = 'hex'): string {
+        const sign = createSign('RSA-SHA256');
+        sign.update(data);
+        const signature = sign.sign(privateKey, encoding);
+        return signature;
+    }
+
+    /**
+     * HMAC-SHA256 签名
+     * @param key - 密钥
+     * @param data - 要签名的数据
+     * @param encoding - 输出编码
+     * @returns HMAC-SHA256 签名
+     */
+    static hmacSha256(key: string | Uint8Array, data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('sha256', key);
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * SHA-512 哈希
+     * @param data - 要哈希的数据
+     * @param encoding - 输出编码
+     * @returns SHA-512 哈希值
+     */
+    static sha512(data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('sha512');
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * HMAC-SHA512 签名
+     * @param key - 密钥
+     * @param data - 要签名的数据
+     * @param encoding - 输出编码
+     * @returns HMAC-SHA512 签名
+     */
+    static hmacSha512(key: string | Uint8Array, data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher('sha512', key);
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * 通用哈希方法
+     * @param algorithm - 算法名称
+     * @param data - 要哈希的数据
+     * @param encoding - 输出编码
+     * @returns 哈希值
+     */
+    static hash(algorithm: HashAlgorithm, data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher(algorithm);
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * 通用 HMAC 方法
+     * @param algorithm - 算法名称
+     * @param key - 密钥
+     * @param data - 要签名的数据
+     * @param encoding - 输出编码
+     * @returns HMAC 签名
+     */
+    static hmac(algorithm: HashAlgorithm, key: string | Uint8Array, data: string | Uint8Array, encoding: EncodingType = 'hex'): string {
+        const hasher = new Bun.CryptoHasher(algorithm, key);
+        hasher.update(data);
+        return hasher.digest(encoding);
+    }
+
+    /**
+     * 文件哈希
+     * @param filePath - 文件路径
+     * @param algorithm - 算法名称
+     * @param encoding - 输出编码
+     * @returns 文件哈希值
+     */
+    static async hashFile(filePath: string, algorithm: HashAlgorithm = 'sha256', encoding: EncodingType = 'hex'): Promise<string> {
+        const file = Bun.file(filePath);
+        const hasher = new Bun.CryptoHasher(algorithm);
+
+        const stream = file.stream();
+        const reader = stream.getReader();
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                hasher.update(value);
+            }
+            return hasher.digest(encoding);
+        } finally {
+            reader.releaseLock();
+        }
+    }
+
+    /**
+     * 创建流式哈希器
+     * @param algorithm - 算法名称
+     * @param key - 可选的 HMAC 密钥
+     * @returns 流式哈希器实例
+     */
+    static createHasher(algorithm: HashAlgorithm, key: string | Uint8Array | null = null): StreamHasher {
+        return new StreamHasher(algorithm, key);
+    }
+
+    /**
+     * 密码哈希 (使用 Argon2)
+     * @param password - 密码
+     * @param options - 选项
+     * @returns 哈希后的密码
+     */
+    static async hashPassword(password: string, options: PasswordHashOptions = {}): Promise<string> {
+        // 设置默认算法为 bcrypt
+        const finalOptions = {
+            algorithm: 'bcrypt',
+            ...options
+        } as any;
+        return await Bun.password.hash(password, finalOptions);
+    }
+
+    /**
+     * 验证密码
+     * @param password - 原始密码
+     * @param hash - 哈希值
+     * @returns 验证结果
+     */
+    static async verifyPassword(password: string, hash: string): Promise<boolean> {
+        return await Bun.password.verify(password, hash);
+    }
+
+    /**
+     * Base64 编码
+     * @param data - 要编码的数据
+     * @returns Base64 编码的字符串
+     */
+    static base64Encode(data: string): string {
+        return Buffer.from(data, 'utf8').toString('base64');
+    }
+
+    /**
+     * Base64 解码
+     * @param data - Base64 编码的字符串
+     * @returns 解码后的字符串
+     */
+    static base64Decode(data: string): string {
+        return Buffer.from(data, 'base64').toString('utf8');
+    }
+
+    /**
+     * 生成随机十六进制字符串
+     * @param length - 字符串长度
+     * @returns 随机十六进制字符串
+     */
+    static randomString(length: number): string {
+        const bytes = Math.ceil(length / 2);
+        const randomBytes = crypto.getRandomValues(new Uint8Array(bytes));
+        let result = '';
+        for (let i = 0; i < randomBytes.length; i++) {
+            result += randomBytes[i].toString(16).padStart(2, '0');
+        }
+        return result.slice(0, length);
+    }
+
+    /**
+     * 快速哈希 (非密码学)
+     * @param data - 数据
+     * @param seed - 种子值
+     * @returns 64位哈希值
+     */
+    static fastHash(data: string | Uint8Array, seed: number = 0): number {
+        return Bun.hash(data, seed);
+    }
+}
+
+/**
+ * 流式哈希器类
+ */
+export class StreamHasher {
+    private hasher: any;
+    private finalized: boolean = false;
+
+    constructor(algorithm: HashAlgorithm, key: string | Uint8Array | null = null) {
+        this.hasher = new Bun.CryptoHasher(algorithm, key);
+    }
+
+    /**
+     * 更新数据
+     * @param data - 数据
+     * @returns 支持链式调用
+     */
+    update(data: string | Uint8Array): this {
+        if (this.finalized) {
+            throw new Error('哈希器已经完成，不能再更新数据');
+        }
+        this.hasher.update(data);
+        return this;
+    }
+
+    /**
+     * 生成最终哈希值
+     * @param encoding - 输出编码
+     * @returns 哈希值
+     */
+    digest(encoding: EncodingType = 'hex'): string {
+        if (this.finalized) {
+            throw new Error('哈希器已经完成');
+        }
+        this.finalized = true;
+        return this.hasher.digest(encoding);
+    }
+
+    /**
+     * 复制哈希器
+     * @returns 新的哈希器实例
+     */
+    copy(): StreamHasher {
+        if (this.finalized) {
+            throw new Error('不能复制已完成的哈希器');
+        }
+        const newHasher = new StreamHasher('md5'); // 临时算法
+        newHasher.hasher = this.hasher.copy();
+        return newHasher;
+    }
+}