@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/sqlite/batch.ts

@@ -1,232 +1,242 @@
-/**
- * Batch writes: many operations, one atomic unit, one outcome (FR-028).
- *
- * Every statement is resolved before any of them runs. That ordering is the
- * point: a conflict or a missing record is reported with the database still
- * untouched, so "the batch failed" and "the batch was partly applied" are
- * never the same event. The statements then go to the engine's own
- * `executeBatch`, which wraps them in a single transaction — the batch is
- * atomic because SQLite makes it atomic, not because this file is careful.
- *
- * Resolution keeps an overlay of what earlier operations in the same batch
- * did, so `insert` followed by `update` on the same id resolves against the
- * batch's own effect rather than against the database as it was before it.
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import type { WriteOutcome } from '../contract/record';
-import type { CollectionSchema } from '../contract/schema';
-import type { BatchOperation, BatchOutcome } from '../contract/transaction';
-import { raise } from '../diagnostics/errors';
-import { assertBatchWithinBudget, assertRecordWithinBudget } from '../query/budgets';
-import { collectionTable, hasSoftDelete } from '../schema/declare';
-import type { Connection } from './connection';
-import type { SqlValue } from './native';
-import { insertColumns, updateAssignments } from './row-codec';
-
-export type BatchContext = {
-	connection: Connection;
-	/** Raises CONFIG_INVALID for a collection the schema never declared. */
-	schemaFor(name: string): CollectionSchema;
-	now(): number;
-};
-
-type Command = [string, SqlValue[]];
-
-function quoted(schema: CollectionSchema): string {
-	return `"${collectionTable(schema.name)}"`;
-}
-
-function insertCommand(
-	schema: CollectionSchema,
-	id: string,
-	data: Parameters<typeof insertColumns>[2],
-	now: number,
-): Command {
-	const { columns, values } = insertColumns(schema, id, data, now);
-	return [
-		`INSERT INTO ${quoted(schema)} (${columns
-			.map(name => `"${name}"`)
-			.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`,
-		values,
-	];
-}
-
-function updateCommand(
-	schema: CollectionSchema,
-	id: string,
-	data: Parameters<typeof updateAssignments>[1],
-	now: number,
-	restore: boolean,
-): Command {
-	const { columns, values } = updateAssignments(schema, data, now);
-	const assignments = columns.map(name => `"${name}" = ?`);
-	if (restore && hasSoftDelete(schema)) {
-		assignments.push('deleted_at = NULL');
-	}
-	return [`UPDATE ${quoted(schema)} SET ${assignments.join(', ')} WHERE id = ?`, [...values, id]];
-}
-
-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;
-};
-
-type Resolved = { command: Command; outcome: WriteOutcome };
-
-function conflict(schema: CollectionSchema, id: string): never {
-	raise(DiagnosticCodes.RECORD_CONFLICT, {
-		message: 'record already exists',
-		detail: { collection: schema.name, recordId: id },
-	});
-}
-
-function missing(schema: CollectionSchema, id: string): never {
-	raise(DiagnosticCodes.RECORD_NOT_FOUND, {
-		message: 'record not found',
-		detail: { collection: schema.name, recordId: id },
-	});
-}
-
-async function resolveInsert(
-	resolver: Resolver,
-	operation: Extract<BatchOperation, { type: 'insert' }>,
-): Promise<Resolved> {
-	const { schema, now } = resolver;
-	assertRecordWithinBudget(schema.name, operation.record.data);
-	if (await resolver.exists(operation.record.id)) {
-		conflict(schema, operation.record.id);
-	}
-	resolver.stage(operation.record.id, true);
-	return {
-		command: insertCommand(schema, operation.record.id, operation.record.data, now),
-		outcome: { operation: 'created', id: operation.record.id },
-	};
-}
-
-async function resolveUpdate(
-	resolver: Resolver,
-	operation: Extract<BatchOperation, { type: 'update' }>,
-): Promise<Resolved> {
-	const { schema, now } = resolver;
-	assertRecordWithinBudget(schema.name, operation.data);
-	if (!(await resolver.exists(operation.id))) {
-		missing(schema, operation.id);
-	}
-	return {
-		command: updateCommand(schema, operation.id, operation.data, now, false),
-		outcome: { operation: 'updated', id: operation.id },
-	};
-}
-
-async function resolveUpsert(
-	resolver: Resolver,
-	operation: Extract<BatchOperation, { type: 'upsert' }>,
-): 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);
-	return {
-		command: present
-			? updateCommand(schema, operation.record.id, operation.record.data, now, true)
-			: insertCommand(schema, operation.record.id, operation.record.data, now),
-		outcome: { operation: present ? 'updated' : 'created', id: operation.record.id },
-	};
-}
-
-async function resolveDelete(
-	resolver: Resolver,
-	operation: Extract<BatchOperation, { type: 'delete' }>,
-): Promise<Resolved> {
-	const { schema } = resolver;
-	if (!(await resolver.exists(operation.id))) {
-		missing(schema, operation.id);
-	}
-	resolver.stage(operation.id, false);
-	return {
-		command: [`DELETE FROM ${quoted(schema)} WHERE id = ?`, [operation.id]],
-		outcome: { operation: 'deleted', id: operation.id },
-	};
-}
-
-async function resolveSoftDelete(
-	resolver: Resolver,
-	operation: Extract<BatchOperation, { type: 'softDelete' }>,
-): Promise<Resolved> {
-	const { schema, now } = resolver;
-	if (!hasSoftDelete(schema)) {
-		raise(DiagnosticCodes.CONFIG_INVALID, {
-			message: 'collection does not declare soft delete',
-			detail: { collection: schema.name },
-		});
-	}
-	if (!(await resolver.exists(operation.id))) {
-		missing(schema, operation.id);
-	}
-	resolver.stage(operation.id, false);
-	return {
-		command: [`UPDATE ${quoted(schema)} SET deleted_at = ? WHERE id = ?`, [now, operation.id]],
-		outcome: { operation: 'deleted', id: operation.id },
-	};
-}
-
-function resolveOperation(resolver: Resolver, operation: BatchOperation): Promise<Resolved> {
-	switch (operation.type) {
-		case 'insert':
-			return resolveInsert(resolver, operation);
-		case 'update':
-			return resolveUpdate(resolver, operation);
-		case 'upsert':
-			return resolveUpsert(resolver, operation);
-		case 'delete':
-			return resolveDelete(resolver, operation);
-		case 'softDelete':
-			return resolveSoftDelete(resolver, operation);
-		default:
-			raise(DiagnosticCodes.CONFIG_INVALID, { message: 'unsupported batch operation' });
-	}
-}
-
-export async function runBatch(
-	context: BatchContext,
-	operations: BatchOperation[],
-): Promise<BatchOutcome> {
-	assertBatchWithinBudget(operations.length);
-
-	const commands: Command[] = [];
-	const outcomes: WriteOutcome[] = [];
-	const overlay = new Map<string, boolean>();
-
-	for (const operation of operations) {
-		const schema = context.schemaFor(operation.collection);
-		const resolver: Resolver = {
-			schema,
-			now: context.now(),
-			async exists(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`,
-					[id],
-				);
-				return result.rows.length > 0;
-			},
-			stage(id, present) {
-				overlay.set(`${schema.name}:${id}`, present);
-			},
-		};
-
-		const resolved = await resolveOperation(resolver, operation);
-		commands.push(resolved.command);
-		outcomes.push(resolved.outcome);
-	}
-
-	await context.connection.executeBatch(commands);
-	return { applied: outcomes.length, outcomes };
-}
+/**
+ * Batch writes: many operations, one atomic unit, one outcome (FR-028).
+ *
+ * Every statement is resolved before any of them runs. That ordering is the
+ * point: a conflict or a missing record is reported with the database still
+ * untouched, so "the batch failed" and "the batch was partly applied" are
+ * never the same event. The statements then go to the engine's own
+ * `executeBatch`, which wraps them in a single transaction — the batch is
+ * atomic because SQLite makes it atomic, not because this file is careful.
+ *
+ * Resolution keeps an overlay of what earlier operations in the same batch
+ * did, so `insert` followed by `update` on the same id resolves against the
+ * batch's own effect rather than against the database as it was before it.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { WriteOutcome } from '../contract/record';
+import type { CollectionSchema } from '../contract/schema';
+import type { BatchOperation, BatchOutcome } from '../contract/transaction';
+import { raise } from '../diagnostics/errors';
+import { assertBatchWithinBudget, assertRecordWithinBudget } from '../query/budgets';
+import { collectionTable, hasSoftDelete } from '../schema/declare';
+import type { Connection } from './connection';
+import type { SqlValue } from './native';
+import { insertColumns, updateAssignments } from './row-codec';
+
+export type BatchContext = {
+	connection: Connection;
+	/** Raises CONFIG_INVALID for a collection the schema never declared. */
+	schemaFor(name: string): CollectionSchema;
+	now(): number;
+};
+
+type Command = [string, SqlValue[]];
+
+function quoted(schema: CollectionSchema): string {
+	return `"${collectionTable(schema.name)}"`;
+}
+
+function insertCommand(
+	schema: CollectionSchema,
+	id: string,
+	data: Parameters<typeof insertColumns>[2],
+	now: number,
+): Command {
+	const { columns, values } = insertColumns(schema, id, data, now);
+	return [
+		`INSERT INTO ${quoted(schema)} (${columns
+			.map(name => `"${name}"`)
+			.join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`,
+		values,
+	];
+}
+
+function updateCommand(
+	schema: CollectionSchema,
+	id: string,
+	data: Parameters<typeof updateAssignments>[1],
+	now: number,
+	restore: boolean,
+): Command {
+	const { columns, values } = updateAssignments(schema, data, now);
+	const assignments = columns.map(name => `"${name}" = ?`);
+	if (restore && hasSoftDelete(schema)) {
+		assignments.push('deleted_at = NULL');
+	}
+	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;
+	state(id: string): Promise<RowState>;
+	stage(id: string, state: RowState): void;
+};
+
+type Resolved = { command: Command; outcome: WriteOutcome };
+
+function conflict(schema: CollectionSchema, id: string): never {
+	raise(DiagnosticCodes.RECORD_CONFLICT, {
+		message: 'record already exists',
+		detail: { collection: schema.name, recordId: id },
+	});
+}
+
+function missing(schema: CollectionSchema, id: string): never {
+	raise(DiagnosticCodes.RECORD_NOT_FOUND, {
+		message: 'record not found',
+		detail: { collection: schema.name, recordId: id },
+	});
+}
+
+async function resolveInsert(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'insert' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	assertRecordWithinBudget(schema.name, operation.record.data);
+	if ((await resolver.state(operation.record.id)) !== 'absent') {
+		conflict(schema, operation.record.id);
+	}
+	resolver.stage(operation.record.id, 'live');
+	return {
+		command: insertCommand(schema, operation.record.id, operation.record.data, now),
+		outcome: { operation: 'created', id: operation.record.id },
+	};
+}
+
+async function resolveUpdate(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'update' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	assertRecordWithinBudget(schema.name, operation.data);
+	if ((await resolver.state(operation.id)) !== 'live') {
+		missing(schema, operation.id);
+	}
+	return {
+		command: updateCommand(schema, operation.id, operation.data, now, false),
+		outcome: { operation: 'updated', id: operation.id },
+	};
+}
+
+async function resolveUpsert(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'upsert' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	assertRecordWithinBudget(schema.name, operation.record.data);
+	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)
+			: insertCommand(schema, operation.record.id, operation.record.data, now),
+		outcome: { operation: present ? 'updated' : 'created', id: operation.record.id },
+	};
+}
+
+async function resolveDelete(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'delete' }>,
+): Promise<Resolved> {
+	const { schema } = resolver;
+	if ((await resolver.state(operation.id)) !== 'live') {
+		missing(schema, operation.id);
+	}
+	resolver.stage(operation.id, 'absent');
+	return {
+		command: [`DELETE FROM ${quoted(schema)} WHERE id = ?`, [operation.id]],
+		outcome: { operation: 'deleted', id: operation.id },
+	};
+}
+
+async function resolveSoftDelete(
+	resolver: Resolver,
+	operation: Extract<BatchOperation, { type: 'softDelete' }>,
+): Promise<Resolved> {
+	const { schema, now } = resolver;
+	if (!hasSoftDelete(schema)) {
+		raise(DiagnosticCodes.CONFIG_INVALID, {
+			message: 'collection does not declare soft delete',
+			detail: { collection: schema.name },
+		});
+	}
+	if ((await resolver.state(operation.id)) !== 'live') {
+		missing(schema, operation.id);
+	}
+	resolver.stage(operation.id, 'softDeleted');
+	return {
+		command: [`UPDATE ${quoted(schema)} SET deleted_at = ? WHERE id = ?`, [now, operation.id]],
+		outcome: { operation: 'deleted', id: operation.id },
+	};
+}
+
+function resolveOperation(resolver: Resolver, operation: BatchOperation): Promise<Resolved> {
+	switch (operation.type) {
+		case 'insert':
+			return resolveInsert(resolver, operation);
+		case 'update':
+			return resolveUpdate(resolver, operation);
+		case 'upsert':
+			return resolveUpsert(resolver, operation);
+		case 'delete':
+			return resolveDelete(resolver, operation);
+		case 'softDelete':
+			return resolveSoftDelete(resolver, operation);
+		default:
+			raise(DiagnosticCodes.CONFIG_INVALID, { message: 'unsupported batch operation' });
+	}
+}
+
+export async function runBatch(
+	context: BatchContext,
+	operations: BatchOperation[],
+): Promise<BatchOutcome> {
+	assertBatchWithinBudget(operations.length);
+
+	const commands: Command[] = [];
+	const outcomes: WriteOutcome[] = [];
+	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 state(id) {
+				const staged = overlay.get(`${schema.name}:${id}`);
+				if (staged !== undefined) {
+					return staged;
+				}
+				const result = await context.connection.execute(
+					`SELECT deleted_at FROM ${quoted(schema)} WHERE id = ?`,
+					[id],
+				);
+				const row = result.rows[0];
+				if (!row) return 'absent';
+				return row.deleted_at === null || row.deleted_at === undefined ? 'live' : 'softDeleted';
+			},
+			stage(id, state) {
+				overlay.set(`${schema.name}:${id}`, state);
+			},
+		};
+
+		const resolved = await resolveOperation(resolver, operation);
+		commands.push(resolved.command);
+		outcomes.push(resolved.outcome);
+	}
+
+	await context.connection.executeBatch(commands);
+	return { applied: outcomes.length, outcomes };
+}