@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/diagnostics/errors.ts

@@ -1,66 +1,63 @@
-/**
- * The single error type the package raises.
- *
- * Everything is redacted on the way in (see redact.ts), so there is no path
- * by which a field value, query parameter, scope component, or key reaches an
- * error object at all.
- */
-
-import {
-	DiagnosticCodes,
-	RETRYABLE_CODES,
-	type DiagnosticCode,
-} from '../contract/errors';
-import type { MigrationFailureDetail } from '../contract/migration';
-import { redactCause, redactDetail, sanitizeAuthoredMessage } from './redact';
-
-export type StorageErrorInit = {
-	/**
-	 * A message this package authored. Never foreign text — a native or
-	 * consumer-thrown message goes in `cause`, which reduces it to an
-	 * identifier. `authored-messages.test.ts` checks every call site.
-	 */
-	message?: string;
-	detail?: Record<string, unknown>;
-	migration?: MigrationFailureDetail;
-	cause?: unknown;
-};
-
-export class StorageError extends Error {
-	readonly code: DiagnosticCode;
-	readonly retryable: boolean;
-	readonly detail?: Record<string, string | number | boolean>;
-	readonly migration?: MigrationFailureDetail;
-	readonly redactedCause?: string;
-
-	constructor(code: DiagnosticCode, init: StorageErrorInit = {}) {
-		super(init.message ? sanitizeAuthoredMessage(init.message) : code);
-		this.name = 'StorageError';
-		this.code = code;
-		this.retryable = RETRYABLE_CODES.has(code);
-		this.detail = redactDetail(init.detail);
-		// Version numbers and an outcome enum — no payload can hide in these.
-		this.migration = init.migration;
-		this.redactedCause = redactCause(init.cause);
-		// `cause` is deliberately NOT assigned: the native error it came from
-		// may quote the offending value, and assigning it would reintroduce
-		// exactly the leak redaction exists to prevent.
-		Object.setPrototypeOf(this, StorageError.prototype);
-	}
-}
-
-export function isStorageError(value: unknown): value is StorageError {
-	return value instanceof StorageError;
-}
-
-/** So no consumer ever has to parse a message string (FR-082). */
-export function isCode(value: unknown, code: DiagnosticCode): boolean {
-	return isStorageError(value) && value.code === code;
-}
-
-export function raise(code: DiagnosticCode, init?: StorageErrorInit): never {
-	throw new StorageError(code, init);
-}
-
-export { DiagnosticCodes };
-export type { DiagnosticCode };
+/**
+ * The single error type the package raises.
+ *
+ * Everything is redacted on the way in (see redact.ts), so there is no path
+ * by which a field value, query parameter, scope component, or key reaches an
+ * error object at all.
+ */
+
+import { SdkError } from '@chipmobilesdk/rn-core';
+
+import { DiagnosticCodes, RETRYABLE_CODES, type DiagnosticCode } from '../contract/errors';
+import type { MigrationFailureDetail } from '../contract/migration';
+import { redactCause, redactDetail, sanitizeAuthoredMessage } from './redact';
+
+export type StorageErrorInit = {
+	/**
+	 * A message this package authored. Never foreign text — a native or
+	 * consumer-thrown message goes in `cause`, which reduces it to an
+	 * identifier. `authored-messages.test.ts` checks every call site.
+	 */
+	message?: string;
+	detail?: Record<string, unknown> | undefined;
+	migration?: MigrationFailureDetail | undefined;
+	cause?: unknown;
+};
+
+/** The package's error; an `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-local-db'`. */
+export class StorageError extends SdkError<DiagnosticCode> {
+	readonly detail?: Record<string, string | number | boolean> | undefined;
+	readonly migration?: MigrationFailureDetail | undefined;
+
+	constructor(code: DiagnosticCode, init: StorageErrorInit = {}) {
+		// Call sites pass only authored literals (authored-messages.test.ts).
+		const message = init.message ? sanitizeAuthoredMessage(init.message) : code;
+		// `cause` is deliberately NOT kept: the native error it came from may
+		// quote the offending value. Only its redacted identifier survives.
+		super('rn-local-db', code, {
+			message,
+			retryable: RETRYABLE_CODES.has(code),
+			redactedCause: redactCause(init.cause),
+		});
+		this.name = 'StorageError';
+		this.detail = redactDetail(init.detail);
+		// Version numbers and an outcome enum — no payload can hide in these.
+		this.migration = init.migration;
+	}
+}
+
+export function isStorageError(value: unknown): value is StorageError {
+	return value instanceof StorageError;
+}
+
+/** So no consumer ever has to parse a message string (FR-082). */
+export function isCode(value: unknown, code: DiagnosticCode): boolean {
+	return isStorageError(value) && value.code === code;
+}
+
+export function raise(code: DiagnosticCode, init?: StorageErrorInit): never {
+	throw new StorageError(code, init);
+}
+
+export { DiagnosticCodes };
+export type { DiagnosticCode };

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