@chipmobilesdk/rn-local-db 0.2.1 → 0.4.0

package/src/sqlite/native.ts

@@ -8,8 +8,10 @@
  * express the synchronous call is a stronger guarantee than a review comment.
  */
 
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
 import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
+import { StorageError } from '../diagnostics/errors';
 
 export type SqlValue = string | number | boolean | null | undefined;
 
@@ -44,30 +46,29 @@ export type Engine = {
 	isSQLCipher?: () => boolean;
 };
 
-let override: Engine | null = null;
-let cached: Engine | null = null;
+/** Loaded on first use (rn-core's lazy peer); a missing peer is `OPEN_FAILED`. */
+const sqlite = lazyPeer('@op-engineering/op-sqlite', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('@op-engineering/op-sqlite') as Engine;
+	} catch (cause) {
+		throw cause;
+	}
+});
 
-/** Swap the engine. Tests only. */
+/** Swap the engine. Tests only; `null` goes back to the real one. */
 export function setEngine(next: Engine | null): void {
-	override = next;
-	cached = null;
+	sqlite.override(next ?? undefined);
 }
 
 export function engine(): Engine {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('@op-engineering/op-sqlite') as Engine;
-		} catch (error) {
-			raise(DiagnosticCodes.OPEN_FAILED, {
+	return sqlite.require(
+		(_peer, cause) =>
+			new StorageError(DiagnosticCodes.OPEN_FAILED, {
 				message: 'storage engine peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
+				cause,
+			}),
+	);
 }
 
 /**

package/src/sqlite/row-codec.ts

@@ -176,9 +176,11 @@ export function insertColumns(
 	id: string,
 	data: StorableRecordData,
 	now: number,
+	/** The payload already serialized by the budget check, to avoid a second pass. */
+	payload: string = encodePayload(data),
 ): WriteColumns {
 	const columns = ['id', 'payload'];
-	const values: SqlValue[] = [id, encodePayload(data)];
+	const values: SqlValue[] = [id, payload];
 
 	if (hasTimestamps(schema)) {
 		columns.push('created_at', 'updated_at');
@@ -200,9 +202,10 @@ export function updateAssignments(
 	schema: CollectionSchema,
 	data: StorableRecordData,
 	now: number,
+	payload: string = encodePayload(data),
 ): WriteColumns {
 	const columns = ['payload'];
-	const values: SqlValue[] = [encodePayload(data)];
+	const values: SqlValue[] = [payload];
 
 	if (hasTimestamps(schema)) {
 		columns.push('updated_at');

package/src/sqlite/statements.ts

@@ -0,0 +1,74 @@
+/**
+ * The write statements, built in one place (LDB-12).
+ *
+ * The collection API and the batch each used to assemble their own INSERT and
+ * UPDATE text. Two copies of the same rule is how a batch upsert came to treat
+ * a soft-deleted row differently from a collection upsert.
+ */
+import type { CollectionSchema } from '../contract/schema';
+import { collectionTable, hasSoftDelete } from '../schema/declare';
+import type { SqlValue } from './native';
+import { insertColumns, updateAssignments } from './row-codec';
+
+export type Statement = [sql: string, params: SqlValue[]];
+
+type RecordData = Parameters<typeof insertColumns>[2];
+
+// Built once per table and column list rather than on every write (PERF-10).
+const insertTexts = new Map<string, string>();
+
+function insertText(table: string, columns: readonly string[]): string {
+	const key = `${table}|${columns.join(',')}`;
+	let sql = insertTexts.get(key);
+	if (sql === undefined) {
+		sql = `INSERT INTO "${table}" (${columns.map(name => `"${name}"`).join(', ')}) VALUES (${columns
+			.map(() => '?')
+			.join(', ')})`;
+		insertTexts.set(key, sql);
+	}
+	return sql;
+}
+
+/**
+ * `ignore` leaves a row that already holds the id untouched and reports zero
+ * rows affected, so a conflict is detected without a SELECT beforehand.
+ */
+export function insertStatement(
+	schema: CollectionSchema,
+	id: string,
+	data: RecordData,
+	now: number,
+	payload: string,
+	onConflict: 'fail' | 'ignore' = 'fail',
+): Statement {
+	const { columns, values } = insertColumns(schema, id, data, now, payload);
+	const sql = insertText(collectionTable(schema.name), columns);
+	return [onConflict === 'ignore' ? `${sql} ON CONFLICT(id) DO NOTHING` : sql, values];
+}
+
+export type UpdateOptions = {
+	/** Clear `deleted_at`: an upsert over a soft-deleted record brings it back. */
+	restore?: boolean;
+	/** Match only a record that is not soft-deleted. */
+	liveOnly?: boolean;
+};
+
+export function updateStatement(
+	schema: CollectionSchema,
+	id: string,
+	data: RecordData,
+	now: number,
+	payload: string,
+	options: UpdateOptions = {},
+): Statement {
+	const { columns, values } = updateAssignments(schema, data, now, payload);
+	const assignments = columns.map(name => `"${name}" = ?`);
+	if (options.restore === true && hasSoftDelete(schema)) {
+		assignments.push('deleted_at = NULL');
+	}
+	const live = options.liveOnly === true ? ' AND deleted_at IS NULL' : '';
+	return [
+		`UPDATE "${collectionTable(schema.name)}" SET ${assignments.join(', ')} WHERE id = ?${live}`,
+		[...values, id],
+	];
+}

package/src/testing/conformance/attachments.ts

@@ -1,5 +1,6 @@
 import { DiagnosticCodes } from '../../contract/errors';
 import { isCode } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../../platform/bytes';
 import type { ConformanceContext } from './index';
 
 /** US7: artifacts the package owns, and the reconciliation that keeps them honest. */
@@ -8,7 +9,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 		beforeEach(() => context.reset());
 
 		const scope = { kind: 'guest' } as const;
-		const content = Buffer.from('hello attachment', 'utf8').toString('base64');
+		const content = bytesToBase64(utf8Bytes('hello attachment'));
 
 		it('stores a reference alongside the artifact', async () => {
 			const handle = await context.adapter.open(context.configFor(scope));
@@ -20,7 +21,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 				content,
 			});
 
-			expect(reference.size).toBe(Buffer.from(content, 'base64').length);
+			expect(reference.size).toBe(base64ToBytes(content).length);
 			expect(await attachments.read('a1')).toBe(content);
 			expect((await attachments.availability('a1')).state).toBe('available');
 			await handle.close();
@@ -32,7 +33,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 			await attachments.write({ id: 'a1', contentType: 'text/plain', content });
 
 			const slice = await attachments.read('a1', { offset: 0, length: 5 });
-			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('hello');
+			expect(utf8String(base64ToBytes(slice))).toBe('hello');
 			await handle.close();
 		});
 
@@ -112,7 +113,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 
 		it('rejects an artifact over the size budget', async () => {
 			const handle = await context.adapter.open(context.configFor(scope));
-			const huge = Buffer.alloc(101 * 1024 * 1024).toString('base64');
+			const huge = bytesToBase64(new Uint8Array(101 * 1024 * 1024));
 
 			let thrown: unknown;
 			try {

package/src/testing/conformance/encryption.ts

@@ -1,6 +1,7 @@
 import { DiagnosticCodes } from '../../contract/errors';
 import type { KeyProvider } from '../../contract/encryption';
 import { isCode } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../../platform/bytes';
 import type { ConformanceContext } from './index';
 
 /** US10: opt-in encryption, and failures that stay apart from each other. */
@@ -47,12 +48,12 @@ export function registerEncryptionConformance(context: ConformanceContext): void
 			const handle = await context.adapter.open(
 				context.configFor(scope, { encryption: encrypted }),
 			);
-			const content = Buffer.from('hello encrypted attachment', 'utf8').toString('base64');
+			const content = bytesToBase64(utf8Bytes('hello encrypted attachment'));
 			await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
 
 			expect(await handle.attachments().read('a1')).toBe(content);
 			const slice = await handle.attachments().read('a1', { offset: 6, length: 9 });
-			expect(Buffer.from(slice, 'base64').toString('utf8')).toBe('encrypted');
+			expect(utf8String(base64ToBytes(slice))).toBe('encrypted');
 			expect((await handle.attachments().availability('a1')).state).toBe('available');
 			await handle.close();
 		});

package/src/testing/conformance/index.ts

@@ -59,7 +59,7 @@ export type ConformanceOptions = {
 	 * — an encrypted database that quietly behaved differently would be a
 	 * second implementation nobody tested.
 	 */
-	encryption?: EncryptionConfig;
+	encryption?: EncryptionConfig | undefined;
 };
 
 export type ConformanceSection =

package/src/testing/index.ts

@@ -8,6 +8,8 @@
 export { createMemoryAdapter, type MemoryAdapterOptions } from './memory-adapter';
 export { memoryConformanceHooks, resetMemoryAdapter, seedRecords } from './memory-adapter/reset';
 export { clearFaults, injectFault, type FaultPoint, type FaultSpec } from './faults';
+/** Makes `openDatabase` and the deletion functions use the given adapter; `null` restores the device one. */
+export { setStorageAdapter } from '../adapter';
 export {
 	runConformanceSuite,
 	type ConformanceContext,

package/src/testing/memory-adapter/attachments.ts

@@ -0,0 +1,146 @@
+/**
+ * The in-memory adapter's attachments (FR-091).
+ *
+ * The same surface the SQLite adapter exposes, over the store's maps: written
+ * whole rather than chunked, no filesystem, and a `sourcePath` read through the
+ * `readSourceFile` option a test supplies. Divergences are documented in the
+ * package README.
+ */
+import type { Attachments } from '../../contract/adapter';
+import type {
+	AttachmentInput,
+	AttachmentOwner,
+	AttachmentReference,
+	ByteRange,
+	DeletionOutcome,
+	ReconciliationReport,
+} from '../../contract/attachment';
+import { DiagnosticCodes } from '../../contract/errors';
+import { raise } from '../../diagnostics/errors';
+import { base64ToBytes, bytesToBase64 } from '../../platform/bytes';
+import { assertArtifactWithinBudget } from '../../query/budgets';
+import { assertValidAttachmentId } from '../../platform/location';
+import { throwIfFaulted } from '../faults';
+import type { MemoryScopeStore } from './store';
+import type { MemoryAdapterOptions } from './index';
+
+/** What one artifact removal has to wait for: the transaction that caused it. */
+export interface Deferred {
+	add(id: string): void;
+}
+
+export interface MemoryAttachmentDeps {
+	store: MemoryScopeStore;
+	options: MemoryAdapterOptions;
+	now: () => number;
+	assertOpen: () => void;
+}
+
+export function createMemoryAttachments(deps: MemoryAttachmentDeps) {
+	const { store, options, now, assertOpen } = deps;
+
+	return (deferred?: Deferred): Attachments => ({
+		async write(input: AttachmentInput): Promise<AttachmentReference> {
+			assertOpen();
+			throwIfFaulted('attachmentWrite');
+			assertValidAttachmentId(input.id);
+			let content = input.content;
+			if (content === undefined) {
+				if (!options.readSourceFile) {
+					raise(DiagnosticCodes.STORAGE_ACCESS, {
+						message: 'the memory adapter was not given readSourceFile',
+						detail: { attachmentId: input.id },
+					});
+				}
+				content = await options.readSourceFile(input.sourcePath ?? '');
+			}
+			const bytes = base64ToBytes(content);
+			assertArtifactWithinBudget(input.id, bytes.length);
+			const reference: AttachmentReference = {
+				id: input.id,
+				owner: input.owner,
+				contentType: input.contentType,
+				size: bytes.length,
+				createdAt: now(),
+			};
+			store.artifacts.set(input.id, content);
+			store.attachments.set(input.id, reference);
+			return reference;
+		},
+		async read(id: string, range?: ByteRange): Promise<string> {
+			assertOpen();
+			// No paths here to escape, but an id the device build would refuse
+			// has to be refused here too, or a consumer's passing tests stop
+			// predicting the device (FR-096).
+			assertValidAttachmentId(id);
+			const content = store.artifacts.get(id);
+			if (content === undefined) {
+				raise(DiagnosticCodes.ATTACHMENT_MISSING, {
+					message: 'artifact is missing',
+					detail: { attachmentId: id },
+				});
+			}
+			if (!range) {
+				return content;
+			}
+			const bytes = base64ToBytes(content);
+			return bytesToBase64(bytes.subarray(range.offset, range.offset + range.length));
+		},
+		async availability(id) {
+			assertOpen();
+			const reference = store.attachments.get(id);
+			if (!reference) {
+				return { id, state: 'missing' };
+			}
+			return store.artifacts.has(id)
+				? { id, state: 'available', size: reference.size }
+				: { id, state: 'missing' };
+		},
+		async remove(id: string): Promise<DeletionOutcome> {
+			assertOpen();
+			assertValidAttachmentId(id);
+			if (deferred) {
+				const hadReference = store.attachments.delete(id);
+				if (hadReference) deferred.add(id);
+				return {
+					removedRecords: 0,
+					removedArtifacts: hadReference ? [id] : [],
+					orphanedReferences: [],
+					failedRemovals: [],
+				};
+			}
+			const removed = store.artifacts.delete(id);
+			store.attachments.delete(id);
+			return {
+				removedRecords: 0,
+				removedArtifacts: removed ? [id] : [],
+				orphanedReferences: [],
+				failedRemovals: [],
+			};
+		},
+		async listFor(owner: AttachmentOwner): Promise<AttachmentReference[]> {
+			assertOpen();
+			return [...store.attachments.values()].filter(
+				reference =>
+					reference.owner?.collection === owner.collection && reference.owner?.id === owner.id,
+			);
+		},
+		async reconcile(reconcileOptions): Promise<ReconciliationReport> {
+			assertOpen();
+			const orphanedArtifacts = [...store.artifacts.keys()].filter(
+				id => !store.attachments.has(id),
+			);
+			const danglingReferences = [...store.attachments.keys()].filter(
+				id => !store.artifacts.has(id),
+			);
+			const removedArtifacts: string[] = [];
+			if (reconcileOptions?.removeOrphans) {
+				for (const id of orphanedArtifacts) {
+					store.artifacts.delete(id);
+					removedArtifacts.push(id);
+				}
+			}
+			return { orphanedArtifacts, danglingReferences, removedArtifacts };
+		},
+	});
+}

package/src/testing/memory-adapter/index.ts

@@ -7,14 +7,7 @@
  */
 
 import { createTransactionQueue } from '../../sqlite/transaction-queue';
-import type {
-	AttachmentInput,
-	AttachmentReference,
-	AttachmentOwner,
-	ByteRange,
-	DeletionOutcome,
-	ReconciliationReport,
-} from '../../contract/attachment';
+import type { DeletionOutcome } from '../../contract/attachment';
 import type { EffectivePosture } from '../../contract/backup';
 import type {
 	DatabaseConfig,
@@ -31,12 +24,11 @@ import type {
 	CollectionOps,
 	Transaction,
 } from '../../contract/transaction';
-import type { Attachments, DatabaseHandle, StorageAdapter } from '../../contract/adapter';
+import type { DatabaseHandle, StorageAdapter } from '../../contract/adapter';
 import { acquireKey } from '../../crypto/key-provider';
 import { instrument } from '../../diagnostics/dev-log';
 import { raise } from '../../diagnostics/errors';
-import { assertValidAttachmentId } from '../../platform/location';
-import { assertBatchWithinBudget, assertArtifactWithinBudget } from '../../query/budgets';
+import { assertBatchWithinBudget } from '../../query/budgets';
 import { validateConfig } from '../../schema/validate-config';
 import { resolveScope } from '../../scope/validate';
 import { runMigrations } from './migrations';
@@ -49,11 +41,18 @@ import {
 	scopeStoreFor,
 	type MemoryScopeStore,
 } from './store';
+import { createMemoryAttachments } from './attachments';
 import { throwIfFaulted } from '../faults';
 
 export type MemoryAdapterOptions = {
 	/** Fixed clock, so timestamp assertions are deterministic. */
 	now?: () => number;
+	/**
+	 * What a `sourcePath` attachment reads, as base64. There is no filesystem
+	 * behind this adapter, so a test that writes attachments by path supplies
+	 * the bytes here; without it such a write is refused with `STORAGE_ACCESS`.
+	 */
+	readSourceFile?: (path: string) => Promise<string> | string;
 };
 
 function schemaIndex(collections: CollectionSchema[]): Map<string, CollectionSchema> {
@@ -188,11 +187,8 @@ export function createMemoryAdapter(options: MemoryAdapterOptions = {}): Storage
 			const ops = instrument(
 				name,
 				'memory',
-				createMemoryCollection<T>({ store, schema, now, assertOpen }) as unknown as Record<
-					string,
-					(...args: never[]) => unknown
-				>,
-			) as unknown as CollectionOps<T>;
+				createMemoryCollection<T>({ store, schema, now, assertOpen }),
+			);
 			if (config.cascadeAttachments !== true) {
 				return ops;
 			}
@@ -214,100 +210,7 @@ export function createMemoryAdapter(options: MemoryAdapterOptions = {}): Storage
 			enforcedBy: 'package',
 		};
 
-		const rawAttachments = (deferred?: Deferred): Attachments => ({
-			async write(input: AttachmentInput): Promise<AttachmentReference> {
-				assertOpen();
-				throwIfFaulted('attachmentWrite');
-				assertValidAttachmentId(input.id);
-				const bytes = Buffer.from(input.content, 'base64');
-				assertArtifactWithinBudget(input.id, bytes.length);
-				const reference: AttachmentReference = {
-					id: input.id,
-					owner: input.owner,
-					contentType: input.contentType,
-					size: bytes.length,
-					createdAt: now(),
-				};
-				store.artifacts.set(input.id, input.content);
-				store.attachments.set(input.id, reference);
-				return reference;
-			},
-			async read(id: string, range?: ByteRange): Promise<string> {
-				assertOpen();
-				// No paths here to escape, but an id the device build would refuse
-				// has to be refused here too, or a consumer's passing tests stop
-				// predicting the device (FR-096).
-				assertValidAttachmentId(id);
-				const content = store.artifacts.get(id);
-				if (content === undefined) {
-					raise(DiagnosticCodes.ATTACHMENT_MISSING, {
-						message: 'artifact is missing',
-						detail: { attachmentId: id },
-					});
-				}
-				if (!range) {
-					return content;
-				}
-				const bytes = Buffer.from(content, 'base64');
-				return bytes.subarray(range.offset, range.offset + range.length).toString('base64');
-			},
-			async availability(id) {
-				assertOpen();
-				const reference = store.attachments.get(id);
-				if (!reference) {
-					return { id, state: 'missing' };
-				}
-				return store.artifacts.has(id)
-					? { id, state: 'available', size: reference.size }
-					: { id, state: 'missing' };
-			},
-			async remove(id: string): Promise<DeletionOutcome> {
-				assertOpen();
-				assertValidAttachmentId(id);
-				if (deferred) {
-					const hadReference = store.attachments.delete(id);
-					if (hadReference) deferred.add(id);
-					return {
-						removedRecords: 0,
-						removedArtifacts: hadReference ? [id] : [],
-						orphanedReferences: [],
-						failedRemovals: [],
-					};
-				}
-				const removed = store.artifacts.delete(id);
-				store.attachments.delete(id);
-				return {
-					removedRecords: 0,
-					removedArtifacts: removed ? [id] : [],
-					orphanedReferences: [],
-					failedRemovals: [],
-				};
-			},
-			async listFor(owner: AttachmentOwner): Promise<AttachmentReference[]> {
-				assertOpen();
-				return [...store.attachments.values()].filter(
-					reference =>
-						reference.owner?.collection === owner.collection && reference.owner?.id === owner.id,
-				);
-			},
-			async reconcile(reconcileOptions): Promise<ReconciliationReport> {
-				assertOpen();
-				const orphanedArtifacts = [...store.artifacts.keys()].filter(
-					id => !store.attachments.has(id),
-				);
-				const danglingReferences = [...store.attachments.keys()].filter(
-					id => !store.artifacts.has(id),
-				);
-				const removedArtifacts: string[] = [];
-				if (reconcileOptions?.removeOrphans) {
-					for (const id of orphanedArtifacts) {
-						store.artifacts.delete(id);
-						removedArtifacts.push(id);
-					}
-				}
-				return { orphanedArtifacts, danglingReferences, removedArtifacts };
-			},
-		});
+		const rawAttachments = createMemoryAttachments({ store, options, now, assertOpen });
 		const attachments = queued(rawAttachments());
 
 		/**

package/src/testing/memory-adapter/store.ts

@@ -16,9 +16,9 @@ export type MemoryRow = {
 	/** Serialized on write, parsed on read — the same payload-as-truth rule
 	 * the SQLite adapter follows, so a mutation after write cannot leak in. */
 	payload: string;
-	createdAt?: number;
-	updatedAt?: number;
-	deletedAt?: number | null;
+	createdAt?: number | undefined;
+	updatedAt?: number | undefined;
+	deletedAt?: number | null | undefined;
 };
 
 export type MemoryScopeStore = {