@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/sqlite/sql-builder.ts

@@ -1,244 +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 };
-}
+/**
+ * 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/transaction-queue.ts

@@ -0,0 +1,87 @@
+/**
+ * The per-handle queue that keeps a transaction to itself.
+ *
+ * A transaction holds the queue until it settles; work arriving meanwhile
+ * through the handle waits its turn and then runs on its own, instead of
+ * joining the transaction and vanishing with its rollback (LDB-01). Shared by
+ * the SQLite connection and the memory adapter so both isolate the same way.
+ *
+ * Pure: no engine, no React, so the memory adapter can use it without loading
+ * native code.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+
+/**
+ * How long work through the handle waits behind a transaction before it is
+ * refused.
+ *
+ * Not a performance budget: it exists for the one wait that never ends. A
+ * transaction body that awaits the handle's own `collection()` or
+ * `attachments()` is waiting on work queued behind itself. Until 0.2.0 that
+ * work ran inside the transaction; now it is refused after this long with a
+ * message naming `tx.collection()` / `tx.attachments()`, and the transaction
+ * rolls back, rather than both waiting forever.
+ */
+export const TRANSACTION_WAIT_LIMIT_MS = 10_000;
+
+export type TransactionQueue = {
+	/** Ordinary work. Bounded by `TRANSACTION_WAIT_LIMIT_MS` when it queues behind a transaction. */
+	run<T>(work: () => Promise<T>): Promise<T>;
+	/** A transaction: holds the queue for as long as `work` runs. */
+	runTransaction<T>(work: () => Promise<T>): Promise<T>;
+};
+
+export function createTransactionQueue(
+	waitLimitMs: number = TRANSACTION_WAIT_LIMIT_MS,
+): TransactionQueue {
+	/** Tail of the queue. Never rejects, so one failure cannot stall the rest. */
+	let tail: Promise<unknown> = Promise.resolve();
+	/** Transactions queued or running. Only work behind one of them can deadlock. */
+	let transactions = 0;
+
+	const enqueue = <T>(work: () => Promise<T>): Promise<T> => {
+		const run = tail.then(work, work);
+		tail = run.catch(() => undefined);
+		return run;
+	};
+
+	return {
+		run<T>(work: () => Promise<T>): Promise<T> {
+			if (transactions === 0) {
+				return enqueue(work);
+			}
+
+			let abandoned = false;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const started = enqueue(() => {
+				clearTimeout(timer);
+				// Refused while waiting: it must not run late, after its caller was
+				// already told it failed.
+				return abandoned ? Promise.resolve(undefined as T) : work();
+			});
+			const refused = new Promise<never>((_, reject) => {
+				timer = setTimeout(() => {
+					abandoned = true;
+					try {
+						raise(DiagnosticCodes.TRANSACTION_STATE, {
+							message:
+								'waited too long behind an in-flight transaction; inside a transaction body use tx.collection() and tx.attachments(), not the handle',
+						});
+					} catch (error) {
+						reject(error);
+					}
+				}, waitLimitMs);
+			});
+			return Promise.race([started, refused]);
+		},
+
+		runTransaction<T>(work: () => Promise<T>): Promise<T> {
+			transactions += 1;
+			return enqueue(work).finally(() => {
+				transactions -= 1;
+			});
+		},
+	};
+}

package/src/sqlite/transactions.ts

@@ -1,33 +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 };
+/**
+ * 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 };