blackcat.js-database 1.0.0 → 1.0.2

package/README.md

@@ -1,9 +1,10 @@
-# blackcat.js-database
+# 🐈‍⬛ blackcat.js-database
 
 Một **database nhẹ, typed và hỗ trợ autocomplete path cho TypeScript**.
 
 `blackcat.js-database` cho phép bạn lưu trữ và truy vấn dữ liệu bằng **dot notation** với **type inference mạnh mẽ trong IDE**.
 
+> [Xem tài liệu ở đây](blackcat-js-database.vercel.app)
 ---
 
 # Tính năng
@@ -29,10 +30,12 @@ npm install blackcat.js-database
 # Khởi tạo Database
 
 ```ts
-import { Database, MemoryDriver } from "blackcat.js-database";
+import { Database, JSONDriver } from "blackcat.js-database";
 
 const db = new Database({
-  driver: new MemoryDriver()
+  driver: db = new JSONDriver({
+    filePath: "./database.json"
+  })
 });
 ```
 
@@ -53,7 +56,9 @@ type Schema = {
 };
 
 const db = new Database<Schema>({
-  driver: new MemoryDriver()
+  driver: db = new JSONDriver({
+    filePath: "./database.json"
+  })
 });
 ```
 
@@ -80,6 +85,14 @@ Lấy toàn bộ database
 await db.get();
 ```
 
+Lấy bằng điều kiện nhất định
+
+```ts
+const data = await database.findOne("users", {
+  name: "username"
+});
+```
+
 ---
 
 # Kiểm tra key tồn tại
@@ -118,6 +131,14 @@ Xóa toàn bộ database
 await db.deleteAll();
 ```
 
+xóa bằng điều kiện nhất đinh
+
+```ts
+const data = await database.deleteMany("member.user.database", {
+  name: "username"
+})
+```
+
 ---
 
 # Number Operations

package/dist/index.d.mts

@@ -61,7 +61,7 @@ interface DatabaseDriver {
 }
 /**
  * Cấu hình khởi tạo cho một instance của {@link Database}.
- *  @hidden
+ * @hidden
  *
  * Interface này xác định các tùy chọn cần thiết để thiết lập database,
  * bao gồm driver lưu trữ và các tùy chọn hành vi bổ sung.
@@ -92,7 +92,7 @@ interface DatabaseConfiguration {
 }
 /**
  * Đại diện cho một giá trị có thể là `T` hoặc `null`.
- *  @hidden
+ * @hidden
  *
  * Utility type này loại bỏ `undefined` khỏi union để đảm bảo
  * giá trị chỉ có thể là kiểu `T` hoặc `null`.
@@ -110,10 +110,14 @@ interface DatabaseConfiguration {
  * const invalid: Maybe<User> = undefined; // lỗi
  */
 type Maybe<T> = Exclude<T | null, undefined>;
+/**
+ *
+ */
+type ArrayElement<T> = T extends (infer U)[] ? U : T;
 /**
  * Utility type điều kiện dùng để trả về một kiểu dữ liệu
  * dựa trên giá trị boolean của điều kiện.
- *  @hidden
+ * @hidden
  *
  * Nếu `T` là `true` thì kiểu trả về sẽ là `IfTrue`.
  * Nếu `T` là `false` thì kiểu trả về sẽ là `IfFalse`.
@@ -505,6 +509,43 @@ declare class Database<V = any> {
      * ```
      */
     get<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>> | V>;
+    /**
+     * Tìm và trả về một bản ghi đầu tiên khớp với điều kiện trong database.
+     *
+     * Hàm này có hai cách sử dụng:
+     *
+     * 1. **Chỉ truyền `key`**
+     *    → Trả về toàn bộ dữ liệu của key (tương tự `get()`).
+     *
+     * 2. **Truyền `key` và `query`**
+     *    → Tìm phần tử đầu tiên trong mảng dữ liệu của key khớp với điều kiện.
+     *
+     * @template V - Kiểu dữ liệu của database.
+     * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+     *
+     * @param key - Key hoặc đường dẫn đến dữ liệu cần truy vấn.
+     * @param query - Đối tượng điều kiện để tìm bản ghi phù hợp.
+     *
+     * @returns
+     * - Nếu chỉ có `key`: trả về toàn bộ dữ liệu của key.
+     * - Nếu có `query`: trả về bản ghi đầu tiên khớp điều kiện.
+     * - Nếu không tìm thấy: trả về `null`.
+     *
+     * @example
+     * Chỉ lấy dữ liệu theo key
+     * ```ts
+     * const users = await db.findOne("user");
+     * ```
+     *
+     * @example
+     * Tìm một bản ghi theo điều kiện
+     * ```ts
+     * const user = await db.findOne("user", {
+     *   guild: 1234566
+     * });
+     * ```
+     */
+    findOne<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>, query?: Partial<ArrayElement<ObjectValue<V, P>>>): Promise<Maybe<ObjectValue<V, P>> | V>;
     /**
      * Kiểm tra một key-path có tồn tại trong database hay không.
      *
@@ -577,6 +618,50 @@ declare class Database<V = any> {
      * await db.deleteAll();
      */
     deleteAll(): Promise<boolean>;
+    /**
+     * Xóa nhiều bản ghi trong một mảng dữ liệu dựa trên điều kiện truy vấn.
+     *
+     * ⚠️ Method này **chỉ hoạt động với dữ liệu dạng mảng (array)**.
+     * Nếu dữ liệu tại `key` không phải là mảng, method sẽ **không thực hiện xóa**
+     * và trả về `0`.
+     *
+     * Method sẽ duyệt qua toàn bộ phần tử trong mảng và xóa những phần tử
+     * khớp với điều kiện `query`.
+     *
+     * @template V - Kiểu dữ liệu của database.
+     * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+     *
+     * @param key - Đường dẫn đến mảng dữ liệu cần thao tác.
+     * @param query - Điều kiện để xác định các phần tử cần xóa.
+     * Có thể truyền:
+     * - Một object điều kiện
+     *
+     * @returns Số lượng phần tử đã bị xóa khỏi mảng.
+     *
+     * @example
+     * Database mẫu:
+     * ```json
+     * {
+     *   "member": {
+     *     "user": {
+     *       "database": [
+     *         { "guild": "123", "username": "vinh" },
+     *         { "guild": "456", "username": "test" }
+     *       ]
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Xóa tất cả user có guild = "123"
+     * ```ts
+     * await db.deleteMany("member.user.database", {
+     *   guild: "123"
+     * });
+     * ```
+     */
+    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.
      *
@@ -953,6 +1038,11 @@ declare class JSONDriver implements DatabaseDriver {
      * ```
      */
     constructor(options: JSONDriverOptions);
+    /**
+     * Đảm bảo file database tồn tại.
+     * Nếu file chưa tồn tại sẽ tự động tạo file `{}`.
+     */
+    private ensureFile;
     /**
      * Đọc toàn bộ dữ liệu từ file database JSON.
      *

package/dist/index.d.ts

@@ -61,7 +61,7 @@ interface DatabaseDriver {
 }
 /**
  * Cấu hình khởi tạo cho một instance của {@link Database}.
- *  @hidden
+ * @hidden
  *
  * Interface này xác định các tùy chọn cần thiết để thiết lập database,
  * bao gồm driver lưu trữ và các tùy chọn hành vi bổ sung.
@@ -92,7 +92,7 @@ interface DatabaseConfiguration {
 }
 /**
  * Đại diện cho một giá trị có thể là `T` hoặc `null`.
- *  @hidden
+ * @hidden
  *
  * Utility type này loại bỏ `undefined` khỏi union để đảm bảo
  * giá trị chỉ có thể là kiểu `T` hoặc `null`.
@@ -110,10 +110,14 @@ interface DatabaseConfiguration {
  * const invalid: Maybe<User> = undefined; // lỗi
  */
 type Maybe<T> = Exclude<T | null, undefined>;
+/**
+ *
+ */
+type ArrayElement<T> = T extends (infer U)[] ? U : T;
 /**
  * Utility type điều kiện dùng để trả về một kiểu dữ liệu
  * dựa trên giá trị boolean của điều kiện.
- *  @hidden
+ * @hidden
  *
  * Nếu `T` là `true` thì kiểu trả về sẽ là `IfTrue`.
  * Nếu `T` là `false` thì kiểu trả về sẽ là `IfFalse`.
@@ -505,6 +509,43 @@ declare class Database<V = any> {
      * ```
      */
     get<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>): Promise<Maybe<ObjectValue<V, P>> | V>;
+    /**
+     * Tìm và trả về một bản ghi đầu tiên khớp với điều kiện trong database.
+     *
+     * Hàm này có hai cách sử dụng:
+     *
+     * 1. **Chỉ truyền `key`**
+     *    → Trả về toàn bộ dữ liệu của key (tương tự `get()`).
+     *
+     * 2. **Truyền `key` và `query`**
+     *    → Tìm phần tử đầu tiên trong mảng dữ liệu của key khớp với điều kiện.
+     *
+     * @template V - Kiểu dữ liệu của database.
+     * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+     *
+     * @param key - Key hoặc đường dẫn đến dữ liệu cần truy vấn.
+     * @param query - Đối tượng điều kiện để tìm bản ghi phù hợp.
+     *
+     * @returns
+     * - Nếu chỉ có `key`: trả về toàn bộ dữ liệu của key.
+     * - Nếu có `query`: trả về bản ghi đầu tiên khớp điều kiện.
+     * - Nếu không tìm thấy: trả về `null`.
+     *
+     * @example
+     * Chỉ lấy dữ liệu theo key
+     * ```ts
+     * const users = await db.findOne("user");
+     * ```
+     *
+     * @example
+     * Tìm một bản ghi theo điều kiện
+     * ```ts
+     * const user = await db.findOne("user", {
+     *   guild: 1234566
+     * });
+     * ```
+     */
+    findOne<P extends AutocompletableString<ObjectPath<V>>>(key?: AutocompletableString<P>, query?: Partial<ArrayElement<ObjectValue<V, P>>>): Promise<Maybe<ObjectValue<V, P>> | V>;
     /**
      * Kiểm tra một key-path có tồn tại trong database hay không.
      *
@@ -577,6 +618,50 @@ declare class Database<V = any> {
      * await db.deleteAll();
      */
     deleteAll(): Promise<boolean>;
+    /**
+     * Xóa nhiều bản ghi trong một mảng dữ liệu dựa trên điều kiện truy vấn.
+     *
+     * ⚠️ Method này **chỉ hoạt động với dữ liệu dạng mảng (array)**.
+     * Nếu dữ liệu tại `key` không phải là mảng, method sẽ **không thực hiện xóa**
+     * và trả về `0`.
+     *
+     * Method sẽ duyệt qua toàn bộ phần tử trong mảng và xóa những phần tử
+     * khớp với điều kiện `query`.
+     *
+     * @template V - Kiểu dữ liệu của database.
+     * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+     *
+     * @param key - Đường dẫn đến mảng dữ liệu cần thao tác.
+     * @param query - Điều kiện để xác định các phần tử cần xóa.
+     * Có thể truyền:
+     * - Một object điều kiện
+     *
+     * @returns Số lượng phần tử đã bị xóa khỏi mảng.
+     *
+     * @example
+     * Database mẫu:
+     * ```json
+     * {
+     *   "member": {
+     *     "user": {
+     *       "database": [
+     *         { "guild": "123", "username": "vinh" },
+     *         { "guild": "456", "username": "test" }
+     *       ]
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @example
+     * Xóa tất cả user có guild = "123"
+     * ```ts
+     * await db.deleteMany("member.user.database", {
+     *   guild: "123"
+     * });
+     * ```
+     */
+    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.
      *
@@ -953,6 +1038,11 @@ declare class JSONDriver implements DatabaseDriver {
      * ```
      */
     constructor(options: JSONDriverOptions);
+    /**
+     * Đảm bảo file database tồn tại.
+     * Nếu file chưa tồn tại sẽ tự động tạo file `{}`.
+     */
+    private ensureFile;
     /**
      * Đọc toàn bộ dữ liệu từ file database JSON.
      *

package/dist/index.js

@@ -247,6 +247,51 @@ var _Database = class _Database {
     }
     return result;
   }
+  /**
+   * Tìm và trả về một bản ghi đầu tiên khớp với điều kiện trong database.
+   *
+   * Hàm này có hai cách sử dụng:
+   *
+   * 1. **Chỉ truyền `key`**
+   *    → Trả về toàn bộ dữ liệu của key (tương tự `get()`).
+   *
+   * 2. **Truyền `key` và `query`**
+   *    → Tìm phần tử đầu tiên trong mảng dữ liệu của key khớp với điều kiện.
+   *
+   * @template V - Kiểu dữ liệu của database.
+   * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+   *
+   * @param key - Key hoặc đường dẫn đến dữ liệu cần truy vấn.
+   * @param query - Đối tượng điều kiện để tìm bản ghi phù hợp.
+   *
+   * @returns
+   * - Nếu chỉ có `key`: trả về toàn bộ dữ liệu của key.
+   * - Nếu có `query`: trả về bản ghi đầu tiên khớp điều kiện.
+   * - Nếu không tìm thấy: trả về `null`.
+   *
+   * @example
+   * Chỉ lấy dữ liệu theo key
+   * ```ts
+   * const users = await db.findOne("user");
+   * ```
+   *
+   * @example
+   * Tìm một bản ghi theo điều kiện
+   * ```ts
+   * const user = await db.findOne("user", {
+   *   guild: 1234566
+   * });
+   * ```
+   */
+  async findOne(key, query) {
+    const data = await this.get(key);
+    if (!query) return data;
+    if (!Array.isArray(data)) return null;
+    const result = data.find((item) => {
+      return Object.entries(query).every(([k, v]) => item[k] == v);
+    });
+    return result ?? null;
+  }
   /**
    * Kiểm tra một key-path có tồn tại trong database hay không.
    *
@@ -367,6 +412,59 @@ var _Database = class _Database {
     await this.driver.delete();
     return true;
   }
+  /**
+   * Xóa nhiều bản ghi trong một mảng dữ liệu dựa trên điều kiện truy vấn.
+   *
+   * ⚠️ Method này **chỉ hoạt động với dữ liệu dạng mảng (array)**.
+   * Nếu dữ liệu tại `key` không phải là mảng, method sẽ **không thực hiện xóa**
+   * và trả về `0`.
+   *
+   * Method sẽ duyệt qua toàn bộ phần tử trong mảng và xóa những phần tử
+   * khớp với điều kiện `query`.
+   *
+   * @template V - Kiểu dữ liệu của database.
+   * @template P - Đường dẫn key trong object (`ObjectPath<V>`).
+   *
+   * @param key - Đường dẫn đến mảng dữ liệu cần thao tác.
+   * @param query - Điều kiện để xác định các phần tử cần xóa.
+   * Có thể truyền:
+   * - Một object điều kiện
+   *
+   * @returns Số lượng phần tử đã bị xóa khỏi mảng.
+   *
+   * @example
+   * Database mẫu:
+   * ```json
+   * {
+   *   "member": {
+   *     "user": {
+   *       "database": [
+   *         { "guild": "123", "username": "vinh" },
+   *         { "guild": "456", "username": "test" }
+   *       ]
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Xóa tất cả user có guild = "123"
+   * ```ts
+   * await db.deleteMany("member.user.database", {
+   *   guild: "123"
+   * });
+   * ```
+   */
+  async deleteMany(key, query) {
+    const data = await this.get(key);
+    if (!Array.isArray(data)) return 0;
+    const originalLength = data.length;
+    const filtered = data.filter((item) => {
+      return !Object.entries(query).every(([k, v]) => item[k] == v);
+    });
+    await this.set(key, filtered);
+    return originalLength - filtered.length;
+  }
   /**
    * Cập nhật giá trị của một key-path trong database.
    *
@@ -877,6 +975,17 @@ var _JSONDriver = class _JSONDriver {
     this.filePath = options.filePath || "database.json";
     this.minifyJSON = options.minifyJSON || false;
   }
+  /**
+   * Đảm bảo file database tồn tại.
+   * Nếu file chưa tồn tại sẽ tự động tạo file `{}`.
+   */
+  async ensureFile() {
+    try {
+      await import_fs.promises.access(this.filePath);
+    } catch {
+      await import_fs.promises.writeFile(this.filePath, "{}");
+    }
+  }
   /**
    * Đọc toàn bộ dữ liệu từ file database JSON.
    *
@@ -887,6 +996,7 @@ var _JSONDriver = class _JSONDriver {
    * @returns Promise chứa toàn bộ dữ liệu database.
    */
   async all() {
+    await this.ensureFile();
     return import_fs.promises.readFile(this.filePath, "utf-8").then((content) => JSON.parse(content)).catch((error) => {
       console.error(`Kh\xF4ng th\u1EC3 \u0111\u1ECDc file database: ${this.filePath}`, error);
       return {};
@@ -905,6 +1015,7 @@ var _JSONDriver = class _JSONDriver {
    * @returns Promise chứa dữ liệu đã ghi.
    */
   async set(data) {
+    await this.ensureFile();
     await import_fs.promises.writeFile(this.filePath, JSON.stringify(data, null, this.minifyJSON ? void 0 : "	"));
     return data;
   }
@@ -916,6 +1027,7 @@ var _JSONDriver = class _JSONDriver {
    * @returns `true` nếu reset thành công.
    */
   async delete() {
+    await this.ensureFile();
     await import_fs.promises.writeFile(this.filePath, "{}");
     return true;
   }