blackcat.js-database 1.0.4 → 1.0.6

package/README.md

@@ -331,6 +331,8 @@ const db = new Database({
 
 # JSON Driver (ví dụ)
 
+Driver lưu dữ liệu trong file json.
+
 ```ts
 import { Database, JSONDriver } from "blackcat.js-database";
 
@@ -344,21 +346,35 @@ const database = new Database({
 
 # Mongo Driver (ví dụ)
 
+Driver lưu dữ liệu trong mongoose.
+
 ```ts
 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);
+        }
+    }),
 });
 ```
 ---
 
 # SQLite Driver (ví dụ)
 
+Driver lưu dữ liệu trong SQLite.
+
 ```ts
 import { Database, SQLiteDriver } from "blackcat.js-database";
 
@@ -372,7 +388,6 @@ const database = new Database({
 ---
 
 
-
 # Tạo Custom Driver
 
 Bạn có thể tạo driver riêng bằng cách implement `DatabaseDriver`.

package/dist/{index.js → index.cjs}

@@ -5,7 +5,6 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 var __export = (target, all) => {
   for (var name in all)
@@ -28,7 +27,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/index.ts
 var index_exports = {};
@@ -42,12 +40,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,23 +58,18 @@ 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 {
+var BlackCatError = class extends Error {
+  static {
+    __name(this, "BlackCatError");
+  }
   /**  
    * Creates a BlackCatError instance.
    * @param {string} errorCode Quick Mongo error code.
@@ -89,65 +86,138 @@ var _BlackCatError = class _BlackCatError extends Error {
     this.name = `BlackCatError [${code}]`;
   }
 };
-__name(_BlackCatError, "BlackCatError");
-var BlackCatError = _BlackCatError;
 
 // src/utils/TypedObject.ts
-var _TypedObject = class _TypedObject {
+var TypedObject = class {
+  static {
+    __name(this, "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
+   *
+   * ---
+   *
+   * ### 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 keys from.
+   * const keys = TypedObject.keys(obj);
+   * // ("a" | "b")[]
+   * ```
    *
-   * @returns {Array<ExtractObjectKeys<TObject>>}
-   * Array of names of the enumerable string properties and methods of the specified object.
+   * @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ề `[]`
    *
-   * @param {TObject} obj Object to get the values from.
+   * ---
+   *
+   * @example
+   * ```ts
+   * const obj = { a: 1, b: 2 };
+   *
+   * 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.
    *
-   * Type parameters:
+   * @typeParam TObject - Kiểu object đầu vào
    *
-   * - `TObject` (`Record<string, any>`) - The object to get the object entries types (key-value pairs types) from.
+   * @param obj - Object cần lấy entries
+   * @returns Mảng các cặp `[key, value]` (`ExtractObjectEntries<TObject>[]`)
    *
-   * @param {TObject} obj Object to get the entries from.
+   * @remarks
+   * Khác với `Object.entries`:
+   * - `Object.entries(obj)` → `[string, any][]`
+   * - `TypedObject.entries(obj)` → typed tuple chính xác
    *
-   * @returns {ExtractObjectEntries<TObject>[]}
-   * Array of entries (key-value pairs) 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 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 || {});
   }
 };
-__name(_TypedObject, "TypedObject");
-var TypedObject = _TypedObject;
-
-// src/utils/Emitter.ts
-var import_node_events = require("events");
 
 // src/Database.ts
-var _Database = class _Database {
+var Database = class {
+  static {
+    __name(this, "Database");
+  }
+  /**
+   * Storage driver được sử dụng để đọc và ghi dữ liệu database.
+   *
+   * Driver phải implement interface `DatabaseDriver`.
+   *
+   * Ví dụ:
+   * ```ts
+   * const db = new Database({
+   *   driver: new JSONDriver({ filePath: "./database.json" }),
+   * })
+   * ```
+   */
+  driver;
   /**
    * Khởi tạo Database instance.
    *
@@ -173,19 +243,6 @@ var _Database = class _Database {
    * ```
    */
   constructor(options) {
-    /**
-     * Storage driver được sử dụng để đọc và ghi dữ liệu database.
-     *
-     * Driver phải implement interface `DatabaseDriver`.
-     *
-     * Ví dụ:
-     * ```ts
-     * const db = new Database({
-     *   driver: new JSONDriver({ filePath: "./database.json" }),
-     * })
-     * ```
-     */
-    __publicField(this, "driver");
     this.driver = options.driver;
   }
   /**
@@ -234,7 +291,6 @@ var _Database = class _Database {
    */
   async get(key) {
     const data = await this.all();
-    if (key === void 0) return data;
     if (typeof key !== "string") {
       throw new BlackCatError("INVALID_TYPE", "key", "string", typeOf(key));
     }
@@ -323,7 +379,7 @@ var _Database = class _Database {
    * @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
@@ -358,7 +414,6 @@ var _Database = class _Database {
     }
     ;
     await this.driver.set(allDatabase);
-    return typeof value == "object" && value !== null ? await this.get(keys[0]) : value;
   }
   /**
    * Xóa một key khỏi database.
@@ -575,7 +630,8 @@ var _Database = class _Database {
     if (!isNumber(numberToAdd)) {
       throw new BlackCatError("INVALID_TYPE", "numberToAdd", "number", typeOf(numberToAdd));
     }
-    return await this.set(key, targetNumber + numberToAdd);
+    await this.set(key, targetNumber + numberToAdd);
+    return targetNumber + numberToAdd;
   }
   /**
    * Trừ giá trị khỏi một key dạng number.
@@ -605,7 +661,8 @@ var _Database = class _Database {
     if (!isNumber(numberToSubtract)) {
       throw new BlackCatError("INVALID_TYPE", "numberToSubtract", "number", typeOf(numberToSubtract));
     }
-    return await this.set(key, targetNumber - numberToSubtract);
+    await this.set(key, targetNumber - numberToSubtract);
+    return targetNumber - numberToSubtract;
   }
   /**
    * Thêm một hoặc nhiều phần tử vào cuối array tại key-path.
@@ -823,7 +880,8 @@ var _Database = class _Database {
    * const userKeys = await db.keys("user");
    */
   async keys(key) {
-    if (!key) return TypedObject.keys(await this.all());
+    const all = await this.all();
+    if (!key) return TypedObject.keys(all);
     const data = await this.get(key);
     return TypedObject.keys(data).filter((key2) => data[key2] !== void 0 && data[key2] !== null);
   }
@@ -857,7 +915,8 @@ var _Database = class _Database {
    * const userValues = await db.values("users");
    */
   async values(key) {
-    if (!key) return TypedObject.values(await this.all());
+    const all = await this.all();
+    if (!key) return TypedObject.values(all);
     const data = await this.get(key);
     return TypedObject.values(data);
   }
@@ -982,12 +1041,21 @@ var _Database = class _Database {
     return values.every(queryFunction);
   }
 };
-__name(_Database, "Database");
-var Database = _Database;
 
 // src/drivers/JSONDriver.ts
 var import_fs = require("fs");
-var _JSONDriver = class _JSONDriver {
+var JSONDriver = class {
+  static {
+    __name(this, "JSONDriver");
+  }
+  /**
+   * Đường dẫn tới file database JSON.
+   */
+  filePath;
+  /**
+   * Cho biết có minify JSON khi ghi file hay không.
+   */
+  minifyJSON;
   /**
    * Khởi tạo một instance mới của {@link JSONDriver}.
    *
@@ -1009,14 +1077,6 @@ var _JSONDriver = class _JSONDriver {
    * ```
    */
   constructor(options) {
-    /**
-     * Đường dẫn tới file database JSON.
-     */
-    __publicField(this, "filePath");
-    /**
-     * Cho biết có minify JSON khi ghi file hay không.
-     */
-    __publicField(this, "minifyJSON");
     this.filePath = options.filePath || "database.json";
     this.minifyJSON = options.minifyJSON || false;
   }
@@ -1077,11 +1137,16 @@ var _JSONDriver = class _JSONDriver {
     return true;
   }
 };
-__name(_JSONDriver, "JSONDriver");
-var JSONDriver = _JSONDriver;
 
 // src/drivers/MemoryDriver.ts
-var _MemoryDriver = class _MemoryDriver {
+var MemoryDriver = class {
+  static {
+    __name(this, "MemoryDriver");
+  }
+  /**
+   * Object chứa toàn bộ dữ liệu database trong RAM.
+   */
+  store;
   /**
    * Khởi tạo MemoryDriver.
    *
@@ -1108,10 +1173,6 @@ var _MemoryDriver = class _MemoryDriver {
    * ```
    */
   constructor(initialData = {}) {
-    /**
-     * Object chứa toàn bộ dữ liệu database trong RAM.
-     */
-    __publicField(this, "store");
     this.store = initialData;
   }
   /**
@@ -1142,12 +1203,21 @@ var _MemoryDriver = class _MemoryDriver {
     return true;
   }
 };
-__name(_MemoryDriver, "MemoryDriver");
-var MemoryDriver = _MemoryDriver;
 
 // src/drivers/SQLiteDriver.ts
 var import_better_sqlite3 = __toESM(require("better-sqlite3"));
-var _SQLiteDriver = class _SQLiteDriver {
+var SQLiteDriver = class {
+  static {
+    __name(this, "SQLiteDriver");
+  }
+  /**
+   * SQLite database instance.
+   */
+  db;
+  /**
+   * Tên table lưu trữ dữ liệu JSON.
+   */
+  table;
   /**
    * Khởi tạo SQLiteDriver.
    *
@@ -1164,14 +1234,6 @@ var _SQLiteDriver = class _SQLiteDriver {
    * ```
    */
   constructor(options = {}) {
-    /**
-     * SQLite database instance.
-     */
-    __publicField(this, "db");
-    /**
-     * Tên table lưu trữ dữ liệu JSON.
-     */
-    __publicField(this, "table");
     this.db = new import_better_sqlite3.default(options.filePath ?? "database.sqlite");
     this.table = options.table ?? "json_store";
     this.db.prepare(`CREATE TABLE IF NOT EXISTS ${this.table} (id INTEGER PRIMARY KEY, data TEXT)`).run();
@@ -1209,12 +1271,45 @@ var _SQLiteDriver = class _SQLiteDriver {
     return true;
   }
 };
-__name(_SQLiteDriver, "SQLiteDriver");
-var SQLiteDriver = _SQLiteDriver;
 
 // src/drivers/MongoDriver.ts
 var import_mongodb = require("mongodb");
-var _MongoDriver = class _MongoDriver {
+var MongoDriver = class {
+  static {
+    __name(this, "MongoDriver");
+  }
+  /**
+   * MongoDB client instance.
+   */
+  client;
+  /**
+   * MongoDB database instance.
+   */
+  db;
+  /**
+   * Collection lưu dữ liệu JSON.
+   */
+  collection;
+  /**
+   * Tên database MongoDB.
+   */
+  databaseName;
+  /**
+   * Tên collection MongoDB.
+   */
+  collectionName;
+  /**
+   * Callback khi kết nối thành công.
+   */
+  onLoad;
+  /**
+   * Callback khi xảy ra lỗi.
+   */
+  onError;
+  /**
+   * Trạng thái đã gọi onLoad chưa (tránh spam)
+   */
+  isLoaded = false;
   /**
    * Khởi tạo MongoDriver.
    *
@@ -1222,35 +1317,25 @@ 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);
+   *          }
    *      })
    * });
    */
   constructor(options = {}) {
-    /**
-     * MongoDB client instance.
-     */
-    __publicField(this, "client");
-    /**
-     * MongoDB database instance.
-     */
-    __publicField(this, "db");
-    /**
-     * Collection lưu dữ liệu JSON.
-     */
-    __publicField(this, "collection");
-    /**
-     * Tên database MongoDB.
-     */
-    __publicField(this, "databaseName");
-    /**
-     * Tên collection MongoDB.
-     */
-    __publicField(this, "collectionName");
     const {
       mongourl = "mongodb://localhost:27017",
       databaseName = "database",
@@ -1259,21 +1344,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;
       }
     }
   }
@@ -1313,8 +1419,6 @@ var _MongoDriver = class _MongoDriver {
     return true;
   }
 };
-__name(_MongoDriver, "MongoDriver");
-var MongoDriver = _MongoDriver;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Database,
@@ -1323,4 +1427,4 @@ var MongoDriver = _MongoDriver;
   MongoDriver,
   SQLiteDriver
 });
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map