Skip to content

Commit ed663e4

Browse files
npermanperma
authored
Update README.md (#392)
1 parent fda8df9 commit ed663e4

File tree

2 files changed

+191
-266
lines changed

2 files changed

+191
-266
lines changed

‎scripts/quick-db/README.md‎

Lines changed: 54 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,171 +1,93 @@
1-
# QuickDB - A Lightweight Database for Minecraft Bedrock ScriptAPI
1+
# QuickDB
22

3-
**QuickDB** is a simple and efficient database system designed for Minecraft Bedrock Edition ScriptAPI. It utilizes dynamic properties from the `@minecraft/server` module, allowing developers to store and manage key-value pairs in a way similar to JavaScript's `Map` object.
3+
QuickDB is a lightweight key-value database designed for Minecraft Bedrock Script API.
4+
It supports two storage backends:
45

5-
---
6-
7-
## Features
8-
9-
- **CRUD Operations**:
10-
- `set(key, value)` - Save a value to the database.
11-
- `get(key)` - Retrieve a value by its key.
12-
- `delete(key)` - Remove a key-value pair from the database.
13-
- `has(key)` - Check if a key exists in the database.
14-
15-
- **Iteration**:
16-
- `keys()` - Get all keys in the database.
17-
- `values()` - Retrieve all values stored in the database.
18-
- `entries()` - Retrieve all key-value pairs as an array of entries.
19-
20-
- **Database Size**:
21-
- `size` - Get the total byte count used by the dynamic properties.
22-
23-
---
24-
25-
## Installation
26-
27-
Import `QuickDB` into your ScriptAPI project. Ensure `QuickDB` is included in your `index.js` file for easy integration.
28-
29-
```javascript
30-
import QuickDB from "./index.js";
31-
```
32-
33-
---
34-
35-
## Documentation
36-
37-
### **Constructor**
38-
39-
```javascript
40-
const db = new QuickDB("user");
41-
```
42-
43-
- **Parameters**:
44-
- `id` *(string)*: A unique identifier for your database instance.
45-
46-
---
6+
- **Dynamic Properties**
7+
- **Scoreboard**
478

48-
### **Methods**
49-
50-
#### `set(key, value)`
51-
- **Description**: Stores a value associated with a key.
52-
- **Parameters**:
53-
- `key` *(string)*: The key to store the value.
54-
- `value` *(any)*: The value to be stored.
55-
- **Returns**: `boolean` - `true` if successful.
56-
57-
```javascript
58-
db.set("FomoKiwor", { money: 20000 });
59-
```
9+
Both storages share the same API, so you can switch storage types without changing your code.
6010

6111
---
6212

63-
#### `get(key)`
64-
- **Description**: Retrieves the value associated with a key.
65-
- **Parameters**:
66-
- `key` *(string)*: The key to retrieve the value.
67-
- **Returns**: `any` - The value associated with the key.
68-
69-
```javascript
70-
const userData = db.get("FomoKiwor"); // { money: 20000 }
71-
```
72-
73-
---
13+
# How Caching Works
7414

75-
#### `has(key)`
76-
- **Description**: Checks if a key exists in the database.
77-
- **Parameters**:
78-
- `key` *(string)*: The key to check.
79-
- **Returns**: `boolean` - `true` if the key exists.
15+
When a database is created, it **loads all existing data into memory** (RAM).
8016

81-
```javascript
82-
const exists = db.has("FomoKiwor"); // true
83-
```
17+
Example process:
8418

85-
---
19+
1. The database scans the storage (Scoreboard or Dynamic Property).
20+
2. All matching keys are loaded into an internal cache.
21+
3. Future operations read from this cache instead of scanning storage again.
8622

87-
#### `delete(key)`
88-
- **Description**: Removes a key-value pair from the database.
89-
- **Parameters**:
90-
- `key` *(string)*: The key to remove.
91-
- **Returns**: `boolean` - `true` if successful.
23+
Because of this:
9224

93-
```javascript
94-
db.delete("FomoKiwor");
95-
```
25+
- `get()` is **very fast**
26+
- `has()` is **very fast**
27+
- `keys()`, `values()`, `entries()` do not need to scan storage again
9628

97-
---
29+
When data changes:
9830

99-
#### `keys()`
100-
- **Description**: Retrieves all keys in the database.
101-
- **Returns**: `string[]` - An array of all keys.
31+
- `set()` updates **storage + cache**
32+
- `delete()` removes **storage + cache**
10233

103-
```javascript
104-
const allKeys = db.keys(); // ["key1", "key2"]
105-
```
34+
This keeps both storage and cache synchronized.
10635

10736
---
10837

109-
#### `values()`
110-
- **Description**: Retrieves all values in the database.
111-
- **Returns**: `any[]` - An array of all values.
38+
# Storage Types
11239

113-
```javascript
114-
const allValues = db.values(); // [{ money: 20000 }, { items: [] }]
115-
```
116-
117-
---
40+
| Storage Type | Backend Used | Description |
41+
| ------------ | ------------ | ------------------------------------ |
42+
| `local` | DynamicDB | Stores data using dynamic properties |
43+
| `dynamic` | DynamicDB | Same as local |
44+
| `global` | ScoreboardDB | Stores data using scoreboard |
45+
| `scoreboard` | ScoreboardDB | Same as global |
11846

119-
#### `entries()`
120-
- **Description**: Retrieves all key-value pairs in the database.
121-
- **Returns**: `Array<[string, any]>` - An array of key-value entries.
47+
Example:
12248

123-
```javascript
124-
const allEntries = db.entries(); // [["key1", { money: 20000 }], ["key2", { items: [] }]]
49+
```ts
50+
const db = new QuickDB("playerData"); // default using local or dynamic
51+
const globalDB = new QuickDB("playerData", "global"); // global database, different cache with local or dynamic database, use this to sync database with other addons you wanna make like plugin structures
12552
```
12653

12754
---
12855

129-
### **Property**
56+
# Methods
13057

131-
#### `size`
132-
- **Description**: Gets the total byte count used by dynamic properties.
133-
- **Returns**: `number` - The total byte count.
134-
135-
```javascript
136-
console.log(db.size); // e.g., 512
137-
```
58+
| Method | Description | Example |
59+
| ----------------- | ------------------------ | ---------------------- |
60+
| `set(key, value)` | Save or update a value | `db.set("coins", 100)` |
61+
| `get(key)` | Get value from cache | `db.get("coins")` |
62+
| `has(key)` | Check if key exists | `db.has("coins")` |
63+
| `delete(key)` | Remove key from database | `db.delete("coins")` |
64+
| `keys()` | Get all keys | `db.keys()` |
65+
| `values()` | Get all values | `db.values()` |
66+
| `entries()` | Get key-value pairs | `db.entries()` |
13867

13968
---
14069

141-
## Example Usage
142-
143-
```javascript
144-
import QuickDB from "./index.js";
70+
# Example Usage
14571

146-
const db = new QuickDB("user");
72+
```ts
73+
const db = new QuickDB("coins");
14774

148-
db.set("FomoKiwor", { money: 20000 });
149-
console.log(db.get("FomoKiwor")); // { money: 20000 }
75+
db.set("player1", 100);
15076

151-
console.log(db.has("FomoKiwor")); // true
152-
db.delete("FomoKiwor");
153-
console.log(db.has("FomoKiwor")); // false
77+
const coins = db.get("player1");
15478

155-
db.set("User1", { score: 100 });
156-
db.set("User2", { score: 150 });
157-
158-
console.log(db.keys()); // ["User1", "User2"]
159-
console.log(db.values()); // [{ score: 100 }, { score: 150 }]
160-
console.log(db.entries()); // [["User1", { score: 100 }], ["User2", { score: 150 }]]
79+
console.log(coins);
16180
```
16281

16382
---
16483

165-
## License
84+
# Summary
16685

167-
MIT License
86+
QuickDB works by:
16887

169-
---
88+
1. Loading data from storage
89+
2. Storing it in an internal cache
90+
3. Using the cache for fast access
91+
4. Keeping storage and cache synchronized
17092

171-
Developed by [Nperma](https://github.com/nperma)
93+
This makes database operations **fast and efficient** for Minecraft Script API projects.

0 commit comments

Comments
 (0)