@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/diagnostics/faults.ts

@@ -1,64 +1,58 @@
-/**
- * The fault registry.
- *
- * It lives here rather than under `testing/` because FR-095 wants every
- * documented failure reachable from a real app running the real adapter — the
- * demo's fault-injection panel exercises the on-device path, not a simulation
- * of it. So the check has to exist in production code.
- *
- * What does *not* exist in production code is a way to inject: `injectFault`
- * and `clearFaults` are exported only from the `./testing` entrypoint. With
- * nothing injected this is one lookup in an empty map, which is the price of
- * being able to prove a recovery path works before a user finds it broken.
- */
-
-import type { DiagnosticCode } from '../contract/errors';
-import { StorageError } from './errors';
-
-export type FaultPoint =
-	| 'open'
-	| 'read'
-	| 'write'
-	| 'commit'
-	| 'migration'
-	| 'attachmentWrite'
-	| 'keyProvider';
-
-export type FaultSpec = {
-	at: FaultPoint;
-	code: DiagnosticCode;
-	/** Fire this many times, then stop. Omit for "until cleared". */
-	times?: number;
-};
-
-const faults = new Map<FaultPoint, { code: DiagnosticCode; remaining: number }>();
-
-export function injectFault(spec: FaultSpec): void {
-	faults.set(spec.at, {
-		code: spec.code,
-		remaining: spec.times ?? Number.POSITIVE_INFINITY,
-	});
-}
-
-export function clearFaults(): void {
-	faults.clear();
-}
-
-export function activeFaults(): FaultPoint[] {
-	return [...faults.keys()];
-}
-
-export function throwIfFaulted(point: FaultPoint): void {
-	if (faults.size === 0) {
-		return;
-	}
-	const fault = faults.get(point);
-	if (!fault || fault.remaining <= 0) {
-		return;
-	}
-	fault.remaining -= 1;
-	if (fault.remaining <= 0) {
-		faults.delete(point);
-	}
-	throw new StorageError(fault.code, { message: `injected fault at ${point}` });
-}
+/**
+ * The fault registry.
+ *
+ * It lives here rather than under `testing/` because FR-095 wants every
+ * documented failure reachable from a real app running the real adapter — the
+ * demo's fault-injection panel exercises the on-device path, not a simulation
+ * of it. So the check has to exist in production code.
+ *
+ * What does *not* exist in production code is a way to inject: `injectFault`
+ * and `clearFaults` are exported only from the `./testing` entrypoint. With
+ * nothing injected this is one lookup in an empty map, which is the price of
+ * being able to prove a recovery path works before a user finds it broken.
+ */
+
+import type { DiagnosticCode } from '../contract/errors';
+import { StorageError } from './errors';
+
+export type FaultPoint =
+	'open' | 'read' | 'write' | 'commit' | 'migration' | 'attachmentWrite' | 'keyProvider';
+
+export type FaultSpec = {
+	at: FaultPoint;
+	code: DiagnosticCode;
+	/** Fire this many times, then stop. Omit for "until cleared". */
+	times?: number;
+};
+
+const faults = new Map<FaultPoint, { code: DiagnosticCode; remaining: number }>();
+
+export function injectFault(spec: FaultSpec): void {
+	faults.set(spec.at, {
+		code: spec.code,
+		remaining: spec.times ?? Number.POSITIVE_INFINITY,
+	});
+}
+
+export function clearFaults(): void {
+	faults.clear();
+}
+
+export function activeFaults(): FaultPoint[] {
+	return [...faults.keys()];
+}
+
+export function throwIfFaulted(point: FaultPoint): void {
+	if (faults.size === 0) {
+		return;
+	}
+	const fault = faults.get(point);
+	if (!fault || fault.remaining <= 0) {
+		return;
+	}
+	fault.remaining -= 1;
+	if (fault.remaining <= 0) {
+		faults.delete(point);
+	}
+	throw new StorageError(fault.code, { message: `injected fault at ${point}` });
+}

package/src/diagnostics/map-native.ts

@@ -1,106 +1,108 @@
-/**
- * Native error to diagnostic code.
- *
- * The three failures FR-076 insists stay apart — a full disk, a filesystem
- * the app cannot reach, and a corrupt database — arrive from SQLite and from
- * the filesystem peer as ordinary errors with a string on them. Collapsing
- * them into one write failure would be the easy thing and the wrong one: an
- * app frees space for the first, retries after unlock for the second, and has
- * to offer a reset for the third.
- *
- * Only the code is derived here. The message never travels — it is redacted
- * at construction by `StorageError` (FR-079).
- */
-
-import { DiagnosticCodes, type DiagnosticCode } from '../contract/errors';
-import { isStorageError, raise } from './errors';
-
-export type NativeContext = {
-	/** Where the failure happened, so ambiguous signatures resolve correctly. */
-	operation: 'open' | 'read' | 'write' | 'transaction' | 'attachment' | 'delete';
-	/**
-	 * Whether the database was opened with a key. "File is not a database" is
-	 * SQLCipher's answer to a wrong key and SQLite's answer to a corrupt file;
-	 * the only thing that separates them is whether a key was in play.
-	 */
-	encrypted?: boolean;
-};
-
-function textOf(error: unknown): string {
-	if (error instanceof Error) {
-		return `${error.message} ${(error as { code?: string }).code ?? ''}`;
-	}
-	if (typeof error === 'string') {
-		return error;
-	}
-	return '';
-}
-
-const DISK_FULL = /SQLITE_FULL|database or disk is full|ENOSPC|no space left/i;
-const NOT_A_DATABASE = /SQLITE_NOTADB|file is not a database|encrypted or is not a database/i;
-const CORRUPT = /SQLITE_CORRUPT|database disk image is malformed|malformed database/i;
-const CONFLICT = /UNIQUE constraint failed|PRIMARY KEY must be unique|SQLITE_CONSTRAINT_PRIMARYKEY/i;
-const ACCESS = /SQLITE_CANTOPEN|SQLITE_READONLY|SQLITE_PERM|SQLITE_AUTH|EACCES|EPERM|EROFS|ENOENT|EISDIR/i;
-const BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i;
-
-export function mapNativeError(error: unknown, context: NativeContext): DiagnosticCode {
-	const text = textOf(error);
-
-	if (DISK_FULL.test(text)) {
-		return DiagnosticCodes.DISK_FULL;
-	}
-	if (NOT_A_DATABASE.test(text)) {
-		// A wrong key and a corrupt file are indistinguishable from the engine's
-		// answer alone. Reporting corruption for a wrong key would push an app
-		// towards destroying recoverable data, so the encrypted case wins.
-		return context.encrypted ? DiagnosticCodes.KEY_INVALID : DiagnosticCodes.CORRUPTION;
-	}
-	if (CORRUPT.test(text)) {
-		return DiagnosticCodes.CORRUPTION;
-	}
-	if (CONFLICT.test(text)) {
-		return DiagnosticCodes.RECORD_CONFLICT;
-	}
-	if (ACCESS.test(text)) {
-		return DiagnosticCodes.STORAGE_ACCESS;
-	}
-	if (BUSY.test(text)) {
-		// Retryable, and distinct from a permanent write failure.
-		return context.operation === 'transaction'
-			? DiagnosticCodes.TRANSACTION_FAILED
-			: DiagnosticCodes.WRITE_FAILED;
-	}
-
-	switch (context.operation) {
-		case 'open':
-			return DiagnosticCodes.OPEN_FAILED;
-		case 'read':
-			return DiagnosticCodes.STORAGE_ACCESS;
-		case 'transaction':
-			return DiagnosticCodes.TRANSACTION_FAILED;
-		case 'attachment':
-			return DiagnosticCodes.ATTACHMENT_WRITE_FAILED;
-		case 'delete':
-		case 'write':
-		default:
-			return DiagnosticCodes.WRITE_FAILED;
-	}
-}
-
-/**
- * Re-raise a native failure as a typed one, preserving an error the package
- * already classified rather than reclassifying it as a generic write failure.
- */
-export function raiseNative(error: unknown, context: NativeContext): never {
-	if (isStorageError(error)) {
-		throw error;
-	}
-	raise(mapNativeError(error, context), {
-		// The native message is deliberately not the error's message. It goes
-		// through `cause`, which redacts it — passing it here as well would be
-		// two chances to leak the same string for no extra information.
-		message: `native ${context.operation} failed`,
-		detail: { operation: context.operation },
-		cause: error,
-	});
-}
+/**
+ * Native error to diagnostic code.
+ *
+ * The three failures FR-076 insists stay apart — a full disk, a filesystem
+ * the app cannot reach, and a corrupt database — arrive from SQLite and from
+ * the filesystem peer as ordinary errors with a string on them. Collapsing
+ * them into one write failure would be the easy thing and the wrong one: an
+ * app frees space for the first, retries after unlock for the second, and has
+ * to offer a reset for the third.
+ *
+ * Only the code is derived here. The message never travels — it is redacted
+ * at construction by `StorageError` (FR-079).
+ */
+
+import { DiagnosticCodes, type DiagnosticCode } from '../contract/errors';
+import { isStorageError, raise } from './errors';
+
+export type NativeContext = {
+	/** Where the failure happened, so ambiguous signatures resolve correctly. */
+	operation: 'open' | 'read' | 'write' | 'transaction' | 'attachment' | 'delete';
+	/**
+	 * Whether the database was opened with a key. "File is not a database" is
+	 * SQLCipher's answer to a wrong key and SQLite's answer to a corrupt file;
+	 * the only thing that separates them is whether a key was in play.
+	 */
+	encrypted?: boolean;
+};
+
+function textOf(error: unknown): string {
+	if (error instanceof Error) {
+		return `${error.message} ${(error as { code?: string }).code ?? ''}`;
+	}
+	if (typeof error === 'string') {
+		return error;
+	}
+	return '';
+}
+
+const DISK_FULL = /SQLITE_FULL|database or disk is full|ENOSPC|no space left/i;
+const NOT_A_DATABASE = /SQLITE_NOTADB|file is not a database|encrypted or is not a database/i;
+const CORRUPT = /SQLITE_CORRUPT|database disk image is malformed|malformed database/i;
+const CONFLICT =
+	/UNIQUE constraint failed|PRIMARY KEY must be unique|SQLITE_CONSTRAINT_PRIMARYKEY/i;
+const ACCESS =
+	/SQLITE_CANTOPEN|SQLITE_READONLY|SQLITE_PERM|SQLITE_AUTH|EACCES|EPERM|EROFS|ENOENT|EISDIR/i;
+const BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i;
+
+export function mapNativeError(error: unknown, context: NativeContext): DiagnosticCode {
+	const text = textOf(error);
+
+	if (DISK_FULL.test(text)) {
+		return DiagnosticCodes.DISK_FULL;
+	}
+	if (NOT_A_DATABASE.test(text)) {
+		// A wrong key and a corrupt file are indistinguishable from the engine's
+		// answer alone. Reporting corruption for a wrong key would push an app
+		// towards destroying recoverable data, so the encrypted case wins.
+		return context.encrypted ? DiagnosticCodes.KEY_INVALID : DiagnosticCodes.CORRUPTION;
+	}
+	if (CORRUPT.test(text)) {
+		return DiagnosticCodes.CORRUPTION;
+	}
+	if (CONFLICT.test(text)) {
+		return DiagnosticCodes.RECORD_CONFLICT;
+	}
+	if (ACCESS.test(text)) {
+		return DiagnosticCodes.STORAGE_ACCESS;
+	}
+	if (BUSY.test(text)) {
+		// Retryable, and distinct from a permanent write failure.
+		return context.operation === 'transaction'
+			? DiagnosticCodes.TRANSACTION_FAILED
+			: DiagnosticCodes.WRITE_FAILED;
+	}
+
+	switch (context.operation) {
+		case 'open':
+			return DiagnosticCodes.OPEN_FAILED;
+		case 'read':
+			return DiagnosticCodes.STORAGE_ACCESS;
+		case 'transaction':
+			return DiagnosticCodes.TRANSACTION_FAILED;
+		case 'attachment':
+			return DiagnosticCodes.ATTACHMENT_WRITE_FAILED;
+		case 'delete':
+		case 'write':
+		default:
+			return DiagnosticCodes.WRITE_FAILED;
+	}
+}
+
+/**
+ * Re-raise a native failure as a typed one, preserving an error the package
+ * already classified rather than reclassifying it as a generic write failure.
+ */
+export function raiseNative(error: unknown, context: NativeContext): never {
+	if (isStorageError(error)) {
+		throw error;
+	}
+	raise(mapNativeError(error, context), {
+		// The native message is deliberately not the error's message. It goes
+		// through `cause`, which redacts it — passing it here as well would be
+		// two chances to leak the same string for no extra information.
+		message: `native ${context.operation} failed`,
+		detail: { operation: context.operation },
+		cause: error,
+	});
+}

package/src/diagnostics/redact.ts

@@ -1,141 +1,137 @@
-/**
- * Redaction, applied at construction rather than at logging time.
- *
- * The distinction matters: an error object that never held a payload cannot
- * leak one through a consumer's crash reporter, which is where these leaks
- * actually happen in practice. Redacting on the way out of a logger would
- * still leave the values sitting on the object for anything else to pick up
- * (FR-079, FR-099).
- */
-
-/**
- * The allowlist IS the mechanism. Every key here has been reviewed as
- * incapable of carrying user data: identifiers the app already knows, sizes,
- * counts, and version numbers.
- *
- * A denylist was tried and removed. It rejected `recordId` because the name
- * contains "record", which is the failure mode denylists always have — they
- * guess from names. A closed allowlist cannot guess, and adding to it is a
- * deliberate act with a reviewer attached.
- */
-export const SAFE_DETAIL_KEYS = new Set([
-	'code',
-	'collection',
-	'recordId',
-	'attachmentId',
-	'scopeKey',
-	'version',
-	'recordedVersion',
-	'failingVersion',
-	'outcome',
-	'operation',
-	'adapter',
-	'platform',
-	'sizeBytes',
-	'limitBytes',
-	'count',
-	'limit',
-]);
-
-const REDACTED = '[redacted]';
-
-/**
- * Reduce foreign text to an identifier, or to nothing.
- *
- * "Foreign" means text this package did not author: a SQLite message, a
- * filesystem error, an `Error` a consumer's own migration threw. Any of them
- * can contain anything — SQLite quotes bound parameters back, and a migration
- * that fails on a constraint routinely names the value that violated it.
- *
- * An earlier version of this tried to keep the readable part: the text before
- * the first colon, if it "looked like a class of failure". That heuristic
- * fails on the case that matters. `Patient reported chest pain` looks exactly
- * like a class of failure — short, no punctuation, no digits — and is a
- * medical record. There is no shape test that separates prose describing a
- * failure from prose describing a person, so there is no version of the
- * heuristic worth keeping.
- *
- * What survives is a leading `SQLITE_*` / `ENOENT`-style identifier, which is
- * a closed vocabulary of engine and libc constants and cannot be a value.
- * Everything else becomes `[redacted]`. A developer who needs more can
- * reproduce with the development logger; a crash report cannot.
- */
-const IDENTIFIER_TOKEN = /^([A-Z][A-Z0-9_]{2,})\b/;
-
-export function redactForeignText(text: string): string {
-	if (!text) {
-		return '';
-	}
-	const firstLine = text.split('\n')[0]!.trim();
-	const token = IDENTIFIER_TOKEN.exec(firstLine);
-	return token ? token[1]! : REDACTED;
-}
-
-const MAX_AUTHORED_MESSAGE = 160;
-
-/**
- * A message this package wrote itself.
- *
- * Every `raise()` call site passes a string literal, and the handful that
- * interpolate do so with a value from a closed set — an operator name, a
- * fault point, a sanitized identifier. `authored-messages.test.ts` enforces
- * that mechanically against the source, so this is a checked property rather
- * than a convention someone has to remember.
- *
- * So no filtering happens here: filtering a message the package wrote would
- * destroy the only readable part of the error for no gain. Foreign text never
- * reaches this function — it goes through `redactForeignText` above.
- */
-export function sanitizeAuthoredMessage(message: string): string {
-	return message.split('\n')[0]!.trim().slice(0, MAX_AUTHORED_MESSAGE);
-}
-
-/**
- * Reduce a consumer-supplied identifier to a bounded, punctuation-free token.
- *
- * A field name is worth naming — FR-034 exists so a typo is distinguishable
- * from a deliberate choice, and "which field?" is the whole answer. But the
- * name arrives from the consumer, so it is capped and stripped rather than
- * trusted verbatim.
- */
-export function sanitizeIdentifier(identifier: string): string {
-	const cleaned = identifier.replace(/\W/g, '').slice(0, 64);
-	return cleaned.length > 0 ? cleaned : REDACTED;
-}
-
-/** Keep only keys on the allowlist, and only primitive values. */
-export function redactDetail(
-	detail: Record<string, unknown> | undefined,
-): Record<string, string | number | boolean> | undefined {
-	if (!detail) {
-		return undefined;
-	}
-	const safe: Record<string, string | number | boolean> = {};
-	for (const [key, value] of Object.entries(detail)) {
-		if (!SAFE_DETAIL_KEYS.has(key)) {
-			continue;
-		}
-		if (
-			typeof value === 'string' ||
-			typeof value === 'number' ||
-			typeof value === 'boolean'
-		) {
-			safe[key] = value;
-		}
-	}
-	return Object.keys(safe).length > 0 ? safe : undefined;
-}
-
-/** Reduce an unknown thrown value to a message-shaped string, redacted. */
-export function redactCause(cause: unknown): string | undefined {
-	if (cause === undefined || cause === null) {
-		return undefined;
-	}
-	if (cause instanceof Error) {
-		return redactForeignText(cause.message);
-	}
-	if (typeof cause === 'string') {
-		return redactForeignText(cause);
-	}
-	return REDACTED;
-}
+/**
+ * Redaction, applied at construction rather than at logging time.
+ *
+ * The distinction matters: an error object that never held a payload cannot
+ * leak one through a consumer's crash reporter, which is where these leaks
+ * actually happen in practice. Redacting on the way out of a logger would
+ * still leave the values sitting on the object for anything else to pick up
+ * (FR-079, FR-099).
+ */
+
+/**
+ * The allowlist IS the mechanism. Every key here has been reviewed as
+ * incapable of carrying user data: identifiers the app already knows, sizes,
+ * counts, and version numbers.
+ *
+ * A denylist was tried and removed. It rejected `recordId` because the name
+ * contains "record", which is the failure mode denylists always have — they
+ * guess from names. A closed allowlist cannot guess, and adding to it is a
+ * deliberate act with a reviewer attached.
+ */
+export const SAFE_DETAIL_KEYS = new Set([
+	'code',
+	'collection',
+	'recordId',
+	'attachmentId',
+	'scopeKey',
+	'version',
+	'recordedVersion',
+	'failingVersion',
+	'outcome',
+	'operation',
+	'adapter',
+	'platform',
+	'sizeBytes',
+	'limitBytes',
+	'count',
+	'limit',
+]);
+
+const REDACTED = '[redacted]';
+
+/**
+ * Reduce foreign text to an identifier, or to nothing.
+ *
+ * "Foreign" means text this package did not author: a SQLite message, a
+ * filesystem error, an `Error` a consumer's own migration threw. Any of them
+ * can contain anything — SQLite quotes bound parameters back, and a migration
+ * that fails on a constraint routinely names the value that violated it.
+ *
+ * An earlier version of this tried to keep the readable part: the text before
+ * the first colon, if it "looked like a class of failure". That heuristic
+ * fails on the case that matters. `Patient reported chest pain` looks exactly
+ * like a class of failure — short, no punctuation, no digits — and is a
+ * medical record. There is no shape test that separates prose describing a
+ * failure from prose describing a person, so there is no version of the
+ * heuristic worth keeping.
+ *
+ * What survives is a leading `SQLITE_*` / `ENOENT`-style identifier, which is
+ * a closed vocabulary of engine and libc constants and cannot be a value.
+ * Everything else becomes `[redacted]`. A developer who needs more can
+ * reproduce with the development logger; a crash report cannot.
+ */
+const IDENTIFIER_TOKEN = /^([A-Z][A-Z0-9_]{2,})\b/;
+
+export function redactForeignText(text: string): string {
+	if (!text) {
+		return '';
+	}
+	const firstLine = text.split('\n')[0]!.trim();
+	const token = IDENTIFIER_TOKEN.exec(firstLine);
+	return token ? token[1]! : REDACTED;
+}
+
+const MAX_AUTHORED_MESSAGE = 160;
+
+/**
+ * A message this package wrote itself.
+ *
+ * Every `raise()` call site passes a string literal, and the handful that
+ * interpolate do so with a value from a closed set — an operator name, a
+ * fault point, a sanitized identifier. `authored-messages.test.ts` enforces
+ * that mechanically against the source, so this is a checked property rather
+ * than a convention someone has to remember.
+ *
+ * So no filtering happens here: filtering a message the package wrote would
+ * destroy the only readable part of the error for no gain. Foreign text never
+ * reaches this function — it goes through `redactForeignText` above.
+ */
+export function sanitizeAuthoredMessage(message: string): string {
+	return message.split('\n')[0]!.trim().slice(0, MAX_AUTHORED_MESSAGE);
+}
+
+/**
+ * Reduce a consumer-supplied identifier to a bounded, punctuation-free token.
+ *
+ * A field name is worth naming — FR-034 exists so a typo is distinguishable
+ * from a deliberate choice, and "which field?" is the whole answer. But the
+ * name arrives from the consumer, so it is capped and stripped rather than
+ * trusted verbatim.
+ */
+export function sanitizeIdentifier(identifier: string): string {
+	const cleaned = identifier.replace(/\W/g, '').slice(0, 64);
+	return cleaned.length > 0 ? cleaned : REDACTED;
+}
+
+/** Keep only keys on the allowlist, and only primitive values. */
+export function redactDetail(
+	detail: Record<string, unknown> | undefined,
+): Record<string, string | number | boolean> | undefined {
+	if (!detail) {
+		return undefined;
+	}
+	const safe: Record<string, string | number | boolean> = {};
+	for (const [key, value] of Object.entries(detail)) {
+		if (!SAFE_DETAIL_KEYS.has(key)) {
+			continue;
+		}
+		if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+			safe[key] = value;
+		}
+	}
+	return Object.keys(safe).length > 0 ? safe : undefined;
+}
+
+/** Reduce an unknown thrown value to a message-shaped string, redacted. */
+export function redactCause(cause: unknown): string | undefined {
+	if (cause === undefined || cause === null) {
+		return undefined;
+	}
+	if (cause instanceof Error) {
+		return redactForeignText(cause.message);
+	}
+	if (typeof cause === 'string') {
+		return redactForeignText(cause);
+	}
+	return REDACTED;
+}