blackcat.js-database 1.0.6 → 1.0.7

package/dist/index.cjs

@@ -343,9 +343,7 @@ var Database = class {
     const data = await this.get(key);
     if (!query) return data;
     if (!Array.isArray(data)) return null;
-    const result = data.find((item) => {
-      return Object.entries(query).every(([k, v]) => item[k] == v);
-    });
+    const result = data.find((item) => Object.entries(query).every(([k, v]) => item[k] == v));
     return result ?? null;
   }
   /**
@@ -416,23 +414,69 @@ var Database = class {
     await this.driver.set(allDatabase);
   }
   /**
-   * 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 đó.
+   *
+   * 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);
    *
-   * Hỗ trợ nested path bằng dot notation.
+   * @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(),
+   * });
+   */
+  async ensure(key, defaultValue) {
+    const current = await this.get(key);
+    if (current !== null && current !== void 0) return current;
+    await this.set(key, defaultValue);
+    return defaultValue;
+  }
+  /**
+   * 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
    */
   async delete(key) {
     if (typeof key !== "string") {
@@ -464,8 +508,8 @@ var Database = class {
    * await db.deleteAll();
    */
   async deleteAll() {
-    await this.driver.delete();
-    return true;
+    const result = await this.driver.delete();
+    return result;
   }
   /**
    * 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.
@@ -521,25 +565,57 @@ var Database = class {
     return originalLength - filtered.length;
   }
   /**
-   * 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:
+   *
+   * - **Đố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 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.
    *
-   * 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.
+   * - **Các kiểu dữ liệu khác**
+   *   - Giá trị mới sẽ ghi đè hoàn toàn giá trị cũ.
    *
-   * Điều này giúp tránh việc làm mất các thuộc tính đã tồn tại.
+   * Sau khi cập nhật xong, toàn bộ database sẽ được ghi lại thông qua driver.
    *
-   * @template P - Đường dẫn key hợp lệ trong object database.
+   * @template P
+   * Đường dẫn hợp lệ của object trong database.
    *
-   * @param key - Đường dẫn tới giá trị cần cập nhật.
-   * Hỗ trợ nested path dạng `"a.b.c"`.
+   * @param key
+   * Đường dẫn cần cập nhật.
    *
-   * @param value - Giá trị mới sẽ được cập nhật tại key.
+   * 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
    * {
@@ -551,10 +627,9 @@ var Database = class {
    * }
    * ```
    *
-   * Cập nhật:
    * ```ts
    * await db.update("123", {
-   *   history: [1,2,3]
+   *     history: [1, 2, 3]
    * });
    * ```
    *
@@ -564,14 +639,120 @@ var Database = class {
    *   "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`.
    */
   async update(key, value) {
     if (!key) {
@@ -591,9 +772,13 @@ var Database = class {
       current = current[part];
     }
     const lastKey = keys[keys.length - 1];
-    if (isObject(value) && isObject(current[lastKey])) {
+    const currentValue = current[lastKey];
+    if (Array.isArray(value) && Array.isArray(currentValue)) {
+      const unique = value.filter((item) => !currentValue.some((existing) => existing.username === item.username && existing.guild === item.guild));
+      current[lastKey] = [...currentValue, ...unique];
+    } else if (isObject(value) && isObject(currentValue)) {
       current[lastKey] = {
-        ...current[lastKey],
+        ...currentValue,
         ...value
       };
     } else {
@@ -602,6 +787,114 @@ var Database = class {
     await this.driver.set(allDatabase);
     return current[lastKey];
   }
+  /**
+   * ## Đồ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.
+   */
+  async syncDatabase({ keys, value, compare }) {
+    const oldValue = await this.get(keys);
+    if (oldValue === void 0 || oldValue === null) {
+      await this.set(keys, value);
+      return;
+    }
+    if (compare?.(oldValue, value)) return;
+    if (!isObject(oldValue) || !isObject(value) || Array.isArray(oldValue) || Array.isArray(value)) {
+      if (!Object.is(oldValue, value)) {
+        await this.update(keys, value);
+      }
+      return;
+    }
+    const changed = {};
+    for (const k in value) {
+      const field = k;
+      if (!Object.is(oldValue[field], value[field])) {
+        changed[field] = value[field];
+      }
+    }
+    if (Object.keys(changed).length === 0) return;
+    await this.update(keys, changed);
+    return changed;
+  }
   /**
    * Cộng thêm giá trị vào một key dạng number.
    *
@@ -664,6 +957,46 @@ var Database = class {
     await this.set(key, targetNumber - numberToSubtract);
     return targetNumber - numberToSubtract;
   }
+  /**
+   * 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);
+   */
+  async unshift(key, ...values) {
+    if (!values.length) {
+      throw new BlackCatError("REQUIRED_PARAMETER_MISSING", "values");
+    }
+    const root = await this.all();
+    const pathParts = key.split(".");
+    let target = root;
+    for (let i = 0; i < pathParts.length; i++) {
+      const part = pathParts[i];
+      if (!(part in target)) {
+        throw new BlackCatError("INVALID_KEY", key);
+      }
+      if (i === pathParts.length - 1) {
+        if (!Array.isArray(target[part])) {
+          throw new BlackCatError("INVALID_TARGET", "array", typeOf(target[part]));
+        }
+        const uniqueValues = values.filter((v) => !target[part].includes(v));
+        target[part].unshift(...uniqueValues);
+      } else {
+        target = target[part];
+      }
+    }
+    await this.set(pathParts[0], root[pathParts[0]]);
+    return target[pathParts[pathParts.length - 1]];
+  }
   /**
    * Thêm một hoặc nhiều phần tử vào cuối array tại key-path.
    *