@baukit/data-contracts 0.7.1 → 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.
@@ -0,0 +1,290 @@
1
+ import { expect, it, vi } from 'vitest';
2
+
3
+ import fixtureCorpus from '../../../../fixtures/import-envelope/import-envelope-v1.json' with { type: 'json' };
4
+
5
+ import {
6
+ ImportEnvelopeError,
7
+ type ImportEnvelopeLimits,
8
+ type ImportEnvelopePreview,
9
+ type ImportEnvelopeSource,
10
+ type ImportEnvelopeTransactionAdapter,
11
+ commitImportEnvelope,
12
+ prepareImportEnvelope,
13
+ } from './import-envelope.js';
14
+ import {
15
+ type ImportEnvelopeConformanceFixtures,
16
+ type ImportEnvelopeConformanceHarness,
17
+ type ImportEnvelopeConformanceHarnessOptions,
18
+ describeImportEnvelopeContract,
19
+ } from './import-envelope.vitest.js';
20
+
21
+ interface FixtureCase {
22
+ readonly name: string;
23
+ readonly outcome: 'accept' | 'reject' | 'commit-failure';
24
+ readonly source: unknown;
25
+ }
26
+
27
+ interface FixtureCorpus {
28
+ readonly fixture_version: number;
29
+ readonly limits: {
30
+ readonly max_source_bytes: number;
31
+ readonly max_rows: number;
32
+ readonly max_string_bytes: number;
33
+ };
34
+ readonly cases: readonly FixtureCase[];
35
+ }
36
+
37
+ interface FixtureRow {
38
+ readonly id: string;
39
+ readonly title: string;
40
+ }
41
+
42
+ interface FixturePlan {
43
+ readonly rows: readonly FixtureRow[];
44
+ }
45
+
46
+ interface FixtureTransaction {
47
+ readonly rows: Map<string, FixtureRow>;
48
+ }
49
+
50
+ const corpus = fixtureCorpus as FixtureCorpus;
51
+ const limits: ImportEnvelopeLimits = {
52
+ maxSourceBytes: corpus.limits.max_source_bytes,
53
+ maxRows: corpus.limits.max_rows,
54
+ maxStringBytes: corpus.limits.max_string_bytes,
55
+ };
56
+
57
+ function fixture(name: string): string {
58
+ const entry = corpus.cases.find((candidate) => candidate.name === name);
59
+ if (entry === undefined) throw new Error(`Missing import-envelope fixture: ${name}`);
60
+ return JSON.stringify(entry.source);
61
+ }
62
+
63
+ const conformanceFixtures: ImportEnvelopeConformanceFixtures = {
64
+ valid: fixture('valid'),
65
+ unknownFields: fixture('unknown-fields'),
66
+ duplicateIds: fixture('duplicate-ids'),
67
+ tombstones: fixture('tombstones'),
68
+ ownershipAndRevisionFields: fixture('ownership-and-revision-fields'),
69
+ oversizedStrings: fixture('oversized-strings'),
70
+ excessRows: fixture('excess-rows'),
71
+ mixedVersions: fixture('mixed-versions'),
72
+ failureHalfwayThroughCommit: fixture('failure-halfway-through-commit'),
73
+ };
74
+
75
+ function isRecord(value: unknown): value is Record<string, unknown> {
76
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
77
+ }
78
+
79
+ function decodeFixtureEnvelope(source: ImportEnvelopeSource) {
80
+ if (typeof source !== 'string') throw new Error('fixture_source_invalid');
81
+ const value: unknown = JSON.parse(source);
82
+ if (!isRecord(value) || value['format'] !== 'baukit-test-import') {
83
+ throw new Error('fixture_envelope_invalid');
84
+ }
85
+ const versions = value['schema_versions'];
86
+ if (!Array.isArray(versions) || versions.length !== 1 || versions[0] !== 1) {
87
+ throw new Error('fixture_schema_unsupported');
88
+ }
89
+ const rawRows = value['rows'];
90
+ if (!Array.isArray(rawRows)) throw new Error('fixture_rows_invalid');
91
+
92
+ const ids = new Set<string>();
93
+ const rows = rawRows.map((raw) => {
94
+ if (!isRecord(raw) || raw['collection'] !== 'records' || typeof raw['id'] !== 'string') {
95
+ throw new Error('fixture_row_invalid');
96
+ }
97
+ const key = `${raw['collection']}:${raw['id']}`;
98
+ if (ids.has(key)) throw new Error('fixture_duplicate_id');
99
+ ids.add(key);
100
+ if (raw['deleted_at'] !== undefined && raw['deleted_at'] !== null) {
101
+ throw new Error('fixture_tombstone_unsupported');
102
+ }
103
+ const fields = Object.fromEntries(
104
+ Object.entries(raw).filter(([field]) => field !== 'collection'),
105
+ );
106
+ return { collection: 'records' as const, fields };
107
+ });
108
+ return { context: { schemaVersion: 1 }, rows };
109
+ }
110
+
111
+ function prepareFixtureImport(
112
+ source: ImportEnvelopeSource,
113
+ ): Promise<ImportEnvelopePreview<FixturePlan>> {
114
+ return prepareImportEnvelope({
115
+ source,
116
+ limits,
117
+ decodeEnvelope: decodeFixtureEnvelope,
118
+ fieldAllowlist: { records: ['id', 'title'] },
119
+ decodeRow: ({ fields }) => {
120
+ const id = fields['id'];
121
+ const title = fields['title'];
122
+ if (typeof id !== 'string' || typeof title !== 'string') {
123
+ throw new Error('fixture_row_invalid');
124
+ }
125
+ return { id, title };
126
+ },
127
+ plan: ({ rows }) => ({ rows }),
128
+ });
129
+ }
130
+
131
+ function makeHarness(
132
+ options: ImportEnvelopeConformanceHarnessOptions,
133
+ ): ImportEnvelopeConformanceHarness<ImportEnvelopePreview<FixturePlan>, string, string> {
134
+ let committedRows = new Map<string, FixtureRow>();
135
+ const writeFields: string[][] = [];
136
+ let cursor = 'cursor-before';
137
+ let syncState = 'idle';
138
+ let transactionCommitted = false;
139
+ let stateAdvancedBeforeCommit = false;
140
+
141
+ const transaction: ImportEnvelopeTransactionAdapter<FixtureTransaction> = {
142
+ async withTransaction(operation) {
143
+ const workingRows = new Map(committedRows);
144
+ transactionCommitted = false;
145
+ const result = await operation({ rows: workingRows });
146
+ committedRows = workingRows;
147
+ transactionCommitted = true;
148
+ return result;
149
+ },
150
+ };
151
+
152
+ return {
153
+ preview: prepareFixtureImport,
154
+ async commit(preview) {
155
+ let writes = 0;
156
+ await commitImportEnvelope({
157
+ preview,
158
+ transaction,
159
+ write: (activeTransaction, plan) => {
160
+ for (const row of plan.rows) {
161
+ writeFields.push(Object.keys(row).sort());
162
+ activeTransaction.rows.set(row.id, row);
163
+ writes += 1;
164
+ if (writes === options.failAfterWrites) throw new Error('fixture_commit_failure');
165
+ }
166
+ return Promise.resolve();
167
+ },
168
+ afterCommit: () => {
169
+ if (!transactionCommitted) stateAdvancedBeforeCommit = true;
170
+ cursor = 'cursor-after';
171
+ syncState = 'sync-requested';
172
+ },
173
+ });
174
+ },
175
+ observe: () => ({
176
+ committedIds: [...committedRows.keys()].sort(),
177
+ writeFields,
178
+ cursor,
179
+ syncState,
180
+ stateAdvancedBeforeCommit,
181
+ }),
182
+ };
183
+ }
184
+
185
+ describeImportEnvelopeContract({
186
+ fixtures: conformanceFixtures,
187
+ makeHarness,
188
+ expectedCommittedIds: ['row-a', 'row-b'],
189
+ forbiddenWriteFields: ['owner_id', 'revision'],
190
+ initialCursor: 'cursor-before',
191
+ committedCursor: 'cursor-after',
192
+ initialSyncState: 'idle',
193
+ committedSyncState: 'sync-requested',
194
+ });
195
+
196
+ it.each([
197
+ ['unknown-fields', { code: 'field_not_allowed', field: 'debug' }],
198
+ ['ownership-and-revision-fields', { code: 'field_not_allowed', field: 'owner_id' }],
199
+ ['oversized-strings', { code: 'string_too_large', field: 'title', measured: 17, allowed: 16 }],
200
+ ['excess-rows', { code: 'too_many_rows', measured: 3, allowed: 2 }],
201
+ ] as const)('returns bounded details for %s', async (name, expected) => {
202
+ await expect(prepareFixtureImport(fixture(name))).rejects.toMatchObject(expected);
203
+ });
204
+
205
+ it('checks the source byte limit before calling the envelope decoder', async () => {
206
+ const decodeEnvelope = vi.fn(decodeFixtureEnvelope);
207
+ await expect(
208
+ prepareImportEnvelope({
209
+ source: fixture('valid'),
210
+ limits: { ...limits, maxSourceBytes: 1 },
211
+ decodeEnvelope,
212
+ fieldAllowlist: { records: ['id', 'title'] },
213
+ decodeRow: () => ({ id: 'unused', title: 'unused' }),
214
+ plan: ({ rows }) => ({ rows }),
215
+ }),
216
+ ).rejects.toMatchObject({ code: 'source_too_large', allowed: 1 });
217
+ expect(decodeEnvelope).not.toHaveBeenCalled();
218
+ });
219
+
220
+ it('rejects collections that have no field allowlist', async () => {
221
+ await expect(
222
+ prepareImportEnvelope({
223
+ source: 'x',
224
+ limits,
225
+ decodeEnvelope: () => ({
226
+ context: undefined,
227
+ rows: [{ collection: 'unlisted', fields: { id: 'row-a' } }],
228
+ }),
229
+ fieldAllowlist: {},
230
+ decodeRow: ({ fields }) => fields,
231
+ plan: ({ rows }) => rows,
232
+ }),
233
+ ).rejects.toEqual(
234
+ new ImportEnvelopeError('collection_not_allowed', {
235
+ collection: 'unlisted',
236
+ rowIndex: 0,
237
+ }),
238
+ );
239
+ });
240
+
241
+ it('checks strings nested inside an allowed field', async () => {
242
+ await expect(
243
+ prepareImportEnvelope({
244
+ source: 'x',
245
+ limits: { ...limits, maxStringBytes: 4 },
246
+ decodeEnvelope: () => ({
247
+ context: undefined,
248
+ rows: [{ collection: 'records', fields: { payload: { label: '12345' } } }],
249
+ }),
250
+ fieldAllowlist: { records: ['payload'] },
251
+ decodeRow: ({ fields }) => fields,
252
+ plan: ({ rows }) => rows,
253
+ }),
254
+ ).rejects.toMatchObject({
255
+ code: 'string_too_large',
256
+ collection: 'records',
257
+ rowIndex: 0,
258
+ field: 'payload',
259
+ measured: 5,
260
+ allowed: 4,
261
+ });
262
+ });
263
+
264
+ it('rejects invalid limits before decoding', async () => {
265
+ const decodeEnvelope = vi.fn(decodeFixtureEnvelope);
266
+ await expect(
267
+ prepareImportEnvelope({
268
+ source: 'x',
269
+ limits: { ...limits, maxRows: -1 },
270
+ decodeEnvelope,
271
+ fieldAllowlist: { records: ['id'] },
272
+ decodeRow: ({ fields }) => fields,
273
+ plan: ({ rows }) => rows,
274
+ }),
275
+ ).rejects.toThrow('maxRows must be a non-negative safe integer');
276
+ expect(decodeEnvelope).not.toHaveBeenCalled();
277
+ });
278
+
279
+ it('exports the helpers without removing the existing package entry points', async () => {
280
+ const [root, entry, vitestEntry] = await Promise.all([
281
+ import('@baukit/data-contracts'),
282
+ import('@baukit/data-contracts/import-envelope'),
283
+ import('@baukit/data-contracts/vitest'),
284
+ ]);
285
+ expect(root.InMemoryStore).toBeTypeOf('function');
286
+ expect(root.prepareImportEnvelope).toBe(entry.prepareImportEnvelope);
287
+ expect(entry.commitImportEnvelope).toBeTypeOf('function');
288
+ expect(vitestEntry.describeRecordStoreContract).toBeTypeOf('function');
289
+ expect(vitestEntry.describeImportEnvelopeContract).toBeTypeOf('function');
290
+ });
@@ -0,0 +1,264 @@
1
+ export type ImportEnvelopeSource = string | Uint8Array;
2
+
3
+ export interface ImportEnvelopeLimits {
4
+ readonly maxSourceBytes: number;
5
+ readonly maxRows: number;
6
+ readonly maxStringBytes: number;
7
+ }
8
+
9
+ export type ImportEnvelopeErrorCode =
10
+ | 'source_too_large'
11
+ | 'too_many_rows'
12
+ | 'collection_not_allowed'
13
+ | 'field_not_allowed'
14
+ | 'string_too_large'
15
+ | 'invalid_row_value';
16
+
17
+ export interface ImportEnvelopeErrorDetails {
18
+ readonly collection?: string;
19
+ readonly rowIndex?: number;
20
+ readonly field?: string;
21
+ readonly measured?: number;
22
+ readonly allowed?: number;
23
+ }
24
+
25
+ export class ImportEnvelopeError extends Error {
26
+ public override readonly name = 'ImportEnvelopeError';
27
+ public readonly code: ImportEnvelopeErrorCode;
28
+ public readonly collection: string | undefined;
29
+ public readonly rowIndex: number | undefined;
30
+ public readonly field: string | undefined;
31
+ public readonly measured: number | undefined;
32
+ public readonly allowed: number | undefined;
33
+
34
+ public constructor(code: ImportEnvelopeErrorCode, details: ImportEnvelopeErrorDetails = {}) {
35
+ super(`Import envelope rejected: ${code}`);
36
+ this.code = code;
37
+ this.collection = details.collection;
38
+ this.rowIndex = details.rowIndex;
39
+ this.field = details.field;
40
+ this.measured = details.measured;
41
+ this.allowed = details.allowed;
42
+ }
43
+ }
44
+
45
+ export interface DecodedImportEnvelopeRow<TCollection extends string> {
46
+ readonly collection: TCollection;
47
+ readonly fields: Readonly<Record<string, unknown>>;
48
+ }
49
+
50
+ export interface DecodedImportEnvelope<TContext, TCollection extends string> {
51
+ readonly context: TContext;
52
+ readonly rows: Iterable<DecodedImportEnvelopeRow<TCollection>>;
53
+ }
54
+
55
+ export interface ImportEnvelopeRowDecoderInput<TContext, TCollection extends string> {
56
+ readonly context: TContext;
57
+ readonly collection: TCollection;
58
+ readonly rowIndex: number;
59
+ readonly fields: Readonly<Record<string, unknown>>;
60
+ }
61
+
62
+ export interface ImportEnvelopePlannerInput<TContext, TRow> {
63
+ readonly context: TContext;
64
+ readonly rows: readonly TRow[];
65
+ }
66
+
67
+ export interface ImportEnvelopePreview<TPlan> {
68
+ readonly rowCount: number;
69
+ readonly plan: TPlan;
70
+ }
71
+
72
+ export interface PrepareImportEnvelopeOptions<TContext, TCollection extends string, TRow, TPlan> {
73
+ readonly source: ImportEnvelopeSource;
74
+ readonly limits: ImportEnvelopeLimits;
75
+ readonly decodeEnvelope: (
76
+ source: ImportEnvelopeSource,
77
+ ) =>
78
+ | DecodedImportEnvelope<TContext, TCollection>
79
+ | Promise<DecodedImportEnvelope<TContext, TCollection>>;
80
+ readonly fieldAllowlist: Readonly<Partial<Record<TCollection, readonly string[]>>>;
81
+ readonly decodeRow: (
82
+ input: ImportEnvelopeRowDecoderInput<TContext, TCollection>,
83
+ ) => TRow | Promise<TRow>;
84
+ readonly plan: (input: ImportEnvelopePlannerInput<TContext, TRow>) => TPlan | Promise<TPlan>;
85
+ }
86
+
87
+ export interface ImportEnvelopeTransactionAdapter<TTransaction> {
88
+ withTransaction<TResult>(
89
+ operation: (transaction: TTransaction) => Promise<TResult>,
90
+ ): Promise<TResult>;
91
+ }
92
+
93
+ export interface CommitImportEnvelopeOptions<TPlan, TTransaction, TResult> {
94
+ readonly preview: ImportEnvelopePreview<TPlan>;
95
+ readonly transaction: ImportEnvelopeTransactionAdapter<TTransaction>;
96
+ readonly write: (transaction: TTransaction, plan: TPlan) => Promise<TResult>;
97
+ readonly afterCommit?: (result: TResult) => Promise<void> | void;
98
+ }
99
+
100
+ export async function prepareImportEnvelope<TContext, TCollection extends string, TRow, TPlan>(
101
+ options: PrepareImportEnvelopeOptions<TContext, TCollection, TRow, TPlan>,
102
+ ): Promise<ImportEnvelopePreview<TPlan>> {
103
+ assertLimits(options.limits);
104
+ const sourceBytes = utf8ByteLength(options.source);
105
+ if (sourceBytes > options.limits.maxSourceBytes) {
106
+ throw new ImportEnvelopeError('source_too_large', {
107
+ measured: sourceBytes,
108
+ allowed: options.limits.maxSourceBytes,
109
+ });
110
+ }
111
+
112
+ const envelope = await options.decodeEnvelope(options.source);
113
+ const decodedRows: TRow[] = [];
114
+ for (const row of envelope.rows) {
115
+ const rowIndex = decodedRows.length;
116
+ if (rowIndex >= options.limits.maxRows) {
117
+ throw new ImportEnvelopeError('too_many_rows', {
118
+ measured: rowIndex + 1,
119
+ allowed: options.limits.maxRows,
120
+ });
121
+ }
122
+ const allowedFields = allowlistFor(options.fieldAllowlist, row.collection, rowIndex);
123
+ const fields = sanitizeFields(
124
+ row.fields,
125
+ allowedFields,
126
+ row.collection,
127
+ rowIndex,
128
+ options.limits.maxStringBytes,
129
+ );
130
+ decodedRows.push(
131
+ await options.decodeRow({
132
+ context: envelope.context,
133
+ collection: row.collection,
134
+ rowIndex,
135
+ fields,
136
+ }),
137
+ );
138
+ }
139
+
140
+ const rows = Object.freeze(decodedRows.slice());
141
+ const plan = await options.plan({ context: envelope.context, rows });
142
+ return Object.freeze({ rowCount: rows.length, plan });
143
+ }
144
+
145
+ export async function commitImportEnvelope<TPlan, TTransaction, TResult>(
146
+ options: CommitImportEnvelopeOptions<TPlan, TTransaction, TResult>,
147
+ ): Promise<TResult> {
148
+ const result = await options.transaction.withTransaction((transaction) =>
149
+ options.write(transaction, options.preview.plan),
150
+ );
151
+ await options.afterCommit?.(result);
152
+ return result;
153
+ }
154
+
155
+ function assertLimits(limits: ImportEnvelopeLimits): void {
156
+ assertLimit(limits.maxSourceBytes, 'maxSourceBytes');
157
+ assertLimit(limits.maxRows, 'maxRows');
158
+ assertLimit(limits.maxStringBytes, 'maxStringBytes');
159
+ }
160
+
161
+ function assertLimit(value: number, name: keyof ImportEnvelopeLimits): void {
162
+ if (!Number.isSafeInteger(value) || value < 0) {
163
+ throw new RangeError(`${name} must be a non-negative safe integer`);
164
+ }
165
+ }
166
+
167
+ function allowlistFor<TCollection extends string>(
168
+ allowlist: Readonly<Partial<Record<TCollection, readonly string[]>>>,
169
+ collection: TCollection,
170
+ rowIndex: number,
171
+ ): ReadonlySet<string> {
172
+ const fields = (allowlist as Readonly<Record<string, readonly string[] | undefined>>)[collection];
173
+ if (fields === undefined) {
174
+ throw new ImportEnvelopeError('collection_not_allowed', { collection, rowIndex });
175
+ }
176
+ return new Set(fields);
177
+ }
178
+
179
+ function sanitizeFields(
180
+ fields: Readonly<Record<string, unknown>>,
181
+ allowedFields: ReadonlySet<string>,
182
+ collection: string,
183
+ rowIndex: number,
184
+ maxStringBytes: number,
185
+ ): Readonly<Record<string, unknown>> {
186
+ if (Object.getOwnPropertySymbols(fields).length > 0) {
187
+ throw new ImportEnvelopeError('invalid_row_value', { collection, rowIndex });
188
+ }
189
+ const entries: [string, unknown][] = [];
190
+ for (const field of Object.keys(fields)) {
191
+ if (!allowedFields.has(field)) {
192
+ throw new ImportEnvelopeError('field_not_allowed', { collection, rowIndex, field });
193
+ }
194
+ const descriptor = Object.getOwnPropertyDescriptor(fields, field);
195
+ if (descriptor === undefined || !('value' in descriptor)) {
196
+ throw new ImportEnvelopeError('invalid_row_value', { collection, rowIndex, field });
197
+ }
198
+ assertBoundedStrings(
199
+ descriptor.value,
200
+ maxStringBytes,
201
+ { collection, rowIndex, field },
202
+ new WeakSet(),
203
+ );
204
+ entries.push([field, descriptor.value]);
205
+ }
206
+ return Object.freeze(Object.fromEntries(entries));
207
+ }
208
+
209
+ function assertBoundedStrings(
210
+ value: unknown,
211
+ allowed: number,
212
+ location: Required<Pick<ImportEnvelopeErrorDetails, 'collection' | 'rowIndex' | 'field'>>,
213
+ ancestors: WeakSet<object>,
214
+ ): void {
215
+ if (typeof value === 'string') {
216
+ const measured = utf8StringBytes(value);
217
+ if (measured > allowed) {
218
+ throw new ImportEnvelopeError('string_too_large', { ...location, measured, allowed });
219
+ }
220
+ return;
221
+ }
222
+ if (value === null || typeof value !== 'object') return;
223
+ if (ancestors.has(value)) {
224
+ throw new ImportEnvelopeError('invalid_row_value', location);
225
+ }
226
+
227
+ ancestors.add(value);
228
+ try {
229
+ for (const key of Reflect.ownKeys(value)) {
230
+ if (typeof key !== 'string') {
231
+ throw new ImportEnvelopeError('invalid_row_value', location);
232
+ }
233
+ const descriptor = Object.getOwnPropertyDescriptor(value, key);
234
+ if (descriptor === undefined || !('value' in descriptor)) {
235
+ throw new ImportEnvelopeError('invalid_row_value', location);
236
+ }
237
+ assertBoundedStrings(descriptor.value, allowed, location, ancestors);
238
+ }
239
+ } finally {
240
+ ancestors.delete(value);
241
+ }
242
+ }
243
+
244
+ function utf8ByteLength(source: ImportEnvelopeSource): number {
245
+ return typeof source === 'string' ? utf8StringBytes(source) : source.byteLength;
246
+ }
247
+
248
+ function utf8StringBytes(value: string): number {
249
+ let bytes = 0;
250
+ for (let index = 0; index < value.length; index += 1) {
251
+ const first = value.charCodeAt(index);
252
+ if (first <= 0x7f) bytes += 1;
253
+ else if (first <= 0x7ff) bytes += 2;
254
+ else if (first >= 0xd800 && first <= 0xdbff && isLowSurrogate(value.charCodeAt(index + 1))) {
255
+ bytes += 4;
256
+ index += 1;
257
+ } else bytes += 3;
258
+ }
259
+ return bytes;
260
+ }
261
+
262
+ function isLowSurrogate(value: number): boolean {
263
+ return value >= 0xdc00 && value <= 0xdfff;
264
+ }
@@ -0,0 +1,115 @@
1
+ import { describe, expect, it } from 'vitest';
2
+
3
+ import type { ImportEnvelopeSource } from './import-envelope.js';
4
+
5
+ export interface ImportEnvelopeConformanceFixtures {
6
+ readonly valid: ImportEnvelopeSource;
7
+ readonly unknownFields: ImportEnvelopeSource;
8
+ readonly duplicateIds: ImportEnvelopeSource;
9
+ readonly tombstones: ImportEnvelopeSource;
10
+ readonly ownershipAndRevisionFields: ImportEnvelopeSource;
11
+ readonly oversizedStrings: ImportEnvelopeSource;
12
+ readonly excessRows: ImportEnvelopeSource;
13
+ readonly mixedVersions: ImportEnvelopeSource;
14
+ readonly failureHalfwayThroughCommit: ImportEnvelopeSource;
15
+ }
16
+
17
+ export interface ImportEnvelopeConformanceHarnessOptions {
18
+ readonly failAfterWrites?: number;
19
+ }
20
+
21
+ export interface ImportEnvelopeConformanceObservation<TCursor, TSyncState> {
22
+ readonly committedIds: readonly string[];
23
+ readonly writeFields: readonly (readonly string[])[];
24
+ readonly cursor: TCursor;
25
+ readonly syncState: TSyncState;
26
+ readonly stateAdvancedBeforeCommit: boolean;
27
+ }
28
+
29
+ export interface ImportEnvelopeConformanceHarness<TPreview, TCursor, TSyncState> {
30
+ preview(source: ImportEnvelopeSource): Promise<TPreview>;
31
+ commit(preview: TPreview): Promise<void>;
32
+ observe():
33
+ | ImportEnvelopeConformanceObservation<TCursor, TSyncState>
34
+ | Promise<ImportEnvelopeConformanceObservation<TCursor, TSyncState>>;
35
+ }
36
+
37
+ export interface ImportEnvelopeConformanceOptions<TPreview, TCursor, TSyncState> {
38
+ readonly fixtures: ImportEnvelopeConformanceFixtures;
39
+ readonly makeHarness: (
40
+ options: ImportEnvelopeConformanceHarnessOptions,
41
+ ) =>
42
+ | ImportEnvelopeConformanceHarness<TPreview, TCursor, TSyncState>
43
+ | Promise<ImportEnvelopeConformanceHarness<TPreview, TCursor, TSyncState>>;
44
+ readonly expectedCommittedIds: readonly string[];
45
+ readonly forbiddenWriteFields: readonly string[];
46
+ readonly initialCursor: TCursor;
47
+ readonly committedCursor: TCursor;
48
+ readonly initialSyncState: TSyncState;
49
+ readonly committedSyncState: TSyncState;
50
+ }
51
+
52
+ /** Registers import validation, preview, atomicity, and post-commit state requirements. */
53
+ export function describeImportEnvelopeContract<TPreview, TCursor, TSyncState>(
54
+ options: ImportEnvelopeConformanceOptions<TPreview, TCursor, TSyncState>,
55
+ ): void {
56
+ describe('import-envelope contract', () => {
57
+ const rejectedFixtures = [
58
+ ['unknown fields', options.fixtures.unknownFields],
59
+ ['duplicate IDs', options.fixtures.duplicateIds],
60
+ ['tombstones', options.fixtures.tombstones],
61
+ ['ownership and revision fields', options.fixtures.ownershipAndRevisionFields],
62
+ ['oversized strings', options.fixtures.oversizedStrings],
63
+ ['excess rows', options.fixtures.excessRows],
64
+ ['mixed versions', options.fixtures.mixedVersions],
65
+ ] as const;
66
+
67
+ it.each(rejectedFixtures)('rejects %s before a product write', async (_name, source) => {
68
+ const harness = await options.makeHarness({});
69
+ await expect(harness.preview(source)).rejects.toThrow();
70
+ const observed = await harness.observe();
71
+ expect(observed.committedIds).toEqual([]);
72
+ expect(observed.writeFields).toEqual([]);
73
+ expect(observed.cursor).toEqual(options.initialCursor);
74
+ expect(observed.syncState).toEqual(options.initialSyncState);
75
+ });
76
+
77
+ it('previews without writing or advancing state', async () => {
78
+ const harness = await options.makeHarness({});
79
+ await expect(harness.preview(options.fixtures.valid)).resolves.toBeDefined();
80
+ const observed = await harness.observe();
81
+ expect(observed.committedIds).toEqual([]);
82
+ expect(observed.writeFields).toEqual([]);
83
+ expect(observed.cursor).toEqual(options.initialCursor);
84
+ expect(observed.syncState).toEqual(options.initialSyncState);
85
+ });
86
+
87
+ it('commits every row before advancing cursor and sync state', async () => {
88
+ const harness = await options.makeHarness({});
89
+ const preview = await harness.preview(options.fixtures.valid);
90
+ await expect(harness.commit(preview)).resolves.toBeUndefined();
91
+ const observed = await harness.observe();
92
+ expect(observed.committedIds).toEqual(options.expectedCommittedIds);
93
+ expect(observed.writeFields).toHaveLength(options.expectedCommittedIds.length);
94
+ expect(observed.cursor).toEqual(options.committedCursor);
95
+ expect(observed.syncState).toEqual(options.committedSyncState);
96
+ expect(observed.stateAdvancedBeforeCommit).toBe(false);
97
+ for (const fields of observed.writeFields) {
98
+ for (const forbidden of options.forbiddenWriteFields) {
99
+ expect(fields).not.toContain(forbidden);
100
+ }
101
+ }
102
+ });
103
+
104
+ it('rolls back every row and leaves state unchanged after a halfway failure', async () => {
105
+ const harness = await options.makeHarness({ failAfterWrites: 1 });
106
+ const preview = await harness.preview(options.fixtures.failureHalfwayThroughCommit);
107
+ await expect(harness.commit(preview)).rejects.toThrow();
108
+ const observed = await harness.observe();
109
+ expect(observed.committedIds).toEqual([]);
110
+ expect(observed.cursor).toEqual(options.initialCursor);
111
+ expect(observed.syncState).toEqual(options.initialSyncState);
112
+ expect(observed.stateAdvancedBeforeCommit).toBe(false);
113
+ });
114
+ });
115
+ }
package/src/index.ts ADDED
@@ -0,0 +1,7 @@
1
+ export * from './contracts.js';
2
+ export * from './erasure.js';
3
+ export * from './export.js';
4
+ export * from './identity.js';
5
+ export * from './import-envelope.js';
6
+ export * from './memory.js';
7
+ export * from './web-storage.js';