blackcat.js-database 1.0.5 → 1.0.7

package/dist/index.d.mts

@@ -82,6 +82,21 @@ interface DatabaseConfiguration {
      * (ví dụ: memory, file, json, mongo, redis...).
      */
     driver: DatabaseDriver;
+    /**
+     * Ký tự phân tách dùng để tách các phần của đường dẫn (key).
+     *
+     * @defaultValue "."
+     *
+     * @example
+     * ```ts
+     * // "user.profile.name"
+     * delimiter: "."
+     *
+     * // "user/profile/name"
+     * delimiter: "/"
+     * ```
+     */
+    delimiter?: string;
     /**
      * Bật chế độ debug.
      *
@@ -113,7 +128,32 @@ interface DatabaseConfiguration {
  */
 type Maybe<T> = Exclude<T | null, undefined>;
 /**
+ * Utility type dùng để trích xuất kiểu phần tử bên trong một mảng.
+ * @hidden
+ *
+ * Nếu `T` là một mảng (`U[]`) thì kiểu trả về sẽ là `U` (kiểu phần tử).
+ * Nếu `T` không phải là mảng thì kiểu trả về chính là `T`.
+ *
+ * Thường được sử dụng trong các generic type để làm việc
+ * với kiểu dữ liệu của phần tử trong mảng một cách an toàn.
+ *
+ * @typeParam T - Kiểu dữ liệu đầu vào, có thể là mảng hoặc bất kỳ kiểu nào.
+ *
+ * @example
+ * type A = ArrayElement<string[]>;
+ * // Kết quả: string
+ *
+ * @example
+ * type B = ArrayElement<number[]>;
+ * // Kết quả: number
+ *
+ * @example
+ * type C = ArrayElement<string>;
+ * // Kết quả: string
  *
+ * @example
+ * type D = ArrayElement<(number | string)[]>;
+ * // Kết quả: number | string
  */
 type ArrayElement<T> = T extends (infer U)[] ? U : T;
 /**
@@ -310,26 +350,6 @@ type IsAny<T> = 0 extends (1 & T) ? true : false;
  * const c: Status = "custom";  // vẫn hợp lệ
  */
 type AutocompletableString<S extends string> = S | (string & {});
-/**
- * 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 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`.
- *
- * @typeParam TKey - Object path cần trích xuất key đầu tiên.
- *
- * @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;
 /**
  * Đạ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`.
@@ -401,7 +421,7 @@ type ObjectPath<T, TKey extends keyof T = keyof T> = IsAny<T> extends true ? str
  * 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;
+type ObjectValue<T, P extends ObjectPath<T> | AutocompletableString<ObjectPath<T>>> = T extends string | number | boolean | bigint | symbol | null | undefined | Date | Function ? T : T extends (infer U)[] ? ObjectValue<U, P>[] : P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? ObjectValue<T[Key], Rest> : never : P extends keyof T ? T[P] : never;
 
 /**
  * Class Database cung cấp API thao tác dữ liệu dạng key-path
@@ -481,7 +501,7 @@ declare class Database<V = any> {
      * console.log(data.users);
      * ```
      */
-    all<T extends Record<string, any> = Record<string, any>>(): Promise<T>;
+    all(): Promise<V>;
     /**
      * Lấy giá trị từ database theo key-path.
      *
@@ -510,7 +530,7 @@ declare class Database<V = any> {
      * const all = await db.get();
      * ```
      */
-    get<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>> | V>;
+    get<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>>>;
     /**
      * Tìm và trả về một bản ghi đầu tiên khớp với điều kiện trong database.
      *
@@ -547,7 +567,7 @@ declare class Database<V = any> {
      * });
      * ```
      */
-    findOne<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>, query?: Partial<ArrayElement<ObjectValue<V, 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>>>;
     /**
      * Kiểm tra một key-path có tồn tại trong database hay không.
      *
@@ -576,7 +596,7 @@ declare class Database<V = any> {
      * @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.
      *
-     * @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.
+     * @returns {void} Giá trị vừa được set hoặc object root nếu value là object.
      *
      * @example
      * ```ts
@@ -588,25 +608,66 @@ declare class Database<V = any> {
      * 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>>;
+    set<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<void>;
     /**
-     * Xóa một key khỏi database.
+     * Đảm bảo một key tồn tại với giá trị mặc định.
+     * Nếu key đã tồn tại → giữ nguyên và trả về giá trị hiện tại.
+     * Nếu chưa tồn tại → set giá trị default và trả về default đó.
      *
-     * Hỗ trợ nested path bằng dot notation.
+     * Khác với `set()` — không bao giờ ghi đè dữ liệu đã có.
+     *
+     * @template P Key path trong database.
+     *
+     * @param key Đường dẫn cần đảm bảo tồn tại.
+     * @param defaultValue Giá trị mặc định nếu key chưa có.
+     *
+     * @returns Giá trị tại key sau khi ensure (current hoặc default).
+     *
+     * @example
+     * // "config.maxRetries" chưa tồn tại → set về 3, trả về 3
+     * const retries = await db.ensure("config.maxRetries", 3);
+     *
+     * @example
+     * // "config.maxRetries" đã là 10 → không đổi, trả về 10
+     * const retries = await db.ensure("config.maxRetries", 3);
+     *
+     * @example
+     * // Dùng với object — đảm bảo cấu trúc user tồn tại
+     * const user = await db.ensure("users.123", {
+     *   balance: 0,
+     *   level: 1,
+     *   joinedAt: Date.now(),
+     * });
+     */
+    ensure<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, defaultValue: ObjectValue<V, P>): Promise<NonNullable<ObjectValue<V, P>>>;
+    /**
+     * Xóa dữ liệu khỏi database.
+     * Hỗ trợ truy cập dữ liệu lồng nhau bằng dot notation.
+     * Nếu key không tồn tại hoặc đường dẫn không hợp lệ, hàm sẽ trả về `false`.
      *
      * @typeParam P - Path của object.
      *
-     * @param key - Đường dẫn key cần xóa.
+     * @param key - Đường dẫn dữ liệu cần xóa.
      *
      * @returns
-     * - `true` nếu xóa thành công
-     * - `false` nếu key không tồn tại
+     * - `true` nếu xóa thành công.
+     * - `false` nếu key không tồn tại hoặc đường dẫn không hợp lệ.
      *
      * @throws BlackCatError
-     * - INVALID_TYPE nếu key không phải string
+     * - INVALID_TYPE nếu `key` không phải là chuỗi.
      *
      * @example
+     * // Xóa một thuộc tính
      * await db.delete("user.name");
+     *
+     * @example
+     * // Xóa object lồng nhau
+     * await db.delete("users.0.profile");
+     *
+     * @example
+     * // Key không tồn tại
+     * const deleted = await db.delete("user.address");
+     * console.log(deleted); // false
      */
     delete<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<boolean>;
     /**
@@ -665,25 +726,57 @@ declare class Database<V = any> {
      */
     deleteMany<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, query: Partial<ArrayElement<ObjectValue<V, P>>>): Promise<number>;
     /**
-     * Cập nhật dữ liệu trong database theo đường dẫn key.
+     * Cập nhật dữ liệu trong database theo đường dẫn (`key`).
+     *
+     * ## Chức năng
+     * - Cập nhật giá trị tại một key hoặc nested key trong database.
+     * - Tự động tạo object trung gian nếu đường dẫn chưa tồn tại.
+     * - Hỗ trợ gộp dữ liệu (merge) đối với object và mảng nhằm hạn chế ghi đè dữ liệu đã có.
+     *
+     * ## Mô tả hoạt động
+     * Hàm sẽ đọc toàn bộ dữ liệu database, tìm đến vị trí tương ứng với `key`
+     * và cập nhật giá trị mới theo các quy tắc sau:
      *
-     * Hàm này sẽ tìm đến vị trí của `key` trong database và gán `value` vào đó.
-     * Nếu `value` và giá trị hiện tại tại key đều là object thì sẽ thực hiện
-     * **shallow merge** thay vì ghi đè toàn bộ object.
+     * - **Đối với Array**
+     *   - Nếu cả giá trị hiện tại và giá trị mới đều là mảng thì sẽ **không ghi đè**.
+     *   - Các phần tử mới sẽ được thêm vào cuối mảng.
+     *   - Chỉ thêm những phần tử chưa tồn tại ví dụ dựa trên cặp thuộc tính:
+     *     - `username`
+     *     - `guild`
+     *   - Điều này giúp tránh lưu trùng dữ liệu thành viên giữa nhiều lần cập nhật.
      *
-     * Điều này giúp tránh việc làm mất các thuộc tính đã tồn tại.
+     * - **Đối với Object**
+     *   - Nếu cả hai đều là object sẽ thực hiện **shallow merge** (`...old, ...new`).
+     *   - Các thuộc tính mới sẽ ghi đè thuộc tính cùng tên.
+     *   - Những thuộc tính khác vẫn được giữ nguyên.
      *
-     * @template P - Đường dẫn key hợp lệ trong object database.
+     * - **Các kiểu dữ liệu khác**
+     *   - Giá trị mới sẽ ghi đè hoàn toàn giá trị cũ.
      *
-     * @param key - Đường dẫn tới giá trị cần cập nhật.
-     * Hỗ trợ nested path dạng `"a.b.c"`.
+     * Sau khi cập nhật xong, toàn bộ database sẽ được ghi lại thông qua driver.
      *
-     * @param value - Giá trị mới sẽ được cập nhật tại key.
+     * @template P
+     * Đường dẫn hợp lệ của object trong database.
+     *
+     * @param key
+     * Đường dẫn cần cập nhật.
+     *
+     * Hỗ trợ nested path:
+     * ```ts
+     * "guilds.123.settings.prefix"
+     * "users.456.profile.name"
+     * ```
+     *
+     * @param value
+     * Giá trị mới cần cập nhật.
      *
      * @returns
-     * Trả về giá trị cuối cùng sau khi cập nhật.
+     * Trả về giá trị cuối cùng sau khi được lưu vào database.
+     *
+     * ## Cách sử dụng
+     *
+     * ### Ví dụ 1 - Cập nhật object
      *
-     * @example
      * Database ban đầu:
      * ```json
      * {
@@ -695,10 +788,9 @@ declare class Database<V = any> {
      * }
      * ```
      *
-     * Cập nhật:
      * ```ts
      * await db.update("123", {
-     *   history: [1,2,3]
+     *     history: [1, 2, 3]
      * });
      * ```
      *
@@ -708,16 +800,211 @@ declare class Database<V = any> {
      *   "123": {
      *     "guildID": "123",
      *     "guildName": "BlackCat",
-     *     "history": [1,2,3]
+     *     "history": [1, 2, 3]
+     *   }
+     * }
+     * ```
+     *
+     * ---
+     *
+     * ### Ví dụ 2 - Cập nhật nested key
+     *
+     * ```ts
+     * await db.update("guilds.123.settings.prefix", "!");
+     * ```
+     *
+     * Nếu đường dẫn chưa tồn tại:
+     *
+     * ```json
+     * {}
+     * ```
+     *
+     * Sau khi cập nhật:
+     *
+     * ```json
+     * {
+     *   "guilds": {
+     *     "123": {
+     *       "settings": {
+     *         "prefix": "!"
+     *       }
+     *     }
      *   }
      * }
      * ```
      *
+     * ---
+     *
+     * ### Ví dụ 3 - Merge object
+     *
+     * Giá trị hiện tại:
+     *
+     * ```json
+     * {
+     *   "name": "BlackCat",
+     *   "language": "vi",
+     *   "prefix": "!"
+     * }
+     * ```
+     *
+     * ```ts
+     * await db.update("config", {
+     *     prefix: "?",
+     *     color: "#5865F2"
+     * });
+     * ```
+     *
+     * Kết quả:
+     *
+     * ```json
+     * {
+     *   "name": "BlackCat",
+     *   "language": "vi",
+     *   "prefix": "?",
+     *   "color": "#5865F2"
+     * }
+     * ```
+     *
+     * ---
+     *
+     * ### Ví dụ 4 - Merge mảng và loại bỏ phần tử trùng
+     *
+     * Giá trị hiện tại:
+     *
+     * ```json
+     * [
+     *   {
+     *     "username": "Alice",
+     *     "guild": "123"
+     *   }
+     * ]
+     * ```
+     *
+     * ```ts
+     * await db.update("history", [
+     *     {
+     *         username: "Alice",
+     *         guild: "123"
+     *     },
+     *     {
+     *         username: "Bob",
+     *         guild: "123"
+     *     }
+     * ]);
+     * ```
+     *
+     * Kết quả:
+     *
+     * ```json
+     * [
+     *   {
+     *     "username": "Alice",
+     *     "guild": "123"
+     *   },
+     *   {
+     *     "username": "Bob",
+     *     "guild": "123"
+     *   }
+     * ]
+     * ```
+     *
+     * Phần tử `"Alice"` sẽ không được thêm lần nữa vì đã tồn tại với cùng
+     * `username` và `guild`.
+     *
      * @throws {BlackCatError}
-     * - `REQUIRED_PARAMETER_MISSING` nếu key không được cung cấp
-     * - `INVALID_TYPE` nếu key không phải string
+     * - `REQUIRED_PARAMETER_MISSING` nếu không truyền `key`.
+     * - `INVALID_TYPE` nếu `key` không phải kiểu `string`.
      */
-    update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
+    update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, P>>>;
+    /**
+     * ## Đồng bộ dữ liệu với cơ sở dữ liệu
+     *
+     * ### Chức năng
+     * Đồng bộ dữ liệu tại một đường dẫn (`keys`) với giá trị mới (`value`).
+     *
+     * Hàm sẽ tự động:
+     * - Tạo mới dữ liệu nếu chưa tồn tại.
+     * - So sánh dữ liệu cũ và mới.
+     * - Chỉ cập nhật các trường thực sự thay đổi đối với Object.
+     * - Không thực hiện ghi nếu dữ liệu không thay đổi.
+     *
+     * Điều này giúp giảm số lần ghi xuống cơ sở dữ liệu và tối ưu hiệu năng.
+     *
+     * ---
+     *
+     * ### Cơ chế hoạt động
+     *
+     * 1. Lấy dữ liệu hiện tại bằng `get()`.
+     * 2. Nếu chưa tồn tại (`undefined` hoặc `null`)
+     *    → gọi `set()` để tạo mới.
+     * 3. Nếu truyền hàm `compare` và hàm này trả về `true`
+     *    → bỏ qua đồng bộ.
+     * 4. Nếu dữ liệu không phải Object (hoặc là Array)
+     *    → so sánh bằng `Object.is()`, nếu khác thì gọi `update()`.
+     * 5. Nếu dữ liệu là Object
+     *    → chỉ lấy các thuộc tính thay đổi và cập nhật đúng các trường đó.
+     * 6. Nếu không có trường nào thay đổi thì không ghi dữ liệu.
+     *
+     * ---
+     *
+     * ### Giá trị trả về
+     *
+     * - `undefined`
+     *   - Khi tạo mới dữ liệu.
+     *   - Khi không có thay đổi.
+     *   - Khi dữ liệu nguyên thủy được cập nhật.
+     * - `Partial<ObjectValue<V, P>>`
+     *   - Trả về object chỉ chứa các trường đã được cập nhật khi đồng bộ Object.
+     *
+     * ---
+     *
+     * ### Ví dụ
+     *
+     * ```ts
+     * // Tạo mới nếu chưa tồn tại
+     * await db.syncDatabase({
+     *   keys: "users.1",
+     *   value: {
+     *     name: "BlackCat",
+     *     age: 20
+     *   }
+     * });
+     *
+     * // Chỉ cập nhật trường age
+     * await db.syncDatabase({
+     *   keys: "users.1",
+     *   value: {
+     *     name: "BlackCat",
+     *     age: 21
+     *   }
+     * });
+     *
+     * // Sử dụng compare để bỏ qua đồng bộ
+     * await db.syncDatabase({
+     *   keys: "users.1",
+     *   value: newData,
+     *   compare(oldData, newData) {
+     *     return oldData.version >= newData.version;
+     *   }
+     * });
+     * ```
+     *
+     * @template P Đường dẫn tới dữ liệu trong cơ sở dữ liệu.
+     *
+     * @param options Thông tin đồng bộ.
+     * @param options.keys Đường dẫn của dữ liệu cần đồng bộ.
+     * @param options.value Giá trị mới cần ghi.
+     * @param options.compare Hàm so sánh tùy chỉnh. Nếu trả về `true` thì sẽ không thực hiện đồng bộ.
+     *
+     * @returns
+     * - `undefined` nếu không có thay đổi hoặc dữ liệu được tạo mới.
+     * - `Partial<ObjectValue<V, P>>` chứa các trường đã thay đổi khi cập nhật Object.
+     */
+    syncDatabase<P extends AutocompletableString<ObjectPath<V>>>({ keys, value, compare }: {
+        keys: AutocompletableString<P>;
+        value: ObjectValue<V, P>;
+        compare?: (oldData: ObjectValue<V, P>, newData: ObjectValue<V, P>) => boolean;
+    }): Promise<Partial<ObjectValue<V, P>> | undefined>;
     /**
      * Cộng thêm giá trị vào một key dạng number.
      *
@@ -754,6 +1041,22 @@ declare class Database<V = any> {
      * ```
      */
     subtract<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, numberToSubtract: number): Promise<number>;
+    /**
+     * Thêm một hoặc nhiều phần tử vào đầu array.
+     *
+     * Chỉ thêm những phần tử chưa tồn tại trong array.
+     *
+     * @typeParam P - Path trỏ tới array.
+     *
+     * @param key - Đường dẫn array.
+     * @param values - Một hoặc nhiều phần tử cần thêm.
+     *
+     * @returns Array sau khi thêm.
+     *
+     * @example
+     * await db.unshift("users", newUser);
+     */
+    unshift<P extends ObjectPath<V>>(key: AutocompletableString<P>, ...values: RestOrArray<ExtractFromArray<ObjectValue<V, P>>>): Promise<ExtractFromArray<ObjectValue<V, P>>[]>;
     /**
      * Thêm một hoặc nhiều phần tử vào cuối array tại key-path.
      *
@@ -1519,4 +1822,4 @@ declare class MongoDriver implements DatabaseDriver {
     delete(): Promise<boolean>;
 }
 
-export { Database, JSONDriver, MemoryDriver, MongoDriver, SQLiteDriver };
+export { Database, type DatabaseDriver, JSONDriver, MemoryDriver, MongoDriver, SQLiteDriver };