@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/diagnostics/redact.ts

@@ -1,141 +1,119 @@
-/**
- * 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).
+ */
+
+import { REDACTED, leadingIdentifier, pickAllowed } from '@chipmobilesdk/rn-core';
+
+/**
+ * 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',
+]);
+
+/**
+ * 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.
+ */
+export function redactForeignText(text: string): string {
+	return leadingIdentifier(text);
+}
+
+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 {
+	const safe = pickAllowed(detail, SAFE_DETAIL_KEYS);
+	return safe && 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;
+}

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';