blackcat.js-database 1.0.4 → 1.0.5

package/README.md

@@ -349,10 +349,20 @@ import { Database, MongoDriver } from "blackcat.js-database";
 
 const database = new Database({ 
     driver: new MongoDriver({
-        mongourl: "mongodb://localhost:27017", 
-        databaseName: "mydb",  
-        collectionName: "store" 
-    })
+        mongourl: "mongourl",
+        databaseName: "BlackCat-Club",
+        collectionName: "database-test",
+        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}`);
+            // Ví dụ advanced:
+            // db.command({ ping: 1 })
+        },
+        onError: ({ error, databaseName }) => {
+            console.error(`❌ Không thể kết nối với cơ sở dữ liệu: ${databaseName}`);
+            console.error(error);
+        }
+    }),
 });
 ```
 ---

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { MongoClient, Db, Collection } from 'mongodb';
+
 /**
  * Interface định nghĩa contract cho các storage driver
  * được sử dụng bởi class `Database`.
@@ -369,7 +371,7 @@ type FirstObjectKey<TKey extends ObjectPath<string, any>> = TKey extends `${infe
  * // "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;
+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 ? NonNullable<T[TKey]> extends Array<any> ? TKey : NonNullable<T[TKey]> extends Record<string, any> ? `${TKey}` | `${TKey}.${ObjectPath<NonNullable<T[TKey]>>}` : TKey : never;
 /**
  * Trích xuất kiểu dữ liệu của giá trị tại một object path.
  * @hidden
@@ -1310,6 +1312,53 @@ declare class SQLiteDriver implements DatabaseDriver {
     delete(): Promise<boolean>;
 }
 
+/**
+ * Context được truyền vào callback `onLoad` của MongoDriver.
+ * @hidden
+ */
+interface MongoDriverOnLoadContext {
+    /**
+     * Instance MongoClient đã kết nối.
+     */
+    client: MongoClient;
+    /**
+     * Database hiện tại.
+     */
+    db: Db;
+    /**
+     * Collection đang được sử dụng.
+     */
+    collection: Collection<DatabaseDocument>;
+    /**
+     * Tên database.
+     */
+    databaseName: string;
+    /**
+     * Tên collection.
+     */
+    collectionName: string;
+}
+/**
+ * Context được truyền vào callback `onError` của MongoDriver.
+ * @hidden
+ */
+interface MongoDriverOnErrorContext {
+    /**
+     * Lỗi phát sinh.
+     *
+     * Có thể là bất kỳ kiểu nào (`unknown`),
+     * nên cần type guard hoặc cast khi xử lý.
+     */
+    error: unknown;
+    /**
+     * Tên database tại thời điểm xảy ra lỗi.
+     */
+    databaseName: string;
+    /**
+     * Tên collection tại thời điểm xảy ra lỗi.
+     */
+    collectionName: string;
+}
 /**
  * Cấu hình cho MongoDriver.
  */
@@ -1332,6 +1381,21 @@ interface MongoDriverOptions {
      * @default "json_store"
      */
     collectionName?: string;
+    /**
+     * Callback khi kết nối thành công.
+     */
+    onLoad?: (ctx: MongoDriverOnLoadContext) => any;
+    /**
+     * Callback khi xảy ra lỗi.
+     */
+    onError?: (ctx: MongoDriverOnErrorContext) => any;
+}
+/**
+ * Schema document dùng để lưu trữ database trong MongoDB.
+ */
+interface DatabaseDocument<V = any> {
+    _id: string;
+    data: V;
 }
 /**
  * Driver lưu trữ dữ liệu bằng MongoDB.
@@ -1354,11 +1418,21 @@ interface MongoDriverOptions {
  *
  * @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);
+ *          }
  *      })
  * });
  * ```
@@ -1384,6 +1458,18 @@ declare class MongoDriver implements DatabaseDriver {
      * Tên collection MongoDB.
      */
     private collectionName;
+    /**
+     * Callback khi kết nối thành công.
+     */
+    onLoad?: (ctx: MongoDriverOnLoadContext) => any;
+    /**
+     * Callback khi xảy ra lỗi.
+     */
+    onError?: (ctx: MongoDriverOnErrorContext) => any;
+    /**
+     * Trạng thái đã gọi onLoad chưa (tránh spam)
+     */
+    private isLoaded;
     /**
      * Khởi tạo MongoDriver.
      *
@@ -1391,11 +1477,21 @@ declare class MongoDriver implements DatabaseDriver {
      *
      * @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);
+     *          }
      *      })
      * });
      */

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { MongoClient, Db, Collection } from 'mongodb';
+
 /**
  * Interface định nghĩa contract cho các storage driver
  * được sử dụng bởi class `Database`.
@@ -369,7 +371,7 @@ type FirstObjectKey<TKey extends ObjectPath<string, any>> = TKey extends `${infe
  * // "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;
+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 ? NonNullable<T[TKey]> extends Array<any> ? TKey : NonNullable<T[TKey]> extends Record<string, any> ? `${TKey}` | `${TKey}.${ObjectPath<NonNullable<T[TKey]>>}` : TKey : never;
 /**
  * Trích xuất kiểu dữ liệu của giá trị tại một object path.
  * @hidden
@@ -1310,6 +1312,53 @@ declare class SQLiteDriver implements DatabaseDriver {
     delete(): Promise<boolean>;
 }
 
+/**
+ * Context được truyền vào callback `onLoad` của MongoDriver.
+ * @hidden
+ */
+interface MongoDriverOnLoadContext {
+    /**
+     * Instance MongoClient đã kết nối.
+     */
+    client: MongoClient;
+    /**
+     * Database hiện tại.
+     */
+    db: Db;
+    /**
+     * Collection đang được sử dụng.
+     */
+    collection: Collection<DatabaseDocument>;
+    /**
+     * Tên database.
+     */
+    databaseName: string;
+    /**
+     * Tên collection.
+     */
+    collectionName: string;
+}
+/**
+ * Context được truyền vào callback `onError` của MongoDriver.
+ * @hidden
+ */
+interface MongoDriverOnErrorContext {
+    /**
+     * Lỗi phát sinh.
+     *
+     * Có thể là bất kỳ kiểu nào (`unknown`),
+     * nên cần type guard hoặc cast khi xử lý.
+     */
+    error: unknown;
+    /**
+     * Tên database tại thời điểm xảy ra lỗi.
+     */
+    databaseName: string;
+    /**
+     * Tên collection tại thời điểm xảy ra lỗi.
+     */
+    collectionName: string;
+}
 /**
  * Cấu hình cho MongoDriver.
  */
@@ -1332,6 +1381,21 @@ interface MongoDriverOptions {
      * @default "json_store"
      */
     collectionName?: string;
+    /**
+     * Callback khi kết nối thành công.
+     */
+    onLoad?: (ctx: MongoDriverOnLoadContext) => any;
+    /**
+     * Callback khi xảy ra lỗi.
+     */
+    onError?: (ctx: MongoDriverOnErrorContext) => any;
+}
+/**
+ * Schema document dùng để lưu trữ database trong MongoDB.
+ */
+interface DatabaseDocument<V = any> {
+    _id: string;
+    data: V;
 }
 /**
  * Driver lưu trữ dữ liệu bằng MongoDB.
@@ -1354,11 +1418,21 @@ interface MongoDriverOptions {
  *
  * @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);
+ *          }
  *      })
  * });
  * ```
@@ -1384,6 +1458,18 @@ declare class MongoDriver implements DatabaseDriver {
      * Tên collection MongoDB.
      */
     private collectionName;
+    /**
+     * Callback khi kết nối thành công.
+     */
+    onLoad?: (ctx: MongoDriverOnLoadContext) => any;
+    /**
+     * Callback khi xảy ra lỗi.
+     */
+    onError?: (ctx: MongoDriverOnErrorContext) => any;
+    /**
+     * Trạng thái đã gọi onLoad chưa (tránh spam)
+     */
+    private isLoaded;
     /**
      * Khởi tạo MongoDriver.
      *
@@ -1391,11 +1477,21 @@ declare class MongoDriver implements DatabaseDriver {
      *
      * @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);
+     *          }
      *      })
      * });
      */

package/dist/index.js

@@ -42,12 +42,16 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // 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");
 
@@ -56,20 +60,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 {
@@ -95,46 +91,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
    *
-   * Type parameters:
+   * @param obj - Object cần lấy key
+   * @returns Mảng các key của object (`ExtractObjectKeys<TObject>[]`)
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object keys types from.
+   * @remarks
+   * Khác với `Object.keys`:
+   * - `Object.keys(obj)` → `string[]`
+   * - `TypedObject.keys(obj)` → union key chính xác
    *
-   * @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.
+   * ### Lưu ý:
+   * - Nếu `obj` là `null` hoặc `undefined`, sẽ fallback thành `{}` → trả về `[]`
+   *
+   * ---
+   *
+   * @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
    *
-   * Type parameters:
+   * @param obj - Object cần lấy value
+   * @returns Mảng các value của object (`ExtractObjectValues<TObject>[]`)
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object values types from.
+   * @remarks
+   * Khác với `Object.values`:
+   * - `Object.values(obj)` → `any[]`
+   * - `TypedObject.values(obj)` → union value chính xác
    *
-   * @param {TObject} obj Object to get the values from.
+   * ---
    *
-   * @returns {Array<ExtractObjectValues<TObject>>}
-   * Array of values of the enumerable properties of the specified object.
+   * ### Lưu ý:
+   * - Nếu `obj` là `null` hoặc `undefined`, sẽ fallback thành `{}` → trả về `[]`
+   *
+   * ---
+   *
+   * @example
+   * ```ts
+   * const obj = { a: 1, b: 2 };
+   *
+   * const values = TypedObject.values(obj);
+   * // number[]
+   * ```
+   *
+   * @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:
+   * ---
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object entries types (key-value pairs 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 entries from.
+   * ---
    *
-   * @returns {ExtractObjectEntries<TObject>[]}
-   * Array of entries (key-value pairs) of the enumerable properties of the specified object.
+   * @example
+   * ```ts
+   * const obj = { a: 1, b: 2 };
+   *
+   * const entries = TypedObject.entries(obj);
+   * // ["a" | "b", number][]
+   * ```
+   *
+   * @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 || {});
@@ -143,9 +200,6 @@ var _TypedObject = class _TypedObject {
 __name(_TypedObject, "TypedObject");
 var TypedObject = _TypedObject;
 
-// src/utils/Emitter.ts
-var import_node_events = require("events");
-
 // src/Database.ts
 var _Database = class _Database {
   /**
@@ -1222,11 +1276,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);
+   *          }
    *      })
    * });
    */
@@ -1251,6 +1315,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",
@@ -1259,21 +1335,42 @@ var _MongoDriver = class _MongoDriver {
     this.client = new import_mongodb.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;
       }
     }
   }