Class Database<V>

Class Database cung cấp API thao tác dữ liệu dạng key-path trên nhiều loại storage khác nhau thông qua DatabaseDriver.

Đây là lớp database chính (logic layer) của hệ thống.

Class này chịu trách nhiệm:

parse key path (user.profile.name)
validate dữ liệu
thao tác object
query dữ liệu (find, filter, map...)

Việc lưu trữ dữ liệu thực tế sẽ được thực hiện bởi các driver phụ trợ như:

JSONDriver
MemoryDriver
SQLiteDriver
MongoDriver

Các driver này chỉ chịu trách nhiệm:

đọc toàn bộ dữ liệu database
ghi toàn bộ dữ liệu database

Type Parameters

V = any
Kiểu dữ liệu tổng thể của database.

Index

Constructors

constructor

new Database<V = any>(options: DatabaseConfiguration): Database<V>
Khởi tạo Database instance.
Type Parameters
- V = any
 Kiểu dữ liệu tổng thể của database.
Parameters
- options: DatabaseConfiguration
 Cấu hình database.
 - driver
 Driver lưu trữ dữ liệu.
Returns Database<V>
Example
```
const db = new Database({
 driver: new JSONDriver({ filePath: "./database.json" }),
})
```
Ví dụ với MongoDB:
```
const db = new Database({
 driver: new MongoDriver({
 uri: "mongodb://localhost:27017",
 databaseName: "mydb"
 })
});
```

Properties

driver

driver: DatabaseDriver

Storage driver được sử dụng để đọc và ghi dữ liệu database.

Driver phải implement interface DatabaseDriver.

Ví dụ:

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

Methods

add

add(
key: AutocompletableString,
numberToAdd: number,
): Promise<number>
Cộng thêm giá trị vào một key dạng number.

Nếu key chưa tồn tại, giá trị mặc định sẽ là 0.
Type Parameters
- P extends string | string & {}
 Key path trong database.
Parameters
- key: AutocompletableString
 Đường dẫn dữ liệu dạng number.
- numberToAdd: number
 Số cần cộng thêm.
Returns Promise<number>
Giá trị mới sau khi cộng.
Example
```
await db.add("economy.users.123.balance", 50);
```

all

all(): Promise<V>
Lấy toàn bộ dữ liệu từ database thông qua driver.

Returns Promise<V>
Promise chứa toàn bộ dữ liệu database.
Example
```
const data = await db.all();
console.log(data.users);
```

delete

delete(
key?: AutocompletableString,
): Promise<boolean>
Xóa một key khỏi database.

Hỗ trợ nested path bằng dot notation.
Type Parameters
- P extends string | string & {}
 Path của object.
Parameters
- Optionalkey: AutocompletableString
 Đường dẫn key cần xóa.
Returns Promise<boolean>
- true nếu xóa thành công
- false nếu key không tồn tại
Throws
BlackCatError
- INVALID_TYPE nếu key không phải string
Example
```
await db.delete("user.name");
```

deleteAll

deleteAll(): Promise<boolean>
Xóa toàn bộ dữ liệu trong database.

Method này gọi trực tiếp driver.delete() để reset storage.

Returns Promise<boolean>
true sau khi dữ liệu đã được xóa.
Example
```
await db.deleteAll();
```

deleteMany

deleteMany(
key: AutocompletableString,
query: Partial<ArrayElement<ObjectValue<V, P>>>,
): Promise<number>
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.
Type Parameters
- P extends string | string & {}
 Đường dẫn key trong object (ObjectPath<V>).
Parameters
- key: AutocompletableString
 Đường dẫn đến mảng dữ liệu cần thao tác.
- query: Partial<ArrayElement<ObjectValue<V, P>>>
 Đ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 Promise<number>
Số lượng phần tử đã bị xóa khỏi mảng.
Example
Database mẫu:
```
{
 "member": {
 "user": {
 "database": [
 { "guild": "123", "username": "vinh" },
 { "guild": "456", "username": "test" }
 ]
 }
 }
}
```
Example
Xóa tất cả user có guild = "123"
```
await db.deleteMany("member.user.database", {
 guild: "123"
});
```

every

every(queryFunction: QueryFunction<V>): Promise<boolean>
Kiểm tra tất cả phần tử có thỏa điều kiện hay không.

Hoạt động giống Array.prototype.every.
Parameters
- queryFunction: QueryFunction<V>
 Hàm kiểm tra điều kiện.
Returns Promise<boolean>
true nếu tất cả phần tử đều thỏa điều kiện.
Example
```
const allActive = await db.every(user => user.active === true);
```

filter

filter(queryFunction: QueryFunction<V>): Promise<V[]>
Lọc các phần tử thỏa điều kiện.

Hoạt động giống Array.prototype.filter.
Parameters
- queryFunction: QueryFunction<V>
 Hàm kiểm tra điều kiện.
Returns Promise<V[]>
Mảng các phần tử thỏa điều kiện.
Example
```
const admins = await db.filter(user => user.role === "admin");
```

find

find(queryFunction: QueryFunction<V>): Promise<Maybe<V>>
Tìm phần tử đầu tiên thỏa điều kiện.

Hoạt động tương tự Array.prototype.find.
Parameters
- queryFunction: QueryFunction<V>
 Hàm kiểm tra điều kiện.
Returns Promise<Maybe<V>>
Phần tử đầu tiên thỏa điều kiện hoặc null nếu không tìm thấy.
Example
```
const user = await db.find(u => u.id === 1);
```

findIndex

findIndex(queryFunction: QueryFunction<V>): Promise<number>
Tìm index của phần tử đầu tiên thỏa điều kiện.

Hoạt động giống Array.prototype.findIndex.
Parameters
- queryFunction: QueryFunction<V>
 Hàm kiểm tra điều kiện.
Returns Promise<number>
Index của phần tử hoặc -1 nếu không tìm thấy.
Example
```
const index = await db.findIndex(user => user.id === 1);
```

findOne

findOne(
key?: AutocompletableString,
query?: Partial<ArrayElement<ObjectValue<V, 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.

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.
Type Parameters
- P extends string | string & {}
 Đường dẫn key trong object (ObjectPath<V>).
Parameters
- Optionalkey: AutocompletableString
 Key hoặc đường dẫn đến dữ liệu cần truy vấn.
- Optionalquery: Partial<ArrayElement<ObjectValue<V, P>>>
 Đối tượng điều kiện để tìm bản ghi phù hợp.
Returns Promise<Maybe<ObjectValue<V, P>>>
- 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
```
const users = await db.findOne("user");
```
Example
Tìm một bản ghi theo điều kiện
```
const user = await db.findOne("user", {
 guild: 1234566
});
```

get

get(
key?: AutocompletableString,
): Promise<Maybe<ObjectValue<V, P>>>
Lấy giá trị từ database theo key-path.

Key có thể là chuỗi dạng path:
```
user.profile.name
economy.users.123.balance
```
Nếu không truyền key, method sẽ trả về toàn bộ database.
Type Parameters
- P extends string | string & {}
 Key path trong database.
Parameters
- Optionalkey: AutocompletableString
 Đường dẫn dữ liệu cần lấy.
Returns Promise<Maybe<ObjectValue<V, P>>>
Giá trị tại key hoặc null nếu không tồn tại.
Example
```
const name = await db.get("user.profile.name");
```
Example
```
const all = await db.get();
```

has

has(
key: AutocompletableString,
): Promise<boolean>
Kiểm tra một key-path có tồn tại trong database hay không.

Method này sử dụng get() để xác định giá trị có tồn tại.
Type Parameters
- P extends string | string & {}
 Key path trong database.
Parameters
- key: AutocompletableString
 Đường dẫn dữ liệu cần kiểm tra.
Returns Promise<boolean>
true nếu key tồn tại, ngược lại false.
Example
```
const exists = await db.has("users.123");
```

isTargetArray

isTargetArray(
key: AutocompletableString,
): Promise<boolean>
Kiểm tra xem giá trị tại key có phải là Array hay không.
Type Parameters
- P extends string | string & {}
 Path của object trong database.
Parameters
- key: AutocompletableString
 Đường dẫn key cần kiểm tra.
Returns Promise<boolean>
true nếu giá trị là Array, ngược lại false.
Example
```
const result = await db.isTargetArray("users");
console.log(result);
```

isTargetNumber

isTargetNumber(
key: AutocompletableString,
): Promise<boolean>
Kiểm tra xem giá trị tại key có phải là Number hay không.
Type Parameters
- P extends string | string & {}
 Path của object trong database.
Parameters
- key: AutocompletableString
 Đường dẫn key cần kiểm tra.
Returns Promise<boolean>
true nếu giá trị là Number, ngược lại false.
Example
```
const result = await db.isTargetNumber("stats.score");
console.log(result);
```

keys

keys(key?: P): Promise<ObjectPath[]>
Lấy danh sách các key của object trong database.

Nếu không truyền key → trả về các key cấp cao nhất của database.
Type Parameters
- P extends string | string & {}
 Path của object.
Parameters
- Optionalkey: P
 Path của object cần lấy danh sách key.
Returns Promise<ObjectPath[]>
Mảng các key tồn tại (không bao gồm null hoặc undefined).
Example
```
const rootKeys = await db.keys();
const userKeys = await db.keys("user");
```

map

map<TReturnType>(
queryFunction: QueryFunction<V, TReturnType>,
): Promise<TReturnType[]>
Biến đổi tất cả giá trị trong database thành một mảng mới.

Hoạt động giống Array.prototype.map.
Type Parameters
- TReturnType
 Kiểu dữ liệu của phần tử trả về.
Parameters
- queryFunction: QueryFunction<V, TReturnType>
 Hàm transform từng phần tử.
Returns Promise<TReturnType[]>
Mảng kết quả sau khi transform.
Example
```
const names = await db.map(user => user.name);
```

pop

pop(
key: AutocompletableString,
...targetArrayElementIndexes: RestOrArray<number>,
): Promise<ExtractFromArray<ObjectValue<V, P>>[]>
Xóa phần tử khỏi array theo index.

Có thể truyền nhiều index hoặc một array index.
Type Parameters
- P extends string | string & {}
 Path trỏ đến array.
Parameters
- key: AutocompletableString
 Đường dẫn array.
- ...targetArrayElementIndexes: RestOrArray<number>
 Các index cần xóa.
Returns Promise<ExtractFromArray<ObjectValue<V, P>>[]>
Danh sách phần tử đã bị xóa.
Throws
BlackCatError
- INVALID_TARGET nếu target không phải array
- REQUIRED_PARAMETER_MISSING nếu thiếu index
- ONE_OR_MORE_ARRAY_TYPES_INVALID nếu index không phải number
Example
```
await db.pop("users", 0);
await db.pop("numbers", [1, 2, 3]);
```

pull

pull(
 key: AutocompletableString,
 targetArrayElementIndex: number,
 value: ExtractFromArray<ObjectValue<V, P>>,
): Promise<ExtractFromArray<ObjectValue<V, P>>[]>
Thay thế phần tử trong array theo index.
Type Parameters
- P extends string | string & {}
 Path trỏ đến array.
Parameters
- key: AutocompletableString
 Đường dẫn array.
- targetArrayElementIndex: number
 Index cần thay.
- value: ExtractFromArray<ObjectValue<V, P>>
 Giá trị mới.
Returns Promise<ExtractFromArray<ObjectValue<V, P>>[]>
Array sau khi thay thế.
Throws
BlackCatError
- INVALID_TYPE nếu index không phải number
- REQUIRED_PARAMETER_MISSING nếu thiếu value
- INVALID_KEY nếu path không tồn tại
- INVALID_TARGET nếu target không phải array
Example
```
await db.pull("users", 0, { id: 2 });
```

push

push(
key: AutocompletableString,
...values: RestOrArray<ExtractFromArray<ObjectValue<V, P>>>,
): Promise<ExtractFromArray<ObjectValue<V, P>>[]>
Thêm một hoặc nhiều phần tử vào cuối array tại key-path.

Method này sẽ:
- kiểm tra target có phải array không
- chỉ thêm các giá trị chưa tồn tại trong array
⚠️ Nếu key không tồn tại hoặc target không phải array thì sẽ ném lỗi.
Type Parameters
- P extends string
 Key path trong database.
Parameters
- key: AutocompletableString
 Đường dẫn tới array cần thêm phần tử.
- ...values: RestOrArray<ExtractFromArray<ObjectValue<V, P>>>
 Một hoặc nhiều giá trị cần thêm.
Returns Promise<ExtractFromArray<ObjectValue<V, P>>[]>
Array sau khi thêm phần tử.
Example
```
await db.push("users.123.roles", "admin");
```
Example
```
await db.push("queue.songs", song1, song2);
```

random

random(
key: AutocompletableString,
): Promise<Maybe<ObjectValue<V, P>>>
Lấy ngẫu nhiên một phần tử từ array tại path được chỉ định.
Type Parameters
- P extends string | string & {}
 Path trỏ đến array trong database.
Parameters
- key: AutocompletableString
 Đường dẫn đến array.
Returns Promise<Maybe<ObjectValue<V, P>>>
Một phần tử ngẫu nhiên trong array hoặc null nếu array rỗng.
Throws
BlackCatError
- INVALID_TARGET nếu giá trị tại key không phải array
Example
```
const randomUser = await db.random("users");
```

set

set(
key: AutocompletableString,
value: ObjectValue<V, P>,
): Promise<void>
Gán giá trị cho một key-path trong database.

Nếu key-path chưa tồn tại, các object trung gian sẽ được tự động tạo.
Type Parameters
- P extends string | string & {}
 Key path trong database.
Parameters
- key: AutocompletableString
 Đường dẫn dữ liệu cần gán giá trị.
- value: ObjectValue<V, P>
 Giá trị mới.
Returns Promise<void>
Giá trị vừa được set hoặc object root nếu value là object.
Example
```
await db.set("users.123.name", "Alice");
```
Example
```
await db.set("config.prefix", "!");
```

size

size(): Promise<number>
Lấy số lượng key cấp cao nhất trong database.

Returns Promise<number>
Tổng số key ở root level.
Example
```
const count = await db.size();
```

some

some(queryFunction: QueryFunction<V>): Promise<boolean>
Kiểm tra có ít nhất một phần tử thỏa điều kiện hay không.

Hoạt động giống Array.prototype.some.
Parameters
- queryFunction: QueryFunction<V>
 Hàm kiểm tra điều kiện.
Returns Promise<boolean>
true nếu tồn tại phần tử thỏa điều kiện.
Example
```
const hasAdmin = await db.some(user => user.role === "admin");
```

subtract

subtract(
key: AutocompletableString,
numberToSubtract: number,
): Promise<number>
Trừ giá trị khỏi một key dạng number.

Nếu key chưa tồn tại, giá trị mặc định sẽ là 0.
Type Parameters
- P extends string | string & {}
 Key path trong database.
Parameters
- key: AutocompletableString
 Đường dẫn dữ liệu dạng number.
- numberToSubtract: number
 Số cần trừ.
Returns Promise<number>
Giá trị mới sau khi trừ.
Example
```
await db.subtract("economy.users.123.balance", 20);
```

update

update(
key: AutocompletableString,
value: ObjectValue<V, P>,
): Promise<If<IsObject<V>, ObjectValue<V, P>>>
Cập nhật dữ liệu trong database theo đường dẫn key.

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.

Điều này giúp tránh việc làm mất các thuộc tính đã tồn tại.
Type Parameters
- P extends string | string & {}
 Đường dẫn key hợp lệ trong object database.
Parameters
- key: AutocompletableString
 Đường dẫn tới giá trị cần cập nhật. Hỗ trợ nested path dạng "a.b.c".
- value: ObjectValue<V, P>
 Giá trị mới sẽ được cập nhật tại key.
Returns Promise<If<IsObject<V>, ObjectValue<V, P>>>
Trả về giá trị cuối cùng sau khi cập nhật.
Example
Database ban đầu:
```
{
 "123": {
 "guildID": "123",
 "guildName": "BlackCat",
 "history": []
 }
}
```
Cập nhật:
```
await db.update("123", {
 history: [1,2,3]
});
```
Kết quả:
```
{
 "123": {
 "guildID": "123",
 "guildName": "BlackCat",
 "history": [1,2,3]
 }
}
```
Throws
- REQUIRED_PARAMETER_MISSING nếu key không được cung cấp
- INVALID_TYPE nếu key không phải string

values

values(key?: P): Promise<ObjectValue<V, P>[]>
Lấy danh sách các giá trị từ database.

Nếu không truyền key → trả về toàn bộ values ở root level. Nếu truyền key → trả về values của object tại path đó.
Type Parameters
- P extends string | string & {}
 Path của object trong database.
Parameters
- Optionalkey: P
 Đường dẫn object cần lấy values.
Returns Promise<ObjectValue<V, P>[]>
Mảng các giá trị.
Example
```
const allValues = await db.values();

const userValues = await db.values("users");
```

Class Database<V>

Type Parameters

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

driver

Returns Database<V>

Example

Properties

driver

Methods

add

Type Parameters

Parameters

Returns Promise<number>

Example

all

Returns Promise<V>

Example

delete

Type Parameters

Parameters

Returns Promise<boolean>

Throws

Example

deleteAll

Returns Promise<boolean>

Example

deleteMany

Type Parameters

Parameters

Returns Promise<number>

Example

Example

every

Parameters

Returns Promise<boolean>

Example

filter

Parameters

Returns Promise<V[]>

Example

find

Parameters

Returns Promise<Maybe<V>>

Example

findIndex

Parameters

Returns Promise<number>

Example

findOne

Type Parameters

Parameters

Returns Promise<Maybe<ObjectValue<V, P>>>

Example

Example

get

Type Parameters

Parameters

Returns Promise<Maybe<ObjectValue<V, P>>>

Example

Example

has

Type Parameters

Parameters

Returns Promise<boolean>

Example

isTargetArray

Type Parameters

Parameters

Returns Promise<boolean>

Example

isTargetNumber

Type Parameters

Parameters