@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.
Files changed (138) hide show
  1. package/README.md +234 -19
  2. package/dist/cache/lru-cache.d.ts +47 -0
  3. package/dist/cache/lru-cache.d.ts.map +1 -0
  4. package/dist/cache/lru-cache.js +110 -0
  5. package/dist/cache/lru-cache.js.map +1 -0
  6. package/dist/core/bucket-db.d.ts +20 -0
  7. package/dist/core/bucket-db.d.ts.map +1 -0
  8. package/dist/core/bucket-db.js +32 -0
  9. package/dist/core/bucket-db.js.map +1 -0
  10. package/dist/core/collection.d.ts +26 -0
  11. package/dist/core/collection.d.ts.map +1 -0
  12. package/dist/core/collection.js +213 -0
  13. package/dist/core/collection.js.map +1 -0
  14. package/dist/core/wal.d.ts +45 -0
  15. package/dist/core/wal.d.ts.map +1 -0
  16. package/dist/core/wal.js +80 -0
  17. package/dist/core/wal.js.map +1 -0
  18. package/dist/index/shard-manager.d.ts +36 -0
  19. package/dist/index/shard-manager.d.ts.map +1 -0
  20. package/dist/index/shard-manager.js +177 -0
  21. package/dist/index/shard-manager.js.map +1 -0
  22. package/dist/index.d.ts +9 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +10 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/query/evaluator.d.ts +10 -0
  27. package/dist/query/evaluator.d.ts.map +1 -0
  28. package/dist/query/evaluator.js +127 -0
  29. package/dist/query/evaluator.js.map +1 -0
  30. package/dist/storage/fs-adapter.d.ts +24 -0
  31. package/dist/storage/fs-adapter.d.ts.map +1 -0
  32. package/dist/storage/fs-adapter.js +208 -0
  33. package/dist/storage/fs-adapter.js.map +1 -0
  34. package/dist/storage/memory-adapter.d.ts +22 -0
  35. package/dist/storage/memory-adapter.d.ts.map +1 -0
  36. package/dist/storage/memory-adapter.js +78 -0
  37. package/dist/storage/memory-adapter.js.map +1 -0
  38. package/dist/storage/oss-adapter.d.ts +26 -0
  39. package/dist/storage/oss-adapter.d.ts.map +1 -0
  40. package/dist/storage/oss-adapter.js +145 -0
  41. package/dist/storage/oss-adapter.js.map +1 -0
  42. package/dist/storage/s3-adapter.d.ts +26 -0
  43. package/dist/storage/s3-adapter.d.ts.map +1 -0
  44. package/dist/storage/s3-adapter.js +170 -0
  45. package/dist/storage/s3-adapter.js.map +1 -0
  46. package/dist/types/collection.d.ts +40 -0
  47. package/dist/types/collection.d.ts.map +1 -0
  48. package/dist/types/collection.js +2 -0
  49. package/dist/types/collection.js.map +1 -0
  50. package/{src/types/document.ts → dist/types/document.d.ts} +6 -10
  51. package/dist/types/document.d.ts.map +1 -0
  52. package/dist/types/document.js +2 -0
  53. package/dist/types/document.js.map +1 -0
  54. package/dist/types/errors.d.ts +32 -0
  55. package/dist/types/errors.d.ts.map +1 -0
  56. package/dist/types/errors.js +48 -0
  57. package/dist/types/errors.js.map +1 -0
  58. package/dist/types/index.d.ts +6 -0
  59. package/dist/types/index.d.ts.map +1 -0
  60. package/dist/types/index.js +3 -0
  61. package/dist/types/index.js.map +1 -0
  62. package/dist/types/query.d.ts +37 -0
  63. package/dist/types/query.d.ts.map +1 -0
  64. package/dist/types/query.js +2 -0
  65. package/dist/types/query.js.map +1 -0
  66. package/dist/types/storage.d.ts +45 -0
  67. package/dist/types/storage.d.ts.map +1 -0
  68. package/dist/types/storage.js +2 -0
  69. package/dist/types/storage.js.map +1 -0
  70. package/dist/utils/hash.d.ts +13 -0
  71. package/dist/utils/hash.d.ts.map +1 -0
  72. package/dist/utils/hash.js +23 -0
  73. package/dist/utils/hash.js.map +1 -0
  74. package/dist/utils/path-validator.d.ts +46 -0
  75. package/dist/utils/path-validator.d.ts.map +1 -0
  76. package/dist/utils/path-validator.js +99 -0
  77. package/dist/utils/path-validator.js.map +1 -0
  78. package/llms.txt +46 -0
  79. package/package.json +14 -3
  80. package/src/core/bucket-db.ts +0 -43
  81. package/src/core/collection.ts +0 -173
  82. package/src/index/shard-manager.ts +0 -142
  83. package/src/index.ts +0 -37
  84. package/src/query/evaluator.ts +0 -87
  85. package/src/storage/ali-oss.d.ts +0 -43
  86. package/src/storage/fs-adapter.ts +0 -222
  87. package/src/storage/memory-adapter.ts +0 -105
  88. package/src/storage/oss-adapter.ts +0 -122
  89. package/src/storage/s3-adapter.ts +0 -151
  90. package/src/types/collection.ts +0 -34
  91. package/src/types/errors.ts +0 -49
  92. package/src/types/index.ts +0 -36
  93. package/src/types/query.ts +0 -50
  94. package/src/types/storage.ts +0 -46
  95. package/src/utils/hash.ts +0 -24
  96. package/tests/core/bucket-db.test.d.ts +0 -2
  97. package/tests/core/bucket-db.test.d.ts.map +0 -1
  98. package/tests/core/bucket-db.test.js +0 -34
  99. package/tests/core/bucket-db.test.js.map +0 -1
  100. package/tests/core/bucket-db.test.ts +0 -50
  101. package/tests/core/collection.test.d.ts +0 -2
  102. package/tests/core/collection.test.d.ts.map +0 -1
  103. package/tests/core/collection.test.js +0 -148
  104. package/tests/core/collection.test.js.map +0 -1
  105. package/tests/core/collection.test.ts +0 -195
  106. package/tests/core/dbpath.test.ts +0 -52
  107. package/tests/index/shard-manager.test.d.ts +0 -2
  108. package/tests/index/shard-manager.test.d.ts.map +0 -1
  109. package/tests/index/shard-manager.test.js +0 -106
  110. package/tests/index/shard-manager.test.js.map +0 -1
  111. package/tests/index/shard-manager.test.ts +0 -129
  112. package/tests/query/evaluator.test.d.ts +0 -2
  113. package/tests/query/evaluator.test.d.ts.map +0 -1
  114. package/tests/query/evaluator.test.js +0 -87
  115. package/tests/query/evaluator.test.js.map +0 -1
  116. package/tests/query/evaluator.test.ts +0 -104
  117. package/tests/storage/fs-adapter.test.ts +0 -111
  118. package/tests/storage/memory-adapter.test.d.ts +0 -2
  119. package/tests/storage/memory-adapter.test.d.ts.map +0 -1
  120. package/tests/storage/memory-adapter.test.js +0 -65
  121. package/tests/storage/memory-adapter.test.js.map +0 -1
  122. package/tests/storage/memory-adapter.test.ts +0 -84
  123. package/tests/storage/oss-adapter.test.d.ts +0 -2
  124. package/tests/storage/oss-adapter.test.d.ts.map +0 -1
  125. package/tests/storage/oss-adapter.test.js +0 -34
  126. package/tests/storage/oss-adapter.test.js.map +0 -1
  127. package/tests/storage/oss-adapter.test.ts +0 -40
  128. package/tests/storage/s3-adapter.test.d.ts +0 -2
  129. package/tests/storage/s3-adapter.test.d.ts.map +0 -1
  130. package/tests/storage/s3-adapter.test.js +0 -51
  131. package/tests/storage/s3-adapter.test.js.map +0 -1
  132. package/tests/storage/s3-adapter.test.ts +0 -62
  133. package/tests/utils/hash.test.d.ts +0 -2
  134. package/tests/utils/hash.test.d.ts.map +0 -1
  135. package/tests/utils/hash.test.js +0 -36
  136. package/tests/utils/hash.test.js.map +0 -1
  137. package/tests/utils/hash.test.ts +0 -42
  138. package/tsconfig.json +0 -12
@@ -0,0 +1,99 @@
1
+ import { join, resolve, relative } from 'path';
2
+ /**
3
+ * ValidationError for path validation failures
4
+ */
5
+ export class PathValidationError extends Error {
6
+ constructor(message) {
7
+ super(message);
8
+ this.name = 'PathValidationError';
9
+ }
10
+ }
11
+ /**
12
+ * Sanitize and validate path components to prevent directory traversal attacks
13
+ * This is for SINGLE path components (like collection names, document IDs)
14
+ *
15
+ * @param input - Path component to sanitize
16
+ * @returns Sanitized path component
17
+ * @throws PathValidationError if validation fails
18
+ */
19
+ export function sanitizePathComponent(input) {
20
+ if (!input || typeof input !== 'string') {
21
+ throw new PathValidationError('Path component must be a non-empty string');
22
+ }
23
+ // Remove any path traversal sequences
24
+ let sanitized = input.replace(/\.\./g, '');
25
+ // Remove directory separators (single components cannot have slashes)
26
+ sanitized = sanitized.replace(/[\/\\]/g, '_');
27
+ // Only allow alphanumeric, underscore, hyphen, and dot
28
+ if (!/^[a-zA-Z0-9_.-]+$/.test(sanitized)) {
29
+ throw new PathValidationError(`Invalid characters in path component. Only alphanumeric, underscore, hyphen, and dot are allowed.`);
30
+ }
31
+ // Prevent excessively long names
32
+ if (sanitized.length > 255) {
33
+ throw new PathValidationError('Path component exceeds maximum length of 255 characters');
34
+ }
35
+ // Prevent hidden files (starting with .)
36
+ if (sanitized.startsWith('.')) {
37
+ throw new PathValidationError('Path component cannot start with a dot');
38
+ }
39
+ return sanitized;
40
+ }
41
+ /**
42
+ * Validate that a target path is within the allowed base path
43
+ * Prevents directory traversal attacks by ensuring the resolved path
44
+ * doesn't escape the base directory
45
+ *
46
+ * @param basePath - Base directory path
47
+ * @param targetPath - Target path to validate
48
+ * @throws PathValidationError if path escapes base directory
49
+ */
50
+ export function validatePathWithinBase(basePath, targetPath) {
51
+ const normalizedBase = resolve(basePath);
52
+ const normalizedTarget = resolve(targetPath);
53
+ const relativePath = relative(normalizedBase, normalizedTarget);
54
+ // If relative path starts with '..', it's outside the base directory
55
+ if (relativePath.startsWith('..') || resolve(normalizedBase, relativePath) !== normalizedTarget) {
56
+ throw new PathValidationError('Path traversal detected: target path is outside base directory');
57
+ }
58
+ }
59
+ /**
60
+ * Safely join path components with validation
61
+ * This is for joining SINGLE components (not full paths with slashes)
62
+ *
63
+ * @param basePath - Base directory path
64
+ * @param components - Path components to join
65
+ * @returns Validated full path
66
+ * @throws PathValidationError if validation fails
67
+ */
68
+ export function safePathJoin(basePath, ...components) {
69
+ // Sanitize each component
70
+ const sanitizedComponents = components.map(sanitizePathComponent);
71
+ // Join paths
72
+ const fullPath = join(basePath, ...sanitizedComponents);
73
+ // Validate the result doesn't escape base path
74
+ validatePathWithinBase(basePath, fullPath);
75
+ return fullPath;
76
+ }
77
+ /**
78
+ * Safely join a key (which may contain slashes) with base path
79
+ * Validates the result doesn't escape base directory
80
+ *
81
+ * @param basePath - Base directory path
82
+ * @param key - Storage key (may contain path separators)
83
+ * @returns Validated full path
84
+ * @throws PathValidationError if validation fails
85
+ */
86
+ export function safeKeyPath(basePath, key) {
87
+ if (!key || typeof key !== 'string') {
88
+ throw new PathValidationError('Key must be a non-empty string');
89
+ }
90
+ // Check for path traversal patterns
91
+ if (key.includes('..')) {
92
+ throw new PathValidationError('Key contains path traversal sequence');
93
+ }
94
+ // Join and validate
95
+ const fullPath = join(basePath, key);
96
+ validatePathWithinBase(basePath, fullPath);
97
+ return fullPath;
98
+ }
99
+ //# sourceMappingURL=path-validator.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"path-validator.js","sourceRoot":"","sources":["../../src/utils/path-validator.ts"],"names":[],"mappings":"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"}
package/llms.txt ADDED
@@ -0,0 +1,46 @@
1
+ # BucketDB
2
+
3
+ TypeScript document database. Uses S3 / Alibaba Cloud OSS / local filesystem as backend. No database server required.
4
+
5
+ ## Key concepts
6
+
7
+ - `BucketDB` — main class, takes a storage adapter and a `dbPath` namespace
8
+ - `Collection<T>` — typed collection, returned by `db.collection<T>(name)`
9
+ - Every document extends `Document` which adds: `id` (UUID), `_etag`, `_createdAt`, `_updatedAt`
10
+ - `InsertDocument<T>` omits system fields (pass only your own fields)
11
+ - Optimistic locking: pass `{ etag: doc._etag }` to `update()` to prevent concurrent overwrites
12
+
13
+ ## Package: @hold-baby/bucket-db
14
+
15
+ ### Exports
16
+
17
+ Classes: BucketDB, Collection, MemoryStorageAdapter, FileSystemAdapter, S3Adapter, OSSAdapter
18
+ Errors: BucketDBError, DocumentNotFoundError, ConcurrentUpdateError, ValidationError, StorageError
19
+ Types: Document, InsertDocument, UpdateDocument, QueryFilter, QueryOptions, UpdateOptions, StorageAdapter
20
+
21
+ ### Collection API
22
+
23
+ ```
24
+ insert(data: InsertDocument<T>): Promise<T>
25
+ findById(id: string): Promise<T> // throws DocumentNotFoundError if missing
26
+ find(filter: QueryFilter<T>, options?: QueryOptions): Promise<T[]>
27
+ update(id: string, data: UpdateDocument<T>, options?: UpdateOptions): Promise<T>
28
+ delete(id: string, options?: UpdateOptions): Promise<void>
29
+ ```
30
+
31
+ ### QueryOptions
32
+
33
+ ```
34
+ { limit?: number, offset?: number }
35
+ ```
36
+
37
+ ### Query operators
38
+
39
+ $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin
40
+
41
+ ### Error mapping
42
+
43
+ DocumentNotFoundError — findById / update / delete on missing doc
44
+ ConcurrentUpdateError — update / delete with stale etag
45
+ ValidationError — invalid input
46
+ StorageError — underlying I/O failure
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@hold-baby/bucket-db",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
+ "description": "A TypeScript document database built on cloud object storage (AWS S3 / Alibaba Cloud OSS) or local file system. No database servers needed.",
4
5
  "type": "module",
5
6
  "main": "./dist/index.js",
6
7
  "types": "./dist/index.d.ts",
@@ -25,8 +26,14 @@
25
26
  "typescript": "^5.3.3"
26
27
  },
27
28
  "publishConfig": {
28
- "access": "public"
29
+ "access": "public",
30
+ "registry": "https://registry.npmjs.org/"
29
31
  },
32
+ "files": [
33
+ "dist",
34
+ "README.md",
35
+ "llms.txt"
36
+ ],
30
37
  "keywords": [
31
38
  "database",
32
39
  "document-db",
@@ -39,7 +46,11 @@
39
46
  "license": "MIT",
40
47
  "repository": {
41
48
  "type": "git",
42
- "url": "https://github.com/holdbaby5483/bucket-db.git",
49
+ "url": "git+https://github.com/holdbaby5483/bucket-db.git",
43
50
  "directory": "packages/core"
51
+ },
52
+ "homepage": "https://github.com/holdbaby5483/bucket-db#readme",
53
+ "bugs": {
54
+ "url": "https://github.com/holdbaby5483/bucket-db/issues"
44
55
  }
45
56
  }
@@ -1,43 +0,0 @@
1
- import type { StorageAdapter, Document } from '../types/index.js';
2
- import { Collection, CollectionOptions } from './collection.js';
3
-
4
- export interface BucketDBOptions {
5
- defaultShardCount?: number;
6
- }
7
-
8
- /**
9
- * Main BucketDB class
10
- */
11
- export class BucketDB {
12
- private collections = new Map<string, Collection<any>>();
13
-
14
- constructor(
15
- private adapter: StorageAdapter,
16
- private dbPath: string,
17
- private options: BucketDBOptions = {}
18
- ) {}
19
-
20
- /**
21
- * Get or create a collection
22
- */
23
- collection<T extends Document>(
24
- name: string,
25
- options?: CollectionOptions
26
- ): Collection<T> {
27
- if (this.collections.has(name)) {
28
- return this.collections.get(name)!;
29
- }
30
-
31
- const collection = new Collection<T>(
32
- this.adapter,
33
- this.dbPath,
34
- name,
35
- {
36
- shardCount: options?.shardCount || this.options.defaultShardCount || 16,
37
- }
38
- );
39
-
40
- this.collections.set(name, collection);
41
- return collection;
42
- }
43
- }
@@ -1,173 +0,0 @@
1
- import type {
2
- ICollection,
3
- Document,
4
- InsertDocument,
5
- UpdateDocument,
6
- QueryFilter,
7
- QueryOptions,
8
- UpdateOptions,
9
- StorageAdapter,
10
- } from '../types/index.js';
11
- import { DocumentNotFoundError, ConcurrentUpdateError } from '../types/index.js';
12
- import { ShardManager } from '../index/shard-manager.js';
13
-
14
- /**
15
- * Generate UUID v4
16
- */
17
- function generateId(): string {
18
- return crypto.randomUUID();
19
- }
20
-
21
- /**
22
- * Get current ISO timestamp
23
- */
24
- function now(): string {
25
- return new Date().toISOString();
26
- }
27
-
28
- export interface CollectionOptions {
29
- shardCount?: number;
30
- }
31
-
32
- /**
33
- * Collection class for type-safe CRUD operations
34
- */
35
- export class Collection<T extends Document> implements ICollection<T> {
36
- private shardManager: ShardManager;
37
- private basePath: string;
38
-
39
- constructor(
40
- private adapter: StorageAdapter,
41
- private dbPath: string,
42
- private collectionName: string,
43
- options: CollectionOptions = {}
44
- ) {
45
- this.basePath = `${dbPath}/${collectionName}`;
46
- this.shardManager = new ShardManager(
47
- adapter,
48
- this.basePath,
49
- options.shardCount || 16
50
- );
51
- }
52
-
53
- private getDocPath(id: string): string {
54
- return `${this.basePath}/docs/${id}.json`;
55
- }
56
-
57
- async insert(data: InsertDocument<T>): Promise<T> {
58
- const id = generateId();
59
- const timestamp = now();
60
-
61
- const document: T = {
62
- ...data,
63
- id,
64
- _createdAt: timestamp,
65
- _updatedAt: timestamp,
66
- } as T;
67
-
68
- // Write document to storage
69
- const { etag } = await this.adapter.put(this.getDocPath(id), document);
70
-
71
- document._etag = etag;
72
-
73
- // Add to index
74
- await this.shardManager.addDocument(document);
75
-
76
- return document;
77
- }
78
-
79
- async findById(id: string): Promise<T | null> {
80
- try {
81
- const { data, etag } = await this.adapter.get(this.getDocPath(id));
82
- const doc = data as T;
83
- doc._etag = etag;
84
- return doc;
85
- } catch (error) {
86
- return null;
87
- }
88
- }
89
-
90
- async find(filter: QueryFilter<T>, options?: QueryOptions): Promise<T[]> {
91
- // Query index to get matching document IDs
92
- const indexResults = await this.shardManager.query(filter);
93
-
94
- // Get full documents
95
- const ids = indexResults.map(doc => doc.id);
96
-
97
- if (ids.length === 0) {
98
- return [];
99
- }
100
-
101
- // Batch get documents
102
- const docMap = await this.adapter.batchGet(ids.map(id => this.getDocPath(id)));
103
-
104
- let results = Array.from(docMap.values()).map(obj => {
105
- const doc = obj.data as T;
106
- doc._etag = obj.etag;
107
- return doc;
108
- });
109
-
110
- // Apply pagination
111
- if (options?.offset) {
112
- results = results.slice(options.offset);
113
- }
114
- if (options?.limit) {
115
- results = results.slice(0, options.limit);
116
- }
117
-
118
- return results;
119
- }
120
-
121
- async update(
122
- id: string,
123
- data: UpdateDocument<T>,
124
- options?: UpdateOptions
125
- ): Promise<T> {
126
- // Get current document
127
- const current = await this.findById(id);
128
- if (!current) {
129
- throw new DocumentNotFoundError(id);
130
- }
131
-
132
- // Check optimistic lock if etag provided
133
- if (options?.etag && current._etag !== options.etag) {
134
- throw new ConcurrentUpdateError(`ETag mismatch for document ${id}`);
135
- }
136
-
137
- // Merge updates
138
- const updated: T = {
139
- ...current,
140
- ...data,
141
- id,
142
- _updatedAt: now(),
143
- } as T;
144
-
145
- // Write document
146
- const { etag } = await this.adapter.put(
147
- this.getDocPath(id),
148
- updated,
149
- current._etag ? { ifMatch: current._etag } : undefined
150
- );
151
-
152
- updated._etag = etag;
153
-
154
- // Update index
155
- await this.shardManager.updateDocument(updated);
156
-
157
- return updated;
158
- }
159
-
160
- async delete(id: string): Promise<void> {
161
- // Check if document exists
162
- const exists = await this.findById(id);
163
- if (!exists) {
164
- throw new DocumentNotFoundError(id);
165
- }
166
-
167
- // Delete from storage
168
- await this.adapter.delete(this.getDocPath(id));
169
-
170
- // Remove from index
171
- await this.shardManager.removeDocument(id);
172
- }
173
- }
@@ -1,142 +0,0 @@
1
- import type { StorageAdapter, IndexShard, QueryFilter } from '../types/index.js';
2
- import { StorageError } from '../types/index.js';
3
- import { getShardId, formatShardId } from '../utils/hash.js';
4
- import { evaluateFilter } from '../query/evaluator.js';
5
-
6
- /**
7
- * Manages index shards for a collection
8
- */
9
- export class ShardManager {
10
- constructor(
11
- private adapter: StorageAdapter,
12
- private collectionPath: string,
13
- private shardCount: number
14
- ) {}
15
-
16
- private getShardPath(shardId: number): string {
17
- return `${this.collectionPath}/index/shard-${formatShardId(shardId)}.json`;
18
- }
19
-
20
- private async readShard(shardId: number): Promise<IndexShard> {
21
- const path = this.getShardPath(shardId);
22
- try {
23
- const { data } = await this.adapter.get(path);
24
- return data as IndexShard;
25
- } catch (error) {
26
- // Return empty shard if not found
27
- return {
28
- shardId: formatShardId(shardId),
29
- documents: {},
30
- };
31
- }
32
- }
33
-
34
- private async writeShard(shardId: number, shard: IndexShard, etag?: string): Promise<void> {
35
- const path = this.getShardPath(shardId);
36
- await this.adapter.put(path, shard, etag ? { ifMatch: etag } : undefined);
37
- }
38
-
39
- /**
40
- * Add document to index
41
- */
42
- async addDocument(doc: Record<string, any>): Promise<void> {
43
- const docId = doc.id;
44
- const shardId = getShardId(docId, this.shardCount);
45
-
46
- // Retry logic for optimistic locking
47
- let retries = 3;
48
- while (retries > 0) {
49
- try {
50
- const shard = await this.readShard(shardId);
51
- const currentEtag = shard.documents[docId] ?
52
- (await this.adapter.get(this.getShardPath(shardId))).etag :
53
- undefined;
54
-
55
- shard.documents[docId] = { ...doc };
56
-
57
- await this.writeShard(shardId, shard, currentEtag);
58
- return;
59
- } catch (error) {
60
- if (error instanceof StorageError && error.message.includes('PreconditionFailed')) {
61
- retries--;
62
- await new Promise(resolve => setTimeout(resolve, 100 * (4 - retries)));
63
- continue;
64
- }
65
- throw error;
66
- }
67
- }
68
- throw new StorageError('Failed to add document after retries');
69
- }
70
-
71
- /**
72
- * Update document in index
73
- */
74
- async updateDocument(doc: Record<string, any>): Promise<void> {
75
- await this.addDocument(doc); // Same as add - upsert behavior
76
- }
77
-
78
- /**
79
- * Remove document from index
80
- */
81
- async removeDocument(docId: string): Promise<void> {
82
- const shardId = getShardId(docId, this.shardCount);
83
-
84
- let retries = 3;
85
- while (retries > 0) {
86
- try {
87
- const { etag } = await this.adapter.get(this.getShardPath(shardId));
88
- const shard = await this.readShard(shardId);
89
-
90
- delete shard.documents[docId];
91
-
92
- await this.writeShard(shardId, shard, etag);
93
- return;
94
- } catch (error) {
95
- if (error instanceof StorageError && error.message.includes('PreconditionFailed')) {
96
- retries--;
97
- await new Promise(resolve => setTimeout(resolve, 100 * (4 - retries)));
98
- continue;
99
- }
100
- // Ignore if shard doesn't exist
101
- if (error instanceof StorageError && error.message.includes('not found')) {
102
- return;
103
- }
104
- throw error;
105
- }
106
- }
107
- }
108
-
109
- /**
110
- * Find document by ID
111
- */
112
- async findById(docId: string): Promise<Record<string, any> | null> {
113
- const shardId = getShardId(docId, this.shardCount);
114
- const shard = await this.readShard(shardId);
115
- return shard.documents[docId] || null;
116
- }
117
-
118
- /**
119
- * Query documents matching filter
120
- */
121
- async query(filter: QueryFilter<any>): Promise<Array<Record<string, any>>> {
122
- // Read all shards in parallel
123
- const shardPromises = Array.from(
124
- { length: this.shardCount },
125
- (_, i) => this.readShard(i)
126
- );
127
-
128
- const shards = await Promise.all(shardPromises);
129
-
130
- // Filter documents across all shards
131
- const results: Array<Record<string, any>> = [];
132
- for (const shard of shards) {
133
- for (const doc of Object.values(shard.documents)) {
134
- if (evaluateFilter(doc, filter)) {
135
- results.push(doc);
136
- }
137
- }
138
- }
139
-
140
- return results;
141
- }
142
- }
package/src/index.ts DELETED
@@ -1,37 +0,0 @@
1
- // Core classes
2
- export { BucketDB } from './core/bucket-db.js';
3
- export { Collection } from './core/collection.js';
4
-
5
- // Storage adapters
6
- export { MemoryStorageAdapter } from './storage/memory-adapter.js';
7
- export { S3Adapter } from './storage/s3-adapter.js';
8
- export { OSSAdapter } from './storage/oss-adapter.js';
9
- export { FileSystemAdapter } from './storage/fs-adapter.js';
10
-
11
- // Re-export types from @bucket-db/types
12
- export type {
13
- Document,
14
- InsertDocument,
15
- UpdateDocument,
16
- QueryOperator,
17
- QueryValue,
18
- QueryFilter,
19
- QueryOptions,
20
- UpdateOptions,
21
- StorageAdapter,
22
- StorageObject,
23
- PutOptions,
24
- StorageCredentials,
25
- StorageAdapterConfig,
26
- ICollection,
27
- CollectionMeta,
28
- IndexShard,
29
- } from './types/index.js';
30
-
31
- export {
32
- BucketDBError,
33
- DocumentNotFoundError,
34
- ConcurrentUpdateError,
35
- ValidationError,
36
- StorageError,
37
- } from './types/index.js';
@@ -1,87 +0,0 @@
1
- import type { QueryValue, QueryFilter } from '../types/index.js';
2
-
3
- /**
4
- * Evaluates a single operator condition
5
- */
6
- export function evaluateOperator<T>(
7
- value: T,
8
- condition: QueryValue<T>
9
- ): boolean {
10
- // Direct value comparison (implicit $eq)
11
- if (typeof condition !== 'object' || condition === null || Array.isArray(condition)) {
12
- return value === condition;
13
- }
14
-
15
- const operators = condition as Record<string, any>;
16
-
17
- // Check all operators (AND logic)
18
- for (const [op, operand] of Object.entries(operators)) {
19
- switch (op) {
20
- case '$eq':
21
- if (value !== operand) return false;
22
- break;
23
-
24
- case '$ne':
25
- if (value === operand) return false;
26
- break;
27
-
28
- case '$gt':
29
- if (!(value > operand)) return false;
30
- break;
31
-
32
- case '$gte':
33
- if (!(value >= operand)) return false;
34
- break;
35
-
36
- case '$lt':
37
- if (!(value < operand)) return false;
38
- break;
39
-
40
- case '$lte':
41
- if (!(value <= operand)) return false;
42
- break;
43
-
44
- case '$in':
45
- if (!Array.isArray(operand) || !operand.includes(value)) return false;
46
- break;
47
-
48
- case '$nin':
49
- if (!Array.isArray(operand) || operand.includes(value)) return false;
50
- break;
51
-
52
- default:
53
- throw new Error(`Unknown operator: ${op}`);
54
- }
55
- }
56
-
57
- return true;
58
- }
59
-
60
- /**
61
- * Evaluates a complete filter against a document
62
- */
63
- export function evaluateFilter<T extends Record<string, any>>(
64
- document: T,
65
- filter: QueryFilter<T>
66
- ): boolean {
67
- // Empty filter matches all documents
68
- if (Object.keys(filter).length === 0) {
69
- return true;
70
- }
71
-
72
- // All conditions must match (AND logic)
73
- for (const [field, condition] of Object.entries(filter)) {
74
- const value = document[field];
75
-
76
- // If field doesn't exist in document, fail the match
77
- if (value === undefined) {
78
- return false;
79
- }
80
-
81
- if (!evaluateOperator(value, condition as QueryValue<any>)) {
82
- return false;
83
- }
84
- }
85
-
86
- return true;
87
- }