@chipmobilesdk/rn-local-db 0.2.0 → 0.2.1

package/src/sqlite/index-coverage.ts

@@ -1,56 +1,54 @@
-/**
- * "Is this query covered by an index?", answered by the engine rather than by
- * inspection of the declarations (FR-037).
- *
- * Reading the schema would answer what the developer intended; `EXPLAIN QUERY
- * PLAN` answers what SQLite will actually do, and the two diverge exactly
- * where it matters — a filter on an indexed field that the planner declines
- * because of a type mismatch or a leading wildcard still reports as "indexed"
- * if you only read declarations.
- *
- * Exposed as a development-mode diagnostic. It runs an extra statement, so an
- * app calling it on every list would pay for it.
- */
-
-import type { IndexCoverageReport, Query, SortKey } from '../contract/query';
-import type { CollectionSchema } from '../contract/schema';
-import { collectionTable } from '../schema/declare';
-import type { Executor } from './connection';
-import { buildFilter, buildOrderBy } from './sql-builder';
-import { declaredIndexName } from './row-codec';
-
-const SCAN = /\bSCAN\b/i;
-const USING_INDEX = /USING\s+(COVERING\s+)?INDEX\s+"?([A-Za-z0-9_]+)"?/i;
-
-export async function explainQuery(
-	executor: Executor,
-	schema: CollectionSchema,
-	query: Query | undefined,
-	sort: SortKey[],
-): Promise<IndexCoverageReport> {
-	const filter = buildFilter(query?.filter);
-	const table = collectionTable(schema.name);
-	const sql = `EXPLAIN QUERY PLAN SELECT id FROM "${table}" WHERE ${filter.sql} ORDER BY ${buildOrderBy(
-		sort,
-	)}`;
-
-	const result = await executor.execute(sql, filter.params);
-	const detail = result.rows
-		.map(row => String(row.detail ?? row.DETAIL ?? ''))
-		.filter(Boolean)
-		.join('; ');
-
-	const match = USING_INDEX.exec(detail);
-	return {
-		collection: schema.name,
-		usesIndex: match !== null,
-		// Reported under the name the app declared, not the collection-scoped
-		// name it has in the file.
-		indexName: match?.[2] === undefined ? undefined : declaredIndexName(schema, match[2]),
-		detail:
-			detail ||
-			(SCAN.test(detail)
-				? 'full table scan'
-				: 'the engine returned no plan for this query'),
-	};
-}
+/**
+ * "Is this query covered by an index?", answered by the engine rather than by
+ * inspection of the declarations (FR-037).
+ *
+ * Reading the schema would answer what the developer intended; `EXPLAIN QUERY
+ * PLAN` answers what SQLite will actually do, and the two diverge exactly
+ * where it matters — a filter on an indexed field that the planner declines
+ * because of a type mismatch or a leading wildcard still reports as "indexed"
+ * if you only read declarations.
+ *
+ * Exposed as a development-mode diagnostic. It runs an extra statement, so an
+ * app calling it on every list would pay for it.
+ */
+
+import type { IndexCoverageReport, Query, SortKey } from '../contract/query';
+import type { CollectionSchema } from '../contract/schema';
+import { collectionTable } from '../schema/declare';
+import type { Executor } from './connection';
+import { buildFilter, buildOrderBy } from './sql-builder';
+import { declaredIndexName } from './row-codec';
+
+const SCAN = /\bSCAN\b/i;
+const USING_INDEX = /USING\s+(COVERING\s+)?INDEX\s+"?([A-Za-z0-9_]+)"?/i;
+
+export async function explainQuery(
+	executor: Executor,
+	schema: CollectionSchema,
+	query: Query | undefined,
+	sort: SortKey[],
+): Promise<IndexCoverageReport> {
+	const filter = buildFilter(query?.filter);
+	const table = collectionTable(schema.name);
+	const sql = `EXPLAIN QUERY PLAN SELECT id FROM "${table}" WHERE ${filter.sql} ORDER BY ${buildOrderBy(
+		sort,
+	)}`;
+
+	const result = await executor.execute(sql, filter.params);
+	const detail = result.rows
+		.map(row => String(row.detail ?? row.DETAIL ?? ''))
+		.filter(Boolean)
+		.join('; ');
+
+	const match = USING_INDEX.exec(detail);
+	return {
+		collection: schema.name,
+		usesIndex: match !== null,
+		// Reported under the name the app declared, not the collection-scoped
+		// name it has in the file.
+		indexName: match?.[2] === undefined ? undefined : declaredIndexName(schema, match[2]),
+		detail:
+			detail ||
+			(SCAN.test(detail) ? 'full table scan' : 'the engine returned no plan for this query'),
+	};
+}

package/src/sqlite/native.ts

@@ -1,83 +1,83 @@
-/**
- * The storage engine peer, behind one lazy accessor.
- *
- * Every native call the package makes to SQLite passes through this type.
- * Note what is missing: `executeSync`. op-sqlite ships it, and using it would
- * put a database read on the interface thread — the one thing PERF-001's
- * 16-millisecond rule cannot survive (research.md R9). A surface that cannot
- * express the synchronous call is a stronger guarantee than a review comment.
- */
-
-import { DiagnosticCodes } from '../contract/errors';
-import { raise } from '../diagnostics/errors';
-
-export type SqlValue = string | number | boolean | null | undefined;
-
-export type ExecuteResult = {
-	rows: Record<string, unknown>[];
-	rowsAffected: number;
-};
-
-export type NativeTransaction = {
-	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
-	commit(): Promise<void>;
-	rollback(): Promise<void>;
-};
-
-export type NativeDatabase = {
-	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
-	executeBatch(commands: [string, SqlValue[]?][]): Promise<ExecuteResult>;
-	transaction<T>(fn: (tx: NativeTransaction) => Promise<T>): Promise<T>;
-	close(): Promise<void>;
-	delete(): Promise<void>;
-};
-
-export type OpenOptions = {
-	name: string;
-	location?: string;
-	/** SQLCipher only. Never logged, never persisted, never returned (FR-098). */
-	encryptionKey?: string;
-};
-
-export type Engine = {
-	open(options: OpenOptions): NativeDatabase;
-	isSQLCipher?: () => boolean;
-};
-
-let override: Engine | null = null;
-let cached: Engine | null = null;
-
-/** Swap the engine. Tests only. */
-export function setEngine(next: Engine | null): void {
-	override = next;
-	cached = null;
-}
-
-export function engine(): Engine {
-	if (override) {
-		return override;
-	}
-	if (!cached) {
-		try {
-			cached = require('@op-engineering/op-sqlite') as Engine;
-		} catch (error) {
-			raise(DiagnosticCodes.OPEN_FAILED, {
-				message: 'storage engine peer is not installed',
-				cause: error,
-			});
-		}
-	}
-	return cached!;
-}
-
-/**
- * Whether SQLCipher is compiled into this build.
- *
- * A build flag in the consuming app, not a separate peer (research.md R1a).
- * An app that enables encryption without it must fail loudly rather than
- * write plaintext to a file it believes is encrypted.
- */
-export function isEncryptionAvailable(): boolean {
-	const current = engine();
-	return typeof current.isSQLCipher === 'function' ? current.isSQLCipher() === true : false;
-}
+/**
+ * The storage engine peer, behind one lazy accessor.
+ *
+ * Every native call the package makes to SQLite passes through this type.
+ * Note what is missing: `executeSync`. op-sqlite ships it, and using it would
+ * put a database read on the interface thread — the one thing PERF-001's
+ * 16-millisecond rule cannot survive (research.md R9). A surface that cannot
+ * express the synchronous call is a stronger guarantee than a review comment.
+ */
+
+import { DiagnosticCodes } from '../contract/errors';
+import { raise } from '../diagnostics/errors';
+
+export type SqlValue = string | number | boolean | null | undefined;
+
+export type ExecuteResult = {
+	rows: Record<string, unknown>[];
+	rowsAffected: number;
+};
+
+export type NativeTransaction = {
+	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+	commit(): Promise<void>;
+	rollback(): Promise<void>;
+};
+
+export type NativeDatabase = {
+	execute(sql: string, params?: SqlValue[]): Promise<ExecuteResult>;
+	executeBatch(commands: [string, SqlValue[]?][]): Promise<ExecuteResult>;
+	transaction<T>(fn: (tx: NativeTransaction) => Promise<T>): Promise<T>;
+	close(): Promise<void>;
+	delete(): Promise<void>;
+};
+
+export type OpenOptions = {
+	name: string;
+	location?: string;
+	/** SQLCipher only. Never logged, never persisted, never returned (FR-098). */
+	encryptionKey?: string;
+};
+
+export type Engine = {
+	open(options: OpenOptions): NativeDatabase;
+	isSQLCipher?: () => boolean;
+};
+
+let override: Engine | null = null;
+let cached: Engine | null = null;
+
+/** Swap the engine. Tests only. */
+export function setEngine(next: Engine | null): void {
+	override = next;
+	cached = null;
+}
+
+export function engine(): Engine {
+	if (override) {
+		return override;
+	}
+	if (!cached) {
+		try {
+			cached = require('@op-engineering/op-sqlite') as Engine;
+		} catch (error) {
+			raise(DiagnosticCodes.OPEN_FAILED, {
+				message: 'storage engine peer is not installed',
+				cause: error,
+			});
+		}
+	}
+	return cached!;
+}
+
+/**
+ * Whether SQLCipher is compiled into this build.
+ *
+ * A build flag in the consuming app, not a separate peer (research.md R1a).
+ * An app that enables encryption without it must fail loudly rather than
+ * write plaintext to a file it believes is encrypted.
+ */
+export function isEncryptionAvailable(): boolean {
+	const current = engine();
+	return typeof current.isSQLCipher === 'function' ? current.isSQLCipher() === true : false;
+}