@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/query/cursor.ts

@@ -1,100 +1,100 @@
-/**
- * Keyset pagination cursors.
- *
- * Keyset rather than OFFSET for two reasons, both of which SC-007 measures:
- * OFFSET degrades linearly at the 100,000-record budget because the engine
- * still walks the skipped rows, and it shifts pages under concurrent writes
- * so a record can be skipped or returned twice. A cursor anchored to the last
- * row's sort values has neither problem.
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import type { FilterValue, SortKey } from '../contract/query';
-import type { StoredRecord } from '../contract/record';
-import { raise } from '../diagnostics/errors';
-import { compareValues } from './compare';
-import { sortValueOf } from './sort';
-import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../platform/bytes';
-
-export type CursorPayload = {
-	/** Sort key fields and directions, so a cursor cannot be reused across shapes. */
-	k: string;
-	/** The last row's values, in sort-key order. */
-	v: FilterValue[];
-};
-
-function shapeOf(sort: SortKey[]): string {
-	return sort.map(key => `${key.field}:${key.direction === 'desc' ? 'd' : 'a'}`).join(',');
-}
-
-function toBase64(value: string): string {
-	if (typeof globalThis.btoa === 'function') {
-		return globalThis.btoa(unescape(encodeURIComponent(value)));
-	}
-	return bytesToBase64(utf8Bytes(value));
-}
-
-function fromBase64(value: string): string {
-	if (typeof globalThis.atob === 'function') {
-		return decodeURIComponent(escape(globalThis.atob(value)));
-	}
-	return utf8String(base64ToBytes(value));
-}
-
-export function encodeCursor(record: StoredRecord, sort: SortKey[]): string {
-	const payload: CursorPayload = {
-		k: shapeOf(sort),
-		v: sort.map(key => sortValueOf(record, key.field) ?? null),
-	};
-	return toBase64(JSON.stringify(payload));
-}
-
-export function decodeCursor(cursor: string, sort: SortKey[]): FilterValue[] {
-	let payload: CursorPayload;
-	try {
-		payload = JSON.parse(fromBase64(cursor)) as CursorPayload;
-	} catch {
-		raise(DiagnosticCodes.CURSOR_INVALID, { message: 'cursor is not decodable' });
-	}
-	if (!payload || typeof payload.k !== 'string' || !Array.isArray(payload.v)) {
-		raise(DiagnosticCodes.CURSOR_INVALID, { message: 'cursor payload is malformed' });
-	}
-	// A cursor from a differently sorted query would produce a silently wrong
-	// page rather than an error, so the shape is part of the cursor.
-	if (payload.k !== shapeOf(sort)) {
-		raise(DiagnosticCodes.CURSOR_INVALID, {
-			message: 'cursor does not match this query shape',
-		});
-	}
-	if (payload.v.length !== sort.length) {
-		raise(DiagnosticCodes.CURSOR_INVALID, { message: 'cursor arity does not match sort' });
-	}
-	return payload.v;
-}
-
-/**
- * Is this record strictly after the cursor position, under the sort order?
- *
- * Lexicographic across the sort keys: equal on the first key means the second
- * decides, and so on down to the id tiebreaker that guarantees a total order.
- */
-export function isAfterCursor(
-	record: StoredRecord,
-	sort: SortKey[],
-	anchor: FilterValue[],
-): boolean {
-	for (let i = 0; i < sort.length; i += 1) {
-		const key = sort[i]!;
-		const direction = key.direction === 'desc' ? -1 : 1;
-		const value = sortValueOf(record, key.field) ?? null;
-		const result = compareValues(value, anchor[i] ?? null) * direction;
-		if (result > 0) {
-			return true;
-		}
-		if (result < 0) {
-			return false;
-		}
-	}
-	// Equal on every key including id — this is the anchor row itself.
-	return false;
-}
+/**
+ * Keyset pagination cursors.
+ *
+ * Keyset rather than OFFSET for two reasons, both of which SC-007 measures:
+ * OFFSET degrades linearly at the 100,000-record budget because the engine
+ * still walks the skipped rows, and it shifts pages under concurrent writes
+ * so a record can be skipped or returned twice. A cursor anchored to the last
+ * row's sort values has neither problem.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import type { FilterValue, SortKey } from '../contract/query';
+import type { StoredRecord } from '../contract/record';
+import { raise } from '../diagnostics/errors';
+import { compareValues } from './compare';
+import { sortValueOf } from './sort';
+import { base64ToBytes, bytesToBase64, utf8Bytes, utf8String } from '../platform/bytes';
+
+export type CursorPayload = {
+	/** Sort key fields and directions, so a cursor cannot be reused across shapes. */
+	k: string;
+	/** The last row's values, in sort-key order. */
+	v: FilterValue[];
+};
+
+function shapeOf(sort: SortKey[]): string {
+	return sort.map(key => `${key.field}:${key.direction === 'desc' ? 'd' : 'a'}`).join(',');
+}
+
+function toBase64(value: string): string {
+	if (typeof globalThis.btoa === 'function') {
+		return globalThis.btoa(unescape(encodeURIComponent(value)));
+	}
+	return bytesToBase64(utf8Bytes(value));
+}
+
+function fromBase64(value: string): string {
+	if (typeof globalThis.atob === 'function') {
+		return decodeURIComponent(escape(globalThis.atob(value)));
+	}
+	return utf8String(base64ToBytes(value));
+}
+
+export function encodeCursor(record: StoredRecord, sort: SortKey[]): string {
+	const payload: CursorPayload = {
+		k: shapeOf(sort),
+		v: sort.map(key => sortValueOf(record, key.field) ?? null),
+	};
+	return toBase64(JSON.stringify(payload));
+}
+
+export function decodeCursor(cursor: string, sort: SortKey[]): FilterValue[] {
+	let payload: CursorPayload;
+	try {
+		payload = JSON.parse(fromBase64(cursor)) as CursorPayload;
+	} catch {
+		raise(DiagnosticCodes.CURSOR_INVALID, { message: 'cursor is not decodable' });
+	}
+	if (!payload || typeof payload.k !== 'string' || !Array.isArray(payload.v)) {
+		raise(DiagnosticCodes.CURSOR_INVALID, { message: 'cursor payload is malformed' });
+	}
+	// A cursor from a differently sorted query would produce a silently wrong
+	// page rather than an error, so the shape is part of the cursor.
+	if (payload.k !== shapeOf(sort)) {
+		raise(DiagnosticCodes.CURSOR_INVALID, {
+			message: 'cursor does not match this query shape',
+		});
+	}
+	if (payload.v.length !== sort.length) {
+		raise(DiagnosticCodes.CURSOR_INVALID, { message: 'cursor arity does not match sort' });
+	}
+	return payload.v;
+}
+
+/**
+ * Is this record strictly after the cursor position, under the sort order?
+ *
+ * Lexicographic across the sort keys: equal on the first key means the second
+ * decides, and so on down to the id tiebreaker that guarantees a total order.
+ */
+export function isAfterCursor(
+	record: StoredRecord,
+	sort: SortKey[],
+	anchor: FilterValue[],
+): boolean {
+	for (let i = 0; i < sort.length; i += 1) {
+		const key = sort[i]!;
+		const direction = key.direction === 'desc' ? -1 : 1;
+		const value = sortValueOf(record, key.field) ?? null;
+		const result = compareValues(value, anchor[i] ?? null) * direction;
+		if (result > 0) {
+			return true;
+		}
+		if (result < 0) {
+			return false;
+		}
+	}
+	// Equal on every key including id — this is the anchor row itself.
+	return false;
+}

package/src/query/filter.ts

@@ -1,82 +1,82 @@
-/**
- * Filter evaluation over a plain record.
- *
- * The in-memory adapter runs this directly. The SQLite adapter translates the
- * same validated tree to SQL. Both must agree, which is why the semantics
- * live here rather than in either of them.
- */
-
-import type { FilterNode, FilterValue } from '../contract/query';
-import type { StorableRecordData } from '../contract/record';
-import { asFilterValue, compareValues, lookupField } from './compare';
-
-function equals(a: FilterValue, b: FilterValue): boolean {
-	return compareValues(a, b) === 0 && (a === null) === (b === null);
-}
-
-export function evaluateFilter(data: StorableRecordData, node: FilterNode): boolean {
-	switch (node.op) {
-		case 'and':
-			return node.nodes.every(child => evaluateFilter(data, child));
-		case 'or':
-			return node.nodes.some(child => evaluateFilter(data, child));
-		case 'not':
-			return !evaluateFilter(data, node.node);
-		default:
-			break;
-	}
-
-	const lookup = lookupField(data, node.field);
-
-	// `exists` is the only operator that answers a question about presence,
-	// which is what keeps "absent" distinguishable from "null" (FR-019).
-	if (node.op === 'exists') {
-		return lookup.present === node.value;
-	}
-
-	if (!lookup.present) {
-		// An absent field satisfies nothing else — not even `ne` or `isNull`.
-		// SQL agrees: a comparison against a missing column yields NULL, which
-		// is not true.
-		return false;
-	}
-
-	const value = asFilterValue(lookup.value);
-	if (value === undefined) {
-		// A nested object or array is not comparable. Matching it would be a
-		// guess, so it simply does not satisfy a comparison.
-		return false;
-	}
-
-	switch (node.op) {
-		case 'isNull':
-			return value === null;
-		case 'isNotNull':
-			return value !== null;
-		case 'eq':
-			return equals(value, node.value);
-		case 'ne':
-			return !equals(value, node.value);
-		case 'lt':
-			return value !== null && node.value !== null && compareValues(value, node.value) < 0;
-		case 'lte':
-			return value !== null && node.value !== null && compareValues(value, node.value) <= 0;
-		case 'gt':
-			return value !== null && node.value !== null && compareValues(value, node.value) > 0;
-		case 'gte':
-			return value !== null && node.value !== null && compareValues(value, node.value) >= 0;
-		case 'in':
-			return node.value.some(candidate => equals(value, candidate));
-		case 'nin':
-			return !node.value.some(candidate => equals(value, candidate));
-		case 'between': {
-			const [low, high] = node.value;
-			if (value === null || low === null || high === null) {
-				return false;
-			}
-			return compareValues(value, low) >= 0 && compareValues(value, high) <= 0;
-		}
-		default:
-			return false;
-	}
-}
+/**
+ * Filter evaluation over a plain record.
+ *
+ * The in-memory adapter runs this directly. The SQLite adapter translates the
+ * same validated tree to SQL. Both must agree, which is why the semantics
+ * live here rather than in either of them.
+ */
+
+import type { FilterNode, FilterValue } from '../contract/query';
+import type { StorableRecordData } from '../contract/record';
+import { asFilterValue, compareValues, lookupField } from './compare';
+
+function equals(a: FilterValue, b: FilterValue): boolean {
+	return compareValues(a, b) === 0 && (a === null) === (b === null);
+}
+
+export function evaluateFilter(data: StorableRecordData, node: FilterNode): boolean {
+	switch (node.op) {
+		case 'and':
+			return node.nodes.every(child => evaluateFilter(data, child));
+		case 'or':
+			return node.nodes.some(child => evaluateFilter(data, child));
+		case 'not':
+			return !evaluateFilter(data, node.node);
+		default:
+			break;
+	}
+
+	const lookup = lookupField(data, node.field);
+
+	// `exists` is the only operator that answers a question about presence,
+	// which is what keeps "absent" distinguishable from "null" (FR-019).
+	if (node.op === 'exists') {
+		return lookup.present === node.value;
+	}
+
+	if (!lookup.present) {
+		// An absent field satisfies nothing else — not even `ne` or `isNull`.
+		// SQL agrees: a comparison against a missing column yields NULL, which
+		// is not true.
+		return false;
+	}
+
+	const value = asFilterValue(lookup.value);
+	if (value === undefined) {
+		// A nested object or array is not comparable. Matching it would be a
+		// guess, so it simply does not satisfy a comparison.
+		return false;
+	}
+
+	switch (node.op) {
+		case 'isNull':
+			return value === null;
+		case 'isNotNull':
+			return value !== null;
+		case 'eq':
+			return equals(value, node.value);
+		case 'ne':
+			return !equals(value, node.value);
+		case 'lt':
+			return value !== null && node.value !== null && compareValues(value, node.value) < 0;
+		case 'lte':
+			return value !== null && node.value !== null && compareValues(value, node.value) <= 0;
+		case 'gt':
+			return value !== null && node.value !== null && compareValues(value, node.value) > 0;
+		case 'gte':
+			return value !== null && node.value !== null && compareValues(value, node.value) >= 0;
+		case 'in':
+			return node.value.some(candidate => equals(value, candidate));
+		case 'nin':
+			return !node.value.some(candidate => equals(value, candidate));
+		case 'between': {
+			const [low, high] = node.value;
+			if (value === null || low === null || high === null) {
+				return false;
+			}
+			return compareValues(value, low) >= 0 && compareValues(value, high) <= 0;
+		}
+		default:
+			return false;
+	}
+}

package/src/query/paginate.ts

@@ -1,51 +1,51 @@
-/**
- * Page assembly over already-filtered, already-sorted records.
- *
- * Shared so the in-memory adapter and the SQLite adapter produce identical
- * pages, including the `hasMore` signal and when a cursor is emitted.
- */
-
-import { Budgets } from '../contract/config';
-import type { PageRequest, ResultPage, SortKey } from '../contract/query';
-import type { StorableRecordData, StoredRecord } from '../contract/record';
-import { decodeCursor, encodeCursor, isAfterCursor } from './cursor';
-
-export const DEFAULT_PAGE_SIZE = 50;
-
-export function resolvePageSize(page: PageRequest | undefined): number {
-	return page?.size ?? DEFAULT_PAGE_SIZE;
-}
-
-/** Fetch one extra row to answer `hasMore` without a second count query. */
-export function fetchLimitFor(size: number): number {
-	return Math.min(size, Budgets.MAX_PAGE_SIZE) + 1;
-}
-
-export function applyCursor<T extends StoredRecord>(
-	records: T[],
-	sort: SortKey[],
-	cursor: string | undefined,
-): T[] {
-	if (!cursor) {
-		return records;
-	}
-	const anchor = decodeCursor(cursor, sort);
-	return records.filter(record => isAfterCursor(record, sort, anchor));
-}
-
-export function buildPage<T extends StorableRecordData>(
-	records: StoredRecord<T>[],
-	sort: SortKey[],
-	size: number,
-): ResultPage<T> {
-	const hasMore = records.length > size;
-	const page = hasMore ? records.slice(0, size) : records;
-	const last = page[page.length - 1];
-	return {
-		records: page,
-		// No cursor on the final page: handing one back invites a consumer to
-		// keep paging past the end and treat an empty page as an error.
-		cursor: hasMore && last ? encodeCursor(last, sort) : undefined,
-		hasMore,
-	};
-}
+/**
+ * Page assembly over already-filtered, already-sorted records.
+ *
+ * Shared so the in-memory adapter and the SQLite adapter produce identical
+ * pages, including the `hasMore` signal and when a cursor is emitted.
+ */
+
+import { Budgets } from '../contract/config';
+import type { PageRequest, ResultPage, SortKey } from '../contract/query';
+import type { StorableRecordData, StoredRecord } from '../contract/record';
+import { decodeCursor, encodeCursor, isAfterCursor } from './cursor';
+
+export const DEFAULT_PAGE_SIZE = 50;
+
+export function resolvePageSize(page: PageRequest | undefined): number {
+	return page?.size ?? DEFAULT_PAGE_SIZE;
+}
+
+/** Fetch one extra row to answer `hasMore` without a second count query. */
+export function fetchLimitFor(size: number): number {
+	return Math.min(size, Budgets.MAX_PAGE_SIZE) + 1;
+}
+
+export function applyCursor<T extends StoredRecord>(
+	records: T[],
+	sort: SortKey[],
+	cursor: string | undefined,
+): T[] {
+	if (!cursor) {
+		return records;
+	}
+	const anchor = decodeCursor(cursor, sort);
+	return records.filter(record => isAfterCursor(record, sort, anchor));
+}
+
+export function buildPage<T extends StorableRecordData>(
+	records: StoredRecord<T>[],
+	sort: SortKey[],
+	size: number,
+): ResultPage<T> {
+	const hasMore = records.length > size;
+	const page = hasMore ? records.slice(0, size) : records;
+	const last = page[page.length - 1];
+	return {
+		records: page,
+		// No cursor on the final page: handing one back invites a consumer to
+		// keep paging past the end and treat an empty page as an error.
+		cursor: hasMore && last ? encodeCursor(last, sort) : undefined,
+		hasMore,
+	};
+}

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));
+}