blackcat.js-database 1.0.0-test → 1.0.1

package/dist/index.d.ts

@@ -1,751 +1,1394 @@
 /**
- * Represents the base driver interface for database operations.
+ * Interface định nghĩa contract cho các storage driver
+ * được sử dụng bởi class `Database`.
+ * @hidden
+ *
+ * ⚠️ Đây **không phải database chính**.
+ * Interface này chỉ dùng để xây dựng **các driver lưu trữ phụ trợ**
+ * như:
+ *
+ * - `JSONDriver`
+ * - `MemoryDriver`
+ * - `SQLiteDriver`
+ *
+ * Các driver này chỉ chịu trách nhiệm:
+ *
+ * - Lưu trữ toàn bộ dữ liệu database
+ * - Trả về dữ liệu database khi được yêu cầu
+ *
+ * Mọi logic xử lý dữ liệu như:
+ *
+ * - parse key path (`a.b.c`)
+ * - validation
+ * - query/filter/map
+ * - update dữ liệu
+ *
+ * đều được thực hiện trong class `Database`.
  */
-interface BaseDriver {
-    get<T = any>(key: string): Promise<T | null>;
-    set<T = any>(key: string, value: T): Promise<T>;
-    delete(key?: any): Promise<boolean>;
-    all(): Promise<Record<string, any>>;
+interface DatabaseDriver {
+    /**
+     * Lấy toàn bộ dữ liệu database từ storage.
+     *
+     * Method này phải trả về **toàn bộ object database**.
+     *
+     * @template T Kiểu dữ liệu database.
+     * @returns Promise chứa toàn bộ dữ liệu database.
+     */
+    all<T = any>(): Promise<T>;
+    /**
+     * Ghi toàn bộ dữ liệu database vào storage.
+     *
+     * ⚠️ Method này **không xử lý key path**.
+     * Object database đã được cập nhật trước bởi class `Database`.
+     *
+     * @param keys Placeholder dùng để tương thích với API của `Database`.
+     * Driver có thể bỏ qua tham số này nếu không cần thiết.
+     *
+     * @param data Toàn bộ object database sau khi đã được cập nhật.
+     *
+     * @template T Kiểu dữ liệu database.
+     * @returns Promise chứa dữ liệu đã được ghi.
+     */
+    set<T = any>(data: T): Promise<T>;
+    /**
+     * Xóa toàn bộ dữ liệu database khỏi storage.
+     *
+     * Thường được sử dụng bởi `Database.deleteAll()`.
+     *
+     * @returns `true` nếu thao tác thành công.
+     */
+    delete(): Promise<boolean>;
 }
 /**
- * Represents the configuration object of the database instance.
+ * Cấu hình khởi tạo cho một instance của {@link Database}.
+ * @hidden
+ *
+ * Interface này xác định các tùy chọn cần thiết để thiết lập database,
+ * bao gồm driver lưu trữ và các tùy chọn hành vi bổ sung.
+ *
+ * @example
+ * const db = new Database({
+ *   driver: new MemoryDriver(),
+ *   debug: true
+ * });
  */
 interface DatabaseConfiguration {
-    driver: BaseDriver;
+    /**
+     * Driver dùng để đọc/ghi dữ liệu của database.
+     *
+     * Driver chịu trách nhiệm xử lý storage backend
+     * (ví dụ: memory, file, json, mongo, redis...).
+     */
+    driver: DatabaseDriver;
+    /**
+     * Bật chế độ debug.
+     *
+     * Khi `true`, database có thể log thêm thông tin về
+     * các thao tác đọc/ghi hoặc lỗi để hỗ trợ debug.
+     *
+     * @defaultValue false
+     */
     debug?: boolean;
 }
 /**
- * Represents the nullish type (`T` or `null`) and excludes `undefined` from it.
+ * Đại diện cho một giá trị có thể là `T` hoặc `null`.
+ * @hidden
+ *
+ * Utility type này loại bỏ `undefined` khỏi union để đảm bảo
+ * giá trị chỉ có thể là kiểu `T` hoặc `null`.
  *
- * Type parameters:
+ * Điều này hữu ích khi một API có thể không tìm thấy kết quả,
+ * nhưng vẫn muốn tránh việc trả về `undefined`.
  *
- * - `T` (`any`) - The type to make nullish.
+ * @typeParam T - Kiểu dữ liệu gốc.
  *
- * @template T - The type to make nullish.
+ * @example
+ * type User = { id: number };
+ *
+ * const user: Maybe<User> = { id: 1 }; // hợp lệ
+ * const noUser: Maybe<User> = null; // hợp lệ
+ * const invalid: Maybe<User> = undefined; // lỗi
  */
 type Maybe<T> = Exclude<T | null, undefined>;
 /**
- * Conditional type that returns the type based on the condition type result.
  *
- * Type parameters:
+ */
+type ArrayElement<T> = T extends (infer U)[] ? U : T;
+/**
+ * Utility type điều kiện dùng để trả về một kiểu dữ liệu
+ * dựa trên giá trị boolean của điều kiện.
+ * @hidden
+ *
+ * Nếu `T` là `true` thì kiểu trả về sẽ là `IfTrue`.
+ * Nếu `T` là `false` thì kiểu trả về sẽ là `IfFalse`.
+ *
+ * Thường được sử dụng trong các generic type phức tạp
+ * để lựa chọn kiểu dữ liệu tại thời điểm compile.
  *
- * - `T` (`boolean`) - The condition to return a boolean value.
- * - `IfTrue` (`any`) - The type to be returned if the condition type `T` is `true`.
- * - `IfFalse` (`null`, optional) - The type to be returned if the condition type `T` is `false`.
+ * @typeParam T - Điều kiện kiểu boolean.
+ * @typeParam IfTrue - Kiểu dữ liệu trả về khi `T` là `true`.
+ * @typeParam IfFalse - Kiểu dữ liệu trả về khi `T` là `false`. Mặc định là `null`.
  *
- * @template T - The condition to return a boolean value.
- * @template IfTrue - The type to be returned if the condition type `T` is `true`.
- * @template IfFalse - The type to be returned if the condition type `T` is `false`.
+ * @example
+ * type A = If<true, string, number>;
+ * // Kết quả: string
+ *
+ * @example
+ * type B = If<false, string, number>;
+ * // Kết quả: number
+ *
+ * @example
+ * // IfFalse mặc định là null
+ * type C = If<false, string>;
+ * // Kết quả: null
  */
 type If<T extends boolean, IfTrue, IfFalse = null> = T extends true ? IfTrue : IfFalse;
 /**
- * Determines if the specified type is object and returns the checking result as boolean.
+ * Kiểm tra xem một kiểu dữ liệu có phải là **object thuần** hay không.
+ * @hidden
  *
- * Type parameters:
+ * Type này sẽ trả về `true` nếu `T` là object dạng `Record`
+ * và **không phải** là:
  *
- * - `T` (`any`) - The type to check.
+ * - `null`
+ * - `undefined`
+ * - `Array`
  *
- * @template T - The type to check.
+ * Nếu `T` thuộc các trường hợp trên thì kết quả sẽ là `false`.
+ *
+ * Utility type này thường được dùng trong các generic phức tạp
+ * để xác định liệu một kiểu dữ liệu có thể được xử lý như object hay không.
+ *
+ * @typeParam T - Kiểu dữ liệu cần kiểm tra.
+ *
+ * @example
+ * type A = IsObject<{ name: string }>;
+ * // Kết quả: true
+ *
+ * @example
+ * type B = IsObject<string>;
+ * // Kết quả: false
+ *
+ * @example
+ * type C = IsObject<string[]>;
+ * // Kết quả: false
+ *
+ * @example
+ * type D = IsObject<null>;
+ * // Kết quả: false
  */
 type IsObject<T> = T extends null ? false : T extends undefined ? false : T extends any[] ? false : T extends Record<any, any> ? true : false;
 /**
- * Represents a type that works as an array of specified type or `...spread` of specified type.
+ * Đại diện cho kiểu dữ liệu có thể là **mảng của `T`**
+ * hoặc **một tuple chứa mảng `T`**.
+ * @hidden
+ *
+ * Utility type này thường được sử dụng để hỗ trợ các API
+ * chấp nhận cả hai cách truyền tham số:
  *
- * Type parameters:
+ * - truyền nhiều giá trị dạng `...spread`
+ * - truyền một mảng các giá trị
  *
- * - `T` (`any`) - The type to convert into rest-or-array type.
+ * @typeParam T - Kiểu phần tử của mảng.
  *
- * @template T - The type to convert into rest-or-array type.
+ * @example
+ * type A = RestOrArray<number>;
+ * // number[] | [number[]]
+ *
+ * @example
+ * function example(...values: RestOrArray<number>) {}
+ *
+ * example(1, 2, 3);       // hợp lệ
+ * example([1, 2, 3]);     // hợp lệ
  */
 type RestOrArray<T> = T[] | [T[]];
 /**
- * From the type `A`, extracts the type `T` from the `Array<T>` type, or returns `A` if not array type was specified.
+ * Trích xuất kiểu phần tử từ một kiểu mảng.
+ * @hidden
+ *
+ * Nếu `A` là kiểu `Array<T>` thì kết quả sẽ là `T`.
+ * Nếu `A` không phải là mảng thì kết quả sẽ giữ nguyên kiểu `A`.
+ *
+ * Utility type này thường được dùng để lấy kiểu của phần tử
+ * bên trong mảng khi làm việc với các generic phức tạp.
  *
- * Type parameters:
+ * @typeParam A - Kiểu dữ liệu cần kiểm tra và trích xuất.
  *
- * - `A` (`any`) - The array type to extract the type from.
+ * @example
+ * type A = ExtractFromArray<number[]>;
+ * // Kết quả: number
+ *
+ * @example
+ * type B = ExtractFromArray<string[]>;
+ * // Kết quả: string
+ *
+ * @example
+ * type C = ExtractFromArray<boolean>;
+ * // Kết quả: boolean
  *
- * @template A - The array type to extract the type from.
+ * @example
+ * type D = ExtractFromArray<{ id: number }[]>;
+ * // Kết quả: { id: number }
  */
 type ExtractFromArray<A> = A extends Array<infer T> ? T : A;
 /**
- * Represents a `predicate` callback function from array methods such as `Array.map()`, `Array.find()`, etc.
+ * Đại diện cho hàm callback dùng để truy vấn hoặc xử lý
+ * các phần tử trong một mảng.
+ * @hidden
+ *
+ * Type này thường được sử dụng trong các method giống
+ * các phương thức của `Array` như:
+ *
+ * - `map`
+ * - `find`
+ * - `filter`
+ * - `some`
+ * - `every`
+ * - `findIndex`
  *
- * Type parameters:
+ * @typeParam T - Kiểu dữ liệu của từng phần tử trong mảng.
+ * @typeParam R - Kiểu dữ liệu trả về của hàm callback. Mặc định là `any`.
  *
- * - `T` (`any`) - The type of the item in the array.
- * - `R` (`any`, optional) - The return type of the function.
+ * @param item - Phần tử hiện tại đang được xử lý.
+ * @param index - Vị trí của phần tử trong mảng.
+ * @param values - Toàn bộ mảng giá trị đang được duyệt.
+ *
+ * @returns Giá trị trả về của callback.
+ *
+ * @example
+ * const result = await db.find((user) => user.id === 1);
  *
- * @template T - The type of the item in the array.
- * @template R - The return type of the function.
+ * @example
+ * const names = await db.map((user) => user.name);
+ *
+ * @example
+ * const admins = await db.filter((user) => user.role === "admin");
  */
 type QueryFunction<T, R = any> = (item: T, index: number, values: T[]) => R;
 /**
- * Determines if the specified type is `any` and returns the checking result as boolean.
+ * Kiểm tra xem một kiểu dữ liệu có phải là `any` hay không.
+ * @hidden
  *
- * Type parameters:
+ * Type này sử dụng kỹ thuật đặc biệt của TypeScript
+ * để phát hiện kiểu `any`. Nếu `T` là `any` thì kết quả
+ * sẽ là `true`, ngược lại sẽ là `false`.
  *
- * - `T` (`any`) - The type to check.
+ * @typeParam T - Kiểu dữ liệu cần kiểm tra.
+ *
+ * @example
+ * type A = IsAny<any>;
+ * // Kết quả: true
  *
- * @template T - The type to check.
+ * @example
+ * type B = IsAny<string>;
+ * // Kết quả: false
+ *
+ * @example
+ * type C = IsAny<unknown>;
+ * // Kết quả: false
  */
 type IsAny<T> = 0 extends (1 & T) ? true : false;
 /**
- * Makes the string union type autocompletable with a `string` type.
+ * Tạo kiểu `string` hỗ trợ **autocomplete từ union string**
+ * nhưng vẫn cho phép nhập bất kỳ chuỗi nào.
+ * @hidden
+ *
+ * Type này thường dùng khi muốn:
+ *
+ * - IDE gợi ý các giá trị có sẵn
+ * - nhưng vẫn cho phép người dùng nhập string tùy ý
  *
- * Type parameters:
+ * @typeParam S - Union các chuỗi được dùng để autocomplete.
  *
- * - `S` (`string`) - The autocompletable union string type to make compatible with a `string` type.
+ * @example
+ * type Status = AutocompletableString<"online" | "offline" | "idle">;
  *
- * @template S - The autocompletable union string type to make compatible with a `string` type.
+ * const a: Status = "online";  // IDE autocomplete
+ * const b: Status = "offline"; // IDE autocomplete
+ * const c: Status = "custom";  // vẫn hợp lệ
  */
 type AutocompletableString<S extends string> = S | (string & {});
 /**
- * Extracts the first key from the specified object path.
- * (for example, in key `member.user.id`, the first key will be `member`)
+ * Trích xuất **key đầu tiên** từ một object path dạng chuỗi.
+ * @hidden
+ *
+ * Ví dụ với path `"member.user.id"` thì key đầu tiên sẽ là `"member"`.
  *
- * Type parameters:
+ * Type này thường được dùng để xác định **object cấp cao nhất**
+ * khi làm việc với các path dạng `dot notation`.
  *
- * - `TKey` (`ObjectPath<string, any>`) - The object path to extract the key from.
+ * @typeParam TKey - Object path cần trích xuất key đầu tiên.
  *
- * @template TKey - The object path to extract the key from.
+ * @example
+ * type A = FirstObjectKey<"user.profile.name">;
+ * // Kết quả: "user"
+ *
+ * @example
+ * type B = FirstObjectKey<"settings">;
+ * // Kết quả: "settings"
  */
 type FirstObjectKey<TKey extends ObjectPath<string, any>> = TKey extends `${infer Key}.${infer _Rest}` ? Key : TKey extends string ? TKey : never;
 /**
- * Represents a path to a nested property in an object.
+ * Đại diện cho **đường dẫn (path)** tới một thuộc tính trong object,
+ * hỗ trợ truy cập các property lồng nhau bằng `dot notation`.
+ * @hidden
  *
- * Type parameters:
+ * Type này được dùng để tạo **autocomplete path** trong IDE.
  *
- * - `T` (`any`) - The object to get the path from.
- * - `TKey` (`keyof T`, defaults to `keyof T`) - The key of the object to get the path from.
+ * @typeParam T - Object cần tạo path.
+ * @typeParam TKey - Key của object (mặc định là `keyof T`).
  *
- * @template T - The object to get the path from.
- * @template TKey - The key of the object to get the path from.
+ * @example
+ * type User = {
+ *   id: number;
+ *   profile: {
+ *     name: string;
+ *     age: number;
+ *   };
+ * };
+ *
+ * type Paths = ObjectPath<User>;
+ *
+ * // Kết quả:
+ * // "id"
+ * // "profile"
+ * // "profile.name"
+ * // "profile.age"
+ *
+ * @example
+ * type Example = {
+ *   user: {
+ *     profile: {
+ *       name: string;
+ *     };
+ *   };
+ * };
+ *
+ * type Paths = ObjectPath<Example>;
+ * // "user"
+ * // "user.profile"
+ * // "user.profile.name"
  */
 type ObjectPath<T, TKey extends keyof T = keyof T> = IsAny<T> extends true ? string : T extends string | number | boolean | symbol ? string : T extends Array<any> ? TKey & string : TKey extends string ? T[TKey] extends Array<any> ? TKey : T[TKey] extends Record<string, any> ? `${TKey}` | `${TKey}.${ObjectPath<T[TKey]>}` : TKey : never;
 /**
- * Extracts the value from the specified object path.
+ * Trích xuất kiểu dữ liệu của giá trị tại một object path.
+ * @hidden
  *
- * Type parameters:
+ * Type này cho phép suy ra kiểu của thuộc tính dựa trên
+ * đường dẫn dạng `dot notation`.
  *
- * - `T` (`any`) - The object to extract the value from.
- * - `P` (`ObjectPath<T>` or `AutocompletableString<ObjectPath<T>>`) - The object path to extract the value from.
+ * @typeParam T - Object nguồn.
+ * @typeParam P - Object path cần lấy giá trị.
+ *
+ * @example
+ * type User = {
+ *   profile: {
+ *     name: string;
+ *     age: number;
+ *   };
+ * };
+ *
+ * type A = ObjectValue<User, "profile.name">;
+ * // Kết quả: string
+ *
+ * @example
+ * type B = ObjectValue<User, "profile.age">;
+ * // Kết quả: number
  *
- * @template T - The object to extract the value from.
- * @template P - The object path to extract the value from.
+ * @example
+ * type C = ObjectValue<User, "profile">;
+ * // Kết quả: { name: string; age: number }
  */
 type ObjectValue<T, P extends ObjectPath<T> | AutocompletableString<ObjectPath<T>>> = T extends AutocompletableString<P> | string | number | boolean | symbol ? T : P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? Rest extends ObjectPath<T[Key]> ? ObjectValue<T[Key], Rest> : null : never : P extends keyof T ? T[P] : T;
 
 /**
- * Database class.
- *
- * Type parameters:
- *
- * - `V` (`any`) - The type of the values in the database.
+ * Class Database cung cấp API thao tác dữ liệu dạng key-path
+ * trên nhiều loại storage khác nhau thông qua `DatabaseDriver`.
  *
- * @template V (`any`) - The type of the values in the database.
+ * Đây là **lớp database chính (logic layer)** của hệ thống.
  *
- * @example
+ * Class này chịu trách nhiệm:
+ * - parse key path (`user.profile.name`)
+ * - validate dữ liệu
+ * - thao tác object
+ * - query dữ liệu (find, filter, map...)
  *
- * // JSON
- * import { Database, JSONDriver } from "blackcat-database";
+ * Việc lưu trữ dữ liệu thực tế sẽ được thực hiện bởi các **driver phụ trợ**
+ * như:
  *
- * const database = new Database({
- *    driver: new JSONDriver({ filePath: "./database.json", minifyJSON: false }),
- * });
+ * - `JSONDriver`
+ * - `MemoryDriver`
+ * - `SQLiteDriver`
+ * - `MongoDriver`
  *
+ * Các driver này chỉ chịu trách nhiệm:
+ * - đọc toàn bộ dữ liệu database
+ * - ghi toàn bộ dữ liệu database
  *
+ * @template V Kiểu dữ liệu tổng thể của database.
  */
 declare class Database<V = any> {
     /**
-     * The low-level database driver handling basic operations.
+     * Storage driver được sử dụng để đọc và ghi dữ liệu database.
+     *
+     * Driver phải implement interface `DatabaseDriver`.
+     *
+     * Ví dụ:
+     * ```ts
+     * const db = new Database({
+     *   driver: new JSONDriver({ filePath: "./database.json" }),
+     * })
+     * ```
      */
-    driver: BaseDriver;
-    constructor(options: DatabaseConfiguration);
+    driver: DatabaseDriver;
     /**
-     * Gets all the database contents from the cache.
+     * Khởi tạo Database instance.
      *
-     * Type parameters:
+     * @param options Cấu hình database.
+     * @param options.driver Driver lưu trữ dữ liệu.
      *
-     * - `T` (`object`, defaults to `Record<string, any>`) - The type of object of all the database object to be returned.
+     * @example
+     * ```ts
+     * const db = new Database({
+     *   driver: new JSONDriver({ filePath: "./database.json" }),
+     * })
+     * ```
+     *
+     * Ví dụ với MongoDB:
+     *
+     * ```ts
+     * const db = new Database({
+     *   driver: new MongoDriver({
+     *     uri: "mongodb://localhost:27017",
+     *     databaseName: "mydb"
+     *   })
+     * });
+     * ```
+     */
+    constructor(options: DatabaseConfiguration);
+    /**
+     * Lấy toàn bộ dữ liệu từ database thông qua driver.
      *
-     * @returns {T} Cached database contents.
+     * @template T Kiểu dữ liệu object database trả về.
      *
-     * @template T (object, defaults to `Record<string, any>`) -
-     * The type of object of all the database object to be returned.
+     * @returns Promise chứa toàn bộ dữ liệu database.
      *
      * @example
-     * const databaseContents = await database.all();
-     * console.log(databaseContents); // -> { ... (the object of all the data stored in database) }
+     * ```ts
+     * const data = await db.all();
+     * console.log(data.users);
+     * ```
      */
     all<T extends Record<string, any> = Record<string, any>>(): Promise<T>;
     /**
-     * Retrieves a value from database by a key.
+     * Lấy giá trị từ database theo key-path.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {Maybe<ObjectValue<V, P>>} The value of the target in database.
+     * Key có thể là chuỗi dạng path:
      *
-     * @example
-     * const simpleValue = await database.get("simpleValue");
-     * console.log(simpleValue); // -> 123
+     * ```
+     * user.profile.name
+     * economy.users.123.balance
+     * ```
+     *
+     * Nếu không truyền `key`, method sẽ trả về **toàn bộ database**.
+     *
+     * @template {AutocompletableString<ObjectPath<V>>} P Key path trong database.
+     *
+     * @param {AutocompletableString<P>} key Đường dẫn dữ liệu cần lấy.
      *
-     * const databaseObjectPropertyAccessed = await database.get("youCanAlso.accessDatabaseObjectProperties.likeThat");
-     * console.log(databaseObjectPropertyAccessed); // -> "hello world!"
+     * @returns Giá trị tại key hoặc `null` nếu không tồn tại.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    simpleValue: 123,
-     * //    youCanAlso: {
-     * //        accessDatabaseObjectProperties: {
-     * //            likeThat: "hello world!"
-     * //        }
-     * //    }
-     * // }
+     * @example
+     * ```ts
+     * const name = await db.get("user.profile.name");
+     * ```
+     *
+     * @example
+     * ```ts
+     * const all = await db.get();
+     * ```
      */
     get<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>> | V>;
     /**
-     * Retrieves a value from database by a key.
+     * Tìm và trả về một bản ghi đầu tiên khớp với điều kiện trong database.
      *
-     * - This method is an alias for {@link Database.get()} method.
+     * Hàm này có hai cách sử dụng:
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {Maybe<ObjectValue<V, P>>} The value from database.
+     * 1. **Chỉ truyền `key`**
+     *    → Trả về toàn bộ dữ liệu của key (tương tự `get()`).
      *
-     * @example
-     * const simpleValue = await database.fetch("simpleValue");
-     * console.log(simpleValue); // -> 123
+     * 2. **Truyền `key` và `query`**
+     *    → Tìm phần tử đầu tiên trong mảng dữ liệu của key khớp với điều kiện.
+     *
+     * @template V - Kiểu dữ liệu của database.
+     * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
      *
-     * // You can use the dot notation to access the database object properties:
-     * const playerInventory = await database.fetch("player.inventory");
-     * console.log(playerInventory); // -> []
+     * @param key - Key hoặc đường dẫn đến dữ liệu cần truy vấn.
+     * @param query - Đối tượng điều kiện để tìm bản ghi phù hợp.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    simpleValue: 123,
-     * //    player: {
-     * //        inventory: []
-     * //    }
-     * // }
+     * @returns
+     * - Nếu chỉ có `key`: trả về toàn bộ dữ liệu của key.
+     * - Nếu có `query`: trả về bản ghi đầu tiên khớp điều kiện.
+     * - Nếu không tìm thấy: trả về `null`.
+     *
+     * @example
+     * Chỉ lấy dữ liệu theo key
+     * ```ts
+     * const users = await db.findOne("user");
+     * ```
+     *
+     * @example
+     * Tìm một bản ghi theo điều kiện
+     * ```ts
+     * const user = await db.findOne("user", {
+     *   guild: 1234566
+     * });
+     * ```
      */
-    fetch<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>> | V>;
+    findOne<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>, query?: Partial<ArrayElement<ObjectValue<V, P>>>): Promise<Maybe<ObjectValue<V, P>> | V>;
     /**
-     * Determines if the data is stored in database.
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {boolean} Whether the data is stored in database.
+     * Kiểm tra một key-path có tồn tại trong database hay không.
      *
-     * @example
-     * const isSimpleValueInDatabase = await database.has("simpleValue");
-     * console.log(isSimpleValueInDatabase); // -> true
+     * Method này sử dụng `get()` để xác định giá trị có tồn tại.
+     *
+     * @template {AutocompletableString<ObjectPath<V>>} P Key path trong database.
      *
-     * const somethingElse = await database.has("somethingElse");
-     * console.log(somethingElse); // -> false
+     * @param {AutocompletableString<P>} key Đường dẫn dữ liệu cần kiểm tra.
      *
-     * // You can use the dot notation to check the database object properties:
-     * const isObjectInDatabase = await database.has("youCanAlso.accessObjectProperties.likeThat");
-     * console.log(isObjectInDatabase); // -> true
+     * @returns `true` nếu key tồn tại, ngược lại `false`.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    simpleValue: 123,
-     * //    player: {
-     * //        inventory: []
-     * //    },
-     * //    youCanAlso: {
-     * //        accessObjectProperties: {
-     * //            likeThat: "hello world!"
-     * //        }
-     * //    }
-     * // }
+     * @example
+     * ```ts
+     * const exists = await db.has("users.123");
+     * ```
      */
     has<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>): Promise<boolean>;
     /**
-     * Writes the specified value into database under the specified key.
+     * Gán giá trị cho một key-path trong database.
+     *
+     * Nếu key-path chưa tồn tại, các object trung gian
+     * sẽ được tự động tạo.
      *
-     * @param {AutocompletableString<P>} key The key to write in the target.
-     * @param {ObjectValue<V, P>} value The value to write.
+     * @template {AutocompletableString<ObjectPath<V>>} P Key path trong database.
      *
-     * @returns {Promise<If<IsObject<V>, FirstObjectKey<P>, V>>}
-     * - If the `value` parameter's type is not an object (string, number, boolean, etc), then the specified
-     * `value` parameter (type of `ObjectValue<V, P>`) will be returned.
+     * @param {AutocompletableString<P>} key Đường dẫn dữ liệu cần gán giá trị.
+     * @param {ObjectValue<V, P>} value Giá trị mới.
      *
-     * - If an object is specified in the `value` parameter, then the object of the first key will be returned.
-     * (type of `FirstObjectKey<P>` - first object key (e.g. in key `member.user.id`, the first key will be `member`))
+     * @returns {Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>} Giá trị vừa được set hoặc object root nếu value là object.
      *
      * @example
-     * // Assuming that the initial database object for this example is empty.
+     * ```ts
+     * await db.set("users.123.name", "Alice");
+     * ```
      *
-     * await database.set("something", "hello");
-     * const hello = await database.get("something");
+     * @example
+     * ```ts
+     * await db.set("config.prefix", "!");
+     * ```
+     */
+    set<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
+    /**
+     * Xóa một key khỏi database.
      *
-     * console.log(hello); // -> "hello"
+     * Hỗ trợ nested path bằng dot notation.
      *
-     * // You can use the dot notation to write data in objects:
-     * const dotNotationSetResult = await database.set("member.user.id", 2000);
-     * console.log(dotNotationSetResult); // -> 2000
+     * @typeParam P - Path của object.
      *
-     * await database.set("member.inventory", []);
-     * const inventory = await database.get("member.inventory");
+     * @param key - Đường dẫn key cần xóa.
      *
-     * console.log(inventory); // -> []
+     * @returns
+     * - `true` nếu xóa thành công
+     * - `false` nếu key không tồn tại
      *
-     * // Using objects as value will return the object of key `thats`:
-     * await database.set("member.user", { name: "Jerry" }); // -> { member: { user: { name: "Jerry" } } }
+     * @throws BlackCatError
+     * - INVALID_TYPE nếu key không phải string
      *
-     * // After these manipulations, the database object will look like this:
-     * // {
-     * //     "something": "hello",
-     * //     "member": {
-     * //       "inventory": [],
-     * //       "user": {
-     * //          "name": "Jerry",
-     * //          "id": 2000
-     * //       }
-     * //     }
-     * // }
+     * @example
+     * await db.delete("user.name");
      */
-    set<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
+    delete<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<boolean>;
     /**
-     * Update the specified value into database under the specified key.
+     * Xóa toàn bộ dữ liệu trong database.
      *
-     * @param {AutocompletableString<P>} key The key to update the target.
-     * @param {ObjectValue<V, P>} value The value to update.
+     * Method này gọi trực tiếp `driver.delete()` để reset storage.
      *
-     * @returns {Promise<If<IsObject<V>, FirstObjectKey<P>, V>>}
-     * - If the `value` parameter's type is not an object (string, number, boolean, etc), then the specified
-     * `value` parameter (type of `ObjectValue<V, P>`) will be returned.
+     * @returns `true` sau khi dữ liệu đã được xóa.
      *
-     * - If an object is specified in the `value` parameter, then the object of the first key will be returned.
-     * (type of `FirstObjectKey<P>` - first object key (e.g. in key `member.user.id`, the first key will be `member`))
+     * @example
+     * await db.deleteAll();
      */
-    update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
+    deleteAll(): Promise<boolean>;
     /**
-     * Performs an arithmetical addition on a target number in database.
+     * Xóa nhiều bản ghi trong một mảng dữ liệu dựa trên điều kiện truy vấn.
+     *
+     * ⚠️ Method này **chỉ hoạt động với dữ liệu dạng mảng (array)**.
+     * Nếu dữ liệu tại `key` không phải là mảng, method sẽ **không thực hiện xóa**
+     * và trả về `0`.
+     *
+     * Method sẽ duyệt qua toàn bộ phần tử trong mảng và xóa những phần tử
+     * khớp với điều kiện `query`.
+     *
+     * @template V - Kiểu dữ liệu của database.
+     * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+     *
+     * @param key - Đường dẫn đến mảng dữ liệu cần thao tác.
+     * @param query - Điều kiện để xác định các phần tử cần xóa.
+     * Có thể truyền:
+     * - Một object điều kiện
      *
-     * [!!!] The type of target value must be a number.
+     * @returns Số lượng phần tử đã bị xóa khỏi mảng.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @param {number} numberToAdd The number to add to the target number in database.
-     * @returns {Promise<number>} Addition operation result.
+     * @example
+     * Database mẫu:
+     * ```json
+     * {
+     *   "member": {
+     *     "user": {
+     *       "database": [
+     *         { "guild": "123", "username": "vinh" },
+     *         { "guild": "456", "username": "test" }
+     *       ]
+     *     }
+     *   }
+     * }
+     * ```
      *
      * @example
-     * const additionResult = await database.add("points", 5);
-     * console.log(additionResult); // -> 10 (5 + 5 = 10)
+     * Xóa tất cả user có guild = "123"
+     * ```ts
+     * await db.deleteMany("member.user.database", {
+     *   guild: "123"
+     * });
+     * ```
+     */
+    deleteMany<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, query: Partial<ArrayElement<ObjectValue<V, P>>>): Promise<number>;
+    /**
+     * Cập nhật giá trị của một key-path trong database.
+     *
+     * Khác với `set()`, method này chỉ ghi đè giá trị của key cuối cùng
+     * trong path mà không thay đổi cấu trúc object phía trên.
+     *
+     * Nếu các object trung gian trong path chưa tồn tại
+     * thì chúng sẽ được tự động tạo.
+     *
+     * @template P Key path trong database.
      *
-     * // Notice that we don't need to assign a value to unexistent properties in database
-     * // before performing an addition since the initial target value is 0 and will be used
-     * // as the value of the unexistent property:
-     * const unexistentAdditionResult = await database.add("somethingElse", 3);
+     * @param key Đường dẫn dữ liệu cần cập nhật.
+     * @param value Giá trị mới.
      *
-     * console.log(unexistentAdditionResult); // -> 3 (0 + 3 = 3)
-     * // the property didn't exist in database, that's why 0 is added to 3
+     * @returns Object cha của key vừa cập nhật.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    points: 5
-     * // }
+     * @example
+     * ```ts
+     * await db.update("users.123.name", "Alice");
+     * ```
      */
-    add<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, numberToAdd: number): Promise<number>;
+    update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
     /**
-     * Performs an arithmetical subtraction on a target number in database.
+     * Cộng thêm giá trị vào một key dạng number.
+     *
+     * Nếu key chưa tồn tại, giá trị mặc định sẽ là `0`.
+     *
+     * @template P Key path trong database.
      *
-     * [!!!] The type of target value must be a number.
+     * @param key Đường dẫn dữ liệu dạng number.
+     * @param numberToAdd Số cần cộng thêm.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @param {number} numberToSubtract The number to subtract from the target number in database.
-     * @returns {Promise<number>} Subtraction operation result.
+     * @returns Giá trị mới sau khi cộng.
      *
      * @example
-     * const subtractionResult = await database.subtract("points", 5)
-     * console.log(subtractionResult) // -> 5 (10 - 5 = 5)
+     * ```ts
+     * await db.add("economy.users.123.balance", 50);
+     * ```
+     */
+    add<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, numberToAdd: number): Promise<number>;
+    /**
+     * Trừ giá trị khỏi một key dạng number.
      *
-     * // Notice that we don't need to assign a value to unexistent properties in database
-     * // before performing a subtraction since the initial target value is 0 and will be used
-     * // as the value of the unexistent property:
-     * const unexistentSubtractionitionResult = await database.subtract("somethingElse", 3)
+     * Nếu key chưa tồn tại, giá trị mặc định sẽ là `0`.
      *
-     * console.log(unexistentSubtractionitionResult) // -> 3 (0 - 3 = -3)
-     * // the property didn't exist in database, so 3 is subtracted from 0
+     * @template P Key path trong database.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    points: 10
-     * // }
+     * @param key Đường dẫn dữ liệu dạng number.
+     * @param numberToSubtract Số cần trừ.
+     *
+     * @returns Giá trị mới sau khi trừ.
+     *
+     * @example
+     * ```ts
+     * await db.subtract("economy.users.123.balance", 20);
+     * ```
      */
     subtract<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, numberToSubtract: number): Promise<number>;
     /**
-     * Pushes the specified value(s) into the target array in database.
+     * Thêm một hoặc nhiều phần tử vào cuối array tại key-path.
      *
-     * [!!!] The type of target value must be an array.
-     * [!!!] get only values ​​not stored in the database.
+     * Method này sẽ:
+     * - kiểm tra target có phải array không
+     * - chỉ thêm các giá trị **chưa tồn tại** trong array
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @param {RestOrArray<ExtractFromArray<ObjectValue<V, P>>>} values
-     * The value(s) to be pushed into the target array in database.
+     * ⚠️ Nếu key không tồn tại hoặc target không phải array
+     * thì sẽ ném lỗi.
      *
-     * @returns {Promise<Array<ExtractFromArray<ObjectValue<V, P>>>>} Updated target array from database.
+     * @template P Key path trong database.
+     *
+     * @param key Đường dẫn tới array cần thêm phần tử.
+     * @param values Một hoặc nhiều giá trị cần thêm.
+     *
+     * @returns Array sau khi thêm phần tử.
      *
      * @example
-     * console.log(await database.push("members", "Jerry")); // -> ["Tom", "Jerry"]
-     * // You can also pass in multiple values to push into the target array:
-     * console.log(await database.push("currencies", "VND")); // -> ["USD", "VND"]
+     * ```ts
+     * await db.push("users.123.roles", "admin");
+     * ```
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    members: ["Tom"],
-     * //    currencies: ["USD"]
-     * // }
+     * @example
+     * ```ts
+     * await db.push("queue.songs", song1, song2);
+     * ```
      */
     push<P extends ObjectPath<V>>(key: AutocompletableString<P>, ...values: RestOrArray<ExtractFromArray<ObjectValue<V, P>>>): Promise<ExtractFromArray<ObjectValue<V, P>>[]>;
     /**
-    * Replaces the specified element in target array with the specified value in the target array in database.
-    *
-    * [!!!] The type of target value must be an array.
-    *
-    * @param {AutocompletableString<P>} key The key to access the target in database by.
-    * @param {number} targetArrayElementIndex The index to find the element in target array by.
-    * @param {V} value The value to be pushed into the target array in database.
-    * @returns {Promise<Array<ExtractFromArray<ObjectValue<V, P>>>>} Updated target array from database.
-    *
-    * @example
-    * console.log(await database.pull("members", 1, "James")); // -> ["Jerry", "James", "Tom"]
-    *
-    * // Assuming that the initial database object for this example is:
-    * // {
-    * //    members: ["Jerry", "William", "Tom"]
-    * // }
-    */
+     * Thay thế phần tử trong array theo index.
+     *
+     * @typeParam P - Path trỏ đến array.
+     *
+     * @param key - Đường dẫn array.
+     * @param targetArrayElementIndex - Index cần thay.
+     * @param value - Giá trị mới.
+     *
+     * @returns Array sau khi thay thế.
+     *
+     * @throws BlackCatError
+     * - INVALID_TYPE nếu index không phải number
+     * - REQUIRED_PARAMETER_MISSING nếu thiếu value
+     * - INVALID_KEY nếu path không tồn tại
+     * - INVALID_TARGET nếu target không phải array
+     *
+     * @example
+     * await db.pull("users", 0, { id: 2 });
+     */
     pull<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, targetArrayElementIndex: number, value: ExtractFromArray<ObjectValue<V, P>>): Promise<ExtractFromArray<ObjectValue<V, P>>[]>;
     /**
-     * Removes the specified element(s) from the target array in database.
+     * Xóa phần tử khỏi array theo index.
      *
-     * [!!!] The type of target value must be an array.
+     * Có thể truyền nhiều index hoặc một array index.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @param {RestOrArray<ExtractFromArray<number>>} targetArrayElementIndexes
-     * The index(es) to find the element(s) in target array by.
+     * @typeParam P - Path trỏ đến array.
      *
-     * @returns {Promise<Array<ExtractFromArray<ObjectValue<V, P>>>>} Updated target array from database.
+     * @param key - Đường dẫn array.
+     * @param targetArrayElementIndexes - Các index cần xóa.
      *
-     * @example
-     * console.log(await database.pop("members", 1)); // -> ["Jerry", "Tom"]
+     * @returns Danh sách phần tử đã bị xóa.
      *
-     * console.log(await database.pop("currencies", 1)); // -> ["VND", "Euro"]
+     * @throws BlackCatError
+     * - INVALID_TARGET nếu target không phải array
+     * - REQUIRED_PARAMETER_MISSING nếu thiếu index
+     * - ONE_OR_MORE_ARRAY_TYPES_INVALID nếu index không phải number
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    members: ["Jerry", "William", "Tom"],
-     * //    currencies: ["VND", "USD", "Euro"]
-     * // }
+     * @example
+     * await db.pop("users", 0);
+     * await db.pop("numbers", [1, 2, 3]);
      */
     pop<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, ...targetArrayElementIndexes: RestOrArray<ExtractFromArray<number>>): Promise<ExtractFromArray<ObjectValue<V, P>>[]>;
     /**
-     * Determines whether the specified target is an array.
+     * Kiểm tra xem giá trị tại key có phải là Array hay không.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {Promise<boolean>} Whether the target is an array.
+     * @typeParam P - Path của object trong database.
+     * @param key - Đường dẫn key cần kiểm tra.
      *
-     * @example
-     * console.log(await databse.isTargetArray("array")); // => true
-     * console.log(await databse.isTargetArray("notArray")); // => false
+     * @returns `true` nếu giá trị là Array, ngược lại `false`.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    array: [],
-     * //    notArray: 123
-     * // }
+     * @example
+     * const result = await db.isTargetArray("users");
+     * console.log(result);
      */
     isTargetArray<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>): Promise<boolean>;
     /**
-     * Determines whether the specified target is a number.
+     * Kiểm tra xem giá trị tại key có phải là Number hay không.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {Promise<boolean>} Whether the target is a number.
+     * @typeParam P - Path của object trong database.
      *
-     * @example
-     * console.log(await database.isTargetNumber("number")); // -> true
-     * console.log(await database.isTargetNumber("notNumber")); // -> false
+     * @param key - Đường dẫn key cần kiểm tra.
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    number: 123,
-     * //    notNumber: []
-     * // }
+     * @returns `true` nếu giá trị là Number, ngược lại `false`.
+     *
+     * @example
+     * const result = await db.isTargetNumber("stats.score");
+     * console.log(result);
      */
     isTargetNumber<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>): Promise<boolean>;
     /**
-     * Returns an array of object keys by specified database key.
+     * Lấy danh sách các key của object trong database.
      *
-     * If `key` parameter is omitted, then an array of object keys of database root object will be returned.
+     * Nếu không truyền `key` → trả về các key cấp cao nhất của database.
      *
-     * Type parameters:
+     * @typeParam P - Path của object.
      *
-     * - `TKeys` (`TupleOrArray<string>`, defaults to `K[]`) - The tuple or array of a type of keys to be returned.
+     * @param key - Path của object cần lấy danh sách key.
      *
-     * @param {P} [key] The key to access the target in database by.
-     * @returns {Array<ObjectPath<P>>} Database object keys array.
+     * @returns Mảng các key tồn tại (không bao gồm `null` hoặc `undefined`).
      *
      * @example
-     * const prop3Keys = await database.keys("prop3");
-     * console.log(prop3Keys) // -> ["prop4", "prop5"]
-     *
-     * const prop5Keys = await database.keys("prop3.prop5");
-     * console.log(prop5Keys) // -> ["prop6"]
-     *
-     * const prop6Keys = await database.keys("prop3.prop5.prop6");
-     * console.log(prop6Keys)
-     * // -> [] (empty since the value in `prop6`, 111, is a primitive value and not an actual object)
-     *
-     * const databaseKeys = await database.keys();
-     * // in this example, `key` parameter is omitted - object keys of database object are being returned
-     *
-     * console.log(databaseKeys) // -> ["prop1", "prop2", "prop3"]
-     *
-     * const unexistentKeys = await database.keys("somethingElse");
-     * console.log(unexistentKeys) // -> [] (empty since the key `somethingElse` does not exist in database)
-     *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    prop1: 123,
-     * //    prop2: 456,
-     * //    prop3: {
-     * //       prop4: 789,
-     * //       prop5: {
-     * //          prop6: 111
-     * //       }
-     * //    }
-     * // }
+     * const rootKeys = await db.keys();
+     * const userKeys = await db.keys("user");
      */
     keys<P extends AutocompletableString<ObjectPath<V>>>(key?: P): Promise<ObjectPath<P>[]>;
     /**
-     * Determines the number of keys in the root of the database.
-     * @type {Promise<number>} amount of data.
+     * Lấy số lượng key cấp cao nhất trong database.
+     *
+     * @returns Tổng số key ở root level.
+     *
+     * @example
+     * const count = await db.size();
      */
     size(): Promise<number>;
     /**
-     * Returns an array of object values by specified database key.
+     * Lấy danh sách các giá trị từ database.
      *
-     * If `key` parameter is omitted, then an array of object values of database root object will be returned.
+     * Nếu không truyền `key` → trả về toàn bộ values ở root level.
+     * Nếu truyền `key` → trả về values của object tại path đó.
      *
-     * @param {P} [key] The key to access the target in database by.
-     * @returns {Array<ObjectValue<V, P>>} Database object values array.
+     * @typeParam P - Path của object trong database.
+     *
+     * @param key - Đường dẫn object cần lấy values.
+     *
+     * @returns Mảng các giá trị.
      *
      * @example
-     * const prop3Values = await database.values("prop3");
-     * console.log(prop3Values); // -> [789, { prop6: 111 }]
+     * const allValues = await db.values();
      *
-     * const prop5Values = await database.values("prop3.prop5");
-     * console.log(prop5Values); // -> []
+     * const userValues = await db.values("users");
+     */
+    values<P extends AutocompletableString<ObjectPath<V>>>(key?: P): Promise<ObjectValue<V, P>[]>;
+    /**
+     * Lấy ngẫu nhiên một phần tử từ array tại path được chỉ định.
      *
-     * const prop6Values = await database.values("prop3.prop5.prop6");
-     * console.log(prop6Values);
-     * // -> [] (empty since the value in `prop6`, 111, is a primitive value and not an actual object)
+     * @typeParam P - Path trỏ đến array trong database.
      *
-     * const databaseValues = await database.values();
-     * // in this example, `key` parameter is omitted - object values of database object are being returned
+     * @param key - Đường dẫn đến array.
      *
-     * console.log(databaseValues); // -> [123, 456, { prop4: 789, prop5: { prop6: 111 } }]
+     * @returns Một phần tử ngẫu nhiên trong array hoặc `null` nếu array rỗng.
      *
-     * const unexistentValues = await database.values("somethingElse");
-     * console.log(unexistentValues); // -> [] (empty since the key `somethingElse` does not exist in database)
+     * @throws BlackCatError
+     * - INVALID_TARGET nếu giá trị tại key không phải array
      *
-     * // Assuming that the initial database object for this example is:
-     * // {
-     * //    prop1: 123,
-     * //    prop2: 456,
-     * //    prop3: {
-     * //       prop4: 789,
-     * //       prop5: {
-     * //          prop6: 111
-     * //       }
-     * //    }
-     * // }
+     * @example
+     * const randomUser = await db.random("users");
      */
-    values<P extends AutocompletableString<ObjectPath<V>>>(key?: P): Promise<ObjectValue<V, P>[]>;
+    random<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>>>;
     /**
-     * This method works the same way as `Array.find()`.
+     * Tìm phần tử đầu tiên thỏa điều kiện.
+     *
+     * Hoạt động tương tự `Array.prototype.find`.
      *
-     * Iterates over root database values, finds the element in database values array
-     * by specified condition in the callback function and returns the result.
+     * @param queryFunction - Hàm kiểm tra điều kiện.
      *
-     * @param {QueryFunction<V>} queryFunction
-     * A function that accepts up to three arguments.
-     * The `find` method calls the `queryFunction` once for each element in database object values array.
+     * @returns Phần tử đầu tiên thỏa điều kiện hoặc `null` nếu không tìm thấy.
      *
-     * @returns {Promise<Maybe<V>>} The search
+     * @example
+     * const user = await db.find(u => u.id === 1);
      */
     find(queryFunction: QueryFunction<V>): Promise<Maybe<V>>;
     /**
-     * This method works the same way as `Array.map()`.
+     * Biến đổi tất cả giá trị trong database thành một mảng mới.
+     *
+     * Hoạt động giống `Array.prototype.map`.
      *
-     * Calls a defined callback function on each element of an array,
-     * and returns an array that contains the results.
+     * @typeParam TReturnType - Kiểu dữ liệu của phần tử trả về.
      *
-     * @param {QueryFunction<V, TReturnType>} queryFunction
-     * A function that accepts up to three arguments.
-     * The `map` method calls the `queryFunction` once for each element in database object values array.
+     * @param queryFunction - Hàm transform từng phần tử.
      *
-     * @returns {Promise<TReturnType[]>}
+     * @returns Mảng kết quả sau khi transform.
+     *
+     * @example
+     * const names = await db.map(user => user.name);
      */
     map<TReturnType>(queryFunction: QueryFunction<V, TReturnType>): Promise<TReturnType[]>;
     /**
-     * This method works the same way as `Array.findIndex()`.
+     * Tìm index của phần tử đầu tiên thỏa điều kiện.
+     *
+     * Hoạt động giống `Array.prototype.findIndex`.
      *
-     * Iterates over root database values, finds the index of the element in database values array
-     * by specified condition in the callback function and returns the result.
+     * @param queryFunction - Hàm kiểm tra điều kiện.
      *
-     * @param {QueryFunction<V>} queryFunction
-     * A function that accepts up to three arguments.
-     * The `findIndex` method calls the `queryFunction` once for each element in database object values array.
+     * @returns Index của phần tử hoặc `-1` nếu không tìm thấy.
      *
-     * @returns {Promise<number>}
+     * @example
+     * const index = await db.findIndex(user => user.id === 1);
      */
     findIndex(queryFunction: QueryFunction<V>): Promise<number>;
     /**
-     * This method works the same way as `Array.filter()`.
+     * Lọc các phần tử thỏa điều kiện.
+     *
+     * Hoạt động giống `Array.prototype.filter`.
      *
-     * Iterates over root database values, finds all the element that match the
-     * specified condition in the callback function and returns the result.
+     * @param queryFunction - Hàm kiểm tra điều kiện.
      *
-     * @param {QueryFunction<V>} queryFunction
-     * A function that accepts up to three arguments.
-     * The `filter` method calls the `queryFunction` once for each element in database object values array.
+     * @returns Mảng các phần tử thỏa điều kiện.
      *
-     * @returns {Promise<V[]>}
+     * @example
+     * const admins = await db.filter(user => user.role === "admin");
      */
     filter(queryFunction: QueryFunction<V>): Promise<V[]>;
     /**
-     * This method works the same way as `Array.some()`.
+     * Kiểm tra có ít nhất một phần tử thỏa điều kiện hay không.
      *
-     * Iterates over root database values and checks if the
-     * specified condition in the callback function returns `true`
-     * for **any** of the elements of the database object values array.
+     * Hoạt động giống `Array.prototype.some`.
      *
-     * @param {QueryFunction<V>} queryFunction
-     * A function that accepts up to three arguments.
-     * The `some` method calls the `queryFunction` once for each element in database object values array.
+     * @param queryFunction - Hàm kiểm tra điều kiện.
      *
-     * @returns {Promise<boolean>}
+     * @returns `true` nếu tồn tại phần tử thỏa điều kiện.
+     *
+     * @example
+     * const hasAdmin = await db.some(user => user.role === "admin");
      */
     some(queryFunction: QueryFunction<V>): Promise<boolean>;
     /**
-     * This method works the same way as `Array.every()`.
+     * Kiểm tra tất cả phần tử có thỏa điều kiện hay không.
+     *
+     * Hoạt động giống `Array.prototype.every`.
      *
-     * Iterates over root database values and checks if the
-     * specified condition in the callback function returns `true`
-     * for **all** of the elements of the database object values array.
+     * @param queryFunction - Hàm kiểm tra điều kiện.
      *
-     * @param {QueryFunction<V>} queryFunction
-     * A function that accepts up to three arguments.
-     * The `every` method calls the `queryFunction` once for each element in database object values array.
+     * @returns `true` nếu tất cả phần tử đều thỏa điều kiện.
      *
-     * @returns {Promise<boolean>}
+     * @example
+     * const allActive = await db.every(user => user.active === true);
      */
     every(queryFunction: QueryFunction<V>): Promise<boolean>;
+}
+
+/**
+ * Cấu hình khởi tạo cho {@link JSONDriver}.
+ */
+interface JSONDriverOptions {
     /**
-     * Picks a random element of array in database and returns the picked array element.
+     * Đường dẫn tới file JSON dùng làm database.
      *
-     * [!!!] The type of target value must be an array.
+     * Ví dụ:
+     * ```ts
+     * "./database.json"
+     * "./data/users.json"
+     * ```
+     */
+    filePath: string;
+    /**
+     * Nếu bật, nội dung JSON sẽ được **minify**
+     * (không format khoảng trắng) để giảm dung lượng file.
      *
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {Promise<Maybe<ObjectValue<V, P>>>} The randomly picked element in the database array.
+     * Nếu tắt, JSON sẽ được format với indentation để dễ đọc.
+     *
+     * @default false
+     */
+    minifyJSON?: boolean;
+}
+/**
+ * Driver lưu trữ dữ liệu dạng JSON.
+ *
+ * ⚠️ Đây **không phải database hoàn chỉnh**.
+ * Class này chỉ đóng vai trò **driver lưu trữ (storage layer)**
+ * cho class chính `Database`.
+ *
+ * Toàn bộ logic xử lý key path (`a.b.c`), validate dữ liệu,
+ * và các thao tác database sẽ được thực hiện trong class `Database`.
+ *
+ * `JSONDriver` chỉ chịu trách nhiệm:
+ *
+ * - Đọc dữ liệu từ file JSON
+ * - Ghi dữ liệu xuống file JSON
+ *
+ * @example
+ * ```ts
+ * const database = new Database({
+ *      driber: new JSONDriver({\
+ *          filePath: "./database.json",
+ *          minifyJSON: false
+ *      })
+ * });
+ * ```
+ */
+declare class JSONDriver implements DatabaseDriver {
+    /**
+     * Đường dẫn tới file database JSON.
+     */
+    private filePath;
+    /**
+     * Cho biết có minify JSON khi ghi file hay không.
+     */
+    minifyJSON: boolean;
+    /**
+     * Khởi tạo một instance mới của {@link JSONDriver}.
+     *
+     * @param options - Cấu hình driver
+     *
+     * @param options.filePath
+     * Đường dẫn tới file JSON dùng làm database.
+     *
+     * @param options.minifyJSON
+     * Nếu `true`, nội dung JSON sẽ được minify khi ghi ra file để giảm dung lượng.
      *
      * @example
-     * const array = await database.get("array"); // assuming that the array is ['example1', 'example2', 'example3']
-     * console.log(array); // -> ['example1', 'example2', 'example3']
+     * ```ts
+     * const database = new Database({
+     *      driver: db = new JSONDriver({
+     *          filePath: "./database.json"
+     *      })
+     * });
+     * ```
+     */
+    constructor(options: JSONDriverOptions);
+    /**
+     * Đảm bảo file database tồn tại.
+     * Nếu file chưa tồn tại sẽ tự động tạo file `{}`.
+     */
+    private ensureFile;
+    /**
+     * Đọc toàn bộ dữ liệu từ file database JSON.
      *
-     * const randomArrayElement = await database.random("exampleArray");
-     * console.log(randomArrayElement); // -> randomly picked array element: either 'example1', 'example2', or 'example3'
+     * Nếu file không tồn tại hoặc lỗi parse,
+     * method sẽ trả về object rỗng.
+     *
+     * @template V Kiểu dữ liệu database.
+     * @returns Promise chứa toàn bộ dữ liệu database.
      */
-    random<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>>>;
+    all<V>(): Promise<V>;
     /**
-     * Deletes the data from database by key.
-     * @param {AutocompletableString<P>} key The key to access the target in database by.
-     * @returns {Promise<boolean>} Whether the deletion was successful.
+     * Ghi toàn bộ dữ liệu database xuống file JSON.
+     *
+     * Method này **không xử lý key path**.
+     * Logic cập nhật dữ liệu sẽ được xử lý ở class `Database`
+     * trước khi truyền object hoàn chỉnh vào đây.
+     *
+     * @param data Toàn bộ dữ liệu database sau khi đã được cập nhật.
+     *
+     * @template R Kiểu dữ liệu database.
+     * @returns Promise chứa dữ liệu đã ghi.
      */
-    delete<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<boolean>;
+    set<R = any>(data: R): Promise<R>;
     /**
-     * Deletes everything from the database.
+     * Xóa toàn bộ database.
+     *
+     * Method này chỉ reset file JSON về `{}`.
      *
-     * - This method is an alias for {@link QuickMongo.clear()} method.
-     * @returns {Promise<boolean>} `true` if cleared successfully, `false` otherwise.
+     * @returns `true` nếu reset thành công.
      */
-    deleteAll(): Promise<boolean>;
+    delete(): Promise<boolean>;
 }
 
-interface JSONDriverOptions {
+/**
+ * Driver lưu trữ dữ liệu trong RAM.
+ *
+ * ⚠️ Đây **không phải database chính**.
+ * Class này chỉ là **storage driver phụ trợ** cho class `Database`.
+ *
+ * Toàn bộ logic xử lý:
+ * - key path (`a.b.c`)
+ * - validation
+ * - update dữ liệu
+ *
+ * đều được thực hiện trong class `Database`.
+ *
+ * `MemoryDriver` chỉ chịu trách nhiệm:
+ * - lưu trữ object database trong RAM
+ * - trả về toàn bộ dữ liệu
+ *
+ * Dữ liệu sẽ **mất khi ứng dụng restart**.
+ *
+ * Phù hợp cho:
+ * - testing
+ * - cache runtime
+ * - development
+ *
+ * @example
+ * ```ts
+ * const database = new Database({
+ *      driver: new MemoryDriver({
+ *          users: {},
+ *          guilds: {},
+ *          settings: {
+ *              prefix: "!"
+ *          }
+ *      })
+ * });
+ * ```
+ *
+ *  hoặc
+ *
+ * ```ts
+ * const database = new Database({
+ *     driver: new MemoryDriver()
+ * });
+ * ```
+ */
+declare class MemoryDriver implements DatabaseDriver {
     /**
-     * JSON database file path.
-     * @type {string}
+     * Object chứa toàn bộ dữ liệu database trong RAM.
      */
-    filePath: string;
+    private store;
     /**
-     * Minifies the JSON content in database file to save some space.
-     * @type {boolean}
+     * Khởi tạo MemoryDriver.
+     *
+     * @param initialData Dữ liệu khởi tạo ban đầu.
+     * * @example
+     * ```ts
+     * const database = new Database({
+     *      driver: new MemoryDriver({
+     *          users: {},
+     *          guilds: {},
+     *          settings: {
+     *              prefix: "!"
+     *          }
+     *      })
+     * });
+     * ```
+     *
+     *  hoặc
+     *
+     * ```ts
+     * const database = new Database({
+     *     driver: new MemoryDriver()
+     * });
+     * ```
      */
-    minifyJSON?: boolean;
+    constructor(initialData?: Record<string, any>);
+    /**
+     * Trả về toàn bộ dữ liệu database.
+     *
+     * @template T Kiểu dữ liệu database.
+     */
+    all<T = any>(): Promise<T>;
+    /**
+     * Ghi toàn bộ database vào memory.
+     *
+     * ⚠️ Method này **không xử lý key-path**.
+     * Dữ liệu đã được xử lý trước bởi `Database`.
+     *
+     * @param data Toàn bộ database object
+     */
+    set<T = any>(data: T): Promise<T>;
+    /**
+     * Xóa toàn bộ dữ liệu database trong memory.
+     */
+    delete(): Promise<boolean>;
 }
+
 /**
- * JSONDriver class.
+ * Các tùy chọn cấu hình cho SQLiteDriver.
+ * @hidden
+ *
+ * Interface này định nghĩa các thiết lập được sử dụng khi
+ * khởi tạo driver SQLite cho hệ thống database.
  */
-declare class JSONDriver implements BaseDriver {
+interface SQLiteDriverOptions {
+    /**
+     * Đường dẫn đến file cơ sở dữ liệu SQLite.
+     *
+     * Nếu không được cung cấp, driver có thể tạo
+     * một file database mặc định tùy theo cách triển khai.
+     *
+     * Ví dụ:
+     * `"./database.sqlite"`
+     */
+    filePath?: string;
     /**
-     * JSON database file path.
-     * @type {string}
+     * Tên bảng được sử dụng để lưu trữ dữ liệu key-value.
+     *
+     * Nếu không được chỉ định, driver có thể sử dụng
+     * một tên bảng mặc định (ví dụ: `"data"`).
+     *
+     * Ví dụ:
+     * `"storage"`
      */
-    private filePath;
+    table?: string;
+}
+/**
+ * Driver lưu trữ dữ liệu bằng SQLite.
+ *
+ * ⚠️ Đây **không phải database chính**.
+ * Class này chỉ là **driver lưu trữ phụ trợ** cho `Database`.
+ *
+ * Logic xử lý dữ liệu như:
+ * - parse key path
+ * - update object
+ * - validation
+ *
+ * sẽ được thực hiện bởi class `Database`.
+ *
+ * Driver này chỉ:
+ * - serialize database thành JSON
+ * - lưu JSON vào SQLite
+ * - trả về JSON khi đọc
+ *
+ * Toàn bộ database được lưu trong **một row duy nhất**.
+ *
+ * @example
+ * ```ts
+ * const database = new Database({
+ *      driver: new SQLiteDriver({
+ *         filePath: "database.sqlite",
+ *         table: "json_store"
+ *      })
+ * })
+ * ```
+ */
+declare class SQLiteDriver implements DatabaseDriver {
     /**
-     * Minifies the JSON content in database file to save some space.
-     * @type {boolean}
+     * SQLite database instance.
      */
-    minifyJSON: boolean;
+    private db;
     /**
-     * JSONDriver class.
-     * @param options.filePath Json database file path.
-     * @param options.minifyJSON Minifies the JSON content in database file to save some space.
+     * Tên table lưu trữ dữ liệu JSON.
      */
-    constructor(options: JSONDriverOptions);
+    private table;
     /**
-     * Returns all data from JSON database.
+     * Khởi tạo SQLiteDriver.
      *
-     * @returns {Promise<any>} All data from JSON database.
+     * @param filePath Đường dẫn file SQLite
+     * @param table Tên table lưu JSON database
+     * @example
+     * ```ts
+     * const database = new Database({
+     *      driver: new SQLiteDriver({
+     *         filePath: "database.sqlite",
+     *         table: "json_store"
+     *      })
+     * })
+     * ```
+     */
+    constructor(options?: SQLiteDriverOptions);
+    /**
+     * Lấy toàn bộ dữ liệu database từ SQLite.
      *
-     * @template V The type of data being returned.
+     * @template T Kiểu dữ liệu database.
      */
-    all<V>(): Promise<V>;
+    all<T = any>(): Promise<T>;
     /**
-     * Parses the key and fetches the value from JSON database.
+     * Ghi toàn bộ database vào SQLite.
      *
-     * Type parameters:
+     * ⚠️ Method này **không xử lý key-path**.
+     * `Database` đã cập nhật object trước khi truyền vào đây.
      *
-     * - `V` - The type of data being returned.
+     * @param data Toàn bộ database object
+     */
+    set<T = any>(data: T): Promise<T>;
+    /**
+     * Reset toàn bộ database.
+     */
+    delete(): Promise<boolean>;
+}
+
+/**
+ * Cấu hình cho MongoDriver.
+ */
+interface MongoDriverOptions {
+    /**
+     * Chuỗi kết nối MongoDB.
      *
-     * @param {string} key The key in JSON database.
-     * @returns {Promise<V>} The data from JSON database.
+     * @default "mongodb://localhost:27017"
+     */
+    mongourl?: string;
+    /**
+     * Tên database MongoDB.
      *
-     * @template V The type of data being returned.
+     * @default "database"
      */
-    get<V = any>(key: string): Promise<V | null>;
+    databaseName?: string;
     /**
-     * Parses the key and sets the value in JSON database.
+     * Tên collection lưu dữ liệu JSON.
      *
-     * Type parameters:
+     * @default "json_store"
+     */
+    collectionName?: string;
+}
+/**
+ * Driver lưu trữ dữ liệu bằng MongoDB.
+ *
+ * ⚠️ Đây **không phải database chính**.
+ * Class này chỉ là **driver lưu trữ phụ trợ** cho class `Database`.
+ *
+ * Logic xử lý:
+ * - parse key path
+ * - validate dữ liệu
+ * - cập nhật object
+ *
+ * sẽ được xử lý bởi class `Database`.
+ *
+ * `MongoDriver` chỉ chịu trách nhiệm:
+ * - lưu toàn bộ database object
+ * - trả về database object
+ *
+ * Toàn bộ database được lưu trong **một document duy nhất**.
+ *
+ * @example
+ * ```ts
+ * const database = new Database({
+ *      driver: new MongoDriver({
+ *          mongourl: "mongodb://localhost:27017",
+ *          databaseName: "mydb",
+ *          collectionName: "store"
+ *      })
+ * });
+ * ```
+ */
+declare class MongoDriver implements DatabaseDriver {
+    /**
+     * MongoDB client instance.
+     */
+    private client;
+    /**
+     * MongoDB database instance.
+     */
+    private db;
+    /**
+     * Collection lưu dữ liệu JSON.
+     */
+    private collection;
+    /**
+     * Tên database MongoDB.
+     */
+    private databaseName;
+    /**
+     * Tên collection MongoDB.
+     */
+    private collectionName;
+    /**
+     * Khởi tạo MongoDriver.
+     *
+     * @param options Cấu hình MongoDB driver.
      *
-     * - `V` - The type of data being set.
-     * - `R` - The type of data being returned.
+     * @example
+     * ```ts
+     * const database = new Database({
+     *      driver: new MongoDriver({
+     *          mongourl: "mongodb://localhost:27017",
+     *          databaseName: "mydb",
+     *          collectionName: "store"
+     *      })
+     * });
+     */
+    constructor(options?: MongoDriverOptions);
+    /**
+     * Thiết lập kết nối MongoDB nếu chưa kết nối.
+     */
+    private connect;
+    /**
+     * Lấy toàn bộ dữ liệu database từ MongoDB.
+     */
+    all<T = any>(): Promise<T>;
+    /**
+     * Ghi toàn bộ database vào MongoDB.
      *
-     * @param {string} key The key in JSON database.
-     * @returns {Promise<R>} The data from JSON database.
+     * ⚠️ Method này **không xử lý key-path**.
+     * Object database đã được xử lý bởi class `Database`.
      *
-     * @template V The type of data being set.
-     * @template R The type of data being returned.
+     * @param data Toàn bộ object database
      */
-    set<V = any, R = any>(key: string, value: V): Promise<R>;
+    set<T = any>(data: T): Promise<T>;
     /**
-     * Parses the key and deletes it from JSON database. If no key is provided, clears the database.
-     * @param {V} key The key in JSON database.
-     * @returns {Promise<boolean>} `true` if deleted successfully.
+     * Reset toàn bộ database về object rỗng.
      */
-    delete<V = any>(key?: V): Promise<boolean>;
+    delete(): Promise<boolean>;
 }
 
-export { Database, JSONDriver };
+export { Database, JSONDriver, MemoryDriver, MongoDriver, SQLiteDriver };