@hold-baby/bucket-db 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +234 -19
- package/dist/cache/lru-cache.d.ts +47 -0
- package/dist/cache/lru-cache.d.ts.map +1 -0
- package/dist/cache/lru-cache.js +110 -0
- package/dist/cache/lru-cache.js.map +1 -0
- package/dist/core/bucket-db.d.ts +20 -0
- package/dist/core/bucket-db.d.ts.map +1 -0
- package/dist/core/bucket-db.js +32 -0
- package/dist/core/bucket-db.js.map +1 -0
- package/dist/core/collection.d.ts +26 -0
- package/dist/core/collection.d.ts.map +1 -0
- package/dist/core/collection.js +213 -0
- package/dist/core/collection.js.map +1 -0
- package/dist/core/wal.d.ts +45 -0
- package/dist/core/wal.d.ts.map +1 -0
- package/dist/core/wal.js +80 -0
- package/dist/core/wal.js.map +1 -0
- package/dist/index/shard-manager.d.ts +36 -0
- package/dist/index/shard-manager.d.ts.map +1 -0
- package/dist/index/shard-manager.js +177 -0
- package/dist/index/shard-manager.js.map +1 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +10 -0
- package/dist/index.js.map +1 -0
- package/dist/query/evaluator.d.ts +10 -0
- package/dist/query/evaluator.d.ts.map +1 -0
- package/dist/query/evaluator.js +127 -0
- package/dist/query/evaluator.js.map +1 -0
- package/dist/storage/fs-adapter.d.ts +24 -0
- package/dist/storage/fs-adapter.d.ts.map +1 -0
- package/dist/storage/fs-adapter.js +208 -0
- package/dist/storage/fs-adapter.js.map +1 -0
- package/dist/storage/memory-adapter.d.ts +22 -0
- package/dist/storage/memory-adapter.d.ts.map +1 -0
- package/dist/storage/memory-adapter.js +78 -0
- package/dist/storage/memory-adapter.js.map +1 -0
- package/dist/storage/oss-adapter.d.ts +26 -0
- package/dist/storage/oss-adapter.d.ts.map +1 -0
- package/dist/storage/oss-adapter.js +145 -0
- package/dist/storage/oss-adapter.js.map +1 -0
- package/dist/storage/s3-adapter.d.ts +26 -0
- package/dist/storage/s3-adapter.d.ts.map +1 -0
- package/dist/storage/s3-adapter.js +170 -0
- package/dist/storage/s3-adapter.js.map +1 -0
- package/dist/types/collection.d.ts +40 -0
- package/dist/types/collection.d.ts.map +1 -0
- package/dist/types/collection.js +2 -0
- package/dist/types/collection.js.map +1 -0
- package/{src/types/document.ts → dist/types/document.d.ts} +6 -10
- package/dist/types/document.d.ts.map +1 -0
- package/dist/types/document.js +2 -0
- package/dist/types/document.js.map +1 -0
- package/dist/types/errors.d.ts +32 -0
- package/dist/types/errors.d.ts.map +1 -0
- package/dist/types/errors.js +48 -0
- package/dist/types/errors.js.map +1 -0
- package/dist/types/index.d.ts +6 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +3 -0
- package/dist/types/index.js.map +1 -0
- package/dist/types/query.d.ts +37 -0
- package/dist/types/query.d.ts.map +1 -0
- package/dist/types/query.js +2 -0
- package/dist/types/query.js.map +1 -0
- package/dist/types/storage.d.ts +45 -0
- package/dist/types/storage.d.ts.map +1 -0
- package/dist/types/storage.js +2 -0
- package/dist/types/storage.js.map +1 -0
- package/dist/utils/hash.d.ts +13 -0
- package/dist/utils/hash.d.ts.map +1 -0
- package/dist/utils/hash.js +23 -0
- package/dist/utils/hash.js.map +1 -0
- package/dist/utils/path-validator.d.ts +46 -0
- package/dist/utils/path-validator.d.ts.map +1 -0
- package/dist/utils/path-validator.js +99 -0
- package/dist/utils/path-validator.js.map +1 -0
- package/llms.txt +46 -0
- package/package.json +14 -3
- package/src/core/bucket-db.ts +0 -43
- package/src/core/collection.ts +0 -173
- package/src/index/shard-manager.ts +0 -142
- package/src/index.ts +0 -37
- package/src/query/evaluator.ts +0 -87
- package/src/storage/ali-oss.d.ts +0 -43
- package/src/storage/fs-adapter.ts +0 -222
- package/src/storage/memory-adapter.ts +0 -105
- package/src/storage/oss-adapter.ts +0 -122
- package/src/storage/s3-adapter.ts +0 -151
- package/src/types/collection.ts +0 -34
- package/src/types/errors.ts +0 -49
- package/src/types/index.ts +0 -36
- package/src/types/query.ts +0 -50
- package/src/types/storage.ts +0 -46
- package/src/utils/hash.ts +0 -24
- package/tests/core/bucket-db.test.d.ts +0 -2
- package/tests/core/bucket-db.test.d.ts.map +0 -1
- package/tests/core/bucket-db.test.js +0 -34
- package/tests/core/bucket-db.test.js.map +0 -1
- package/tests/core/bucket-db.test.ts +0 -50
- package/tests/core/collection.test.d.ts +0 -2
- package/tests/core/collection.test.d.ts.map +0 -1
- package/tests/core/collection.test.js +0 -148
- package/tests/core/collection.test.js.map +0 -1
- package/tests/core/collection.test.ts +0 -195
- package/tests/core/dbpath.test.ts +0 -52
- package/tests/index/shard-manager.test.d.ts +0 -2
- package/tests/index/shard-manager.test.d.ts.map +0 -1
- package/tests/index/shard-manager.test.js +0 -106
- package/tests/index/shard-manager.test.js.map +0 -1
- package/tests/index/shard-manager.test.ts +0 -129
- package/tests/query/evaluator.test.d.ts +0 -2
- package/tests/query/evaluator.test.d.ts.map +0 -1
- package/tests/query/evaluator.test.js +0 -87
- package/tests/query/evaluator.test.js.map +0 -1
- package/tests/query/evaluator.test.ts +0 -104
- package/tests/storage/fs-adapter.test.ts +0 -111
- package/tests/storage/memory-adapter.test.d.ts +0 -2
- package/tests/storage/memory-adapter.test.d.ts.map +0 -1
- package/tests/storage/memory-adapter.test.js +0 -65
- package/tests/storage/memory-adapter.test.js.map +0 -1
- package/tests/storage/memory-adapter.test.ts +0 -84
- package/tests/storage/oss-adapter.test.d.ts +0 -2
- package/tests/storage/oss-adapter.test.d.ts.map +0 -1
- package/tests/storage/oss-adapter.test.js +0 -34
- package/tests/storage/oss-adapter.test.js.map +0 -1
- package/tests/storage/oss-adapter.test.ts +0 -40
- package/tests/storage/s3-adapter.test.d.ts +0 -2
- package/tests/storage/s3-adapter.test.d.ts.map +0 -1
- package/tests/storage/s3-adapter.test.js +0 -51
- package/tests/storage/s3-adapter.test.js.map +0 -1
- package/tests/storage/s3-adapter.test.ts +0 -62
- package/tests/utils/hash.test.d.ts +0 -2
- package/tests/utils/hash.test.d.ts.map +0 -1
- package/tests/utils/hash.test.js +0 -36
- package/tests/utils/hash.test.js.map +0 -1
- package/tests/utils/hash.test.ts +0 -42
- package/tsconfig.json +0 -12
package/README.md
CHANGED
|
@@ -1,38 +1,253 @@
|
|
|
1
|
-
#
|
|
1
|
+
# BucketDB
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@hold-baby/bucket-db)
|
|
4
|
+
[](https://www.npmjs.com/package/@hold-baby/bucket-db)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
A TypeScript document database built on cloud object storage (AWS S3 / Alibaba Cloud OSS) or local file system. No database servers needed.
|
|
6
8
|
|
|
7
|
-
##
|
|
9
|
+
## Installation
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
```bash
|
|
12
|
+
bun add @hold-baby/bucket-db
|
|
13
|
+
# or
|
|
14
|
+
npm install @hold-baby/bucket-db
|
|
15
|
+
```
|
|
10
16
|
|
|
11
|
-
|
|
17
|
+
## Exports
|
|
12
18
|
|
|
13
19
|
```typescript
|
|
14
|
-
|
|
20
|
+
// Core classes
|
|
21
|
+
import { BucketDB, Collection } from '@hold-baby/bucket-db';
|
|
22
|
+
|
|
23
|
+
// Storage adapters
|
|
24
|
+
import {
|
|
25
|
+
MemoryStorageAdapter, // in-memory (testing)
|
|
26
|
+
FileSystemAdapter, // local file system (development)
|
|
27
|
+
S3Adapter, // AWS S3 (production)
|
|
28
|
+
OSSAdapter, // Alibaba Cloud OSS (production)
|
|
29
|
+
} from '@hold-baby/bucket-db';
|
|
30
|
+
|
|
31
|
+
// Types
|
|
32
|
+
import type {
|
|
33
|
+
Document,
|
|
34
|
+
InsertDocument,
|
|
35
|
+
UpdateDocument,
|
|
36
|
+
QueryFilter,
|
|
37
|
+
QueryOptions,
|
|
38
|
+
UpdateOptions,
|
|
39
|
+
StorageAdapter,
|
|
40
|
+
} from '@hold-baby/bucket-db';
|
|
41
|
+
|
|
42
|
+
// Error classes
|
|
43
|
+
import {
|
|
44
|
+
BucketDBError,
|
|
45
|
+
DocumentNotFoundError,
|
|
46
|
+
ConcurrentUpdateError,
|
|
47
|
+
ValidationError,
|
|
48
|
+
StorageError,
|
|
49
|
+
} from '@hold-baby/bucket-db';
|
|
15
50
|
```
|
|
16
51
|
|
|
17
|
-
|
|
52
|
+
## Document Type
|
|
18
53
|
|
|
19
|
-
|
|
54
|
+
Every document stored in BucketDB has these system fields:
|
|
20
55
|
|
|
21
56
|
```typescript
|
|
22
|
-
|
|
57
|
+
interface Document {
|
|
58
|
+
id: string; // auto-generated UUID
|
|
59
|
+
_etag?: string; // version tag for optimistic locking
|
|
60
|
+
_createdAt?: string; // ISO 8601 timestamp
|
|
61
|
+
_updatedAt?: string; // ISO 8601 timestamp
|
|
62
|
+
}
|
|
23
63
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
64
|
+
// Extend Document to define your own schema
|
|
65
|
+
interface User extends Document {
|
|
66
|
+
name: string;
|
|
67
|
+
age: number;
|
|
68
|
+
email: string;
|
|
69
|
+
}
|
|
29
70
|
```
|
|
30
71
|
|
|
31
|
-
|
|
72
|
+
`InsertDocument<T>` omits `id`, `_etag`, `_createdAt`, `_updatedAt` — pass only your fields when inserting.
|
|
73
|
+
|
|
74
|
+
`UpdateDocument<T>` is `Partial<Omit<T, 'id'>>` — all fields optional except `id` is excluded.
|
|
75
|
+
|
|
76
|
+
## Quick Start
|
|
77
|
+
|
|
78
|
+
```typescript
|
|
79
|
+
import { BucketDB, FileSystemAdapter } from '@hold-baby/bucket-db';
|
|
80
|
+
import type { Document } from '@hold-baby/bucket-db';
|
|
81
|
+
|
|
82
|
+
interface User extends Document {
|
|
83
|
+
name: string;
|
|
84
|
+
age: number;
|
|
85
|
+
email: string;
|
|
86
|
+
status: 'active' | 'inactive';
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
const db = new BucketDB(
|
|
90
|
+
new FileSystemAdapter({ basePath: './data' }),
|
|
91
|
+
'my-app'
|
|
92
|
+
);
|
|
93
|
+
|
|
94
|
+
const users = db.collection<User>('users');
|
|
95
|
+
|
|
96
|
+
// Insert
|
|
97
|
+
const user = await users.insert({ name: 'Alice', age: 25, email: 'alice@example.com', status: 'active' });
|
|
98
|
+
// user.id, user._etag, user._createdAt are set automatically
|
|
99
|
+
|
|
100
|
+
// Find by ID
|
|
101
|
+
const found = await users.findById(user.id);
|
|
102
|
+
|
|
103
|
+
// Query
|
|
104
|
+
const activeUsers = await users.find({ status: 'active' });
|
|
105
|
+
const adults = await users.find({ age: { $gte: 18 } }, { limit: 10, offset: 0 });
|
|
106
|
+
|
|
107
|
+
// Update (with optimistic locking via etag)
|
|
108
|
+
const updated = await users.update(user.id, { age: 26 }, { etag: user._etag });
|
|
109
|
+
|
|
110
|
+
// Delete
|
|
111
|
+
await users.delete(user.id);
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Query Operators
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
// Equality (shorthand)
|
|
118
|
+
await users.find({ status: 'active' }); // { status: { $eq: 'active' } }
|
|
119
|
+
|
|
120
|
+
// Comparison
|
|
121
|
+
await users.find({ age: { $gt: 18 } });
|
|
122
|
+
await users.find({ age: { $gte: 18 } });
|
|
123
|
+
await users.find({ age: { $lt: 65 } });
|
|
124
|
+
await users.find({ age: { $lte: 65 } });
|
|
125
|
+
await users.find({ status: { $ne: 'inactive' } });
|
|
126
|
+
|
|
127
|
+
// Array membership
|
|
128
|
+
await users.find({ status: { $in: ['active', 'pending'] } });
|
|
129
|
+
await users.find({ status: { $nin: ['banned', 'deleted'] } });
|
|
130
|
+
|
|
131
|
+
// Pagination
|
|
132
|
+
await users.find({}, { limit: 20, offset: 40 });
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Error Handling
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
import {
|
|
139
|
+
DocumentNotFoundError,
|
|
140
|
+
ConcurrentUpdateError,
|
|
141
|
+
ValidationError,
|
|
142
|
+
StorageError,
|
|
143
|
+
} from '@hold-baby/bucket-db';
|
|
144
|
+
|
|
145
|
+
try {
|
|
146
|
+
const user = await users.findById('nonexistent-id');
|
|
147
|
+
} catch (err) {
|
|
148
|
+
if (err instanceof DocumentNotFoundError) {
|
|
149
|
+
// Document does not exist
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
try {
|
|
154
|
+
await users.update(id, { age: 30 }, { etag: staleEtag });
|
|
155
|
+
} catch (err) {
|
|
156
|
+
if (err instanceof ConcurrentUpdateError) {
|
|
157
|
+
// Another write happened — re-fetch and retry
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
| Error class | When thrown |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `DocumentNotFoundError` | `findById` or `update`/`delete` on a missing document |
|
|
165
|
+
| `ConcurrentUpdateError` | `update`/`delete` with a stale `etag` |
|
|
166
|
+
| `ValidationError` | Invalid input (e.g. missing required fields) |
|
|
167
|
+
| `StorageError` | Underlying storage failure (S3, OSS, filesystem I/O) |
|
|
168
|
+
|
|
169
|
+
## Storage Adapters
|
|
170
|
+
|
|
171
|
+
### MemoryStorageAdapter (Testing)
|
|
172
|
+
|
|
173
|
+
```typescript
|
|
174
|
+
import { BucketDB, MemoryStorageAdapter } from '@hold-baby/bucket-db';
|
|
175
|
+
|
|
176
|
+
const db = new BucketDB(new MemoryStorageAdapter(), 'test-db');
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### FileSystemAdapter (Development)
|
|
180
|
+
|
|
181
|
+
```typescript
|
|
182
|
+
import { FileSystemAdapter } from '@hold-baby/bucket-db';
|
|
183
|
+
|
|
184
|
+
const adapter = new FileSystemAdapter({ basePath: './data' });
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### S3Adapter (Production)
|
|
188
|
+
|
|
189
|
+
```typescript
|
|
190
|
+
import { S3Adapter } from '@hold-baby/bucket-db';
|
|
191
|
+
|
|
192
|
+
const adapter = new S3Adapter({
|
|
193
|
+
bucket: 'my-bucket',
|
|
194
|
+
region: 'us-east-1',
|
|
195
|
+
credentials: {
|
|
196
|
+
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
|
|
197
|
+
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
|
|
198
|
+
},
|
|
199
|
+
});
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### OSSAdapter (Production)
|
|
203
|
+
|
|
204
|
+
```typescript
|
|
205
|
+
import { OSSAdapter } from '@hold-baby/bucket-db';
|
|
206
|
+
|
|
207
|
+
const adapter = new OSSAdapter({
|
|
208
|
+
bucket: 'my-bucket',
|
|
209
|
+
region: 'oss-cn-hangzhou',
|
|
210
|
+
credentials: {
|
|
211
|
+
accessKeyId: process.env.OSS_ACCESS_KEY_ID!,
|
|
212
|
+
secretAccessKey: process.env.OSS_ACCESS_KEY_SECRET!,
|
|
213
|
+
},
|
|
214
|
+
});
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## BucketDB Options
|
|
218
|
+
|
|
219
|
+
```typescript
|
|
220
|
+
new BucketDB(adapter, dbPath, options?)
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
| Parameter | Type | Description |
|
|
224
|
+
|---|---|---|
|
|
225
|
+
| `adapter` | `StorageAdapter` | Storage backend |
|
|
226
|
+
| `dbPath` | `string` | Namespace for this database (e.g. `'my-app'`, `'tenant-123'`) |
|
|
227
|
+
| `options.defaultShardCount` | `number` | Default index shard count (default: `16`) |
|
|
228
|
+
|
|
229
|
+
## Collection Options
|
|
230
|
+
|
|
231
|
+
```typescript
|
|
232
|
+
db.collection<T>(name, options?)
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
| Parameter | Type | Description |
|
|
236
|
+
|---|---|---|
|
|
237
|
+
| `name` | `string` | Collection name |
|
|
238
|
+
| `options.shardCount` | `number` | Override shard count for this collection |
|
|
239
|
+
|
|
240
|
+
## Features
|
|
241
|
+
|
|
242
|
+
- No database servers — uses S3 / OSS / local filesystem as backend
|
|
243
|
+
- Type-safe TypeScript API with full inference
|
|
244
|
+
- Optimistic locking via ETag
|
|
245
|
+
- Sharded index design for scale
|
|
246
|
+
- Unified API across all storage backends
|
|
247
|
+
|
|
248
|
+
## Documentation
|
|
32
249
|
|
|
33
|
-
|
|
34
|
-
- `S3Adapter` - AWS S3 storage
|
|
35
|
-
- `OSSAdapter` - Alibaba Cloud OSS storage
|
|
250
|
+
📚 https://bucket-db.vercel.app
|
|
36
251
|
|
|
37
252
|
## License
|
|
38
253
|
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* LRU (Least Recently Used) Cache implementation
|
|
3
|
+
*/
|
|
4
|
+
export declare class LRUCache<T> {
|
|
5
|
+
private cache;
|
|
6
|
+
private maxSize;
|
|
7
|
+
private ttl;
|
|
8
|
+
private hits;
|
|
9
|
+
private misses;
|
|
10
|
+
private evictions;
|
|
11
|
+
constructor(maxSize?: number, ttl?: number);
|
|
12
|
+
/**
|
|
13
|
+
* Generate cache key from query filter and options
|
|
14
|
+
*/
|
|
15
|
+
static generateKey(filter: Record<string, any>, options?: Record<string, any>): string;
|
|
16
|
+
/**
|
|
17
|
+
* Get value from cache
|
|
18
|
+
*/
|
|
19
|
+
get(key: string): T | null;
|
|
20
|
+
/**
|
|
21
|
+
* Put value into cache
|
|
22
|
+
*/
|
|
23
|
+
set(key: string, value: T): void;
|
|
24
|
+
/**
|
|
25
|
+
* Invalidate cache entries (clear all by default)
|
|
26
|
+
*/
|
|
27
|
+
invalidate(pattern?: RegExp): void;
|
|
28
|
+
/**
|
|
29
|
+
* Get cache statistics
|
|
30
|
+
*/
|
|
31
|
+
getStats(): {
|
|
32
|
+
size: number;
|
|
33
|
+
hits: number;
|
|
34
|
+
misses: number;
|
|
35
|
+
evictions: number;
|
|
36
|
+
hitRate: string;
|
|
37
|
+
};
|
|
38
|
+
/**
|
|
39
|
+
* Clear all cache statistics
|
|
40
|
+
*/
|
|
41
|
+
resetStats(): void;
|
|
42
|
+
/**
|
|
43
|
+
* Clear the entire cache
|
|
44
|
+
*/
|
|
45
|
+
clear(): void;
|
|
46
|
+
}
|
|
47
|
+
//# sourceMappingURL=lru-cache.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../../src/cache/lru-cache.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACrB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,GAAG,CAAS;IAGpB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,SAAS,CAAa;gBAElB,OAAO,GAAE,MAAY,EAAE,GAAG,GAAE,MAAsB;IAM9D;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM;IAKtF;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAuB1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAqBhC;;OAEG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAclC;;OAEG;IACH,QAAQ;;;;;;;IAWR;;OAEG;IACH,UAAU,IAAI,IAAI;IAMlB;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { createHash } from 'crypto';
|
|
2
|
+
/**
|
|
3
|
+
* LRU (Least Recently Used) Cache implementation
|
|
4
|
+
*/
|
|
5
|
+
export class LRUCache {
|
|
6
|
+
cache;
|
|
7
|
+
maxSize;
|
|
8
|
+
ttl; // Time To Live in milliseconds
|
|
9
|
+
// Statistics
|
|
10
|
+
hits = 0;
|
|
11
|
+
misses = 0;
|
|
12
|
+
evictions = 0;
|
|
13
|
+
constructor(maxSize = 100, ttl = 5 * 60 * 1000) {
|
|
14
|
+
this.cache = new Map();
|
|
15
|
+
this.maxSize = maxSize;
|
|
16
|
+
this.ttl = ttl;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Generate cache key from query filter and options
|
|
20
|
+
*/
|
|
21
|
+
static generateKey(filter, options) {
|
|
22
|
+
const data = JSON.stringify({ filter, options });
|
|
23
|
+
return createHash('md5').update(data).digest('hex');
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Get value from cache
|
|
27
|
+
*/
|
|
28
|
+
get(key) {
|
|
29
|
+
const entry = this.cache.get(key);
|
|
30
|
+
if (!entry) {
|
|
31
|
+
this.misses++;
|
|
32
|
+
return null;
|
|
33
|
+
}
|
|
34
|
+
// Check if entry has expired
|
|
35
|
+
if (Date.now() - entry.timestamp > this.ttl) {
|
|
36
|
+
this.cache.delete(key);
|
|
37
|
+
this.misses++;
|
|
38
|
+
return null;
|
|
39
|
+
}
|
|
40
|
+
// Move to end (mark as recently used)
|
|
41
|
+
this.cache.delete(key);
|
|
42
|
+
this.cache.set(key, entry);
|
|
43
|
+
this.hits++;
|
|
44
|
+
return entry.value;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Put value into cache
|
|
48
|
+
*/
|
|
49
|
+
set(key, value) {
|
|
50
|
+
// Remove if already exists (to update position)
|
|
51
|
+
if (this.cache.has(key)) {
|
|
52
|
+
this.cache.delete(key);
|
|
53
|
+
}
|
|
54
|
+
// Evict oldest entry if cache is full
|
|
55
|
+
if (this.cache.size >= this.maxSize) {
|
|
56
|
+
const firstKey = this.cache.keys().next().value;
|
|
57
|
+
if (firstKey) {
|
|
58
|
+
this.cache.delete(firstKey);
|
|
59
|
+
this.evictions++;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
this.cache.set(key, {
|
|
63
|
+
value,
|
|
64
|
+
timestamp: Date.now(),
|
|
65
|
+
});
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Invalidate cache entries (clear all by default)
|
|
69
|
+
*/
|
|
70
|
+
invalidate(pattern) {
|
|
71
|
+
if (!pattern) {
|
|
72
|
+
this.cache.clear();
|
|
73
|
+
return;
|
|
74
|
+
}
|
|
75
|
+
// Remove entries matching pattern
|
|
76
|
+
for (const key of this.cache.keys()) {
|
|
77
|
+
if (pattern.test(key)) {
|
|
78
|
+
this.cache.delete(key);
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Get cache statistics
|
|
84
|
+
*/
|
|
85
|
+
getStats() {
|
|
86
|
+
const total = this.hits + this.misses;
|
|
87
|
+
return {
|
|
88
|
+
size: this.cache.size,
|
|
89
|
+
hits: this.hits,
|
|
90
|
+
misses: this.misses,
|
|
91
|
+
evictions: this.evictions,
|
|
92
|
+
hitRate: total > 0 ? (this.hits / total * 100).toFixed(2) + '%' : '0%',
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Clear all cache statistics
|
|
97
|
+
*/
|
|
98
|
+
resetStats() {
|
|
99
|
+
this.hits = 0;
|
|
100
|
+
this.misses = 0;
|
|
101
|
+
this.evictions = 0;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* Clear the entire cache
|
|
105
|
+
*/
|
|
106
|
+
clear() {
|
|
107
|
+
this.cache.clear();
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
//# sourceMappingURL=lru-cache.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lru-cache.js","sourceRoot":"","sources":["../../src/cache/lru-cache.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { StorageAdapter, Document } from '../types/index.js';
|
|
2
|
+
import { Collection, CollectionOptions } from './collection.js';
|
|
3
|
+
export interface BucketDBOptions {
|
|
4
|
+
defaultShardCount?: number;
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Main BucketDB class
|
|
8
|
+
*/
|
|
9
|
+
export declare class BucketDB {
|
|
10
|
+
private adapter;
|
|
11
|
+
private dbPath;
|
|
12
|
+
private options;
|
|
13
|
+
private collections;
|
|
14
|
+
constructor(adapter: StorageAdapter, dbPath: string, options?: BucketDBOptions);
|
|
15
|
+
/**
|
|
16
|
+
* Get or create a collection
|
|
17
|
+
*/
|
|
18
|
+
collection<T extends Document>(name: string, options?: CollectionOptions): Collection<T>;
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=bucket-db.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bucket-db.d.ts","sourceRoot":"","sources":["../../src/core/bucket-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGhE,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,QAAQ;IAIjB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IALjB,OAAO,CAAC,WAAW,CAAsC;gBAG/C,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB;IAGvC;;OAEG;IACH,UAAU,CAAC,CAAC,SAAS,QAAQ,EAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,iBAAiB,GAC1B,UAAU,CAAC,CAAC,CAAC;CAoBjB"}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { Collection } from './collection.js';
|
|
2
|
+
import { sanitizePathComponent } from '../utils/path-validator.js';
|
|
3
|
+
/**
|
|
4
|
+
* Main BucketDB class
|
|
5
|
+
*/
|
|
6
|
+
export class BucketDB {
|
|
7
|
+
adapter;
|
|
8
|
+
dbPath;
|
|
9
|
+
options;
|
|
10
|
+
collections = new Map();
|
|
11
|
+
constructor(adapter, dbPath, options = {}) {
|
|
12
|
+
this.adapter = adapter;
|
|
13
|
+
this.dbPath = dbPath;
|
|
14
|
+
this.options = options;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Get or create a collection
|
|
18
|
+
*/
|
|
19
|
+
collection(name, options) {
|
|
20
|
+
// Validate collection name to prevent path traversal
|
|
21
|
+
sanitizePathComponent(name);
|
|
22
|
+
if (this.collections.has(name)) {
|
|
23
|
+
return this.collections.get(name);
|
|
24
|
+
}
|
|
25
|
+
const collection = new Collection(this.adapter, this.dbPath, name, {
|
|
26
|
+
shardCount: options?.shardCount || this.options.defaultShardCount || 16,
|
|
27
|
+
});
|
|
28
|
+
this.collections.set(name, collection);
|
|
29
|
+
return collection;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
//# sourceMappingURL=bucket-db.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bucket-db.js","sourceRoot":"","sources":["../../src/core/bucket-db.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAMnE;;GAEG;AACH,MAAM,OAAO,QAAQ;IAIT;IACA;IACA;IALF,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAC;IAEzD,YACU,OAAuB,EACvB,MAAc,EACd,UAA2B,EAAE;QAF7B,YAAO,GAAP,OAAO,CAAgB;QACvB,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAsB;IACpC,CAAC;IAEJ;;OAEG;IACH,UAAU,CACR,IAAY,EACZ,OAA2B;QAE3B,qDAAqD;QACrD,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAE5B,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QACrC,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,UAAU,CAC/B,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,MAAM,EACX,IAAI,EACJ;YACE,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,iBAAiB,IAAI,EAAE;SACxE,CACF,CAAC;QAEF,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACvC,OAAO,UAAU,CAAC;IACpB,CAAC;CACF"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { ICollection, Document, InsertDocument, UpdateDocument, QueryFilter, QueryOptions, UpdateOptions, StorageAdapter } from '../types/index.js';
|
|
2
|
+
export interface CollectionOptions {
|
|
3
|
+
shardCount?: number;
|
|
4
|
+
}
|
|
5
|
+
/**
|
|
6
|
+
* Collection class for type-safe CRUD operations
|
|
7
|
+
*/
|
|
8
|
+
export declare class Collection<T extends Document> implements ICollection<T> {
|
|
9
|
+
private adapter;
|
|
10
|
+
private shardManager;
|
|
11
|
+
private wal;
|
|
12
|
+
private queryCache;
|
|
13
|
+
private basePath;
|
|
14
|
+
constructor(adapter: StorageAdapter, dbPath: string, collectionName: string, options?: CollectionOptions);
|
|
15
|
+
/**
|
|
16
|
+
* Recover from pending WAL entries
|
|
17
|
+
*/
|
|
18
|
+
private recoverFromWAL;
|
|
19
|
+
private getDocPath;
|
|
20
|
+
insert(data: InsertDocument<T>): Promise<T>;
|
|
21
|
+
findById(id: string): Promise<T | null>;
|
|
22
|
+
find(filter: QueryFilter<T>, options?: QueryOptions): Promise<T[]>;
|
|
23
|
+
update(id: string, data: UpdateDocument<T>, options?: UpdateOptions): Promise<T>;
|
|
24
|
+
delete(id: string): Promise<void>;
|
|
25
|
+
}
|
|
26
|
+
//# sourceMappingURL=collection.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/core/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,EACf,MAAM,mBAAmB,CAAC;AAqB3B,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,QAAQ,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAOjE,OAAO,CAAC,OAAO;IANjB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAGf,OAAO,EAAE,cAAc,EAC/B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,iBAAsB;IAmBjC;;OAEG;YACW,cAAc;IAmB5B,OAAO,CAAC,UAAU;IAMZ,MAAM,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAWvC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IA0ClE,MAAM,CACV,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,CAAC,CAAC;IAsDP,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA+BxC"}
|