@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

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

@@ -1,119 +1,117 @@
-/**
- * Migration execution for the in-memory adapter.
- *
- * Mirrors the on-device rules exactly, because migration behaviour is the
- * thing consumers most need to test without a device: ordered, at most once
- * per scope, atomic per step, and loud on failure (FR-047 to FR-057).
- */
-
-import type { DatabaseConfig } from '../../contract/config';
-import { DiagnosticCodes } from '../../contract/errors';
-import type { MigrationContext } from '../../contract/migration';
-import { raise } from '../../diagnostics/errors';
-import { throwIfFaulted } from '../faults';
-import type { MemoryScopeStore } from './store';
-
-export async function runMigrations(
-	store: MemoryScopeStore,
-	config: DatabaseConfig,
-	now: () => number,
-): Promise<void> {
-	const migrations = [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
-
-	if (store.schemaVersion > config.schemaVersion) {
-		// Opening anyway would mean a newer database read by older code, which
-		// silently drops whatever the newer schema added.
-		raise(DiagnosticCodes.SCHEMA_DOWNGRADE, {
-			message: 'recorded schema version is newer than the declared one',
-			detail: {
-				recordedVersion: store.schemaVersion,
-				version: config.schemaVersion,
-			},
-		});
-	}
-
-	for (const migration of migrations) {
-		if (migration.version <= store.schemaVersion) {
-			continue;
-		}
-
-		const snapshot = new Map(
-			[...store.collections].map(([name, rows]) => [name, new Map(rows)]),
-		);
-
-		try {
-			throwIfFaulted('migration');
-			// A migration gets collection access but no handle-level surface:
-			// it must not open another scope or start a nested transaction.
-			const context = {
-				collection: (name: string) => {
-					if (!store.collections.has(name)) {
-						store.collections.set(name, new Map());
-					}
-					return migrationCollection(store, name);
-				},
-				abort: async () => {
-					throw new Error('migration aborted');
-				},
-				execute: async () => {
-					// The memory adapter has no SQL. Documented divergence.
-				},
-			} as unknown as MigrationContext;
-
-			await migration.migrate(context);
-
-			store.schemaVersion = migration.version;
-			store.ledger.set(migration.version, {
-				version: migration.version,
-				attemptedAt: now(),
-				outcome: 'applied',
-			});
-		} catch (error) {
-			// Leave the recorded version untouched so the next open retries
-			// from the same place rather than skipping ahead (FR-051).
-			store.collections = snapshot;
-			store.ledger.set(migration.version, {
-				version: migration.version,
-				attemptedAt: now(),
-				outcome: 'failed',
-				failureCode: (error as { code?: string }).code ?? DiagnosticCodes.MIGRATION_FAILED,
-			});
-			raise(DiagnosticCodes.MIGRATION_FAILED, {
-				message: 'migration failed',
-				migration: {
-					recordedVersion: store.schemaVersion,
-					failingVersion: migration.version,
-					outcome: 'failed',
-				},
-				cause: error,
-			});
-		}
-	}
-
-	if (migrations.length === 0) {
-		store.schemaVersion = config.schemaVersion;
-	}
-}
-
-function migrationCollection(store: MemoryScopeStore, name: string) {
-	const rows = store.collections.get(name)!;
-	return {
-		async insert(record: { id: string; data: Record<string, unknown> }) {
-			rows.set(record.id, { id: record.id, payload: JSON.stringify(record.data) });
-			return { operation: 'created' as const, id: record.id };
-		},
-		async upsert(record: { id: string; data: Record<string, unknown> }) {
-			const existed = rows.has(record.id);
-			rows.set(record.id, { id: record.id, payload: JSON.stringify(record.data) });
-			return { operation: existed ? ('updated' as const) : ('created' as const), id: record.id };
-		},
-		async delete(id: string) {
-			rows.delete(id);
-			return { operation: 'deleted' as const, id };
-		},
-		async find(id: string) {
-			const row = rows.get(id);
-			return row ? { id: row.id, data: JSON.parse(row.payload) } : null;
-		},
-	};
-}
+/**
+ * Migration execution for the in-memory adapter.
+ *
+ * Mirrors the on-device rules exactly, because migration behaviour is the
+ * thing consumers most need to test without a device: ordered, at most once
+ * per scope, atomic per step, and loud on failure (FR-047 to FR-057).
+ */
+
+import type { DatabaseConfig } from '../../contract/config';
+import { DiagnosticCodes } from '../../contract/errors';
+import type { MigrationContext } from '../../contract/migration';
+import { raise } from '../../diagnostics/errors';
+import { throwIfFaulted } from '../faults';
+import type { MemoryScopeStore } from './store';
+
+export async function runMigrations(
+	store: MemoryScopeStore,
+	config: DatabaseConfig,
+	now: () => number,
+): Promise<void> {
+	const migrations = [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
+
+	if (store.schemaVersion > config.schemaVersion) {
+		// Opening anyway would mean a newer database read by older code, which
+		// silently drops whatever the newer schema added.
+		raise(DiagnosticCodes.SCHEMA_DOWNGRADE, {
+			message: 'recorded schema version is newer than the declared one',
+			detail: {
+				recordedVersion: store.schemaVersion,
+				version: config.schemaVersion,
+			},
+		});
+	}
+
+	for (const migration of migrations) {
+		if (migration.version <= store.schemaVersion) {
+			continue;
+		}
+
+		const snapshot = new Map([...store.collections].map(([name, rows]) => [name, new Map(rows)]));
+
+		try {
+			throwIfFaulted('migration');
+			// A migration gets collection access but no handle-level surface:
+			// it must not open another scope or start a nested transaction.
+			const context = {
+				collection: (name: string) => {
+					if (!store.collections.has(name)) {
+						store.collections.set(name, new Map());
+					}
+					return migrationCollection(store, name);
+				},
+				abort: async () => {
+					throw new Error('migration aborted');
+				},
+				execute: async () => {
+					// The memory adapter has no SQL. Documented divergence.
+				},
+			} as unknown as MigrationContext;
+
+			await migration.migrate(context);
+
+			store.schemaVersion = migration.version;
+			store.ledger.set(migration.version, {
+				version: migration.version,
+				attemptedAt: now(),
+				outcome: 'applied',
+			});
+		} catch (error) {
+			// Leave the recorded version untouched so the next open retries
+			// from the same place rather than skipping ahead (FR-051).
+			store.collections = snapshot;
+			store.ledger.set(migration.version, {
+				version: migration.version,
+				attemptedAt: now(),
+				outcome: 'failed',
+				failureCode: (error as { code?: string }).code ?? DiagnosticCodes.MIGRATION_FAILED,
+			});
+			raise(DiagnosticCodes.MIGRATION_FAILED, {
+				message: 'migration failed',
+				migration: {
+					recordedVersion: store.schemaVersion,
+					failingVersion: migration.version,
+					outcome: 'failed',
+				},
+				cause: error,
+			});
+		}
+	}
+
+	if (migrations.length === 0) {
+		store.schemaVersion = config.schemaVersion;
+	}
+}
+
+function migrationCollection(store: MemoryScopeStore, name: string) {
+	const rows = store.collections.get(name)!;
+	return {
+		async insert(record: { id: string; data: Record<string, unknown> }) {
+			rows.set(record.id, { id: record.id, payload: JSON.stringify(record.data) });
+			return { operation: 'created' as const, id: record.id };
+		},
+		async upsert(record: { id: string; data: Record<string, unknown> }) {
+			const existed = rows.has(record.id);
+			rows.set(record.id, { id: record.id, payload: JSON.stringify(record.data) });
+			return { operation: existed ? ('updated' as const) : ('created' as const), id: record.id };
+		},
+		async delete(id: string) {
+			rows.delete(id);
+			return { operation: 'deleted' as const, id };
+		},
+		async find(id: string) {
+			const row = rows.get(id);
+			return row ? { id: row.id, data: JSON.parse(row.payload) } : null;
+		},
+	};
+}

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

@@ -1,50 +1,50 @@
-/**
- * Test lifecycle helpers.
- *
- * `seedRecords` deliberately goes through the same write operations
- * production code uses (FR-094). Seeding by poking the store directly would
- * skip budget checks and timestamp handling, so tests would pass against data
- * the package would have refused to store.
- */
-
-import type { StorageAdapter } from '../../contract/adapter';
-import type { DatabaseConfig } from '../../contract/config';
-import type { RecordInput, StorableRecordData } from '../../contract/record';
-import { clearFaults } from '../faults';
-import { existingScopeStore, resetAllMemoryStores } from './store';
-
-/**
- * The conformance suite's "reach past the package" hooks, implemented for the
- * in-memory store. On device the equivalent unlinks the file directly.
- */
-export const memoryConformanceHooks = {
-	async removeArtifactBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void> {
-		existingScopeStore('conformance', scopeKey)?.artifacts.delete(attachmentId);
-	},
-	async removeReferenceBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void> {
-		existingScopeStore('conformance', scopeKey)?.attachments.delete(attachmentId);
-	},
-};
-
-/** Return every in-memory database to a known-empty state (FR-093). */
-export async function resetMemoryAdapter(_adapter?: StorageAdapter): Promise<void> {
-	resetAllMemoryStores();
-	clearFaults();
-}
-
-export async function seedRecords<T extends StorableRecordData>(
-	adapter: StorageAdapter,
-	config: DatabaseConfig,
-	collection: string,
-	records: RecordInput<T>[],
-): Promise<void> {
-	const handle = await adapter.open(config);
-	try {
-		const ops = handle.collection<T>(collection);
-		for (const record of records) {
-			await ops.upsert(record);
-		}
-	} finally {
-		await handle.close();
-	}
-}
+/**
+ * Test lifecycle helpers.
+ *
+ * `seedRecords` deliberately goes through the same write operations
+ * production code uses (FR-094). Seeding by poking the store directly would
+ * skip budget checks and timestamp handling, so tests would pass against data
+ * the package would have refused to store.
+ */
+
+import type { StorageAdapter } from '../../contract/adapter';
+import type { DatabaseConfig } from '../../contract/config';
+import type { RecordInput, StorableRecordData } from '../../contract/record';
+import { clearFaults } from '../faults';
+import { existingScopeStore, resetAllMemoryStores } from './store';
+
+/**
+ * The conformance suite's "reach past the package" hooks, implemented for the
+ * in-memory store. On device the equivalent unlinks the file directly.
+ */
+export const memoryConformanceHooks = {
+	async removeArtifactBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void> {
+		existingScopeStore('conformance', scopeKey)?.artifacts.delete(attachmentId);
+	},
+	async removeReferenceBehindTheScenes(scopeKey: string, attachmentId: string): Promise<void> {
+		existingScopeStore('conformance', scopeKey)?.attachments.delete(attachmentId);
+	},
+};
+
+/** Return every in-memory database to a known-empty state (FR-093). */
+export async function resetMemoryAdapter(_adapter?: StorageAdapter): Promise<void> {
+	resetAllMemoryStores();
+	clearFaults();
+}
+
+export async function seedRecords<T extends StorableRecordData>(
+	adapter: StorageAdapter,
+	config: DatabaseConfig,
+	collection: string,
+	records: RecordInput<T>[],
+): Promise<void> {
+	const handle = await adapter.open(config);
+	try {
+		const ops = handle.collection<T>(collection);
+		for (const record of records) {
+			await ops.upsert(record);
+		}
+	} finally {
+		await handle.close();
+	}
+}

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

@@ -1,134 +1,128 @@
-/**
- * The in-memory store behind the test adapter.
- *
- * Scope isolation is structural here for the same reason it is on device: one
- * store per scope, held in a registry keyed by scope digest. A handle holds a
- * reference to its own store and has no way to reach another (FR-011).
- */
-
-import type { AttachmentReference } from '../../contract/attachment';
-import type { MigrationLedgerEntry } from '../../contract/migration';
-import type { StorableRecordData, StoredRecord } from '../../contract/record';
-import type { ScopeDeletionState } from '../../contract/scope';
-
-export type MemoryRow = {
-	id: string;
-	/** Serialized on write, parsed on read — the same payload-as-truth rule
-	 * the SQLite adapter follows, so a mutation after write cannot leak in. */
-	payload: string;
-	createdAt?: number;
-	updatedAt?: number;
-	deletedAt?: number | null;
-};
-
-export type MemoryScopeStore = {
-	scopeKey: string;
-	schemaVersion: number;
-	ledger: Map<number, MigrationLedgerEntry>;
-	collections: Map<string, Map<string, MemoryRow>>;
-	attachments: Map<string, AttachmentReference>;
-	artifacts: Map<string, string>;
-	deletionState: ScopeDeletionState;
-	encrypted: boolean;
-	backupIncluded: boolean;
-};
-
-export type MemoryDatabase = {
-	name: string;
-	scopes: Map<string, MemoryScopeStore>;
-};
-
-const databases = new Map<string, MemoryDatabase>();
-
-export function databaseFor(name: string): MemoryDatabase {
-	let database = databases.get(name);
-	if (!database) {
-		database = { name, scopes: new Map() };
-		databases.set(name, database);
-	}
-	return database;
-}
-
-export function scopeStoreFor(name: string, scopeKey: string): MemoryScopeStore {
-	const database = databaseFor(name);
-	let store = database.scopes.get(scopeKey);
-	if (!store) {
-		store = {
-			scopeKey,
-			schemaVersion: 0,
-			ledger: new Map(),
-			collections: new Map(),
-			attachments: new Map(),
-			artifacts: new Map(),
-			deletionState: 'active',
-			encrypted: false,
-			backupIncluded: false,
-		};
-		database.scopes.set(scopeKey, store);
-	}
-	return store;
-}
-
-export function existingScopeStore(
-	name: string,
-	scopeKey: string,
-): MemoryScopeStore | undefined {
-	return databases.get(name)?.scopes.get(scopeKey);
-}
-
-export function dropScope(name: string, scopeKey: string): void {
-	databases.get(name)?.scopes.delete(scopeKey);
-}
-
-export function dropDatabase(name: string): void {
-	databases.delete(name);
-}
-
-/** Between tests (FR-093). */
-export function resetAllMemoryStores(): void {
-	databases.clear();
-}
-
-export function collectionMap(
-	store: MemoryScopeStore,
-	collection: string,
-): Map<string, MemoryRow> {
-	let rows = store.collections.get(collection);
-	if (!rows) {
-		rows = new Map();
-		store.collections.set(collection, rows);
-	}
-	return rows;
-}
-
-/**
- * Deep copy through serialization on the way in and out.
- *
- * The same discipline as the SQLite adapter's payload column: a consumer that
- * mutates the object it handed us must not change what is stored (FR-022),
- * and what we hand back must not be a live reference into the store.
- */
-export function encodePayload(data: StorableRecordData): string {
-	return JSON.stringify(data ?? {});
-}
-
-export function decodePayload<T extends StorableRecordData>(payload: string): T {
-	return JSON.parse(payload) as T;
-}
-
-export function toStoredRecord<T extends StorableRecordData>(row: MemoryRow): StoredRecord<T> {
-	const record: StoredRecord<T> = {
-		id: row.id,
-		data: decodePayload<T>(row.payload),
-	};
-	if (row.createdAt !== undefined) {
-		record.createdAt = row.createdAt;
-	}
-	if (row.updatedAt !== undefined) {
-		record.updatedAt = row.updatedAt;
-	}
-	if (row.deletedAt !== undefined) {
-		record.deletedAt = row.deletedAt;
-	}
-	return record;
-}
+/**
+ * The in-memory store behind the test adapter.
+ *
+ * Scope isolation is structural here for the same reason it is on device: one
+ * store per scope, held in a registry keyed by scope digest. A handle holds a
+ * reference to its own store and has no way to reach another (FR-011).
+ */
+
+import type { AttachmentReference } from '../../contract/attachment';
+import type { MigrationLedgerEntry } from '../../contract/migration';
+import type { StorableRecordData, StoredRecord } from '../../contract/record';
+import type { ScopeDeletionState } from '../../contract/scope';
+
+export type MemoryRow = {
+	id: string;
+	/** Serialized on write, parsed on read — the same payload-as-truth rule
+	 * the SQLite adapter follows, so a mutation after write cannot leak in. */
+	payload: string;
+	createdAt?: number | undefined;
+	updatedAt?: number | undefined;
+	deletedAt?: number | null | undefined;
+};
+
+export type MemoryScopeStore = {
+	scopeKey: string;
+	schemaVersion: number;
+	ledger: Map<number, MigrationLedgerEntry>;
+	collections: Map<string, Map<string, MemoryRow>>;
+	attachments: Map<string, AttachmentReference>;
+	artifacts: Map<string, string>;
+	deletionState: ScopeDeletionState;
+	encrypted: boolean;
+	backupIncluded: boolean;
+};
+
+export type MemoryDatabase = {
+	name: string;
+	scopes: Map<string, MemoryScopeStore>;
+};
+
+const databases = new Map<string, MemoryDatabase>();
+
+export function databaseFor(name: string): MemoryDatabase {
+	let database = databases.get(name);
+	if (!database) {
+		database = { name, scopes: new Map() };
+		databases.set(name, database);
+	}
+	return database;
+}
+
+export function scopeStoreFor(name: string, scopeKey: string): MemoryScopeStore {
+	const database = databaseFor(name);
+	let store = database.scopes.get(scopeKey);
+	if (!store) {
+		store = {
+			scopeKey,
+			schemaVersion: 0,
+			ledger: new Map(),
+			collections: new Map(),
+			attachments: new Map(),
+			artifacts: new Map(),
+			deletionState: 'active',
+			encrypted: false,
+			backupIncluded: false,
+		};
+		database.scopes.set(scopeKey, store);
+	}
+	return store;
+}
+
+export function existingScopeStore(name: string, scopeKey: string): MemoryScopeStore | undefined {
+	return databases.get(name)?.scopes.get(scopeKey);
+}
+
+export function dropScope(name: string, scopeKey: string): void {
+	databases.get(name)?.scopes.delete(scopeKey);
+}
+
+export function dropDatabase(name: string): void {
+	databases.delete(name);
+}
+
+/** Between tests (FR-093). */
+export function resetAllMemoryStores(): void {
+	databases.clear();
+}
+
+export function collectionMap(store: MemoryScopeStore, collection: string): Map<string, MemoryRow> {
+	let rows = store.collections.get(collection);
+	if (!rows) {
+		rows = new Map();
+		store.collections.set(collection, rows);
+	}
+	return rows;
+}
+
+/**
+ * Deep copy through serialization on the way in and out.
+ *
+ * The same discipline as the SQLite adapter's payload column: a consumer that
+ * mutates the object it handed us must not change what is stored (FR-022),
+ * and what we hand back must not be a live reference into the store.
+ */
+export function encodePayload(data: StorableRecordData): string {
+	return JSON.stringify(data ?? {});
+}
+
+export function decodePayload<T extends StorableRecordData>(payload: string): T {
+	return JSON.parse(payload) as T;
+}
+
+export function toStoredRecord<T extends StorableRecordData>(row: MemoryRow): StoredRecord<T> {
+	const record: StoredRecord<T> = {
+		id: row.id,
+		data: decodePayload<T>(row.payload),
+	};
+	if (row.createdAt !== undefined) {
+		record.createdAt = row.createdAt;
+	}
+	if (row.updatedAt !== undefined) {
+		record.updatedAt = row.updatedAt;
+	}
+	if (row.deletedAt !== undefined) {
+		record.deletedAt = row.deletedAt;
+	}
+	return record;
+}