@chipmobilesdk/rn-local-db 0.1.0

package/src/testing/conformance/migrations.ts

@@ -0,0 +1,177 @@
+import { DiagnosticCodes } from '../../contract/errors';
+import type { Migration } from '../../contract/migration';
+import { isCode } from '../../diagnostics/errors';
+import type { ConformanceContext } from './index';
+
+/** US5: ordered, once-only migrations that fail loudly. */
+export function registerMigrationConformance(context: ConformanceContext): void {
+	describe('conformance: migrations', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'guest' } as const;
+
+		function chain(order: number[], onRun: (version: number) => void): Migration[] {
+			return order.map(version => ({
+				version,
+				migrate: async () => {
+					onRun(version);
+				},
+			}));
+		}
+
+		it('runs pending migrations in ascending order', async () => {
+			const ran: number[] = [];
+			const handle = await context.adapter.open(
+				context.configFor(scope, {
+					schemaVersion: 3,
+					migrations: chain([3, 1, 2], v => ran.push(v)),
+				}),
+			);
+			expect(ran).toEqual([1, 2, 3]);
+			expect(handle.schemaVersion).toBe(3);
+			await handle.close();
+		});
+
+		it('runs each migration at most once across repeated opens', async () => {
+			const ran: number[] = [];
+			const config = context.configFor(scope, {
+				schemaVersion: 2,
+				migrations: chain([1, 2], v => ran.push(v)),
+			});
+
+			for (let i = 0; i < 3; i += 1) {
+				const handle = await context.adapter.open(config);
+				await handle.close();
+			}
+			expect(ran).toEqual([1, 2]);
+		});
+
+		it('returns no handle and keeps the version when a migration fails', async () => {
+			const config = context.configFor(scope, {
+				schemaVersion: 2,
+				migrations: [
+					{ version: 1, migrate: async () => {} },
+					{
+						version: 2,
+						migrate: async () => {
+							throw new Error('boom');
+						},
+					},
+				],
+			});
+
+			let thrown: unknown;
+			try {
+				await context.adapter.open(config);
+			} catch (error) {
+				thrown = error;
+			}
+
+			expect(isCode(thrown, DiagnosticCodes.MIGRATION_FAILED)).toBe(true);
+			expect((thrown as { migration?: unknown }).migration).toEqual({
+				recordedVersion: 1,
+				failingVersion: 2,
+				outcome: 'failed',
+			});
+		});
+
+		it('retries from the same version rather than skipping ahead', async () => {
+			let attempts = 0;
+			const config = context.configFor(scope, {
+				schemaVersion: 1,
+				migrations: [
+					{
+						version: 1,
+						migrate: async () => {
+							attempts += 1;
+							if (attempts < 3) {
+								throw new Error('not yet');
+							}
+						},
+					},
+				],
+			});
+
+			for (let i = 0; i < 2; i += 1) {
+				await expect(context.adapter.open(config)).rejects.toBeDefined();
+			}
+			const handle = await context.adapter.open(config);
+			expect(attempts).toBe(3);
+			expect(handle.schemaVersion).toBe(1);
+			await handle.close();
+		});
+
+		it('alters nothing across repeated failed opens', async () => {
+			const seedConfig = context.configFor(scope, {
+				schemaVersion: 1,
+				migrations: [{ version: 1, migrate: async () => {} }],
+			});
+			const seeded = await context.adapter.open(seedConfig);
+			await seeded.collection('notes').insert({ id: 'keep', data: { title: 'keep' } });
+			await seeded.close();
+
+			const brokenConfig = context.configFor(scope, {
+				schemaVersion: 2,
+				migrations: [
+					{ version: 1, migrate: async () => {} },
+					{
+						version: 2,
+						migrate: async () => {
+							throw new Error('permanently broken');
+						},
+					},
+				],
+			});
+
+			for (let i = 0; i < 10; i += 1) {
+				await expect(context.adapter.open(brokenConfig)).rejects.toBeDefined();
+			}
+
+			const recovered = await context.adapter.open(seedConfig);
+			expect((await recovered.collection('notes').get('keep')).data.title).toBe('keep');
+			await recovered.close();
+		});
+
+		it('reports a downgrade rather than opening or discarding', async () => {
+			const newer = await context.adapter.open(
+				context.configFor(scope, {
+					schemaVersion: 3,
+					migrations: chain([1, 2, 3], () => {}),
+				}),
+			);
+			await newer.close();
+
+			let thrown: unknown;
+			try {
+				await context.adapter.open(
+					context.configFor(scope, {
+						schemaVersion: 1,
+						migrations: chain([1], () => {}),
+					}),
+				);
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.SCHEMA_DOWNGRADE)).toBe(true);
+		});
+
+		it('migrates a scope created after the migration shipped', async () => {
+			const ran: number[] = [];
+			const config = (id: string) =>
+				context.configFor(
+					{ kind: 'identity', id },
+					{ schemaVersion: 2, migrations: chain([1, 2], v => ran.push(v)) },
+				);
+
+			const first = await context.adapter.open(config('alice'));
+			await first.close();
+			ran.length = 0;
+
+			// A brand-new scope must not be assumed already current.
+			const second = await context.adapter.open(config('bob'));
+			expect(ran).toEqual([1, 2]);
+			expect(second.schemaVersion).toBe(2);
+			await second.close();
+		});
+	});
+}

package/src/testing/conformance/queries.ts

@@ -0,0 +1,167 @@
+import { DiagnosticCodes } from '../../contract/errors';
+import { isCode } from '../../diagnostics/errors';
+import type { ConformanceContext } from './index';
+
+/** US3: filter, sort, page, count — and paging that loses nothing. */
+export function registerQueryConformance(context: ConformanceContext): void {
+	describe('conformance: queries', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'guest' } as const;
+		const SIZE = 40;
+
+		async function seeded() {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			for (let i = 0; i < SIZE; i += 1) {
+				await notes.insert({
+					id: `id-${String(i).padStart(3, '0')}`,
+					data: { title: `note ${i}`, score: i % 10, done: i % 2 === 0 },
+				});
+			}
+			return handle;
+		}
+
+		it('filters to the matching records only', async () => {
+			const handle = await seeded();
+			const page = await handle
+				.collection('notes')
+				.list({ filter: { op: 'eq', field: 'score', value: 3 }, page: { size: 100 } });
+			expect(page.records).toHaveLength(4);
+			expect(page.records.every(r => r.data.score === 3)).toBe(true);
+			await handle.close();
+		});
+
+		it('agrees between count and a full listing', async () => {
+			const handle = await seeded();
+			const notes = handle.collection('notes');
+			const filter = { op: 'gte', field: 'score', value: 5 } as const;
+
+			const counted = await notes.count(filter);
+			const listed = await notes.list({ filter, page: { size: 500 } });
+			expect(counted).toBe(listed.records.length);
+			await handle.close();
+		});
+
+		it('walks every record exactly once with no gaps or duplicates', async () => {
+			const handle = await seeded();
+			const notes = handle.collection('notes');
+			const seen: string[] = [];
+			let cursor: string | undefined;
+			let guard = 0;
+
+			do {
+				const page = await notes.list({
+					sort: [{ field: 'score' }],
+					page: { size: 7, cursor },
+				});
+				seen.push(...page.records.map(r => r.id));
+				cursor = page.cursor;
+				guard += 1;
+			} while (cursor && guard < 50);
+
+			expect(seen).toHaveLength(SIZE);
+			expect(new Set(seen).size).toBe(SIZE);
+			await handle.close();
+		});
+
+		it('sorts, and breaks ties deterministically', async () => {
+			const handle = await seeded();
+			const page = await handle
+				.collection('notes')
+				.list({ sort: [{ field: 'score' }], page: { size: 500 } });
+
+			const scores = page.records.map(r => r.data.score as number);
+			expect([...scores].sort((a, b) => a - b)).toEqual(scores);
+
+			const again = await handle
+				.collection('notes')
+				.list({ sort: [{ field: 'score' }], page: { size: 500 } });
+			expect(again.records.map(r => r.id)).toEqual(page.records.map(r => r.id));
+			await handle.close();
+		});
+
+		it('sorts descending when asked', async () => {
+			const handle = await seeded();
+			const page = await handle
+				.collection('notes')
+				.list({ sort: [{ field: 'score', direction: 'desc' }], page: { size: 5 } });
+			expect(page.records[0]!.data.score).toBe(9);
+			await handle.close();
+		});
+
+		it('returns an empty result rather than an error when nothing matches', async () => {
+			const handle = await seeded();
+			const page = await handle
+				.collection('notes')
+				.list({ filter: { op: 'eq', field: 'score', value: 999 } });
+			expect(page.records).toEqual([]);
+			expect(page.hasMore).toBe(false);
+			await handle.close();
+		});
+
+		it('rejects a filter on an undeclared field', async () => {
+			const handle = await seeded();
+			let thrown: unknown;
+			try {
+				await handle.collection('notes').list({ filter: { op: 'eq', field: 'nope', value: 1 } });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.QUERY_INVALID)).toBe(true);
+			await handle.close();
+		});
+
+		it.each([0, -1, 501])('rejects page size %p', async size => {
+			const handle = await seeded();
+			let thrown: unknown;
+			try {
+				await handle.collection('notes').list({ page: { size } });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.PAGE_SIZE_INVALID)).toBe(true);
+			await handle.close();
+		});
+
+		it('excludes soft-deleted records from queries and counts by default', async () => {
+			const handle = await seeded();
+			const notes = handle.collection('notes');
+			await notes.softDelete('id-000');
+
+			expect(await notes.count()).toBe(SIZE - 1);
+			const page = await notes.list({ page: { size: 500 } });
+			expect(page.records.some(r => r.id === 'id-000')).toBe(false);
+			await handle.close();
+		});
+
+		it('supports the full operator set', async () => {
+			const handle = await seeded();
+			const notes = handle.collection('notes');
+
+			expect((await notes.list({ filter: { op: 'ne', field: 'score', value: 0 }, page: { size: 500 } })).records).toHaveLength(36);
+			expect((await notes.list({ filter: { op: 'in', field: 'score', value: [0, 1] }, page: { size: 500 } })).records).toHaveLength(8);
+			expect((await notes.list({ filter: { op: 'nin', field: 'score', value: [0] }, page: { size: 500 } })).records).toHaveLength(36);
+			expect((await notes.list({ filter: { op: 'between', field: 'score', value: [0, 1] }, page: { size: 500 } })).records).toHaveLength(8);
+			expect((await notes.list({ filter: { op: 'lt', field: 'score', value: 1 }, page: { size: 500 } })).records).toHaveLength(4);
+			expect((await notes.list({ filter: { op: 'exists', field: 'title', value: true }, page: { size: 500 } })).records).toHaveLength(SIZE);
+			expect((await notes.list({ filter: { op: 'isNull', field: 'title' }, page: { size: 500 } })).records).toHaveLength(0);
+			expect(
+				(
+					await notes.list({
+						filter: {
+							op: 'and',
+							nodes: [
+								{ op: 'gte', field: 'score', value: 5 },
+								{ op: 'eq', field: 'done', value: true },
+							],
+						},
+						page: { size: 500 },
+					})
+				).records.length,
+			).toBeGreaterThan(0);
+
+			await handle.close();
+		});
+	});
+}

package/src/testing/conformance/records.ts

@@ -0,0 +1,169 @@
+import { DiagnosticCodes } from '../../contract/errors';
+import { isCode } from '../../diagnostics/errors';
+import type { ConformanceContext } from './index';
+
+/** US1: durable CRUD, and the four value conditions staying distinguishable. */
+export function registerRecordConformance(context: ConformanceContext): void {
+	describe('conformance: records', () => {
+		beforeEach(() => context.reset());
+
+		const scope = { kind: 'guest' } as const;
+
+		it('returns exactly what was stored', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			const data = {
+				title: 'alpha',
+				score: 1.5,
+				nested: { deep: [1, 'two', null, { three: true }] },
+				explicitNull: null,
+			};
+			await notes.insert({ id: 'a', data });
+
+			expect((await notes.get('a')).data).toEqual(data);
+			await handle.close();
+		});
+
+		it('does not mutate the object the caller passed in', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const data = { title: 'alpha' };
+			await handle.collection('notes').insert({ id: 'a', data });
+			expect(data).toEqual({ title: 'alpha' });
+			await handle.close();
+		});
+
+		it('does not hand back a live reference into the store', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			await notes.insert({ id: 'a', data: { title: 'alpha' } });
+
+			const first = await notes.get('a');
+			(first.data as { title: string }).title = 'mutated';
+
+			expect((await notes.get('a')).data).toEqual({ title: 'alpha' });
+			await handle.close();
+		});
+
+		it('distinguishes absent record, explicit null, and absent field', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			await notes.insert({ id: 'null-field', data: { title: null } });
+			await notes.insert({ id: 'absent-field', data: {} });
+
+			const withNull = await notes.get('null-field');
+			expect('title' in withNull.data).toBe(true);
+			expect(withNull.data.title).toBeNull();
+
+			const withAbsent = await notes.get('absent-field');
+			expect('title' in withAbsent.data).toBe(false);
+
+			expect(await notes.find('never-existed')).toBeNull();
+			await handle.close();
+		});
+
+		it('reports a conflict rather than overwriting on insert', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			await notes.insert({ id: 'a', data: { title: 'first' } });
+
+			let thrown: unknown;
+			try {
+				await notes.insert({ id: 'a', data: { title: 'second' } });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.RECORD_CONFLICT)).toBe(true);
+			expect((await notes.get('a')).data.title).toBe('first');
+			await handle.close();
+		});
+
+		it('reports whether an upsert created or updated', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			expect((await notes.upsert({ id: 'a', data: { title: 'x' } })).operation).toBe('created');
+			expect((await notes.upsert({ id: 'a', data: { title: 'y' } })).operation).toBe('updated');
+			await handle.close();
+		});
+
+		it('reports record-not-found rather than creating on update', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			let thrown: unknown;
+			try {
+				await handle.collection('notes').update('ghost', { data: { title: 'x' } });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.RECORD_NOT_FOUND)).toBe(true);
+			expect(await handle.collection('notes').find('ghost')).toBeNull();
+			await handle.close();
+		});
+
+		it('makes a hard-deleted record not-found', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			await notes.insert({ id: 'a', data: { title: 'x' } });
+			await notes.delete('a');
+			expect(await notes.find('a')).toBeNull();
+			await handle.close();
+		});
+
+		it('hides a soft-deleted record by default and restores it', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			const notes = handle.collection('notes');
+			await notes.insert({ id: 'a', data: { title: 'x' } });
+			await notes.softDelete('a');
+
+			expect(await notes.find('a')).toBeNull();
+			expect((await notes.list()).records).toHaveLength(0);
+			expect((await notes.list({ includeSoftDeleted: true })).records).toHaveLength(1);
+
+			await notes.restore('a');
+			expect(await notes.find('a')).not.toBeNull();
+			await handle.close();
+		});
+
+		it('rejects a record over the size budget rather than truncating', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			let thrown: unknown;
+			try {
+				await handle
+					.collection('notes')
+					.insert({ id: 'big', data: { title: 'x'.repeat(300_000) } });
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.RECORD_TOO_LARGE)).toBe(true);
+			expect(await handle.collection('notes').find('big')).toBeNull();
+			await handle.close();
+		});
+
+		it('rejects operations on a closed handle', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			await handle.close();
+
+			let thrown: unknown;
+			try {
+				await handle.collection('notes').find('a');
+			} catch (error) {
+				thrown = error;
+			}
+			expect(isCode(thrown, DiagnosticCodes.CLOSED_HANDLE)).toBe(true);
+		});
+
+		it('persists across a close and reopen', async () => {
+			const first = await context.adapter.open(context.configFor(scope));
+			await first.collection('notes').insert({ id: 'a', data: { title: 'kept' } });
+			await first.close();
+
+			const second = await context.adapter.open(context.configFor(scope));
+			expect((await second.collection('notes').get('a')).data.title).toBe('kept');
+			await second.close();
+		});
+
+		it('rejects a collection that was never declared', async () => {
+			const handle = await context.adapter.open(context.configFor(scope));
+			expect(() => handle.collection('nope')).toThrow();
+			await handle.close();
+		});
+	});
+}

package/src/testing/conformance/scopes.ts

@@ -0,0 +1,88 @@
+import type { ScopeDescriptor } from '../../contract/scope';
+import type { ConformanceContext } from './index';
+
+/** US2: scope isolation, proven with unfiltered reads and colliding ids. */
+export function registerScopeConformance(context: ConformanceContext): void {
+	describe('conformance: scopes', () => {
+		beforeEach(() => context.reset());
+
+		const guest: ScopeDescriptor = { kind: 'guest' };
+		const alice: ScopeDescriptor = { kind: 'identity', id: 'alice' };
+		const bob: ScopeDescriptor = { kind: 'identity', id: 'bob' };
+
+		it('returns nothing from another scope, even unfiltered', async () => {
+			const a = await context.adapter.open(context.configFor(alice));
+			await a.collection('notes').insert({ id: 'shared-id', data: { title: 'alice' } });
+			await a.close();
+
+			const b = await context.adapter.open(context.configFor(bob));
+			expect((await b.collection('notes').list()).records).toHaveLength(0);
+			expect(await b.collection('notes').count()).toBe(0);
+			expect(await b.collection('notes').find('shared-id')).toBeNull();
+			await b.close();
+		});
+
+		it('lets the same id exist independently in two scopes', async () => {
+			const a = await context.adapter.open(context.configFor(alice));
+			const b = await context.adapter.open(context.configFor(bob));
+
+			await a.collection('notes').insert({ id: 'same', data: { title: 'alice' } });
+			await b.collection('notes').insert({ id: 'same', data: { title: 'bob' } });
+
+			expect((await a.collection('notes').get('same')).data.title).toBe('alice');
+			expect((await b.collection('notes').get('same')).data.title).toBe('bob');
+			await a.close();
+			await b.close();
+		});
+
+		it('keeps three concurrently open handles independent', async () => {
+			const handles = await Promise.all(
+				[guest, alice, bob].map(scope => context.adapter.open(context.configFor(scope))),
+			);
+
+			await Promise.all(
+				handles.map((handle, index) =>
+					handle.collection('notes').insert({ id: 'x', data: { score: index } }),
+				),
+			);
+
+			for (const [index, handle] of handles.entries()) {
+				expect((await handle.collection('notes').get('x')).data.score).toBe(index);
+				expect(await handle.collection('notes').count()).toBe(1);
+			}
+			await Promise.all(handles.map(handle => handle.close()));
+		});
+
+		it('exposes the scope digest rather than the components', async () => {
+			const handle = await context.adapter.open(context.configFor(alice));
+			expect(handle.scopeKey).toMatch(/^[0-9a-f]{64}$/);
+			expect(handle.scopeKey).not.toContain('alice');
+			await handle.close();
+		});
+
+		it('resolves the same descriptor to the same scope across opens', async () => {
+			const first = await context.adapter.open(context.configFor(alice));
+			const key = first.scopeKey;
+			await first.close();
+
+			const second = await context.adapter.open(
+				context.configFor({ kind: 'identity', id: 'alice' }),
+			);
+			expect(second.scopeKey).toBe(key);
+			await second.close();
+		});
+
+		it('treats a differing component as a different scope', async () => {
+			const plain = await context.adapter.open(context.configFor(alice));
+			const tenanted = await context.adapter.open(
+				context.configFor({ ...alice, tenant: 'acme' }),
+			);
+			expect(tenanted.scopeKey).not.toBe(plain.scopeKey);
+
+			await plain.collection('notes').insert({ id: 'x', data: { title: 'plain' } });
+			expect(await tenanted.collection('notes').find('x')).toBeNull();
+			await plain.close();
+			await tenanted.close();
+		});
+	});
+}