@chipmobilesdk/rn-local-db 0.1.0

package/src/sqlite/native.ts

@@ -0,0 +1,83 @@
+/**
+ * The storage engine peer, behind one lazy accessor.
+ *
+ * Every native call the package makes to SQLite passes through this type.
+ * Note what is missing: `executeSync`. op-sqlite ships it, and using it would
+ * put a database read on the interface thread — the one thing PERF-001's
+ * 16-millisecond rule cannot survive (research.md R9). A surface that cannot
+ * express the synchronous call is a stronger guarantee than a review comment.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+
+export type SqlValue = string | number | boolean | null | undefined;
+
+export type ExecuteResult = {
+	rows: Record<string, unknown>[];
+	rowsAffected: number;
+};
+
+export type NativeTransaction = {
+	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+	commit(): Promise<void>;
+	rollback(): Promise<void>;
+};
+
+export type NativeDatabase = {
+	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+	executeBatch(commands: [string, SqlValue[]?][]): Promise<ExecuteResult>;
+	transaction<T>(fn: (tx: NativeTransaction) => Promise<T>): Promise<T>;
+	close(): Promise<void>;
+	delete(): Promise<void>;
+};
+
+export type OpenOptions = {
+	name: string;
+	location?: string;
+	/** SQLCipher only. Never logged, never persisted, never returned (FR-098). */
+	encryptionKey?: string;
+};
+
+export type Engine = {
+	open(options: OpenOptions): NativeDatabase;
+	isSQLCipher?: () => boolean;
+};
+
+let override: Engine | null = null;
+let cached: Engine | null = null;
+
+/** Swap the engine. Tests only. */
+export function setEngine(next: Engine | null): void {
+	override = next;
+	cached = null;
+}
+
+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, {
+				message: 'storage engine peer is not installed',
+				cause: error,
+			});
+		}
+	}
+	return cached!;
+}
+
+/**
+ * Whether SQLCipher is compiled into this build.
+ *
+ * A build flag in the consuming app, not a separate peer (research.md R1a).
+ * An app that enables encryption without it must fail loudly rather than
+ * write plaintext to a file it believes is encrypted.
+ */
+export function isEncryptionAvailable(): boolean {
+	const current = engine();
+	return typeof current.isSQLCipher === 'function' ? current.isSQLCipher() === true : false;
+}

package/src/sqlite/row-codec.ts

@@ -0,0 +1,201 @@
+/**
+ * Table shape, and the payload-as-truth rule.
+ *
+ * Every read reconstructs the record from `payload` alone. The projected
+ * `f_*` columns are written on every write and consulted only by `WHERE` and
+ * `ORDER BY` — never by a read path (research.md R6).
+ *
+ * That single rule is what makes two requirements structural rather than
+ * carefully maintained. FR-018's byte fidelity holds because nothing else is
+ * consulted to rebuild a record, and FR-019's explicit-null versus
+ * absent-field distinction holds because a NULL projected column cannot be
+ * ambiguous if no read ever looks at it.
+ */
+
+import type { StorableRecordData, StoredRecord } from '../contract/record';
+import type { CollectionSchema, FieldDeclaration } from '../contract/schema';
+import { collectionTable, hasSoftDelete, hasTimestamps, projectedColumn } from '../schema/declare';
+import type { SqlValue } from './native';
+import { num, text } from './values';
+
+export const RESERVED_COLUMNS = ['id', 'payload', 'created_at', 'updated_at', 'deleted_at'];
+
+/** SQLite affinity for a declared field type. */
+function affinityOf(field: FieldDeclaration): string {
+	switch (field.type) {
+		case 'number':
+		case 'timestamp':
+			return 'REAL';
+		case 'boolean':
+			return 'INTEGER';
+		case 'string':
+		default:
+			return 'TEXT';
+	}
+}
+
+export function createTableSql(schema: CollectionSchema): string {
+	const columns = [
+		'id TEXT PRIMARY KEY',
+		'payload TEXT NOT NULL',
+		'created_at INTEGER',
+		'updated_at INTEGER',
+		'deleted_at INTEGER',
+		...(schema.fields ?? []).map(
+			field => `"${projectedColumn(field.name)}" ${affinityOf(field)}`,
+		),
+	];
+	return `CREATE TABLE IF NOT EXISTS "${collectionTable(schema.name)}" (${columns.join(', ')})`;
+}
+
+export function addColumnSql(schema: CollectionSchema, field: FieldDeclaration): string {
+	return `ALTER TABLE "${collectionTable(schema.name)}" ADD COLUMN "${projectedColumn(
+		field.name,
+	)}" ${affinityOf(field)}`;
+}
+
+export function createIndexSql(schema: CollectionSchema): string[] {
+	const table = collectionTable(schema.name);
+	const statements = (schema.indexes ?? []).map(index => {
+		const columns = index.fields.map(field => `"${projectedColumn(field)}"`).join(', ');
+		return `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS "${
+			index.name
+		}" ON "${table}" (${columns})`;
+	});
+	if (hasSoftDelete(schema)) {
+		// Every default query carries `deleted_at IS NULL`, so without this the
+		// exclusion turns the cheapest possible filter into a full scan.
+		statements.push(
+			`CREATE INDEX IF NOT EXISTS "${table}_live" ON "${table}" (deleted_at)`,
+		);
+	}
+	return statements;
+}
+
+/**
+ * Project a declared field for the WHERE and ORDER BY columns.
+ *
+ * Anything that is not a comparable primitive projects to NULL. A nested
+ * object has no defensible ordering, and inventing one would make a filter
+ * silently match records a consumer never meant to select.
+ */
+export function projectValue(data: StorableRecordData, field: FieldDeclaration): SqlValue {
+	if (!Object.prototype.hasOwnProperty.call(data, field.name)) {
+		return null;
+	}
+	const value = data[field.name];
+	if (value === null) {
+		return null;
+	}
+	switch (typeof value) {
+		case 'boolean':
+			return value ? 1 : 0;
+		case 'number':
+			return Number.isFinite(value) ? value : null;
+		case 'string':
+			return value;
+		default:
+			return null;
+	}
+}
+
+export function projectedValues(schema: CollectionSchema, data: StorableRecordData): SqlValue[] {
+	return (schema.fields ?? []).map(field => projectValue(data, field));
+}
+
+export function projectedColumnNames(schema: CollectionSchema): string[] {
+	return (schema.fields ?? []).map(field => projectedColumn(field.name));
+}
+
+/** Serialize on the way in, so a caller mutating its object cannot change
+ * what is stored (FR-022). */
+export function encodePayload(data: StorableRecordData): string {
+	return JSON.stringify(data ?? {});
+}
+
+export type CollectionRow = {
+	id: string;
+	payload: string;
+	created_at?: number | null;
+	updated_at?: number | null;
+	deleted_at?: number | null;
+};
+
+/**
+ * Rebuild a record from the payload column and nothing else.
+ *
+ * The timestamp and soft-delete fields are surfaced only when the collection
+ * declared them, so a consumer cannot come to depend on a field the schema
+ * never promised.
+ */
+export function decodeRow<T extends StorableRecordData>(
+	schema: CollectionSchema,
+	row: Record<string, unknown>,
+): StoredRecord<T> {
+	const record: StoredRecord<T> = {
+		id: text(row.id),
+		data: JSON.parse(text(row.payload)) as T,
+	};
+	if (hasTimestamps(schema)) {
+		if (row.created_at != null) {
+			record.createdAt = num(row.created_at);
+		}
+		if (row.updated_at != null) {
+			record.updatedAt = num(row.updated_at);
+		}
+	}
+	if (hasSoftDelete(schema)) {
+		record.deletedAt = row.deleted_at == null ? null : num(row.deleted_at);
+	}
+	return record;
+}
+
+export type WriteColumns = {
+	columns: string[];
+	values: SqlValue[];
+};
+
+export function insertColumns(
+	schema: CollectionSchema,
+	id: string,
+	data: StorableRecordData,
+	now: number,
+): WriteColumns {
+	const columns = ['id', 'payload'];
+	const values: SqlValue[] = [id, encodePayload(data)];
+
+	if (hasTimestamps(schema)) {
+		columns.push('created_at', 'updated_at');
+		values.push(now, now);
+	}
+	if (hasSoftDelete(schema)) {
+		columns.push('deleted_at');
+		values.push(null);
+	}
+	const projected = projectedValues(schema, data);
+	for (const [index, name] of projectedColumnNames(schema).entries()) {
+		columns.push(name);
+		values.push(projected[index]!);
+	}
+	return { columns, values };
+}
+
+export function updateAssignments(
+	schema: CollectionSchema,
+	data: StorableRecordData,
+	now: number,
+): WriteColumns {
+	const columns = ['payload'];
+	const values: SqlValue[] = [encodePayload(data)];
+
+	if (hasTimestamps(schema)) {
+		columns.push('updated_at');
+		values.push(now);
+	}
+	const projected = projectedValues(schema, data);
+	for (const [index, name] of projectedColumnNames(schema).entries()) {
+		columns.push(name);
+		values.push(projected[index]!);
+	}
+	return { columns, values };
+}

package/src/sqlite/sql-builder.ts

@@ -0,0 +1,244 @@
+/**
+ * Filter tree to parameterized SQL.
+ *
+ * Nothing a consumer supplies is ever concatenated into a statement. Field
+ * names are resolved through the schema first — validation has already run
+ * and rejected anything undeclared (FR-034) — so the only identifiers that
+ * reach SQL are ones this package generated from a declaration it checked.
+ * Values bind as parameters, without exception. Injection stops being a thing
+ * to remember and becomes a thing the shape of the code prevents.
+ *
+ * The other half of this file is keyset pagination. `OFFSET` was rejected for
+ * two measured reasons (research.md R6): it degrades linearly at the 100,000
+ * record budget because the engine still walks the skipped rows, and it
+ * shifts pages under concurrent writes so a record can be skipped or returned
+ * twice — the exact failure SC-007 forbids.
+ */
+
+import type { FilterNode, FilterValue, SortKey } from '../contract/query';
+import { projectedColumn } from '../schema/declare';
+import type { SqlValue } from './native';
+
+export type SqlFragment = {
+	sql: string;
+	params: SqlValue[];
+};
+
+const TRUE: SqlFragment = { sql: '1', params: [] };
+const FALSE: SqlFragment = { sql: '0', params: [] };
+
+function columnFor(field: string): string {
+	return field === 'id' ? 'id' : `"${projectedColumn(field)}"`;
+}
+
+/**
+ * The JSON path for a declared field.
+ *
+ * Safe to interpolate: the field name came from a schema declaration that
+ * validation already matched against `^[A-Za-z][A-Za-z0-9_]{0,62}$`, so it
+ * cannot carry a quote, a dollar sign, or a path separator.
+ */
+function jsonType(field: string): string {
+	return `json_type(payload, '$.${field}')`;
+}
+
+/** Present, and holding something a comparison can be defined over. */
+function presentPrimitive(field: string): string {
+	return `(${jsonType(field)} IS NOT NULL AND ${jsonType(field)} NOT IN ('object', 'array'))`;
+}
+
+/** Present and explicitly null — the condition `isNull` actually means. */
+function isExplicitNull(field: string): string {
+	return `${jsonType(field)} = 'null'`;
+}
+
+/** Booleans project to 0/1, so a bound parameter has to match. */
+function bind(value: FilterValue): SqlValue {
+	return typeof value === 'boolean' ? (value ? 1 : 0) : value;
+}
+
+function comparison(node: Extract<FilterNode, { field: string }>): SqlFragment {
+	const field = node.field;
+	const column = columnFor(field);
+
+	switch (node.op) {
+		case 'exists':
+			return {
+				sql: node.value ? `${jsonType(field)} IS NOT NULL` : `${jsonType(field)} IS NULL`,
+				params: [],
+			};
+
+		case 'isNull':
+			return { sql: isExplicitNull(field), params: [] };
+
+		case 'isNotNull':
+			return {
+				sql: `(${jsonType(field)} IS NOT NULL AND ${jsonType(field)} != 'null')`,
+				params: [],
+			};
+
+		case 'eq':
+			// Matching an explicit null needs the JSON type: `col = NULL` is
+			// NULL in SQL, which is not true, and a projected NULL cannot tell
+			// "absent" from "null" on its own.
+			return node.value === null
+				? { sql: isExplicitNull(field), params: [] }
+				: { sql: `${column} = ?`, params: [bind(node.value)] };
+
+		case 'ne':
+			return node.value === null
+				? {
+						sql: `(${presentPrimitive(field)} AND ${jsonType(field)} != 'null')`,
+						params: [],
+					}
+				: {
+						sql: `(${presentPrimitive(field)} AND ${column} IS NOT ?)`,
+						params: [bind(node.value)],
+					};
+
+		case 'lt':
+		case 'lte':
+		case 'gt':
+		case 'gte': {
+			if (node.value === null) {
+				// An ordered comparison against null has no answer; SQL would
+				// return NULL and the in-memory adapter returns false. Being
+				// explicit keeps the two identical.
+				return FALSE;
+			}
+			const operator = { lt: '<', lte: '<=', gt: '>', gte: '>=' }[node.op];
+			return {
+				sql: `(${column} IS NOT NULL AND ${column} ${operator} ?)`,
+				params: [bind(node.value)],
+			};
+		}
+
+		case 'between': {
+			const [low, high] = node.value;
+			if (low === null || high === null) {
+				return FALSE;
+			}
+			return {
+				sql: `(${column} IS NOT NULL AND ${column} BETWEEN ? AND ?)`,
+				params: [bind(low), bind(high)],
+			};
+		}
+
+		case 'in':
+		case 'nin': {
+			const values = node.value;
+			const nonNull = values.filter((value): value is Exclude<FilterValue, null> => value !== null);
+			const acceptsNull = values.length !== nonNull.length;
+
+			const clauses: string[] = [];
+			const params: SqlValue[] = [];
+			if (nonNull.length > 0) {
+				clauses.push(`${column} IN (${nonNull.map(() => '?').join(', ')})`);
+				params.push(...nonNull.map(value => bind(value)));
+			}
+			if (acceptsNull) {
+				clauses.push(isExplicitNull(field));
+			}
+			const membership = clauses.length > 0 ? `(${clauses.join(' OR ')})` : '0';
+
+			if (node.op === 'in') {
+				return { sql: membership, params };
+			}
+			// `nin` excludes, but only among records that have the field at
+			// all: an absent field satisfies no comparison, negated or not.
+			return {
+				sql: `(${presentPrimitive(field)} AND NOT IFNULL(${membership}, 0))`,
+				params,
+			};
+		}
+
+		default:
+			return FALSE;
+	}
+}
+
+export function buildFilter(node: FilterNode | undefined): SqlFragment {
+	if (!node) {
+		return TRUE;
+	}
+	switch (node.op) {
+		case 'and':
+		case 'or': {
+			const parts = node.nodes.map(child => buildFilter(child));
+			return {
+				sql: `(${parts.map(part => part.sql).join(node.op === 'and' ? ' AND ' : ' OR ')})`,
+				params: parts.flatMap(part => part.params),
+			};
+		}
+		case 'not': {
+			const inner = buildFilter(node.node);
+			// IFNULL, because NOT NULL is NULL in SQL and would quietly drop
+			// rows the in-memory adapter keeps.
+			return { sql: `(NOT IFNULL(${inner.sql}, 0))`, params: inner.params };
+		}
+		default:
+			return comparison(node);
+	}
+}
+
+export function buildOrderBy(sort: SortKey[]): string {
+	return sort
+		.map(key => `${columnFor(key.field)} ${key.direction === 'desc' ? 'DESC' : 'ASC'}`)
+		.join(', ');
+}
+
+/**
+ * The keyset predicate: everything strictly after the cursor position.
+ *
+ * Lexicographic across the sort keys — equal on the first means the second
+ * decides, down to the `id` tiebreaker that guarantees a total order. NULL is
+ * treated as smaller than every value, matching both SQLite's default
+ * ordering and `compareValues`, so the two adapters page identically.
+ */
+export function buildKeysetPredicate(sort: SortKey[], anchor: FilterValue[]): SqlFragment {
+	const params: SqlValue[] = [];
+
+	const build = (index: number): string => {
+		if (index >= sort.length) {
+			return '0';
+		}
+		const key = sort[index]!;
+		const column = columnFor(key.field);
+		const value = anchor[index] ?? null;
+		const descending = key.direction === 'desc';
+
+		let strictly: string;
+		if (descending) {
+			if (value === null) {
+				// Nothing sorts before null, so a descending walk anchored on
+				// null has nothing left ahead of it on this key.
+				strictly = '0';
+			} else {
+				strictly = `(${column} IS NULL OR ${column} < ?)`;
+				params.push(bind(value));
+			}
+		} else if (value === null) {
+			strictly = `${column} IS NOT NULL`;
+		} else {
+			strictly = `${column} > ?`;
+			params.push(bind(value));
+		}
+
+		const equal = `${column} IS ?`;
+		const equalParam = bind(value);
+
+		if (index === sort.length - 1) {
+			return strictly;
+		}
+
+		// Params are pushed in the order the fragments are concatenated, so the
+		// equality parameter has to land between this key's comparison and the
+		// next key's fragment.
+		const head = `(${strictly} OR (${equal} AND `;
+		params.push(equalParam);
+		const tail = build(index + 1);
+		return `${head}${tail}))`;
+	};
+
+	return { sql: build(0), params };
+}

package/src/sqlite/transactions.ts

@@ -0,0 +1,33 @@
+/**
+ * The transaction primitive.
+ *
+ * A transaction never spans two scopes, and not because a check forbids it:
+ * a transaction runs on one connection, a connection is opened against one
+ * scope's file, and the public surface offers no way to reach a second one
+ * from inside. FR-038 is a type error rather than a runtime one (research.md
+ * R2).
+ *
+ * Rollback fidelity is SQLite's, not this package's. A failure at any step
+ * unwinds through the engine's own `ROLLBACK`, which is the only way SC-006's
+ * "identical to its pre-transaction state, every time" survives a process
+ * kill halfway through.
+ */
+
+import type { Connection, TransactionExecutor } from './connection';
+
+/**
+ * Run `body` inside one transaction on one scope.
+ *
+ * Deliberately thin. The interesting behavior — read-your-own-writes,
+ * terminal-state rejection, what a settled transaction does when used again —
+ * belongs to `adapter/transaction.ts`, where both adapters can be held to the
+ * same rules.
+ */
+export function runInTransaction<R>(
+	connection: Connection,
+	body: (tx: TransactionExecutor) => Promise<R>,
+): Promise<R> {
+	return connection.transaction(body);
+}
+
+export type { TransactionExecutor };

package/src/sqlite/values.ts

@@ -0,0 +1,24 @@
+/**
+ * Reading values back out of a result row.
+ *
+ * The engine hands back `unknown` per column, and every read site would
+ * otherwise repeat the same `String(...)` / `Number(...)` coercion with a
+ * slightly different null check. One place to do it means one place where the
+ * "NULL means absent, not empty string" rule is decided.
+ */
+
+export function text(value: unknown): string {
+	return typeof value === 'string' ? value : String(value as string | number | boolean);
+}
+
+export function num(value: unknown): number {
+	return typeof value === 'number' ? value : Number(value as string | number);
+}
+
+export function maybeText(value: unknown): string | null {
+	return value == null ? null : text(value);
+}
+
+export function maybeNum(value: unknown): number | null {
+	return value == null ? null : num(value);
+}