@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/sqlite/row-codec.ts

@@ -1,201 +1,217 @@
-/**
- * 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 };
-}
+/**
+ * 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)}`;
+}
+
+/**
+ * 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 "${physicalIndexName(
+			schema,
+			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 };
+}