@symbiote-native/sqlite 0.1.0

package/src/angular/sqlite.service.ts

@@ -0,0 +1,114 @@
+// Angular's DI twin of upstream's `<SQLiteProvider>`/`useSQLiteContext`
+// (.vendors/expo@sdk-57 packages/expo-sqlite/src/hooks.tsx): ONE database instance app-wide by
+// default, opened once and read through DI instead of a React context.
+//
+// Declarative config goes through `provideSqliteDatabase()` — the
+// `providers: [{ provide: TOKEN, useValue }]` pattern this repo already uses for
+// gate-demand.ts's `provideGateDemand()` — rather than a scoping directive like navigation's
+// `symbioteNavigationScope`. That directive pattern deliberately mints a FRESH service instance
+// per usage (one per route); wrong here, since a database is a singleton to open once, not
+// something to re-scope per screen.
+//
+// Async state rides Angular's own `resource()` (adapters/angular/src/render/index.ts already
+// leans on it for TransferState) rather than a hand-rolled Promise/Observable — it is the
+// signals-first primitive this Angular adapter already uses for "async value + error + loading",
+// so `database`/`error`/`isLoading` come straight off it instead of a second, parallel state
+// machine. Its own contract already matches upstream's non-Suspense provider: a failure PARKS in
+// `error()` rather than throwing, exactly like `SQLiteProviderNonSuspense`'s `onError` branch
+// parks it in React state instead of re-throwing.
+//
+// Deliberately excluded, same as `../core`: `assetSource` (needs `expo-asset`, out of scope).
+// No Suspense equivalent — Angular has none.
+
+import {
+  Injectable,
+  InjectionToken,
+  effect,
+  inject,
+  resource,
+  signal,
+  type OnDestroy,
+  type Provider,
+} from '@angular/core';
+import { openDatabaseAsync } from '../core';
+import type { IOpenDatabaseOptions } from '../core';
+
+export interface ISqliteConfig {
+  /** The name of the database file to open. */
+  databaseName: string;
+  /** The directory the database file is located in. Defaults to `defaultDatabaseDirectory`. */
+  directory?: string;
+  /** Open options — `onInit` runs once, right after the native handle opens. */
+  options?: IOpenDatabaseOptions;
+  /**
+   * Called instead of the failure sitting quietly in `SqliteService#error` — mirrors upstream's
+   * `SQLiteProviderProps.onError`. Omit it to read the failure off `error()` instead.
+   */
+  onError?: (error: Error) => void;
+}
+
+export const SQLITE_CONFIG = new InjectionToken<ISqliteConfig>(
+  'symbiote.sqlite-config',
+);
+
+/**
+ * Declarative config for `SqliteService`'s app-wide database — pass to `bootstrapApplication`'s
+ * (or any environment injector's) `providers`, mirroring mounting `<SQLiteProvider>` once near
+ * the app root.
+ */
+export function provideSqliteDatabase(config: ISqliteConfig): Provider {
+  return { provide: SQLITE_CONFIG, useValue: config };
+}
+
+@Injectable({ providedIn: 'root' })
+export class SqliteService implements OnDestroy {
+  private readonly config = signal<ISqliteConfig | undefined>(undefined);
+  private readonly onErrorHandler = signal<
+    ((error: Error) => void) | undefined
+  >(undefined);
+
+  private readonly dbResource = resource({
+    params: () => this.config(),
+    loader: ({ params }) =>
+      openDatabaseAsync(params.databaseName, params.options, params.directory),
+  });
+
+  /**
+   * The resolved database, or `undefined` before `open()` has resolved. `resource()`'s own
+   * contract: reading this while `error()` is set RE-THROWS that error instead of returning —
+   * this IS the "propagates" half of upstream's `onError` contract for a caller that reads it
+   * directly (e.g. from a template's `@if (sqlite.database(); as db)`).
+   */
+  readonly database = this.dbResource.value;
+  /** The open failure, if any — reading `error()` itself never throws, only `database()` does. */
+  readonly error = this.dbResource.error;
+  readonly isLoading = this.dbResource.isLoading;
+
+  constructor() {
+    const injected = inject(SQLITE_CONFIG, { optional: true });
+    if (injected) this.open(injected);
+
+    effect(() => {
+      const raw = this.dbResource.error();
+      if (raw === undefined) return;
+      const error = raw instanceof Error ? raw : new Error(String(raw));
+      this.onErrorHandler()?.(error);
+    });
+  }
+
+  /** Opens (or re-opens, for a new config) the app-wide database. */
+  open(config: ISqliteConfig): void {
+    this.onErrorHandler.set(config.onError);
+    this.config.set(config);
+  }
+
+  // ponytail: closes only the CURRENTLY resolved handle, on the service's own teardown
+  // (providedIn: 'root' → root injector destruction). Re-opening with a different config does
+  // not close the previous handle first, unlike upstream's `getDatabaseAsync` memo — add that if
+  // an app actually calls `open()` more than once per lifetime.
+  ngOnDestroy(): void {
+    // `hasValue()` never throws, unlike reading `.value()` directly on an errored resource.
+    if (!this.dbResource.hasValue()) return;
+    void this.dbResource.value().closeAsync();
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,40 @@
+export {
+  SQLiteDatabase,
+  defaultDatabaseDirectory,
+  bundledExtensions,
+  openDatabaseAsync,
+  openDatabaseSync,
+  deserializeDatabaseAsync,
+  deserializeDatabaseSync,
+  deleteDatabaseAsync,
+  deleteDatabaseSync,
+  backupDatabaseAsync,
+  backupDatabaseSync,
+  addDatabaseChangeListener,
+} from './sqlite-database';
+export type {
+  ISQLiteOpenOptions,
+  IDatabaseChangeEvent,
+  IOnInitCallback,
+  IOpenDatabaseOptions,
+} from './sqlite-database';
+
+export { SQLiteStatement } from './sqlite-statement';
+export type {
+  ISQLiteBindParams,
+  ISQLiteBindValue,
+  ISQLiteExecuteAsyncResult,
+  ISQLiteExecuteSyncResult,
+  ISQLiteRunResult,
+  ISQLiteVariadicBindParams,
+} from './sqlite-statement';
+
+export { SQLiteSession } from './sqlite-session';
+export type { IChangeset } from './sqlite-session';
+
+export { SQLiteTaggedQuery } from './sqlite-tagged-query';
+
+export { parseSQLQuery } from './query-utils';
+export type { ISQLParsedInfo } from './query-utils';
+
+export { createDatabasePath, basename } from './path-utils';

package/src/core/native-database.ts

@@ -0,0 +1,118 @@
+// Ported from expo-sqlite's NativeDatabase.ts (.vendors/expo @ origin/sdk-57,
+// packages/expo-sqlite/src/NativeDatabase.ts), renamed with this repo's `I`-prefix convention.
+//
+// `NativeDatabase` is a PLAIN native class, not a `SharedObject` — expo-sqlite instantiates it
+// directly (`new ExpoSQLite.NativeDatabase(path, options)`), unlike expo-audio's JSI-backed
+// shared objects. See the package README for why that makes this port simpler than
+// `@symbiote-native/audio`'s.
+import type { NativeSession } from './native-session';
+import type { NativeStatement } from './native-statement';
+
+/** An instance of the native SQLite database handle. */
+export declare class NativeDatabase {
+  constructor(
+    databasePath: string,
+    options?: ISQLiteOpenOptions,
+    serializedData?: Uint8Array,
+  );
+
+  //#region Asynchronous API
+
+  public initAsync(): Promise<void>;
+  public isInTransactionAsync(): Promise<boolean>;
+  public closeAsync(): Promise<void>;
+  public execAsync(source: string): Promise<void>;
+  public serializeAsync(databaseName: string): Promise<Uint8Array>;
+  public prepareAsync(
+    nativeStatement: NativeStatement,
+    source: string,
+  ): Promise<NativeStatement>;
+  public createSessionAsync(
+    nativeSession: NativeSession,
+    dbName: string,
+  ): Promise<NativeSession>;
+  public loadExtensionAsync(
+    libPath: string,
+    entryPoint?: string,
+  ): Promise<void>;
+
+  //#endregion
+
+  //#region Synchronous API
+
+  public initSync(): void;
+  public isInTransactionSync(): boolean;
+  public closeSync(): void;
+  public execSync(source: string): void;
+  public serializeSync(databaseName: string): Uint8Array;
+  public prepareSync(
+    nativeStatement: NativeStatement,
+    source: string,
+  ): NativeStatement;
+  public createSessionSync(
+    nativeSession: NativeSession,
+    dbName: string,
+  ): NativeSession;
+  public loadExtensionSync(libPath: string, entryPoint?: string): void;
+
+  //#endregion
+
+  /** Only available when the native module was built against a libSQL-backed SQLite. */
+  public syncLibSQL(): Promise<void>;
+}
+
+/** Options for opening a database. */
+export type ISQLiteOpenOptions = {
+  /**
+   * Whether to call the [`sqlite3_update_hook()`](https://www.sqlite.org/c3ref/update_hook.html)
+   * function and enable `onDatabaseChange` events.
+   * @default false
+   */
+  enableChangeListener?: boolean;
+  /**
+   * Whether to create a new connection even if a connection with the same database name exists
+   * in cache.
+   * @default false
+   */
+  useNewConnection?: boolean;
+  /**
+   * Finalize unclosed statements automatically when the database is closed.
+   * @default true
+   * @hidden
+   */
+  finalizeUnusedStatementsBeforeClosing?: boolean;
+  /** Options for libSQL integration. */
+  libSQLOptions?: {
+    /** The URL of the libSQL server. */
+    url: string;
+    /** The auth token for the libSQL server. */
+    authToken: string;
+    /**
+     * Whether to use remote-only without syncing to a local database.
+     * @default false
+     */
+    remoteOnly?: boolean;
+  };
+};
+
+type IFlattenedOpenOptions = Omit<ISQLiteOpenOptions, 'libSQLOptions'> & {
+  libSQLUrl?: string;
+  libSQLAuthToken?: string;
+  libSQLRemoteOnly?: boolean;
+};
+
+/** Flattens `ISQLiteOpenOptions` into the shape the native module expects. */
+export function flattenOpenOptions(
+  options: ISQLiteOpenOptions,
+): IFlattenedOpenOptions {
+  const { libSQLOptions, ...restOptions } = options;
+  const result: IFlattenedOpenOptions = { ...restOptions };
+  if (libSQLOptions) {
+    Object.assign(result, {
+      libSQLUrl: libSQLOptions.url,
+      libSQLAuthToken: libSQLOptions.authToken,
+      libSQLRemoteOnly: libSQLOptions.remoteOnly,
+    });
+  }
+  return result;
+}

package/src/core/native-module.ts

@@ -0,0 +1,57 @@
+// Resolves expo-sqlite's native module by the same name its own `ExpoSQLite.ts` one-liner uses
+// (`.vendors/expo` @ origin/sdk-57, packages/expo-sqlite/src/ExpoSQLite.ts:
+// `requireNativeModule('ExpoSQLite')`) — through `expo-modules-core` directly, never the `expo`
+// meta-package (root CLAUDE.md's dependency-scope invariant). Verified against the Android
+// module's `Name("ExpoSQLite")` declaration
+// (packages/expo-sqlite/android/.../SQLiteModule.kt) — see this package's `native-link.json`.
+//
+// `NativeDatabase`/`NativeStatement`/`NativeSession` are plain constructors exposed as CLASS
+// PROPERTIES on the native module (`new ExpoSQLite.NativeDatabase(...)`), not `SharedObject`
+// subclasses — see native-database.ts's header for why that makes this simpler than
+// `@symbiote-native/audio`'s port.
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+
+import { NativeDatabase } from './native-database';
+import { NativeSession } from './native-session';
+import { NativeStatement } from './native-statement';
+import type { IDatabaseChangeEvent } from './types';
+
+const EXPO_SQLITE_MODULE_NAME = 'ExpoSQLite';
+
+export type INativeSQLiteModule = {
+  readonly NativeDatabase: typeof NativeDatabase;
+  readonly NativeStatement: typeof NativeStatement;
+  readonly NativeSession: typeof NativeSession;
+  /** The directory new databases are created in when no explicit directory is given. */
+  readonly defaultDatabaseDirectory: string;
+  /** Pre-bundled SQLite extensions (e.g. `sqlite-vec`), keyed by extension name. */
+  readonly bundledExtensions: Record<
+    string,
+    { libPath: string; entryPoint: string } | undefined
+  >;
+  ensureDatabasePathExistsAsync(databasePath: string): Promise<void>;
+  ensureDatabasePathExistsSync(databasePath: string): void;
+  deleteDatabaseAsync(databasePath: string): Promise<void>;
+  deleteDatabaseSync(databasePath: string): void;
+  backupDatabaseAsync(
+    destDatabase: NativeDatabase,
+    destDatabaseName: string,
+    sourceDatabase: NativeDatabase,
+    sourceDatabaseName: string,
+  ): Promise<void>;
+  backupDatabaseSync(
+    destDatabase: NativeDatabase,
+    destDatabaseName: string,
+    sourceDatabase: NativeDatabase,
+    sourceDatabaseName: string,
+  ): void;
+  addListener(
+    eventName: 'onDatabaseChange',
+    listener: (event: IDatabaseChangeEvent) => void,
+  ): EventSubscription;
+};
+
+export const expoSQLite = requireNativeModule<INativeSQLiteModule>(
+  EXPO_SQLITE_MODULE_NAME,
+);

package/src/core/native-session.ts

@@ -0,0 +1,64 @@
+// Ported from expo-sqlite's NativeSession.ts (.vendors/expo @ origin/sdk-57,
+// packages/expo-sqlite/src/NativeSession.ts), renamed with this repo's `I`-prefix convention.
+//
+// A plain native class wrapping SQLite's session extension
+// (https://www.sqlite.org/sessionintro.html), instantiated directly
+// (`new ExpoSQLite.NativeSession()`) and mutated in place by
+// `NativeDatabase.createSessionAsync`/`createSessionSync` — see `sqlite-database.ts`.
+import type { ISQLiteAnyDatabase } from './native-statement';
+
+/** A changeset produced by the session extension. */
+export type IChangeset = Uint8Array;
+export type INativeChangeset = ArrayBuffer;
+
+export declare class NativeSession {
+  //#region Asynchronous API
+
+  public attachAsync(
+    database: ISQLiteAnyDatabase,
+    table: string | null,
+  ): Promise<void>;
+  public enableAsync(
+    database: ISQLiteAnyDatabase,
+    enabled: boolean,
+  ): Promise<void>;
+  public closeAsync(database: ISQLiteAnyDatabase): Promise<void>;
+
+  public createChangesetAsync(
+    database: ISQLiteAnyDatabase,
+  ): Promise<INativeChangeset>;
+  public createInvertedChangesetAsync(
+    database: ISQLiteAnyDatabase,
+  ): Promise<INativeChangeset>;
+  public applyChangesetAsync(
+    database: ISQLiteAnyDatabase,
+    changeset: IChangeset | INativeChangeset,
+  ): Promise<void>;
+  public invertChangesetAsync(
+    database: ISQLiteAnyDatabase,
+    changeset: IChangeset | INativeChangeset,
+  ): Promise<INativeChangeset>;
+
+  //#endregion
+
+  //#region Synchronous API
+
+  public attachSync(database: ISQLiteAnyDatabase, table: string | null): void;
+  public enableSync(database: ISQLiteAnyDatabase, enabled: boolean): void;
+  public closeSync(database: ISQLiteAnyDatabase): void;
+
+  public createChangesetSync(database: ISQLiteAnyDatabase): INativeChangeset;
+  public createInvertedChangesetSync(
+    database: ISQLiteAnyDatabase,
+  ): INativeChangeset;
+  public applyChangesetSync(
+    database: ISQLiteAnyDatabase,
+    changeset: IChangeset | INativeChangeset,
+  ): void;
+  public invertChangesetSync(
+    database: ISQLiteAnyDatabase,
+    changeset: IChangeset | INativeChangeset,
+  ): INativeChangeset;
+
+  //#endregion
+}

package/src/core/native-statement.ts

@@ -0,0 +1,85 @@
+// Ported from expo-sqlite's NativeStatement.ts (.vendors/expo @ origin/sdk-57,
+// packages/expo-sqlite/src/NativeStatement.ts), renamed with this repo's `I`-prefix convention.
+//
+// A plain native class, instantiated directly (`new ExpoSQLite.NativeStatement()`) and then
+// mutated in place by `NativeDatabase.prepareAsync`/`prepareSync` — see `sqlite-database.ts`.
+
+/** A result returned by `SQLiteStatement.executeAsync()`/`executeSync()`. */
+export type ISQLiteRunResult = {
+  /**
+   * The last inserted row ID, from
+   * [`sqlite3_last_insert_rowid()`](https://www.sqlite.org/c3ref/last_insert_rowid.html).
+   */
+  lastInsertRowId: number;
+  /**
+   * The number of rows affected, from
+   * [`sqlite3_changes()`](https://www.sqlite.org/c3ref/changes.html).
+   */
+  changes: number;
+};
+
+/**
+ * Bind parameters to a prepared statement — a single array/variadic args for unnamed
+ * parameters (`?`), or a single object for named parameters (`:VVV`, `@VVV`, `$VVV`).
+ */
+export type ISQLiteBindValue =
+  string | number | null | boolean | ISQLiteBindBlobValue;
+export type ISQLiteBindParams =
+  Record<string, ISQLiteBindValue> | ISQLiteBindValue[];
+export type ISQLiteVariadicBindParams = ISQLiteBindValue[];
+export type ISQLiteBindBlobValue = Uint8Array | ArrayBuffer;
+
+export type ISQLiteBindPrimitiveParams = Record<
+  string,
+  Exclude<ISQLiteBindValue, ISQLiteBindBlobValue>
+>;
+export type ISQLiteBindBlobParams = Record<string, ISQLiteBindBlobValue>;
+export type ISQLiteColumnNames = string[];
+// `any`: native bridge payload — a prepared statement's row shape is only known to the caller of
+// `executeAsync<T>`/`executeSync<T>`.
+export type ISQLiteColumnValues = any[];
+// `any`: `NativeDatabase` and its `Transaction` subclass (sqlite-database.ts) both satisfy this,
+// kept untyped here (matching upstream) to avoid a circular import between the two native
+// declaration files.
+export type ISQLiteAnyDatabase = any;
+
+/** An instance of a prepared SQLite statement. */
+export declare class NativeStatement {
+  //#region Asynchronous API
+
+  public runAsync(
+    database: ISQLiteAnyDatabase,
+    bindParams: ISQLiteBindPrimitiveParams,
+    bindBlobParams: ISQLiteBindBlobParams,
+    shouldPassAsArray: boolean,
+  ): Promise<ISQLiteRunResult & { firstRowValues: ISQLiteColumnValues }>;
+  public stepAsync(
+    database: ISQLiteAnyDatabase,
+  ): Promise<ISQLiteColumnValues | null | undefined>;
+  public getAllAsync(
+    database: ISQLiteAnyDatabase,
+  ): Promise<ISQLiteColumnValues[]>;
+  public resetAsync(database: ISQLiteAnyDatabase): Promise<void>;
+  public getColumnNamesAsync(): Promise<ISQLiteColumnNames>;
+  public finalizeAsync(database: ISQLiteAnyDatabase): Promise<void>;
+
+  //#endregion
+
+  //#region Synchronous API
+
+  public runSync(
+    database: ISQLiteAnyDatabase,
+    bindParams: ISQLiteBindPrimitiveParams,
+    bindBlobParams: ISQLiteBindBlobParams,
+    shouldPassAsArray: boolean,
+  ): ISQLiteRunResult & { firstRowValues: ISQLiteColumnValues };
+  public stepSync(
+    database: ISQLiteAnyDatabase,
+  ): ISQLiteColumnValues | null | undefined;
+  public getAllSync(database: ISQLiteAnyDatabase): ISQLiteColumnValues[];
+  public resetSync(database: ISQLiteAnyDatabase): void;
+  public getColumnNamesSync(): string[];
+  public finalizeSync(database: ISQLiteAnyDatabase): void;
+
+  //#endregion
+}

package/src/core/param-utils.ts

@@ -0,0 +1,163 @@
+// Ported verbatim (logic unchanged) from expo-sqlite's paramUtils.ts (.vendors/expo @
+// origin/sdk-57, packages/expo-sqlite/src/paramUtils.ts), renamed with this repo's `I`-prefix
+// convention.
+import type {
+  ISQLiteBindBlobParams,
+  ISQLiteBindBlobValue,
+  ISQLiteBindPrimitiveParams,
+  ISQLiteBindValue,
+  ISQLiteColumnNames,
+  ISQLiteColumnValues,
+} from './native-statement';
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Normalizes bind params into `[primitiveParams, blobParams, shouldPassAsArray]` for the
+ * native module. `params` is untyped because the public overloads
+ * (`ISQLiteBindParams` vs. variadic `ISQLiteVariadicBindParams`) already constrain what a
+ * type-checked caller can pass here — this only has to survive a caller that bypasses them.
+ * @hidden
+ */
+export function normalizeParams(
+  ...params: unknown[]
+): [ISQLiteBindPrimitiveParams, ISQLiteBindBlobParams, boolean] {
+  const rawParams: unknown = params.length > 1 ? params : params[0];
+  let bindParams: unknown = rawParams ?? [];
+
+  if (
+    typeof bindParams !== 'object' ||
+    bindParams === null ||
+    bindParams instanceof ArrayBuffer ||
+    ArrayBuffer.isView(bindParams)
+  ) {
+    bindParams = [bindParams];
+  }
+
+  const shouldPassAsArray = Array.isArray(bindParams);
+  const entries: [string, unknown][] = Array.isArray(bindParams)
+    ? bindParams.map((value, index): [string, unknown] => [
+        String(index),
+        value,
+      ])
+    : isPlainRecord(bindParams)
+      ? Object.entries(bindParams)
+      : [];
+
+  const primitiveParams: ISQLiteBindPrimitiveParams = {};
+  const blobParams: ISQLiteBindBlobParams = {};
+  for (const [key, value] of entries) {
+    if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+      blobParams[key] = value;
+    } else if (typeof value === 'boolean') {
+      primitiveParams[key] = value ? 1 : 0;
+    } else if (
+      value === null ||
+      typeof value === 'string' ||
+      typeof value === 'number'
+    ) {
+      primitiveParams[key] = value;
+    } else {
+      // Not a recognized ISQLiteBindValue at this point (undefined, an object, an array, a
+      // function...) — keep it as-is, matching upstream's `value ?? null`, which only guards
+      // null/undefined and otherwise passes the value through untouched. Binding an invalid
+      // value is the native bridge's problem at bind time; this function only reshapes params.
+      // I/O edge: `value` is genuinely unknown here — a caller that bypassed the public
+      // `ISQLiteBindParams` overloads is the only way to reach this branch.
+      primitiveParams[key] = (value ?? null) as Exclude<
+        ISQLiteBindValue,
+        ISQLiteBindBlobValue
+      >;
+    }
+  }
+
+  return [primitiveParams, blobParams, shouldPassAsArray];
+}
+
+/**
+ * Composes `columnNames` and `columnValues` into a row object.
+ * @hidden
+ */
+export function composeRow<T>(
+  columnNames: ISQLiteColumnNames,
+  columnValues: ISQLiteColumnValues,
+): T {
+  const row: Record<string, unknown> = {};
+  if (columnNames.length !== columnValues.length) {
+    throw new Error(
+      `Column names and values count mismatch. Names: ${columnNames.length}, Values: ${columnValues.length}`,
+    );
+  }
+  for (let i = 0; i < columnNames.length; i++) {
+    const columnName = columnNames[i];
+    if (columnName != null) {
+      row[columnName] = columnValues[i];
+    }
+  }
+  // I/O edge: T is the caller-specified row shape (SQLiteStatement.executeAsync<T>, etc.) — the
+  // native bridge has no way to describe it, so it is asserted here, at the narrowest point
+  // native data enters the type system.
+  return row as T;
+}
+
+/**
+ * Composes `columnNames` and `columnValuesList` into an array of row objects.
+ * @hidden
+ */
+export function composeRows<T>(
+  columnNames: ISQLiteColumnNames,
+  columnValuesList: ISQLiteColumnValues[],
+): T[] {
+  const firstRow = columnValuesList[0];
+  if (firstRow == null) {
+    return [];
+  }
+  if (columnNames.length !== firstRow.length) {
+    // Only the first row is checked — SQLite returns the same column count for every row. A
+    // shorter LATER row is not an error case (unlike composeRow's own check, which this
+    // deliberately does NOT delegate to) — a missing trailing value just composes as
+    // `undefined`, matching upstream's inline (non-composeRow) row construction here.
+    throw new Error(
+      `Column names and values count mismatch. Names: ${columnNames.length}, Values: ${firstRow.length}`,
+    );
+  }
+  const results: T[] = [];
+  for (const columnValues of columnValuesList) {
+    const row: Record<string, unknown> = {};
+    for (let i = 0; i < columnNames.length; i++) {
+      const columnName = columnNames[i];
+      if (columnName != null) {
+        row[columnName] = columnValues[i];
+      }
+    }
+    // I/O edge, same as composeRow above.
+    results.push(row as T);
+  }
+  return results;
+}
+
+/**
+ * Normalizes the index for `SQLiteStorage.getKeyByIndexAsync`/`getKeyByIndexSync`. `index` is
+ * `unknown` (upstream types it `any`) because the function coerces defensively via `Number()` —
+ * a caller reaching this from untyped host data (e.g. a `web` `Storage` polyfill) may hand it
+ * anything.
+ * @returns The normalized index, or `null` when out of bounds.
+ * @hidden
+ */
+export function normalizeStorageIndex(index: unknown): number | null {
+  const value = Math.floor(Number(index));
+
+  if (Object.is(value, -0)) {
+    return 0;
+  }
+  if (!Number.isSafeInteger(value)) {
+    // Chromium uses a zero index when the index is out of bounds.
+    return 0;
+  }
+  if (value < 0) {
+    return null;
+  }
+  return value;
+}

package/src/core/path-utils.ts

@@ -0,0 +1,38 @@
+// Ported verbatim (logic unchanged) from expo-sqlite's pathUtils.ts (.vendors/expo @
+// origin/sdk-57, packages/expo-sqlite/src/pathUtils.ts).
+import { expoSQLite } from './native-module';
+
+function resolveDbDirectory(directory: string | undefined): string {
+  const resolvedDirectory = directory ?? expoSQLite.defaultDatabaseDirectory;
+  if (resolvedDirectory == null) {
+    throw new Error(
+      'Both provided directory and defaultDatabaseDirectory are null.',
+    );
+  }
+  return resolvedDirectory;
+}
+
+/**
+ * Creates a normalized database path by combining the directory and database name — no
+ * trailing slash on the directory, no leading slash on the name, so the join never doubles up.
+ */
+export function createDatabasePath(
+  databaseName: string,
+  directory?: string,
+): string {
+  if (databaseName === ':memory:') return databaseName;
+  const resolvedDirectory = resolveDbDirectory(directory);
+
+  function removeTrailingSlash(path: string): string {
+    return path.replace(/\/*$/, '');
+  }
+  function removeLeadingSlash(path: string): string {
+    return path.replace(/^\/+/, '');
+  }
+
+  return `${removeTrailingSlash(resolvedDirectory)}/${removeLeadingSlash(databaseName)}`;
+}
+
+export function basename(path: string): string {
+  return path.substring(path.lastIndexOf('/') + 1);
+}