@baukit/data-contracts 0.7.2 → 0.7.3
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/dist/erasure.d.ts +1 -1
- package/dist/erasure.d.ts.map +1 -1
- package/package.json +2 -1
- package/src/contracts.ts +160 -0
- package/src/durable-draft.test.ts +1214 -0
- package/src/durable-draft.ts +502 -0
- package/src/erasure.test.ts +229 -0
- package/src/erasure.ts +162 -0
- package/src/export.test.ts +167 -0
- package/src/export.ts +164 -0
- package/src/identity.test.ts +465 -0
- package/src/identity.ts +637 -0
- package/src/import-envelope.test.ts +290 -0
- package/src/import-envelope.ts +264 -0
- package/src/import-envelope.vitest.ts +115 -0
- package/src/index.ts +7 -0
- package/src/limits-policy.test.ts +145 -0
- package/src/limits.test.ts +170 -0
- package/src/limits.ts +329 -0
- package/src/memory.test.ts +49 -0
- package/src/memory.ts +375 -0
- package/src/revisioned-drafts.fixture.test.ts +247 -0
- package/src/revisioned-writes.test.ts +684 -0
- package/src/revisioned-writes.ts +374 -0
- package/src/vitest.ts +614 -0
- package/src/web-storage.test.ts +95 -0
- package/src/web-storage.ts +88 -0
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
/// <reference lib="dom" />
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The document a queue writes to. `acknowledgedRevision` is the last revision the server
|
|
5
|
+
* confirmed for this document, never a revision derived from a local value that was not sent.
|
|
6
|
+
*/
|
|
7
|
+
export interface RevisionedWriteScope<TScope, TDocument, TRevision> {
|
|
8
|
+
readonly scope: TScope;
|
|
9
|
+
readonly document: TDocument;
|
|
10
|
+
readonly acknowledgedRevision: TRevision;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* The product-mapped outcome of one write. Return `rejected` only when the server certainly did
|
|
15
|
+
* not apply the write. Throw, or let the promise reject, when the outcome is unknown.
|
|
16
|
+
*/
|
|
17
|
+
export type RevisionedWriteResult<TRevision, TConflict> =
|
|
18
|
+
| { readonly kind: 'accepted'; readonly revision: TRevision }
|
|
19
|
+
| {
|
|
20
|
+
readonly kind: 'conflict';
|
|
21
|
+
readonly currentRevision: TRevision;
|
|
22
|
+
readonly conflict: TConflict;
|
|
23
|
+
}
|
|
24
|
+
| { readonly kind: 'rejected'; readonly error: unknown };
|
|
25
|
+
|
|
26
|
+
export interface RevisionedWriteRequest<TScope, TDocument, TValue, TRevision> {
|
|
27
|
+
readonly scope: TScope;
|
|
28
|
+
readonly document: TDocument;
|
|
29
|
+
readonly value: TValue;
|
|
30
|
+
readonly expectedRevision: TRevision;
|
|
31
|
+
/**
|
|
32
|
+
* True when this request repeats a write whose earlier outcome was unknown. The value and
|
|
33
|
+
* expected revision are identical to that attempt, so a product can reuse its idempotency key
|
|
34
|
+
* or read the server state first.
|
|
35
|
+
*/
|
|
36
|
+
readonly afterUnknownOutcome: boolean;
|
|
37
|
+
/** Aborts when the queue is cancelled or reset. */
|
|
38
|
+
readonly signal: AbortSignal;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export interface RevisionedWriteQueueOptions<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
42
|
+
readonly initial: RevisionedWriteScope<TScope, TDocument, TRevision>;
|
|
43
|
+
readonly write: (
|
|
44
|
+
request: RevisionedWriteRequest<TScope, TDocument, TValue, TRevision>,
|
|
45
|
+
) => Promise<RevisionedWriteResult<TRevision, TConflict>>;
|
|
46
|
+
/** Merges an older unsent value with a newer one. Defaults to keeping the newer value. */
|
|
47
|
+
readonly coalesce?: (older: TValue, newer: TValue) => TValue;
|
|
48
|
+
/** Cancels the queue permanently when it aborts, for example when its owner unmounts. */
|
|
49
|
+
readonly signal?: AbortSignal;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export type RevisionedWriteStatus =
|
|
53
|
+
'idle' | 'dirty' | 'writing' | 'failed' | 'unknown-outcome' | 'conflict' | 'cancelled';
|
|
54
|
+
|
|
55
|
+
export interface RevisionedWriteConflict<TRevision, TConflict> {
|
|
56
|
+
readonly currentRevision: TRevision;
|
|
57
|
+
readonly conflict: TConflict;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export interface UncertainRevisionedWrite<TValue, TRevision> {
|
|
61
|
+
readonly value: TValue;
|
|
62
|
+
readonly expectedRevision: TRevision;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
66
|
+
readonly status: RevisionedWriteStatus;
|
|
67
|
+
readonly scope: TScope;
|
|
68
|
+
readonly document: TDocument;
|
|
69
|
+
readonly acknowledgedRevision: TRevision;
|
|
70
|
+
/** Local value the server has not seen, including a value it definitely did not apply. */
|
|
71
|
+
readonly unsent: { readonly value: TValue } | null;
|
|
72
|
+
/** A write the server may or may not have applied. */
|
|
73
|
+
readonly uncertain: UncertainRevisionedWrite<TValue, TRevision> | null;
|
|
74
|
+
readonly conflict: RevisionedWriteConflict<TRevision, TConflict> | null;
|
|
75
|
+
/** The cause of the last failed or unknown write, or `null`. */
|
|
76
|
+
readonly error: unknown;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export interface RevisionedWriteQueue<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
80
|
+
getSnapshot(): RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>;
|
|
81
|
+
subscribe(listener: () => void): () => void;
|
|
82
|
+
/** Records a local value. It is sent by the next `flush`, never by `enqueue` itself. */
|
|
83
|
+
enqueue(value: TValue): void;
|
|
84
|
+
/**
|
|
85
|
+
* Sends unsent values one at a time until none is left or the queue pauses. Concurrent callers
|
|
86
|
+
* share one drain. Resolves with the snapshot and never rejects.
|
|
87
|
+
*/
|
|
88
|
+
flush(): Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>>;
|
|
89
|
+
/**
|
|
90
|
+
* Resumes after `failed`, or replays the uncertain write after `unknown-outcome` with
|
|
91
|
+
* `afterUnknownOutcome: true`. Does nothing during a conflict or after cancellation.
|
|
92
|
+
*/
|
|
93
|
+
retry(): Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>>;
|
|
94
|
+
/**
|
|
95
|
+
* Switches to another scope, document, or acknowledged revision. Aborts the active write,
|
|
96
|
+
* drops unsent and uncertain values, and ignores every late completion.
|
|
97
|
+
*/
|
|
98
|
+
reset(next: RevisionedWriteScope<TScope, TDocument, TRevision>): void;
|
|
99
|
+
/** Aborts the active write, drops unsent values, and ignores late completions until `reset`. */
|
|
100
|
+
cancel(): void;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
type Pause = 'failed' | 'unknown-outcome' | 'conflict' | 'cancelled';
|
|
104
|
+
|
|
105
|
+
interface Attempt<TValue, TRevision> {
|
|
106
|
+
readonly value: TValue;
|
|
107
|
+
readonly expectedRevision: TRevision;
|
|
108
|
+
readonly afterUnknownOutcome: boolean;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
function keepNewer<TValue>(_older: TValue, newer: TValue): TValue {
|
|
112
|
+
return newer;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
class DefaultRevisionedWriteQueue<
|
|
116
|
+
TScope,
|
|
117
|
+
TDocument,
|
|
118
|
+
TValue,
|
|
119
|
+
TRevision,
|
|
120
|
+
TConflict,
|
|
121
|
+
> implements RevisionedWriteQueue<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
122
|
+
readonly #write: RevisionedWriteQueueOptions<
|
|
123
|
+
TScope,
|
|
124
|
+
TDocument,
|
|
125
|
+
TValue,
|
|
126
|
+
TRevision,
|
|
127
|
+
TConflict
|
|
128
|
+
>['write'];
|
|
129
|
+
readonly #coalesce: (older: TValue, newer: TValue) => TValue;
|
|
130
|
+
readonly #hostSignal: AbortSignal | undefined;
|
|
131
|
+
readonly #listeners = new Set<() => void>();
|
|
132
|
+
#generation = 0;
|
|
133
|
+
#abort = new AbortController();
|
|
134
|
+
#scope: RevisionedWriteScope<TScope, TDocument, TRevision>;
|
|
135
|
+
#acknowledgedRevision: TRevision;
|
|
136
|
+
#unsent: { readonly value: TValue } | null = null;
|
|
137
|
+
#uncertain: UncertainRevisionedWrite<TValue, TRevision> | null = null;
|
|
138
|
+
#conflict: RevisionedWriteConflict<TRevision, TConflict> | null = null;
|
|
139
|
+
#error: unknown = null;
|
|
140
|
+
#writing = false;
|
|
141
|
+
#pause: Pause | null = null;
|
|
142
|
+
#drain: Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>> | null =
|
|
143
|
+
null;
|
|
144
|
+
#snapshot: RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>;
|
|
145
|
+
|
|
146
|
+
constructor(
|
|
147
|
+
options: RevisionedWriteQueueOptions<TScope, TDocument, TValue, TRevision, TConflict>,
|
|
148
|
+
) {
|
|
149
|
+
this.#write = options.write;
|
|
150
|
+
this.#coalesce = options.coalesce ?? keepNewer;
|
|
151
|
+
this.#hostSignal = options.signal;
|
|
152
|
+
this.#scope = options.initial;
|
|
153
|
+
this.#acknowledgedRevision = options.initial.acknowledgedRevision;
|
|
154
|
+
if (this.#hostSignal?.aborted === true) {
|
|
155
|
+
this.#pause = 'cancelled';
|
|
156
|
+
}
|
|
157
|
+
this.#hostSignal?.addEventListener('abort', () => {
|
|
158
|
+
this.cancel();
|
|
159
|
+
});
|
|
160
|
+
this.#snapshot = this.#buildSnapshot();
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
getSnapshot(): RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
164
|
+
return this.#snapshot;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
subscribe(listener: () => void): () => void {
|
|
168
|
+
this.#listeners.add(listener);
|
|
169
|
+
return () => {
|
|
170
|
+
this.#listeners.delete(listener);
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
enqueue(value: TValue): void {
|
|
175
|
+
if (this.#pause === 'cancelled') {
|
|
176
|
+
return;
|
|
177
|
+
}
|
|
178
|
+
this.#unsent = this.#merge(this.#unsent, value);
|
|
179
|
+
this.#publish();
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
flush(): Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>> {
|
|
183
|
+
if (this.#drain !== null) {
|
|
184
|
+
return this.#drain;
|
|
185
|
+
}
|
|
186
|
+
const resumable = this.#pause === null || this.#pause === 'failed';
|
|
187
|
+
if (!resumable || this.#unsent === null) {
|
|
188
|
+
return Promise.resolve(this.#snapshot);
|
|
189
|
+
}
|
|
190
|
+
this.#pause = null;
|
|
191
|
+
return this.#startDrain(null);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
retry(): Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>> {
|
|
195
|
+
if (this.#drain !== null || this.#pause !== 'unknown-outcome' || this.#uncertain === null) {
|
|
196
|
+
return this.flush();
|
|
197
|
+
}
|
|
198
|
+
const uncertain = this.#uncertain;
|
|
199
|
+
this.#uncertain = null;
|
|
200
|
+
this.#pause = null;
|
|
201
|
+
return this.#startDrain({ ...uncertain, afterUnknownOutcome: true });
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
reset(next: RevisionedWriteScope<TScope, TDocument, TRevision>): void {
|
|
205
|
+
this.#fence();
|
|
206
|
+
this.#scope = next;
|
|
207
|
+
this.#acknowledgedRevision = next.acknowledgedRevision;
|
|
208
|
+
this.#pause = this.#hostSignal?.aborted === true ? 'cancelled' : null;
|
|
209
|
+
this.#publish();
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
cancel(): void {
|
|
213
|
+
if (this.#pause === 'cancelled') {
|
|
214
|
+
return;
|
|
215
|
+
}
|
|
216
|
+
this.#fence();
|
|
217
|
+
this.#pause = 'cancelled';
|
|
218
|
+
this.#publish();
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
#fence(): void {
|
|
222
|
+
this.#generation += 1;
|
|
223
|
+
this.#abort.abort();
|
|
224
|
+
this.#abort = new AbortController();
|
|
225
|
+
this.#drain = null;
|
|
226
|
+
this.#writing = false;
|
|
227
|
+
this.#unsent = null;
|
|
228
|
+
this.#uncertain = null;
|
|
229
|
+
this.#conflict = null;
|
|
230
|
+
this.#error = null;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
#startDrain(
|
|
234
|
+
first: Attempt<TValue, TRevision> | null,
|
|
235
|
+
): Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>> {
|
|
236
|
+
const drain = this.#runDrain(this.#generation, first);
|
|
237
|
+
this.#drain = drain;
|
|
238
|
+
return drain;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
async #runDrain(
|
|
242
|
+
generation: number,
|
|
243
|
+
first: Attempt<TValue, TRevision> | null,
|
|
244
|
+
): Promise<RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict>> {
|
|
245
|
+
try {
|
|
246
|
+
let attempt = first ?? this.#takeUnsent();
|
|
247
|
+
while (attempt !== null && (await this.#send(attempt, generation))) {
|
|
248
|
+
attempt = this.#takeUnsent();
|
|
249
|
+
}
|
|
250
|
+
} finally {
|
|
251
|
+
if (generation === this.#generation) {
|
|
252
|
+
this.#drain = null;
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
return this.#snapshot;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
#takeUnsent(): Attempt<TValue, TRevision> | null {
|
|
259
|
+
if (this.#pause !== null || this.#unsent === null) {
|
|
260
|
+
return null;
|
|
261
|
+
}
|
|
262
|
+
const { value } = this.#unsent;
|
|
263
|
+
this.#unsent = null;
|
|
264
|
+
return { value, expectedRevision: this.#acknowledgedRevision, afterUnknownOutcome: false };
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
async #send(attempt: Attempt<TValue, TRevision>, generation: number): Promise<boolean> {
|
|
268
|
+
this.#writing = true;
|
|
269
|
+
this.#error = null;
|
|
270
|
+
this.#publish();
|
|
271
|
+
let result: RevisionedWriteResult<TRevision, TConflict>;
|
|
272
|
+
try {
|
|
273
|
+
result = await this.#write({
|
|
274
|
+
scope: this.#scope.scope,
|
|
275
|
+
document: this.#scope.document,
|
|
276
|
+
value: attempt.value,
|
|
277
|
+
expectedRevision: attempt.expectedRevision,
|
|
278
|
+
afterUnknownOutcome: attempt.afterUnknownOutcome,
|
|
279
|
+
signal: this.#abort.signal,
|
|
280
|
+
});
|
|
281
|
+
} catch (error) {
|
|
282
|
+
if (generation === this.#generation) {
|
|
283
|
+
this.#pauseUncertain(attempt, error);
|
|
284
|
+
}
|
|
285
|
+
return false;
|
|
286
|
+
}
|
|
287
|
+
if (generation !== this.#generation) {
|
|
288
|
+
return false;
|
|
289
|
+
}
|
|
290
|
+
return this.#apply(attempt, result);
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
#apply(
|
|
294
|
+
attempt: Attempt<TValue, TRevision>,
|
|
295
|
+
result: RevisionedWriteResult<TRevision, TConflict>,
|
|
296
|
+
): boolean {
|
|
297
|
+
this.#writing = false;
|
|
298
|
+
switch (result.kind) {
|
|
299
|
+
case 'accepted':
|
|
300
|
+
this.#acknowledgedRevision = result.revision;
|
|
301
|
+
this.#publish();
|
|
302
|
+
return true;
|
|
303
|
+
case 'rejected':
|
|
304
|
+
this.#restoreUnapplied(attempt.value);
|
|
305
|
+
this.#pause = 'failed';
|
|
306
|
+
this.#error = result.error;
|
|
307
|
+
this.#publish();
|
|
308
|
+
return false;
|
|
309
|
+
case 'conflict':
|
|
310
|
+
this.#restoreUnapplied(attempt.value);
|
|
311
|
+
this.#pause = 'conflict';
|
|
312
|
+
this.#conflict = { currentRevision: result.currentRevision, conflict: result.conflict };
|
|
313
|
+
this.#publish();
|
|
314
|
+
return false;
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
#pauseUncertain(attempt: Attempt<TValue, TRevision>, error: unknown): void {
|
|
319
|
+
this.#writing = false;
|
|
320
|
+
this.#uncertain = { value: attempt.value, expectedRevision: attempt.expectedRevision };
|
|
321
|
+
this.#pause = 'unknown-outcome';
|
|
322
|
+
this.#error = error;
|
|
323
|
+
this.#publish();
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
#restoreUnapplied(value: TValue): void {
|
|
327
|
+
this.#unsent =
|
|
328
|
+
this.#unsent === null ? { value } : { value: this.#coalesce(value, this.#unsent.value) };
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
#merge(current: { readonly value: TValue } | null, value: TValue): { readonly value: TValue } {
|
|
332
|
+
return current === null ? { value } : { value: this.#coalesce(current.value, value) };
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
#status(): RevisionedWriteStatus {
|
|
336
|
+
if (this.#pause === 'cancelled') {
|
|
337
|
+
return 'cancelled';
|
|
338
|
+
}
|
|
339
|
+
if (this.#writing) {
|
|
340
|
+
return 'writing';
|
|
341
|
+
}
|
|
342
|
+
if (this.#pause !== null) {
|
|
343
|
+
return this.#pause;
|
|
344
|
+
}
|
|
345
|
+
return this.#unsent === null ? 'idle' : 'dirty';
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
#buildSnapshot(): RevisionedWriteSnapshot<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
349
|
+
return {
|
|
350
|
+
status: this.#status(),
|
|
351
|
+
scope: this.#scope.scope,
|
|
352
|
+
document: this.#scope.document,
|
|
353
|
+
acknowledgedRevision: this.#acknowledgedRevision,
|
|
354
|
+
unsent: this.#unsent,
|
|
355
|
+
uncertain: this.#uncertain,
|
|
356
|
+
conflict: this.#conflict,
|
|
357
|
+
error: this.#error,
|
|
358
|
+
};
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
#publish(): void {
|
|
362
|
+
this.#snapshot = this.#buildSnapshot();
|
|
363
|
+
for (const listener of this.#listeners) {
|
|
364
|
+
listener();
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/** Creates a framework-free queue that serializes revision-checked writes to one document. */
|
|
370
|
+
export function createRevisionedWriteQueue<TScope, TDocument, TValue, TRevision, TConflict>(
|
|
371
|
+
options: RevisionedWriteQueueOptions<TScope, TDocument, TValue, TRevision, TConflict>,
|
|
372
|
+
): RevisionedWriteQueue<TScope, TDocument, TValue, TRevision, TConflict> {
|
|
373
|
+
return new DefaultRevisionedWriteQueue(options);
|
|
374
|
+
}
|