@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/sqlite/catalog.ts

@@ -1,108 +1,105 @@
-/**
- * The catalog: one registry per logical database, listing the scopes that
- * exist.
- *
- * This is the only structure that spans scopes, so it is deliberately the
- * smallest thing that answers the questions the package must answer without
- * opening every scope file. It holds a digest, timestamps, and two posture
- * flags — **no raw scope components** (FR-014), so a device with full disk
- * access cannot mine it for identities or tenant names even though the
- * catalog itself is never encrypted.
- *
- * The `deleting` flag is the load-bearing part. It is written before a scope
- * deletion begins and cleared last, so a crash at any point leaves the
- * interruption visible on the next open. Clearing it first would make an
- * interrupted deletion look complete — the exact failure FR-063 exists to
- * prevent.
- */
-
-import type { ScopeDeletionState } from '../contract/scope';
-import type { Connection } from './connection';
-import { num, text } from './values';
-
-export type CatalogEntry = {
-	scopeKey: string;
-	createdAt: number;
-	deletionState: ScopeDeletionState;
-	backupPosture: 'excluded' | 'included';
-	encrypted: boolean;
-};
-
-const CREATE_SCOPES = `CREATE TABLE IF NOT EXISTS scopes (
-  scope_key      TEXT PRIMARY KEY,
-  created_at     INTEGER NOT NULL,
-  deletion_state TEXT NOT NULL,
-  backup_posture TEXT NOT NULL,
-  encrypted      INTEGER NOT NULL
-)`;
-
-export async function ensureCatalog(connection: Connection): Promise<void> {
-	await connection.execute(CREATE_SCOPES);
-}
-
-export async function readEntry(
-	connection: Connection,
-	scopeKey: string,
-): Promise<CatalogEntry | null> {
-	const result = await connection.execute(
-		'SELECT scope_key, created_at, deletion_state, backup_posture, encrypted FROM scopes WHERE scope_key = ?',
-		[scopeKey],
-	);
-	const row = result.rows[0];
-	if (!row) {
-		return null;
-	}
-	return {
-		scopeKey: text(row.scope_key),
-		createdAt: num(row.created_at),
-		deletionState: text(row.deletion_state) as ScopeDeletionState,
-		backupPosture: text(row.backup_posture) as 'excluded' | 'included',
-		encrypted: num(row.encrypted) === 1,
-	};
-}
-
-export async function listEntries(connection: Connection): Promise<CatalogEntry[]> {
-	const result = await connection.execute(
-		'SELECT scope_key, created_at, deletion_state, backup_posture, encrypted FROM scopes',
-	);
-	return result.rows.map(row => ({
-		scopeKey: text(row.scope_key),
-		createdAt: num(row.created_at),
-		deletionState: text(row.deletion_state) as ScopeDeletionState,
-		backupPosture: text(row.backup_posture) as 'excluded' | 'included',
-		encrypted: num(row.encrypted) === 1,
-	}));
-}
-
-export async function registerScope(
-	connection: Connection,
-	entry: CatalogEntry,
-): Promise<void> {
-	await connection.execute(
-		`INSERT INTO scopes (scope_key, created_at, deletion_state, backup_posture, encrypted)
-		 VALUES (?, ?, ?, ?, ?)
-		 ON CONFLICT(scope_key) DO UPDATE SET
-		   deletion_state = excluded.deletion_state,
-		   backup_posture = excluded.backup_posture,
-		   encrypted = excluded.encrypted`,
-		[
-			entry.scopeKey,
-			entry.createdAt,
-			entry.deletionState,
-			entry.backupPosture,
-			entry.encrypted ? 1 : 0,
-		],
-	);
-}
-
-export async function markDeleting(connection: Connection, scopeKey: string): Promise<void> {
-	await connection.execute('UPDATE scopes SET deletion_state = ? WHERE scope_key = ?', [
-		'deleting',
-		scopeKey,
-	]);
-}
-
-/** Cleared last, on purpose. See the note at the top of this file. */
-export async function clearScope(connection: Connection, scopeKey: string): Promise<void> {
-	await connection.execute('DELETE FROM scopes WHERE scope_key = ?', [scopeKey]);
-}
+/**
+ * The catalog: one registry per logical database, listing the scopes that
+ * exist.
+ *
+ * This is the only structure that spans scopes, so it is deliberately the
+ * smallest thing that answers the questions the package must answer without
+ * opening every scope file. It holds a digest, timestamps, and two posture
+ * flags — **no raw scope components** (FR-014), so a device with full disk
+ * access cannot mine it for identities or tenant names even though the
+ * catalog itself is never encrypted.
+ *
+ * The `deleting` flag is the load-bearing part. It is written before a scope
+ * deletion begins and cleared last, so a crash at any point leaves the
+ * interruption visible on the next open. Clearing it first would make an
+ * interrupted deletion look complete — the exact failure FR-063 exists to
+ * prevent.
+ */
+
+import type { ScopeDeletionState } from '../contract/scope';
+import type { Connection } from './connection';
+import { num, text } from './values';
+
+export type CatalogEntry = {
+	scopeKey: string;
+	createdAt: number;
+	deletionState: ScopeDeletionState;
+	backupPosture: 'excluded' | 'included';
+	encrypted: boolean;
+};
+
+const CREATE_SCOPES = `CREATE TABLE IF NOT EXISTS scopes (
+  scope_key      TEXT PRIMARY KEY,
+  created_at     INTEGER NOT NULL,
+  deletion_state TEXT NOT NULL,
+  backup_posture TEXT NOT NULL,
+  encrypted      INTEGER NOT NULL
+)`;
+
+export async function ensureCatalog(connection: Connection): Promise<void> {
+	await connection.execute(CREATE_SCOPES);
+}
+
+export async function readEntry(
+	connection: Connection,
+	scopeKey: string,
+): Promise<CatalogEntry | null> {
+	const result = await connection.execute(
+		'SELECT scope_key, created_at, deletion_state, backup_posture, encrypted FROM scopes WHERE scope_key = ?',
+		[scopeKey],
+	);
+	const row = result.rows[0];
+	if (!row) {
+		return null;
+	}
+	return {
+		scopeKey: text(row.scope_key),
+		createdAt: num(row.created_at),
+		deletionState: text(row.deletion_state) as ScopeDeletionState,
+		backupPosture: text(row.backup_posture) as 'excluded' | 'included',
+		encrypted: num(row.encrypted) === 1,
+	};
+}
+
+export async function listEntries(connection: Connection): Promise<CatalogEntry[]> {
+	const result = await connection.execute(
+		'SELECT scope_key, created_at, deletion_state, backup_posture, encrypted FROM scopes',
+	);
+	return result.rows.map(row => ({
+		scopeKey: text(row.scope_key),
+		createdAt: num(row.created_at),
+		deletionState: text(row.deletion_state) as ScopeDeletionState,
+		backupPosture: text(row.backup_posture) as 'excluded' | 'included',
+		encrypted: num(row.encrypted) === 1,
+	}));
+}
+
+export async function registerScope(connection: Connection, entry: CatalogEntry): Promise<void> {
+	await connection.execute(
+		`INSERT INTO scopes (scope_key, created_at, deletion_state, backup_posture, encrypted)
+		 VALUES (?, ?, ?, ?, ?)
+		 ON CONFLICT(scope_key) DO UPDATE SET
+		   deletion_state = excluded.deletion_state,
+		   backup_posture = excluded.backup_posture,
+		   encrypted = excluded.encrypted`,
+		[
+			entry.scopeKey,
+			entry.createdAt,
+			entry.deletionState,
+			entry.backupPosture,
+			entry.encrypted ? 1 : 0,
+		],
+	);
+}
+
+export async function markDeleting(connection: Connection, scopeKey: string): Promise<void> {
+	await connection.execute('UPDATE scopes SET deletion_state = ? WHERE scope_key = ?', [
+		'deleting',
+		scopeKey,
+	]);
+}
+
+/** Cleared last, on purpose. See the note at the top of this file. */
+export async function clearScope(connection: Connection, scopeKey: string): Promise<void> {
+	await connection.execute('DELETE FROM scopes WHERE scope_key = ?', [scopeKey]);
+}

package/src/sqlite/connection.ts

@@ -1,227 +1,227 @@
-/**
- * One connection per database file.
- *
- * Two things about this file carry design weight:
- *
- * **Scope isolation is the file boundary.** A connection is opened against
- * one scope's `data.db`, whose directory is named by the scope digest and
- * never by the components (FR-014). No SQL this package could generate — and
- * none a future bug could generate — reaches another scope's rows, because
- * they are in a file this connection never opened (research.md R2).
- *
- * **A transaction owns the connection while it runs, and only its own
- * executor reaches it.** Every operation queues on the connection, and a
- * transaction holds the queue until it settles. Work issued through the
- * connection meanwhile — a background sync, a second screen — waits and then
- * runs on its own, rather than joining the transaction and vanishing with its
- * rollback. Until 0.2.0 `execute` routed into whatever transaction was in
- * flight, which is how an unrelated write was lost. Work meant to be part of
- * the transaction goes through the executor the transaction hands out
- * (`tx.collection`, `tx.attachments`).
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
-import { raiseNative } from '../diagnostics/map-native';
-import { fileSystem } from '../platform/fs';
-import { createTransactionQueue } from './transaction-queue';
-import {
-	engine,
-	type ExecuteResult,
-	type NativeDatabase,
-	type NativeTransaction,
-	type SqlValue,
-} from './native';
-
-export type Executor = {
-	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
-};
-
-/**
- * The executor a transaction body runs against, plus the one control it
- * needs. `rollback` is handed to the body rather than returned from
- * `transaction`, so an explicit abort cannot outlive the transaction it
- * belongs to.
- */
-export type TransactionExecutor = Executor & {
-	rollback(): Promise<void>;
-};
-
-export type Connection = Executor & {
-	readonly path: string;
-	readonly encrypted: boolean;
-	transaction<R>(fn: (tx: TransactionExecutor) => Promise<R>): Promise<R>;
-	executeBatch(commands: [string, SqlValue[]?][]): Promise<void>;
-	/** Full-database check, for the diagnostics surface. Never run at open. */
-	integrityCheck(): Promise<boolean>;
-	close(): Promise<void>;
-};
-
-export type OpenConnectionOptions = {
-	/** Absolute path to the database file, already inside the managed area. */
-	path: string;
-	encryptionKey?: string;
-};
-
-function splitPath(path: string): { location: string; name: string } {
-	const index = path.lastIndexOf('/');
-	return index === -1
-		? { location: '', name: path }
-		: { location: path.slice(0, index), name: path.slice(index + 1) };
-}
-
-export async function openConnection(options: OpenConnectionOptions): Promise<Connection> {
-	const { location, name } = splitPath(options.path);
-	const encrypted = options.encryptionKey !== undefined;
-
-	try {
-		await fileSystem().mkdir(location);
-	} catch (error) {
-		raiseNative(error, { operation: 'open' });
-	}
-
-	let database: NativeDatabase;
-	try {
-		database = engine().open({
-			name,
-			location,
-			// Passing the key only when encryption is on keeps an unencrypted
-			// database from being opened as an encrypted one with an empty key,
-			// which SQLCipher accepts and which would produce a file neither
-			// posture can reopen.
-			...(encrypted ? { encryptionKey: options.encryptionKey } : {}),
-		});
-	} catch (error) {
-		raiseNative(error, { operation: 'open', encrypted });
-	}
-
-	let closed = false;
-	let active: NativeTransaction | null = null;
-	const queue = createTransactionQueue();
-
-	const assertOpen = (): void => {
-		if (closed) {
-			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'connection is closed' });
-		}
-	};
-
-	const classify = (sql: string) =>
-		/^\s*select|^\s*pragma|^\s*explain/i.test(sql) ? 'read' : 'write';
-
-	const connection: Connection = {
-		path: options.path,
-		encrypted,
-
-		execute(sql, params = []) {
-			assertOpen();
-			// Never into an in-flight transaction: queued behind it instead. See
-			// the note at the top of this file.
-			return queue.run(async () => {
-				try {
-					return await database.execute(sql, params);
-				} catch (error) {
-					raiseNative(error, { operation: classify(sql), encrypted });
-				}
-			});
-		},
-
-		async transaction(fn) {
-			assertOpen();
-			if (active) {
-				// Nested transactions would need savepoints and would let a
-				// partial rollback look like a full one. Refused rather than
-				// queued: a body that opened a second transaction would otherwise
-				// wait on itself forever.
-				raise(DiagnosticCodes.TRANSACTION_STATE, {
-					message: 'a transaction is already in flight on this connection',
-				});
-			}
-			return queue.runTransaction(async () => {
-				try {
-					return await database.transaction(async tx => {
-						active = tx;
-						let settled = false;
-						try {
-							return await fn({
-								execute: (sql, params = []) => {
-									if (settled) {
-										// After an explicit rollback the body is still running
-										// inside the engine's callback. Its remaining statements
-										// are refused, not run in autocommit (LDB-V1).
-										raise(DiagnosticCodes.TRANSACTION_STATE, {
-											message: 'transaction already rolled back',
-										});
-									}
-									return tx.execute(sql, params);
-								},
-								rollback: async () => {
-									await tx.rollback();
-									settled = true;
-								},
-							});
-						} finally {
-							active = null;
-						}
-					});
-				} catch (error) {
-					raiseNative(error, { operation: 'transaction', encrypted });
-				}
-			});
-		},
-
-		executeBatch(commands) {
-			assertOpen();
-			return queue.run(async () => {
-				try {
-					await database.executeBatch(commands);
-				} catch (error) {
-					raiseNative(error, { operation: 'write', encrypted });
-				}
-			});
-		},
-
-		async integrityCheck() {
-			assertOpen();
-			const result = await connection.execute('PRAGMA quick_check(1)');
-			const first = result.rows[0];
-			return first ? Object.values(first)[0] === 'ok' : false;
-		},
-
-		async close() {
-			if (closed) {
-				return;
-			}
-			closed = true;
-			try {
-				await database.close();
-			} catch {
-				// A close that fails leaves nothing for a caller to do, and
-				// reporting it would turn an orderly sign-out into an error.
-			}
-		},
-	};
-
-	// Write-ahead logging so a reader is not blocked by the writer — FR-045's
-	// "reads proceed while a write is in flight" is this pragma plus op-sqlite's
-	// single-writer serialization, not a lock this package maintains.
-	await connection.execute('PRAGMA journal_mode = WAL');
-	await connection.execute('PRAGMA foreign_keys = ON');
-	// Durability over speed: a half-written record after a crash is exactly
-	// what FR-039 promises never happens.
-	await connection.execute('PRAGMA synchronous = FULL');
-
-	return connection;
-}
-
-/**
- * Confirm a freshly opened database is readable.
- *
- * Deliberately not `PRAGMA integrity_check`: that walks the whole file and
- * would put open time far past the 150-millisecond budget on a large scope.
- * One trivial read is enough to surface the failures that matter at open —
- * a wrong key, a truncated file, a malformed header — because all three fail
- * it, and the error mapping keeps them distinguishable (FR-076, FR-078).
- */
-export async function assertReadable(connection: Connection): Promise<void> {
-	await connection.execute('SELECT count(*) AS n FROM sqlite_master');
-}
+/**
+ * One connection per database file.
+ *
+ * Two things about this file carry design weight:
+ *
+ * **Scope isolation is the file boundary.** A connection is opened against
+ * one scope's `data.db`, whose directory is named by the scope digest and
+ * never by the components (FR-014). No SQL this package could generate — and
+ * none a future bug could generate — reaches another scope's rows, because
+ * they are in a file this connection never opened (research.md R2).
+ *
+ * **A transaction owns the connection while it runs, and only its own
+ * executor reaches it.** Every operation queues on the connection, and a
+ * transaction holds the queue until it settles. Work issued through the
+ * connection meanwhile — a background sync, a second screen — waits and then
+ * runs on its own, rather than joining the transaction and vanishing with its
+ * rollback. Until 0.2.0 `execute` routed into whatever transaction was in
+ * flight, which is how an unrelated write was lost. Work meant to be part of
+ * the transaction goes through the executor the transaction hands out
+ * (`tx.collection`, `tx.attachments`).
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+import { raiseNative } from '../diagnostics/map-native';
+import { fileSystem } from '../platform/fs';
+import { createTransactionQueue } from './transaction-queue';
+import {
+	engine,
+	type ExecuteResult,
+	type NativeDatabase,
+	type NativeTransaction,
+	type SqlValue,
+} from './native';
+
+export type Executor = {
+	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+};
+
+/**
+ * The executor a transaction body runs against, plus the one control it
+ * needs. `rollback` is handed to the body rather than returned from
+ * `transaction`, so an explicit abort cannot outlive the transaction it
+ * belongs to.
+ */
+export type TransactionExecutor = Executor & {
+	rollback(): Promise<void>;
+};
+
+export type Connection = Executor & {
+	readonly path: string;
+	readonly encrypted: boolean;
+	transaction<R>(fn: (tx: TransactionExecutor) => Promise<R>): Promise<R>;
+	executeBatch(commands: [string, SqlValue[]?][]): Promise<void>;
+	/** Full-database check, for the diagnostics surface. Never run at open. */
+	integrityCheck(): Promise<boolean>;
+	close(): Promise<void>;
+};
+
+export type OpenConnectionOptions = {
+	/** Absolute path to the database file, already inside the managed area. */
+	path: string;
+	encryptionKey?: string;
+};
+
+function splitPath(path: string): { location: string; name: string } {
+	const index = path.lastIndexOf('/');
+	return index === -1
+		? { location: '', name: path }
+		: { location: path.slice(0, index), name: path.slice(index + 1) };
+}
+
+export async function openConnection(options: OpenConnectionOptions): Promise<Connection> {
+	const { location, name } = splitPath(options.path);
+	const encrypted = options.encryptionKey !== undefined;
+
+	try {
+		await fileSystem().mkdir(location);
+	} catch (error) {
+		raiseNative(error, { operation: 'open' });
+	}
+
+	let database: NativeDatabase;
+	try {
+		database = engine().open({
+			name,
+			location,
+			// Passing the key only when encryption is on keeps an unencrypted
+			// database from being opened as an encrypted one with an empty key,
+			// which SQLCipher accepts and which would produce a file neither
+			// posture can reopen.
+			...(encrypted ? { encryptionKey: options.encryptionKey } : {}),
+		});
+	} catch (error) {
+		raiseNative(error, { operation: 'open', encrypted });
+	}
+
+	let closed = false;
+	let active: NativeTransaction | null = null;
+	const queue = createTransactionQueue();
+
+	const assertOpen = (): void => {
+		if (closed) {
+			raise(DiagnosticCodes.CLOSED_HANDLE, { message: 'connection is closed' });
+		}
+	};
+
+	const classify = (sql: string) =>
+		/^\s*select|^\s*pragma|^\s*explain/i.test(sql) ? 'read' : 'write';
+
+	const connection: Connection = {
+		path: options.path,
+		encrypted,
+
+		execute(sql, params = []) {
+			assertOpen();
+			// Never into an in-flight transaction: queued behind it instead. See
+			// the note at the top of this file.
+			return queue.run(async () => {
+				try {
+					return await database.execute(sql, params);
+				} catch (error) {
+					raiseNative(error, { operation: classify(sql), encrypted });
+				}
+			});
+		},
+
+		async transaction(fn) {
+			assertOpen();
+			if (active) {
+				// Nested transactions would need savepoints and would let a
+				// partial rollback look like a full one. Refused rather than
+				// queued: a body that opened a second transaction would otherwise
+				// wait on itself forever.
+				raise(DiagnosticCodes.TRANSACTION_STATE, {
+					message: 'a transaction is already in flight on this connection',
+				});
+			}
+			return queue.runTransaction(async () => {
+				try {
+					return await database.transaction(async tx => {
+						active = tx;
+						let settled = false;
+						try {
+							return await fn({
+								execute: (sql, params = []) => {
+									if (settled) {
+										// After an explicit rollback the body is still running
+										// inside the engine's callback. Its remaining statements
+										// are refused, not run in autocommit (LDB-V1).
+										raise(DiagnosticCodes.TRANSACTION_STATE, {
+											message: 'transaction already rolled back',
+										});
+									}
+									return tx.execute(sql, params);
+								},
+								rollback: async () => {
+									await tx.rollback();
+									settled = true;
+								},
+							});
+						} finally {
+							active = null;
+						}
+					});
+				} catch (error) {
+					raiseNative(error, { operation: 'transaction', encrypted });
+				}
+			});
+		},
+
+		executeBatch(commands) {
+			assertOpen();
+			return queue.run(async () => {
+				try {
+					await database.executeBatch(commands);
+				} catch (error) {
+					raiseNative(error, { operation: 'write', encrypted });
+				}
+			});
+		},
+
+		async integrityCheck() {
+			assertOpen();
+			const result = await connection.execute('PRAGMA quick_check(1)');
+			const first = result.rows[0];
+			return first ? Object.values(first)[0] === 'ok' : false;
+		},
+
+		async close() {
+			if (closed) {
+				return;
+			}
+			closed = true;
+			try {
+				await database.close();
+			} catch {
+				// A close that fails leaves nothing for a caller to do, and
+				// reporting it would turn an orderly sign-out into an error.
+			}
+		},
+	};
+
+	// Write-ahead logging so a reader is not blocked by the writer — FR-045's
+	// "reads proceed while a write is in flight" is this pragma plus op-sqlite's
+	// single-writer serialization, not a lock this package maintains.
+	await connection.execute('PRAGMA journal_mode = WAL');
+	await connection.execute('PRAGMA foreign_keys = ON');
+	// Durability over speed: a half-written record after a crash is exactly
+	// what FR-039 promises never happens.
+	await connection.execute('PRAGMA synchronous = FULL');
+
+	return connection;
+}
+
+/**
+ * Confirm a freshly opened database is readable.
+ *
+ * Deliberately not `PRAGMA integrity_check`: that walks the whole file and
+ * would put open time far past the 150-millisecond budget on a large scope.
+ * One trivial read is enough to surface the failures that matter at open —
+ * a wrong key, a truncated file, a malformed header — because all three fail
+ * it, and the error mapping keeps them distinguishable (FR-076, FR-078).
+ */
+export async function assertReadable(connection: Connection): Promise<void> {
+	await connection.execute('SELECT count(*) AS n FROM sqlite_master');
+}