@rozenite/sqlite-plugin 1.7.0-rc.0

package/src/react-native/adapters/generic.ts

@@ -0,0 +1,88 @@
+import type {
+  SqliteAdapter,
+  SqliteDatabaseNode,
+  SqliteExecuteStatementsRunner,
+} from '../../shared/types';
+
+type SqliteDatabaseConfig = {
+  name?: string;
+  executeStatements: SqliteExecuteStatementsRunner;
+};
+
+type SingleDatabaseOptions = {
+  database: SqliteExecuteStatementsRunner | SqliteDatabaseConfig;
+  adapterId?: string;
+  adapterName?: string;
+  databaseName?: string;
+};
+
+type MultiDatabaseOptions = {
+  databases: Record<
+    string,
+    SqliteExecuteStatementsRunner | SqliteDatabaseConfig
+  >;
+  adapterId?: string;
+  adapterName?: string;
+};
+
+export type CreateSqliteAdapterOptions =
+  | SingleDatabaseOptions
+  | MultiDatabaseOptions;
+
+const slugify = (value: string) =>
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'database';
+
+const createDatabaseId = (adapterId: string, seed: string, index: number) =>
+  `${adapterId}__${slugify(seed)}__${index.toString(36)}`;
+
+const resolveDatabaseConfig = (
+  config: SqliteExecuteStatementsRunner | SqliteDatabaseConfig,
+) => (typeof config === 'function' ? { executeStatements: config } : config);
+
+const toDatabaseNode = (
+  adapterId: string,
+  databaseKey: string,
+  config: SqliteExecuteStatementsRunner | SqliteDatabaseConfig,
+  index: number,
+  fallbackName?: string,
+): SqliteDatabaseNode => {
+  const resolved = resolveDatabaseConfig(config);
+  const name = resolved.name ?? fallbackName ?? databaseKey;
+
+  return {
+    id: createDatabaseId(adapterId, `${databaseKey}-${name}`, index),
+    name,
+    executeStatements: resolved.executeStatements,
+  };
+};
+
+export const createSqliteAdapter = (
+  options: CreateSqliteAdapterOptions,
+): SqliteAdapter => {
+  const { adapterId = 'sqlite', adapterName = 'SQLite' } = options;
+
+  const databases =
+    'databases' in options
+      ? Object.entries(options.databases).map(([key, config], index) =>
+          toDatabaseNode(adapterId, key, config, index),
+        )
+      : [
+          toDatabaseNode(
+            adapterId,
+            options.databaseName ?? 'default',
+            options.database,
+            0,
+            options.databaseName ?? 'Default Database',
+          ),
+        ];
+
+  return {
+    id: adapterId,
+    name: adapterName,
+    databases,
+  };
+};

package/src/react-native/adapters/index.ts

@@ -0,0 +1,9 @@
+export {
+  createSqliteAdapter,
+  type CreateSqliteAdapterOptions,
+} from './generic';
+export {
+  createExpoSqliteAdapter,
+  type CreateExpoSqliteAdapterOptions,
+  type ExpoSqliteLike,
+} from './expo-sqlite';

package/src/react-native/sqlite-view.ts

@@ -0,0 +1,24 @@
+import type {
+  SqliteAdapter,
+  SqliteDatabaseInfo,
+  SqliteStatementInput,
+} from '../shared/types';
+
+export type SqliteDatabaseView = SqliteDatabaseInfo & {
+  executeStatements: (
+    statements: SqliteStatementInput[],
+  ) => ReturnType<SqliteAdapter['databases'][number]['executeStatements']>;
+};
+
+export const createSqliteDatabaseViews = (
+  adapters: SqliteAdapter[],
+): SqliteDatabaseView[] =>
+  adapters.flatMap((adapter) =>
+    adapter.databases.map((database) => ({
+      id: database.id,
+      name: database.name,
+      adapterId: adapter.id,
+      adapterName: adapter.name,
+      executeStatements: database.executeStatements,
+    })),
+  );

package/src/react-native/useRozeniteSqlitePlugin.ts

@@ -0,0 +1,262 @@
+import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { useEffect, useMemo, useRef } from 'react';
+import { formatSqliteError } from '../shared/bridge-values';
+import { PLUGIN_ID, type SqliteEventMap } from '../shared/protocol';
+import { normalizeSingleStatementSql, splitSqlStatements } from '../shared/sql';
+import type {
+  SqliteAdapter,
+  SqliteExecuteStatementsError,
+  SqliteQueryParams,
+  SqliteStatementInput,
+} from '../shared/types';
+import { createSqliteDatabaseViews } from './sqlite-view';
+
+export type RozeniteSqlitePluginOptions = {
+  adapters: SqliteAdapter[];
+};
+
+const safeError = (error: unknown) => formatSqliteError(error);
+
+const isExecuteStatementsError = (
+  error: unknown,
+): error is SqliteExecuteStatementsError =>
+  error instanceof Error &&
+  ('completedResults' in error || 'failedStatementIndex' in error);
+
+export const useRozeniteSqlitePlugin = ({
+  adapters,
+}: RozeniteSqlitePluginOptions) => {
+  const views = useMemo(() => createSqliteDatabaseViews(adapters), [adapters]);
+  const client = useRozeniteDevToolsClient<SqliteEventMap>({
+    pluginId: PLUGIN_ID,
+  });
+  const subscriptionsRef = useRef<Array<{ remove: () => void }>>([]);
+  const databaseQueuesRef = useRef(new Map<string, Promise<void>>());
+
+  useEffect(() => {
+    if (!client) {
+      return;
+    }
+
+    const enqueueDatabaseTask = async <T>(
+      databaseId: string,
+      task: () => Promise<T>,
+    ): Promise<T> => {
+      const queue =
+        databaseQueuesRef.current.get(databaseId) ?? Promise.resolve();
+      const next = queue.catch(() => undefined).then(task);
+
+      databaseQueuesRef.current.set(
+        databaseId,
+        next.then(
+          () => undefined,
+          () => undefined,
+        ),
+      );
+
+      return next;
+    };
+
+    const resolveDatabase = (databaseId: string) => {
+      const database = views.find((view) => view.id === databaseId);
+
+      if (!database) {
+        throw new Error(`Unknown database "${databaseId}".`);
+      }
+
+      return database;
+    };
+
+    const executeStatements = async (
+      databaseId: string,
+      statements: SqliteStatementInput[],
+    ) => {
+      const database = resolveDatabase(databaseId);
+      const normalizedStatements = statements.map(({ sql, params }) => ({
+        sql: normalizeSingleStatementSql(sql),
+        params,
+      }));
+      const results = await database.executeStatements(normalizedStatements);
+
+      if (results.length !== normalizedStatements.length) {
+        throw new Error(
+          `Expected ${normalizedStatements.length} statement result(s), received ${results.length}.`,
+        );
+      }
+
+      return {
+        inputs: normalizedStatements,
+        results,
+      };
+    };
+
+    const executeSingleQuery = async (
+      databaseId: string,
+      sql: string,
+      params?: SqliteQueryParams,
+    ) => {
+      const execution = await executeStatements(databaseId, [
+        {
+          sql,
+          params,
+        },
+      ]);
+      const result = execution.results[0];
+
+      if (!result) {
+        throw new Error('The query completed without a result payload.');
+      }
+
+      return result;
+    };
+
+    client.send('sqlite:ready', { timestamp: Date.now() });
+
+    subscriptionsRef.current.push(
+      client.onMessage('sqlite:list-databases', ({ requestId }) => {
+        client.send('sqlite:list-databases:result', {
+          requestId,
+          databases: views.map(({ id, name, adapterId, adapterName }) => ({
+            id,
+            name,
+            adapterId,
+            adapterName,
+          })),
+        });
+      }),
+    );
+
+    subscriptionsRef.current.push(
+      client.onMessage(
+        'sqlite:query',
+        async ({ requestId, databaseId, sql, params }) => {
+          try {
+            const result = await enqueueDatabaseTask(databaseId, () =>
+              executeSingleQuery(databaseId, sql, params),
+            );
+
+            client.send('sqlite:query:result', {
+              requestId,
+              databaseId,
+              result,
+            });
+          } catch (error) {
+            client.send('sqlite:query:result', {
+              requestId,
+              databaseId,
+              error: safeError(error),
+            });
+          }
+        },
+      ),
+    );
+
+    subscriptionsRef.current.push(
+      client.onMessage(
+        'sqlite:execute-script',
+        async ({ requestId, databaseId, sql }) => {
+          try {
+            const result = await enqueueDatabaseTask(databaseId, async () => {
+              const statementSegments = splitSqlStatements(sql);
+
+              if (statementSegments.length === 0) {
+                throw new Error('Query cannot be empty.');
+              }
+
+              const statementInputs = statementSegments.map((statement) => ({
+                sql: statement.text,
+              }));
+
+              try {
+                const execution = await executeStatements(
+                  databaseId,
+                  statementInputs,
+                );
+
+                return {
+                  statements: statementSegments.map((statement, index) => ({
+                    index,
+                    start: statement.start,
+                    end: statement.end,
+                    input: execution.inputs[index],
+                    execution: {
+                      input: execution.inputs[index],
+                      result: execution.results[index],
+                    },
+                  })),
+                  totalStatementCount: statementSegments.length,
+                  failedStatementIndex: null,
+                };
+              } catch (error) {
+                if (!isExecuteStatementsError(error)) {
+                  throw error;
+                }
+
+                const failedStatementIndex = Math.max(
+                  0,
+                  Math.min(
+                    typeof error.failedStatementIndex === 'number'
+                      ? error.failedStatementIndex
+                      : (error.completedResults?.length ?? 0),
+                    statementSegments.length - 1,
+                  ),
+                );
+                const completedResults = (error.completedResults ?? []).slice(
+                  0,
+                  failedStatementIndex,
+                );
+                const completedStatements = completedResults.map(
+                  (queryResult, index) => ({
+                    index,
+                    start: statementSegments[index].start,
+                    end: statementSegments[index].end,
+                    input: statementInputs[index],
+                    execution: {
+                      input: statementInputs[index],
+                      result: queryResult,
+                    },
+                  }),
+                );
+
+                return {
+                  statements: [
+                    ...completedStatements,
+                    {
+                      index: failedStatementIndex,
+                      start: statementSegments[failedStatementIndex].start,
+                      end: statementSegments[failedStatementIndex].end,
+                      input: statementInputs[failedStatementIndex],
+                      error: safeError(error),
+                    },
+                  ],
+                  totalStatementCount: statementSegments.length,
+                  failedStatementIndex,
+                };
+              }
+            });
+
+            client.send('sqlite:execute-script:result', {
+              requestId,
+              databaseId,
+              result,
+            });
+          } catch (error) {
+            client.send('sqlite:execute-script:result', {
+              requestId,
+              databaseId,
+              error: safeError(error),
+            });
+          }
+        },
+      ),
+    );
+
+    return () => {
+      subscriptionsRef.current.forEach((subscription) => subscription.remove());
+      subscriptionsRef.current = [];
+      databaseQueuesRef.current.clear();
+    };
+  }, [client, views]);
+
+  return client;
+};

package/src/shared/__tests__/bridge-values.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import {
+  decodeSqliteBridgeValue,
+  encodeSqliteBridgeValue,
+  formatSqliteError,
+} from '../bridge-values';
+
+describe('sqlite bridge values', () => {
+  it('round-trips Uint8Array values through a bridge-safe payload', () => {
+    const original = {
+      params: [new Uint8Array([1, 2, 255]), { nested: new Uint8Array([9, 8]) }],
+    };
+
+    expect(decodeSqliteBridgeValue(encodeSqliteBridgeValue(original))).toEqual(
+      original,
+    );
+  });
+
+  it('formats nested error details with code and cause information', () => {
+    const error = Object.assign(
+      new Error("Calling the 'runAsync' function has failed"),
+      {
+        cause: {
+          code: 'ERR_INTERNAL_SQLITE_ERROR',
+          reason: 'Invalid bind parameter',
+        },
+      },
+    );
+
+    expect(formatSqliteError(error)).toBe(
+      "Calling the 'runAsync' function has failed\nCaused by: [ERR_INTERNAL_SQLITE_ERROR] Invalid bind parameter",
+    );
+  });
+});

package/src/shared/__tests__/sql.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getStatementAtCursor,
+  normalizeSingleStatementSql,
+  splitSqlStatements,
+} from '../sql';
+
+describe('SQL statement helpers', () => {
+  it('finds the active statement when earlier statements contain comments and quoted semicolons', () => {
+    const sql = [
+      '-- setup comment;',
+      "SELECT 'semi;colon' AS value;",
+      "INSERT INTO logs(message) VALUES('done');",
+    ].join('\n');
+    const cursor = sql.indexOf('logs');
+
+    expect(getStatementAtCursor(sql, cursor)?.text).toBe(
+      "INSERT INTO logs(message) VALUES('done')",
+    );
+  });
+
+  it('normalizes a single statement and removes the trailing semicolon', () => {
+    expect(normalizeSingleStatementSql(' SELECT * FROM projects;  ')).toBe(
+      'SELECT * FROM projects',
+    );
+  });
+
+  it('rejects multiple statements', () => {
+    expect(() =>
+      normalizeSingleStatementSql('SELECT * FROM projects; DELETE FROM logs;'),
+    ).toThrow('Only a single SQL statement is supported in v1.');
+  });
+
+  it('splits statements while preserving source offsets', () => {
+    const sql = [
+      '-- comment before first statement',
+      'SELECT 1;',
+      '',
+      "INSERT INTO logs(message) VALUES('done');",
+    ].join('\n');
+
+    expect(splitSqlStatements(sql)).toEqual([
+      {
+        text: '-- comment before first statement\nSELECT 1',
+        start: 0,
+        end: sql.indexOf(';'),
+      },
+      {
+        text: "INSERT INTO logs(message) VALUES('done')",
+        start: 43,
+        end: sql.lastIndexOf(';'),
+      },
+    ]);
+  });
+});

package/src/shared/bridge-values.ts

@@ -0,0 +1,170 @@
+const SQLITE_BRIDGE_BINARY_TYPE = '__rozeniteSqliteBinary';
+
+type SqliteEncodedBinaryValue = {
+  [SQLITE_BRIDGE_BINARY_TYPE]: true;
+  data: number[];
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object';
+
+const isEncodedBinaryValue = (
+  value: unknown,
+): value is SqliteEncodedBinaryValue =>
+  isRecord(value) &&
+  value[SQLITE_BRIDGE_BINARY_TYPE] === true &&
+  Array.isArray(value.data) &&
+  value.data.every((item) => typeof item === 'number');
+
+export const encodeSqliteBridgeValue = (value: unknown): unknown => {
+  if (
+    value == null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+
+  if (value instanceof Uint8Array) {
+    return {
+      [SQLITE_BRIDGE_BINARY_TYPE]: true,
+      data: Array.from(value),
+    } satisfies SqliteEncodedBinaryValue;
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return {
+      [SQLITE_BRIDGE_BINARY_TYPE]: true,
+      data: Array.from(new Uint8Array(value)),
+    } satisfies SqliteEncodedBinaryValue;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(encodeSqliteBridgeValue);
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        encodeSqliteBridgeValue(nestedValue),
+      ]),
+    );
+  }
+
+  return String(value);
+};
+
+export const decodeSqliteBridgeValue = (value: unknown): unknown => {
+  if (
+    value == null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+
+  if (isEncodedBinaryValue(value)) {
+    return new Uint8Array(value.data);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(decodeSqliteBridgeValue);
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        decodeSqliteBridgeValue(nestedValue),
+      ]),
+    );
+  }
+
+  return value;
+};
+
+const getStringField = (value: unknown, key: string): string | null => {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const field = value[key];
+  if (typeof field !== 'string') {
+    return null;
+  }
+
+  const trimmed = field.trim();
+  return trimmed ? trimmed : null;
+};
+
+const stringifyFallback = (value: unknown): string => {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+};
+
+const describeError = (error: unknown): string | null => {
+  if (error instanceof Error) {
+    const code = getStringField(error, 'code');
+    const reason = getStringField(error, 'reason');
+    const message = error.message.trim();
+    const detailParts = [message || null, reason].filter(
+      (part, index, parts): part is string =>
+        !!part && parts.indexOf(part) === index,
+    );
+    const detail = detailParts.join(' | ') || error.name;
+
+    return code ? `[${code}] ${detail}` : detail;
+  }
+
+  if (isRecord(error)) {
+    const code = getStringField(error, 'code');
+    const message = getStringField(error, 'message');
+    const reason = getStringField(error, 'reason');
+    const detail = message ?? reason ?? stringifyFallback(error);
+
+    return code ? `[${code}] ${detail}` : detail;
+  }
+
+  if (typeof error === 'string') {
+    return error.trim() || null;
+  }
+
+  if (error == null) {
+    return null;
+  }
+
+  return stringifyFallback(error);
+};
+
+const getCause = (error: unknown): unknown => {
+  if (!isRecord(error)) {
+    return undefined;
+  }
+
+  return error.cause;
+};
+
+export const formatSqliteError = (error: unknown): string => {
+  const visited = new Set<unknown>();
+  const parts: string[] = [];
+  let current: unknown = error;
+
+  while (current !== undefined && current !== null && !visited.has(current)) {
+    visited.add(current);
+
+    const description = describeError(current);
+    if (description && !parts.includes(description)) {
+      parts.push(description);
+    }
+
+    current = getCause(current);
+  }
+
+  return parts.join('\nCaused by: ') || 'Unknown SQLite error.';
+};

package/src/shared/protocol.ts

@@ -0,0 +1,41 @@
+import type {
+  SqliteDatabaseInfo,
+  SqliteQueryParams,
+  SqliteQueryResult,
+  SqliteScriptResult,
+} from './types';
+
+export const PLUGIN_ID = '@rozenite/sqlite-plugin';
+
+export type SqliteEventMap = {
+  'sqlite:ready': { timestamp: number };
+  'sqlite:list-databases': { requestId: string };
+  'sqlite:list-databases:result': {
+    requestId: string;
+    databases: SqliteDatabaseInfo[];
+    error?: string;
+  };
+  'sqlite:query': {
+    requestId: string;
+    databaseId: string;
+    sql: string;
+    params?: SqliteQueryParams;
+  };
+  'sqlite:query:result': {
+    requestId: string;
+    databaseId: string;
+    result?: SqliteQueryResult;
+    error?: string;
+  };
+  'sqlite:execute-script': {
+    requestId: string;
+    databaseId: string;
+    sql: string;
+  };
+  'sqlite:execute-script:result': {
+    requestId: string;
+    databaseId: string;
+    result?: SqliteScriptResult;
+    error?: string;
+  };
+};