@hold-baby/bucket-db 0.3.1 → 0.5.0

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 (114) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +331 -62
  3. package/dist/bucket-db.d.ts +25 -0
  4. package/dist/bucket-db.js +36 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +133 -0
  7. package/dist/collection.d.ts +78 -0
  8. package/dist/collection.js +321 -0
  9. package/dist/doctor.d.ts +7 -0
  10. package/dist/doctor.js +100 -0
  11. package/dist/errors.d.ts +59 -0
  12. package/dist/errors.js +57 -0
  13. package/dist/index.d.ts +13 -9
  14. package/dist/index.js +6 -10
  15. package/dist/keys.d.ts +12 -0
  16. package/dist/keys.js +31 -0
  17. package/dist/query.d.ts +16 -0
  18. package/dist/query.js +133 -0
  19. package/dist/snapshot.d.ts +16 -0
  20. package/dist/snapshot.js +40 -0
  21. package/dist/storage/adapter.d.ts +75 -0
  22. package/dist/storage/adapter.js +27 -0
  23. package/dist/storage/fs.d.ts +28 -0
  24. package/dist/storage/fs.js +175 -0
  25. package/dist/storage/memory.d.ts +18 -0
  26. package/dist/storage/memory.js +49 -0
  27. package/dist/storage/s3/adapters.d.ts +38 -0
  28. package/dist/storage/s3/adapters.js +65 -0
  29. package/dist/storage/s3/client.d.ts +52 -0
  30. package/dist/storage/s3/client.js +231 -0
  31. package/dist/storage/s3/credentials.d.ts +17 -0
  32. package/dist/storage/s3/credentials.js +42 -0
  33. package/dist/storage/s3/sigv4.d.ts +32 -0
  34. package/dist/storage/s3/sigv4.js +75 -0
  35. package/dist/types.d.ts +55 -0
  36. package/dist/types.js +1 -0
  37. package/dist/url.d.ts +16 -0
  38. package/dist/url.js +66 -0
  39. package/llms.txt +116 -20
  40. package/package.json +7 -5
  41. package/dist/cache/lru-cache.d.ts +0 -47
  42. package/dist/cache/lru-cache.d.ts.map +0 -1
  43. package/dist/cache/lru-cache.js +0 -110
  44. package/dist/cache/lru-cache.js.map +0 -1
  45. package/dist/core/bucket-db.d.ts +0 -20
  46. package/dist/core/bucket-db.d.ts.map +0 -1
  47. package/dist/core/bucket-db.js +0 -32
  48. package/dist/core/bucket-db.js.map +0 -1
  49. package/dist/core/collection.d.ts +0 -26
  50. package/dist/core/collection.d.ts.map +0 -1
  51. package/dist/core/collection.js +0 -213
  52. package/dist/core/collection.js.map +0 -1
  53. package/dist/core/wal.d.ts +0 -45
  54. package/dist/core/wal.d.ts.map +0 -1
  55. package/dist/core/wal.js +0 -80
  56. package/dist/core/wal.js.map +0 -1
  57. package/dist/index/shard-manager.d.ts +0 -36
  58. package/dist/index/shard-manager.d.ts.map +0 -1
  59. package/dist/index/shard-manager.js +0 -177
  60. package/dist/index/shard-manager.js.map +0 -1
  61. package/dist/index.d.ts.map +0 -1
  62. package/dist/index.js.map +0 -1
  63. package/dist/query/evaluator.d.ts +0 -10
  64. package/dist/query/evaluator.d.ts.map +0 -1
  65. package/dist/query/evaluator.js +0 -127
  66. package/dist/query/evaluator.js.map +0 -1
  67. package/dist/storage/fs-adapter.d.ts +0 -24
  68. package/dist/storage/fs-adapter.d.ts.map +0 -1
  69. package/dist/storage/fs-adapter.js +0 -208
  70. package/dist/storage/fs-adapter.js.map +0 -1
  71. package/dist/storage/memory-adapter.d.ts +0 -22
  72. package/dist/storage/memory-adapter.d.ts.map +0 -1
  73. package/dist/storage/memory-adapter.js +0 -78
  74. package/dist/storage/memory-adapter.js.map +0 -1
  75. package/dist/storage/oss-adapter.d.ts +0 -26
  76. package/dist/storage/oss-adapter.d.ts.map +0 -1
  77. package/dist/storage/oss-adapter.js +0 -145
  78. package/dist/storage/oss-adapter.js.map +0 -1
  79. package/dist/storage/s3-adapter.d.ts +0 -26
  80. package/dist/storage/s3-adapter.d.ts.map +0 -1
  81. package/dist/storage/s3-adapter.js +0 -170
  82. package/dist/storage/s3-adapter.js.map +0 -1
  83. package/dist/types/collection.d.ts +0 -40
  84. package/dist/types/collection.d.ts.map +0 -1
  85. package/dist/types/collection.js +0 -2
  86. package/dist/types/collection.js.map +0 -1
  87. package/dist/types/document.d.ts +0 -18
  88. package/dist/types/document.d.ts.map +0 -1
  89. package/dist/types/document.js +0 -2
  90. package/dist/types/document.js.map +0 -1
  91. package/dist/types/errors.d.ts +0 -32
  92. package/dist/types/errors.d.ts.map +0 -1
  93. package/dist/types/errors.js +0 -48
  94. package/dist/types/errors.js.map +0 -1
  95. package/dist/types/index.d.ts +0 -6
  96. package/dist/types/index.d.ts.map +0 -1
  97. package/dist/types/index.js +0 -3
  98. package/dist/types/index.js.map +0 -1
  99. package/dist/types/query.d.ts +0 -37
  100. package/dist/types/query.d.ts.map +0 -1
  101. package/dist/types/query.js +0 -2
  102. package/dist/types/query.js.map +0 -1
  103. package/dist/types/storage.d.ts +0 -45
  104. package/dist/types/storage.d.ts.map +0 -1
  105. package/dist/types/storage.js +0 -2
  106. package/dist/types/storage.js.map +0 -1
  107. package/dist/utils/hash.d.ts +0 -13
  108. package/dist/utils/hash.d.ts.map +0 -1
  109. package/dist/utils/hash.js +0 -23
  110. package/dist/utils/hash.js.map +0 -1
  111. package/dist/utils/path-validator.d.ts +0 -46
  112. package/dist/utils/path-validator.d.ts.map +0 -1
  113. package/dist/utils/path-validator.js +0 -99
  114. package/dist/utils/path-validator.js.map +0 -1
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Base class for every error BucketDB throws.
3
+ */
4
+ export declare class BucketDBError extends Error {
5
+ constructor(message: string, options?: {
6
+ cause?: unknown;
7
+ });
8
+ }
9
+ /**
10
+ * Invalid input: collection name, document ID, dbPath or filter.
11
+ */
12
+ export declare class ValidationError extends BucketDBError {
13
+ }
14
+ /**
15
+ * `update` on a document that does not exist.
16
+ */
17
+ export declare class DocumentNotFoundError extends BucketDBError {
18
+ constructor(id: string);
19
+ }
20
+ /**
21
+ * `update` lost a race: the supplied etag is stale, or retries were exhausted.
22
+ */
23
+ export declare class ConcurrentUpdateError extends BucketDBError {
24
+ constructor(message?: string);
25
+ }
26
+ /**
27
+ * The operation needs a capability the storage backend does not provide.
28
+ */
29
+ export declare class UnsupportedError extends BucketDBError {
30
+ }
31
+ /**
32
+ * - `not-found`: the object does not exist
33
+ * - `conflict`: a write condition (ifNoneMatch / ifMatch) was not met
34
+ * - `transient`: a retryable failure that persisted after retries
35
+ * - `permanent`: anything else (permissions, malformed data, …)
36
+ */
37
+ export type StorageErrorKind = 'not-found' | 'conflict' | 'transient' | 'permanent';
38
+ export interface StorageErrorOptions {
39
+ kind?: StorageErrorKind;
40
+ key?: string;
41
+ /** HTTP status, for HTTP backends */
42
+ status?: number;
43
+ cause?: unknown;
44
+ }
45
+ /**
46
+ * A storage backend failure.
47
+ */
48
+ export declare class StorageError extends BucketDBError {
49
+ readonly kind: StorageErrorKind;
50
+ readonly key?: string;
51
+ readonly status?: number;
52
+ constructor(message: string, options?: StorageErrorOptions);
53
+ }
54
+ /**
55
+ * `insert` with an explicit id that is already taken.
56
+ */
57
+ export declare class DocumentExistsError extends BucketDBError {
58
+ constructor(id: string);
59
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Base class for every error BucketDB throws.
3
+ */
4
+ export class BucketDBError extends Error {
5
+ constructor(message, options) {
6
+ super(message, options);
7
+ this.name = new.target.name;
8
+ }
9
+ }
10
+ /**
11
+ * Invalid input: collection name, document ID, dbPath or filter.
12
+ */
13
+ export class ValidationError extends BucketDBError {
14
+ }
15
+ /**
16
+ * `update` on a document that does not exist.
17
+ */
18
+ export class DocumentNotFoundError extends BucketDBError {
19
+ constructor(id) {
20
+ super(`Document not found: ${id}`);
21
+ }
22
+ }
23
+ /**
24
+ * `update` lost a race: the supplied etag is stale, or retries were exhausted.
25
+ */
26
+ export class ConcurrentUpdateError extends BucketDBError {
27
+ constructor(message = 'Concurrent update conflict, please retry') {
28
+ super(message);
29
+ }
30
+ }
31
+ /**
32
+ * The operation needs a capability the storage backend does not provide.
33
+ */
34
+ export class UnsupportedError extends BucketDBError {
35
+ }
36
+ /**
37
+ * A storage backend failure.
38
+ */
39
+ export class StorageError extends BucketDBError {
40
+ kind;
41
+ key;
42
+ status;
43
+ constructor(message, options = {}) {
44
+ super(message, { cause: options.cause });
45
+ this.kind = options.kind ?? 'permanent';
46
+ this.key = options.key;
47
+ this.status = options.status;
48
+ }
49
+ }
50
+ /**
51
+ * `insert` with an explicit id that is already taken.
52
+ */
53
+ export class DocumentExistsError extends BucketDBError {
54
+ constructor(id) {
55
+ super(`Document already exists: ${id}`);
56
+ }
57
+ }
package/dist/index.d.ts CHANGED
@@ -1,9 +1,13 @@
1
- export { BucketDB } from './core/bucket-db.js';
2
- export { Collection } from './core/collection.js';
3
- export { MemoryStorageAdapter } from './storage/memory-adapter.js';
4
- export { S3Adapter } from './storage/s3-adapter.js';
5
- export { OSSAdapter } from './storage/oss-adapter.js';
6
- export { FileSystemAdapter } from './storage/fs-adapter.js';
7
- export type { Document, InsertDocument, UpdateDocument, QueryOperator, QueryValue, QueryFilter, QueryOptions, UpdateOptions, StorageAdapter, StorageObject, PutOptions, StorageCredentials, StorageAdapterConfig, ICollection, CollectionMeta, IndexShard, } from './types/index.js';
8
- export { BucketDBError, DocumentNotFoundError, ConcurrentUpdateError, ValidationError, StorageError, } from './types/index.js';
9
- //# sourceMappingURL=index.d.ts.map
1
+ export { BucketDB } from './bucket-db.js';
2
+ export type { BucketDBOptions } from './bucket-db.js';
3
+ export { Collection } from './collection.js';
4
+ export type { CollectionOptions } from './collection.js';
5
+ export { MemoryStorageAdapter } from './storage/memory.js';
6
+ export { FileSystemAdapter } from './storage/fs.js';
7
+ export type { FileSystemAdapterConfig } from './storage/fs.js';
8
+ export { S3Adapter, OSSAdapter } from './storage/s3/adapters.js';
9
+ export type { S3AdapterOptions, OSSAdapterOptions, Credentials, CredentialProvider } from './storage/s3/adapters.js';
10
+ export type { StorageAdapter, Capabilities, Guarantee, WriteCondition, ObjectEntry, ListPage, ListOptions, } from './storage/adapter.js';
11
+ export type { Document, InsertDocument, UpdateDocument, QueryOperator, QueryValue, QueryFilter, QueryOptions, UpdateOptions, InsertOptions, Logger, LogEvent, } from './types.js';
12
+ export { BucketDBError, ValidationError, DocumentNotFoundError, DocumentExistsError, ConcurrentUpdateError, UnsupportedError, StorageError, } from './errors.js';
13
+ export type { StorageErrorKind, StorageErrorOptions } from './errors.js';
package/dist/index.js CHANGED
@@ -1,10 +1,6 @@
1
- // Core classes
2
- export { BucketDB } from './core/bucket-db.js';
3
- export { Collection } from './core/collection.js';
4
- // Storage adapters
5
- export { MemoryStorageAdapter } from './storage/memory-adapter.js';
6
- export { S3Adapter } from './storage/s3-adapter.js';
7
- export { OSSAdapter } from './storage/oss-adapter.js';
8
- export { FileSystemAdapter } from './storage/fs-adapter.js';
9
- export { BucketDBError, DocumentNotFoundError, ConcurrentUpdateError, ValidationError, StorageError, } from './types/index.js';
10
- //# sourceMappingURL=index.js.map
1
+ export { BucketDB } from './bucket-db.js';
2
+ export { Collection } from './collection.js';
3
+ export { MemoryStorageAdapter } from './storage/memory.js';
4
+ export { FileSystemAdapter } from './storage/fs.js';
5
+ export { S3Adapter, OSSAdapter } from './storage/s3/adapters.js';
6
+ export { BucketDBError, ValidationError, DocumentNotFoundError, DocumentExistsError, ConcurrentUpdateError, UnsupportedError, StorageError, } from './errors.js';
package/dist/keys.d.ts ADDED
@@ -0,0 +1,12 @@
1
+ export declare function isValidName(value: unknown): value is string;
2
+ /**
3
+ * Collection names, document IDs and dbPath segments: 1-255 letters, digits,
4
+ * `_`, `-` or `.`, not starting with `.`. Invalid input is rejected, never rewritten.
5
+ */
6
+ export declare function validateName(kind: string, value: unknown): string;
7
+ /**
8
+ * `dbPath` is a `/`-separated key prefix; `''` means the bucket root.
9
+ */
10
+ export declare function validateDbPath(dbPath: unknown): string;
11
+ /** Key prefix under which a collection's documents live, ending with `/`. */
12
+ export declare function docsPrefix(dbPath: string, collection: string): string;
package/dist/keys.js ADDED
@@ -0,0 +1,31 @@
1
+ import { ValidationError } from './errors.js';
2
+ const NAME = /^[A-Za-z0-9_.-]{1,255}$/;
3
+ export function isValidName(value) {
4
+ return typeof value === 'string' && NAME.test(value) && !value.startsWith('.');
5
+ }
6
+ /**
7
+ * Collection names, document IDs and dbPath segments: 1-255 letters, digits,
8
+ * `_`, `-` or `.`, not starting with `.`. Invalid input is rejected, never rewritten.
9
+ */
10
+ export function validateName(kind, value) {
11
+ if (!isValidName(value)) {
12
+ throw new ValidationError(`Invalid ${kind} ${JSON.stringify(value)}: use 1-255 letters, digits, '_', '-' or '.', not starting with '.'`);
13
+ }
14
+ return value;
15
+ }
16
+ /**
17
+ * `dbPath` is a `/`-separated key prefix; `''` means the bucket root.
18
+ */
19
+ export function validateDbPath(dbPath) {
20
+ if (dbPath === '')
21
+ return dbPath;
22
+ if (typeof dbPath !== 'string')
23
+ throw new ValidationError(`Invalid dbPath ${JSON.stringify(dbPath)}`);
24
+ for (const segment of dbPath.split('/'))
25
+ validateName('dbPath segment', segment);
26
+ return dbPath;
27
+ }
28
+ /** Key prefix under which a collection's documents live, ending with `/`. */
29
+ export function docsPrefix(dbPath, collection) {
30
+ return `${dbPath === '' ? '' : `${dbPath}/`}${collection}/docs/`;
31
+ }
@@ -0,0 +1,16 @@
1
+ import type { QueryFilter } from './types.js';
2
+ /**
3
+ * Rejects reserved field names, unknown operators and non-array `$in` / `$nin` operands.
4
+ */
5
+ export declare function validateFilter(filter: QueryFilter<unknown>): void;
6
+ /**
7
+ * True when `document` satisfies every condition in `filter` (AND).
8
+ * Call `validateFilter` first.
9
+ */
10
+ export declare function evaluateFilter(document: Record<string, unknown>, filter: QueryFilter<unknown>): boolean;
11
+ export type SortSpec = Record<string, 1 | -1>;
12
+ /**
13
+ * Sorts by the fields of `sort` in order (1 ascending, -1 descending), then by
14
+ * `_createdAt` and `id`. Missing or null values sort last in either direction.
15
+ */
16
+ export declare function sortDocuments<D extends Record<string, unknown>>(documents: D[], sort?: SortSpec): D[];
package/dist/query.js ADDED
@@ -0,0 +1,133 @@
1
+ import { ValidationError } from './errors.js';
2
+ const ALLOWED_OPERATORS = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin']);
3
+ /** Field names that would reach the prototype chain. */
4
+ const RESERVED_FIELDS = new Set([
5
+ '__proto__',
6
+ 'constructor',
7
+ 'prototype',
8
+ 'toString',
9
+ 'valueOf',
10
+ 'hasOwnProperty',
11
+ 'isPrototypeOf',
12
+ 'propertyIsEnumerable',
13
+ ]);
14
+ const isOperatorObject = (condition) => typeof condition === 'object' && condition !== null && !Array.isArray(condition);
15
+ /**
16
+ * Rejects reserved field names, unknown operators and non-array `$in` / `$nin` operands.
17
+ */
18
+ export function validateFilter(filter) {
19
+ for (const [field, condition] of Object.entries(filter)) {
20
+ if (RESERVED_FIELDS.has(field)) {
21
+ throw new ValidationError(`Query contains forbidden field name: ${field}`);
22
+ }
23
+ if (!isOperatorObject(condition))
24
+ continue;
25
+ for (const [operator, operand] of Object.entries(condition)) {
26
+ if (!ALLOWED_OPERATORS.has(operator)) {
27
+ throw new ValidationError(`Query contains invalid operator: ${operator}`);
28
+ }
29
+ if ((operator === '$in' || operator === '$nin') && !Array.isArray(operand)) {
30
+ throw new ValidationError(`${operator} operator requires an array operand`);
31
+ }
32
+ }
33
+ }
34
+ }
35
+ /** A missing field is `undefined`: it fails `$eq` / ranges / `$in` and satisfies `$ne` / `$nin`. */
36
+ function evaluateCondition(value, condition) {
37
+ // a plain value means $eq
38
+ if (!isOperatorObject(condition))
39
+ return value === condition;
40
+ // all operators must hold
41
+ for (const [operator, operand] of Object.entries(condition)) {
42
+ switch (operator) {
43
+ case '$eq':
44
+ if (value !== operand)
45
+ return false;
46
+ break;
47
+ case '$ne':
48
+ if (value === operand)
49
+ return false;
50
+ break;
51
+ case '$gt':
52
+ case '$gte':
53
+ case '$lt':
54
+ case '$lte': {
55
+ // only number-to-number and string-to-string comparisons can match
56
+ if (typeof value !== typeof operand || (typeof value !== 'number' && typeof value !== 'string'))
57
+ return false;
58
+ const right = operand;
59
+ if (operator === '$gt' && !(value > right))
60
+ return false;
61
+ if (operator === '$gte' && !(value >= right))
62
+ return false;
63
+ if (operator === '$lt' && !(value < right))
64
+ return false;
65
+ if (operator === '$lte' && !(value <= right))
66
+ return false;
67
+ break;
68
+ }
69
+ case '$in':
70
+ if (!operand.includes(value))
71
+ return false;
72
+ break;
73
+ case '$nin':
74
+ if (operand.includes(value))
75
+ return false;
76
+ break;
77
+ }
78
+ }
79
+ return true;
80
+ }
81
+ /**
82
+ * True when `document` satisfies every condition in `filter` (AND).
83
+ * Call `validateFilter` first.
84
+ */
85
+ export function evaluateFilter(document, filter) {
86
+ for (const [field, condition] of Object.entries(filter)) {
87
+ const value = Object.hasOwn(document, field) ? document[field] : undefined;
88
+ if (!evaluateCondition(value, condition))
89
+ return false;
90
+ }
91
+ return true;
92
+ }
93
+ /** booleans < numbers < strings < everything else (compared as JSON) */
94
+ function rank(value) {
95
+ const order = ['boolean', 'number', 'string'].indexOf(typeof value);
96
+ return order === -1 ? 3 : order;
97
+ }
98
+ function compareValues(a, b) {
99
+ if (rank(a) !== rank(b))
100
+ return rank(a) - rank(b);
101
+ const [left, right] = rank(a) === 3 ? [JSON.stringify(a), JSON.stringify(b)] : [a, b];
102
+ return left < right ? -1 : left > right ? 1 : 0;
103
+ }
104
+ /**
105
+ * Sorts by the fields of `sort` in order (1 ascending, -1 descending), then by
106
+ * `_createdAt` and `id`. Missing or null values sort last in either direction.
107
+ */
108
+ export function sortDocuments(documents, sort = {}) {
109
+ const keys = Object.entries(sort);
110
+ for (const [field, direction] of keys) {
111
+ if (RESERVED_FIELDS.has(field) || (direction !== 1 && direction !== -1)) {
112
+ throw new ValidationError(`Invalid sort ${JSON.stringify({ [field]: direction })}: use 1 or -1 per field`);
113
+ }
114
+ }
115
+ for (const field of ['_createdAt', 'id'])
116
+ if (!(field in sort))
117
+ keys.push([field, 1]);
118
+ return documents.sort((a, b) => {
119
+ for (const [field, direction] of keys) {
120
+ const left = a[field] ?? undefined;
121
+ const right = b[field] ?? undefined;
122
+ if (left === undefined || right === undefined) {
123
+ if (left !== right)
124
+ return left === undefined ? 1 : -1;
125
+ continue;
126
+ }
127
+ const order = compareValues(left, right) * direction;
128
+ if (order !== 0)
129
+ return order;
130
+ }
131
+ return 0;
132
+ });
133
+ }
@@ -0,0 +1,16 @@
1
+ import type { Document } from './types.js';
2
+ /**
3
+ * A disposable cache of a collection's documents, stored next to `docs/`.
4
+ * Entries are trusted only when their etag equals the one LIST reports for
5
+ * the document, so a missing, stale, corrupt or overwritten snapshot changes
6
+ * how many GETs a query needs, never its result.
7
+ */
8
+ export declare const SNAPSHOT_NAME = "_snapshot.v1.json";
9
+ export interface SnapshotEntry {
10
+ etag: string;
11
+ /** Document body without `id` and `_etag`. */
12
+ body: Record<string, unknown>;
13
+ }
14
+ /** `undefined` when the bytes are not a version-1 snapshot. */
15
+ export declare function parseSnapshot(bytes: Uint8Array): Map<string, SnapshotEntry> | undefined;
16
+ export declare function encodeSnapshot(documents: Document[]): Uint8Array;
@@ -0,0 +1,40 @@
1
+ import { isValidName } from './keys.js';
2
+ /**
3
+ * A disposable cache of a collection's documents, stored next to `docs/`.
4
+ * Entries are trusted only when their etag equals the one LIST reports for
5
+ * the document, so a missing, stale, corrupt or overwritten snapshot changes
6
+ * how many GETs a query needs, never its result.
7
+ */
8
+ export const SNAPSHOT_NAME = '_snapshot.v1.json';
9
+ const FORMAT = 'bucket-db-snapshot';
10
+ const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
11
+ const decoder = new TextDecoder();
12
+ const encoder = new TextEncoder();
13
+ /** `undefined` when the bytes are not a version-1 snapshot. */
14
+ export function parseSnapshot(bytes) {
15
+ let data;
16
+ try {
17
+ data = JSON.parse(decoder.decode(bytes));
18
+ }
19
+ catch {
20
+ return undefined;
21
+ }
22
+ if (!isObject(data) || data.format !== FORMAT || data.version !== 1 || !isObject(data.documents)) {
23
+ return undefined;
24
+ }
25
+ const entries = new Map();
26
+ for (const [id, entry] of Object.entries(data.documents)) {
27
+ if (isValidName(id) && isObject(entry) && typeof entry.etag === 'string' && isObject(entry.body)) {
28
+ entries.set(id, { etag: entry.etag, body: entry.body });
29
+ }
30
+ }
31
+ return entries;
32
+ }
33
+ export function encodeSnapshot(documents) {
34
+ // null prototype: `__proto__` is a valid document id
35
+ const entries = Object.create(null);
36
+ for (const { id, _etag, ...body } of documents) {
37
+ entries[id] = { etag: _etag ?? '', body: body };
38
+ }
39
+ return encoder.encode(JSON.stringify({ format: FORMAT, version: 1, documents: entries }));
40
+ }
@@ -0,0 +1,75 @@
1
+ import { StorageError } from '../errors.js';
2
+ /**
3
+ * How strongly a backend enforces a write condition:
4
+ * - `atomic`: enforced by the storage service, across processes
5
+ * - `single-process`: enforced only among writers in one process
6
+ * - `none`: not supported; requesting it throws UnsupportedError
7
+ */
8
+ export type Guarantee = 'atomic' | 'single-process' | 'none';
9
+ export interface Capabilities {
10
+ /** `put(key, body, { ifNoneMatch: '*' })` */
11
+ readonly createIfAbsent: Guarantee;
12
+ /** `put(key, body, { ifMatch })` */
13
+ readonly compareAndSwap: Guarantee;
14
+ }
15
+ export type WriteCondition = {
16
+ ifNoneMatch: '*';
17
+ } | {
18
+ ifMatch: string;
19
+ };
20
+ export interface ObjectEntry {
21
+ key: string;
22
+ /** Unquoted; equals the etag `get` / `put` report for the same version. */
23
+ etag: string;
24
+ }
25
+ export interface ListPage {
26
+ /** In lexicographic key order. */
27
+ entries: ObjectEntry[];
28
+ /** Present when another page follows. */
29
+ cursor?: string;
30
+ }
31
+ export interface ListOptions {
32
+ cursor?: string;
33
+ /** Page size; default and maximum 1000. */
34
+ limit?: number;
35
+ }
36
+ /**
37
+ * A flat key/value object store. Keys use `/` as separator.
38
+ *
39
+ * Errors are StorageError with `kind`:
40
+ * - `get` of a missing key: `not-found`
41
+ * - `put` whose condition fails: `conflict`; `ifMatch` on a missing key: `not-found`
42
+ * - `put` with a condition whose capability is `none`: UnsupportedError, without a request
43
+ * - `delete` of a missing key: no error
44
+ */
45
+ export interface StorageAdapter {
46
+ readonly capabilities: Capabilities;
47
+ /**
48
+ * True when every read is a network round trip. Collection then keeps a
49
+ * snapshot so a query does not GET every document.
50
+ */
51
+ readonly remote?: boolean;
52
+ get(key: string): Promise<{
53
+ body: Uint8Array;
54
+ etag: string;
55
+ }>;
56
+ put(key: string, body: Uint8Array, condition?: WriteCondition): Promise<{
57
+ etag: string;
58
+ }>;
59
+ delete(key: string): Promise<void>;
60
+ list(prefix: string, options?: ListOptions): Promise<ListPage>;
61
+ }
62
+ export declare const MAX_LIST_LIMIT = 1000;
63
+ export type GetManyResult = {
64
+ key: string;
65
+ body: Uint8Array;
66
+ etag: string;
67
+ } | {
68
+ key: string;
69
+ error: StorageError;
70
+ };
71
+ /**
72
+ * Reads `keys` with at most `concurrency` requests in flight. Results follow
73
+ * the input order; a failed read is reported in place instead of rejecting.
74
+ */
75
+ export declare function getMany(adapter: StorageAdapter, keys: string[], concurrency?: number): Promise<GetManyResult[]>;
@@ -0,0 +1,27 @@
1
+ import { StorageError } from '../errors.js';
2
+ export const MAX_LIST_LIMIT = 1000;
3
+ /**
4
+ * Reads `keys` with at most `concurrency` requests in flight. Results follow
5
+ * the input order; a failed read is reported in place instead of rejecting.
6
+ */
7
+ export async function getMany(adapter, keys, concurrency = 16) {
8
+ const results = new Array(keys.length);
9
+ let next = 0;
10
+ const worker = async () => {
11
+ while (next < keys.length) {
12
+ const index = next++;
13
+ const key = keys[index];
14
+ try {
15
+ results[index] = { key, ...(await adapter.get(key)) };
16
+ }
17
+ catch (error) {
18
+ results[index] = {
19
+ key,
20
+ error: error instanceof StorageError ? error : new StorageError(`Failed to read ${key}`, { key, cause: error }),
21
+ };
22
+ }
23
+ }
24
+ };
25
+ await Promise.all(Array.from({ length: Math.min(concurrency, keys.length) }, worker));
26
+ return results;
27
+ }
@@ -0,0 +1,28 @@
1
+ import type { StorageAdapter, Capabilities, WriteCondition, ListOptions, ListPage } from './adapter.js';
2
+ export interface FileSystemAdapterConfig {
3
+ /** Directory that holds all objects; created on first write. */
4
+ basePath: string;
5
+ }
6
+ /**
7
+ * Stores each object as a file under `basePath`. Create-if-absent uses
8
+ * `link()`, which is atomic across processes; compare-and-swap is serialized
9
+ * only within this process.
10
+ */
11
+ export declare class FileSystemAdapter implements StorageAdapter {
12
+ readonly capabilities: Capabilities;
13
+ private readonly basePath;
14
+ private readonly locks;
15
+ constructor(config: FileSystemAdapterConfig);
16
+ private pathOf;
17
+ /** Runs `fn` after every earlier writer of `path` in this process has finished. */
18
+ private withLock;
19
+ get(key: string): Promise<{
20
+ body: Uint8Array;
21
+ etag: string;
22
+ }>;
23
+ put(key: string, body: Uint8Array, condition?: WriteCondition): Promise<{
24
+ etag: string;
25
+ }>;
26
+ delete(key: string): Promise<void>;
27
+ list(prefix: string, options?: ListOptions): Promise<ListPage>;
28
+ }