@chipmobilesdk/rn-local-db 0.2.0 → 0.3.0

package/src/contract/adapter.ts

@@ -1,78 +1,76 @@
-/**
- * The interface every storage implementation satisfies.
- *
- * Two implementations exist: op-sqlite on device, and a pure-TypeScript
- * in-memory one for tests. The second is not a convenience — op-sqlite is
- * native and unreachable from Jest, so without it the package's own
- * guarantees would be untestable in CI (research.md R8).
- */
-
-import type {
-	AttachmentAvailability,
-	AttachmentInput,
-	AttachmentReference,
-	AttachmentOwner,
-	ByteRange,
-	DeletionOutcome,
-	ReconciliationReport,
-} from './attachment';
-import type { EffectivePosture } from './backup';
-import type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } from './config';
-import type { FilterNode, IndexCoverageReport, Query, ResultPage } from './query';
-import type { RecordInput, StorableRecordData, StoredRecord, WriteOutcome } from './record';
-import type { BatchOperation, BatchOutcome, CollectionOps, Transaction } from './transaction';
-
-export type Attachments = {
-	write(input: AttachmentInput): Promise<AttachmentReference>;
-	read(id: string, range?: ByteRange): Promise<string>;
-	/** Never opens or decrypts the artifact (FR-073e, FR-107b). */
-	availability(id: string): Promise<AttachmentAvailability>;
-	remove(id: string): Promise<DeletionOutcome>;
-	listFor(owner: AttachmentOwner): Promise<AttachmentReference[]>;
-	/** App-triggered only; the package runs no background sweep. */
-	reconcile(options?: { removeOrphans?: boolean }): Promise<ReconciliationReport>;
-};
-
-export type DatabaseHandle = {
-	/** The scope hash. Never the components (FR-014). */
-	readonly scopeKey: string;
-	readonly schemaVersion: number;
-	readonly backupPosture: EffectivePosture;
-	readonly isEncrypted: boolean;
-
-	collection<T extends StorableRecordData = StorableRecordData>(
-		name: string,
-	): CollectionOps<T>;
-	transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R>;
-	batch(operations: BatchOperation[]): Promise<BatchOutcome>;
-	attachments(): Attachments;
-	/** Development-mode index coverage answer (FR-037). */
-	explain(collection: string, query?: Query): Promise<IndexCoverageReport>;
-	close(): Promise<void>;
-};
-
-/**
- * What an implementation must provide. Deliberately lower-level than the
- * public surface: validation, budget checks, and error mapping happen once in
- * `adapter/`, above this line, so both implementations share them.
- */
-export type StorageAdapter = {
-	readonly name: 'sqlite' | 'memory';
-
-	open(config: DatabaseConfig): Promise<DatabaseHandle>;
-	deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome>;
-	deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome>;
-	/** The FR-057a recovery path. Never reachable from open(). */
-	resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome>;
-};
-
-export type {
-	CollectionOps,
-	FilterNode,
-	Query,
-	RecordInput,
-	ResultPage,
-	StoredRecord,
-	Transaction,
-	WriteOutcome,
-};
+/**
+ * The interface every storage implementation satisfies.
+ *
+ * Two implementations exist: op-sqlite on device, and a pure-TypeScript
+ * in-memory one for tests. The second is not a convenience — op-sqlite is
+ * native and unreachable from Jest, so without it the package's own
+ * guarantees would be untestable in CI (research.md R8).
+ */
+
+import type {
+	AttachmentAvailability,
+	AttachmentInput,
+	AttachmentReference,
+	AttachmentOwner,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from './attachment';
+import type { EffectivePosture } from './backup';
+import type { DatabaseConfig, DatabaseTargetConfig, ScopeTargetConfig } from './config';
+import type { FilterNode, IndexCoverageReport, Query, ResultPage } from './query';
+import type { RecordInput, StorableRecordData, StoredRecord, WriteOutcome } from './record';
+import type { BatchOperation, BatchOutcome, CollectionOps, Transaction } from './transaction';
+
+export type Attachments = {
+	write(input: AttachmentInput): Promise<AttachmentReference>;
+	read(id: string, range?: ByteRange): Promise<string>;
+	/** Never opens or decrypts the artifact (FR-073e, FR-107b). */
+	availability(id: string): Promise<AttachmentAvailability>;
+	remove(id: string): Promise<DeletionOutcome>;
+	listFor(owner: AttachmentOwner): Promise<AttachmentReference[]>;
+	/** App-triggered only; the package runs no background sweep. */
+	reconcile(options?: { removeOrphans?: boolean }): Promise<ReconciliationReport>;
+};
+
+export type DatabaseHandle = {
+	/** The scope hash. Never the components (FR-014). */
+	readonly scopeKey: string;
+	readonly schemaVersion: number;
+	readonly backupPosture: EffectivePosture;
+	readonly isEncrypted: boolean;
+
+	collection<T extends StorableRecordData = StorableRecordData>(name: string): CollectionOps<T>;
+	transaction<R>(fn: (tx: Transaction) => Promise<R>): Promise<R>;
+	batch(operations: BatchOperation[]): Promise<BatchOutcome>;
+	attachments(): Attachments;
+	/** Development-mode index coverage answer (FR-037). */
+	explain(collection: string, query?: Query): Promise<IndexCoverageReport>;
+	close(): Promise<void>;
+};
+
+/**
+ * What an implementation must provide. Deliberately lower-level than the
+ * public surface: validation, budget checks, and error mapping happen once in
+ * `adapter/`, above this line, so both implementations share them.
+ */
+export type StorageAdapter = {
+	readonly name: 'sqlite' | 'memory';
+
+	open(config: DatabaseConfig): Promise<DatabaseHandle>;
+	deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome>;
+	deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome>;
+	/** The FR-057a recovery path. Never reachable from open(). */
+	resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome>;
+};
+
+export type {
+	CollectionOps,
+	FilterNode,
+	Query,
+	RecordInput,
+	ResultPage,
+	StoredRecord,
+	Transaction,
+	WriteOutcome,
+};

package/src/contract/attachment.ts

@@ -1,78 +1,75 @@
-/**
- * Attachment references and the artifacts behind them.
- *
- * This package owns both halves. The consequence is that a filesystem write
- * cannot be rolled back by a database transaction, which is why
- * reconciliation exists (FR-073d) rather than being a nicety.
- */
-
-export type AttachmentOwner = {
-	collection: string;
-	id: string;
-};
-
-export type AttachmentInput = {
-	id: string;
-	/** Absent means the attachment belongs to the scope rather than a record. */
-	owner?: AttachmentOwner;
-	contentType: string;
-	/** Base64 content. Written incrementally; never held whole when encrypted. */
-	content: string;
-};
-
-export type AttachmentReference = {
-	id: string;
-	owner?: AttachmentOwner;
-	contentType: string;
-	/** Plaintext byte length, <= 100 MB (FR-088). */
-	size: number;
-	createdAt: number;
-	/** Present only for encrypted artifacts (research.md R4). */
-	chunkSize?: number;
-	chunkCount?: number;
-};
-
-/**
- * `undecryptable` is deliberately distinct from `missing`: one is data loss
- * for that artifact, the other is a wrong key or a tampered file (FR-107c).
- */
-export type AttachmentAvailabilityState =
-	| 'available'
-	| 'missing'
-	| 'inaccessible'
-	| 'undecryptable';
-
-export type AttachmentAvailability = {
-	id: string;
-	state: AttachmentAvailabilityState;
-	size?: number;
-};
-
-export type ByteRange = {
-	offset: number;
-	length: number;
-};
-
-/**
- * Both directions of divergence between the database and the disk (FR-073d).
- */
-export type ReconciliationReport = {
-	orphanedArtifacts: string[];
-	danglingReferences: string[];
-	removedArtifacts: string[];
-};
-
-/** Never a bare success (FR-065, FR-071). */
-export type DeletionOutcome = {
-	scopeKey?: string;
-	removedRecords: number;
-	/**
-	 * True when the scope was deleted but its records could not be counted — an
-	 * encrypted scope whose key was unavailable, or a file that would not open.
-	 * `removedRecords` is then 0 and means "unknown". Added in 0.2.0.
-	 */
-	recordCountUnavailable?: boolean;
-	removedArtifacts: string[];
-	orphanedReferences: string[];
-	failedRemovals: string[];
-};
+/**
+ * Attachment references and the artifacts behind them.
+ *
+ * This package owns both halves. The consequence is that a filesystem write
+ * cannot be rolled back by a database transaction, which is why
+ * reconciliation exists (FR-073d) rather than being a nicety.
+ */
+
+export type AttachmentOwner = {
+	collection: string;
+	id: string;
+};
+
+export type AttachmentInput = {
+	id: string;
+	/** Absent means the attachment belongs to the scope rather than a record. */
+	owner?: AttachmentOwner | undefined;
+	contentType: string;
+	/** Base64 content. Written incrementally; never held whole when encrypted. */
+	content: string;
+};
+
+export type AttachmentReference = {
+	id: string;
+	owner?: AttachmentOwner | undefined;
+	contentType: string;
+	/** Plaintext byte length, <= 100 MB (FR-088). */
+	size: number;
+	createdAt: number;
+	/** Present only for encrypted artifacts (research.md R4). */
+	chunkSize?: number;
+	chunkCount?: number;
+};
+
+/**
+ * `undecryptable` is deliberately distinct from `missing`: one is data loss
+ * for that artifact, the other is a wrong key or a tampered file (FR-107c).
+ */
+export type AttachmentAvailabilityState =
+	'available' | 'missing' | 'inaccessible' | 'undecryptable';
+
+export type AttachmentAvailability = {
+	id: string;
+	state: AttachmentAvailabilityState;
+	size?: number;
+};
+
+export type ByteRange = {
+	offset: number;
+	length: number;
+};
+
+/**
+ * Both directions of divergence between the database and the disk (FR-073d).
+ */
+export type ReconciliationReport = {
+	orphanedArtifacts: string[];
+	danglingReferences: string[];
+	removedArtifacts: string[];
+};
+
+/** Never a bare success (FR-065, FR-071). */
+export type DeletionOutcome = {
+	scopeKey?: string;
+	removedRecords: number;
+	/**
+	 * True when the scope was deleted but its records could not be counted — an
+	 * encrypted scope whose key was unavailable, or a file that would not open.
+	 * `removedRecords` is then 0 and means "unknown". Added in 0.2.0.
+	 */
+	recordCountUnavailable?: boolean;
+	removedArtifacts: string[];
+	orphanedReferences: string[];
+	failedRemovals: string[];
+};

package/src/contract/backup.ts

@@ -1,28 +1,28 @@
-/**
- * Platform backup posture.
- *
- * The platforms are not symmetric, and this contract is where that becomes
- * visible to the consumer rather than hidden. On iOS the package sets the
- * exclusion attribute itself. On Android backup participation is declared in
- * the app's manifest — build-time, app-owned, and unreachable from a library
- * that authors no native code — so the package verifies and reports instead.
- * See research.md R5.
- */
-
-export type BackupConfig = {
-	/** Default false: excluded unless the app asks otherwise (FR-109). */
-	includeInPlatformBackup: boolean;
-};
-
-export type BackupPostureValue = 'excluded' | 'included' | 'unknown';
-
-export type EffectivePosture = {
-	/** What the app asked for. */
-	requested: Exclude<BackupPostureValue, 'unknown'>;
-	/** What the package can actually confirm on this platform. */
-	observed: BackupPostureValue;
-	/** iOS: the package. Android: the app's manifest. */
-	enforcedBy: 'package' | 'app-manifest';
-	/** Present when requested and observed disagree — the case that matters. */
-	warning?: string;
-};
+/**
+ * Platform backup posture.
+ *
+ * The platforms are not symmetric, and this contract is where that becomes
+ * visible to the consumer rather than hidden. On iOS the package sets the
+ * exclusion attribute itself. On Android backup participation is declared in
+ * the app's manifest — build-time, app-owned, and unreachable from a library
+ * that authors no native code — so the package verifies and reports instead.
+ * See research.md R5.
+ */
+
+export type BackupConfig = {
+	/** Default false: excluded unless the app asks otherwise (FR-109). */
+	includeInPlatformBackup: boolean;
+};
+
+export type BackupPostureValue = 'excluded' | 'included' | 'unknown';
+
+export type EffectivePosture = {
+	/** What the app asked for. */
+	requested: Exclude<BackupPostureValue, 'unknown'>;
+	/** What the package can actually confirm on this platform. */
+	observed: BackupPostureValue;
+	/** iOS: the package. Android: the app's manifest. */
+	enforcedBy: 'package' | 'app-manifest';
+	/** Present when requested and observed disagree — the case that matters. */
+	warning?: string;
+};

package/src/contract/config.ts

@@ -1,54 +1,54 @@
-/**
- * Database configuration: everything an app supplies at open time.
- *
- * Immutable for the handle's lifetime. Scope in particular is bound here and
- * never changes (FR-008a) — there is no switchScope, and no operation takes a
- * scope argument, which is what makes cross-scope leakage inexpressible
- * rather than merely prevented.
- */
-
-import type { BackupConfig } from './backup';
-import type { EncryptionConfig } from './encryption';
-import type { Migration } from './migration';
-import type { CollectionSchema } from './schema';
-import type { ScopeDescriptor } from './scope';
-
-/** Phase-one budgets (FR-088). Confirmed against the harness during validation. */
-export const Budgets = {
-	MAX_RECORDS_PER_COLLECTION: 100_000,
-	MAX_RECORD_BYTES: 256 * 1024,
-	MAX_BATCH_OPERATIONS: 1_000,
-	MAX_PAGE_SIZE: 500,
-	MAX_COLLECTIONS_PER_DATABASE: 50,
-	MAX_ATTACHMENT_REFERENCES_PER_SCOPE: 50_000,
-	MAX_ARTIFACT_BYTES: 100 * 1024 * 1024,
-	MAX_OPEN_HANDLES: 8,
-	/** Plaintext chunk size for encrypted artifacts (research.md R4). */
-	ARTIFACT_CHUNK_BYTES: 256 * 1024,
-} as const;
-
-export type DatabaseConfig = {
-	name: string;
-	scope: ScopeDescriptor;
-	/** Must equal the highest version in `migrations` (FR-053). */
-	schemaVersion: number;
-	collections: CollectionSchema[];
-	migrations?: Migration[];
-	/** Absent means unencrypted (FR-097). */
-	encryption?: EncryptionConfig;
-	/** Absent means excluded from platform backup (FR-109). */
-	backup?: BackupConfig;
-	/** Governs whether deleting a record removes its artifacts (FR-070). */
-	cascadeAttachments?: boolean;
-};
-
-/** Names a scope for the operations that legitimately need to (FR-059). */
-export type ScopeTargetConfig = {
-	name: string;
-	scope: ScopeDescriptor;
-	encryption?: EncryptionConfig;
-};
-
-export type DatabaseTargetConfig = {
-	name: string;
-};
+/**
+ * Database configuration: everything an app supplies at open time.
+ *
+ * Immutable for the handle's lifetime. Scope in particular is bound here and
+ * never changes (FR-008a) — there is no switchScope, and no operation takes a
+ * scope argument, which is what makes cross-scope leakage inexpressible
+ * rather than merely prevented.
+ */
+
+import type { BackupConfig } from './backup';
+import type { EncryptionConfig } from './encryption';
+import type { Migration } from './migration';
+import type { CollectionSchema } from './schema';
+import type { ScopeDescriptor } from './scope';
+
+/** Phase-one budgets (FR-088). Confirmed against the harness during validation. */
+export const Budgets = {
+	MAX_RECORDS_PER_COLLECTION: 100_000,
+	MAX_RECORD_BYTES: 256 * 1024,
+	MAX_BATCH_OPERATIONS: 1_000,
+	MAX_PAGE_SIZE: 500,
+	MAX_COLLECTIONS_PER_DATABASE: 50,
+	MAX_ATTACHMENT_REFERENCES_PER_SCOPE: 50_000,
+	MAX_ARTIFACT_BYTES: 100 * 1024 * 1024,
+	MAX_OPEN_HANDLES: 8,
+	/** Plaintext chunk size for encrypted artifacts (research.md R4). */
+	ARTIFACT_CHUNK_BYTES: 256 * 1024,
+} as const;
+
+export type DatabaseConfig = {
+	name: string;
+	scope: ScopeDescriptor;
+	/** Must equal the highest version in `migrations` (FR-053). */
+	schemaVersion: number;
+	collections: CollectionSchema[];
+	migrations?: Migration[];
+	/** Absent means unencrypted (FR-097). */
+	encryption?: EncryptionConfig | undefined;
+	/** Absent means excluded from platform backup (FR-109). */
+	backup?: BackupConfig;
+	/** Governs whether deleting a record removes its artifacts (FR-070). */
+	cascadeAttachments?: boolean;
+};
+
+/** Names a scope for the operations that legitimately need to (FR-059). */
+export type ScopeTargetConfig = {
+	name: string;
+	scope: ScopeDescriptor;
+	encryption?: EncryptionConfig | undefined;
+};
+
+export type DatabaseTargetConfig = {
+	name: string;
+};

package/src/contract/encryption.ts

@@ -1,34 +1,34 @@
-/**
- * Opt-in encryption at rest under an app-supplied key.
- *
- * The package never generates, derives from its own material, persists,
- * caches beyond the handle's lifetime, transmits, or returns a key (FR-098).
- * Keeping key acquisition on the app side is also what keeps a keychain
- * dependency out of this package entirely (LIB-004).
- */
-
-import type { ResolvedScope } from './scope';
-
-/**
- * Implemented by the consuming app. Receives the scope so an app can key per
- * identity — which is what makes destroying one identity's key meaningful
- * (FR-104).
- */
-export type KeyProvider = {
-	getKey(scope: ResolvedScope): Promise<string>;
-};
-
-export type EncryptionConfig = {
-	enabled: true;
-	keyProvider: KeyProvider;
-};
-
-/**
- * What the package will say about its own at-rest posture. Reported so a
- * consumer can make an accurate privacy disclosure rather than assume one.
- */
-export type EncryptionPosture = {
-	enabled: boolean;
-	/** Whether SQLCipher is actually compiled into the app (research.md R1a). */
-	available: boolean;
-};
+/**
+ * Opt-in encryption at rest under an app-supplied key.
+ *
+ * The package never generates, derives from its own material, persists,
+ * caches beyond the handle's lifetime, transmits, or returns a key (FR-098).
+ * Keeping key acquisition on the app side is also what keeps a keychain
+ * dependency out of this package entirely (LIB-004).
+ */
+
+import type { ResolvedScope } from './scope';
+
+/**
+ * Implemented by the consuming app. Receives the scope so an app can key per
+ * identity — which is what makes destroying one identity's key meaningful
+ * (FR-104).
+ */
+export type KeyProvider = {
+	getKey(scope: ResolvedScope): Promise<string>;
+};
+
+export type EncryptionConfig = {
+	enabled: true;
+	keyProvider: KeyProvider;
+};
+
+/**
+ * What the package will say about its own at-rest posture. Reported so a
+ * consumer can make an accurate privacy disclosure rather than assume one.
+ */
+export type EncryptionPosture = {
+	enabled: boolean;
+	/** Whether SQLCipher is actually compiled into the app (research.md R1a). */
+	available: boolean;
+};