befly 2.3.2 → 3.0.0

package/types/context.ts

@@ -0,0 +1,167 @@
+/**
+ * 请求上下文类
+ * 提供统一的请求数据访问接口和类型安全
+ */
+
+/**
+ * 标准请求上下文类
+ */
+export class RequestContext {
+    /** 原始请求对象 */
+    public readonly request: Request;
+
+    /** 请求开始时间（毫秒） */
+    public readonly startTime: number;
+
+    /** 请求体参数 (GET/POST 解析后的数据) */
+    public body: Record<string, any> = {};
+
+    /** 用户信息 (认证后填充) */
+    public user: Record<string, any> = {};
+
+    /** 自定义状态 (用于在中间件间传递数据) */
+    public state: Record<string, any> = {};
+
+    /** 响应数据 (由 handler 设置) */
+    public response?: any;
+
+    constructor(req: Request) {
+        this.request = req;
+        this.startTime = Date.now();
+    }
+
+    // ========== 便捷访问器 ==========
+
+    /**
+     * 获取请求方法
+     */
+    get method(): string {
+        return this.request.method;
+    }
+
+    /**
+     * 获取请求 URL
+     */
+    get url(): string {
+        return this.request.url;
+    }
+
+    /**
+     * 获取请求头对象
+     */
+    get headers(): Headers {
+        return this.request.headers;
+    }
+
+    /**
+     * 获取客户端 IP 地址
+     */
+    get ip(): string | null {
+        return this.request.headers.get('x-forwarded-for') || this.request.headers.get('x-real-ip') || this.request.headers.get('cf-connecting-ip') || null;
+    }
+
+    /**
+     * 获取 User-Agent
+     */
+    get userAgent(): string | null {
+        return this.request.headers.get('user-agent');
+    }
+
+    /**
+     * 获取 Content-Type
+     */
+    get contentType(): string | null {
+        return this.request.headers.get('content-type');
+    }
+
+    // ========== 工具方法 ==========
+
+    /**
+     * 获取请求头
+     * @param name - 请求头名称
+     */
+    header(name: string): string | null {
+        return this.request.headers.get(name);
+    }
+
+    /**
+     * 获取参数值
+     * @param key - 参数键名
+     */
+    get(key: string): any {
+        return this.body[key];
+    }
+
+    /**
+     * 设置参数值
+     * @param key - 参数键名
+     * @param value - 参数值
+     */
+    set(key: string, value: any): void {
+        this.body[key] = value;
+    }
+
+    /**
+     * 检查参数是否存在
+     * @param key - 参数键名
+     */
+    has(key: string): boolean {
+        return key in this.params;
+    }
+
+    /**
+     * 获取所有参数
+     */
+    all(): Record<string, any> {
+        return { ...this.params };
+    }
+
+    /**
+     * 计算请求耗时（毫秒）
+     */
+    getElapsedTime(): number {
+        return Date.now() - this.startTime;
+    }
+
+    /**
+     * 获取格式化的请求信息（用于日志）
+     */
+    getRequestInfo(): Record<string, any> {
+        return {
+            method: this.method,
+            url: this.url,
+            ip: this.ip,
+            userAgent: this.userAgent,
+            elapsedTime: this.getElapsedTime()
+        };
+    }
+
+    /**
+     * 设置响应数据
+     * @param data - 响应数据
+     */
+    setResponse(data: any): void {
+        this.response = data;
+    }
+
+    /**
+     * 判断用户是否已登录
+     */
+    isAuthenticated(): boolean {
+        return !!this.user.id;
+    }
+
+    /**
+     * 获取用户 ID
+     */
+    getUserId(): number | null {
+        return this.user.id || null;
+    }
+
+    /**
+     * 获取用户角色
+     */
+    getUserRole(): string | null {
+        return this.user.role || this.user.role_type || null;
+    }
+}

package/types/crypto.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 加密相关类型定义
+ */
+
+/**
+ * 编码类型
+ */
+export type EncodingType = 'hex' | 'base64' | 'base64url';
+
+/**
+ * 哈希算法类型
+ */
+export type HashAlgorithm = 'md5' | 'sha1' | 'sha256' | 'sha512' | 'sha384' | 'sha224';
+
+/**
+ * 密码哈希选项
+ */
+export interface PasswordHashOptions {
+    algorithm?: 'argon2' | 'bcrypt';
+    memoryCost?: number;
+    timeCost?: number;
+    [key: string]: any;
+}

package/types/database.d.ts

@@ -0,0 +1,278 @@
+/**
+ * 数据库相关类型定义
+ */
+
+import type { SqlValue, WhereConditions } from './common';
+
+// 重新导出 WhereOperator 和 WhereConditions，供其他模块使用
+export type { WhereOperator, WhereConditions } from './index';
+
+/**
+ * 查询选项
+ */
+export interface QueryOptions {
+    /** 表名 */
+    table: string;
+    /** 查询字段 */
+    fields?: string[];
+    /** WHERE 条件 */
+    where?: WhereConditions;
+    /** 排序 */
+    orderBy?: string;
+    /** 页码（从 1 开始） */
+    page?: number;
+    /** 每页数量 */
+    limit?: number;
+    /** 是否包含已删除数据 */
+    includeDeleted?: boolean;
+    /** 自定义 state 条件 */
+    customState?: WhereConditions;
+}
+
+/**
+ * 插入选项
+ */
+export interface InsertOptions {
+    /** 表名 */
+    table: string;
+    /** 插入数据（ID、时间戳、state 会自动生成） */
+    data: Record<string, any>;
+}
+
+/**
+ * 更新选项
+ */
+export interface UpdateOptions {
+    /** 表名 */
+    table: string;
+    /** 更新数据（updated_at 会自动更新） */
+    data: Record<string, any>;
+    /** WHERE 条件 */
+    where: WhereConditions;
+    /** 是否包含已删除数据 */
+    includeDeleted?: boolean;
+}
+
+/**
+ * 删除选项
+ */
+export interface DeleteOptions {
+    /** 表名 */
+    table: string;
+    /** WHERE 条件 */
+    where: WhereConditions;
+    /** 是否物理删除（false=软删除，true=物理删除） */
+    hard?: boolean;
+}
+
+/**
+ * 列表查询结果
+ */
+export interface ListResult<T = any> {
+    /** 数据列表 */
+    list: T[];
+    /** 总条数 */
+    total: number;
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    limit: number;
+    /** 总页数 */
+    pages: number;
+}
+
+/**
+ * 事务回调函数
+ */
+export type TransactionCallback<T = any> = (trans: SqlHelper) => Promise<T>;
+
+/**
+ * SQL 查询结果
+ */
+export interface SqlQuery {
+    sql: string;
+    params: SqlValue[];
+}
+
+/**
+ * 插入数据类型
+ */
+export type InsertData = Record<string, SqlValue> | Record<string, SqlValue>[];
+
+/**
+ * 更新数据类型
+ */
+export type UpdateData = Record<string, SqlValue>;
+
+/**
+ * 数据库类型
+ */
+export type DbType = 'mysql' | 'postgresql' | 'sqlite';
+
+/**
+ * 列信息
+ */
+export interface ColumnInfo {
+    /** 列名 */
+    name: string;
+    /** 数据类型 */
+    type: string;
+    /** 是否可空 */
+    nullable: boolean;
+    /** 默认值 */
+    default: any;
+    /** 注释 */
+    comment: string;
+    /** 长度 */
+    length?: number;
+}
+
+/**
+ * 索引信息
+ */
+export interface IndexInfo {
+    /** 索引名 */
+    name: string;
+    /** 列名 */
+    column: string;
+    /** 是否唯一 */
+    unique: boolean;
+}
+
+/**
+ * 同步统计
+ */
+export interface SyncStats {
+    /** 创建的表数 */
+    created: number;
+    /** 修改的表数 */
+    modified: number;
+    /** 创建的索引数 */
+    indexesCreated: number;
+    /** 删除的索引数 */
+    indexesDropped: number;
+}
+
+/**
+ * SqlHelper 接口（前向声明）
+ */
+export interface SqlHelper {
+    getDetail<T = any>(options: QueryOptions): Promise<T | null>;
+    getList<T = any>(options: QueryOptions): Promise<ListResult<T>>;
+    getAll<T = any>(options: Omit<QueryOptions, 'page' | 'limit'>): Promise<T[]>;
+    insData(options: InsertOptions): Promise<number>;
+    updData(options: UpdateOptions): Promise<number>;
+    delData(options: DeleteOptions): Promise<number>;
+    trans<T = any>(callback: TransactionCallback<T>): Promise<T>;
+    query(sql: string, params?: any[]): Promise<any>;
+}
+
+/**
+ * SQL 客户端选项
+ */
+export interface SqlClientOptions {
+    /** 最大连接数 */
+    max?: number;
+    /** 是否使用 BigInt */
+    bigint?: boolean;
+    /** 其他自定义选项 */
+    [key: string]: any;
+}
+
+// ========== 数据库同步相关类型 ==========
+
+/**
+ * 列信息接口（用于数据库同步）
+ */
+export interface ColumnInfo {
+    /** 字段类型（如 string, number 等） */
+    type: string;
+    /** 数据库列类型（如 VARCHAR, INT 等） */
+    columnType: string;
+    /** 字段长度 */
+    length: number | null;
+    /** 是否可空 */
+    nullable: boolean;
+    /** 默认值 */
+    defaultValue: any;
+    /** 字段注释 */
+    comment: string | null;
+}
+
+/**
+ * 索引信息接口
+ */
+export interface IndexInfo {
+    /** 索引名称到字段数组的映射 */
+    [indexName: string]: string[];
+}
+
+/**
+ * 字段变更类型
+ */
+export interface FieldChange {
+    /** 变更类型 */
+    type: 'length' | 'comment' | 'datatype' | 'default';
+    /** 当前值 */
+    current: any;
+    /** 新值 */
+    new: any;
+}
+
+/**
+ * 索引操作接口
+ */
+export interface IndexAction {
+    /** 操作类型：create（创建）或 drop（删除） */
+    action: 'create' | 'drop';
+    /** 索引名称 */
+    indexName: string;
+    /** 字段名称 */
+    fieldName: string;
+}
+
+/**
+ * 表同步计划接口
+ */
+export interface TablePlan {
+    /** 是否有变更 */
+    changed: boolean;
+    /** 添加字段的 SQL 子句 */
+    addClauses: string[];
+    /** 修改字段的 SQL 子句 */
+    modifyClauses: string[];
+    /** 默认值变更的 SQL 子句 */
+    defaultClauses: string[];
+    /** 索引操作列表 */
+    indexActions: IndexAction[];
+    /** 注释变更的 SQL 子句（可选） */
+    commentActions?: string[];
+}
+
+/**
+ * 全局统计计数接口
+ */
+export interface GlobalCount {
+    /** 已处理表数量 */
+    processedTables: number;
+    /** 创建表数量 */
+    createdTables: number;
+    /** 修改表数量 */
+    modifiedTables: number;
+    /** 新增字段数量 */
+    addFields: number;
+    /** 类型变更数量 */
+    typeChanges: number;
+    /** 最大值变更数量 */
+    maxChanges: number;
+    /** 最小值变更数量 */
+    minChanges: number;
+    /** 默认值变更数量 */
+    defaultChanges: number;
+    /** 名称变更数量 */
+    nameChanges: number;
+    /** 索引创建数量 */
+    indexCreate: number;
+    /** 索引删除数量 */
+    indexDrop: number;
+}

package/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Befly 类型定义入口文件
+ * 统一导出所有类型定义
+ */
+
+// 通用类型
+export * from './common.js';
+
+// 插件系统
+export * from './plugin.js';
+
+// API 系统
+export * from './api.js';
+
+// Befly 核心
+export * from './befly.js';