@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/migration/executor.ts

@@ -1,136 +1,132 @@
-/**
- * The migration executor.
- *
- * Four rules, each of which exists because the alternative loses data:
- *
- * - **Ascending, and pending only.** A migration whose version is at or below
- *   the recorded one has already run against this scope (FR-047, FR-049).
- * - **One transaction per migration.** A failure unwinds that migration and
- *   nothing else, so the recorded version and the data always agree.
- * - **The recorded version moves only on success**, inside the same
- *   transaction as the migration's own writes. Writing it separately would
- *   leave a window where a crash records a migration that did not happen.
- * - **A failure returns no handle** (FR-050). Half-migrated data behind a
- *   working handle is the failure this whole design exists to prevent, and it
- *   is worse than being unable to open at all: the app writes to it.
- *
- * A retry starts from the same version rather than skipping ahead (FR-051),
- * which is what makes a transient failure — a locked keychain, a full disk
- * mid-migration — recoverable on the next launch instead of permanent.
- */
-
-import type { DatabaseConfig } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import type { MigrationContext } from '../contract/migration';
-import type { StorableRecordData } 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 { createSqlCollection } from '../adapter/collection';
-import type { Connection, Executor } from '../sqlite/connection';
-import { ensureLedger, readSchemaVersion, recordAttempt, writeSchemaVersion } from './ledger';
-import { pendingMigrations, validateMigrationChain } from './validate-chain';
-
-export type MigrationRunContext = {
-	connection: Connection;
-	config: DatabaseConfig;
-	schemaFor(name: string): CollectionSchema;
-	now(): number;
-	/**
-	 * Called before a migration failure is raised. The executor does not own
-	 * the connection, so it asks rather than closing directly — but the close
-	 * has to happen before the error escapes, or a caller catching it could
-	 * still be holding something usable (FR-050).
-	 */
-	closeOnFailure(): Promise<void>;
-};
-
-function migrationContextFor(
-	context: MigrationRunContext,
-	executor: Executor,
-): MigrationContext {
-	return {
-		collection<T extends StorableRecordData>(name: string): CollectionOps<T> {
-			return createSqlCollection<T>({
-				executor: () => executor,
-				schema: context.schemaFor(name),
-				now: context.now,
-				// Inside a migration the handle does not exist yet, so there is
-				// no closed-handle or deleted-scope state to guard against.
-				assertUsable: () => {},
-			});
-		},
-		async abort(): Promise<void> {
-			// A migration that wants to give up should throw; aborting the
-			// transaction from inside while the executor still believes it is
-			// running would record an outcome that never happened.
-			raise(DiagnosticCodes.TRANSACTION_STATE, {
-				message: 'a migration cannot abort its own transaction',
-			});
-		},
-		async execute(sql: string, params?: unknown[]): Promise<void> {
-			await executor.execute(sql, params as never);
-		},
-	};
-}
-
-export async function runMigrations(context: MigrationRunContext): Promise<number> {
-	const { config, connection } = context;
-	validateMigrationChain(config);
-	await ensureLedger(connection);
-
-	const recorded = await readSchemaVersion(connection);
-
-	if (recorded > config.schemaVersion) {
-		// Opening anyway would mean newer data read by older code, which drops
-		// whatever the newer schema added — silently, and on write (FR-052).
-		await context.closeOnFailure();
-		raise(DiagnosticCodes.SCHEMA_DOWNGRADE, {
-			message: 'recorded schema version is newer than the declared one',
-			detail: { recordedVersion: recorded, version: config.schemaVersion },
-		});
-	}
-
-	let current = recorded;
-
-	for (const migration of pendingMigrations(config, recorded)) {
-		try {
-			await connection.transaction(async tx => {
-				throwIfFaulted('migration');
-				await migration.migrate(migrationContextFor(context, tx));
-				await writeSchemaVersion(tx, migration.version);
-				await recordAttempt(tx, {
-					version: migration.version,
-					attemptedAt: context.now(),
-					outcome: 'applied',
-				});
-			});
-			current = migration.version;
-		} catch (error) {
-			// Recorded outside the rolled-back transaction, or it would vanish
-			// with the migration it describes.
-			await recordAttempt(connection, {
-				version: migration.version,
-				attemptedAt: context.now(),
-				outcome: 'failed',
-				failureCode:
-					(error as { code?: string }).code ?? DiagnosticCodes.MIGRATION_FAILED,
-			});
-			await context.closeOnFailure();
-			raise(DiagnosticCodes.MIGRATION_FAILED, {
-				message: 'migration failed',
-				migration: {
-					// Unchanged: the next open retries from here rather than
-					// skipping the migration that failed.
-					recordedVersion: current,
-					failingVersion: migration.version,
-					outcome: 'failed',
-				},
-				cause: error,
-			});
-		}
-	}
-
-	return current;
-}
+/**
+ * The migration executor.
+ *
+ * Four rules, each of which exists because the alternative loses data:
+ *
+ * - **Ascending, and pending only.** A migration whose version is at or below
+ *   the recorded one has already run against this scope (FR-047, FR-049).
+ * - **One transaction per migration.** A failure unwinds that migration and
+ *   nothing else, so the recorded version and the data always agree.
+ * - **The recorded version moves only on success**, inside the same
+ *   transaction as the migration's own writes. Writing it separately would
+ *   leave a window where a crash records a migration that did not happen.
+ * - **A failure returns no handle** (FR-050). Half-migrated data behind a
+ *   working handle is the failure this whole design exists to prevent, and it
+ *   is worse than being unable to open at all: the app writes to it.
+ *
+ * A retry starts from the same version rather than skipping ahead (FR-051),
+ * which is what makes a transient failure — a locked keychain, a full disk
+ * mid-migration — recoverable on the next launch instead of permanent.
+ */
+
+import type { DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { MigrationContext } from '../contract/migration';
+import type { StorableRecordData } 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 { createSqlCollection } from '../adapter/collection';
+import type { Connection, Executor } from '../sqlite/connection';
+import { ensureLedger, readSchemaVersion, recordAttempt, writeSchemaVersion } from './ledger';
+import { pendingMigrations, validateMigrationChain } from './validate-chain';
+
+export type MigrationRunContext = {
+	connection: Connection;
+	config: DatabaseConfig;
+	schemaFor(name: string): CollectionSchema;
+	now(): number;
+	/**
+	 * Called before a migration failure is raised. The executor does not own
+	 * the connection, so it asks rather than closing directly — but the close
+	 * has to happen before the error escapes, or a caller catching it could
+	 * still be holding something usable (FR-050).
+	 */
+	closeOnFailure(): Promise<void>;
+};
+
+function migrationContextFor(context: MigrationRunContext, executor: Executor): MigrationContext {
+	return {
+		collection<T extends StorableRecordData>(name: string): CollectionOps<T> {
+			return createSqlCollection<T>({
+				executor: () => executor,
+				schema: context.schemaFor(name),
+				now: context.now,
+				// Inside a migration the handle does not exist yet, so there is
+				// no closed-handle or deleted-scope state to guard against.
+				assertUsable: () => {},
+			});
+		},
+		async abort(): Promise<void> {
+			// A migration that wants to give up should throw; aborting the
+			// transaction from inside while the executor still believes it is
+			// running would record an outcome that never happened.
+			raise(DiagnosticCodes.TRANSACTION_STATE, {
+				message: 'a migration cannot abort its own transaction',
+			});
+		},
+		async execute(sql: string, params?: unknown[]): Promise<void> {
+			await executor.execute(sql, params as never);
+		},
+	};
+}
+
+export async function runMigrations(context: MigrationRunContext): Promise<number> {
+	const { config, connection } = context;
+	validateMigrationChain(config);
+	await ensureLedger(connection);
+
+	const recorded = await readSchemaVersion(connection);
+
+	if (recorded > config.schemaVersion) {
+		// Opening anyway would mean newer data read by older code, which drops
+		// whatever the newer schema added — silently, and on write (FR-052).
+		await context.closeOnFailure();
+		raise(DiagnosticCodes.SCHEMA_DOWNGRADE, {
+			message: 'recorded schema version is newer than the declared one',
+			detail: { recordedVersion: recorded, version: config.schemaVersion },
+		});
+	}
+
+	let current = recorded;
+
+	for (const migration of pendingMigrations(config, recorded)) {
+		try {
+			await connection.transaction(async tx => {
+				throwIfFaulted('migration');
+				await migration.migrate(migrationContextFor(context, tx));
+				await writeSchemaVersion(tx, migration.version);
+				await recordAttempt(tx, {
+					version: migration.version,
+					attemptedAt: context.now(),
+					outcome: 'applied',
+				});
+			});
+			current = migration.version;
+		} catch (error) {
+			// Recorded outside the rolled-back transaction, or it would vanish
+			// with the migration it describes.
+			await recordAttempt(connection, {
+				version: migration.version,
+				attemptedAt: context.now(),
+				outcome: 'failed',
+				failureCode: (error as { code?: string }).code ?? DiagnosticCodes.MIGRATION_FAILED,
+			});
+			await context.closeOnFailure();
+			raise(DiagnosticCodes.MIGRATION_FAILED, {
+				message: 'migration failed',
+				migration: {
+					// Unchanged: the next open retries from here rather than
+					// skipping the migration that failed.
+					recordedVersion: current,
+					failingVersion: migration.version,
+					outcome: 'failed',
+				},
+				cause: error,
+			});
+		}
+	}
+
+	return current;
+}

package/src/migration/ledger.ts

@@ -1,97 +1,95 @@
-/**
- * The per-scope migration ledger.
- *
- * Per scope, not per database, and that is the whole reason FR-054 works: a
- * scope created after a migration shipped starts at version 0 and is migrated
- * on first open, rather than being assumed current because some other scope
- * already ran the chain.
- *
- * The ledger records a **code**, never a message (FR-079). A migration that
- * failed because a domain constraint was violated could otherwise write the
- * offending value into a table that outlives the failure — a payload leak
- * with a long half-life, sitting in a file the next crash report might carry.
- */
-
-import type { MigrationLedgerEntry, MigrationOutcome } from '../contract/migration';
-import type { Executor } from '../sqlite/connection';
-import { maybeText, num, text } from '../sqlite/values';
-
-/** Physical layout version, independent of the app's schema version. */
-export const FORMAT_VERSION = 1;
-
-const CREATE_META = `CREATE TABLE IF NOT EXISTS _meta (
-  key   TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-)`;
-
-const CREATE_MIGRATIONS = `CREATE TABLE IF NOT EXISTS _migrations (
-  version      INTEGER PRIMARY KEY,
-  attempted_at INTEGER NOT NULL,
-  outcome      TEXT NOT NULL,
-  failure_code TEXT
-)`;
-
-export async function ensureLedger(executor: Executor): Promise<void> {
-	await executor.execute(CREATE_META);
-	await executor.execute(CREATE_MIGRATIONS);
-	await executor.execute(
-		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING',
-		['format_version', String(FORMAT_VERSION)],
-	);
-	await executor.execute(
-		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING',
-		['schema_version', '0'],
-	);
-}
-
-async function readMeta(executor: Executor, key: string): Promise<string | null> {
-	const result = await executor.execute('SELECT value FROM _meta WHERE key = ?', [key]);
-	const row = result.rows[0];
-	return row ? text(row.value) : null;
-}
-
-export async function readSchemaVersion(executor: Executor): Promise<number> {
-	const raw = await readMeta(executor, 'schema_version');
-	return raw === null ? 0 : Number(raw);
-}
-
-export async function readFormatVersion(executor: Executor): Promise<number> {
-	const raw = await readMeta(executor, 'format_version');
-	return raw === null ? FORMAT_VERSION : Number(raw);
-}
-
-export async function writeSchemaVersion(executor: Executor, version: number): Promise<void> {
-	await executor.execute(
-		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
-		['schema_version', String(version)],
-	);
-}
-
-export async function recordAttempt(
-	executor: Executor,
-	entry: { version: number; attemptedAt: number; outcome: MigrationOutcome; failureCode?: string },
-): Promise<void> {
-	await executor.execute(
-		`INSERT INTO _migrations (version, attempted_at, outcome, failure_code)
-		 VALUES (?, ?, ?, ?)
-		 ON CONFLICT(version) DO UPDATE SET
-		   attempted_at = excluded.attempted_at,
-		   outcome = excluded.outcome,
-		   failure_code = excluded.failure_code`,
-		[entry.version, entry.attemptedAt, entry.outcome, entry.failureCode ?? null],
-	);
-}
-
-export async function readLedger(executor: Executor): Promise<MigrationLedgerEntry[]> {
-	const result = await executor.execute(
-		'SELECT version, attempted_at, outcome, failure_code FROM _migrations ORDER BY version ASC',
-	);
-	return result.rows.map(row => ({
-		version: num(row.version),
-		attemptedAt: num(row.attempted_at),
-		outcome: text(row.outcome) as MigrationOutcome,
-		...(maybeText(row.failure_code) === null
-			? {}
-			: { failureCode: text(row.failure_code) }),
-	}));
-}
+/**
+ * The per-scope migration ledger.
+ *
+ * Per scope, not per database, and that is the whole reason FR-054 works: a
+ * scope created after a migration shipped starts at version 0 and is migrated
+ * on first open, rather than being assumed current because some other scope
+ * already ran the chain.
+ *
+ * The ledger records a **code**, never a message (FR-079). A migration that
+ * failed because a domain constraint was violated could otherwise write the
+ * offending value into a table that outlives the failure — a payload leak
+ * with a long half-life, sitting in a file the next crash report might carry.
+ */
+
+import type { MigrationLedgerEntry, MigrationOutcome } from '../contract/migration';
+import type { Executor } from '../sqlite/connection';
+import { maybeText, num, text } from '../sqlite/values';
+
+/** Physical layout version, independent of the app's schema version. */
+export const FORMAT_VERSION = 1;
+
+const CREATE_META = `CREATE TABLE IF NOT EXISTS _meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+)`;
+
+const CREATE_MIGRATIONS = `CREATE TABLE IF NOT EXISTS _migrations (
+  version      INTEGER PRIMARY KEY,
+  attempted_at INTEGER NOT NULL,
+  outcome      TEXT NOT NULL,
+  failure_code TEXT
+)`;
+
+export async function ensureLedger(executor: Executor): Promise<void> {
+	await executor.execute(CREATE_META);
+	await executor.execute(CREATE_MIGRATIONS);
+	await executor.execute(
+		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING',
+		['format_version', String(FORMAT_VERSION)],
+	);
+	await executor.execute(
+		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING',
+		['schema_version', '0'],
+	);
+}
+
+async function readMeta(executor: Executor, key: string): Promise<string | null> {
+	const result = await executor.execute('SELECT value FROM _meta WHERE key = ?', [key]);
+	const row = result.rows[0];
+	return row ? text(row.value) : null;
+}
+
+export async function readSchemaVersion(executor: Executor): Promise<number> {
+	const raw = await readMeta(executor, 'schema_version');
+	return raw === null ? 0 : Number(raw);
+}
+
+export async function readFormatVersion(executor: Executor): Promise<number> {
+	const raw = await readMeta(executor, 'format_version');
+	return raw === null ? FORMAT_VERSION : Number(raw);
+}
+
+export async function writeSchemaVersion(executor: Executor, version: number): Promise<void> {
+	await executor.execute(
+		'INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value',
+		['schema_version', String(version)],
+	);
+}
+
+export async function recordAttempt(
+	executor: Executor,
+	entry: { version: number; attemptedAt: number; outcome: MigrationOutcome; failureCode?: string },
+): Promise<void> {
+	await executor.execute(
+		`INSERT INTO _migrations (version, attempted_at, outcome, failure_code)
+		 VALUES (?, ?, ?, ?)
+		 ON CONFLICT(version) DO UPDATE SET
+		   attempted_at = excluded.attempted_at,
+		   outcome = excluded.outcome,
+		   failure_code = excluded.failure_code`,
+		[entry.version, entry.attemptedAt, entry.outcome, entry.failureCode ?? null],
+	);
+}
+
+export async function readLedger(executor: Executor): Promise<MigrationLedgerEntry[]> {
+	const result = await executor.execute(
+		'SELECT version, attempted_at, outcome, failure_code FROM _migrations ORDER BY version ASC',
+	);
+	return result.rows.map(row => ({
+		version: num(row.version),
+		attemptedAt: num(row.attempted_at),
+		outcome: text(row.outcome) as MigrationOutcome,
+		...(maybeText(row.failure_code) === null ? {} : { failureCode: text(row.failure_code) }),
+	}));
+}

package/src/migration/validate-chain.ts

@@ -1,65 +1,65 @@
-/**
- * Migration chain validation, run before any migration executes (FR-053).
- *
- * Validating first is what stops a half-run chain from being the thing that
- * discovers the problem. A duplicate version, a gap, or a chain that does not
- * reach the declared `schemaVersion` are all configuration errors the
- * developer can fix; discovering them after migration 3 of 5 has already
- * rewritten a user's data is not.
- *
- * A gap is refused rather than skipped over deliberately. A user upgrading
- * from the version inside the gap has no path across it, and opening anyway
- * would hand them a database the code believes is current and is not.
- */
-
-import type { DatabaseConfig } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import type { Migration } from '../contract/migration';
-import { raise } from '../diagnostics/errors';
-
-function invalid(message: string, detail?: Record<string, unknown>): never {
-	raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, { message, detail });
-}
-
-export function validateMigrationChain(config: DatabaseConfig): void {
-	const migrations = config.migrations ?? [];
-
-	if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
-		invalid('schemaVersion must be a positive integer');
-	}
-
-	const versions = new Set<number>();
-	for (const migration of migrations) {
-		if (!Number.isInteger(migration.version) || migration.version < 1) {
-			invalid('migration version must be a positive integer');
-		}
-		if (versions.has(migration.version)) {
-			invalid('duplicate migration version', { version: migration.version });
-		}
-		versions.add(migration.version);
-		if (typeof migration.migrate !== 'function') {
-			invalid('migration has no migrate function', { version: migration.version });
-		}
-	}
-
-	for (let version = 1; version <= config.schemaVersion; version += 1) {
-		if (!versions.has(version)) {
-			invalid('migration chain has a gap', { version });
-		}
-	}
-
-	for (const version of versions) {
-		if (version > config.schemaVersion) {
-			invalid('migration version exceeds the declared schemaVersion', { version });
-		}
-	}
-}
-
-/** Ascending, because the order a consumer declared them in is not a contract. */
-export function orderedMigrations(config: DatabaseConfig): Migration[] {
-	return [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
-}
-
-export function pendingMigrations(config: DatabaseConfig, recordedVersion: number): Migration[] {
-	return orderedMigrations(config).filter(migration => migration.version > recordedVersion);
-}
+/**
+ * Migration chain validation, run before any migration executes (FR-053).
+ *
+ * Validating first is what stops a half-run chain from being the thing that
+ * discovers the problem. A duplicate version, a gap, or a chain that does not
+ * reach the declared `schemaVersion` are all configuration errors the
+ * developer can fix; discovering them after migration 3 of 5 has already
+ * rewritten a user's data is not.
+ *
+ * A gap is refused rather than skipped over deliberately. A user upgrading
+ * from the version inside the gap has no path across it, and opening anyway
+ * would hand them a database the code believes is current and is not.
+ */
+
+import type { DatabaseConfig } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { Migration } from '../contract/migration';
+import { raise } from '../diagnostics/errors';
+
+function invalid(message: string, detail?: Record<string, unknown>): never {
+	raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, { message, detail });
+}
+
+export function validateMigrationChain(config: DatabaseConfig): void {
+	const migrations = config.migrations ?? [];
+
+	if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
+		invalid('schemaVersion must be a positive integer');
+	}
+
+	const versions = new Set<number>();
+	for (const migration of migrations) {
+		if (!Number.isInteger(migration.version) || migration.version < 1) {
+			invalid('migration version must be a positive integer');
+		}
+		if (versions.has(migration.version)) {
+			invalid('duplicate migration version', { version: migration.version });
+		}
+		versions.add(migration.version);
+		if (typeof migration.migrate !== 'function') {
+			invalid('migration has no migrate function', { version: migration.version });
+		}
+	}
+
+	for (let version = 1; version <= config.schemaVersion; version += 1) {
+		if (!versions.has(version)) {
+			invalid('migration chain has a gap', { version });
+		}
+	}
+
+	for (const version of versions) {
+		if (version > config.schemaVersion) {
+			invalid('migration version exceeds the declared schemaVersion', { version });
+		}
+	}
+}
+
+/** Ascending, because the order a consumer declared them in is not a contract. */
+export function orderedMigrations(config: DatabaseConfig): Migration[] {
+	return [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
+}
+
+export function pendingMigrations(config: DatabaseConfig, recordedVersion: number): Migration[] {
+	return orderedMigrations(config).filter(migration => migration.version > recordedVersion);
+}