@chipmobilesdk/rn-local-db 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@chipmobilesdk/rn-local-db",
+	"version": "0.1.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./testing": {
+			"types": "./src/testing/index.ts",
+			"react-native": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/adapter",
+		"src/artifacts",
+		"src/contract",
+		"src/crypto",
+		"src/diagnostics",
+		"src/migration",
+		"src/platform",
+		"src/query",
+		"src/schema",
+		"src/scope",
+		"src/sqlite",
+		"src/testing",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"pack:dry-run": "npm pack --dry-run"
+	},
+	"peerDependencies": {
+		"@dr.pogodin/react-native-fs": ">=2.39.2",
+		"@op-engineering/op-sqlite": ">=17.1.0",
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-quick-crypto": ">=1.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react-native-quick-crypto": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=22.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/src/adapter/budgets.ts

@@ -0,0 +1,67 @@
+/**
+ * Where the FR-088 budgets are actually enforced.
+ *
+ * The checks live in `query/budgets.ts` so both adapters share them; this
+ * module is the adapter-layer entry point, and exists so there is one place
+ * to answer "which budgets are hard?" — per-record size, batch size, page
+ * size, and artifact size, each with a typed error (FR-088a).
+ *
+ * The rest are soft by design. Exceeding 100,000 records in a collection is
+ * slow, not an error, and refusing the 100,001st write would destroy data an
+ * app already holds. Degraded behavior is documented in the README instead.
+ */
+
+import { Budgets } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { StorableRecordData } from '../contract/record';
+import { raise } from '../diagnostics/errors';
+import {
+	assertArtifactWithinBudget,
+	assertBatchWithinBudget,
+	assertRecordWithinBudget,
+	serializedSize,
+} from '../query/budgets';
+
+export {
+	assertArtifactWithinBudget,
+	assertBatchWithinBudget,
+	assertRecordWithinBudget,
+	serializedSize,
+};
+
+/**
+ * Concurrently open handles.
+ *
+ * Each one holds a native connection and its write-ahead log, so an app that
+ * leaks handles runs out of file descriptors rather than slowing down. Eight
+ * is generous for the multi-identity case FR-008b describes and low enough
+ * that a leak surfaces during development instead of in the field.
+ */
+let openHandles = 0;
+
+export function acquireHandleSlot(): void {
+	if (openHandles >= Budgets.MAX_OPEN_HANDLES) {
+		raise(DiagnosticCodes.OPEN_FAILED, {
+			message: 'too many database handles are open',
+			detail: { count: openHandles, limit: Budgets.MAX_OPEN_HANDLES },
+		});
+	}
+	openHandles += 1;
+}
+
+export function releaseHandleSlot(): void {
+	openHandles = Math.max(0, openHandles - 1);
+}
+
+export function openHandleCount(): number {
+	return openHandles;
+}
+
+/** Between tests, and after a `deleteDatabase` that invalidated every handle. */
+export function resetHandleSlots(): void {
+	openHandles = 0;
+}
+
+export function assertWritable(collection: string, data: StorableRecordData): void {
+	assertRecordWithinBudget(collection, data);
+}

package/src/adapter/collection.ts

@@ -0,0 +1,298 @@
+/**
+ * Collection operations against a SQLite executor.
+ *
+ * The executor is either the connection or the transaction in flight on it,
+ * which is what gives read-your-own-writes for free (FR-043): a read inside a
+ * transaction runs on the same handle that made the writes, so it sees them,
+ * and a reader outside does not.
+ *
+ * Every semantic decision that could differ between the two adapters —
+ * which operators mean what, how nulls sort, what a cursor points at — is
+ * delegated to `query/`. This file decides only how to say it in SQL.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { FilterNode, Query, ResultPage } from '../contract/query';
+import type {
+	RecordInput,
+	StorableRecordData,
+	StoredRecord,
+	WriteOutcome,
+} from '../contract/record';
+import type { CollectionSchema } from '../contract/schema';
+import type { CollectionOps } from '../contract/transaction';
+import { raise } from '../diagnostics/errors';
+import { throwIfFaulted } from '../diagnostics/faults';
+import { decodeCursor } from '../query/cursor';
+import { buildPage, fetchLimitFor, resolvePageSize } from '../query/paginate';
+import { withStableTiebreaker } from '../query/sort';
+import { validateQuery } from '../query/validate';
+import { collectionTable, hasSoftDelete, hasTimestamps } from '../schema/declare';
+import type { Executor } from '../sqlite/connection';
+import type { SqlValue } from '../sqlite/native';
+import {
+	decodeRow,
+	encodePayload,
+	insertColumns,
+	projectedColumnNames,
+	projectedValues,
+	updateAssignments,
+} from '../sqlite/row-codec';
+import { buildFilter, buildKeysetPredicate, buildOrderBy } from '../sqlite/sql-builder';
+import { assertRecordWithinBudget } from './budgets';
+
+export type SqlCollectionContext = {
+	/** Resolved per call, so a transaction can swap in its own executor. */
+	executor(): Executor;
+	schema: CollectionSchema;
+	now(): number;
+	assertUsable(): void;
+};
+
+const LIVE = 'deleted_at IS NULL';
+
+function notFound(collection: string, id: string): never {
+	raise(DiagnosticCodes.RECORD_NOT_FOUND, {
+		message: 'record not found',
+		detail: { collection, recordId: id },
+	});
+}
+
+export function createSqlCollection<T extends StorableRecordData>(
+	context: SqlCollectionContext,
+): CollectionOps<T> {
+	const { schema } = context;
+	const table = `"${collectionTable(schema.name)}"`;
+
+	const selectColumns = ['id', 'payload', 'created_at', 'updated_at', 'deleted_at'].join(', ');
+
+	async function rowById(id: string, includeDeleted = false): Promise<Record<string, unknown> | undefined> {
+		const result = await context.executor().execute(
+			`SELECT ${selectColumns} FROM ${table} WHERE id = ?${includeDeleted ? '' : ` AND ${LIVE}`}`,
+			[id],
+		);
+		return result.rows[0];
+	}
+
+	return {
+		async insert(record: RecordInput<T>): Promise<WriteOutcome> {
+			context.assertUsable();
+			throwIfFaulted('write');
+			assertRecordWithinBudget(schema.name, record.data);
+
+			// Checked rather than left to the primary-key constraint: the
+			// constraint would work, but inside a transaction the engine's
+			// error can arrive after other statements have run, and reporting
+			// the conflict before touching anything keeps the failure boring.
+			if (await rowById(record.id, true)) {
+				raise(DiagnosticCodes.RECORD_CONFLICT, {
+					message: 'record already exists',
+					detail: { collection: schema.name, recordId: record.id },
+				});
+			}
+
+			const { columns, values } = insertColumns(schema, record.id, record.data, context.now());
+			await context
+				.executor()
+				.execute(
+					`INSERT INTO ${table} (${columns.map(name => `"${name}"`).join(', ')}) VALUES (${columns
+						.map(() => '?')
+						.join(', ')})`,
+					values,
+				);
+			return { operation: 'created', id: record.id };
+		},
+
+		async update(id, record): Promise<WriteOutcome> {
+			context.assertUsable();
+			throwIfFaulted('write');
+			assertRecordWithinBudget(schema.name, record.data);
+
+			const { columns, values } = updateAssignments(schema, record.data, context.now());
+			const result = await context
+				.executor()
+				.execute(
+					`UPDATE ${table} SET ${columns
+						.map(name => `"${name}" = ?`)
+						.join(', ')} WHERE id = ? AND ${LIVE}`,
+					[...values, id],
+				);
+			if (result.rowsAffected === 0) {
+				// Creating the record instead would be a silent write to an id
+				// the caller believed already existed.
+				notFound(schema.name, id);
+			}
+			return { operation: 'updated', id };
+		},
+
+		async upsert(record: RecordInput<T>): Promise<WriteOutcome> {
+			context.assertUsable();
+			throwIfFaulted('write');
+			assertRecordWithinBudget(schema.name, record.data);
+
+			const existed = (await rowById(record.id, true)) !== undefined;
+			const now = context.now();
+
+			if (existed) {
+				const assignments = ['payload = ?'];
+				const values: SqlValue[] = [encodePayload(record.data)];
+				if (hasTimestamps(schema)) {
+					assignments.push('updated_at = ?');
+					values.push(now);
+				}
+				if (hasSoftDelete(schema)) {
+					// An upsert over a soft-deleted record brings it back: the
+					// caller asked for this id to hold this data.
+					assignments.push('deleted_at = NULL');
+				}
+				const projected = projectedValues(schema, record.data);
+				for (const [index, name] of projectedColumnNames(schema).entries()) {
+					assignments.push(`"${name}" = ?`);
+					values.push(projected[index]!);
+				}
+				await context
+					.executor()
+					.execute(`UPDATE ${table} SET ${assignments.join(', ')} WHERE id = ?`, [
+						...values,
+						record.id,
+					]);
+				return { operation: 'updated', id: record.id };
+			}
+
+			const { columns, values } = insertColumns(schema, record.id, record.data, now);
+			await context
+				.executor()
+				.execute(
+					`INSERT INTO ${table} (${columns.map(name => `"${name}"`).join(', ')}) VALUES (${columns
+						.map(() => '?')
+						.join(', ')})`,
+					values,
+				);
+			return { operation: 'created', id: record.id };
+		},
+
+		async get(id: string): Promise<StoredRecord<T>> {
+			context.assertUsable();
+			throwIfFaulted('read');
+			const row = await rowById(id);
+			if (!row) {
+				notFound(schema.name, id);
+			}
+			return decodeRow<T>(schema, row);
+		},
+
+		async find(id: string): Promise<StoredRecord<T> | null> {
+			context.assertUsable();
+			throwIfFaulted('read');
+			const row = await rowById(id);
+			return row ? decodeRow<T>(schema, row) : null;
+		},
+
+		async delete(id: string): Promise<WriteOutcome> {
+			context.assertUsable();
+			throwIfFaulted('write');
+			const result = await context.executor().execute(`DELETE FROM ${table} WHERE id = ?`, [id]);
+			if (result.rowsAffected === 0) {
+				notFound(schema.name, id);
+			}
+			return { operation: 'deleted', id };
+		},
+
+		async softDelete(id: string): Promise<WriteOutcome> {
+			context.assertUsable();
+			throwIfFaulted('write');
+			if (!hasSoftDelete(schema)) {
+				raise(DiagnosticCodes.CONFIG_INVALID, {
+					message: 'collection does not declare soft delete',
+					detail: { collection: schema.name },
+				});
+			}
+			const result = await context
+				.executor()
+				.execute(`UPDATE ${table} SET deleted_at = ? WHERE id = ? AND ${LIVE}`, [
+					context.now(),
+					id,
+				]);
+			if (result.rowsAffected === 0) {
+				notFound(schema.name, id);
+			}
+			return { operation: 'deleted', id };
+		},
+
+		async restore(id: string): Promise<WriteOutcome> {
+			context.assertUsable();
+			throwIfFaulted('write');
+			if (!hasSoftDelete(schema)) {
+				raise(DiagnosticCodes.CONFIG_INVALID, {
+					message: 'collection does not declare soft delete',
+					detail: { collection: schema.name },
+				});
+			}
+			const result = await context
+				.executor()
+				.execute(`UPDATE ${table} SET deleted_at = NULL WHERE id = ? AND deleted_at IS NOT NULL`, [
+					id,
+				]);
+			if (result.rowsAffected === 0) {
+				notFound(schema.name, id);
+			}
+			return { operation: 'restored', id };
+		},
+
+		async list(query?: Query): Promise<ResultPage<T>> {
+			context.assertUsable();
+			throwIfFaulted('read');
+			validateQuery(schema, query);
+
+			const sort = withStableTiebreaker(query?.sort);
+			const size = resolvePageSize(query?.page);
+			const filter = buildFilter(query?.filter);
+
+			const clauses = [filter.sql];
+			const params: SqlValue[] = [...filter.params];
+
+			if (query?.includeSoftDeleted !== true) {
+				clauses.push(LIVE);
+			}
+			if (query?.page?.cursor) {
+				const keyset = buildKeysetPredicate(sort, decodeCursor(query.page.cursor, sort));
+				clauses.push(keyset.sql);
+				params.push(...keyset.params);
+			}
+
+			// One row past the page, so `hasMore` is answered without a second
+			// query that could disagree with the first under a concurrent write.
+			const limit = fetchLimitFor(size);
+			const result = await context
+				.executor()
+				.execute(
+					`SELECT ${selectColumns} FROM ${table} WHERE ${clauses.join(
+						' AND ',
+					)} ORDER BY ${buildOrderBy(sort)} LIMIT ?`,
+					[...params, limit],
+				);
+
+			return buildPage(
+				result.rows.map(row => decodeRow<T>(schema, row)),
+				sort,
+				size,
+			);
+		},
+
+		async count(filter?: FilterNode): Promise<number> {
+			context.assertUsable();
+			throwIfFaulted('read');
+			if (filter) {
+				validateQuery(schema, { filter });
+			}
+			const built = buildFilter(filter);
+			const result = await context
+				.executor()
+				.execute(
+					`SELECT count(*) AS total FROM ${table} WHERE ${built.sql} AND ${LIVE}`,
+					built.params,
+				);
+			return Number(result.rows[0]?.total ?? 0);
+		},
+	};
+}

package/src/adapter/deletion.ts

@@ -0,0 +1,238 @@
+/**
+ * Deletion, and the ordering that makes an interrupted one visible.
+ *
+ * These are module-level functions rather than handle methods because they
+ * must work whether or not a handle is open on the target (FR-059) — a
+ * sign-out that already closed the handle still has to be able to delete, and
+ * an app recovering from a crash has no handle to call a method on.
+ *
+ * The order is: **mark `deleting` first, clear the catalog row last**
+ * (FR-061, FR-063). A crash at any point in between leaves the flag set, so
+ * the next open reports a scope mid-deletion rather than presenting it as
+ * complete. Clearing the row first would be the natural way to write this and
+ * would produce exactly the failure FR-063 exists to prevent: an
+ * interruption that looks like a success, leaving a user's data on disk after
+ * they asked for it to be gone.
+ *
+ * Nothing here ever runs on its own. No expiry, no sweep, no deletion on
+ * close or on app upgrade (FR-058) — the package deletes when asked, where
+ * asked, and not otherwise.
+ */
+
+import type { DeletionOutcome } from '../contract/attachment';
+import type { DatabaseTargetConfig, ScopeTargetConfig } from '../contract/config';
+import type { ResolvedScope } from '../contract/scope';
+import { fileSystem, removeIfPresent } from '../platform/fs';
+import { layoutFor, type StorageLayout } from '../platform/location';
+import { artifactsDirectory } from '../artifacts/paths';
+import { acquireKey } from '../crypto/key-provider';
+import { byteOrder } from '../query/compare';
+import { resolveScope } from '../scope/validate';
+import { clearScope, ensureCatalog, listEntries, markDeleting, readEntry } from '../sqlite/catalog';
+import { openConnection, type Connection } from '../sqlite/connection';
+import { num, text } from '../sqlite/values';
+
+/**
+ * Scopes deleted beneath a handle that is still open.
+ *
+ * FR-059a wants the handle to report `SCOPE_DELETED` rather than keep
+ * answering from a database that no longer exists — and wants the deletion to
+ * proceed rather than wait for the handle to be closed. A shared set is the
+ * whole mechanism: the deleter records, the handle checks.
+ */
+const invalidated = new Set<string>();
+
+function invalidationKey(name: string, scopeKey: string): string {
+	return `${name}:${scopeKey}`;
+}
+
+export function markScopeInvalidated(name: string, scopeKey: string): void {
+	invalidated.add(invalidationKey(name, scopeKey));
+}
+
+export function clearScopeInvalidation(name: string, scopeKey: string): void {
+	invalidated.delete(invalidationKey(name, scopeKey));
+}
+
+export function isScopeInvalidated(name: string, scopeKey: string): boolean {
+	return invalidated.has(invalidationKey(name, scopeKey));
+}
+
+export function clearAllInvalidations(): void {
+	invalidated.clear();
+}
+
+/** Deleting a scope that holds nothing is success, not an error (FR-062). */
+export function emptyOutcome(scope?: ResolvedScope): DeletionOutcome {
+	return {
+		...(scope ? { scopeKey: scope.key } : {}),
+		removedRecords: 0,
+		removedArtifacts: [],
+		orphanedReferences: [],
+		failedRemovals: [],
+	};
+}
+
+/**
+ * How many records the scope held, best effort.
+ *
+ * Best effort because an encrypted scope whose caller supplied no key cannot
+ * be opened to be counted — and refusing to delete it on that basis would be
+ * the worst possible answer to a deletion request. The files come off disk
+ * either way; only the number in the report is unavailable.
+ */
+async function countRecords(
+	layout: StorageLayout,
+	scopeKey: string,
+	encryptionKey: string | undefined,
+): Promise<number> {
+	let connection: Connection | null = null;
+	try {
+		connection = await openConnection({
+			path: layout.scopeDataPath(scopeKey),
+			...(encryptionKey ? { encryptionKey } : {}),
+		});
+		const tables = await connection.execute(
+			"SELECT name FROM sqlite_master WHERE type = 'table' AND name LIKE 'c!_%' ESCAPE '!'",
+		);
+		let total = 0;
+		for (const row of tables.rows) {
+			const table = text(row.name);
+			const counted = await connection.execute(`SELECT count(*) AS total FROM "${table}"`);
+			total += num(counted.rows[0]?.total ?? 0);
+		}
+		return total;
+	} catch {
+		return 0;
+	} finally {
+		await connection?.close();
+	}
+}
+
+async function artifactIdsOnDisk(layout: StorageLayout, scopeKey: string): Promise<string[]> {
+	try {
+		return (await fileSystem().readdir(artifactsDirectory(layout, scopeKey))).sort(byteOrder);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * The one implementation behind `deleteScopeData` and `resetScope`.
+ *
+ * They do the same thing to disk and mean entirely different things to the
+ * caller: one is a lifecycle operation an app performs on request, the other
+ * is an admission that a database is broken and is being discarded to recover
+ * from it (FR-057a). Keeping them as two exported names with two docstrings
+ * is what stops the destructive one from being reached by accident — there is
+ * no path from `openDatabase` to either.
+ */
+async function removeScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	const scope = resolveScope(config.scope);
+	const layout = layoutFor(config.name);
+	const catalog = await openConnection({ path: layout.catalogPath });
+
+	try {
+		await ensureCatalog(catalog);
+		const entry = await readEntry(catalog, scope.key);
+
+		// Mark first. Everything after this point is recoverable-in-principle;
+		// this flag is what makes an interruption visible rather than silent.
+		if (entry) {
+			await markDeleting(catalog, scope.key);
+		}
+		markScopeInvalidated(config.name, scope.key);
+
+		const removedArtifacts = await artifactIdsOnDisk(layout, scope.key);
+
+		// The key is needed to count what is being removed, not to remove it.
+		// It is released the moment the count is done, whatever happened.
+		const keyHandle = config.encryption?.enabled
+			? await acquireKey(config.encryption, scope)
+			: null;
+		let removedRecords: number;
+		try {
+			removedRecords = await countRecords(layout, scope.key, keyHandle?.value());
+		} finally {
+			keyHandle?.release();
+		}
+
+		const failedRemovals: string[] = [];
+		if (!(await removeIfPresent(layout.scopePath(scope.key))) && entry) {
+			// The directory was there and would not go. Reporting it is the
+			// point: an app that told the user "deleted" would be wrong.
+			const stillThere = await fileSystem()
+				.exists(layout.scopePath(scope.key))
+				.catch(() => false);
+			if (stillThere) {
+				failedRemovals.push(scope.key);
+			}
+		}
+
+		if (failedRemovals.length === 0) {
+			// Cleared last, on purpose.
+			await clearScope(catalog, scope.key);
+		}
+
+		return {
+			scopeKey: scope.key,
+			removedRecords,
+			removedArtifacts,
+			orphanedReferences: [],
+			failedRemovals,
+		};
+	} finally {
+		await catalog.close();
+	}
+}
+
+/**
+ * Remove one scope's data. Every collection in that scope, and nothing
+ * outside it (FR-059, SC-012).
+ */
+export function deleteScopeData(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return removeScope(config);
+}
+
+/**
+ * Discard one scope and leave it ready for a clean first-run migration
+ * (FR-057a).
+ *
+ * Destructive, separately named, and never reachable from `openDatabase`. An
+ * automatic fallback here would turn a bad migration shipped to production
+ * into silent data loss for every user who launched the app.
+ */
+export function resetScope(config: ScopeTargetConfig): Promise<DeletionOutcome> {
+	return removeScope(config);
+}
+
+/** Remove the whole database directory: catalog, every scope, every artifact. */
+export async function deleteDatabase(config: DatabaseTargetConfig): Promise<DeletionOutcome> {
+	const layout = layoutFor(config.name);
+
+	let scopeKeys: string[] = [];
+	try {
+		const catalog = await openConnection({ path: layout.catalogPath });
+		try {
+			await ensureCatalog(catalog);
+			scopeKeys = (await listEntries(catalog)).map(entry => entry.scopeKey);
+		} finally {
+			await catalog.close();
+		}
+	} catch {
+		// No catalog means nothing was ever registered here. The directory
+		// removal below is still the right thing to attempt.
+	}
+
+	for (const scopeKey of scopeKeys) {
+		markScopeInvalidated(config.name, scopeKey);
+	}
+
+	const removed = await removeIfPresent(layout.root);
+	return {
+		removedRecords: 0,
+		removedArtifacts: [],
+		orphanedReferences: [],
+		failedRemovals: removed || scopeKeys.length === 0 ? [] : scopeKeys,
+	};
+}