@chipmobilesdk/rn-local-db 0.1.0

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

@@ -0,0 +1,388 @@
+/**
+ * The in-memory adapter.
+ *
+ * Not a convenience: op-sqlite is native and unreachable from Jest, so this
+ * is the only way the package's own guarantees are testable in CI
+ * (research.md R8). Documented divergences are listed in the package README.
+ */
+
+import type {
+	AttachmentInput,
+	AttachmentReference,
+	AttachmentOwner,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from '../../contract/attachment';
+import type { EffectivePosture } from '../../contract/backup';
+import type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } from '../../contract/config';
+import { DiagnosticCodes } from '../../contract/errors';
+import type { IndexCoverageReport, Query } from '../../contract/query';
+import type { StorableRecordData } from '../../contract/record';
+import type { CollectionSchema } from '../../contract/schema';
+import type { BatchOperation, BatchOutcome, CollectionOps, Transaction } from '../../contract/transaction';
+import type { Attachments, DatabaseHandle, StorageAdapter } from '../../contract/adapter';
+import { acquireKey } from '../../crypto/key-provider';
+import { instrument } from '../../diagnostics/dev-log';
+import { raise } from '../../diagnostics/errors';
+import { assertValidAttachmentId } from '../../platform/location';
+import { assertBatchWithinBudget, assertArtifactWithinBudget } from '../../query/budgets';
+import { validateConfig } from '../../schema/validate-config';
+import { resolveScope } from '../../scope/validate';
+import { runMigrations } from './migrations';
+import { createMemoryCollection } from './collection';
+import {
+	collectionMap,
+	dropDatabase,
+	dropScope,
+	existingScopeStore,
+	scopeStoreFor,
+	type MemoryScopeStore,
+} from './store';
+import { throwIfFaulted } from '../faults';
+
+export type MemoryAdapterOptions = {
+	/** Fixed clock, so timestamp assertions are deterministic. */
+	now?: () => number;
+};
+
+function schemaIndex(collections: CollectionSchema[]): Map<string, CollectionSchema> {
+	return new Map(collections.map(collection => [collection.name, collection]));
+}
+
+function cloneCollections(
+	store: MemoryScopeStore,
+): Map<string, Map<string, { id: string; payload: string; createdAt?: number; updatedAt?: number; deletedAt?: number | null }>> {
+	const copy = new Map<string, Map<string, never>>();
+	for (const [name, rows] of store.collections) {
+		copy.set(name, new Map([...rows].map(([id, row]) => [id, { ...row } as never])));
+	}
+	return copy as never;
+}
+
+export function createMemoryAdapter(options: MemoryAdapterOptions = {}): StorageAdapter {
+	const now = options.now ?? (() => Date.now());
+
+	async function open(config: DatabaseConfig): Promise<DatabaseHandle> {
+		validateConfig(config);
+		throwIfFaulted('open');
+
+		const scope = resolveScope(config.scope);
+		const existing = existingScopeStore(config.name, scope.key);
+		if (existing?.deletionState === 'deleting') {
+			// A deletion that was interrupted must never look complete.
+			raise(DiagnosticCodes.SCOPE_DELETED, {
+				message: 'scope deletion was interrupted',
+				detail: { scopeKey: scope.key },
+			});
+		}
+
+		const store = scopeStoreFor(config.name, scope.key);
+		const encryptionRequested = config.encryption?.enabled === true;
+
+		if (store.schemaVersion > 0 && store.encrypted !== encryptionRequested) {
+			raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
+				message: 'encryption posture does not match the stored database',
+			});
+		}
+		if (encryptionRequested) {
+			// The same acquisition path the on-device adapter uses, so a locked
+			// keychain and a provider returning nothing stay as distinguishable
+			// here as they are on a phone (SC-020b). Released immediately: the
+			// in-memory store has nothing to encrypt with it.
+			const key = await acquireKey(config.encryption!, scope);
+			key.release();
+		}
+		store.encrypted = encryptionRequested;
+		store.backupIncluded = config.backup?.includeInPlatformBackup === true;
+
+		const schemas = schemaIndex(config.collections);
+		for (const collection of config.collections) {
+			collectionMap(store, collection.name);
+		}
+
+		await runMigrations(store, config, now);
+
+		let closed = false;
+		const assertOpen = (): void => {
+			if (closed) {
+				raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'handle is closed' });
+			}
+			if (store.deletionState === 'deleting') {
+				raise(DiagnosticCodes.SCOPE_DELETED, {
+					message: 'scope was deleted beneath this handle',
+					detail: { scopeKey: scope.key },
+				});
+			}
+		};
+
+		const collectionFor = <T extends StorableRecordData>(name: string): CollectionOps<T> => {
+			assertOpen();
+			const schema = schemas.get(name);
+			if (!schema) {
+				raise(DiagnosticCodes.CONFIG_INVALID, {
+					message: 'collection is not declared',
+					detail: { collection: name },
+				});
+			}
+			return instrument(
+				name,
+				'memory',
+				createMemoryCollection<T>({ store, schema, now, assertOpen }) as unknown as Record<
+					string,
+					(...args: never[]) => unknown
+				>,
+			) as unknown as CollectionOps<T>;
+		};
+
+		const backupPosture: EffectivePosture = {
+			requested: store.backupIncluded ? 'included' : 'excluded',
+			observed: store.backupIncluded ? 'included' : 'excluded',
+			enforcedBy: 'package',
+		};
+
+		const attachments: Attachments = {
+			async write(input: AttachmentInput): Promise<AttachmentReference> {
+				assertOpen();
+				throwIfFaulted('attachmentWrite');
+				assertValidAttachmentId(input.id);
+				const bytes = Buffer.from(input.content, 'base64');
+				assertArtifactWithinBudget(input.id, bytes.length);
+				const reference: AttachmentReference = {
+					id: input.id,
+					owner: input.owner,
+					contentType: input.contentType,
+					size: bytes.length,
+					createdAt: now(),
+				};
+				store.artifacts.set(input.id, input.content);
+				store.attachments.set(input.id, reference);
+				return reference;
+			},
+			async read(id: string, range?: ByteRange): Promise<string> {
+				assertOpen();
+				// No paths here to escape, but an id the device build would refuse
+				// has to be refused here too, or a consumer's passing tests stop
+				// predicting the device (FR-096).
+				assertValidAttachmentId(id);
+				const content = store.artifacts.get(id);
+				if (content === undefined) {
+					raise(DiagnosticCodes.ATTACHMENT_MISSING, {
+						message: 'artifact is missing',
+						detail: { attachmentId: id },
+					});
+				}
+				if (!range) {
+					return content;
+				}
+				const bytes = Buffer.from(content, 'base64');
+				return bytes.subarray(range.offset, range.offset + range.length).toString('base64');
+			},
+			async availability(id) {
+				assertOpen();
+				const reference = store.attachments.get(id);
+				if (!reference) {
+					return { id, state: 'missing' };
+				}
+				return store.artifacts.has(id)
+					? { id, state: 'available', size: reference.size }
+					: { id, state: 'missing' };
+			},
+			async remove(id: string): Promise<DeletionOutcome> {
+				assertOpen();
+				assertValidAttachmentId(id);
+				const removed = store.artifacts.delete(id);
+				store.attachments.delete(id);
+				return {
+					removedRecords: 0,
+					removedArtifacts: removed ? [id] : [],
+					orphanedReferences: [],
+					failedRemovals: [],
+				};
+			},
+			async listFor(owner: AttachmentOwner): Promise<AttachmentReference[]> {
+				assertOpen();
+				return [...store.attachments.values()].filter(
+					reference =>
+						reference.owner?.collection === owner.collection &&
+						reference.owner?.id === owner.id,
+				);
+			},
+			async reconcile(reconcileOptions): Promise<ReconciliationReport> {
+				assertOpen();
+				const orphanedArtifacts = [...store.artifacts.keys()].filter(
+					id => !store.attachments.has(id),
+				);
+				const danglingReferences = [...store.attachments.keys()].filter(
+					id => !store.artifacts.has(id),
+				);
+				const removedArtifacts: string[] = [];
+				if (reconcileOptions?.removeOrphans) {
+					for (const id of orphanedArtifacts) {
+						store.artifacts.delete(id);
+						removedArtifacts.push(id);
+					}
+				}
+				return { orphanedArtifacts, danglingReferences, removedArtifacts };
+			},
+		};
+
+		const handle: DatabaseHandle = {
+			scopeKey: scope.key,
+			schemaVersion: store.schemaVersion,
+			backupPosture,
+			isEncrypted: store.encrypted,
+			collection: collectionFor,
+
+			async transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R> {
+				assertOpen();
+				// Snapshot-and-restore rather than a write log: simpler to
+				// reason about, and rollback fidelity is what US4 tests.
+				const snapshot = cloneCollections(store);
+				const attachmentSnapshot = new Map(store.attachments);
+				let settled = false;
+
+				const tx: Transaction = {
+					collection: <T extends StorableRecordData>(name: string) => {
+						if (settled) {
+							raise(DiagnosticCodes.TRANSACTION_STATE, {
+								message: 'transaction already settled',
+							});
+						}
+						return collectionFor<T>(name);
+					},
+					async abort() {
+						if (settled) {
+							raise(DiagnosticCodes.TRANSACTION_STATE, {
+								message: 'transaction already settled',
+							});
+						}
+						settled = true;
+						store.collections = snapshot as never;
+						store.attachments = attachmentSnapshot;
+					},
+				};
+
+				try {
+					const result = await fn(tx);
+					if (!settled) {
+						throwIfFaulted('commit');
+						settled = true;
+					}
+					return result;
+				} catch (error) {
+					if (!settled) {
+						settled = true;
+						store.collections = snapshot as never;
+						store.attachments = attachmentSnapshot;
+					}
+					throw error;
+				}
+			},
+
+			async batch(operations: BatchOperation[]): Promise<BatchOutcome> {
+				assertOpen();
+				assertBatchWithinBudget(operations.length);
+				return handle.transaction(async (tx: Transaction) => {
+					const outcomes = [];
+					for (const operation of operations) {
+						const ops = tx.collection(operation.collection);
+						switch (operation.type) {
+							case 'insert':
+								outcomes.push(await ops.insert(operation.record));
+								break;
+							case 'update':
+								outcomes.push(await ops.update(operation.id, { data: operation.data }));
+								break;
+							case 'upsert':
+								outcomes.push(await ops.upsert(operation.record));
+								break;
+							case 'delete':
+								outcomes.push(await ops.delete(operation.id));
+								break;
+							case 'softDelete':
+								outcomes.push(await ops.softDelete(operation.id));
+								break;
+							default:
+								break;
+						}
+					}
+					return { applied: outcomes.length, outcomes };
+				});
+			},
+
+			attachments: () => attachments,
+
+			async explain(collection: string, _query?: Query): Promise<IndexCoverageReport> {
+				assertOpen();
+				// Documented divergence: index declarations are validated but
+				// have no performance effect in memory (FR-096).
+				return {
+					collection,
+					usesIndex: false,
+					detail: 'memory adapter does not use indexes',
+				};
+			},
+
+			async close(): Promise<void> {
+				closed = true;
+			},
+		};
+
+		return handle;
+	}
+
+	/**
+	 * Backs both `deleteScopeData` and `resetScope`. They differ in intent and
+	 * in what they let a consumer conclude, not in what they do to the store —
+	 * keeping them as separate exported names is what makes the destructive one
+	 * impossible to call by accident.
+	 */
+	async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+		const scope = resolveScope(config.scope);
+		const store = existingScopeStore(config.name, scope.key);
+		if (!store) {
+			// Deleting nothing is success, not an error (FR-062).
+			return {
+				scopeKey: scope.key,
+				removedRecords: 0,
+				removedArtifacts: [],
+				orphanedReferences: [],
+				failedRemovals: [],
+			};
+		}
+		store.deletionState = 'deleting';
+		let removedRecords = 0;
+		for (const rows of store.collections.values()) {
+			removedRecords += rows.size;
+		}
+		const removedArtifacts = [...store.artifacts.keys()];
+		dropScope(config.name, scope.key);
+		return {
+			scopeKey: scope.key,
+			removedRecords,
+			removedArtifacts,
+			orphanedReferences: [],
+			failedRemovals: [],
+		};
+	}
+
+	return {
+		name: 'memory',
+		open,
+		deleteScopeData: config => removeScope(config),
+		resetScope: config => removeScope(config),
+		async deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
+			dropDatabase(config.name);
+			return {
+				removedRecords: 0,
+				removedArtifacts: [],
+				orphanedReferences: [],
+				failedRemovals: [],
+			};
+		},
+	};
+}
+
+export { Budgets } from '../../contract/config';
+export { activeFaults } from '../faults';

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

@@ -0,0 +1,119 @@
+/**
+ * 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

@@ -0,0 +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();
+	}
+}

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

@@ -0,0 +1,134 @@
+/**
+ * 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;
+}