blackcat.js-database 1.0.3 → 1.0.5

package/dist/index.mjs

@@ -4,12 +4,16 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/utils/isObject.function.ts
-var isObject = /* @__PURE__ */ __name((item) => !Array.isArray(item) && item !== null && typeof item == "object", "isObject");
+var isObject = /* @__PURE__ */ __name((item) => !Array.isArray(item) && item !== null && typeof item === "object", "isObject");
 
 // src/utils/typeOf.function.ts
 var typeOf = /* @__PURE__ */ __name((input) => {
-  if (input == null || typeof input === "number" && Number.isNaN(input)) return String(input);
-  if (typeof input === "function" && input.prototype) return `${input.name} class instance`;
+  if (input == null || typeof input === "number" && Number.isNaN(input)) {
+    return String(input);
+  }
+  if (typeof input === "function" && input.prototype) {
+    return `${input.name} class instance`;
+  }
   return input?.constructor?.name ?? typeof input;
 }, "typeOf");
 
@@ -18,20 +22,12 @@ var isNumber = /* @__PURE__ */ __name((input) => !isNaN(input) && input !== "" &
 
 // src/utils/BlackCatError.ts
 var errors = {
-  DEVICE_IS_OFFLINE: "Your device appears to be offline so it's impossible to proceed with connection to your online MongoDB cluster. Please connect your device to the internet or switch to the local MongoDB database and try again.",
-  CONNECTION_NOT_ESTABLISHED: "Failed to connect to MongoDB. Please double-check the specified connection URI and make sure that you're performing the database connection using the `QuickMongoClient.connect()` method.",
-  CONNECTION_URI_NOT_SPECIFIED: "The MongoDB connection URI must be specified.",
-  INVALID_CONNECTION_URI: "The specified MongoDB connection URI is invalid.",
-  UNKNOWN_ERROR: "Unknown error.",
-  REQUIRED_PARAMETER_MISSING: "'{1}' parameter is required but is missing.",
-  REQUIRED_CONSTRUCTOR_PARAMETER_MISSING: "'{1}' parameter in constructor '{2}' is required but is missing.",
-  INVALID_CONSTRUCTOR_PARAMETER_TYPE: "'{1}' parameter in constructor '{2}' must be a type of {3}. Received type: {4}.",
-  INVALID_TYPE: "'{1}' must be a type of {2}. Received type: {3}.",
-  ONE_OR_MORE_ARRAY_TYPES_INVALID: "All specified elements from array in '{1}' parameter must be a type of {2}. Received array of types: {3}.",
-  INVALID_TARGET: "The target in database must be a type of {1}. Received target type: {2}.",
-  INVALID_KEY: "{1}",
-  INVALID_PARAMETER: "{1} {2}",
-  DATABASE_CONNECTION_FAILED: "{1}"
+  UNKNOWN_ERROR: "L\u1ED7i kh\xF4ng x\xE1c \u0111\u1ECBnh.",
+  REQUIRED_PARAMETER_MISSING: "Tham s\u1ED1 '{1}' l\xE0 b\u1EAFt bu\u1ED9c nh\u01B0ng ch\u01B0a \u0111\u01B0\u1EE3c cung c\u1EA5p.",
+  INVALID_TYPE: "'{1}' ph\u1EA3i c\xF3 ki\u1EC3u {2}. Ki\u1EC3u nh\u1EADn \u0111\u01B0\u1EE3c: {3}.",
+  ONE_OR_MORE_ARRAY_TYPES_INVALID: "T\u1EA5t c\u1EA3 ph\u1EA7n t\u1EED trong m\u1EA3ng c\u1EE7a tham s\u1ED1 '{1}' ph\u1EA3i c\xF3 ki\u1EC3u {2}. C\xE1c ki\u1EC3u nh\u1EADn \u0111\u01B0\u1EE3c trong m\u1EA3ng: {3}.",
+  INVALID_TARGET: "\u0110\u1ED1i t\u01B0\u1EE3ng target trong database ph\u1EA3i c\xF3 ki\u1EC3u {1}. Ki\u1EC3u nh\u1EADn \u0111\u01B0\u1EE3c: {2}.",
+  INVALID_KEY: "{1}"
 };
 var createTypesArray = /* @__PURE__ */ __name((...elements) => `[${elements.map((element) => typeOf(element))}]`, "createTypesArray");
 var _BlackCatError = class _BlackCatError extends Error {
@@ -57,46 +53,107 @@ var BlackCatError = _BlackCatError;
 // src/utils/TypedObject.ts
 var _TypedObject = class _TypedObject {
   /**
-   * Returns the names of the enumerable string properties and methods of an object.
+   * Lấy danh sách key của object với type chính xác.
+   *
+   * @typeParam TObject - Kiểu object đầu vào
+   *
+   * @param obj - Object cần lấy key
+   * @returns Mảng các key của object (`ExtractObjectKeys<TObject>[]`)
+   *
+   * @remarks
+   * Khác với `Object.keys`:
+   * - `Object.keys(obj)` → `string[]`
+   * - `TypedObject.keys(obj)` → union key chính xác
    *
-   * Type parameters:
+   * ---
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object keys types from.
+   * ### Lưu ý:
+   * - Nếu `obj` là `null` hoặc `undefined`, sẽ fallback thành `{}` → trả về `[]`
    *
-   * @param {TObject} obj Object to get the keys from.
+   * ---
    *
-   * @returns {Array<ExtractObjectKeys<TObject>>}
-   * Array of names of the enumerable string properties and methods of the specified object.
+   * @example
+   * ```ts
+   * const obj = { a: 1, b: 2 };
+   *
+   * const keys = TypedObject.keys(obj);
+   * // ("a" | "b")[]
+   * ```
+   *
+   * @see Object.keys
    */
   static keys(obj) {
     return Object.keys(obj || {});
   }
   /**
-   * Returns an array of values of the enumerable properties of an object.
+   * Lấy danh sách value của object với type chính xác.
+   *
+   * @typeParam TObject - Kiểu object đầu vào
+   *
+   * @param obj - Object cần lấy value
+   * @returns Mảng các value của object (`ExtractObjectValues<TObject>[]`)
+   *
+   * @remarks
+   * Khác với `Object.values`:
+   * - `Object.values(obj)` → `any[]`
+   * - `TypedObject.values(obj)` → union value chính xác
    *
-   * Type parameters:
+   * ---
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object values types from.
+   * ### Lưu ý:
+   * - Nếu `obj` là `null` hoặc `undefined`, sẽ fallback thành `{}` → trả về `[]`
+   *
+   * ---
+   *
+   * @example
+   * ```ts
+   * const obj = { a: 1, b: 2 };
    *
-   * @param {TObject} obj Object to get the values from.
+   * const values = TypedObject.values(obj);
+   * // number[]
+   * ```
    *
-   * @returns {Array<ExtractObjectValues<TObject>>}
-   * Array of values of the enumerable properties of the specified object.
+   * @see Object.values
    */
   static values(obj) {
     return Object.values(obj || {});
   }
   /**
-   * Returns an array of entries (key-value pairs) of the enumerable properties of an object.
+   * Lấy danh sách entry (key-value) của object với type chính xác.
+   *
+   * @typeParam TObject - Kiểu object đầu vào
+   *
+   * @param obj - Object cần lấy entries
+   * @returns Mảng các cặp `[key, value]` (`ExtractObjectEntries<TObject>[]`)
+   *
+   * @remarks
+   * Khác với `Object.entries`:
+   * - `Object.entries(obj)` → `[string, any][]`
+   * - `TypedObject.entries(obj)` → typed tuple chính xác
+   *
+   * ---
    *
-   * Type parameters:
+   * ### Lưu ý:
+   * - Nếu `obj` là `null` hoặc `undefined`, sẽ fallback thành `{}` → trả về `[]`
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object entries types (key-value pairs types) from.
+   * ---
    *
-   * @param {TObject} obj Object to get the entries from.
+   * @example
+   * ```ts
+   * const obj = { a: 1, b: 2 };
+   *
+   * const entries = TypedObject.entries(obj);
+   * // ["a" | "b", number][]
+   * ```
    *
-   * @returns {ExtractObjectEntries<TObject>[]}
-   * Array of entries (key-value pairs) of the enumerable properties of the specified object.
+   * @example
+   * ```ts
+   * for (const [key, value] of TypedObject.entries(obj)) {
+   *   // key & value được infer đúng type
+   * }
+   * ```
+   *
+   * @see Object.entries
    */
   static entries(obj) {
     return Object.entries(obj || {});
@@ -105,9 +162,6 @@ var _TypedObject = class _TypedObject {
 __name(_TypedObject, "TypedObject");
 var TypedObject = _TypedObject;
 
-// src/utils/Emitter.ts
-import { EventEmitter } from "events";
-
 // src/Database.ts
 var _Database = class _Database {
   /**
@@ -428,41 +482,86 @@ var _Database = class _Database {
     return originalLength - filtered.length;
   }
   /**
-   * Cập nhật giá trị của một key-path trong database.
+   * Cập nhật dữ liệu trong database theo đường dẫn key.
    *
-   * 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.
+   * 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.
    *
-   * Nếu các object trung gian trong path chưa tồn tại
-   * thì chúng sẽ được tự động tạo.
+   * Điều này giúp tránh việc làm mất các thuộc tính đã tồn tại.
    *
-   * @template P Key path trong database.
+   * @template P - Đường dẫn key hợp lệ trong object database.
    *
-   * @param key Đường dẫn dữ liệu cần cập nhật.
-   * @param value Giá trị mới.
+   * @param key - Đường dẫn tới giá trị cần cập nhật.
+   * Hỗ trợ nested path dạng `"a.b.c"`.
    *
-   * @returns Object cha của key vừa cập nhật.
+   * @param value - Giá trị mới sẽ được cập nhật tại key.
+   *
+   * @returns
+   * Trả về giá trị cuối cùng sau khi cập nhật.
    *
    * @example
+   * Database ban đầu:
+   * ```json
+   * {
+   *   "123": {
+   *     "guildID": "123",
+   *     "guildName": "BlackCat",
+   *     "history": []
+   *   }
+   * }
+   * ```
+   *
+   * Cập nhật:
    * ```ts
-   * await db.update("users.123.name", "Alice");
+   * await db.update("123", {
+   *   history: [1,2,3]
+   * });
    * ```
+   *
+   * Kết quả:
+   * ```json
+   * {
+   *   "123": {
+   *     "guildID": "123",
+   *     "guildName": "BlackCat",
+   *     "history": [1,2,3]
+   *   }
+   * }
+   * ```
+   *
+   * @throws {BlackCatError}
+   * - `REQUIRED_PARAMETER_MISSING` nếu key không được cung cấp
+   * - `INVALID_TYPE` nếu key không phải string
    */
   async update(key, value) {
+    if (!key) {
+      throw new BlackCatError("REQUIRED_PARAMETER_MISSING", "key");
+    }
+    if (typeof key !== "string") {
+      throw new BlackCatError("INVALID_TYPE", "key", "string", typeOf(key));
+    }
     const allDatabase = await this.all();
     const keys = key.split(".");
     let current = allDatabase;
     for (let i = 0; i < keys.length - 1; i++) {
       const part = keys[i];
-      if (!(part in current)) {
+      if (!isObject(current[part])) {
         current[part] = {};
       }
       current = current[part];
     }
     const lastKey = keys[keys.length - 1];
-    current[lastKey] = value;
+    if (isObject(value) && isObject(current[lastKey])) {
+      current[lastKey] = {
+        ...current[lastKey],
+        ...value
+      };
+    } else {
+      current[lastKey] = value;
+    }
     await this.driver.set(allDatabase);
-    return current;
+    return current[lastKey];
   }
   /**
    * Cộng thêm giá trị vào một key dạng number.
@@ -1139,11 +1238,21 @@ var _MongoDriver = class _MongoDriver {
    * 
    * @example 
    * ```ts
+   * import { Database, MongoDriver } from "blackcat.js-database";
+   * 
    * const database = new Database({ 
    *      driver: new MongoDriver({
    *          mongourl: "mongodb://localhost:27017", 
    *          databaseName: "mydb",  
-   *          collectionName: "store" 
+   *          collectionName: "store",
+   *          onLoad: ({ db, collection, databaseName }) => {
+   *              console.log(`✅ Đã kết nối với cơ sở dữ liệu: ${databaseName}`);
+   *              console.log(`📦 Bộ sưu tập: ${collection.collectionName}`);
+   *          },
+   *          onError: ({ error, databaseName }) => {
+   *              console.error(`❌ Không thể kết nối với cơ sở dữ liệu: ${databaseName}`); 
+   *              console.error(error);
+   *          }
    *      })
    * });
    */
@@ -1168,6 +1277,18 @@ var _MongoDriver = class _MongoDriver {
      * Tên collection MongoDB.
      */
     __publicField(this, "collectionName");
+    /**
+     * Callback khi kết nối thành công.
+     */
+    __publicField(this, "onLoad");
+    /**
+     * Callback khi xảy ra lỗi.
+     */
+    __publicField(this, "onError");
+    /**
+     * Trạng thái đã gọi onLoad chưa (tránh spam)
+     */
+    __publicField(this, "isLoaded", false);
     const {
       mongourl = "mongodb://localhost:27017",
       databaseName = "database",
@@ -1176,21 +1297,42 @@ var _MongoDriver = class _MongoDriver {
     this.client = new MongoClient(mongourl);
     this.databaseName = databaseName;
     this.collectionName = collectionName;
+    this.onLoad = options.onLoad;
+    this.onError = options.onError;
   }
   /**
    * Thiết lập kết nối MongoDB nếu chưa kết nối.
    */
   async connect() {
     if (!this.db) {
-      await this.client.connect();
-      this.db = this.client.db(this.databaseName);
-      this.collection = this.db.collection(this.collectionName);
-      const doc = await this.collection.findOne({ _id: "database" });
-      if (!doc) {
-        await this.collection.insertOne({
-          _id: "database",
-          data: {}
+      try {
+        await this.client.connect();
+        this.db = this.client.db(this.databaseName);
+        this.collection = this.db.collection(this.collectionName);
+        const doc = await this.collection.findOne({ _id: "database" });
+        if (!doc) {
+          await this.collection.insertOne({
+            _id: "database",
+            data: {}
+          });
+        }
+        if (!this.isLoaded) {
+          this.isLoaded = true;
+          this.onLoad?.({
+            client: this.client,
+            db: this.db,
+            collection: this.collection,
+            databaseName: this.databaseName,
+            collectionName: this.collectionName
+          });
+        }
+      } catch (error) {
+        this.onError?.({
+          error,
+          databaseName: this.databaseName,
+          collectionName: this.collectionName
         });
+        throw error;
       }
     }
   }