@fastify-core/base 1.0.7 → 1.0.8

package/dist/index.d.mts

@@ -1,18 +1,173 @@
 import * as Decimal from "decimal.js";
-import { Pool, PoolConnection } from "mysql2/promise";
-import { FastifyRequest } from "fastify";
+import { Pool, PoolConnection, RowDataPacket } from "mysql2/promise";
+import { FastifyRequest, Session } from "fastify";
 import { SessionStore } from "@fastify/session";
+//#region src/Sql.d.ts
+/**
+ * Các kiểu và hàm dùng để xây dựng SQL từ định danh.
+ *
+ * Identifier động luôn được escape bằng backtick. Riêng SELECT và điều kiện
+ * JOIN được giới hạn ở column reference đơn giản, không nhận SQL thô.
+ */
+type SqlSelectField = string | {
+  column: string;
+  alias?: string;
+};
+type SqlSelectInput = string | readonly SqlSelectField[];
+type SqlJoinOperator = "=" | "<>" | "!=" | "<=" | ">=" | "<" | ">";
+type SqlJoinCondition = string | {
+  left: string;
+  right: string;
+  operator?: SqlJoinOperator;
+};
+/**
+ * Escape identifier đơn theo chuẩn MySQL bằng cách nhân đôi backtick bên trong.
+ * Từ chối tên rỗng, chứa NUL hoặc vượt giới hạn của MySQL.
+ */
+declare function escapeIdentifier(name: string): string;
+/**
+ * Escape từng phần của một đường dẫn, ví dụ `users.id` thành
+ * `` `users`.`id` ``. Giá trị chỉ được dùng làm identifier, không phải SQL.
+ */
+declare function escapeQualifiedName(path: string): string;
+/** Escape một column reference hợp lệ dùng cho SELECT hoặc JOIN. */
+declare function escapeColumnReference(reference: string): string;
+/**
+ * Chuẩn hóa và kiểm tra tên JOIN table để giữ nguyên alias được truyền vào.
+ *
+ * - Tên đơn được escape thành backtick.
+ * - Tên có alias được ghi thành `` `table` `alias` ``; alias vẫn được escape.
+ *
+ * @param tableAndAlias Chuỗi `table` hoặc `table AS alias`
+ * @throws {Error} `invalid_join_table` khi thiếu/sai định dạng hoặc alias
+ */
+declare function buildJoinTable(tableAndAlias: string): string;
+/** Chuẩn hóa và kiểm tra chiều ORDER BY. */
+declare function assertOrderDirection(direction: string): "ASC" | "DESC";
+/** Chuẩn hóa loại JOIN; giá trị thiếu mặc định thành LEFT JOIN. */
+declare function assertJoinType(type?: string | null): string;
+/**
+ * Xây dựng danh sách cột của mệnh đề SELECT.
+ *
+ * Chấp nhận:
+ * - Chuỗi: `"id"`, `"users.id, roles.name"`.
+ * - Mảng chuỗi: `["id", { column: "users.name", alias: "userName" }]`.
+ * - `{ column, alias? }` để đặt tên cột trả về.
+ *
+ * Chỉ nhận tên cột hoặc column reference; aggregate, hàm, subquery và SQL
+ * thô đều bị từ chối bằng `invalid_column_reference`.
+ *
+ * @throws {Error} `invalid_select` khi danh sách rỗng
+ * @throws {Error} `invalid_column_reference` khi có tên cột không hợp lệ
+ *
+ * @example
+ * ```ts
+ * buildSelectList(["id", { column: "roles.name", alias: "roleName" }]);
+ * // `id`, `roles`.`name` AS `roleName`
+ * ```
+ */
+declare function buildSelectList(select: SqlSelectInput): string;
+/**
+ * Xây dựng điều kiện JOIN mà không nối SQL thô.
+ *
+ * Hỗ trợ `"users.id = roles.userId"` và `{ left, right, operator? }` với
+ * operator thuộc `=`, `<>`, `!=`, `<=`, `>=`, `<`, `>`. Subquery, function,
+ * comment, dấu `;` và biểu thức nhiều phép so sánh đều bị từ chối.
+ *
+ * @throws {Error} `invalid_join_condition` khi cú pháp không hợp lệ
+ */
+declare function buildJoinCondition(condition: SqlJoinCondition): string;
+//#endregion
 //#region src/BaseModel.d.ts
-interface IBaseModel<T = any> {
+/**
+ * Ràng buộc tối thiểu cho entity của model: bắt buộc có khoá chính `id`.
+ *
+ * Cố ý KHÔNG dùng `Record<string, unknown>` ở đây. Một `interface` khai báo
+ * kiểu thường (`interface UserItem { id: number; ... }`) không có implicit
+ * index signature nên sẽ không thoả `Record<string, unknown>`, dẫn đến lỗi
+ * `TS2344` cho đúng cách khai báo entity mà README hướng dẫn.
+ */
+type ModelEntity = {
+  id: number;
+};
+/** Dòng dữ liệu dạng generic cho các model chưa có kiểu entity cụ thể. */
+type ModelRow = Record<string, unknown> & ModelEntity;
+/** Giá trị được phép truyền trực tiếp cho placeholder (`?`) của mysql2. */
+type SqlParam = string | number | boolean | null | Date | Buffer | SqlParam[];
+/** Giá trị "rộng" mà bộ lọc động và các hàm CRUD chấp nhận. */
+type LooseValue = string | number | boolean | null | Date | Buffer | LooseValue[] | {
+  [key: string]: LooseValue;
+};
+type LooseRecord = Record<string, LooseValue>;
+/**
+ * Thu hẹp biến `unknown` trong `catch` về kiểu `Error` để đọc được `.message`.
+ *
+ * @param error Giá trị bắt được từ `catch` (có thể là bất kỳ kiểu nào)
+ * @returns Chính `error` nếu đã là `Error`, ngược lại một `Error` mới chứa `String(error)`
+ *
+ * @example
+ * ```ts
+ * try {
+ *   JSON.parse(raw);
+ * } catch (error) {
+ *   // Không cần tự kiểm tra `error instanceof Error` thủ công
+ *   console.error(toError(error).message);
+ *   // => "Unexpected token o in JSON at position 1"
+ * }
+ * ```
+ */
+declare function toError(error: unknown): Error;
+type FilterValue = unknown;
+/**
+ * Điều kiện lọc của `BaseModel`.
+ *
+ * `T` chỉ dùng để **gợi ý tên field hợp lệ** khi gõ; `Record<string, FilterValue>`
+ * vẫn cho phép mọi khoá vì filter là ngôn ngữ động (toán tử `$in`, `$or`, tên
+ * cột không nằm trong entity...). Vì vậy TypeScript **không** bắt được lỗi gõ
+ * typo trong tên field — hãy dùng `model.isFields([...])` để kiểm tra tên cột
+ * lấy từ người dùng.
+ *
+ * @template T Kiểu entity của model, dùng để gợi ý
+ */
+type Filter<T extends ModelEntity = ModelEntity> = Partial<Record<keyof T, FilterValue>> & Record<string, FilterValue>;
+/**
+ * Filter dạng "rộng" cho code nội bộ của thư viện.
+ *
+ * `keyof T` ở {@link Filter} chưa cụ thể hoá khi T là type parameter, nên không
+ * dùng được cho các thao tác nội bộ như gán `isDeleted` hay dựng `{ id }`.
+ */
+type AnyFilter = Record<string, FilterValue>;
+/** Kết quả của {@link BaseModel.saveResult}. */
+type SaveResult<T> = {
+  ok: true;
+  item: T;
+} | {
+  ok: false;
+  errors: string[];
+};
+type QueryRows = RowDataPacket[];
+/** Một tập hàng kết quả truy vấn. */
+type QueryResult = [QueryRows, unknown];
+/**
+ * Giá trị trả về thật của {@link BaseModel.query}, giống hệt `mysql2`: một tuple
+ * `[result, fields]`, nơi `result` là `OkPacket`, `ResultSetHeader` hoặc mảng hàng
+ * tuỳ loại câu lệnh.
+ *
+ * Phải dùng kiểu này cho chữ ký `query()`. Nếu khai báo `Promise<QueryResult>` thì
+ * `BaseModel` **không** gán được cho `IBaseModel`, khiến khai báo `modifieds` báo
+ * lỗi type ở phía người dùng.
+ */
+type RawQueryResult = [unknown, unknown];
+interface IBaseModel<T extends ModelEntity = ModelRow> {
   table: string;
   isDeleted: boolean;
   errors: string[];
   fieldName(key: string): string;
   save(item: Partial<T>, conn?: PoolConnection): Promise<T | false>;
-  findOne(filter: Record<string, any>): Promise<T | null>;
-  find(filter: Record<string, any>): Promise<T[]>;
-  query(sql: string, params?: any[], conn?: PoolConnection): any;
-  update(data: Record<string, any>, filter: Record<string, any>, conn?: PoolConnection): Promise<number>;
+  findOne(filter: Filter<T>): Promise<T | null>;
+  find(filter: Filter<T>): Promise<T[]>;
+  query(sql: string, params?: SqlParam[], conn?: PoolConnection): Promise<RawQueryResult>;
+  update(data: Partial<T> | Record<string, SqlParam | SqlParam[]>, filter: Filter<T>, conn?: PoolConnection): Promise<number>;
 }
 interface PaginationResult<T> {
   page: number;
@@ -22,191 +177,729 @@ interface PaginationResult<T> {
   items: T[];
 }
 interface JoinType {
+  /** Tên bảng liên kết — được escape tự động */
   table: string;
-  on: string;
-  type: string;
-  fields: string[];
+  /**
+   * Điều kiện nối bảng: `"users.id = profiles.user_id"` hoặc
+   * `{ left: "users.id", right: "profiles.user_id", operator: "=" }`.
+   * Chỉ hỗ trợ phép so sánh đơn giản giữa các column reference.
+   */
+  on: SqlJoinCondition;
+  /** Kiểu JOIN — phải thuộc whitelist (`LEFT JOIN`, `INNER JOIN`...), sai sẽ ném `invalid_join_type` */
+  type?: string | null;
+  /** Danh sách cột cần lấy — chỉ nhận tên cột, không nhận SQL thô */
+  fields?: readonly string[];
 }
 interface ModifiedType {
   [field: string]: {
-    smodel: IBaseModel<any>;
+    /** Model liên kết; dùng `AnyIBaseModel` để nhận được model khai báo entity bằng `interface`. */
+    smodel: AnyIBaseModel;
     tkey: string;
     skey: string;
     fmap: string;
   };
 }
 /**
- * Abstract base model class.
- * Provides common database operations such as
- * CRUD, query building, pagination and validation.
+ * Lớp model cơ sở (abstract).
+ *
+ * Cung cấp các thao tác database dùng chung như:
+ * CRUD, dựng câu truy vấn, phân trang và kiểm tra dữ liệu (validation).
  *
- * @template T Entity type, must contain `id`
+ * @template T Kiểu entity, bắt buộc phải có trường `id`
  */
-declare abstract class BaseModel<T extends Record<string, any> & {
-  id: number;
-}> {
+declare abstract class BaseModel<T extends ModelEntity = ModelRow> {
   abstract table: string;
   protected pool: Pool;
   isDeleted: boolean;
   errors: string[];
-  vdObject: any;
+  validate: Record<string, string> | undefined;
   modifieds: ModifiedType | undefined;
   /**
-   * Create model instance
-   * @param pool MySQL connection pool
+   * Cache danh sách cột theo bảng, phục vụ `isField`/`isFields`.
+   * Xoá bằng `clearSchemaCache()`.
+   */
+  private readonly schemaCache;
+  /**
+   * Khởi tạo instance của model.
+   *
+   * @param pool Connection pool MySQL dùng để truy vấn
+   *
+   * @example
+   * ```ts
+   * import mysql from 'mysql2/promise';
+   * import { UserModel } from './models/UserModel.js';
+   *
+   * const pool = mysql.createPool({ host: 'localhost', user: 'root', database: 'app_db' });
+   * const userModel = new UserModel(pool);
+   * ```
    */
   constructor(pool: Pool);
+  /**
+   * Lấy tên hiển thị của trường.
+   *
+   * Có thể ghi đè trong class con để ứng dụng tự dùng khi dựng thông báo lỗi.
+   * Lưu ý: `Validation` không còn gọi tới hàm này vì validator không phụ thuộc model.
+   *
+   * @param key Tên cột trong bảng
+   * @returns Tên hiển thị tương ứng
+   *
+   * @example
+   * ```ts
+   * // Lớp con ghi đè để trả về nhãn tiếng Việt dùng cho thông báo lỗi
+   * override fieldName(key: string) {
+   *   return { fullname: 'Họ và tên', email: 'Địa chỉ Email' }[key] ?? key;
+   * }
+   *
+   * userModel.fieldName('fullname'); // => "Họ và tên"
+   * userModel.fieldName('status');   // => "status" (không có trong map thì trả về chính key)
+   * ```
+   */
   fieldName(key: string): string;
+  /**
+   * Lấy danh sách các thông báo lỗi phát sinh trong quá trình thực thi của model.
+   * @returns Mảng các chuỗi thông báo lỗi
+   *
+   * @example
+   * ```ts
+   * const ok = await userModel.save({ email: 'khong-hop-le' }); // false do DB báo lỗi
+   * userModel.getErrors();
+   * // => ["ER_BAD_NULL_ERROR: Column 'fullname' cannot be null"]
+   * ```
+   */
   getErrors(): string[];
+  /**
+   * Lấy một kết nối đơn lẻ từ connection pool để chạy transaction.
+   * @returns Promise giải quyết kết nối PoolConnection
+   *
+   * @example
+   * ```ts
+   * const conn = await userModel.getConnection();
+   * try {
+   *   await conn.beginTransaction();
+   *   await userModel.update({ status: 1 }, { id: 7 }, conn);
+   *   await conn.commit();
+   * } catch (err) {
+   *   await conn.rollback();
+   *   throw err;
+   * } finally {
+   *   // Bắt buộc trả kết nối về pool
+   *   conn.release();
+   * }
+   * ```
+   */
   getConnection(): Promise<PoolConnection>;
   /**
-   * Validate data using Validation rules
+   * Kiểm tra dữ liệu theo bộ quy tắc của lớp `Validation`.
    *
-   * @param item Data to validate
-   * @param vdObject Validation rules
+   * `Validation` hoàn toàn thuần (không truy vấn database), nên việc kiểm tra
+   * trùng lặp phải tự thực hiện ở tầng nghiệp vụ trước khi gọi hàm này.
+   *
+   * @param item Dữ liệu cần kiểm tra
+   * @param validate Bộ quy tắc kiểm tra dạng `field -> rule1|rule2`
+   * @param lang Mã ngôn ngữ cho thông báo lỗi (mặc định `'vi'`)
+   * @throws {Error} Khi có ít nhất một rule không thỏa hoặc rule không tồn tại
+   *
+   * @example
+   * ```ts
+   * await userModel.runValidate(
+   *   { fullname: 'Nguyen Van A', email: 'a@example.com', age: 25 },
+   *   { email: 'required|email', age: 'required|integer|rangeNum(18,60)' }
+   * );
+   * // Không ném lỗi => dữ liệu hợp lệ
+   *
+   * // Trả thông báo lỗi bằng tiếng Anh
+   * await userModel.runValidate({ email: 'sai' }, { email: 'required|email' }, 'en');
+   * // throw: "Email is not in the correct format"
+   * ```
    */
-  validate(item: Partial<T>, vdObject?: Record<string, any>): Promise<void>;
+  runValidate(item: Partial<T>, validate?: Record<string, string>, lang?: string): Promise<void>;
   /**
-   * Execute SQL query using pool or provided connection
+   * Thực thi câu SQL thông qua connection pool hoặc connection được truyền vào.
+   *
+   * @param sql Câu SQL, mọi giá trị động đều phải dùng placeholder `?`
+   * @param params Danh sách tham số bind cho các placeholder
+   * @param conn Connection cụ thể (thường dùng khi chạy transaction)
+   * @returns Kết quả trả về nguyên bản của mysql2
+   *
+   * @example
+   * ```ts
+   * const [rows] = await userModel.query(
+   *   'SELECT id, email FROM users WHERE roleId = ? AND status = ?',
+   *   [2, 1]
+   * );
+   * ```
    */
-  query(sql: string, params?: any[], conn?: PoolConnection): Promise<[import("mysql2").QueryResult, import("mysql2").FieldPacket[]]>;
+  query(sql: string, params?: SqlParam[], conn?: PoolConnection): Promise<[import("mysql2").QueryResult, import("mysql2").FieldPacket[]]>;
   /**
-   * Synchronize mapped fields from related models
+   * Đồng bộ các trường được ánh xạ (mapped field) từ model liên kết.
+   *
+   * Dùng để tự động điền trường hiển thị từ khóa ngoại.
    *
-   * Used to auto-fill display fields from foreign keys
+   * @param data Dữ liệu đích (được sửa tại chỗ)
+   * @returns Chính đối tượng `data` sau khi đã bổ sung các trường ánh xạ
+   *
+   * @example
+   * ```ts
+   * // Khai báo ánh xạ: lấy `roleName` từ bảng `roles` theo `roleId` của bản ghi hiện tại
+   * userModel.modifieds = {
+   *   roleName: { smodel: roleModel, tkey: 'roleId', skey: 'id', fmap: 'name' }
+   * };
    *
-   * @param data Target data
+   * const data = await userModel.modifiedSync({ id: 1, fullname: 'Nguyen Van A', roleId: 2 });
+   * // data.roleName => "Admin" (tự động truy vấn roles WHERE id = 2)
+   * ```
    */
-  modifiedSync<T extends Record<string, any>>(data: any): Promise<T>;
   /**
-   * Build SQL WHERE clause from filter object
+   * Đồng bộ các trường hiển thị lấy từ model liên kết.
+   *
+   * Dùng để điền tên gọi từ khoá ngoại (ví dụ `roleId` → `roleName`) lấy từ bảng
+   * khác.
+   *
+   * Truy vấn được **gom nhóm**: các field dùng chung một `(model, khoá)` chỉ gây
+   * ra đúng 1 lệnh `SELECT ... WHERE khoá IN (...)` thay vì 1 lệnh cho mỗi
+   * field — trước đây đây là mẫu N+1 và các lệnh được `await` tuần tự.
    *
-   * Supports advanced operators such as:
-   * `$in`, `$nin`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`, `$like`
+   * Chỉ gán giá trị khi tìm thấy bản ghi nguồn; nếu không thì field đích được
+   * để nguyên (giống hành vi trước đây).
    *
-   * @param filter Query filter object
-   * @param als Optional table alias
+   * @param data Bản ghi cần điền trường hiển thị (được sửa tại chỗ)
+   * @returns Chính `data`
+   *
+   * @example
+   * ```ts
+   * // Khai báo ánh xạ: lấy `roleName` từ bảng `roles` theo `roleId` của bản ghi
+   * userModel.modifieds = {
+   *   roleName: { smodel: roleModel, tkey: 'roleId', skey: 'id', fmap: 'name' }
+   * };
+   *
+   * const data = await userModel.modifiedSync({ id: 1, fullname: 'Nguyen Van A', roleId: 2 });
+   * // data.roleName => "Admin"
+   * ```
    */
-  buildWhere(filter: Record<string, any>, als?: string): {
+  modifiedSync<R extends Record<string, unknown>>(data: Record<string, unknown>): Promise<R>;
+  /**
+   * Dựng mệnh đề SQL `WHERE` từ đối tượng filter.
+   *
+   * Hỗ trợ các toán tử nâng cao:
+   * `$in`, `$nin`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`, `$like`, `$likeIn`
+   * và nhóm điều kiện `$or`, `$and`.
+   *
+   * Khi `isDeleted = true`, mọi filter sẽ được tự động gắn thêm điều kiện `isDeleted = 0`
+   * (soft delete), trừ khi filter đã chỉ định `isDeleted` rõ ràng.
+   *
+   * @param filter Đối tượng điều kiện lọc
+   * @param als Tên alias của bảng (tùy chọn), dùng khi truy vấn có `join`
+   * @returns Object gồm `sql` (mệnh đề WHERE) và `params` (tham số theo đúng thứ tự placeholder)
+   * @throws {Error} `$between requires [min, max]` khi mảng khoảng không đúng 2 phần tử
+   *
+   * @example
+   * ```ts
+   * const { sql, params } = userModel.buildWhere({
+   *   status: 1,
+   *   roleId: { $in: [1, 2] },
+   *   fullname: { $like: 'Nguyen' },
+   *   $or: [{ email: 'a@example.com' }, { email: 'b@example.com' }]
+   * });
+   * // sql    => "`status` = ? AND (`roleId` IN (?,?)) AND (`fullname` LIKE ?) AND ((`email` = ?) OR (`email` = ?)) AND `isDeleted` = ?"
+   * // params => [1, 1, 2, '%Nguyen%', 'a@example.com', 'b@example.com', 0]
+   *
+   * // Filter rỗng khi bật soft delete vẫn lọc theo isDeleted = 0
+   * userModel.buildWhere({}); // { sql: "`isDeleted` = ?", params: [0] }
+   *
+   * // Truyền alias khi cần tự viết câu SQL có join:
+   * const where = userModel.buildWhere({ roleId: 2 }, 'u');
+   * // sql => "`u`.`roleId` = ? AND `u`.`isDeleted` = ?"
+   * ```
+   */
+  buildWhere(filter: AnyFilter, als?: string): {
     sql: string;
-    params: any[];
+    params: SqlParam[];
   };
   /**
-   * Count records matching filter
+   * Đếm số bản ghi khớp với điều kiện lọc.
    *
-   * @param filter Query conditions
+   * @param filter Điều kiện lọc (mặc định không lọc)
+   * @returns Tổng số bản ghi, trả về `0` nếu không có kết quả
+   *
+   * @example
+   * ```ts
+   * await userModel.count();                                   // => tổng số user
+   * await userModel.count({ status: 1, roleId: { $gte: 2 } }); // => số user còn hoạt động thuộc role từ 2 trở lên
+   * ```
    */
-  count(filter?: Record<string, any>): Promise<number>;
+  count(filter?: Filter<T>): Promise<number>;
   /**
-   * Insert a new record
+   * Thêm mới một bản ghi.
+   *
+   * @param data Dữ liệu cần thêm (tên cột sẽ được escape tự động)
+   * @param conn Kết nối DB tùy chọn (dùng trong transaction)
+   * @returns `insertId` của bản ghi vừa thêm
    *
-   * @param data Insert data
-   * @param conn Optional DB connection
+   * @example
+   * ```ts
+   * const newId = await userModel.insert({
+   *   fullname: 'Nguyen Van A',
+   *   email: 'a@example.com',
+   *   roleId: 2,
+   *   status: 1
+   * });
+   * // newId => 42
+   * ```
+   */
+  insert(data: Record<string, SqlParam>, conn?: PoolConnection): Promise<number>;
+  /**
+   * Cập nhật bản ghi theo điều kiện (so sánh bằng dấu `=`).
+   *
+   * Khi `isDeleted = true`, mệnh đề `WHERE` cũng được gắn thêm `isDeleted = 0`
+   * để không cập nhật nhầm lên bản ghi đã xoá mềm (trừ khi filter đã chỉ định
+   * rõ `isDeleted`).
+   *
+   * @param data Dữ liệu cần cập nhật
+   * @param filter Điều kiện lọc WHERE
+   * @param conn Kết nối DB tùy chọn
+   * @returns Số dòng bị ảnh hưởng
+   * @throws {Error} Khi `filter` rỗng, tránh cập nhật toàn bảng
+   *
+   * @example
+   * ```ts
+   * const affected = await userModel.update(
+   *   { status: 0, fullname: 'Nguyen Van B' },
+   *   { id: 7 }
+   * );
+   * // affected => 1
+   *
+   * // Nhiều điều kiện được nối bằng AND
+   * await userModel.update({ status: 1 }, { roleId: 2, status: 0 });
+   * ```
    */
-  insert(data: Record<string, any>, conn?: PoolConnection): Promise<number>;
+  update(data: Record<string, SqlParam>, filter: Filter<T>, conn?: PoolConnection): Promise<number>;
   /**
-   * Update records by condition
+   * Cập nhật nâng cao với điều kiện `WHERE` động (hỗ trợ toán tử nâng cao).
+   *
+   * @param data Danh sách giá trị cần cập nhật; bỏ trống thì hàm thoát ra ngay
+   * @param filter Điều kiện lọc, dựng bằng `buildWhere()`
+   * @param conn Kết nối DB tùy chọn
+   * @returns Số dòng bị ảnh hưởng, `undefined` nếu `data` rỗng
+   * @throws {Error} `invalid_update_is_deleted` khi có lỗi phát sinh trong quá trình cập nhật
+   *
+   * @example
+   * ```ts
+   * // Khác `update()`: điều kiện lọc dùng được toán tử nâng cao
+   * const affected = await userModel.updateAdv(
+   *   { status: 0 },
+   *   { roleId: { $in: [1, 2] }, createdAt: { $between: ['2024-01-01', '2024-12-31'] } }
+   * );
+   * // affected => số user thuộc role 1 hoặc 2 được tạo trong năm 2024
+   * ```
+   */
+  updateAdv(data?: Record<string, SqlParam>, filter?: Filter<T>, conn?: PoolConnection): Promise<number | undefined>;
+  /**
+   * Thêm mới hoặc cập nhật bản ghi theo khóa chính.
+   *
+   * - Nếu có `item.id` → thực hiện `UPDATE`
+   * - Ngược lại → thực hiện `INSERT`
+   *
+   * @param item Dữ liệu entity
+   * @param conn Kết nối DB tùy chọn
+   * @returns Đối tượng đã lưu (với `id` đã được gán khi thêm mới), hoặc `false` nếu có lỗi
+   *
+   * @example
+   * ```ts
+   * // Không có id => INSERT, item.id được gán lại bằng insertId
+   * const created = await userModel.save({ fullname: 'Nguyen Van A', email: 'a@example.com' });
+   * // created.id => 42
+   *
+   * // Có id => UPDATE
+   * await userModel.save({ id: 42, status: 0 });
+   * ```
    */
-  update(data: Record<string, any>, filter: Record<string, any>, conn?: PoolConnection): Promise<number>;
   /**
-   * Advanced update with dynamic where conditions
+   * Lưu bản ghi và trả về kết quả có kiểu, **không** dùng state lỗi dùng chung.
+   *
+   * Model thường được đăng ký là singleton (`initModels`) nên dùng chung cho mọi
+   * request. Biến `errors` của instance vì thế có thể bị lẫn giữa các request
+   * đang chạy song song. Hàm này trả lỗi trực tiếp trong giá trị trả về nên
+   * không cần đọc `getErrors()` — đây là API nên dùng.
    *
-   * @param data Update values
-   * @param filter Query conditions
-   * @param conn Optional DB connection
+   * @param item Dữ liệu cần lưu
+   * @param conn Kết nối DB tùy chọn
+   * @returns `{ ok: true, item }` khi thành công, `{ ok: false, errors }` khi lỗi
+   *
+   * @example
+   * ```ts
+   * const result = await userModel.saveResult({ fullname: 'A' });
+   * if (!result.ok) throw new ClientError(result.errors.join(', '), 400);
+   * console.log(result.item.id);
+   * ```
    */
-  updateAdv(data?: Record<string, any>, filter?: Record<string, any>, conn?: PoolConnection): Promise<any>;
+  saveResult(item: Partial<T>, conn?: PoolConnection): Promise<SaveResult<T>>;
   /**
-   * Insert or update record by primary key
+   * Lưu bản ghi, trả về `false` nếu thất bại.
    *
-   * - If `item.id` exists → update
-   * - Otherwise → insert
+   * > **Cảnh báo về trạng thái dùng chung**: hàm này ghi lỗi vào `this.errors`
+   * > (dùng chung cho mọi request khi model là singleton). Với code chạy đồng
+   * > thời, hãy dùng {@link BaseModel.saveResult} để nhận lỗi trực tiếp.
    *
-   * @param item Entity data
-   * @param conn Optional DB connection
+   * @param item Dữ liệu cần lưu
+   * @param conn Kết nối DB tùy chọn
+   * @returns Bản ghi đã lưu, hoặc `false` khi thất bại
    */
   save(item: Partial<T>, conn?: PoolConnection): Promise<T | false>;
   /**
-   * Validate and save record
+   * Kiểm tra dữ liệu rồi lưu bản ghi.
+   *
+   * Trình tự thực hiện: `modifiedSync()` → `validate()` → `save()`.
    *
-   * @throws Error when validation or save fails
+   * @param item Dữ liệu cần lưu
+   * @param validate Bộ quy tắc kiểm tra; truyền `false` để bỏ qua bước validate
+   * @param conn Kết nối DB tùy chọn
+   * @param lang Mã ngôn ngữ cho thông báo lỗi (mặc định `'vi'`)
+   * @returns Bản ghi đã lưu, hoặc `null` nếu bỏ qua validate và lưu thất bại
+   * @throws {Error} Khi kiểm tra hoặc lưu thất bại; message là các lỗi nối bằng dấu `, `
+   *
+   * @example
+   * ```ts
+   * const rules = { email: 'required|email' };
+   *
+   * try {
+   *   const user = await userModel.vdSave(
+   *     { fullname: 'Nguyen Van A', email: 'a@example.com' },
+   *     rules
+   *   );
+   *   // user.id => 42
+   * } catch (error) {
+   *   // Ví dụ: "Email không đúng định dạng"
+   *   console.error(toError(error).message);
+   * }
+   *
+   * // Thông báo lỗi bằng tiếng Anh (lang là tham số cuối)
+   * await userModel.vdSave({ email: 'sai' }, rules, undefined, 'en');
+   * // throw: "Email is not in the correct format"
+   * ```
    */
-  vdSave(item: any, vdObject?: any | false, conn?: PoolConnection): Promise<T | null>;
+  vdSave(item: Partial<T>, validate?: Record<string, string> | false, conn?: PoolConnection, lang?: string): Promise<T | null>;
   /**
-   * Batch update multiple records using CASE WHEN
+   * Cập nhật hàng loạt nhiều bản ghi bằng kỹ thuật `CASE WHEN`.
+   *
+   * Mỗi cột được dựng thành `CASE ... WHEN id THEN ? ... ELSE <cột hiện tại> END`,
+   * nên câu lệnh chỉ chạy một lần thay vì N lần.
+   *
+   * @param rows Danh sách dữ liệu, các phần tử phải có cùng tập cột
+   * @param key Tên trường khóa chính dùng để định danh từng dòng
+   * @param conn Kết nối DB tùy chọn
+   * @throws {Error} `invalid_update_many` khi có lỗi phát sinh trong quá trình cập nhật
    *
-   * @param rows Data rows
-   * @param key Primary key field
+   * @example
+   * ```ts
+   * await userModel.updateMany([
+   *   { id: 1, status: 0 },
+   *   { id: 2, status: 1 }
+   * ], 'id');
+   * // => UPDATE `users` SET `status` = CASE `id` WHEN ? THEN ? WHEN ? THEN ? ELSE `status` END WHERE `id` IN (?,?)
+   * ```
    */
-  updateMany(rows: any[], key: string, conn?: PoolConnection): Promise<void>;
+  updateMany(rows: Array<Record<string, SqlParam>>, key: string, conn?: PoolConnection): Promise<void>;
   /**
-   * Bulk insert or update (UPSERT) records
+   * Thêm hàng loạt bản ghi, tự cập nhật nếu bản ghi đã tồn tại (UPSERT).
+   *
+   * Dùng `INSERT ... ON DUPLICATE KEY UPDATE` với mệnh đề `col = VALUES(col)`
+   * cho mọi cột trừ khóa chính.
+   *
+   * @param rows Danh sách dữ liệu, các phần tử phải có cùng tập cột
+   * @param key Tên trường khóa chính (không được đưa vào phần `UPDATE`)
+   * @param conn Kết nối DB tùy chọn
+   * @throws {Error} `invalid_update_and_create` khi có lỗi phát sinh trong quá trình ghi
+   *
+   * @example
+   * ```ts
+   * await userModel.updateAndCreateMany([
+   *   { id: 1, fullname: 'Nguyen Van A', status: 1 },
+   *   { id: 2, fullname: 'Tran Thi B', status: 1 }
+   * ], 'id');
+   * // id chưa có => INSERT; id đã có => UPDATE các cột còn lại
+   * ```
+   */
+  updateAndCreateMany(rows: Array<Record<string, SqlParam>>, key: string, conn?: PoolConnection): Promise<void>;
+  /**
+   * Tìm danh sách bản ghi với các tùy chọn nâng cao (lọc, sắp xếp, join, chọn cột, giới hạn).
+   *
+   * @param filter Điều kiện lọc WHERE
+   * @param order Tùy chọn sắp xếp (ORDER BY) — key là tên cột (đã escape), value chỉ nhận `'ASC' | 'DESC'`
+   * @param join Cấu hình JOIN bảng; `on` chỉ nhận phép so sánh đơn giản giữa các cột
+   * @param select Danh sách cột cần lấy; không nhận SQL thô
+   * @param limit Số bản ghi tối đa cần lấy, `0` nghĩa là không giới hạn
+   * @returns Mảng các bản ghi tìm thấy (mảng rỗng nếu không có kết quả)
+   *
+   * @example
+   * ```ts
+   * // Lọc + sắp xếp + giới hạn
+   * const users = await userModel.find(
+   *   { status: 1, roleId: { $in: [1, 2] }, fullname: { $like: 'Nguyen' } },
+   *   { id: 'DESC' },
+   *   false,
+   *   ['id', 'fullname', 'email'],
+   *   10
+   * );
    *
-   * @param rows Data rows
-   * @param key Primary key field
+   * // Kết hợp join để lấy thêm cột của bảng khác
+   * const usersWithRoles = await userModel.find(
+   *   { status: 1 },
+   *   { id: 'DESC' },
+   *   { table: 'roles', on: { left: 'users.roleId', right: 'roles.id', operator: '=' }, fields: ['name'] },
+   *   [{ column: 'users.id' }, { column: 'roles.name', alias: 'roleName' }]
+   * );
+   * ```
    */
-  updateAndCreateMany(rows: any[], key: string, conn?: PoolConnection): Promise<void>;
+  find(filter?: Filter<T>, order?: Record<string, string> | false, join?: JoinType | JoinType[] | false, select?: SqlSelectInput | false, limit?: number): Promise<T[]>;
   /**
-   * Find records with advanced options
+   * Tìm 1 bản ghi đầu tiên thỏa mãn điều kiện lọc
+   *
+   * @param filter Điều kiện lọc WHERE
+   * @param order Tùy chọn sắp xếp (ORDER BY); key là tên cột, value là `ASC` / `DESC`
+   * @param join Cấu hình JOIN bảng; `on` chỉ nhận phép so sánh đơn giản giữa các cột
+   * @param select Danh sách cột cần lấy; không nhận SQL thô
+   * @returns Bản ghi tìm thấy hoặc null nếu không tồn tại
    *
-   * @param filter Query conditions
-   * @param order Sort options
-   * @param join Join configuration
-   * @param select Custom select fields
-   * @param limit Limit result count
+   * @example
+   * ```ts
+   * const user = await userModel.findOne({ email: 'a@example.com' });
+   * // user?.id => 42, hoặc null nếu email không tồn tại
+   *
+   * // Kèm điều kiện sắp xếp để chọn đúng 1 bản ghi khi có nhiều kết quả
+   * await userModel.findOne({ roleId: 2 }, { id: 'DESC' });
+   * ```
+   */
+  findOne(filter?: Filter<T>, order?: Record<string, string> | false, join?: JoinType | JoinType[] | false, select?: SqlSelectInput | false): Promise<T | null>;
+  /**
+   * Tìm bản ghi theo ID khóa chính
+   *
+   * @param id Khóa chính ID của bản ghi
+   * @param filter Điều kiện lọc bổ sung
+   * @returns Bản ghi tìm thấy hoặc null
+   *
+   * @example
+   * ```ts
+   * const user = await userModel.findById(42);
+   * // user?.email => "a@example.com", hoặc null nếu id không tồn tại
+   *
+   * // Có thể kèm điều kiện lọc bổ sung (được nối với điều kiện id bằng AND)
+   * await userModel.findById(42, { status: 1 });
+   * ```
+   */
+  findById(id: number, filter?: Filter<T>): Promise<T | null>;
+  /**
+   * Xóa 1 bản ghi thỏa mãn điều kiện lọc (LIMIT 1)
+   *
+   * @param filter Điều kiện lọc WHERE
+   * @param conn Kết nối DB tùy chọn
+   * @returns `true` nếu xóa thành công ít nhất 1 dòng, ngược lại `false`
+   *
+   * @example
+   * ```ts
+   * // Xóa tối đa 1 bản ghi đầu tiên khớp điều kiện
+   * const ok = await userModel.deleteOne({ email: 'a@example.com' });
+   * // ok => true nếu có dòng bị xóa, ngược lại false
+   * ```
+   */
+  deleteOne(filter: Filter<T>, conn?: PoolConnection): Promise<boolean>;
+  /**
+   * Xóa bản ghi theo ID khóa chính
+   *
+   * @param id Khóa chính ID cần xóa
+   * @param conn Kết nối DB tùy chọn
+   * @returns `true` nếu xóa thành công, ngược lại `false`
+   *
+   * @example
+   * ```ts
+   * const ok = await userModel.deleteById(42);
+   * // ok => true nếu bản ghi id = 42 bị xóa, ngược lại false
+   * ```
    */
-  find(filter?: Record<string, any>, order?: Record<string, string> | false, join?: JoinType | JoinType[] | false, select?: string | string[] | false, limit?: number): Promise<T[]>;
-  findOne(filter?: Record<string, any>, order?: Record<string, string> | false, join?: JoinType | JoinType[] | false, select?: string | string[] | false): Promise<T | null>;
-  findById(id: number, filter?: Record<string, any>): Promise<T | null>;
-  deleteOne(filter: Record<string, any>, conn?: PoolConnection): Promise<boolean>;
   deleteById(id: number, conn?: PoolConnection): Promise<boolean>;
-  deleteMany(filter: Record<string, any>, limit?: number, conn?: PoolConnection): Promise<boolean>;
+  /**
+   * Xóa nhiều bản ghi thỏa mãn điều kiện lọc
+   *
+   * @param filter Điều kiện lọc WHERE (bắt buộc)
+   * @param limit Giới hạn số dòng cần xóa (0 = không giới hạn)
+   * @param conn Kết nối DB tùy chọn
+   * @returns `true` nếu có dòng bị xóa, ngược lại `false`
+   * @throws {Error} `deleteMany requires a filter condition` khi `filter` rỗng.
+   *   Bắt buộc chặn trường hợp này vì `buildWhere()` luôn trả về `1=1` khi
+   *   không có điều kiện, và `DELETE FROM t WHERE 1=1` sẽ xóa toàn bộ bảng.
+   *
+   * @example
+   * ```ts
+   * // Xóa toàn bộ bản ghi khớp điều kiện
+   * const ok = await userModel.deleteMany({ roleId: 2 });
+   * // ok => true nếu có dòng bị xóa
+   *
+   * // Giới hạn số dòng xóa tối đa
+   * await userModel.deleteMany({ status: 0 }, 100);
+   *
+   * // Filter rỗng bị từ chối để tránh xóa nhầm toàn bộ bảng
+   * await userModel.deleteMany({});   // throw Error: deleteMany requires a filter condition
+   * ```
+   */
+  deleteMany(filter: Filter<T>, limit?: number, conn?: PoolConnection): Promise<boolean>;
+  /**
+   * Kiểm tra một cột cụ thể có tồn tại trong bảng hay không
+   *
+   * @param field Tên cột cần kiểm tra
+   * @param table Tên bảng (mặc định: bảng hiện tại của model)
+   * @returns `true` nếu cột tồn tại, ngược lại `false`
+   *
+   * @example
+   * ```ts
+   * await userModel.isField('email');            // => true (cột tồn tại trong bảng `users`)
+   * await userModel.isField('not_exist');        // => false
+   * await userModel.isField('name', 'roles');    // kiểm tra trên bảng khác
+   *
+   * // Thường dùng để kiểm tra cột do người dùng gửi lên trước khi đưa vào truy vấn
+   * if (await userModel.isField(inputField)) {
+   *   await userModel.find({ [inputField]: inputValue });
+   * }
+   * ```
+   */
   isField(field: string, table?: string): Promise<boolean>;
+  /**
+   * Xác thực danh sách các cột có thuộc schema của bảng hay không.
+   * Thường dùng để phòng chống SQL injection qua custom fields.
+   *
+   * @param fields Danh sách tên cột cần kiểm tra
+   * @returns Danh sách các cột hợp lệ
+   * @throws {Error} `invalid_fields` nếu có cột không tồn tại trong bảng
+   *
+   * @example
+   * ```ts
+   * // Mảng rỗng => trả về mảng rỗng, không truy vấn DB
+   * await userModel.isFields([]); // => []
+   *
+   * await userModel.isFields(['id', 'fullname', 'email']); // => ['id', 'fullname', 'email']
+   * await userModel.isFields(['id', 'hack']);              // throw Error: invalid_fields
+   *
+   * // Dùng để chống SQL injection khi người dùng tự chọn cột cần sắp xếp
+   * const orderBy = await userModel.isFields([req.query.sortBy as string]);
+   * await userModel.find({}, { [orderBy[0]]: 'DESC' });
+   * ```
+   */
   isFields(fields?: string[]): Promise<string[]>;
   /**
-   * Get mapped display value from a related model.
+   * Đọc (và ghi nhớ) danh sách cột của một bảng.
    *
-   * This method is commonly used to convert a foreign key value
-   * into a human-readable field (e.g. `name`, `title`) from another table.
+   * Kết quả được cache theo tên bảng để tránh gọi `SHOW COLUMNS` lặp lại cho
+   * mỗi request — trước đây `isField`/`isFields` đều chạy một round-trip mỗi lần
+   * gọi (mẫu N+1).
    *
-   * It will only query the related model when:
-   * - `fieldVal` is provided
-   * - `fieldVal` is different from the previous value (`itemOld`)
+   * Cache là thuộc tính của **instance**. Nếu schema bảng thay đổi trong lúc
+   * ứng dụng đang chạy, dùng `clearSchemaCache()` để nạp lại.
    *
-   * @param field       Target field name in current model
-   * @param fieldVal    New value of the field (usually a foreign key ID)
-   * @param mdClass     Related model class instance used to fetch data
-   * @param itemOld     Previous record data (used to detect value changes)
-   * @param fieldMap    Field name in related model to map from (default: `"name"`)
+   * @param table Tên bảng cần đọc schema
+   * @returns Danh sách tên cột
+   * @private
+   */
+  private getSchemaFields;
+  /**
+   * Xoá cache schema của model.
    *
-   * @returns Mapped display value from related model,
-   *          or empty string if not found or unchanged
+   * Cần gọi khi bảng được migrate/ALTER trong lúc ứng dụng đang chạy.
    *
    * @example
    * ```ts
-   * // Convert categoryId → categoryName
-   * const categoryName = await productModel.getMapName(
-   *   "categoryId",
-   *   product.categoryId,
-   *   categoryModel,
-   *   oldProduct,
-   *   "name"
+   * await migrate();
+   * userModel.clearSchemaCache();
+   * ```
+   */
+  clearSchemaCache(): void;
+  /**
+   * Lấy giá trị hiển thị được ánh xạ từ model liên kết.
+   *
+   * Thường dùng để chuyển một giá trị khóa ngoại thành trường dễ đọc
+   * (ví dụ `name`, `title`) lấy từ bảng khác.
+   *
+   * Chỉ truy vấn model liên kết khi:
+   * - `fieldVal` có giá trị
+   * - `fieldVal` khác giá trị cũ (`itemOld`)
+   *
+   * @param field    Tên trường đích trong model hiện tại
+   * @param fieldVal Giá trị mới của trường (thường là ID khóa ngoại)
+   * @param mdClass  Instance model liên kết dùng để lấy dữ liệu
+   * @param itemOld  Dữ liệu bản ghi cũ (dùng để phát hiện giá trị có thay đổi)
+   * @param fieldMap Tên trường cần lấy trong model liên kết (mặc định: `"name"`)
+   *
+   * @returns Giá trị hiển thị lấy từ model liên kết,
+   *          hoặc chuỗi rỗng nếu không tìm thấy hoặc giá trị không đổi
+   *
+   * @example
+   * ```ts
+   * // Chuyển roleId => roleName
+   * const roleName = await userModel.getMapName(
+   *   'roleId',
+   *   user.roleId,
+   *   roleModel,
+   *   oldUser,
+   *   'name'
    * );
+   * // roleName => "Admin"
+   * // Nếu roleId không đổi so với oldUser hoặc không tìm thấy bản ghi => ""
    * ```
    */
-  getMapName(field: string, fieldVal: any, mdClass: any, itemOld?: any, fieldMap?: string): Promise<any>;
+  getMapName(field: string, fieldVal: SqlParam, mdClass: IBaseModel | null | undefined, itemOld?: Partial<T> | null, fieldMap?: string): Promise<{}>;
   /**
-   * Find records with pagination support
+   * Tìm bản ghi kèm phân trang.
+   *
+   * Chạy 2 câu truy vấn: một câu `COUNT(*)` để tính tổng số bản ghi
+   * và một câu `SELECT ... LIMIT ? OFFSET ?` để lấy dữ liệu trang hiện tại.
+   *
+   * @param filter Điều kiện lọc WHERE
+   * @param order Tùy chọn sắp xếp (ORDER BY) — key là tên cột (đã escape), value chỉ nhận `'ASC' | 'DESC'`
+   * @param join Cấu hình JOIN bảng; `on` chỉ nhận phép so sánh đơn giản giữa các cột
+   * @param select Danh sách cột cần lấy; không nhận SQL thô
+   * @param page Số trang, bắt đầu từ 1 (giá trị không hợp lệ sẽ được chuẩn hóa về 1)
+   * @param limit Số bản ghi mỗi trang (tối thiểu 1)
+   * @returns Object gồm `page`, `length`, `pageTotal`, `recordTotal` và `items`
+   *
+   * @example
+   * ```ts
+   * const result = await userModel.findWithPagination(
+   *   { status: 1 },
+   *   { id: 'DESC' },
+   *   false,   // join
+   *   false,   // select
+   *   2,       // page: trang thứ 2
+   *   20       // limit: 20 bản ghi mỗi trang
+   * );
+   * // result.recordTotal => 45 (tổng số bản ghi)
+   * // result.pageTotal   => 3  (Math.ceil(45 / 20))
+   * // result.items       => mảng 20 bản ghi của trang 2
    *
-   * @param filter Query conditions
-   * @param order Sort options
-   * @param join Join configuration
-   * @param select Custom select fields
-   * @param page Page number (starts from 1)
-   * @param limit Items per page
+   * // Kết hợp join để lấy tên role kèm theo
+   * await userModel.findWithPagination(
+   *   { status: 1 },
+   *   { id: 'DESC' },
+   *   { table: 'roles', on: { left: 'users.roleId', right: 'roles.id', operator: '=' } },
+   *   [{ column: 'users.id' }, { column: 'users.fullname' }, { column: 'roles.name', alias: 'roleName' }]
+   * );
+   * ```
    */
-  findWithPagination(filter?: Record<string, any>, order?: Record<string, string> | false, join?: JoinType | JoinType[] | false, select?: string | string[] | false, page?: number, limit?: number): Promise<PaginationResult<T>>;
+  findWithPagination(filter?: Filter<T>, order?: Record<string, string> | false, join?: JoinType | JoinType[] | false, select?: SqlSelectInput | false, page?: number, limit?: number): Promise<PaginationResult<T>>;
 }
+/**
+ * Instance model dùng ở những vị trí không cần biết entity cụ thể, ví dụ container
+ * `Models` hay khai báo `modifieds`.
+ *
+ * Vì sao dùng `any` thay vì `ModelRow`: `BaseModel<T>` là **bất biến** (invariant)
+ * trong `T` — `T` xuất hiện ở cả vị trí tham số (`save(item: Partial<T>)`) lẫn kiểu
+ * trả về (`Promise<T | false>`) — nên `BaseModel<UserItem>` không thể gán cho
+ * `BaseModel<ModelRow>`. Nếu ràng buộc bằng `ModelRow` thì container sẽ không nhận
+ * được bất kỳ model nào khai báo entity bằng `interface`.
+ *
+ * Ở các vị trí này không có hàm nào của model được gọi, nên ràng buộc chỉ mang tính
+ * gợi ý; kiểu chính xác của từng model vẫn được giữ nguyên qua `InstanceType` trong
+ * `Models<T>`.
+ */
+type AnyBaseModel = BaseModel<any>;
+/** @see {@link AnyBaseModel} — phiên bản interface cho các vị trí tương tự. */
+type AnyIBaseModel = IBaseModel<any>;
 //#endregion
 //#region src/Common.d.ts
 /**
@@ -214,19 +907,56 @@ declare abstract class BaseModel<T extends Record<string, any> & {
  * @param value Chuỗi mật khẩu gốc
  * @returns Chuỗi mật khẩu đã được hash
  */
-declare function makePassword(value: any): Promise<string>;
+declare function makePassword(value: string | Buffer): Promise<string>;
 /**
  * 🔐 Kiểm tra mật khẩu với hash
  * @param value Mật khẩu người dùng nhập
  * @param hashedValue Mật khẩu đã hash lưu trong DB
  * @returns true nếu khớp, false nếu không
  */
-declare function checkPassword(value: any, hashedValue: any): Promise<boolean>;
+declare function checkPassword(value: string | Buffer, hashedValue: string): Promise<boolean>;
+/**
+ * 🛡️ Escape các ký tự đặc biệt của HTML.
+ *
+ * Đây là cách **loại bỏ rủi ro XSS triệt để** thay vì "xoá thẻ nguy hiểm": escape
+ * làm cho mọi thẻ HTML trở thành **văn bản hiển thị**, nên không tồn tại payload nào
+ * lọt qua được — kể cả `onerror`, `onload`, `javascript:`, `<svg>`, `<iframe>`...
+ *
+ * Phạm vi: escape `& < > " ' \`` — đủ cho cả ngữ cảnh văn bản lẫn thuộc tính HTML.
+ *
+ * Lưu ý: escape **mọi thứ**, kể cả thẻ vô hại. Nếu cần lưu rich-text (HTML do
+ * người dùng soạn bằng trình soạn thảo), hãy dùng thư viện sanitizer chuyên dụng
+ * (`sanitize-html`, `DOMPurify`) thay vì escape.
+ *
+ * @param input Chuỗi cần escape
+ * @returns Chuỗi đã escape; input không phải string trả `''`
+ *
+ * @example
+ * ```ts
+ * escapeHtml('<img src=x onerror=alert(1)>');
+ * // => '&lt;img src=x onerror=alert(1)&gt;'  — hiển thị an toàn, không thực thi
+ * ```
+ */
+declare function escapeHtml(input: string): string;
 /**
- * 🔢 Tạo chuỗi random
+ * 🎲 Tạo chuỗi ngẫu nhiên bằng CSPRNG (`node:crypto`).
+ *
+ * Dùng `crypto.randomInt()` chứ không phải `Math.random()`: `Math.random()` dùng
+ * thuật toán PRNG không phải sinh hoàn toàn và **không đảm bảo an toàn về mật mã**,
+ * tức chuỗi sinh ra có thể bị dự đoán nếu dùng cho OTP, token đặt lại mật khẩu hay
+ * khoá phiên.
+ *
+ * Tập ký tự sinh ra giống hệt bản cũ nên chuỗi trả về tương thích ngược.
+ *
  * @param length Độ dài chuỗi
- * @param az Có bao gồm chữ cái hay không
- * @returns Chuỗi random
+ * @param az Có bao gồm chữ cái hay không (mặc định chỉ chữ số)
+ * @returns Chuỗi ngẫu nhiên
+ *
+ * @example
+ * ```ts
+ * randomText(6);        // '428193'  — OTP
+ * randomText(32, true); // 32 ký tự chữ + số — CSRF token
+ * ```
  */
 declare function randomText(length: number, az?: boolean): string;
 /**
@@ -250,7 +980,7 @@ declare function slugify(text: string): string;
  * @param headers Header bổ sung
  * @returns JSON response
  */
-declare function callFetchApi(url: string, data?: any, type?: string, ctype?: string, headers?: Record<string, any>): Promise<any>;
+declare function callFetchApi(url: string, data?: unknown, type?: string, ctype?: string, headers?: Record<string, string>): Promise<any>;
 /**
  * 🧠 Tạo chuỗi keyword phục vụ search
  * @param text Chuỗi đầu vào
@@ -300,7 +1030,7 @@ declare function toMySQLDateNowVN(): string;
  * @param df Giá trị mặc định
  * @returns Giá trị hoặc default
  */
-declare function getValue(item: any, key: any, df?: any): any;
+declare function getValue<T>(item: Record<string, unknown> | T | null | undefined, key: keyof T | string, df?: unknown): unknown;
 /**
  * ➕ Tính tổng 1 cột trong mảng object
  * @param items Mảng object
@@ -357,28 +1087,28 @@ declare function getTrueFlaseStatus(id: string | boolean | number, color?: boole
  * @param arr2 Mảng thứ hai
  * @returns Mảng chứa các phần tử chỉ xuất hiện ở một trong hai mảng
  */
-declare function getDiffArr(arr1: any[], arr2: any[]): any[];
+declare function getDiffArr<T>(arr1: T[], arr2: T[]): T[];
 /**
  * 📦 Kiểm tra mảng arr1 có phải là tập con của arr2 hay không
  * @param arr1 Mảng cần kiểm tra
  * @param arr2 Mảng cha
  * @returns true nếu mọi phần tử arr1 đều tồn tại trong arr2
  */
-declare function isSubArr(arr1: any[], arr2: any[]): boolean;
+declare function isSubArr<T>(arr1: T[], arr2: T[]): boolean;
 /**
  * ➖ Lấy các phần tử chỉ có trong mảng thứ nhất
  * @param arr1 Mảng gốc
  * @param arr2 Mảng so sánh
  * @returns Mảng các phần tử chỉ tồn tại trong arr1
  */
-declare function getArrOnlyInFirst(arr1: any[], arr2: any[]): any[];
+declare function getArrOnlyInFirst<T>(arr1: T[], arr2: T[]): T[];
 /**
  * 📤 Lấy danh sách giá trị của một cột trong mảng object
  * @param arr Mảng object
  * @param field Tên field cần lấy
  * @returns Mảng giá trị của field
  */
-declare function getArrColumn(arr: any[], field: string): any[];
+declare function getArrColumn<T extends Record<string, unknown>>(arr: T[], field: keyof T | string): any[];
 /**
  * ➕ Tính tổng một cột trong mảng object với điều kiện tùy chọn
  * @param arr Mảng object
@@ -386,7 +1116,7 @@ declare function getArrColumn(arr: any[], field: string): any[];
  * @param conditions Điều kiện lọc (optional)
  * @returns Tổng giá trị thỏa điều kiện
  */
-declare function sumArrColumn<T extends Record<string, any>>(arr: T[], sumColumn: keyof T, conditions?: Partial<T>): number;
+declare function sumArrColumn<T extends Record<string, unknown>>(arr: T[], sumColumn: keyof T, conditions?: Partial<T>): number;
 /**
  * 🔢 Chuyển chuỗi số sang Decimal.js an toàn
  * @param value Chuỗi hoặc số (có thể chứa ký tự khác)
@@ -399,7 +1129,7 @@ declare function decimalNumber(value: string | number): Decimal.Decimal;
  * @param df Giá trị mặc định nếu parse lỗi
  * @returns Object | Array | df
  */
-declare function stringToJson(input: any, df?: Record<string, any>): any;
+declare function stringToJson<T = Record<string, unknown>>(input: unknown, df?: T): any;
 /**
  * 🌐 Lấy danh sách ngôn ngữ
  * @param ids Danh sách id cần lọc hoặc false để lấy tất cả
@@ -411,20 +1141,92 @@ declare function getLangs(ids?: number[] | false): {
 }[];
 //#endregion
 //#region src/Csrf.d.ts
+/**
+ * Kiểm tra xem phương thức HTTP có phải là method làm thay đổi trạng thái (POST, PUT, PATCH, DELETE) hay không.
+ *
+ * @param method Tên phương thức HTTP (vd: 'GET', 'POST', 'delete')
+ * @returns `true` nếu method thuộc POST, PUT, PATCH, DELETE; ngược lại `false`
+ */
 declare function isStateChangingMethod(method: string): boolean;
-declare function getCsrfTokenFromRequest(req: any): any;
-declare function ensureCsrfProtection(req: any, session: any, options?: any): {
-  allowed: boolean;
-  reason: null;
-} | {
+interface CsrfRequest {
+  method?: string;
+  headers?: Record<string, string | string[] | undefined>;
+  body?: Record<string, unknown> | null;
+}
+interface CsrfSession {
+  csrfToken?: string;
+}
+interface CsrfProtectionOptions {
+  expectedToken?: string;
+}
+interface CsrfProtectionResult {
   allowed: boolean;
-  reason: string;
-};
+  reason: string | null;
+}
+/**
+ * Trích xuất CSRF token từ request Fastify/Express.
+ * Token có thể được gửi qua header (`x-csrf-token`, `X-CSRF-Token`) hoặc body (`csrfToken`, `csrf_token`).
+ *
+ * @param req Đối tượng request
+ * @returns Chuỗi CSRF token hoặc rỗng nếu không tìm thấy
+ */
+declare function getCsrfTokenFromRequest(req: CsrfRequest | null | undefined): string;
+/**
+ * Xác thực bảo vệ chống CSRF cho request.
+ * - Với GET/HEAD/OPTIONS...: bỏ qua kiểm tra, luôn cho phép.
+ * - Với POST/PUT/PATCH/DELETE: so sánh token trong session với token gửi từ request.
+ *
+ * Token được so sánh bằng `safeEqual()` (constant-time) để không bị lộ qua
+ * timing attack.
+ *
+ * @param req Đối tượng request
+ * @param session Đối tượng session chứa `csrfToken`
+ * @param options Tùy chọn bổ sung, có thể truyền `expectedToken` nếu không nằm trong session
+ * @returns Đối tượng `{ allowed: boolean, reason: string | null }`
+ *
+ * @example
+ * ```ts
+ * const check = ensureCsrfProtection(req, session);
+ * if (!check.allowed) {
+ *   throw new ClientError('CSRF token không hợp lệ', 403);
+ * }
+ * ```
+ */
+declare function ensureCsrfProtection(req: CsrfRequest | null | undefined, session: CsrfSession | null | undefined, options?: CsrfProtectionOptions): CsrfProtectionResult;
+//#endregion
+//#region src/Crypto.d.ts
+/**
+ * So sánh hai chuỗi bí mật theo cách chống **timing attack**.
+ *
+ * `===` / `!==` dừng so sánh ngay khi gặp ký tự khác nhau, nên thời gian thực thi
+ * phản ánh vị trí ký tự đầu tiên lệch → kẻ tấn công có thể dò từng ký tự secret.
+ * `timingSafeEqual` so sánh toàn bộ byte trong thời gian cố định.
+ *
+ * Cả hai chuỗi được băm SHA-256 trước nhằm:
+ * - luôn có cùng độ dài 32 byte để `timingSafeEqual` không ném lỗi khi hai chuỗi
+ *   khác độ dài;
+ * - không làm lộ độ dài của secret qua thời gian chạy.
+ *
+ * @param a Chuỗi thứ nhất (ví dụ token người dùng gửi lên)
+ * @param b Chuỗi thứ hai (ví dụ secret lưu trong session/env)
+ * @returns `true` khi hai chuỗi giống nhau
+ *
+ * @example
+ * ```ts
+ * safeEqual(req.headers['x-api-key'] ?? '', process.env.API_KEY ?? '');
+ * ```
+ */
+declare function safeEqual(a: string, b: string): boolean;
 //#endregion
 //#region src/FastRequest.d.ts
 /**
  * Kiểu dữ liệu file upload tạm
  */
+type RequestValue = string | number | boolean | null | undefined | RequestValue[] | {
+  [key: string]: RequestValue;
+};
+type RequestBody = Record<string, RequestValue | unknown>;
+type FilterType = string;
 interface FileType$1 {
   filename: string;
   basename: string;
@@ -449,7 +1251,7 @@ interface FileType$1 {
  * - Import / export / upload file
  */
 declare class FastRequest {
-  [x: string]: any;
+  [x: string]: unknown;
   /** Fastify request gốc */
   private req;
   /** Body sau khi parse */
@@ -465,13 +1267,19 @@ declare class FastRequest {
    */
   constructor(req: FastifyRequest);
   /**
-   * Start xử lý request
+   * Parse dữ liệu request vào `body`/`files` để dùng cho các getter.
    *
-   * Công dụng:
-   * - Parse body thường (JSON)
-   * - Parse multipart/form-data
-   * - Lưu file upload vào thư mục tạm
-   * - Gom field & file theo đúng format
+   * Điều kiện xử lý:
+   * - `req.body` truthy được dùng nguyên trạng; nhánh multipart chỉ chạy khi
+   *   body falsy và `req.isMultipart()` trả `true`.
+   * - Multipart field trùng tên: giá trị đầu giữ scalar, lần thứ hai trở đi
+   *   được gom thành mảng theo thứ tự.
+   * - File chỉ được ghi khi `FileUpload.checkDefFile(...)` trả `true`; nếu ghi
+   *   lỗi, thông báo được log nhưng entry file vẫn được thêm với đường dẫn đích.
+   * - Thư mục `uploads/tmb` được tạo nếu chưa tồn tại. Tên file dùng basename
+   *   đã slugify nhưng không được bảo đảm unique nếu các field trùng tên file.
+   *
+   * @returns `Promise<void>`
    */
   start: () => Promise<void>;
   /**
@@ -488,54 +1296,226 @@ declare class FastRequest {
   /** Check AJAX request */
   isAjax(): boolean;
   /**
-   * Lấy dữ liệu POST
+   * Lấy một giá trị từ body đã được `start()` parse.
+   *
+   * Điều kiện xử lý:
+   * - `name` rỗng: trả toàn bộ `this.body` mà không filter.
+   * - Field không tồn tại: trả `defaultValue`.
+   * - Field là object có thuộc tính `value !== undefined`: lấy `field.value`.
+   * - Các trường hợp còn lại: chuyển qua `FastRequest.filterSafeData()`.
+   *
+   * `defaultValue` được truyền xuống filter, nên còn được dùng khi `int`/`number`
+   * không chuyển đổi được. Giá trị có sẵn kiểu `number` luôn được giữ nguyên.
+   *
+   * @param name Tên field; chuỗi rỗng dùng để lấy toàn bộ body
+   * @param defaultValue Giá trị khi thiếu field hoặc chuyển kiểu số thất bại
+   * @param type Kiểu filter, xem `FastRequest.filterSafeData`
+   * @returns Toàn bộ body hoặc giá trị đã xử lý
+   * @throws {Error} `invalid_max_safe_integer` hoặc `invalid_min_safe_integer`
+   * khi giá trị số vượt giới hạn an toàn
+   */
+  getPost(name?: string, defaultValue?: unknown, type?: string): any;
+  /**
+   * Lấy giá trị của field đa ngôn ngữ có tên dạng `field{lang}`.
+   *
+   * Điều kiện xử lý:
+   * - `name` rỗng hoặc không khớp đúng mẫu `field{lang}`: trả `defaultValue`.
+   * - `field` trong body là chuỗi JSON: parse thành object/array trước khi đọc key `lang`.
+   * - Body JSON không hợp lệ hoặc không đúng cấu trúc được xem như không có key `lang`.
+   * - Giá trị tìm thấy được chuyển qua `FastRequest.filterSafeData()` với `defaultValue`.
+   *
+   * Với field lồng không tồn tại, kết quả phụ thuộc `type`: `int`/`number` trả
+   * `defaultValue`; các loại chuỗi thông thường trả `''`, còn `raw` có thể trả `undefined`.
+   *
+   * @param name Tên theo mẫu `field{lang}`
+   * @param defaultValue Giá trị khi tên sai hoặc dùng làm fallback của filter số
+   * @param type Kiểu filter, xem `FastRequest.filterSafeData`
+   * @returns Giá trị đa ngôn ngữ đã filter
+   */
+  getLangPost(name: string, defaultValue?: unknown, type?: string): any;
+  /**
+   * Lấy một route param từ `request.params`.
+   *
+   * Điều kiện xử lý:
+   * - Không có `params`, hoặc `params[name]` là falsy (`undefined`, `null`, `''`,
+   *   `0`, `false`, `NaN`): trả `defaultValue`.
+   * - Giá trị truthy được chuyển qua `FastRequest.filterSafeData()`.
+   *
+   * `defaultValue` không được truyền vào filter. Vì vậy khi `type='int'` hoặc
+   * `type='number'` nhưng chuyển đổi thất bại, hàm trả `''` (fallback mặc định
+   * của filter), không trả `defaultValue` đã truyền cho hàm.
+   *
+   * @param name Tên route param
+   * @param defaultValue Giá trị khi param không tồn tại hoặc có giá trị falsy
+   * @param type Kiểu filter, xem `FastRequest.filterSafeData`
+   * @returns Giá trị param đã filter hoặc `defaultValue`
+   * @throws {Error} Khi chuyển số vượt giới hạn `Number.MIN_SAFE_INTEGER` đến
+   * `Number.MAX_SAFE_INTEGER`
+   */
+  getParam(name: string, defaultValue?: unknown, type?: string): any;
+  /**
+   * Lấy một query-string value hoặc toàn bộ query từ `request.query`.
+   *
+   * Điều kiện xử lý:
+   * - `name` rỗng: trả toàn bộ `request.query` mà không filter.
+   * - `query[name]` là `undefined`: trả `defaultValue`.
+   * - Giá trị tồn tại (kể cả `null`, `''`, `0`, `false`): chuyển qua
+   *   `FastRequest.filterSafeData()`.
+   *
+   * `defaultValue` không được truyền vào filter. Vì vậy khi chuyển `int`/`number`
+   * thất bại, hàm trả `''` chứ không trả `defaultValue` của hàm.
+   *
+   * @param name Tên query; chuỗi rỗng dùng để lấy toàn bộ query
+   * @param defaultValue Giá trị khi query không có key
+   * @param type Kiểu filter, xem `FastRequest.filterSafeData`
+   * @returns Toàn bộ query hoặc giá trị đã filter
+   * @throws {Error} Khi chuyển số vượt giới hạn an toàn
+   */
+  get(name?: string, defaultValue?: unknown, type?: string): any;
+  /**
+   * Kiểm tra key query có tồn tại hay không.
+   *
+   * Với một tên, tồn tại nghĩa là `query[name] !== undefined`; vì vậy `null`, chuỗi
+   * rỗng, `0` và `false` vẫn được xem là có. Với mảng tên, tất cả key phải tồn tại
+   * (`every`); mảng rỗng trả `true`.
+   *
+   * @param names Một tên query hoặc danh sách tên
+   * @returns `true` khi toàn bộ tên được yêu cầu tồn tại
+   */
+  has(names: string | string[]): boolean;
+  /**
+   * Kiểm tra field body đã parse có tồn tại hay không.
    *
-   * @param name Tên field
-   * @param defaultValue Giá trị mặc định
-   * @param type Kiểu filter
+   * Với một tên, tồn tại nghĩa là `body[name] !== undefined`; vì vậy `null`, chuỗi
+   * rỗng, `0` và `false` vẫn được xem là có. Với mảng tên, tất cả field phải tồn
+   * tại (`every`); mảng rỗng trả `true`.
    *
-   * @returns Giá trị đã filter
+   * @param names Một tên field hoặc danh sách tên field
+   * @returns `true` khi toàn bộ field được yêu cầu tồn tại
    */
-  getPost(name?: string, defaultValue?: any, type?: string): any;
+  hasPost(names: string | string[]): boolean;
   /**
-   * Lấy dữ liệu POST dạng đa ngôn ngữ
+   * Lấy header dưới dạng chuỗi.
    *
-   * Ví dụ field: title{vi}, title{en}
-   */
-  getLangPost(name: string, defaultValue?: any, type?: string): any;
-  /**
-   * Lấy param từ URL
-   */
-  getParam(name: string, defaultValue?: any, type?: string): any;
-  /**
-   * Lấy query string
+   * Key được chuyển về chữ thường để phù hợp header của Node/Fastify. Giá trị được
+   * ép sang chuỗi; header thiếu hoặc có giá trị falsy sau ép chuỗi sẽ trả `''`.
+   *
+   * @param key Tên header không phân biệt hoa thường
+   * @returns Giá trị header hoặc chuỗi rỗng
    */
-  get(name?: string, defaultValue?: any, type?: string): any;
-  /** Check tồn tại query */
-  has(names: string | string[]): boolean;
-  /** Check tồn tại post */
-  hasPost(names: string | string[]): boolean;
-  /** Lấy header */
   getHeader(key: string): string;
   /**
-   * Filter & validate dữ liệu an toàn
+   * Lọc/chuyển kiểu một giá trị đầu vào.
+   *
+   * Điều kiện chung:
+   * - Nếu `input` đã là `number`, hàm trả nguyên giá trị đó ngay và bỏ qua mọi
+   *   kiểm tra/filter còn lại. Vì vậy `int` không cắt phần thập phân của số đã có,
+   *   và số vượt safe range cũng không bị lỗi.
+   * - `defaultValue` chỉ được dùng khi chuyển `int`/`number` ra `NaN`.
+   * - `type` không thuộc các nhánh chuyên biệt sẽ so sánh `typeof input === type`;
+   *   không khớp thì trả `''`.
+   *
+   * Các kiểu được hỗ trợ:
+   * - `ids`: mảng ID number; loại NaN và loại trùng, giữ thứ tự xuất hiện.
+   * - `stringIds`: như `ids` nhưng chuyển từng ID thành chuỗi.
+   * - `strings`: mảng chuỗi; mỗi phần tử được `stripTags`, loại trùng.
+   * - `dQuoteIds`: mảng ID number, mỗi ID thành chuỗi `%"id"%`.
+   * - `int`: `Number(input)`, kiểm tra safe integer rồi `Math.trunc`.
+   * - `number`: `Number(input)`, giữ nguyên phần thập phân, kiểm tra safe range.
+   * - `decimal`: `Decimal`; mọi ký tự ngoài số và dấu `.` bị loại.
+   * - `stripTags`: bỏ **mọi** thẻ rồi trim. An toàn khi xuất ra dạng text, nhưng
+   *   có thể mất dữ liệu (ví dụ `a < b and c > d` thành `a  d`).
+   * - `html`: escape `& < > " ' \`` (xem `escapeHtml`) — **không thể bypass**, nhưng
+   *   thẻ vô hại cũng thành text. Dùng khi lưu dữ liệu người dùng rồi render HTML.
+   * - `date`: chuỗi ISO hợp lệ thành `yyyy-MM-dd`, ngày sai trả `null`.
+   * - `datetime`: chuỗi ISO hợp lệ thành `yyyy-MM-dd HH:mm:ss`, ngày sai trả `null`.
+   * - `raw`: JSON string được parse; JSON sai hoặc input không phải string được giữ nguyên.
+   * - Ngoài ra có thể dùng tên `typeof`, ví dụ `boolean`, `object`, `string`.
+   *
+   * `date`, `datetime`, `html` và `stripTags` chỉ được áp dụng khi input là string.
+   * Với input không phù hợp, chúng rơi xuống kiểm tra `typeof` và thường trả `''`.
    *
    * @param input Dữ liệu đầu vào
-   * @param type Kiểu filter
-   * @param defaultValue Giá trị fallback
+   * @param type Kiểu filter/chuyển đổi; mặc định `stripTags`
+   * @param defaultValue Fallback khi `int`/`number` không parse được; mặc định `''`
+   * @returns Giá trị đã filter/chuyển kiểu
+   * @throws {Error} `invalid_max_safe_integer` hoặc `invalid_min_safe_integer` khi
+   * input không phải number sẵn có và giá trị chuyển đổi vượt safe range
+   */
+  static filterSafeData(input: unknown, type?: string, defaultValue?: unknown): any;
+  /**
+   * Parse raw input.
+   *
+   * - Input không phải string được trả nguyên trạng.
+   * - String là JSON hợp lệ được parse thành kiểu tương ứng, kể cả null, boolean,
+   *   number, string, array hoặc object.
+   * - JSON không hợp lệ được trả nguyên chuỗi gốc.
+   *
+   * @param input Giá trị cần parse
+   * @returns Giá trị đã parse hoặc input gốc
    */
-  static filterSafeData(input: any, type?: string, defaultValue?: any): any;
-  /** Parse raw JSON input */
   private static parseRawInput;
-  /** Filter HTML tránh XSS */
+  /**
+    /**
+     * Escape HTML — biến mọi thẻ thành văn bản hiển thị.
+     *
+     * > ✅ **Không còn payload nào lọt qua.** Trước đây hàm này dùng regex để xoá
+     * > riêng các thẻ `script`/`style`/`meta`, khiến các vector khác lọt nguyên vẹn
+     * > (đã kiểm chứng): `<img src=x onerror=...>`, `<svg/onload=...>`,
+     * > `<a href="javascript:...">`, `<iframe>`, `<body onload=...>`.
+     * >
+     * > Nay escape `& < > " ' \``, nên mọi thẻ đều thành text — không thể bypass.
+     * > Đổi lại, **thẻ vô hại cũng bị escape**: `<p>Keep</p>` trở thành
+     * > `&lt;p&gt;Keep&lt;/p&gt;`. Nếu cần lưu rich-text, hãy dùng thư viện sanitizer
+     * > chuyên dụng (`sanitize-html`, `DOMPurify`).
+     *
+     * @param input Chuỗi cần escape
+     * @returns Chuỗi đã escape; input không phải string trả `''`
+     */
   private static filterHtml;
-  /** Filter mảng ID number */
+  /**
+   * Chuẩn hóa input thành mảng ID number.
+   *
+   * - Chuỗi JSON array được parse và dùng làm mảng.
+   * - Chuỗi không phải JSON được thử `Number()`; số hợp lệ thành mảng một phần tử.
+   * - Chuỗi không parse được trả `[]`.
+   * - Mọi phần tử được `Number()`, bỏ `NaN`, rồi khử trùng; thứ tự đầu được giữ.
+   * - Input không phải array/string trả `[]`.
+   *
+   * @param input Một ID, danh sách ID hoặc chuỗi JSON
+   * @returns Mảng ID number duy nhất
+   */
   private static filterIds;
-  /** Filter mảng ID string */
+  /**
+   * Lọc mảng ID rồi chuyển từng ID sang chuỗi.
+   *
+   * Chuỗi JSON không phải array hoặc input không hợp lệ trả `[]`; mảng hợp lệ đi
+   * qua `filterIds()` nên vẫn loại `NaN` và trùng trước khi chuyển `String`.
+   *
+   * @param input Một ID, danh sách ID hoặc chuỗi JSON
+   * @returns Mảng ID dạng chuỗi duy nhất
+   */
   private static filterStringIds;
-  /** Filter mảng string */
+  /**
+   * Lọc và khử trùng một mảng giá trị.
+   *
+   * Từng phần tử được xử lý bằng `filterSafeData(..., 'stripTags')`; phần tử số được
+   * giữ nguyên, chuỗi được bỏ thẻ và trim, giá trị khác thường trả `''`. Kết quả
+   * được đưa vào `Set`, vì vậy so sánh trùng dùng semantics của JavaScript.
+   *
+   * @param input Danh sách giá trị
+   * @returns Danh sách đã lọc và khử trùng
+   */
   private static filterStrings;
-  /** Filter ID dạng LIKE "%id%" */
+  /**
+   * Chuyển mảng ID thành từng mẫu dạng `%"id"%`.
+   *
+   * Trước hết ID được ép number, loại `NaN` và trùng giống `filterIds()`; sau đó
+   * mỗi ID được bọc trong hai dấu `%` và một cặp dấu nháy kép.
+   *
+   * @param input Danh sách ID
+   * @returns Danh sách mẫu `%"id"%`
+   */
   private static filterDQuoteIds;
 }
 //#endregion
@@ -565,11 +1545,26 @@ declare class FileUpload {
   constructor(files: {
     [key: string]: FileType[];
   }, uploadType?: string);
+  /**
+   * Nối `subPath` vào `baseDir` và bảo đảm kết quả vẫn nằm bên trong `baseDir`.
+   *
+   * Chặn **path traversal**: nếu không có bước này thì `folders = '../../etc'`
+   * sẽ khiến file được ghi ra ngoài thư mục upload.
+   *
+   * @param baseDir Thư mục gốc (thư mục upload)
+   * @param subPath Đường dẫn tương đối do ứng dụng truyền vào
+   * @returns Đường dẫn tuyệt đối, chắc chắn nằm trong `baseDir`
+   * @throws {Error} `invalid_upload_folder` khi `subPath` thoát ra khỏi `baseDir`
+   */
+  private static resolveInside;
   /**
    * Copy danh sách file từ src sang dist
    * Dùng khi cần nhân bản file đã tồn tại
    */
-  copyFiles(files: any[]): Promise<void>;
+  copyFiles(files: Array<{
+    src: string;
+    dist: string;
+  }>): Promise<void>;
   /**
    * Upload 1 file theo field name
    * @returns đường dẫn file sau upload hoặc false
@@ -585,6 +1580,11 @@ declare class FileUpload {
    * - Tự tạo tên file theo timestamp
    * - Tạo folder nếu chưa tồn tại
    * - Move file từ temp sang thư mục upload
+   *
+   * `folders` và `file.filename` đều được kiểm tra để không thoát khỏi thư mục
+   * upload (path traversal).
+   *
+   * @throws {Error} `invalid_upload_folder` khi `folders` hoặc tên file chứa đường dẫn thoát ra ngoài
    */
   upload(file: FileType, folders?: string): Promise<string | false>;
   /**
@@ -598,6 +1598,8 @@ declare class FileUpload {
   static removeFiles: (pathFiles: string[] | boolean, uploadType?: string) => boolean;
   /**
    * Xóa 1 file theo đường dẫn
+   *
+   * Đường dẫn phải nằm trong thư mục upload, nếu không sẽ bị từ chối.
    */
   static removeFile: (fileName: string | false, uploadType?: string) => boolean;
   /**
@@ -627,28 +1629,190 @@ declare class FileUpload {
 }
 //#endregion
 //#region src/JWTApp.d.ts
+interface JwtUser {
+  id: number;
+  fullname: string;
+}
+interface JwtRequest {
+  ip?: string;
+  headers: Record<string, string | string[] | undefined>;
+}
+interface JwtPayload {
+  iss?: string;
+  aud?: string;
+  sub: number;
+  name: string;
+  ip?: string;
+  us?: string;
+  iat: number;
+  exp: number;
+  expired: number;
+  accessToken: string;
+  [key: string]: unknown;
+}
+/**
+ * Lớp tiện ích xử lý JSON Web Token (JWT) cho ứng dụng.
+ * Hỗ trợ tạo token, xác thực token từ Authorization header hoặc Cookie,
+ * và kiểm tra khóa bảo mật hệ thống.
+ */
 declare class JWTApp {
-  static createToken(user: any, req: any): string;
+  /**
+   * Tạo JWT token cho người dùng dựa trên thông tin IP, User-Agent và cấu hình env.
+   * Biến môi trường sử dụng: `JWT_KEY`, `JWT_AUD`, `JWT_ISS`, `JWT_TIMEOUT` (mặc định 3600 giây).
+   *
+   * @param user Thông tin người dùng (yêu cầu thuộc tính `id`, `fullname`)
+   * @param req Request Fastify/Express để lấy `ip` và `user-agent`
+   * @returns Chuỗi JWT token đã được ký
+   * @throws {Error} `missing_jwt_key` khi chưa cấu hình `JWT_KEY`
+   *
+   * @example
+   * ```ts
+   * const token = JWTApp.createToken({ id: 1, fullname: 'Admin' }, req);
+   * ```
+   */
+  static createToken(user: JwtUser, req: JwtRequest): string;
+  /**
+   * Xác thực JWT token từ request (header Bearer hoặc Cookie).
+   * Kiểm tra tính hợp lệ của token, thời gian hết hạn, và so khớp User-Agent
+   * cùng IP của client.
+   *
+   * Hạn dùng được kiểm tra hai lần: `exp` (giây, do `jsonwebtoken` kiểm tra) và
+   * trường tuỳ chỉnh `expired` (mili-giây) do `createToken()` ghi kèm.
+   *
+   * @param req FastifyRequest (có thể kèm `cookies`)
+   * @param isCookie `true` nếu đọc từ cookie `accessToken`, `false` nếu đọc từ header `Authorization: Bearer <token>`
+   * @returns Payload đã giải mã và xác thực kèm thuộc tính `accessToken`
+   * @throws {Error | ClientError} Khi thiếu `JWT_KEY`, token bị thiếu, không hợp lệ
+   * (sai chữ ký, sai user-agent, sai ip, sai user ID) hoặc đã hết hạn
+   *
+   * @example
+   * ```ts
+   * const userPayload = JWTApp.verifyToken(request);
+   * ```
+   */
   static verifyToken(req: FastifyRequest & {
     cookies?: Record<string, string | undefined>;
-  }, isCookie?: boolean): any;
+  }, isCookie?: boolean): JwtPayload;
+  /**
+   * Kiểm tra Secret Key được truyền vào có khớp với biến môi trường `JWT_SECRET_KEY` hay không.
+   * Thường dùng cho các webhook nội bộ hoặc giao tiếp giữa các service.
+   *
+   * So sánh dùng `safeEqual()` (constant-time) để không bị lộ secret qua
+   * timing attack.
+   *
+   * @param key Chuỗi secret key cần kiểm tra
+   * @throws {Error} Khi biến môi trường `JWT_SECRET_KEY` chưa được thiết lập
+   * @throws {ClientError} Khi khóa không khớp
+   *
+   * @example
+   * ```ts
+   * JWTApp.checkSecretKey(apiKeyHeader);
+   * ```
+   */
   static checkSecretKey(key: string): void;
 }
 //#endregion
 //#region src/Models.d.ts
-type ModelConstructor<T extends BaseModel<any> = BaseModel<any>> = new (pool: Pool) => T;
+/**
+ * Kiểu constructor cho class kế thừa từ BaseModel
+ *
+ * Dùng `AnyBaseModel` làm ràng buộc: `BaseModel<T>` bất biến trong `T` nên ràng
+ * buộc bằng `ModelRow` sẽ loại bỏ mọi model khai báo entity bằng `interface`.
+ * @see {@link AnyBaseModel}
+ */
+type ModelConstructor<T extends AnyBaseModel = AnyBaseModel> = new (pool: Pool) => T;
+/**
+ * Kiểu map các model instance tương ứng với ModelConstructor
+ */
 type Models<T extends Record<string, ModelConstructor>> = { [K in keyof T]: InstanceType<T[K]>; };
+/**
+ * Khởi tạo danh sách instance của các model từ modelMap và connection pool.
+ *
+ * @param modelMap Đối tượng chứa các class model constructor
+ * @param pool MySQL Connection Pool
+ * @returns Đối tượng chứa các instance model tương ứng
+ *
+ * @example
+ * ```ts
+ * const models = createModels({ user: UserModel, product: ProductModel }, pool);
+ * ```
+ */
 declare function createModels<T extends Record<string, ModelConstructor>>(modelMap: T, pool: Pool): Models<T>;
+/**
+ * Khởi tạo singleton container chứa các model toàn ứng dụng.
+ * Nếu đã được khởi tạo trước đó, hàm trả về đối tượng hiện tại mà không khởi tạo lại.
+ *
+ * @param modelMap Đối tượng chứa các class model constructor
+ * @param pool MySQL Connection Pool
+ * @returns Singleton container chứa các instance model
+ *
+ * @example
+ * ```ts
+ * initModels({ user: UserModel, post: PostModel }, pool);
+ * ```
+ */
 declare function initModels<T extends Record<string, ModelConstructor>>(modelMap: T, pool: Pool): Models<T>;
+/**
+ * Lấy singleton container chứa các model đã khởi tạo.
+ *
+ * @template T Kiểu container models mong muốn
+ * @returns Đối tượng các instance model
+ * @throws {Error} Khi models chưa được gọi `initModels()`
+ *
+ * @example
+ * ```ts
+ * const { user, post } = getModels<AppModels>();
+ * ```
+ */
 declare function getModels<T>(): T;
 //#endregion
 //#region src/MySQLSessionStore.d.ts
+type SessionData = Session;
+type SessionCallbackError = Error | null | undefined;
+type SessionResultCallback = (err: SessionCallbackError, session?: SessionData | null) => void;
+type SessionDoneCallback = (err?: SessionCallbackError) => void;
+interface SessionTableRow {
+  data: string;
+}
+/**
+ * Bộ lưu trữ Session MySQL cho @fastify/session.
+ * Tự động tạo hoặc cập nhật session trong bảng `sessions` với thời gian hết hạn 14 ngày.
+ */
 declare class MySQLSessionStore implements SessionStore {
   private pool;
-  constructor(pool: Pool);
-  get(sid: string, cb: (err: any, session?: any | null) => void): Promise<void>;
-  set(sid: string, session: any, cb: (err?: any) => void): Promise<void>;
-  destroy(sid: string, cb: (err?: any) => void): Promise<void>;
+  /**
+   * Số ngày session còn hiệu lực.
+   *
+   * Có thể chỉnh qua biến môi trường `SESSION_TTL_DAYS` (mặc định 14). Giá trị
+   * không hợp lệ sẽ rơi về mặc định.
+   */
+  private readonly ttlDays;
+  /**
+   * Khởi tạo session store với MySQL connection pool.
+   * @param pool MySQL Pool
+   * @param ttlDays Số ngày hết hạn; bỏ trống thì đọc `SESSION_TTL_DAYS` hoặc dùng 14
+   */
+  constructor(pool: Pool, ttlDays?: number);
+  /**
+   * Lấy thông tin session theo session ID (`sid`).
+   * @param sid Mã định danh session
+   * @param cb Callback trả về lỗi hoặc session data (null nếu không tìm thấy)
+   */
+  get(sid: string, cb: SessionResultCallback): Promise<void>;
+  /**
+   * Lưu hoặc cập nhật session data theo session ID (`sid`).
+   * Thời hạn session được gia hạn mỗi lần lưu, mặc định 14 ngày.
+   * @param sid Mã định danh session
+   * @param session Dữ liệu session cần lưu
+   * @param cb Callback hoàn tất
+   */
+  set(sid: string, session: SessionData, cb: SessionDoneCallback): Promise<void>;
+  /**
+   * Xóa session khỏi cơ sở dữ liệu theo session ID (`sid`).
+   * @param sid Mã định danh session cần hủy
+   * @param cb Callback hoàn tất
+   */
+  destroy(sid: string, cb: SessionDoneCallback): Promise<void>;
 }
 //#endregion
 //#region src/Route.d.ts
@@ -664,10 +1828,19 @@ declare class MySQLSessionStore implements SessionStore {
  * @property method     HTTP method (get | post | put | delete...)
  * @property rateLimit  Giới hạn request (optional)
  */
+/**
+ * Controller của route: một class được khởi tạo rồi gọi action theo tên.
+ *
+ * Không yêu cầu `Record<string, ...>` vì một class thông thường không có
+ * implicit index signature, nên ràng buộc đó sẽ khiến `route.addGS(link, MyController, module)`
+ * — đúng như README hướng dẫn — không compile. Việc controller có thật sự có
+ * action tương ứng được kiểm tra lúc chạy ở phía đăng ký route.
+ */
+type RouteController = new (...args: never[]) => object;
 interface RouterType {
   link: string;
   module: string;
-  controller: any;
+  controller: RouteController;
   action: string;
   method?: string;
   rateLimit?: number;
@@ -691,6 +1864,21 @@ interface RouterType {
  * - Khai báo routing tập trung
  * - Auto register route cho Fastify / Express
  */
+interface AddGsOptions {
+  /**
+   * Định nghĩa route param cho `:code` trong `detail/:code`, `edit/:code` và
+   * `delete/:code`.
+   *
+   * Mặc định `':code([0-9]+)'` — chỉ nhận mã dạng số. Truyền giá trị khác khi
+   * mã nghiệp vụ không phải số, ví dụ:
+   * - UUID: `':code([0-9a-fA-F-]{36})'`
+   * - slug: `':code([a-z0-9-]+)'`
+   * - chuỗi tuỳ ý: `':code'`
+   *
+   * @default ':code([0-9]+)'
+   */
+  codeParam?: string;
+}
 declare class Route {
   /** Danh sách route */
   private routes;
@@ -700,7 +1888,7 @@ declare class Route {
    * @param router RouterType
    * @returns method (mặc định: GET)
    */
-  static getMethod(router: any): any;
+  static getMethod(router: Pick<RouterType, 'method'>): string;
   /**
    * Thêm danh sách route với prefix
    *
@@ -726,14 +1914,21 @@ declare class Route {
    * - POST   /copy
    * - POST   /import
    * - GET    /export
-   * - GET    /delete/:code
+   * - POST   /delete/:code
    * - POST   /delete
    *
+   * Mọi route làm thay đổi trạng thái đều dùng `POST`. Route `POST /delete/:code`
+   * là `POST` (không phải `GET`) vì `GET` sẽ khiến thao tác xóa bị kích hoạt
+   * bởi link, thẻ `<img>`, prefetch của trình duyệt — đồng thời `GET` không nằm
+   * trong danh sách method mà `ensureCsrfProtection()` kiểm tra nên sẽ bị bỏ qua
+   * CSRF.
+   *
    * @param link Base URL (vd: /admin/product)
    * @param controller Controller xử lý
    * @param module Tên module
+   * @param options Tùy chọn, xem {@link AddGsOptions} (mặc định `:code` chỉ nhận số)
    */
-  addGS(link: string, controller: any, module: string): void;
+  addGS(link: string, controller: RouteController, module: string, options?: AddGsOptions): void;
   /**
    * Lấy toàn bộ danh sách route
    *
@@ -743,27 +1938,153 @@ declare class Route {
 }
 //#endregion
 //#region src/Utils.d.ts
-declare function sanitizeAuditPayload(value: any, parentKey?: string): any;
-declare function buildAuditLogData(item: any, itemOld: any, ignoreFields?: never[]): {
-  difference: any;
-  item: any;
+type AuditValue = string | number | boolean | null | undefined | AuditValue[] | {
+  [key: string]: AuditValue;
+};
+type SanitizedAuditValue = string | number | boolean | null | undefined | SanitizedAuditValue[] | {
+  [key: string]: SanitizedAuditValue;
+};
+type AuditRecord = Record<string, unknown>;
+/**
+ * Loại bỏ các trường thông tin nhạy cảm (mật khẩu, token, secret, api key...) khỏi payload để ghi audit log an toàn.
+ * Hàm duyệt đệ quy qua các object và mảng lồng nhau.
+ *
+ * @param value Dữ liệu cần làm sạch
+ * @param parentKey Tên key cha (phục vụ đệ quy)
+ * @returns Dữ liệu đã được loại bỏ các field nhạy cảm
+ */
+declare function sanitizeAuditPayload(value: unknown, parentKey?: string): SanitizedAuditValue;
+/**
+ * Tạo dữ liệu phục vụ ghi nhận audit log giữa bản ghi mới và bản ghi cũ.
+ * Tự động loại trừ các trường mặc định (`updatedAt`, `createdAt`, `__v`) cùng các trường chỉ định,
+ * và khử trùng thông tin nhạy cảm khỏi log.
+ *
+ * @param item Bản ghi mới sau khi cập nhật
+ * @param itemOld Bản ghi cũ trước khi cập nhật
+ * @param ignoreFields Danh sách tên các trường cần bỏ qua không tính toán chênh lệch
+ * @returns Đối tượng chứa:
+ *  - `difference`: Chi tiết các trường thay đổi `{ field: { old, new } }`
+ *  - `item`: Bản ghi mới đã khử trùng
+ *
+ * @example
+ * ```ts
+ * const audit = buildAuditLogData(newData, oldData, ['lastActive']);
+ * ```
+ */
+declare function buildAuditLogData(item: AuditRecord | null | undefined, itemOld: AuditRecord | null | undefined, ignoreFields?: string[]): {
+  difference: SanitizedAuditValue;
+  item: SanitizedAuditValue;
 };
-declare function getCorsOriginPolicy(corsOrigins: any, isProduction: boolean | number): any;
+/**
+ * Xác định chính sách nguồn gốc CORS (origin) dựa trên danh sách origins cấu hình và môi trường chạy.
+ *
+ * @param corsOrigins Danh sách allowed origins (mảng hoặc chuỗi)
+ * @param isProduction Cờ xác định môi trường production (boolean hoặc 1/0)
+ * @returns
+ *  - Nếu có cấu hình `corsOrigins`: trả về chính `corsOrigins`
+ *  - Nếu không có: trả về `false` (chặn) trên production, hoặc `true` (cho phép tất cả) trên dev/local
+ */
+declare function getCorsOriginPolicy(corsOrigins: string | string[] | null | undefined, isProduction: boolean | number): string | boolean | string[];
 //#endregion
 //#region src/Validation.d.ts
+type ValidationValue = string | number | boolean | null | undefined | ValidationValue[] | {
+  [key: string]: ValidationValue;
+};
+/** Dữ liệu cần validate; là object phẳng `field -> value`. */
+type ValidationItem = Record<string, ValidationValue>;
+type ValidationRules = Record<string, string>;
+interface ValidationEntry {
+  field: string;
+  value: ValidationValue;
+  rules: string;
+  fieldName: string;
+  /**
+   * Danh sách args dự phòng cho rule không có tham số.
+   * Giữ theo cấu trúc cũ (`filed`) nên thường là `undefined` khi tạo từ `runValidate()`.
+   */
+  filed?: string[];
+}
+/**
+ * Bộ validator dùng rule dạng chuỗi, ví dụ `required|minLen(6)`.
+ *
+ * Quy ước chung:
+ * - `runValidate()` chuẩn hóa `null`/`undefined` của field thành chuỗi rỗng.
+ * - Rule có tham số dùng `tenRule(doiSo1,doiSo2)`; các đối số luôn là chuỗi.
+ * - Rule chạy theo thứ tự trong từng chuỗi; các field được validate tuần tự.
+ *   `skip=true` dừng ngay tại lỗi đầu và trả `false`.
+ * - Nên kết hợp `required` hoặc `requiredId` với các rule regex/định dạng vì
+ *   nhiều rule định dạng coi giá trị rỗng là hợp lệ.
+ *
+ * Validator hoàn toàn thuần: không truy vấn database và không phụ thuộc model.
+ * Tên hiển thị trong thông báo lỗi chính là tên field (`validate`).
+ * Việc kiểm tra trùng lặp phải tự thực hiện bằng query ở tầng nghiệp vụ.
+ *
+ * Lưu ý: phần mô tả ngay trên từng rule mô tả chính xác điều kiện đang được
+ * kiểm tra bởi implementation hiện tại, kể cả các giới hạn của biểu thức chính quy.
+ */
 declare class Validation {
-  private md?;
-  constructor(md?: IBaseModel<any>);
+  /** Danh sách thông báo lỗi của lần validate hiện tại. */
   private errors;
-  runValidate(item: any, vdObject?: Record<string, any>): Promise<void>;
   /**
-   * Start the validation using values and rules passed in data
-   * @param  array  data
-   * @param  bool   skip To skip validations as soon as one of the rules fails+
-   * @throws Error if rule method doesn't exist
-   * @return bool
+   * Validate toàn bộ field theo cấu hình rule.
+   *
+   * Điều kiện xử lý:
+   * - Mỗi lần gọi đều xoá lỗi của lần trước, nên một instance có thể tái
+   *   sử dụng cho nhiều request mà không bị dính lỗi cũ.
+   * - `validate` không có entry: dừng ngay và không ghi lỗi.
+   * - Chỉ các own enumerable field của `validate` được validate.
+   * - `item` không tồn tại vẫn được xử lý; mỗi field nullish được đổi thành `''`.
+   * - Tên hiển thị lấy trực tiếp từ tên field trong `validate`; validator không
+   *   gọi tới model nên không có tên hiển thị tùy chỉnh.
+   * - Sau khi chạy mọi rule, nếu danh sách lỗi không rỗng thì ném một `Error` chứa
+   *   toàn bộ thông báo nối bằng `, `.
+   * - Thông báo lỗi được tra theo `lang` trong từ điển i18n (khóa `validate_<rule>`).
+   *   Ngôn ngữ chưa có bản dịch sẽ dùng thông báo chung `validate_default`.
+   * - Tên rule phải nằm trong allowlist `RULES`; tên từ `Object.prototype`
+   *   (`toString`, `valueOf`, `constructor`...) bị từ chối.
+   *
+   * @param item Dữ liệu cần validate
+   * @param validate Map `field -> rule1|rule2`; rule phải là chuỗi
+   * @param lang Mã ngôn ngữ cho thông báo lỗi (mặc định `'vi'`)
+   * @returns `Promise<void>`
+   * @throws {Error} Khi có ít nhất một rule fail hoặc rule không tồn tại
+   *
+   * @example
+   * ```ts
+   * const rules = { email: 'required|email', age: 'required|rangeNum(18,60)' };
+   *
+   * await validator.runValidate({ email: 'sai', age: 10 }, rules, 'vi');
+   * // throw: "Email không đúng định dạng, age phải nằm trong khoản từ 18 đến 60"
+   *
+   * await validator.runValidate({ email: 'sai', age: 10 }, rules, 'en');
+   * // throw: "Email is not in the correct format, age must be between 18 and 60"
+   * ```
+   */
+  runValidate(item: ValidationItem | null | undefined, validate?: ValidationRules, lang?: string): Promise<void>;
+  /**
+   * Chạy danh sách rule đã chuẩn hóa và ghi lỗi khi rule trả false.
+   *
+   * Điều kiện xử lý:
+   * - `validation` được duyệt tuần tự; mỗi entry cần `rules`, `value` và
+   *   `fieldName` (`filed` được đọc để giữ tương thích nhưng thường là undefined).
+   * - `rules` phải là chuỗi được phân tách bằng `|`; chỉ phần có tham số được
+   *   trim trong `getRuleArgs()`. Tên rule không có tham số không được trim trước khi tra cứu.
+   * - Với rule có tham số, `args` là mảng chuỗi từ `getRuleArgs()`; với rule không
+   *   có tham số, `args` lấy từ `dtVal.filed` (thường `undefined` trong dữ liệu
+   *   do `runValidate()` tạo và được `addError()` xử lý như danh sách rỗng).
+   * - `skip=true` dừng ngay tại rule fail đầu tiên; rule/field sau đó không chạy.
+   * - Mọi rule đều thuần và đồng bộ; không có rule nào truy vấn database.
+   * - Rule không tồn tại hoặc tên rule rỗng sẽ ném lỗi từ `this[method]()`.
+   * - `passed` được trả về nhưng caller `runValidate()` kiểm tra `getErrors()` thay vì
+   *   dùng giá trị này.
+   *
+   * @param validation Danh sách field/value/rules đã chuẩn hóa
+   * @param skip Dừng ngay sau rule fail đầu tiên
+   * @param lang Mã ngôn ngữ cho thông báo lỗi (mặc định `'vi'`)
+   * @returns `false` nếu có ít nhất một rule fail; ngược lại `true`
+   * @throws {Error} Khi không gọi được rule hoặc rule async phát sinh lỗi
    */
-  validate(validation: any, skip?: boolean): Promise<boolean>;
+  validate(validation: ValidationEntry[], skip?: boolean, lang?: string): Promise<boolean>;
   /**
    * Determine if a given rule has arguments, Ex: max(4)
    *
@@ -772,27 +2093,44 @@ declare class Validation {
    */
   private isruleHasArgs;
   /**
-   * get rule name for rules that have args
+   * Tách tên rule khỏi phần tham số trong ngoặc.
    *
-   * @param  string  rule
-   * @return string
+   * `minLen(6)` trả `minLen`; phần trước dấu `(` đầu tiên được giữ nguyên.
+   *
+   * @param rule Chuỗi rule
+   * @returns Tên rule
    */
   private getRuleName;
   /**
-   * get arguments for rules that have args
+   * Kiểm tra `hasRuleArgs()` rồi lấy đối số của rule.
    *
-   * @param  string  rule
-   * @return array
+   * Điều kiện:
+   * - Hàm chỉ được gọi sau `isruleHasArgs(rule) === true`.
+   * - Lấy phần sau dấu `(` đầu tiên; nếu có `)` ở cuối thì cắt đi rồi tách theo
+   *   `,`. Không trim từng đối số, không escape và không parse số.
+   * - `rule()` với phần giữa rỗng trả `['']`; nếu gọi trực tiếp với rule không
+   *   có `(` thì `args` là `undefined` và có thể ném lỗi tại `endsWith`.
+   *
+   * @param rule Chuỗi rule như `minLen(6)` hoặc `rangeNum(1,10)`
+   * @returns Mảng đối số nguyên bản
    */
   private getRuleArgs;
   /**
-   * Add an error
+   * Thêm thông báo cho rule fail.
    *
-   * @param  string  rule
-   * @param  string  placeholder for filed
-   * @param  mixed   value
-   * @param  array   args
+   * Điều kiện:
+   * - `rule` rỗng: không làm gì.
+   * - Có message mặc định: thay `{placeholder}`, `{value}` và `{0}`, `{1}`...
+   *   bằng dữ liệu thực; value không phải string bị thay bằng chuỗi rỗng.
+   *   Giá trị `args` mặc định là `[]`; nếu truyền `null` thì có thể lỗi khi gọi `forEach`.
+   * - Message mặc định là chuỗi rỗng: không ghi lỗi ở đây (rule phải tự xử lý).
+   * - Không có message mặc định: ghi thông báo tổng quát bằng tên field.
    *
+   * @param rule Tên rule không có tham số
+   * @param placeholder Tên field hiển thị
+   * @param value Giá trị đã validate
+   * @param args Tham số rule để điền vào message
+   * @param lang Mã ngôn ngữ dùng để tra thông báo trong từ điển
    */
   private addError;
   /**
@@ -815,144 +2153,370 @@ declare class Validation {
   /** **************    Validations    ************** **/
   /** *********************************************** **/
   /**
-   * Is value not empty?
-   * @param  mixed  value
-   * @return bool
+   * Rule `required`: yêu cầu value khác nullish và chuỗi không rỗng sau trim.
+   *
+   * Mọi giá trị khác nullish đều hợp lệ, kể cả `0`, `false`, `NaN`, mảng/object rỗng;
+   * chỉ chuỗi có `trim() === ''` bị từ chối.
+   *
+   * @param value Giá trị field
+   * @returns `true` khi có giá trị theo điều kiện trên
    */
   private required;
   /**
-   * Is value not empty?
-   * @param  mixed  value
-   * @return bool
+   * Rule `requiredId`: yêu cầu ID khác nullish, chuỗi không rỗng sau trim và
+   * không bằng số `0`.
+   *
+   * `false`, object, mảng và các số khác 0 vẫn hợp lệ; chuỗi `'0'` cũng hợp lệ
+   * vì điều kiện chỉ chặn number `0`.
+   *
+   * @param value Giá trị ID
+   * @returns `true` khi ID đạt điều kiện
    */
   private requiredId;
   /**
-   * min string length
-   * @param  string  str
-   * @param  array  args(min)
-   * @return bool
+   * Rule `minLen`: độ dài chuỗi phải lớn hơn hoặc bằng `parseInt(args[0])`.
+   *
+   * Giá trị được kỳ vọng là string; rule không tự kiểm tra `typeof` và không trim.
+   * `parseInt` không có radix nên có thể đọc tiền tố của chuỗi tham số.
+   *
+   * @param str Chuỗi cần đo
+   * @param args Mảng tham số, `args[0]` là độ dài tối thiểu
+   * @returns `true` khi độ dài đạt yêu cầu
    */
   private minLen;
+  /**
+   * Rule `equalLen`: độ dài chuỗi phải bằng `parseInt(args[0])` chính xác.
+   *
+   * Không trim và không kiểm tra kiểu đầu vào; giá trị được kỳ vọng là string.
+   *
+   * @param str Chuỗi cần đo
+   * @param args Mảng tham số, `args[0]` là độ dài yêu cầu
+   * @returns `true` khi độ dài bằng yêu cầu
+   */
   private equalLen;
   /**
-   * max string length
+   * Rule `maxLen`: độ dài chuỗi phải nhỏ hơn hoặc bằng `parseInt(args[0])`.
    *
-   * @param  string  str
-   * @param  array  args(max)
+   * Không trim và không kiểm tra `typeof`; giá trị được kỳ vọng là string.
    *
-   * @return bool
+   * @param str Chuỗi cần đo
+   * @param args Mảng tham số, `args[0]` là độ dài tối đa
+   * @returns `true` khi độ dài không vượt quá
    */
   private maxLen;
   /**
-   * check if number between given range of numbers
+   * Rule `rangeNum`: value phải nằm trong khoảng đóng từ `args[0]` đến `args[1]`.
    *
-   * @param  int     num
-   * @param  array   args(min,max)
-   * @return bool
+   * Hai bound được đọc bằng `parseInt`; phép so sánh JavaScript có thể coerce
+   * value. Không tự kiểm tra `typeof`, không kiểm tra số nguyên và không trim.
+   *
+   * @param num Giá trị cần kiểm tra
+   * @param args Mảng tham số `[min, max]`
+   * @returns `true` khi `min <= num <= max`
    */
   private rangeNum;
   /**
-   * check if number between given range of numbers
+   * Rule `max`: value phải nhỏ hơn hoặc bằng `Number(args[0])`.
    *
-   * @param  int     num
-   * @param  array   args(min,max)
-   * @return bool
+   * Bound được parse bằng `Number`, không phải `parseInt`; không tự kiểm tra kiểu
+   * value. `Number('abc')` thành `NaN` nên phép so sánh thường fail.
+   *
+   * @param num Giá trị cần kiểm tra
+   * @param args Mảng tham số, `args[0]` là ngưỡng trên
+   * @returns Kết quả phép so sánh `num <= Number(args[0])`
    */
   private max;
+  /**
+   * Rule `min`: value phải lớn hơn hoặc bằng `Number(args[0])`.
+   *
+   * Bound được parse bằng `Number`, không phải `parseInt`; không tự kiểm tra kiểu
+   * value. `Number('abc')` thành `NaN` nên phép so sánh thường fail.
+   *
+   * @param num Giá trị cần kiểm tra
+   * @param args Mảng tham số, `args[0]` là ngưỡng dưới
+   * @returns Kết quả phép so sánh `num >= Number(args[0])`
+   */
   private min;
   /**
-   * check if value is a valid number
+   * Rule `integer`: `parseInt(value)` không phải `NaN`.
    *
-   * @param  string|integer  value
-   * @return bool
+   * Đây không phải kiểm tra số nguyên nghiêm ngặt: `parseInt('12abc')` là 12,
+   * `parseInt('1.9')` là 1, và chuỗi rỗng thường fail. Giá trị falsy không được
+   * guard riêng trong method này.
+   *
+   * @param value Giá trị cần parse
+   * @returns `true` nếu `parseInt(value)` không phải `NaN`
+   */
+  /**
+   * Rule `integer`: giá trị phải là một số nguyên hợp lệ.
+   *
+   * Dùng `Number()` + `Number.isInteger()` thay vì `parseInt()` vì `parseInt`
+   * chỉ đọc **tiền tố** nên `'12abc'` và `'12.5'` đều bị coi là hợp lệ.
+   * Chuỗi rỗng / toàn khoảng trắng bị từ chối vì `Number('')` là `0`.
+   *
+   * @param value Giá trị cần kiểm tra
+   * @returns `true` khi value là số nguyên
    */
   private integer;
   /**
-   * check if value(s) is in a given array
+   * Rule `inArray`: giá trị phải thuộc danh sách tham số của rule.
    *
-   * @param  string|array  value
-   * @param  array         arr
-   * @return bool
+   * - Primitive (chuỗi/số): so sánh membership bằng `includes` trên `String(value)`.
+   * - Object/array: **mọi value bên trong** phải thuộc danh sách; object rỗng pass.
+   * - So sánh luôn là so sánh chuỗi nên `inArray(1,2)` nhận cả `1` và `'1'`.
+   *
+   * Trước đây rule dùng toán tử `in`, mà `in` trên mảng chỉ kiểm tra **index**
+   * (`'a' in ['a']` là `false`) chứ không kiểm tra membership — khiến
+   * `inArray(a)` với giá trị `'a'` luôn thất bại.
+   *
+   * @param value Giá trị hoặc object/array cần kiểm tra
+   * @param arr Danh sách giá trị hợp lệ, lấy từ tham số rule `inArray(a,b,c)`
+   * @returns `true` khi mọi giá trị được kiểm tra đều thuộc `arr`
    */
   private inArray;
+  /**
+   * Rule `inArrayNumber`: kiểm tra value hoặc từng phần tử object/array nằm trong
+   * danh sách số.
+   *
+   * - `arr` được chuyển từng phần tử sang `Number` trước khi so sánh.
+   * - Mảng: kiểm tra từng phần tử. Object thường: kiểm tra từng **value**.
+   * - `null`/`undefined` trả `false` thay vì ném `TypeError` — trước đây
+   *   `typeof null === 'object'` khiến nhánh object được gọi `.every` trên `null`.
+   * - Với primitive: so sánh nghiêm ngặt, nên chuỗi `'1'` không khớp số `1`.
+   *
+   * @param value Giá trị hoặc danh sách cần kiểm tra
+   * @param arr Danh sách giá trị được phép
+   * @returns `true` khi tất cả giá trị được chuyển số nằm trong danh sách
+   */
   private inArrayNumber;
   /**
-   * check if value is contains alphabetic characters and numbers
+   * Rule `alphaNum`: chỉ cho phép chữ ASCII `[a-zA-Z0-9]`, ít nhất một ký tự.
    *
-   * @param  mixed   value
-   * @return bool
+   * Giá trị truthy được `RegExp.test()` ép sang chuỗi theo JavaScript; không có
+   * guard `typeof` riêng. Chuỗi có khoảng trắng, dấu hoặc ký tự Unicode không hợp lệ.
+   *
+   * @param value Giá trị cần kiểm tra
+   * @returns `true` khi value falsy hoặc chỉ gồm chữ/số ASCII
    */
   private alphaNum;
   /**
-   * check if value is contains alphabetic characters and numbers
+   * Rule `number`: `true` khi value là số nằm trong khoảng an toàn.
    *
-   * @param  mixed   value
-   * @return bool
+   * Trước đây rule này **ném** `INVALID_SAFE_NUMBER` khi số vượt khoảng trong
+   * khi 18 rule còn lại đều trả `false`. Hệ quả là `runValidate()` dừng giữa
+   * chừng, các field phía sau không được kiểm tra, và lỗi trả về có dạng khác
+   * hẳn so với lỗi validate thông thường. Nay mọi rule đều tuân theo cùng một
+   * hợp đồng: trả boolean.
+   *
+   * `NaN` giờ bị từ chối (trước đây lọt qua vì mọi phép so sánh với `NaN` đều
+   * cho `false`).
+   *
+   * @param value Giá trị cần kiểm tra
+   * @returns `true` khi value là số hữu hạn trong khoảng `MIN/MAX_SAFE_INTEGER`
    */
   private number;
   /**
-   * check if value is contains alphabetic characters, numbers and spaces
+   * Rule `alphaNumWithSpaces`: chỉ cho phép chữ/số ASCII và khoảng trắng ASCII.
    *
-   * @param  mixed   value
-   * @return bool
+   * Regex là `/^[a-z0-9 ]+$/i`, nên phải có ít nhất một ký tự và chỉ cho phép
+   * khoảng trắng ASCII; space ở đầu/cuối vẫn được phép, còn tab, dấu và ký tự
+   * Unicode không hợp lệ. Value falsy được coi là hợp lệ và trả `true`.
+   *
+   * @param value Giá trị cần kiểm tra
+   * @returns `true` khi value rỗng/falsy hoặc chỉ gồm chữ/số/space ASCII
    */
   private alphaNumWithSpaces;
   /**
-   * check if password has at least
-   * - one lowercase letter
-   * - one uppercase letter
-   * - one number
-   * - one special(non-word) character
+   * Rule `password`: yêu cầu mật khẩu 8-32 ký tự trong regex hiện tại.
+   *
+   * Regex bắt buộc có ít nhất một chữ số, chữ thường, chữ hoa và một ký tự đặc
+   * biệt trong tập `@#!%^&*`; phần ký tự được phép là chữ/số và các ký tự này.
+   * Có `$` ở cuối nên chuỗi dài hơn 32 ký tự hoặc chứa ký tự lạ đều bị từ chối;
+   * value falsy được coi là hợp lệ.
+   *
+   * @param value Mật khẩu cần kiểm tra
+   * @returns `true` khi value falsy hoặc match regex
    */
   private password;
   /**
-   * - Phone VN
-   */
+     * Rule `phoneVn`: regex số điện thoại Việt Nam hiện tại.
+     *
+     * Pattern là `/^[03|05|07|08|09]{2}[0-9]{8}/`: hai ký tự đầu phải thuộc tập ký
+     * tự `0,3,|,5,7,8,9`, sau đó tối thiểu tám chữ số. Pattern không có `$`, nên
+     * chuỗi dài hơn vẫn có thể match; falsy value được trả `true`.
+     *
+    /**
+     * Rule `phoneVn`: số điện thoại di động Việt Nam gồm 10 chữ số.
+     *
+     * Theo quy hoạch số thuê bao của Bộ TT&TT, định dạng số di động là
+     * `03xx xxx xxx`, `05xx xxx xxx`, `07xx xxx xxx`, `08xx xxx xxx`,
+     * `09xx xxx xxx` — tức **chữ số thứ hai** phải thuộc `{3, 5, 7, 8, 9}`
+     * (không có khối `01`, `02`, `04`, `06` cho di động).
+     *
+     * Cố ý **không** giới hạn chữ số thứ ba: quy hoạch không ràng buộc vị trí này
+     * và các đầu số `090` (MobiFone), `091` (VinaPhone) đều đang được sử dụng.
+     * Ép về `[2-9]` sẽ chặn nhầm khách hàng thật.
+     *
+     * Đầu vào được chuẩn hoá trước khi kiểm tra:
+     * - Bỏ khoảng trắng và các dấu phân cách `.`, `-`, `(`, `)`.
+     * - Đưa mã quốc gia `+84` / `84` về dạng nội địa có số `0` ở đầu.
+     * - Bỏ tiền tố quốc tế `00`.
+     * Nhờ vậy `0900 000 000`, `0900-000-000` và `+84 900 000 000` đều hợp lệ.
+     *
+     * Giá trị falsy (`''`, `null`, `undefined`) được coi là hợp lệ — nhất quán với
+     * `email`, `alphaNum`, `password`; nên kết hợp với `required` khi bắt buộc.
+     *
+     * @param value Số điện thoại cần kiểm tra
+     * @returns `true` khi value falsy hoặc là số di động VN hợp lệ
+     */
   private phoneVn;
   /**
-   * check if value is equals to another value(strings)
+   * Rule `equals`: so sánh `String(value)` với `args[0]`.
    *
-   * @param  string  value
-   * @param  array   args(value)
-   * @return bool
+   * Tham số rule luôn là chuỗi nên phải chuẩn hoá về chuỗi để so sánh — trước đây
+   * so sánh nghiêm ngặt khiến số `1` không bằng chuỗi `'1'`, dù `equals(1)` rõ
+   * ràng là muốn so với số `1`.
+   *
+   * @param value Giá trị cần so sánh
+   * @param args Mảng tham số, giá trị đích ở `args[0]`
+   * @returns `true` khi hai bên bằng nhau sau khi chuẩn hoá chuỗi
    */
   private equals;
   /**
-   * check if value is not equal to another value(strings)
+   * Rule `notEqual`: phủ định của {@link Validation.equals}.
    *
-   * @param  string  value
-   * @param  array   args(value)
-   * @return bool
+   * @param value Giá trị cần so sánh
+   * @param args Mảng tham số, giá trị bị cấm ở `args[0]`
+   * @returns `true` khi hai bên khác nhau sau khi chuẩn hoá chuỗi
    */
   private notEqual;
   /**
-   * check if value is a valid email
+   * Tách chuỗi rule theo dấu `|`, **tôn trọng ký tự escape `\|`**.
    *
-   * @param  string  email
-   * @return bool
+   * `|` vừa là dấu phân cách rule vừa là toán tử alternation `(a|b)` trong
+   * regex. Nếu tách thẳng thì `regex(/^(?:x|y)=\d$/)` bị cắt thành hai rule
+   * và hỏng. Vì vậy `\|` được hiểu là dấu `|` literal và dấu `\` bị bỏ đi.
+   *
+   * @param rules Chuỗi rule, ví dụ `required|regex(/^a\|b$/)`
+   * @returns Mỗi phần tử là một tên rule
    */
-  private email;
-  /** *********************************************** **/
-  /** ************  Database Validations  *********** **/
-  /** *********************************************** **/
+  private static splitRules;
   /**
-   * check if a value of a column is unique.
+   * Lấy nguyên văn pattern của rule `regex(...)`.
    *
-   * @param  string  value
-   * @param  array   args(table, column)
-   * @return bool
+   * Cố ý KHÔNG dùng {@link Validation.getRuleArgs} vì hàm đó tách tham số theo
+   * dấu phẩy, trong khi pattern regex rất hay chứa dấu phẩy:
+   * `/a{2,3}/`, `/[a,b]/`, `/^(x,y)$/` — những pattern đó sẽ bị cắt đôi.
+   *
+   * @param rule Chuỗi rule dạng `regex(/pattern/flags)`
+   * @returns Chuỗi pattern, hoặc `''` nếu không trích được
+   */
+  private getRegexPattern;
+  /**
+   * Rule `regex`: kiểm tra giá trị có khớp biểu thức chính quy tuỳ chỉnh hay không.
+   *
+   * - Nhận cả hai dạng có và không có dấu nháy bao:
+   *   `regex(/^[A-Z]{2}\d{6}$/)`, `regex(/^ab+c$/i)`, `regex(^[A-Z]+$)`.
+   * - Dấu `|` bên trong pattern phải viết thành `\|`, vì `|` là dấu phân cách
+   *   rule: `regex(/^(?:x\|y)=1$/)`. Có thể tránh bằng lớp ký tự `[xy]`.
+   * - Cờ `g` và `y` bị bỏ qua: `RegExp.test()` với cờ global có trạng thái
+   *   `lastIndex` nên kết quả sẽ phụ thuộc thứ tự gọi.
+   * - **Pattern không được neo tự động**: `regex(/abc/)` cũng khớp `xxabcxx`.
+   *   Hãy tự viết `^...$` nếu cần khớp trọn vẹn.
+   * - Giá trị falsy trả `true`, đúng như các rule khác — hãy kết hợp `required`.
+   *
+   * ⚠️ Pattern do ứng dụng tự viết trong chuỗi rule, không lấy từ dữ liệu người
+   * dùng. Tuy vậy nên tránh biểu thức có khả năng **catastrophic backtracking**
+   * (ReDoS) như `/(a+)+$/`.
+   *
+   * @param value Giá trị cần kiểm tra
+   * @param args `args[0]` là pattern
+   * @returns `true` khi value falsy hoặc khớp pattern
+   *
+   * @example
+   * ```ts
+   * const rules = { so: 'required|regex(/^0\d{9}$/)' };
+   * await validator.runValidate({ so: '0900000000' }, rules); // ok
+   * await validator.runValidate({ so: 'sai' }, rules);       // throw lỗi
+   * ```
+   */
+  private regex;
+  /**
+   * Rule `email`: kiểm tra định dạng email ASCII.
+   *
+   * - Local part cho phép ký tự đặc biệt hợp lệ của RFC 5322 kể cả `+`
+   *   (ví dụ `ten+the@gmail.com`) và chấp nhận subdomain lồng nhau.
+   * - TLD là **2 chữ cái ASCII trở lên**, không giới hạn 4 ký tự — trước đây
+   *   giới hạn `{2,4}` nên từ chối các TLD dài hợp lệ như `.technology`.
+   * - Không cho phép dấu chấm liên tiếp và không cho phép dấu chấm ở đầu/cuối
+   *   local part.
+   * - Không hỗ trợ email quốc tế viết bằng ký tự Unicode (IDN) và không trim.
+   *   `FastRequest.filterSafeData(..., 'stripTags')` đã trim sẵn theo mặc
+   *   định nên đường thông thường không bị vấn đề khoảng trắng.
+   *
+   * @param email Giá trị cần kiểm tra
+   * @returns `true` khi email falsy hoặc khớp định dạng
    */
-  private unique;
+  private email;
   /** *********************************************** **/
   /** ************   Default Messages     *********** **/
   /** *********************************************** **/
+  /**
+   * Tra thông báo mặc định của một rule theo ngôn ngữ.
+   *
+   * Khóa trong từ điển có dạng `validate_<tênRule>` (xem `src/lang/vi.ts`, `src/lang/en.ts`).
+   * Ứng dụng có thể ghi đè hoặc bổ sung ngôn ngữ mới bằng `initI18n()`.
+   *
+   * @param rule Tên rule, ví dụ `minLen`
+   * @param lang Mã ngôn ngữ (mặc định `'vi'`)
+   * @returns Chuỗi thông báo, hoặc `null` nếu rule chưa có bản dịch
+   */
   private static defaultMessages;
+  /**
+   * Tra bản dịch cho `key` theo ngôn ngữ, có lùi về tiếng Việt.
+   *
+   * `t()` trả về chính `key` khi không tìm thấy, nên hàm này dùng giá trị đó
+   * làm tín hiệu "thiếu bản dịch" và thử lại với `'vi'` trước khi kết luận.
+   *
+   * @param key Khoá trong từ điển, ví dụ `validate_email`
+   * @param lang Mã ngôn ngữ
+   * @returns Chuỗi đã dịch, hoặc chính `key` nếu không có ở ngôn ngữ nào
+   */
+  private static translate;
 }
 //#endregion
 //#region src/I18n.d.ts
 type LanguageDictionary = Record<string, string>;
 type I18nDictionaries = Record<string, LanguageDictionary>;
+/**
+ * Khởi tạo hoặc cập nhật từ điển đa ngôn ngữ (i18n).
+ * Hỗ trợ ghi đè các từ khóa mặc định (vi, en) hoặc bổ sung ngôn ngữ mới.
+ *
+ * @param data Đối tượng chứa các từ điển ngôn ngữ cần khởi tạo/bổ sung
+ *
+ * @example
+ * ```ts
+ * initI18n({
+ *   vi: { welcome: 'Xin chào' },
+ *   en: { welcome: 'Welcome' },
+ *   ja: { welcome: 'いらっしゃいませ' }
+ * });
+ * ```
+ */
 declare function initI18n(data: I18nDictionaries): void;
+/**
+ * Dịch một khóa ngôn ngữ theo mã ngôn ngữ tương ứng.
+ * Nếu không tìm thấy khóa trong từ điển, hàm trả về chính khóa đó.
+ *
+ * @param key Khóa cần dịch (vd: 'invalid_403')
+ * @param lang Mã ngôn ngữ (mặc định: 'vi')
+ * @returns Chuỗi bản dịch tương ứng hoặc chính key nếu chưa được định nghĩa
+ *
+ * @example
+ * ```ts
+ * const msg = t('invalid_403', 'vi'); // 'Truy cập không được phép'
+ * ```
+ */
 declare function t(key: string, lang?: string): string;
 //#endregion
 //#region src/HMAC.d.ts
@@ -975,7 +2539,7 @@ declare function t(key: string, lang?: string): string;
  * const signature = createSignature(data);
  * ```
  */
-declare function createSignature(data: Record<string, any>): string;
+declare function createSignature(data: Record<string, unknown>): string;
 /**
  * Creates an HMAC-SHA256 signature for the given data using the Web Crypto API.
  *
@@ -998,13 +2562,23 @@ declare function createSignature(data: Record<string, any>): string;
  * const signature = await createHmac(data, secret);
  * ```
  */
-declare function createHmac(data: Record<string, any>, secret: string): Promise<string>;
+declare function createHmac(data: Record<string, unknown>, secret: string): Promise<string>;
 //#endregion
 //#region src/Error.d.ts
+/**
+ * Lỗi phía client (Bad Request hoặc lỗi tương tự)
+ * Dùng để phân biệt lỗi do người dùng gửi lên với lỗi hệ thống 500
+ */
 declare class ClientError extends Error {
   readonly statusCode: number;
   readonly code?: string | undefined;
+  /**
+   * Khởi tạo lỗi ClientError
+   * @param message Thông điệp lỗi
+   * @param statusCode Mã trạng thái HTTP (mặc định: 400)
+   * @param code Mã lỗi tùy chọn phục vụ định danh lỗi (vd: invalid_user)
+   */
   constructor(message: string, statusCode?: number, code?: string | undefined);
 }
 //#endregion
-export { BaseModel, ClientError, FastRequest, FileUpload, IBaseModel, JWTApp, JoinType, ModelConstructor, Models, ModifiedType, MySQLSessionStore, PaginationResult, Route, RouterType, Validation, buildAuditLogData, callFetchApi, checkPassword, createHmac, createModels, createSignature, decimalNumber, ensureCsrfProtection, formatDate, generateKeywords, getActiveStatus, getArrColumn, getArrOnlyInFirst, getCorsOriginPolicy, getCsrfTokenFromRequest, getDaysInMonth, getDiffArr, getLangs, getModels, getMonthRange, getPublishStatus, getTrueFlaseStatus, getValue, initI18n, initModels, isStateChangingMethod, isSubArr, makePassword, parseDate, randomText, removeVietnameseTones, sanitizeAuditPayload, slugify, stringToJson, sumArrCol, sumArrColumn, t, toMySQLDateNowVN, toRoman };
+export { AddGsOptions, AnyBaseModel, AnyIBaseModel, AuditRecord, AuditValue, BaseModel, ClientError, CsrfProtectionOptions, CsrfProtectionResult, CsrfRequest, CsrfSession, FastRequest, FileUpload, Filter, FilterType, FilterValue, IBaseModel, JWTApp, JoinType, JwtPayload, JwtRequest, JwtUser, LooseRecord, LooseValue, ModelConstructor, ModelEntity, ModelRow, Models, ModifiedType, MySQLSessionStore, PaginationResult, QueryResult, QueryRows, RawQueryResult, RequestBody, RequestValue, Route, RouteController, RouterType, SanitizedAuditValue, SaveResult, SessionCallbackError, SessionData, SessionDoneCallback, SessionResultCallback, SessionTableRow, SqlJoinCondition, SqlJoinOperator, SqlParam, SqlSelectField, SqlSelectInput, Validation, ValidationEntry, ValidationItem, ValidationRules, ValidationValue, assertJoinType, assertOrderDirection, buildAuditLogData, buildJoinCondition, buildJoinTable, buildSelectList, callFetchApi, checkPassword, createHmac, createModels, createSignature, decimalNumber, ensureCsrfProtection, escapeColumnReference, escapeHtml, escapeIdentifier, escapeQualifiedName, formatDate, generateKeywords, getActiveStatus, getArrColumn, getArrOnlyInFirst, getCorsOriginPolicy, getCsrfTokenFromRequest, getDaysInMonth, getDiffArr, getLangs, getModels, getMonthRange, getPublishStatus, getTrueFlaseStatus, getValue, initI18n, initModels, isStateChangingMethod, isSubArr, makePassword, parseDate, randomText, removeVietnameseTones, safeEqual, sanitizeAuditPayload, slugify, stringToJson, sumArrCol, sumArrColumn, t, toError, toMySQLDateNowVN, toRoman };