blackcat.js-database 1.0.3 → 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
@@ -663,25 +665,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 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
      */
     update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
     /**
@@ -1278,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.
  */
@@ -1300,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.
@@ -1322,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);
+ *          }
  *      })
  * });
  * ```
@@ -1352,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.
      *
@@ -1359,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
@@ -663,25 +665,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 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
      */
     update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, FirstObjectKey<P>>, V>>;
     /**
@@ -1278,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.
  */
@@ -1300,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.
@@ -1322,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);
+ *          }
  *      })
  * });
  * ```
@@ -1352,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.
      *
@@ -1359,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);
+     *          }
      *      })
      * });
      */