@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/query/sort.ts

@@ -1,56 +1,55 @@
-/**
- * Sort ordering.
- *
- * The record id is always appended as the final sort key (FR-031). Without a
- * tiebreaker, records with equal sort values come back in whatever order the
- * engine happens to produce, which makes keyset pagination lose or repeat
- * rows — the exact failure SC-007 forbids.
- */
-
-import type { SortKey } from '../contract/query';
-import type { StoredRecord } from '../contract/record';
-import { asFilterValue, compareValues, lookupField } from './compare';
-
-export const ID_SORT_KEY: SortKey = { field: 'id', direction: 'asc' };
-
-/** Append `id ASC` unless the caller already sorted by it. */
-export function withStableTiebreaker(sort: SortKey[] | undefined): SortKey[] {
-	const keys = sort ? [...sort] : [];
-	if (!keys.some(key => key.field === 'id')) {
-		keys.push(ID_SORT_KEY);
-	}
-	return keys;
-}
-
-/** Sort values come from the record id or from a declared field. */
-export function sortValueOf(record: StoredRecord, field: string): ReturnType<typeof asFilterValue> {
-	if (field === 'id') {
-		return record.id;
-	}
-	const lookup = lookupField(record.data, field);
-	if (!lookup.present) {
-		// Absent sorts alongside null, matching how SQLite treats a NULL
-		// column, so the two adapters agree without special-casing.
-		return null;
-	}
-	return asFilterValue(lookup.value) ?? null;
-}
-
-export function compareRecords(
-	a: StoredRecord,
-	b: StoredRecord,
-	sort: SortKey[],
-): number {
-	for (const key of sort) {
-		const direction = key.direction === 'desc' ? -1 : 1;
-		const result = compareValues(sortValueOf(a, key.field) ?? null, sortValueOf(b, key.field) ?? null);
-		if (result !== 0) {
-			return result * direction;
-		}
-	}
-	return 0;
-}
-
-export function sortRecords<T extends StoredRecord>(records: T[], sort: SortKey[]): T[] {
-	return [...records].sort((a, b) => compareRecords(a, b, sort));
-}
+/**
+ * Sort ordering.
+ *
+ * The record id is always appended as the final sort key (FR-031). Without a
+ * tiebreaker, records with equal sort values come back in whatever order the
+ * engine happens to produce, which makes keyset pagination lose or repeat
+ * rows — the exact failure SC-007 forbids.
+ */
+
+import type { SortKey } from '../contract/query';
+import type { StoredRecord } from '../contract/record';
+import { asFilterValue, compareValues, lookupField } from './compare';
+
+export const ID_SORT_KEY: SortKey = { field: 'id', direction: 'asc' };
+
+/** Append `id ASC` unless the caller already sorted by it. */
+export function withStableTiebreaker(sort: SortKey[] | undefined): SortKey[] {
+	const keys = sort ? [...sort] : [];
+	if (!keys.some(key => key.field === 'id')) {
+		keys.push(ID_SORT_KEY);
+	}
+	return keys;
+}
+
+/** Sort values come from the record id or from a declared field. */
+export function sortValueOf(record: StoredRecord, field: string): ReturnType<typeof asFilterValue> {
+	if (field === 'id') {
+		return record.id;
+	}
+	const lookup = lookupField(record.data, field);
+	if (!lookup.present) {
+		// Absent sorts alongside null, matching how SQLite treats a NULL
+		// column, so the two adapters agree without special-casing.
+		return null;
+	}
+	return asFilterValue(lookup.value) ?? null;
+}
+
+export function compareRecords(a: StoredRecord, b: StoredRecord, sort: SortKey[]): number {
+	for (const key of sort) {
+		const direction = key.direction === 'desc' ? -1 : 1;
+		const result = compareValues(
+			sortValueOf(a, key.field) ?? null,
+			sortValueOf(b, key.field) ?? null,
+		);
+		if (result !== 0) {
+			return result * direction;
+		}
+	}
+	return 0;
+}
+
+export function sortRecords<T extends StoredRecord>(records: T[], sort: SortKey[]): T[] {
+	return [...records].sort((a, b) => compareRecords(a, b, sort));
+}

package/src/query/validate.ts

@@ -1,171 +1,171 @@
-/**
- * Query validation, run before any SQL is built.
- *
- * Two things fall out of validating first: FR-034 is satisfied, and no
- * consumer-supplied string ever reaches SQL construction — field names are
- * resolved through the schema to a known column, and values bind as
- * parameters. Injection stops being a thing to remember.
- */
-
-import { Budgets } from '../contract/config';
-import { DiagnosticCodes } from '../contract/errors';
-import type { FilterNode, FilterValue, Query, SortKey } from '../contract/query';
-import type { CollectionSchema, FieldType } from '../contract/schema';
-import { raise } from '../diagnostics/errors';
-import { sanitizeIdentifier } from '../diagnostics/redact';
-import { fieldOf } from '../schema/declare';
-
-function queryInvalid(message: string, collection: string): never {
-	// The field name is named; its *value* never is (FR-079).
-	raise(DiagnosticCodes.QUERY_INVALID, { message, detail: { collection } });
-}
-
-const ORDERED_OPERATORS = new Set(['lt', 'lte', 'gt', 'gte', 'between']);
-
-function typeMatches(type: FieldType, value: FilterValue): boolean {
-	if (value === null) {
-		return true;
-	}
-	switch (type) {
-		case 'string':
-			return typeof value === 'string';
-		case 'number':
-		case 'timestamp':
-			return typeof value === 'number';
-		case 'boolean':
-			return typeof value === 'boolean';
-		default:
-			return false;
-	}
-}
-
-function validateField(
-	collection: CollectionSchema,
-	field: string,
-): ReturnType<typeof fieldOf> {
-	const declared = fieldOf(collection, field);
-	if (!declared) {
-		// Returning everything or nothing here would be worse than failing:
-		// a typo would silently change what the user sees.
-		queryInvalid(`filter references undeclared field ${sanitizeIdentifier(field)}`, collection.name);
-	}
-	return declared;
-}
-
-export function validateFilter(collection: CollectionSchema, node: FilterNode): void {
-	switch (node.op) {
-		case 'and':
-		case 'or': {
-			if (!Array.isArray(node.nodes) || node.nodes.length === 0) {
-				queryInvalid(`${node.op} requires at least one child`, collection.name);
-			}
-			for (const child of node.nodes) {
-				validateFilter(collection, child);
-			}
-			return;
-		}
-		case 'not': {
-			if (!node.node) {
-				queryInvalid('not requires a child', collection.name);
-			}
-			validateFilter(collection, node.node);
-			return;
-		}
-		case 'isNull':
-		case 'isNotNull': {
-			validateField(collection, node.field);
-			return;
-		}
-		case 'exists': {
-			validateField(collection, node.field);
-			if (typeof node.value !== 'boolean') {
-				queryInvalid('exists requires a boolean', collection.name);
-			}
-			return;
-		}
-		case 'in':
-		case 'nin': {
-			const declared = validateField(collection, node.field)!;
-			if (!Array.isArray(node.value) || node.value.length === 0) {
-				queryInvalid(`${node.op} requires a non-empty array`, collection.name);
-			}
-			for (const value of node.value) {
-				if (!typeMatches(declared.type, value)) {
-					queryInvalid(`${node.op} value does not match field type`, collection.name);
-				}
-			}
-			return;
-		}
-		case 'between': {
-			const declared = validateField(collection, node.field)!;
-			if (!Array.isArray(node.value) || node.value.length !== 2) {
-				queryInvalid('between requires exactly two bounds', collection.name);
-			}
-			for (const value of node.value) {
-				if (!typeMatches(declared.type, value)) {
-					queryInvalid('between bound does not match field type', collection.name);
-				}
-			}
-			return;
-		}
-		case 'eq':
-		case 'ne':
-		case 'lt':
-		case 'lte':
-		case 'gt':
-		case 'gte': {
-			const declared = validateField(collection, node.field)!;
-			if (declared.type === 'boolean' && ORDERED_OPERATORS.has(node.op)) {
-				queryInvalid('ordered comparison is not defined for a boolean', collection.name);
-			}
-			if (!typeMatches(declared.type, node.value)) {
-				queryInvalid('filter value does not match field type', collection.name);
-			}
-			return;
-		}
-		default: {
-			queryInvalid(
-				`unsupported operator ${sanitizeIdentifier(String((node as { op: string }).op))}`,
-				collection.name,
-			);
-		}
-	}
-}
-
-export function validateSort(collection: CollectionSchema, sort: SortKey[]): void {
-	const seen = new Set<string>();
-	for (const key of sort) {
-		validateField(collection, key.field);
-		if (seen.has(key.field)) {
-			queryInvalid(`duplicate sort field ${sanitizeIdentifier(key.field)}`, collection.name);
-		}
-		seen.add(key.field);
-		if (key.direction && key.direction !== 'asc' && key.direction !== 'desc') {
-			queryInvalid('sort direction must be asc or desc', collection.name);
-		}
-	}
-}
-
-export function validatePageSize(size: number): void {
-	if (!Number.isInteger(size) || size < 1 || size > Budgets.MAX_PAGE_SIZE) {
-		raise(DiagnosticCodes.PAGE_SIZE_INVALID, {
-			message: 'page size out of range',
-			detail: { limit: Budgets.MAX_PAGE_SIZE },
-		});
-	}
-}
-
-export function validateQuery(collection: CollectionSchema, query: Query | undefined): void {
-	if (!query) {
-		return;
-	}
-	if (query.filter) {
-		validateFilter(collection, query.filter);
-	}
-	if (query.sort) {
-		validateSort(collection, query.sort);
-	}
-	if (query.page) {
-		validatePageSize(query.page.size);
-	}
-}
+/**
+ * Query validation, run before any SQL is built.
+ *
+ * Two things fall out of validating first: FR-034 is satisfied, and no
+ * consumer-supplied string ever reaches SQL construction — field names are
+ * resolved through the schema to a known column, and values bind as
+ * parameters. Injection stops being a thing to remember.
+ */
+
+import { Budgets } from '../contract/config';
+import { DiagnosticCodes } from '../contract/errors';
+import type { FilterNode, FilterValue, Query, SortKey } from '../contract/query';
+import type { CollectionSchema, FieldType } from '../contract/schema';
+import { raise } from '../diagnostics/errors';
+import { sanitizeIdentifier } from '../diagnostics/redact';
+import { fieldOf } from '../schema/declare';
+
+function queryInvalid(message: string, collection: string): never {
+	// The field name is named; its *value* never is (FR-079).
+	raise(DiagnosticCodes.QUERY_INVALID, { message, detail: { collection } });
+}
+
+const ORDERED_OPERATORS = new Set(['lt', 'lte', 'gt', 'gte', 'between']);
+
+function typeMatches(type: FieldType, value: FilterValue): boolean {
+	if (value === null) {
+		return true;
+	}
+	switch (type) {
+		case 'string':
+			return typeof value === 'string';
+		case 'number':
+		case 'timestamp':
+			return typeof value === 'number';
+		case 'boolean':
+			return typeof value === 'boolean';
+		default:
+			return false;
+	}
+}
+
+function validateField(collection: CollectionSchema, field: string): ReturnType<typeof fieldOf> {
+	const declared = fieldOf(collection, field);
+	if (!declared) {
+		// Returning everything or nothing here would be worse than failing:
+		// a typo would silently change what the user sees.
+		queryInvalid(
+			`filter references undeclared field ${sanitizeIdentifier(field)}`,
+			collection.name,
+		);
+	}
+	return declared;
+}
+
+export function validateFilter(collection: CollectionSchema, node: FilterNode): void {
+	switch (node.op) {
+		case 'and':
+		case 'or': {
+			if (!Array.isArray(node.nodes) || node.nodes.length === 0) {
+				queryInvalid(`${node.op} requires at least one child`, collection.name);
+			}
+			for (const child of node.nodes) {
+				validateFilter(collection, child);
+			}
+			return;
+		}
+		case 'not': {
+			if (!node.node) {
+				queryInvalid('not requires a child', collection.name);
+			}
+			validateFilter(collection, node.node);
+			return;
+		}
+		case 'isNull':
+		case 'isNotNull': {
+			validateField(collection, node.field);
+			return;
+		}
+		case 'exists': {
+			validateField(collection, node.field);
+			if (typeof node.value !== 'boolean') {
+				queryInvalid('exists requires a boolean', collection.name);
+			}
+			return;
+		}
+		case 'in':
+		case 'nin': {
+			const declared = validateField(collection, node.field)!;
+			if (!Array.isArray(node.value) || node.value.length === 0) {
+				queryInvalid(`${node.op} requires a non-empty array`, collection.name);
+			}
+			for (const value of node.value) {
+				if (!typeMatches(declared.type, value)) {
+					queryInvalid(`${node.op} value does not match field type`, collection.name);
+				}
+			}
+			return;
+		}
+		case 'between': {
+			const declared = validateField(collection, node.field)!;
+			if (!Array.isArray(node.value) || node.value.length !== 2) {
+				queryInvalid('between requires exactly two bounds', collection.name);
+			}
+			for (const value of node.value) {
+				if (!typeMatches(declared.type, value)) {
+					queryInvalid('between bound does not match field type', collection.name);
+				}
+			}
+			return;
+		}
+		case 'eq':
+		case 'ne':
+		case 'lt':
+		case 'lte':
+		case 'gt':
+		case 'gte': {
+			const declared = validateField(collection, node.field)!;
+			if (declared.type === 'boolean' && ORDERED_OPERATORS.has(node.op)) {
+				queryInvalid('ordered comparison is not defined for a boolean', collection.name);
+			}
+			if (!typeMatches(declared.type, node.value)) {
+				queryInvalid('filter value does not match field type', collection.name);
+			}
+			return;
+		}
+		default: {
+			queryInvalid(
+				`unsupported operator ${sanitizeIdentifier(String((node as { op: string }).op))}`,
+				collection.name,
+			);
+		}
+	}
+}
+
+export function validateSort(collection: CollectionSchema, sort: SortKey[]): void {
+	const seen = new Set<string>();
+	for (const key of sort) {
+		validateField(collection, key.field);
+		if (seen.has(key.field)) {
+			queryInvalid(`duplicate sort field ${sanitizeIdentifier(key.field)}`, collection.name);
+		}
+		seen.add(key.field);
+		if (key.direction && key.direction !== 'asc' && key.direction !== 'desc') {
+			queryInvalid('sort direction must be asc or desc', collection.name);
+		}
+	}
+}
+
+export function validatePageSize(size: number): void {
+	if (!Number.isInteger(size) || size < 1 || size > Budgets.MAX_PAGE_SIZE) {
+		raise(DiagnosticCodes.PAGE_SIZE_INVALID, {
+			message: 'page size out of range',
+			detail: { limit: Budgets.MAX_PAGE_SIZE },
+		});
+	}
+}
+
+export function validateQuery(collection: CollectionSchema, query: Query | undefined): void {
+	if (!query) {
+		return;
+	}
+	if (query.filter) {
+		validateFilter(collection, query.filter);
+	}
+	if (query.sort) {
+		validateSort(collection, query.sort);
+	}
+	if (query.page) {
+		validatePageSize(query.page.size);
+	}
+}

package/src/schema/declare.ts

@@ -1,45 +1,42 @@
-/**
- * Schema lookup helpers shared by both adapters.
- *
- * Declaring a field makes it queryable — it does not restrict what a record
- * may contain. `isQueryable` is the single answer to "may a filter or sort
- * reference this?", so both adapters reject the same field names (FR-034).
- */
-
-import type { CollectionSchema, FieldDeclaration } from '../contract/schema';
-
-export type SchemaIndex = ReadonlyMap<string, CollectionSchema>;
-
-export function indexSchemas(collections: CollectionSchema[]): SchemaIndex {
-	return new Map(collections.map(collection => [collection.name, collection]));
-}
-
-export function fieldOf(
-	collection: CollectionSchema,
-	name: string,
-): FieldDeclaration | undefined {
-	return collection.fields?.find(field => field.name === name);
-}
-
-export function isQueryable(collection: CollectionSchema, name: string): boolean {
-	return fieldOf(collection, name) !== undefined;
-}
-
-export function hasSoftDelete(collection: CollectionSchema): boolean {
-	return collection.softDelete === true;
-}
-
-export function hasTimestamps(collection: CollectionSchema): boolean {
-	return collection.timestamps === true;
-}
-
-/** Column name for a projected queryable field. Prefixed to avoid colliding
- * with the reserved columns (`id`, `payload`, `created_at`, ...). */
-export function projectedColumn(field: string): string {
-	return `f_${field}`;
-}
-
-/** Table name for a collection, prefixed for the same reason. */
-export function collectionTable(name: string): string {
-	return `c_${name}`;
-}
+/**
+ * Schema lookup helpers shared by both adapters.
+ *
+ * Declaring a field makes it queryable — it does not restrict what a record
+ * may contain. `isQueryable` is the single answer to "may a filter or sort
+ * reference this?", so both adapters reject the same field names (FR-034).
+ */
+
+import type { CollectionSchema, FieldDeclaration } from '../contract/schema';
+
+export type SchemaIndex = ReadonlyMap<string, CollectionSchema>;
+
+export function indexSchemas(collections: CollectionSchema[]): SchemaIndex {
+	return new Map(collections.map(collection => [collection.name, collection]));
+}
+
+export function fieldOf(collection: CollectionSchema, name: string): FieldDeclaration | undefined {
+	return collection.fields?.find(field => field.name === name);
+}
+
+export function isQueryable(collection: CollectionSchema, name: string): boolean {
+	return fieldOf(collection, name) !== undefined;
+}
+
+export function hasSoftDelete(collection: CollectionSchema): boolean {
+	return collection.softDelete === true;
+}
+
+export function hasTimestamps(collection: CollectionSchema): boolean {
+	return collection.timestamps === true;
+}
+
+/** Column name for a projected queryable field. Prefixed to avoid colliding
+ * with the reserved columns (`id`, `payload`, `created_at`, ...). */
+export function projectedColumn(field: string): string {
+	return `f_${field}`;
+}
+
+/** Table name for a collection, prefixed for the same reason. */
+export function collectionTable(name: string): string {
+	return `c_${name}`;
+}