blackcat.js-database 1.0.4 → 1.0.6

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`.
@@ -111,7 +113,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;
 /**
@@ -308,26 +335,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`.
@@ -369,7 +376,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
@@ -399,7 +406,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
@@ -479,7 +486,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.
      *
@@ -508,7 +515,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.
      *
@@ -545,7 +552,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.
      *
@@ -574,7 +581,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
@@ -586,7 +593,7 @@ 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.
      *
@@ -715,7 +722,7 @@ declare class Database<V = any> {
      * - `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>>;
+    update<P extends AutocompletableString<ObjectPath<V>>>(key: AutocompletableString<P>, value: ObjectValue<V, P>): Promise<If<IsObject<V>, ObjectValue<V, P>>>;
     /**
      * Cộng thêm giá trị vào một key dạng number.
      *
@@ -1310,6 +1317,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 +1386,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 +1423,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 +1463,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 +1482,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);
+     *          }
      *      })
      * });
      */
@@ -1423,4 +1524,4 @@ declare class MongoDriver implements DatabaseDriver {
     delete(): Promise<boolean>;
 }
 
-export { Database, JSONDriver, MemoryDriver, MongoDriver, SQLiteDriver };
+export { Database, type DatabaseDriver, JSONDriver, MemoryDriver, MongoDriver, SQLiteDriver };