🐈‍⬛ 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.

---

Tính năng

• Autocomplete path trong IDE (user.profile.name)
• Type-safe với TypeScript
• Hỗ trợ nested object
• API tương tự Array
• Driver system (memory, file, custom storage)
• Query helpers (find, filter, map, ...)
• Hỗ trợ thao tác với number và array

---

Cài đặt

npm install blackcat.js-database
Copy

---

Khởi tạo Database

import { Database, JSONDriver } from "blackcat.js-database";

const db = new Database({
  driver: db = new JSONDriver({
    filePath: "./database.json"
  })
});
Copy

---

Sử dụng với TypeScript Schema

type Schema = {
  users: {
    id: number;
    name: string;
    coins: number;
  }[];
  settings: {
    prefix: string;
  };
};

const db = new Database<Schema>({
  driver: db = new JSONDriver({
    filePath: "./database.json"
  })
});
Copy

Autocomplete trong IDE:

"users"
"users.0.id"
"settings.prefix"
Copy

---

Lấy dữ liệu

await db.get("users");
await db.get("settings.prefix");
Copy

Lấy toàn bộ database

await db.get();
Copy

Lấy bằng điều kiện nhất định

const data = await database.findOne("users", {
  name: "username"
});
Copy

---

Kiểm tra key tồn tại

await db.has("users");
Copy

---

Gán giá trị

await db.set("settings.prefix", "!");
Copy

---

Cập nhật giá trị

await db.update("settings.prefix", "?");
Copy

---

Xóa dữ liệu

await db.delete("settings.prefix");
Copy

Xóa toàn bộ database

await db.deleteAll();
Copy

xóa bằng điều kiện nhất đinh

const data = await database.deleteMany("member.user.database", {
  name: "username"
})
Copy

---

Number Operations

Cộng giá trị

await db.add("users.0.coins", 10);
Copy

Trừ giá trị

await db.subtract("users.0.coins", 5);
Copy

---

Array Operations

Thêm phần tử

await db.push("users", {
  id: 1,
  name: "Alice",
  coins: 0
});
Copy

Hoặc

await db.push("numbers", 1, 2, 3);
Copy

---

Thay thế phần tử trong mảng

await db.pull("users", 0, {
  id: 2,
  name: "Bob",
  coins: 10
});
Copy

---

Xóa phần tử

await db.pop("users", 0);
Copy

Hoặc

await db.pop("users", [0, 2]);
Copy

---

Lấy phần tử ngẫu nhiên

await db.random("users");
Copy

---

Query API

Database hỗ trợ các method tương tự Array.

find

const user = await db.find((u) => u.id === 1);
Copy

---

filter

const admins = await db.filter((u) => u.role === "admin");
Copy

---

map

const names = await db.map((u) => u.name);
Copy

---

findIndex

const index = await db.findIndex((u) => u.id === 1);
Copy

---

some

await db.some((u) => u.active === true);
Copy

---

every

await db.every((u) => u.active === true);
Copy

---

Utilities

keys

await db.keys();
await db.keys("users");
Copy

---

values

await db.values();
await db.values("users");
Copy

---

size

await db.size();
Copy

---

Kiểm tra kiểu dữ liệu

await db.isTargetArray("users");
await db.isTargetNumber("users.0.coins");
Copy

---

Driver System

Database sử dụng driver system để lưu trữ dữ liệu.

Driver chịu trách nhiệm:

• đọc dữ liệu
• ghi dữ liệu
• xóa dữ liệu

---

Memory Driver (ví dụ)

Driver lưu dữ liệu trong RAM.

import { Database, MemoryDriver } from "blackcat.js-database";

const db = new Database({
  driver: new MemoryDriver()
});
Copy

---

JSON Driver (ví dụ)

Driver lưu dữ liệu trong file json.

import { Database, JSONDriver } from "blackcat.js-database";

const database = new Database({
    driver: db = new JSONDriver({
      filePath: "./database.json"
    })
});
Copy

---

Mongo Driver (ví dụ)

Driver lưu dữ liệu trong mongoose.

import { Database, MongoDriver } from "blackcat.js-database";

const database = new Database({ 
    driver: new MongoDriver({
        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);
        }
    }),
});
Copy

---

SQLite Driver (ví dụ)

Driver lưu dữ liệu trong SQLite.

import { Database, SQLiteDriver } from "blackcat.js-database";

const database = new Database({ 
    driver: new SQLiteDriver({
        filePath: "database.sqlite",
        table: "json_store"
    })
});
Copy

---

Tạo Custom Driver

Bạn có thể tạo driver riêng bằng cách implement DatabaseDriver.

import { DatabaseDriver } from "blackcat.js-database";

class MyDriver implements DatabaseDriver {
  async all() {
    return {};
  }

  async set(data) {
  }

  async delete() {
  }

}
Copy

Sử dụng:

const db = new Database({
  driver: new MyDriver()
});
Copy

---

Ví dụ hoàn chỉnh

import { Database, JSONDriver } from "blackcat.js-database";

const db = new Database({
    driver: db = new JSONDriver({
      filePath: "./database.json"
    })
});
 
await db.set("users", []);

await db.push("users", {
  id: 1,
  name: "Alice",
  coins: 100
});

await db.add("users.0.coins", 50);

const user = await db.get("users.0");

console.log(user);
Copy

---

License

MIT