@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/adapter/deletion.ts

@@ -1,252 +1,252 @@
-/**
- * Deletion, and the ordering that makes an interrupted one visible.
- *
- * These are module-level functions rather than handle methods because they
- * must work whether or not a handle is open on the target (FR-059) — a
- * sign-out that already closed the handle still has to be able to delete, and
- * an app recovering from a crash has no handle to call a method on.
- *
- * The order is: **mark `deleting` first, clear the catalog row last**
- * (FR-061, FR-063). A crash at any point in between leaves the flag set, so
- * the next open reports a scope mid-deletion rather than presenting it as
- * complete. Clearing the row first would be the natural way to write this and
- * would produce exactly the failure FR-063 exists to prevent: an
- * interruption that looks like a success, leaving a user's data on disk after
- * they asked for it to be gone.
- *
- * Nothing here ever runs on its own. No expiry, no sweep, no deletion on
- * close or on app upgrade (FR-058) — the package deletes when asked, where
- * asked, and not otherwise.
- */
-
-import type { DeletionOutcome } from '../contract/attachment';
-import type { DatabaseTargetConfig, ScopeTargetConfig } from '../contract/config';
-import type { ResolvedScope } from '../contract/scope';
-import { fileSystem, removeIfPresent } from '../platform/fs';
-import { layoutFor, type StorageLayout } from '../platform/location';
-import { artifactsDirectory } from '../artifacts/paths';
-import { acquireKey } from '../crypto/key-provider';
-import { byteOrder } from '../query/compare';
-import { resolveScope } from '../scope/validate';
-import { clearScope, ensureCatalog, listEntries, markDeleting, readEntry } from '../sqlite/catalog';
-import { openConnection, type Connection } from '../sqlite/connection';
-import { num, text } from '../sqlite/values';
-
-/**
- * Scopes deleted beneath a handle that is still open.
- *
- * FR-059a wants the handle to report `SCOPE_DELETED` rather than keep
- * answering from a database that no longer exists — and wants the deletion to
- * proceed rather than wait for the handle to be closed. A shared set is the
- * whole mechanism: the deleter records, the handle checks.
- */
-const invalidated = new Set<string>();
-
-function invalidationKey(name: string, scopeKey: string): string {
-	return `${name}:${scopeKey}`;
-}
-
-export function markScopeInvalidated(name: string, scopeKey: string): void {
-	invalidated.add(invalidationKey(name, scopeKey));
-}
-
-export function clearScopeInvalidation(name: string, scopeKey: string): void {
-	invalidated.delete(invalidationKey(name, scopeKey));
-}
-
-export function isScopeInvalidated(name: string, scopeKey: string): boolean {
-	return invalidated.has(invalidationKey(name, scopeKey));
-}
-
-export function clearAllInvalidations(): void {
-	invalidated.clear();
-}
-
-/** Deleting a scope that holds nothing is success, not an error (FR-062). */
-export function emptyOutcome(scope?: ResolvedScope): DeletionOutcome {
-	return {
-		...(scope ? { scopeKey: scope.key } : {}),
-		removedRecords: 0,
-		removedArtifacts: [],
-		orphanedReferences: [],
-		failedRemovals: [],
-	};
-}
-
-/**
- * How many records the scope held, best effort.
- *
- * Best effort because an encrypted scope whose caller supplied no key cannot
- * be opened to be counted — and refusing to delete it on that basis would be
- * the worst possible answer to a deletion request. The files come off disk
- * either way; only the number in the report is unavailable.
- */
-async function countRecords(
-	layout: StorageLayout,
-	scopeKey: string,
-	encryptionKey: string | undefined,
-): Promise<number | undefined> {
-	let connection: Connection | null = null;
-	try {
-		connection = await openConnection({
-			path: layout.scopeDataPath(scopeKey),
-			...(encryptionKey ? { encryptionKey } : {}),
-		});
-		const tables = await connection.execute(
-			"SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'c!_%' ESCAPE '!'",
-		);
-		let total = 0;
-		for (const row of tables.rows) {
-			const table = text(row.name);
-			const counted = await connection.execute(`SELECT count(*) AS total FROM "${table}"`);
-			total += num(counted.rows[0]?.total ?? 0);
-		}
-		return total;
-	} catch {
-		// Unknown, not zero: a report that said "0 records" about a scope it
-		// could not open would understate what was deleted.
-		return undefined;
-	} finally {
-		await connection?.close();
-	}
-}
-
-async function artifactIdsOnDisk(layout: StorageLayout, scopeKey: string): Promise<string[]> {
-	try {
-		return (await fileSystem().readdir(artifactsDirectory(layout, scopeKey))).sort(byteOrder);
-	} catch {
-		return [];
-	}
-}
-
-/**
- * The one implementation behind `deleteScopeData` and `resetScope`.
- *
- * They do the same thing to disk and mean entirely different things to the
- * caller: one is a lifecycle operation an app performs on request, the other
- * is an admission that a database is broken and is being discarded to recover
- * from it (FR-057a). Keeping them as two exported names with two docstrings
- * is what stops the destructive one from being reached by accident — there is
- * no path from `openDatabase` to either.
- */
-async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
-	const scope = resolveScope(config.scope);
-	const layout = layoutFor(config.name);
-	const catalog = await openConnection({ path: layout.catalogPath });
-
-	try {
-		await ensureCatalog(catalog);
-		const entry = await readEntry(catalog, scope.key);
-
-		// Mark first. Everything after this point is recoverable-in-principle;
-		// this flag is what makes an interruption visible rather than silent.
-		if (entry) {
-			await markDeleting(catalog, scope.key);
-		}
-		markScopeInvalidated(config.name, scope.key);
-
-		const removedArtifacts = await artifactIdsOnDisk(layout, scope.key);
-
-		// The key is needed to count what is being removed, not to remove it,
-		// so a key provider that fails — or a key already destroyed for this
-		// identity, which FR-104 encourages — costs the count, never the
-		// deletion. Until 0.2.0 it failed the whole call after the scope was
-		// already marked, leaving it stuck in `deleting`.
-		let keyHandle: Awaited<ReturnType<typeof acquireKey>> | null = null;
-		if (config.encryption?.enabled) {
-			try {
-				keyHandle = await acquireKey(config.encryption, scope);
-			} catch {
-				keyHandle = null;
-			}
-		}
-		let counted: number | undefined;
-		try {
-			counted =
-				config.encryption?.enabled && keyHandle === null
-					? undefined
-					: await countRecords(layout, scope.key, keyHandle?.value());
-		} finally {
-			keyHandle?.release();
-		}
-
-		const failedRemovals: string[] = [];
-		if (!(await removeIfPresent(layout.scopePath(scope.key))) && entry) {
-			// The directory was there and would not go. Reporting it is the
-			// point: an app that told the user "deleted" would be wrong.
-			const stillThere = await fileSystem()
-				.exists(layout.scopePath(scope.key))
-				.catch(() => false);
-			if (stillThere) {
-				failedRemovals.push(scope.key);
-			}
-		}
-
-		if (failedRemovals.length === 0) {
-			// Cleared last, on purpose.
-			await clearScope(catalog, scope.key);
-		}
-
-		return {
-			scopeKey: scope.key,
-			removedRecords: counted ?? 0,
-			...(counted === undefined ? { recordCountUnavailable: true } : {}),
-			removedArtifacts,
-			orphanedReferences: [],
-			failedRemovals,
-		};
-	} finally {
-		await catalog.close();
-	}
-}
-
-/**
- * Remove one scope's data. Every collection in that scope, and nothing
- * outside it (FR-059, SC-012).
- */
-export function deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome> {
-	return removeScope(config);
-}
-
-/**
- * Discard one scope and leave it ready for a clean first-run migration
- * (FR-057a).
- *
- * Destructive, separately named, and never reachable from `openDatabase`. An
- * automatic fallback here would turn a bad migration shipped to production
- * into silent data loss for every user who launched the app.
- */
-export function resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
-	return removeScope(config);
-}
-
-/** Remove the whole database directory: catalog, every scope, every artifact. */
-export async function deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
-	const layout = layoutFor(config.name);
-
-	let scopeKeys: string[] = [];
-	try {
-		const catalog = await openConnection({ path: layout.catalogPath });
-		try {
-			await ensureCatalog(catalog);
-			scopeKeys = (await listEntries(catalog)).map(entry => entry.scopeKey);
-		} finally {
-			await catalog.close();
-		}
-	} catch {
-		// No catalog means nothing was ever registered here. The directory
-		// removal below is still the right thing to attempt.
-	}
-
-	for (const scopeKey of scopeKeys) {
-		markScopeInvalidated(config.name, scopeKey);
-	}
-
-	const removed = await removeIfPresent(layout.root);
-	return {
-		removedRecords: 0,
-		removedArtifacts: [],
-		orphanedReferences: [],
-		failedRemovals: removed || scopeKeys.length === 0 ? [] : scopeKeys,
-	};
-}
+/**
+ * Deletion, and the ordering that makes an interrupted one visible.
+ *
+ * These are module-level functions rather than handle methods because they
+ * must work whether or not a handle is open on the target (FR-059) — a
+ * sign-out that already closed the handle still has to be able to delete, and
+ * an app recovering from a crash has no handle to call a method on.
+ *
+ * The order is: **mark `deleting` first, clear the catalog row last**
+ * (FR-061, FR-063). A crash at any point in between leaves the flag set, so
+ * the next open reports a scope mid-deletion rather than presenting it as
+ * complete. Clearing the row first would be the natural way to write this and
+ * would produce exactly the failure FR-063 exists to prevent: an
+ * interruption that looks like a success, leaving a user's data on disk after
+ * they asked for it to be gone.
+ *
+ * Nothing here ever runs on its own. No expiry, no sweep, no deletion on
+ * close or on app upgrade (FR-058) — the package deletes when asked, where
+ * asked, and not otherwise.
+ */
+
+import type { DeletionOutcome } from '../contract/attachment';
+import type { DatabaseTargetConfig, ScopeTargetConfig } from '../contract/config';
+import type { ResolvedScope } from '../contract/scope';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import { layoutFor, type StorageLayout } from '../platform/location';
+import { artifactsDirectory } from '../artifacts/paths';
+import { acquireKey } from '../crypto/key-provider';
+import { byteOrder } from '../query/compare';
+import { resolveScope } from '../scope/validate';
+import { clearScope, ensureCatalog, listEntries, markDeleting, readEntry } from '../sqlite/catalog';
+import { openConnection, type Connection } from '../sqlite/connection';
+import { num, text } from '../sqlite/values';
+
+/**
+ * Scopes deleted beneath a handle that is still open.
+ *
+ * FR-059a wants the handle to report `SCOPE_DELETED` rather than keep
+ * answering from a database that no longer exists — and wants the deletion to
+ * proceed rather than wait for the handle to be closed. A shared set is the
+ * whole mechanism: the deleter records, the handle checks.
+ */
+const invalidated = new Set<string>();
+
+function invalidationKey(name: string, scopeKey: string): string {
+	return `${name}:${scopeKey}`;
+}
+
+export function markScopeInvalidated(name: string, scopeKey: string): void {
+	invalidated.add(invalidationKey(name, scopeKey));
+}
+
+export function clearScopeInvalidation(name: string, scopeKey: string): void {
+	invalidated.delete(invalidationKey(name, scopeKey));
+}
+
+export function isScopeInvalidated(name: string, scopeKey: string): boolean {
+	return invalidated.has(invalidationKey(name, scopeKey));
+}
+
+export function clearAllInvalidations(): void {
+	invalidated.clear();
+}
+
+/** Deleting a scope that holds nothing is success, not an error (FR-062). */
+export function emptyOutcome(scope?: ResolvedScope): DeletionOutcome {
+	return {
+		...(scope ? { scopeKey: scope.key } : {}),
+		removedRecords: 0,
+		removedArtifacts: [],
+		orphanedReferences: [],
+		failedRemovals: [],
+	};
+}
+
+/**
+ * How many records the scope held, best effort.
+ *
+ * Best effort because an encrypted scope whose caller supplied no key cannot
+ * be opened to be counted — and refusing to delete it on that basis would be
+ * the worst possible answer to a deletion request. The files come off disk
+ * either way; only the number in the report is unavailable.
+ */
+async function countRecords(
+	layout: StorageLayout,
+	scopeKey: string,
+	encryptionKey: string | undefined,
+): Promise<number | undefined> {
+	let connection: Connection | null = null;
+	try {
+		connection = await openConnection({
+			path: layout.scopeDataPath(scopeKey),
+			...(encryptionKey ? { encryptionKey } : {}),
+		});
+		const tables = await connection.execute(
+			"SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'c!_%' ESCAPE '!'",
+		);
+		let total = 0;
+		for (const row of tables.rows) {
+			const table = text(row.name);
+			const counted = await connection.execute(`SELECT count(*) AS total FROM "${table}"`);
+			total += num(counted.rows[0]?.total ?? 0);
+		}
+		return total;
+	} catch {
+		// Unknown, not zero: a report that said "0 records" about a scope it
+		// could not open would understate what was deleted.
+		return undefined;
+	} finally {
+		await connection?.close();
+	}
+}
+
+async function artifactIdsOnDisk(layout: StorageLayout, scopeKey: string): Promise<string[]> {
+	try {
+		return (await fileSystem().readdir(artifactsDirectory(layout, scopeKey))).sort(byteOrder);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * The one implementation behind `deleteScopeData` and `resetScope`.
+ *
+ * They do the same thing to disk and mean entirely different things to the
+ * caller: one is a lifecycle operation an app performs on request, the other
+ * is an admission that a database is broken and is being discarded to recover
+ * from it (FR-057a). Keeping them as two exported names with two docstrings
+ * is what stops the destructive one from being reached by accident — there is
+ * no path from `openDatabase` to either.
+ */
+async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	const scope = resolveScope(config.scope);
+	const layout = layoutFor(config.name);
+	const catalog = await openConnection({ path: layout.catalogPath });
+
+	try {
+		await ensureCatalog(catalog);
+		const entry = await readEntry(catalog, scope.key);
+
+		// Mark first. Everything after this point is recoverable-in-principle;
+		// this flag is what makes an interruption visible rather than silent.
+		if (entry) {
+			await markDeleting(catalog, scope.key);
+		}
+		markScopeInvalidated(config.name, scope.key);
+
+		const removedArtifacts = await artifactIdsOnDisk(layout, scope.key);
+
+		// The key is needed to count what is being removed, not to remove it,
+		// so a key provider that fails — or a key already destroyed for this
+		// identity, which FR-104 encourages — costs the count, never the
+		// deletion. Until 0.2.0 it failed the whole call after the scope was
+		// already marked, leaving it stuck in `deleting`.
+		let keyHandle: Awaited<ReturnType<typeof acquireKey>> | null = null;
+		if (config.encryption?.enabled) {
+			try {
+				keyHandle = await acquireKey(config.encryption, scope);
+			} catch {
+				keyHandle = null;
+			}
+		}
+		let counted: number | undefined;
+		try {
+			counted =
+				config.encryption?.enabled && keyHandle === null
+					? undefined
+					: await countRecords(layout, scope.key, keyHandle?.value());
+		} finally {
+			keyHandle?.release();
+		}
+
+		const failedRemovals: string[] = [];
+		if (!(await removeIfPresent(layout.scopePath(scope.key))) && entry) {
+			// The directory was there and would not go. Reporting it is the
+			// point: an app that told the user "deleted" would be wrong.
+			const stillThere = await fileSystem()
+				.exists(layout.scopePath(scope.key))
+				.catch(() => false);
+			if (stillThere) {
+				failedRemovals.push(scope.key);
+			}
+		}
+
+		if (failedRemovals.length === 0) {
+			// Cleared last, on purpose.
+			await clearScope(catalog, scope.key);
+		}
+
+		return {
+			scopeKey: scope.key,
+			removedRecords: counted ?? 0,
+			...(counted === undefined ? { recordCountUnavailable: true } : {}),
+			removedArtifacts,
+			orphanedReferences: [],
+			failedRemovals,
+		};
+	} finally {
+		await catalog.close();
+	}
+}
+
+/**
+ * Remove one scope's data. Every collection in that scope, and nothing
+ * outside it (FR-059, SC-012).
+ */
+export function deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return removeScope(config);
+}
+
+/**
+ * Discard one scope and leave it ready for a clean first-run migration
+ * (FR-057a).
+ *
+ * Destructive, separately named, and never reachable from `openDatabase`. An
+ * automatic fallback here would turn a bad migration shipped to production
+ * into silent data loss for every user who launched the app.
+ */
+export function resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return removeScope(config);
+}
+
+/** Remove the whole database directory: catalog, every scope, every artifact. */
+export async function deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
+	const layout = layoutFor(config.name);
+
+	let scopeKeys: string[] = [];
+	try {
+		const catalog = await openConnection({ path: layout.catalogPath });
+		try {
+			await ensureCatalog(catalog);
+			scopeKeys = (await listEntries(catalog)).map(entry => entry.scopeKey);
+		} finally {
+			await catalog.close();
+		}
+	} catch {
+		// No catalog means nothing was ever registered here. The directory
+		// removal below is still the right thing to attempt.
+	}
+
+	for (const scopeKey of scopeKeys) {
+		markScopeInvalidated(config.name, scopeKey);
+	}
+
+	const removed = await removeIfPresent(layout.root);
+	return {
+		removedRecords: 0,
+		removedArtifacts: [],
+		orphanedReferences: [],
+		failedRemovals: removed || scopeKeys.length === 0 ? [] : scopeKeys,
+	};
+}

package/src/adapter/index.ts

@@ -1,68 +1,64 @@
-/**
- * The public lifecycle functions.
- *
- * Scope deletion and reset are module-level rather than handle methods: they
- * must work whether or not a handle is open on the target (FR-059), and
- * `resetScope` in particular must never be reachable as a fallback from
- * `openDatabase` (FR-057a).
- *
- * The active adapter is resolved lazily so a consuming app that only ever
- * uses the in-memory adapter in tests never loads the native peers.
- */
-
-import type { DatabaseHandle, StorageAdapter } from '../contract/adapter';
-import type {
-	DatabaseConfig,
-	DatabaseTargetConfig,
-	ScopeTargetConfig,
-} from '../contract/config';
-import type { DeletionOutcome } from '../contract/attachment';
-
-let override: StorageAdapter | null = null;
-let cached: StorageAdapter | null = null;
-
-/**
- * Swap the adapter. Intended for tests and for the demo app's in-memory
- * mode; production code never calls this.
- */
-export function setStorageAdapter(adapter: StorageAdapter | null): void {
-	override = adapter;
-}
-
-function activeAdapter(): StorageAdapter {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		// Lazy require, matching how rn-auth and rn-camera reach their native
-		// peers: importing at module scope would pull op-sqlite into every
-		// consumer, including ones that only run the in-memory adapter.
-		const { createSqliteAdapter } = require('../sqlite/adapter') as {
-			createSqliteAdapter: () => StorageAdapter;
-		};
-		cached = createSqliteAdapter();
-	}
-	return cached;
-}
-
-export function openDatabase(config: DatabaseConfig): Promise<DatabaseHandle> {
-	return activeAdapter().open(config);
-}
-
-export function deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome> {
-	return activeAdapter().deleteScopeData(config);
-}
-
-export function deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
-	return activeAdapter().deleteDatabase(config);
-}
-
-/**
- * Destructive. Discards one scope's data and leaves it ready for a clean
- * first-run migration. Named apart from `deleteScopeData` deliberately: one
- * is a lifecycle operation, the other is an admission that a database is
- * broken.
- */
-export function resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
-	return activeAdapter().resetScope(config);
-}
+/**
+ * The public lifecycle functions.
+ *
+ * Scope deletion and reset are module-level rather than handle methods: they
+ * must work whether or not a handle is open on the target (FR-059), and
+ * `resetScope` in particular must never be reachable as a fallback from
+ * `openDatabase` (FR-057a).
+ *
+ * The active adapter is resolved lazily so a consuming app that only ever
+ * uses the in-memory adapter in tests never loads the native peers.
+ */
+
+import type { DatabaseHandle, StorageAdapter } from '../contract/adapter';
+import type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } from '../contract/config';
+import type { DeletionOutcome } from '../contract/attachment';
+
+let override: StorageAdapter | null = null;
+let cached: StorageAdapter | null = null;
+
+/**
+ * Swap the adapter. Intended for tests and for the demo app's in-memory
+ * mode; production code never calls this.
+ */
+export function setStorageAdapter(adapter: StorageAdapter | null): void {
+	override = adapter;
+}
+
+function activeAdapter(): StorageAdapter {
+	if (override) {
+		return override;
+	}
+	if (!cached) {
+		// Lazy require, matching how rn-auth and rn-camera reach their native
+		// peers: importing at module scope would pull op-sqlite into every
+		// consumer, including ones that only run the in-memory adapter.
+		const { createSqliteAdapter } = require('../sqlite/adapter') as {
+			createSqliteAdapter: () => StorageAdapter;
+		};
+		cached = createSqliteAdapter();
+	}
+	return cached;
+}
+
+export function openDatabase(config: DatabaseConfig): Promise<DatabaseHandle> {
+	return activeAdapter().open(config);
+}
+
+export function deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return activeAdapter().deleteScopeData(config);
+}
+
+export function deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
+	return activeAdapter().deleteDatabase(config);
+}
+
+/**
+ * Destructive. Discards one scope's data and leaves it ready for a clean
+ * first-run migration. Named apart from `deleteScopeData` deliberately: one
+ * is a lifecycle operation, the other is an admission that a database is
+ * broken.
+ */
+export function resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return activeAdapter().resetScope(config);
+}