@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/index.ts

@@ -1,110 +1,80 @@
-/**
- * `@chipmobilesdk/rn-local-db`
- *
- * Offline-first, scope-isolated local storage for ChipMobileSdk apps.
- *
- * What is deliberately absent is part of the contract: there is no
- * `switchScope`, and no read, write, or query operation accepts a scope
- * argument. Scope is bound to a handle at open time and immutable, so a
- * cross-scope leak is not expressible rather than merely prevented.
- *
- * The underlying engine, the physical layout, key material, and the query
- * translation are private and unreachable by deep import.
- */
-
-// Lifecycle
-export {
-	deleteDatabase,
-	deleteScopeData,
-	openDatabase,
-	resetScope,
-} from './adapter';
-
-// Diagnostics
-export {
-	DiagnosticCodes,
-	StorageError,
-	isCode,
-	isStorageError,
-} from './diagnostics/errors';
-export { setDiagnosticLogger, type DiagnosticLogger } from './diagnostics/dev-log';
-
-// Budgets, so a consumer can check before it writes rather than after
-export { Budgets } from './contract/config';
-
-// Contract types
-export type {
-	DatabaseConfig,
-	DatabaseTargetConfig,
-	ScopeTargetConfig,
-} from './contract/config';
-export type {
-	ResolvedScope,
-	ScopeDescriptor,
-	ScopeKind,
-} from './contract/scope';
-export type {
-	CollectionSchema,
-	FieldDeclaration,
-	FieldType,
-	IndexDeclaration,
-} from './contract/schema';
-export type {
-	RecordInput,
-	StorableRecordData,
-	StorableValue,
-	StoredRecord,
-	WriteOperation,
-	WriteOutcome,
-} from './contract/record';
-export type {
-	ComparisonNode,
-	FilterNode,
-	FilterValue,
-	IndexCoverageReport,
-	LogicalNode,
-	PageRequest,
-	Query,
-	ResultPage,
-	SortDirection,
-	SortKey,
-} from './contract/query';
-export type {
-	BatchOperation,
-	BatchOutcome,
-	CollectionOps,
-	Transaction,
-} from './contract/transaction';
-export type {
-	Migration,
-	MigrationContext,
-	MigrationFailureDetail,
-	MigrationLedgerEntry,
-	MigrationOutcome,
-} from './contract/migration';
-export type {
-	AttachmentAvailability,
-	AttachmentAvailabilityState,
-	AttachmentInput,
-	AttachmentOwner,
-	AttachmentReference,
-	ByteRange,
-	DeletionOutcome,
-	ReconciliationReport,
-} from './contract/attachment';
-export type {
-	EncryptionConfig,
-	EncryptionPosture,
-	KeyProvider,
-} from './contract/encryption';
-export type {
-	BackupConfig,
-	BackupPostureValue,
-	EffectivePosture,
-} from './contract/backup';
-export type { DiagnosticCode } from './contract/errors';
-export type {
-	Attachments,
-	DatabaseHandle,
-	StorageAdapter,
-} from './contract/adapter';
+/**
+ * `@chipmobilesdk/rn-local-db`
+ *
+ * Offline-first, scope-isolated local storage for ChipMobileSdk apps.
+ *
+ * What is deliberately absent is part of the contract: there is no
+ * `switchScope`, and no read, write, or query operation accepts a scope
+ * argument. Scope is bound to a handle at open time and immutable, so a
+ * cross-scope leak is not expressible rather than merely prevented.
+ *
+ * The underlying engine, the physical layout, key material, and the query
+ * translation are private and unreachable by deep import.
+ */
+
+// Lifecycle
+export { deleteDatabase, deleteScopeData, openDatabase, resetScope } from './adapter';
+
+// Diagnostics
+export { DiagnosticCodes, StorageError, isCode, isStorageError } from './diagnostics/errors';
+export { setDiagnosticLogger, type DiagnosticLogger } from './diagnostics/dev-log';
+
+// Budgets, so a consumer can check before it writes rather than after
+export { Budgets } from './contract/config';
+
+// Contract types
+export type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } from './contract/config';
+export type { ResolvedScope, ScopeDescriptor, ScopeKind } from './contract/scope';
+export type {
+	CollectionSchema,
+	FieldDeclaration,
+	FieldType,
+	IndexDeclaration,
+} from './contract/schema';
+export type {
+	RecordInput,
+	StorableRecordData,
+	StorableValue,
+	StoredRecord,
+	WriteOperation,
+	WriteOutcome,
+} from './contract/record';
+export type {
+	ComparisonNode,
+	FilterNode,
+	FilterValue,
+	IndexCoverageReport,
+	LogicalNode,
+	PageRequest,
+	Query,
+	ResultPage,
+	SortDirection,
+	SortKey,
+} from './contract/query';
+export type {
+	BatchOperation,
+	BatchOutcome,
+	CollectionOps,
+	Transaction,
+} from './contract/transaction';
+export type {
+	Migration,
+	MigrationContext,
+	MigrationFailureDetail,
+	MigrationLedgerEntry,
+	MigrationOutcome,
+} from './contract/migration';
+export type {
+	AttachmentAvailability,
+	AttachmentAvailabilityState,
+	AttachmentInput,
+	AttachmentOwner,
+	AttachmentReference,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from './contract/attachment';
+export type { EncryptionConfig, EncryptionPosture, KeyProvider } from './contract/encryption';
+export type { BackupConfig, BackupPostureValue, EffectivePosture } from './contract/backup';
+export type { DiagnosticCode } from './contract/errors';
+export type { Attachments, DatabaseHandle, StorageAdapter } from './contract/adapter';

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