@chipmobilesdk/rn-local-db 0.1.0

package/src/testing/conformance/transactions.ts

@@ -0,0 +1,149 @@
+import { DiagnosticCodes } from '../../contract/errors';
+import { isCode } from '../../diagnostics/errors';
+import type { ConformanceContext } from './index';
+
+/** US4: all-or-nothing writes. */
+export function registerTransactionConformance(context: ConformanceContext): void {
+	describe('conformance: transactions', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'guest' } as const;
+
+		it('commits every write together', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.transaction(async tx => {
+				await tx.collection('notes').insert({ id: 'a', data: { title: 'a' } });
+				await tx.collection('plain').insert({ id: 'b', data: { label: 'b' } });
+			});
+
+			expect(await handle.collection('notes').find('a')).not.toBeNull();
+			expect(await handle.collection('plain').find('b')).not.toBeNull();
+			await handle.close();
+		});
+
+		it('rolls back every write when one fails', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.collection('notes').insert({ id: 'existing', data: { title: 'kept' } });
+
+			let thrown: unknown;
+			try {
+				await handle.transaction(async tx => {
+					await tx.collection('notes').insert({ id: 'new', data: { title: 'new' } });
+					// Conflicts with `existing`, so the whole transaction unwinds.
+					await tx.collection('notes').insert({ id: 'existing', data: { title: 'clash' } });
+				});
+			} catch (error) {
+				thrown = error;
+			}
+
+			expect(isCode(thrown, DiagnosticCodes.RECORD_CONFLICT)).toBe(true);
+			expect(await handle.collection('notes').find('new')).toBeNull();
+			expect((await handle.collection('notes').get('existing')).data.title).toBe('kept');
+			await handle.close();
+		});
+
+		it.each([0, 1, 2, 3])('rolls back cleanly when step %p fails', async failAt => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const before = await handle.collection('notes').count();
+
+			try {
+				await handle.transaction(async tx => {
+					for (let step = 0; step < 4; step += 1) {
+						if (step === failAt) {
+							throw new Error('injected');
+						}
+						await tx.collection('notes').insert({ id: `s${step}`, data: { score: step } });
+					}
+				});
+			} catch {
+				// Expected.
+			}
+
+			expect(await handle.collection('notes').count()).toBe(before);
+			await handle.close();
+		});
+
+		it('discards everything on an explicit abort', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.transaction(async tx => {
+				await tx.collection('notes').insert({ id: 'a', data: { title: 'a' } });
+				await tx.abort();
+			});
+			expect(await handle.collection('notes').find('a')).toBeNull();
+			await handle.close();
+		});
+
+		it('sees its own uncommitted writes inside the transaction', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.transaction(async tx => {
+				const notes = tx.collection('notes');
+				await notes.insert({ id: 'a', data: { title: 'inside' } });
+				expect((await notes.get('a')).data.title).toBe('inside');
+			});
+			await handle.close();
+		});
+
+		it('rejects use after the transaction settles', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			let thrown: unknown;
+			await handle.transaction(async tx => {
+				await tx.abort();
+				try {
+					tx.collection('notes');
+				} catch (error) {
+					thrown = error;
+				}
+			});
+			expect(isCode(thrown, DiagnosticCodes.TRANSACTION_STATE)).toBe(true);
+			await handle.close();
+		});
+
+		it('applies a batch as one unit', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const outcome = await handle.batch([
+				{ type: 'insert', collection: 'notes', record: { id: 'a', data: { score: 1 } } },
+				{ type: 'insert', collection: 'notes', record: { id: 'b', data: { score: 2 } } },
+				{ type: 'upsert', collection: 'plain', record: { id: 'c', data: { label: 'c' } } },
+			]);
+			expect(outcome.applied).toBe(3);
+			expect(await handle.collection('notes').count()).toBe(2);
+			await handle.close();
+		});
+
+		it('rolls back the whole batch when one operation fails', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.collection('notes').insert({ id: 'a', data: { score: 0 } });
+
+			try {
+				await handle.batch([
+					{ type: 'insert', collection: 'notes', record: { id: 'b', data: { score: 1 } } },
+					{ type: 'insert', collection: 'notes', record: { id: 'a', data: { score: 9 } } },
+				]);
+			} catch {
+				// Expected.
+			}
+
+			expect(await handle.collection('notes').find('b')).toBeNull();
+			expect((await handle.collection('notes').get('a')).data.score).toBe(0);
+			await handle.close();
+		});
+
+		it('rejects a batch over the operation budget', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const operations = Array.from({ length: 1001 }, (_, i) => ({
+				type: 'upsert' as const,
+				collection: 'notes',
+				record: { id: `x${i}`, data: { score: i } },
+			}));
+
+			let thrown: unknown;
+			try {
+				await handle.batch(operations);
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.BATCH_TOO_LARGE)).toBe(true);
+			await handle.close();
+		});
+	});
+}

package/src/testing/faults.ts

@@ -0,0 +1,21 @@
+/**
+ * Fault injection, exposed only through the `./testing` entrypoint.
+ *
+ * Produces the same typed errors the on-device implementation produces, so a
+ * consumer can test its recovery paths without a device that is actually out
+ * of space or actually corrupt (FR-095). The registry itself lives in
+ * `diagnostics/faults.ts`, because the *checks* have to run in production code
+ * for the demo app's panel to exercise the real adapter — only the ability to
+ * arm one is kept behind this entrypoint.
+ */
+
+export {
+	activeFaults,
+	clearFaults,
+	injectFault,
+	throwIfFaulted,
+	type FaultPoint,
+	type FaultSpec,
+} from '../diagnostics/faults';
+
+export { DiagnosticCodes } from '../contract/errors';

package/src/testing/index.ts

@@ -0,0 +1,21 @@
+/**
+ * `@chipmobilesdk/rn-local-db/testing`
+ *
+ * Test-only surface, kept behind its own entrypoint so the in-memory engine
+ * never reaches a consuming app's production bundle (research.md R10).
+ */
+
+export { createMemoryAdapter, type MemoryAdapterOptions } from './memory-adapter';
+export {
+	memoryConformanceHooks,
+	resetMemoryAdapter,
+	seedRecords,
+} from './memory-adapter/reset';
+export { clearFaults, injectFault, type FaultPoint, type FaultSpec } from './faults';
+export {
+	runConformanceSuite,
+	type ConformanceContext,
+	type ConformanceHooks,
+	type ConformanceOptions,
+	type ConformanceSection,
+} from './conformance';

package/src/testing/memory-adapter/collection.ts

@@ -0,0 +1,219 @@
+/**
+ * Collection operations over the in-memory store.
+ *
+ * Every semantic decision — filtering, sorting, paging — is delegated to
+ * `query/`, the module the SQLite adapter also validates through. Anything
+ * decided here instead would be a place the two adapters could drift.
+ */
+
+import { DiagnosticCodes } from '../../contract/errors';
+import type { FilterNode, Query, ResultPage } from '../../contract/query';
+import type {
+	RecordInput,
+	StorableRecordData,
+	StoredRecord,
+	WriteOutcome,
+} from '../../contract/record';
+import type { CollectionSchema } from '../../contract/schema';
+import type { CollectionOps } from '../../contract/transaction';
+import { raise } from '../../diagnostics/errors';
+import { throwIfFaulted } from '../../diagnostics/faults';
+import { assertRecordWithinBudget } from '../../query/budgets';
+import { evaluateFilter } from '../../query/filter';
+import { applyCursor, buildPage, resolvePageSize } from '../../query/paginate';
+import { sortRecords, withStableTiebreaker } from '../../query/sort';
+import { validateQuery } from '../../query/validate';
+import { hasSoftDelete, hasTimestamps } from '../../schema/declare';
+import {
+	collectionMap,
+	encodePayload,
+	toStoredRecord,
+	type MemoryScopeStore,
+} from './store';
+
+export type CollectionContext = {
+	store: MemoryScopeStore;
+	schema: CollectionSchema;
+	now: () => number;
+	assertOpen: () => void;
+};
+
+function notFound(collection: string, id: string): never {
+	raise(DiagnosticCodes.RECORD_NOT_FOUND, {
+		message: 'record not found',
+		detail: { collection, recordId: id },
+	});
+}
+
+export function createMemoryCollection<T extends StorableRecordData>(
+	context: CollectionContext,
+): CollectionOps<T> {
+	const { schema } = context;
+	const rows = () => collectionMap(context.store, schema.name);
+
+	const readable = (includeSoftDeleted: boolean): StoredRecord<T>[] => {
+		const out: StoredRecord<T>[] = [];
+		for (const row of rows().values()) {
+			if (!includeSoftDeleted && row.deletedAt != null) {
+				continue;
+			}
+			out.push(toStoredRecord<T>(row));
+		}
+		return out;
+	};
+
+	return {
+		async insert(record: RecordInput<T>): Promise<WriteOutcome> {
+			context.assertOpen();
+			throwIfFaulted('write');
+			assertRecordWithinBudget(schema.name, record.data);
+			if (rows().has(record.id)) {
+				// Overwriting silently is how a caller loses data without ever
+				// seeing a failure.
+				raise(DiagnosticCodes.RECORD_CONFLICT, {
+					message: 'record already exists',
+					detail: { collection: schema.name, recordId: record.id },
+				});
+			}
+			const now = context.now();
+			rows().set(record.id, {
+				id: record.id,
+				payload: encodePayload(record.data),
+				createdAt: hasTimestamps(schema) ? now : undefined,
+				updatedAt: hasTimestamps(schema) ? now : undefined,
+				deletedAt: hasSoftDelete(schema) ? null : undefined,
+			});
+			return { operation: 'created', id: record.id };
+		},
+
+		async update(id, record): Promise<WriteOutcome> {
+			context.assertOpen();
+			throwIfFaulted('write');
+			assertRecordWithinBudget(schema.name, record.data);
+			const existing = rows().get(id);
+			if (!existing || existing.deletedAt != null) {
+				notFound(schema.name, id);
+			}
+			existing.payload = encodePayload(record.data);
+			if (hasTimestamps(schema)) {
+				existing.updatedAt = context.now();
+			}
+			return { operation: 'updated', id };
+		},
+
+		async upsert(record: RecordInput<T>): Promise<WriteOutcome> {
+			context.assertOpen();
+			throwIfFaulted('write');
+			assertRecordWithinBudget(schema.name, record.data);
+			const existing = rows().get(record.id);
+			const now = context.now();
+			if (existing) {
+				existing.payload = encodePayload(record.data);
+				if (hasTimestamps(schema)) {
+					existing.updatedAt = now;
+				}
+				existing.deletedAt = hasSoftDelete(schema) ? null : undefined;
+				return { operation: 'updated', id: record.id };
+			}
+			rows().set(record.id, {
+				id: record.id,
+				payload: encodePayload(record.data),
+				createdAt: hasTimestamps(schema) ? now : undefined,
+				updatedAt: hasTimestamps(schema) ? now : undefined,
+				deletedAt: hasSoftDelete(schema) ? null : undefined,
+			});
+			return { operation: 'created', id: record.id };
+		},
+
+		async get(id: string): Promise<StoredRecord<T>> {
+			context.assertOpen();
+			throwIfFaulted('read');
+			const row = rows().get(id);
+			if (!row || row.deletedAt != null) {
+				notFound(schema.name, id);
+			}
+			return toStoredRecord<T>(row);
+		},
+
+		async find(id: string): Promise<StoredRecord<T> | null> {
+			context.assertOpen();
+			throwIfFaulted('read');
+			const row = rows().get(id);
+			if (!row || row.deletedAt != null) {
+				return null;
+			}
+			return toStoredRecord<T>(row);
+		},
+
+		async delete(id: string): Promise<WriteOutcome> {
+			context.assertOpen();
+			throwIfFaulted('write');
+			if (!rows().delete(id)) {
+				notFound(schema.name, id);
+			}
+			return { operation: 'deleted', id };
+		},
+
+		async softDelete(id: string): Promise<WriteOutcome> {
+			context.assertOpen();
+			throwIfFaulted('write');
+			if (!hasSoftDelete(schema)) {
+				raise(DiagnosticCodes.CONFIG_INVALID, {
+					message: 'collection does not declare soft delete',
+					detail: { collection: schema.name },
+				});
+			}
+			const row = rows().get(id);
+			if (!row || row.deletedAt != null) {
+				notFound(schema.name, id);
+			}
+			row.deletedAt = context.now();
+			return { operation: 'deleted', id };
+		},
+
+		async restore(id: string): Promise<WriteOutcome> {
+			context.assertOpen();
+			throwIfFaulted('write');
+			if (!hasSoftDelete(schema)) {
+				raise(DiagnosticCodes.CONFIG_INVALID, {
+					message: 'collection does not declare soft delete',
+					detail: { collection: schema.name },
+				});
+			}
+			const row = rows().get(id);
+			if (!row || row.deletedAt == null) {
+				notFound(schema.name, id);
+			}
+			row.deletedAt = null;
+			return { operation: 'restored', id };
+		},
+
+		async list(query?: Query): Promise<ResultPage<T>> {
+			context.assertOpen();
+			throwIfFaulted('read');
+			validateQuery(schema, query);
+			const sort = withStableTiebreaker(query?.sort);
+			const size = resolvePageSize(query?.page);
+
+			let matched = readable(query?.includeSoftDeleted === true);
+			if (query?.filter) {
+				matched = matched.filter(record => evaluateFilter(record.data, query.filter!));
+			}
+			const ordered = applyCursor(sortRecords(matched, sort), sort, query?.page?.cursor);
+			return buildPage(ordered.slice(0, size + 1), sort, size);
+		},
+
+		async count(filter?: FilterNode): Promise<number> {
+			context.assertOpen();
+			throwIfFaulted('read');
+			if (filter) {
+				validateQuery(schema, { filter });
+			}
+			const matched = readable(false);
+			if (!filter) {
+				return matched.length;
+			}
+			return matched.filter(record => evaluateFilter(record.data, filter)).length;
+		},
+	};
+}