@chipmobilesdk/rn-local-db 0.1.1 → 0.2.0

package/src/sqlite/batch.ts

@@ -67,12 +67,20 @@ function updateCommand(
 	return [`UPDATE ${quoted(schema)} SET ${assignments.join(', ')} WHERE id = ?`, [...values, id]];
 }
 
+/**
+ * Where a record stands, as this batch has left it so far. Three states, not
+ * two: a soft-deleted row is invisible to reads but still holds its primary
+ * key, so an insert over it conflicts and an upsert over it restores it — the
+ * same rules the collection API applies. Treating it as absent made a batch
+ * upsert issue an INSERT and fail the whole batch on the primary key.
+ */
+type RowState = 'live' | 'softDeleted' | 'absent';
+
 type Resolver = {
 	schema: CollectionSchema;
 	now: number;
-	/** Existence as this batch has left it so far, not as the database was. */
-	exists(id: string): Promise<boolean>;
-	stage(id: string, present: boolean): void;
+	state(id: string): Promise<RowState>;
+	stage(id: string, state: RowState): void;
 };
 
 type Resolved = { command: Command; outcome: WriteOutcome };
@@ -97,10 +105,10 @@ async function resolveInsert(
 ): Promise<Resolved> {
 	const { schema, now } = resolver;
 	assertRecordWithinBudget(schema.name, operation.record.data);
-	if (await resolver.exists(operation.record.id)) {
+	if ((await resolver.state(operation.record.id)) !== 'absent') {
 		conflict(schema, operation.record.id);
 	}
-	resolver.stage(operation.record.id, true);
+	resolver.stage(operation.record.id, 'live');
 	return {
 		command: insertCommand(schema, operation.record.id, operation.record.data, now),
 		outcome: { operation: 'created', id: operation.record.id },
@@ -113,7 +121,7 @@ async function resolveUpdate(
 ): Promise<Resolved> {
 	const { schema, now } = resolver;
 	assertRecordWithinBudget(schema.name, operation.data);
-	if (!(await resolver.exists(operation.id))) {
+	if ((await resolver.state(operation.id)) !== 'live') {
 		missing(schema, operation.id);
 	}
 	return {
@@ -128,8 +136,8 @@ async function resolveUpsert(
 ): Promise<Resolved> {
 	const { schema, now } = resolver;
 	assertRecordWithinBudget(schema.name, operation.record.data);
-	const present = await resolver.exists(operation.record.id);
-	resolver.stage(operation.record.id, true);
+	const present = (await resolver.state(operation.record.id)) !== 'absent';
+	resolver.stage(operation.record.id, 'live');
 	return {
 		command: present
 			? updateCommand(schema, operation.record.id, operation.record.data, now, true)
@@ -143,10 +151,10 @@ async function resolveDelete(
 	operation: Extract<BatchOperation, { type: 'delete' }>,
 ): Promise<Resolved> {
 	const { schema } = resolver;
-	if (!(await resolver.exists(operation.id))) {
+	if ((await resolver.state(operation.id)) !== 'live') {
 		missing(schema, operation.id);
 	}
-	resolver.stage(operation.id, false);
+	resolver.stage(operation.id, 'absent');
 	return {
 		command: [`DELETE FROM ${quoted(schema)} WHERE id = ?`, [operation.id]],
 		outcome: { operation: 'deleted', id: operation.id },
@@ -164,10 +172,10 @@ async function resolveSoftDelete(
 			detail: { collection: schema.name },
 		});
 	}
-	if (!(await resolver.exists(operation.id))) {
+	if ((await resolver.state(operation.id)) !== 'live') {
 		missing(schema, operation.id);
 	}
-	resolver.stage(operation.id, false);
+	resolver.stage(operation.id, 'softDeleted');
 	return {
 		command: [`UPDATE ${quoted(schema)} SET deleted_at = ? WHERE id = ?`, [now, operation.id]],
 		outcome: { operation: 'deleted', id: operation.id },
@@ -199,26 +207,28 @@ export async function runBatch(
 
 	const commands: Command[] = [];
 	const outcomes: WriteOutcome[] = [];
-	const overlay = new Map<string, boolean>();
+	const overlay = new Map<string, RowState>();
 
 	for (const operation of operations) {
 		const schema = context.schemaFor(operation.collection);
 		const resolver: Resolver = {
 			schema,
 			now: context.now(),
-			async exists(id) {
+			async state(id) {
 				const staged = overlay.get(`${schema.name}:${id}`);
 				if (staged !== undefined) {
 					return staged;
 				}
 				const result = await context.connection.execute(
-					`SELECT 1 AS present FROM ${quoted(schema)} WHERE id = ? AND deleted_at IS NULL`,
+					`SELECT deleted_at FROM ${quoted(schema)} WHERE id = ?`,
 					[id],
 				);
-				return result.rows.length > 0;
+				const row = result.rows[0];
+				if (!row) return 'absent';
+				return row.deleted_at === null || row.deleted_at === undefined ? 'live' : 'softDeleted';
 			},
-			stage(id, present) {
-				overlay.set(`${schema.name}:${id}`, present);
+			stage(id, state) {
+				overlay.set(`${schema.name}:${id}`, state);
 			},
 		};
 

package/src/sqlite/connection.ts

@@ -9,17 +9,22 @@
  * none a future bug could generate — reaches another scope's rows, because
  * they are in a file this connection never opened (research.md R2).
  *
- * **A transaction owns the connection while it runs.** `execute` routes to
- * the in-flight transaction rather than around it. That is what makes an
- * attachment reference written during a transaction roll back with it
- * (FR-072); routing around would leave the reference behind and the artifact
- * orphaned with no record of why.
+ * **A transaction owns the connection while it runs, and only its own
+ * executor reaches it.** Every operation queues on the connection, and a
+ * transaction holds the queue until it settles. Work issued through the
+ * connection meanwhile — a background sync, a second screen — waits and then
+ * runs on its own, rather than joining the transaction and vanishing with its
+ * rollback. Until 0.2.0 `execute` routed into whatever transaction was in
+ * flight, which is how an unrelated write was lost. Work meant to be part of
+ * the transaction goes through the executor the transaction hands out
+ * (`tx.collection`, `tx.attachments`).
  */
 
 import { DiagnosticCodes } from '../contract/errors';
 import { raise } from '../diagnostics/errors';
 import { raiseNative } from '../diagnostics/map-native';
 import { fileSystem } from '../platform/fs';
+import { createTransactionQueue } from './transaction-queue';
 import {
 	engine,
 	type ExecuteResult,
@@ -92,6 +97,7 @@ export async function openConnection(options: OpenConnectionOptions): Promise<Co
 
 	let closed = false;
 	let active: NativeTransaction | null = null;
+	const queue = createTransactionQueue();
 
 	const assertOpen = (): void => {
 		if (closed) {
@@ -99,63 +105,79 @@ export async function openConnection(options: OpenConnectionOptions): Promise<Co
 		}
 	};
 
+	const classify = (sql: string) =>
+		/^\s*select|^\s*pragma|^\s*explain/i.test(sql) ? 'read' : 'write';
+
 	const connection: Connection = {
 		path: options.path,
 		encrypted,
 
-		async execute(sql, params = []) {
+		execute(sql, params = []) {
 			assertOpen();
-			try {
-				// The in-flight transaction, when there is one. See the note at
-				// the top of this file.
-				return await (active ?? database).execute(sql, params);
-			} catch (error) {
-				raiseNative(error, {
-					operation: /^\s*select|^\s*pragma|^\s*explain/i.test(sql) ? 'read' : 'write',
-					encrypted,
-				});
-			}
+			// Never into an in-flight transaction: queued behind it instead. See
+			// the note at the top of this file.
+			return queue.run(async () => {
+				try {
+					return await database.execute(sql, params);
+				} catch (error) {
+					raiseNative(error, { operation: classify(sql), encrypted });
+				}
+			});
 		},
 
 		async transaction(fn) {
 			assertOpen();
 			if (active) {
 				// Nested transactions would need savepoints and would let a
-				// partial rollback look like a full one.
+				// partial rollback look like a full one. Refused rather than
+				// queued: a body that opened a second transaction would otherwise
+				// wait on itself forever.
 				raise(DiagnosticCodes.TRANSACTION_STATE, {
 					message: 'a transaction is already in flight on this connection',
 				});
 			}
-			try {
-				return await database.transaction(async tx => {
-					active = tx;
-					try {
-						return await fn({
-							execute: (sql, params = []) => tx.execute(sql, params),
-							rollback: async () => {
-								await tx.rollback();
-								// Cleared immediately: anything that runs after an
-								// abort must not be routed into a settled
-								// transaction and silently discarded.
-								active = null;
-							},
-						});
-					} finally {
-						active = null;
-					}
-				});
-			} catch (error) {
-				raiseNative(error, { operation: 'transaction', encrypted });
-			}
+			return queue.runTransaction(async () => {
+				try {
+					return await database.transaction(async tx => {
+						active = tx;
+						let settled = false;
+						try {
+							return await fn({
+								execute: (sql, params = []) => {
+									if (settled) {
+										// After an explicit rollback the body is still running
+										// inside the engine's callback. Its remaining statements
+										// are refused, not run in autocommit (LDB-V1).
+										raise(DiagnosticCodes.TRANSACTION_STATE, {
+											message: 'transaction already rolled back',
+										});
+									}
+									return tx.execute(sql, params);
+								},
+								rollback: async () => {
+									await tx.rollback();
+									settled = true;
+								},
+							});
+						} finally {
+							active = null;
+						}
+					});
+				} catch (error) {
+					raiseNative(error, { operation: 'transaction', encrypted });
+				}
+			});
 		},
 
-		async executeBatch(commands) {
+		executeBatch(commands) {
 			assertOpen();
-			try {
-				await database.executeBatch(commands);
-			} catch (error) {
-				raiseNative(error, { operation: 'write', encrypted });
-			}
+			return queue.run(async () => {
+				try {
+					await database.executeBatch(commands);
+				} catch (error) {
+					raiseNative(error, { operation: 'write', encrypted });
+				}
+			});
 		},
 
 		async integrityCheck() {

package/src/sqlite/index-coverage.ts

@@ -17,6 +17,7 @@ import type { CollectionSchema } from '../contract/schema';
 import { collectionTable } from '../schema/declare';
 import type { Executor } from './connection';
 import { buildFilter, buildOrderBy } from './sql-builder';
+import { declaredIndexName } from './row-codec';
 
 const SCAN = /\bSCAN\b/i;
 const USING_INDEX = /USING\s+(COVERING\s+)?INDEX\s+"?([A-Za-z0-9_]+)"?/i;
@@ -43,7 +44,9 @@ export async function explainQuery(
 	return {
 		collection: schema.name,
 		usesIndex: match !== null,
-		indexName: match?.[2],
+		// Reported under the name the app declared, not the collection-scoped
+		// name it has in the file.
+		indexName: match?.[2] === undefined ? undefined : declaredIndexName(schema, match[2]),
 		detail:
 			detail ||
 			(SCAN.test(detail)

package/src/sqlite/row-codec.ts

@@ -54,13 +54,33 @@ export function addColumnSql(schema: CollectionSchema, field: FieldDeclaration):
 	)}" ${affinityOf(field)}`;
 }
 
+/**
+ * The name an index has in the database file.
+ *
+ * Index names are database-wide in SQLite, but declared per collection. Until
+ * 0.2.0 the declared name was used as is, so a second collection declaring an
+ * index of the same name hit `IF NOT EXISTS` and silently got no index — a
+ * UNIQUE constraint included. The double underscore keeps a declared name from
+ * colliding with the package's own `<table>_live` index.
+ */
+export function physicalIndexName(schema: CollectionSchema, declaredName: string): string {
+	return `${collectionTable(schema.name)}__${declaredName}`;
+}
+
+/** The declared name back from a physical one, for reporting to the app. */
+export function declaredIndexName(schema: CollectionSchema, physicalName: string): string {
+	const prefix = `${collectionTable(schema.name)}__`;
+	return physicalName.startsWith(prefix) ? physicalName.slice(prefix.length) : physicalName;
+}
+
 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})`;
+		return `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS "${physicalIndexName(
+			schema,
+			index.name,
+		)}" ON "${table}" (${columns})`;
 	});
 	if (hasSoftDelete(schema)) {
 		// Every default query carries `deleted_at IS NULL`, so without this the

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/testing/conformance/attachments.ts

@@ -95,7 +95,7 @@ export function registerAttachmentConformance(context: ConformanceContext): void
 			try {
 				await handle.transaction(async tx => {
 					await tx.collection('notes').insert({ id: 'n1', data: { title: 'x' } });
-					await handle.attachments().write({ id: 'a1', contentType: 'text/plain', content });
+					await tx.attachments().write({ id: 'a1', contentType: 'text/plain', content });
 					throw new Error('injected');
 				});
 			} catch {