@chipmobilesdk/rn-local-db 0.1.2 → 0.2.1

package/src/query/compare.ts

@@ -1,91 +1,91 @@
-/**
- * Comparison and field access semantics.
- *
- * Defined once here, used by the in-memory adapter directly and by the SQL
- * builder for validation and cursor construction. Two implementations of
- * these rules would drift, and the drift would show up as a conformance
- * divergence that hides a real bug (research.md R8).
- */
-
-import type { FilterValue } from '../contract/query';
-import type { StorableRecordData, StorableValue } from '../contract/record';
-
-/**
- * A field is one of three things, and the difference is the whole point of
- * FR-019: present with a value, present and null, or absent.
- */
-export type FieldLookup =
-	| { present: true; value: Exclude<StorableValue, null> }
-	| { present: true; value: null }
-	| { present: false };
-
-export function lookupField(data: StorableRecordData, field: string): FieldLookup {
-	if (!Object.prototype.hasOwnProperty.call(data, field)) {
-		return { present: false };
-	}
-	const value = data[field];
-	if (value === null) {
-		return { present: true, value: null };
-	}
-	return { present: true, value: value as Exclude<StorableValue, null> };
-}
-
-/**
- * Ordering for values of the same declared type.
- *
- * Null sorts before every non-null value, matching SQLite's default so the
- * two adapters agree without the SQL builder emitting NULLS FIRST/LAST
- * clauses that older SQLite versions do not support.
- */
-export function compareValues(a: FilterValue, b: FilterValue): number {
-	if (a === null && b === null) {
-		return 0;
-	}
-	if (a === null) {
-		return -1;
-	}
-	if (b === null) {
-		return 1;
-	}
-	if (typeof a === 'boolean' || typeof b === 'boolean') {
-		return Number(a) - Number(b);
-	}
-	if (typeof a === 'number' && typeof b === 'number') {
-		if (Number.isNaN(a) || Number.isNaN(b)) {
-			return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? -1 : 1;
-		}
-		return a < b ? -1 : a > b ? 1 : 0;
-	}
-	const sa = String(a);
-	const sb = String(b);
-	// Byte-order rather than locale collation: a locale-aware comparison would
-	// make the stored order depend on device settings, so the same data would
-	// page differently on two phones.
-	return sa < sb ? -1 : sa > sb ? 1 : 0;
-}
-
-/** Only primitives can be compared; a nested object is never a filter target. */
-export function asFilterValue(value: StorableValue): FilterValue | undefined {
-	if (
-		value === null ||
-		typeof value === 'string' ||
-		typeof value === 'number' ||
-		typeof value === 'boolean'
-	) {
-		return value;
-	}
-	return undefined;
-}
-
-/**
- * Byte order, not locale collation.
- *
- * A locale-aware sort would make the reported order depend on device
- * settings, so two phones holding identical data would report it differently.
- */
-export function byteOrder(a: string, b: string): number {
-	if (a < b) {
-		return -1;
-	}
-	return a > b ? 1 : 0;
-}
+/**
+ * Comparison and field access semantics.
+ *
+ * Defined once here, used by the in-memory adapter directly and by the SQL
+ * builder for validation and cursor construction. Two implementations of
+ * these rules would drift, and the drift would show up as a conformance
+ * divergence that hides a real bug (research.md R8).
+ */
+
+import type { FilterValue } from '../contract/query';
+import type { StorableRecordData, StorableValue } from '../contract/record';
+
+/**
+ * A field is one of three things, and the difference is the whole point of
+ * FR-019: present with a value, present and null, or absent.
+ */
+export type FieldLookup =
+	| { present: true; value: Exclude<StorableValue, null> }
+	| { present: true; value: null }
+	| { present: false };
+
+export function lookupField(data: StorableRecordData, field: string): FieldLookup {
+	if (!Object.prototype.hasOwnProperty.call(data, field)) {
+		return { present: false };
+	}
+	const value = data[field];
+	if (value === null) {
+		return { present: true, value: null };
+	}
+	return { present: true, value: value as Exclude<StorableValue, null> };
+}
+
+/**
+ * Ordering for values of the same declared type.
+ *
+ * Null sorts before every non-null value, matching SQLite's default so the
+ * two adapters agree without the SQL builder emitting NULLS FIRST/LAST
+ * clauses that older SQLite versions do not support.
+ */
+export function compareValues(a: FilterValue, b: FilterValue): number {
+	if (a === null && b === null) {
+		return 0;
+	}
+	if (a === null) {
+		return -1;
+	}
+	if (b === null) {
+		return 1;
+	}
+	if (typeof a === 'boolean' || typeof b === 'boolean') {
+		return Number(a) - Number(b);
+	}
+	if (typeof a === 'number' && typeof b === 'number') {
+		if (Number.isNaN(a) || Number.isNaN(b)) {
+			return Number.isNaN(a) && Number.isNaN(b) ? 0 : Number.isNaN(a) ? -1 : 1;
+		}
+		return a < b ? -1 : a > b ? 1 : 0;
+	}
+	const sa = String(a);
+	const sb = String(b);
+	// Byte-order rather than locale collation: a locale-aware comparison would
+	// make the stored order depend on device settings, so the same data would
+	// page differently on two phones.
+	return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+
+/** Only primitives can be compared; a nested object is never a filter target. */
+export function asFilterValue(value: StorableValue): FilterValue | undefined {
+	if (
+		value === null ||
+		typeof value === 'string' ||
+		typeof value === 'number' ||
+		typeof value === 'boolean'
+	) {
+		return value;
+	}
+	return undefined;
+}
+
+/**
+ * Byte order, not locale collation.
+ *
+ * A locale-aware sort would make the reported order depend on device
+ * settings, so two phones holding identical data would report it differently.
+ */
+export function byteOrder(a: string, b: string): number {
+	if (a < b) {
+		return -1;
+	}
+	return a > b ? 1 : 0;
+}

package/src/query/cursor.ts

@@ -1,99 +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';
-
-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 Buffer.from(value, 'utf8').toString('base64');
-}
-
-function fromBase64(value: string): string {
-	if (typeof globalThis.atob === 'function') {
-		return decodeURIComponent(escape(globalThis.atob(value)));
-	}
-	return Buffer.from(value, 'base64').toString('utf8');
-}
-
-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,
+	};
+}