@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/adapter/collection.ts

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