@symbiote-native/sqlite 0.1.0

package/build/core/native-statement.d.ts

@@ -0,0 +1,45 @@
+/** 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[];
+export type ISQLiteColumnValues = any[];
+export type ISQLiteAnyDatabase = any;
+/** An instance of a prepared SQLite statement. */
+export declare class NativeStatement {
+    runAsync(database: ISQLiteAnyDatabase, bindParams: ISQLiteBindPrimitiveParams, bindBlobParams: ISQLiteBindBlobParams, shouldPassAsArray: boolean): Promise<ISQLiteRunResult & {
+        firstRowValues: ISQLiteColumnValues;
+    }>;
+    stepAsync(database: ISQLiteAnyDatabase): Promise<ISQLiteColumnValues | null | undefined>;
+    getAllAsync(database: ISQLiteAnyDatabase): Promise<ISQLiteColumnValues[]>;
+    resetAsync(database: ISQLiteAnyDatabase): Promise<void>;
+    getColumnNamesAsync(): Promise<ISQLiteColumnNames>;
+    finalizeAsync(database: ISQLiteAnyDatabase): Promise<void>;
+    runSync(database: ISQLiteAnyDatabase, bindParams: ISQLiteBindPrimitiveParams, bindBlobParams: ISQLiteBindBlobParams, shouldPassAsArray: boolean): ISQLiteRunResult & {
+        firstRowValues: ISQLiteColumnValues;
+    };
+    stepSync(database: ISQLiteAnyDatabase): ISQLiteColumnValues | null | undefined;
+    getAllSync(database: ISQLiteAnyDatabase): ISQLiteColumnValues[];
+    resetSync(database: ISQLiteAnyDatabase): void;
+    getColumnNamesSync(): string[];
+    finalizeSync(database: ISQLiteAnyDatabase): void;
+}

package/build/core/native-statement.js

@@ -0,0 +1,6 @@
+// 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`.
+export {};

package/build/core/param-utils.d.ts

@@ -0,0 +1,28 @@
+import type { ISQLiteBindBlobParams, ISQLiteBindPrimitiveParams, ISQLiteColumnNames, ISQLiteColumnValues } from './native-statement';
+/**
+ * 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 declare function normalizeParams(...params: unknown[]): [ISQLiteBindPrimitiveParams, ISQLiteBindBlobParams, boolean];
+/**
+ * Composes `columnNames` and `columnValues` into a row object.
+ * @hidden
+ */
+export declare function composeRow<T>(columnNames: ISQLiteColumnNames, columnValues: ISQLiteColumnValues): T;
+/**
+ * Composes `columnNames` and `columnValuesList` into an array of row objects.
+ * @hidden
+ */
+export declare function composeRows<T>(columnNames: ISQLiteColumnNames, columnValuesList: ISQLiteColumnValues[]): T[];
+/**
+ * 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 declare function normalizeStorageIndex(index: unknown): number | null;

package/build/core/param-utils.js

@@ -0,0 +1,126 @@
+function isPlainRecord(value) {
+    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) {
+    const rawParams = params.length > 1 ? params : params[0];
+    let bindParams = rawParams ?? [];
+    if (typeof bindParams !== 'object' ||
+        bindParams === null ||
+        bindParams instanceof ArrayBuffer ||
+        ArrayBuffer.isView(bindParams)) {
+        bindParams = [bindParams];
+    }
+    const shouldPassAsArray = Array.isArray(bindParams);
+    const entries = Array.isArray(bindParams)
+        ? bindParams.map((value, index) => [
+            String(index),
+            value,
+        ])
+        : isPlainRecord(bindParams)
+            ? Object.entries(bindParams)
+            : [];
+    const primitiveParams = {};
+    const blobParams = {};
+    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);
+        }
+    }
+    return [primitiveParams, blobParams, shouldPassAsArray];
+}
+/**
+ * Composes `columnNames` and `columnValues` into a row object.
+ * @hidden
+ */
+export function composeRow(columnNames, columnValues) {
+    const row = {};
+    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;
+}
+/**
+ * Composes `columnNames` and `columnValuesList` into an array of row objects.
+ * @hidden
+ */
+export function composeRows(columnNames, columnValuesList) {
+    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 = [];
+    for (const columnValues of columnValuesList) {
+        const row = {};
+        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);
+    }
+    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) {
+    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/build/core/path-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function createDatabasePath(databaseName: string, directory?: string): string;
+export declare function basename(path: string): string;

package/build/core/path-utils.js

@@ -0,0 +1,29 @@
+// 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.js';
+function resolveDbDirectory(directory) {
+    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, directory) {
+    if (databaseName === ':memory:')
+        return databaseName;
+    const resolvedDirectory = resolveDbDirectory(directory);
+    function removeTrailingSlash(path) {
+        return path.replace(/\/*$/, '');
+    }
+    function removeLeadingSlash(path) {
+        return path.replace(/^\/+/, '');
+    }
+    return `${removeTrailingSlash(resolvedDirectory)}/${removeLeadingSlash(databaseName)}`;
+}
+export function basename(path) {
+    return path.substring(path.lastIndexOf('/') + 1);
+}

package/build/core/query-utils.d.ts

@@ -0,0 +1,17 @@
+/** Information about a parsed SQL query. */
+export type ISQLParsedInfo = {
+    canReturnRows: boolean;
+};
+/**
+ * Parses a SQL query to determine whether it can return rows, using a priority-based approach:
+ * `RETURNING` always returns rows; a bare mutation keyword never does; a query keyword does;
+ * anything else does not.
+ *
+ * @example
+ * ```ts
+ * parseSQLQuery('SELECT * FROM users') // { canReturnRows: true }
+ * parseSQLQuery('INSERT INTO users VALUES (1)') // { canReturnRows: false }
+ * parseSQLQuery('INSERT INTO users VALUES (1) RETURNING *') // { canReturnRows: true }
+ * ```
+ */
+export declare function parseSQLQuery(query: string): ISQLParsedInfo;

package/build/core/query-utils.js

@@ -0,0 +1,37 @@
+// Ported verbatim (logic unchanged) from expo-sqlite's queryUtils.ts (.vendors/expo @
+// origin/sdk-57, packages/expo-sqlite/src/queryUtils.ts), renamed with this repo's `I`-prefix
+// convention. A reimplementation of Bun's SQLite query parser (credited upstream).
+const SINGLE_QUOTED_STRING = /'(?:[^']|'')*'/g;
+const DOUBLE_QUOTED_STRING = /"(?:[^"]|"")*"/g;
+const RETURNING_KEYWORD = /\bRETURNING\b/i;
+const MUTATION_KEYWORDS = /\b(INSERT|UPDATE|DELETE|CREATE|ALTER|DROP)\b/i;
+const QUERY_KEYWORDS = /\b(SELECT|PRAGMA|WITH|EXPLAIN)\b/i;
+/**
+ * Parses a SQL query to determine whether it can return rows, using a priority-based approach:
+ * `RETURNING` always returns rows; a bare mutation keyword never does; a query keyword does;
+ * anything else does not.
+ *
+ * @example
+ * ```ts
+ * parseSQLQuery('SELECT * FROM users') // { canReturnRows: true }
+ * parseSQLQuery('INSERT INTO users VALUES (1)') // { canReturnRows: false }
+ * parseSQLQuery('INSERT INTO users VALUES (1) RETURNING *') // { canReturnRows: true }
+ * ```
+ */
+export function parseSQLQuery(query) {
+    // SQLite doubles quotes to escape them ('don''t', "test""quote") — strip quoted strings first
+    // so a keyword INSIDE a string literal can't produce a false positive.
+    const cleaned = query
+        .replace(SINGLE_QUOTED_STRING, "''")
+        .replace(DOUBLE_QUOTED_STRING, '""');
+    if (RETURNING_KEYWORD.test(cleaned)) {
+        return { canReturnRows: true };
+    }
+    if (MUTATION_KEYWORDS.test(cleaned)) {
+        return { canReturnRows: false };
+    }
+    if (QUERY_KEYWORDS.test(cleaned)) {
+        return { canReturnRows: true };
+    }
+    return { canReturnRows: false };
+}

package/build/core/sqlite-database.d.ts

@@ -0,0 +1,246 @@
+import type { EventSubscription } from 'expo-modules-core';
+import { NativeDatabase } from './native-database';
+import type { ISQLiteOpenOptions } from './native-database';
+import { SQLiteSession } from './sqlite-session';
+import { SQLiteStatement } from './sqlite-statement';
+import type { ISQLiteBindParams, ISQLiteRunResult, ISQLiteVariadicBindParams } from './sqlite-statement';
+import { SQLiteTaggedQuery } from './sqlite-tagged-query';
+import type { IDatabaseChangeEvent, IOpenDatabaseOptions } from './types';
+export type { ISQLiteOpenOptions } from './native-database';
+export type { IDatabaseChangeEvent, IOnInitCallback, IOpenDatabaseOptions, } from './types';
+/** A SQLite database. */
+export declare class SQLiteDatabase {
+    readonly databasePath: string;
+    readonly options: ISQLiteOpenOptions;
+    readonly nativeDatabase: NativeDatabase;
+    constructor(databasePath: string, options: ISQLiteOpenOptions, nativeDatabase: NativeDatabase);
+    /** Whether the database is currently in a transaction. */
+    isInTransactionAsync(): Promise<boolean>;
+    /** Closes the database. */
+    closeAsync(): Promise<void>;
+    /**
+     * Executes all SQL queries in the supplied string.
+     * > **Note:** The queries are not escaped for you — be careful when constructing them.
+     */
+    execAsync(source: string): Promise<void>;
+    /**
+     * [Serializes the database](https://sqlite.org/c3ref/serialize.html) as a `Uint8Array`.
+     * @param databaseName The attached database name. Defaults to `main`.
+     */
+    serializeAsync(databaseName?: string): Promise<Uint8Array>;
+    /**
+     * Creates a [prepared statement](https://www.sqlite.org/c3ref/prepare.html) from `source`.
+     */
+    prepareAsync(source: string): Promise<SQLiteStatement>;
+    /**
+     * Creates a new session for the database.
+     * @see [`sqlite3session_create`](https://www.sqlite.org/session/sqlite3session_create.html)
+     * @param dbName The database name to create a session for. Defaults to `main`.
+     */
+    createSessionAsync(dbName?: string): Promise<SQLiteSession>;
+    /**
+     * Loads a SQLite extension.
+     * @param libPath The path to the extension library file.
+     * @param entryPoint The extension's entry point. Inferred by
+     *   [`sqlite3_load_extension`](https://www.sqlite.org/c3ref/load_extension.html) when omitted.
+     */
+    loadExtensionAsync(libPath: string, entryPoint?: string): Promise<void>;
+    /**
+     * Executes a transaction, committing/rolling back automatically based on `task`'s result.
+     *
+     * > **Note:** Not exclusive — other async queries can interleave, so the order of execution
+     * > relative to a query issued outside the transaction is not guaranteed. Use
+     * > `withExclusiveTransactionAsync` when that matters.
+     */
+    withTransactionAsync(task: () => Promise<void>): Promise<void>;
+    /**
+     * Executes a transaction, committing/rolling back automatically based on `task`'s result.
+     * The transaction may be exclusive: once it becomes a write transaction, other async write
+     * queries abort with a `database is locked` error.
+     *
+     * > **Note:** Not supported on web.
+     *
+     * @param task Any queries inside it must run on the `txn` object it receives — a private
+     *   `SQLiteDatabase` subclass bound to the exclusive connection, typed here as the base class
+     *   since the subclass is an implementation detail, not a public export.
+     */
+    withExclusiveTransactionAsync(task: (txn: SQLiteDatabase) => Promise<void>): Promise<void>;
+    /** Whether the database is currently in a transaction. */
+    isInTransactionSync(): boolean;
+    /** Closes the database. */
+    closeSync(): void;
+    /**
+     * Executes all SQL queries in the supplied string.
+     * > **Note:** The queries are not escaped for you. Running heavy tasks with this function can
+     * > block the JavaScript thread.
+     */
+    execSync(source: string): void;
+    /**
+     * [Serializes the database](https://sqlite.org/c3ref/serialize.html) as a `Uint8Array`.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    serializeSync(databaseName?: string): Uint8Array;
+    /**
+     * Creates a [prepared statement](https://www.sqlite.org/c3ref/prepare.html) from `source`.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    prepareSync(source: string): SQLiteStatement;
+    /**
+     * Creates a new session for the database.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     * @see [`sqlite3session_create`](https://www.sqlite.org/session/sqlite3session_create.html)
+     */
+    createSessionSync(dbName?: string): SQLiteSession;
+    /**
+     * Loads a SQLite extension.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    loadExtensionSync(libPath: string, entryPoint?: string): void;
+    /**
+     * Executes a transaction, committing/rolling back automatically based on `task`'s result.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    withTransactionSync(task: () => void): void;
+    /**
+     * Executes SQL queries using tagged template literals (Bun-style), automatically parameterized
+     * against SQL injection. Directly awaitable (returns rows/`ISQLiteRunResult`); use `.values()`,
+     * `.first()`, `.each()`, or the `*Sync` variants for other shapes.
+     *
+     * @example
+     * ```ts
+     * const users = await db.sql<User>`SELECT * FROM users WHERE age > ${21}`;
+     * const rows = await db.sql`SELECT name, age FROM users`.values();
+     * const user = await db.sql<User>`SELECT * FROM users WHERE id = ${userId}`.first();
+     * ```
+     */
+    sql: <T = unknown>(strings: TemplateStringsArray, ...values: unknown[]) => SQLiteTaggedQuery<T>;
+    /**
+     * A convenience wrapper around `prepareAsync()`, `SQLiteStatement.executeAsync()`, and
+     * `SQLiteStatement.finalizeAsync()`.
+     */
+    runAsync(source: string, params: ISQLiteBindParams): Promise<ISQLiteRunResult>;
+    /** @hidden */
+    runAsync(source: string, ...params: ISQLiteVariadicBindParams): Promise<ISQLiteRunResult>;
+    /**
+     * A convenience wrapper around `prepareAsync()`, `SQLiteStatement.executeAsync()`,
+     * `ISQLiteExecuteAsyncResult.getFirstAsync()`, and `SQLiteStatement.finalizeAsync()`.
+     */
+    getFirstAsync<T>(source: string, params: ISQLiteBindParams): Promise<T | null>;
+    /** @hidden */
+    getFirstAsync<T>(source: string, ...params: ISQLiteVariadicBindParams): Promise<T | null>;
+    /**
+     * A convenience wrapper around `prepareAsync()`, `SQLiteStatement.executeAsync()`, the
+     * `ISQLiteExecuteAsyncResult` async iterator, and `SQLiteStatement.finalizeAsync()`.
+     */
+    getEachAsync<T>(source: string, params: ISQLiteBindParams): AsyncIterableIterator<T>;
+    /** @hidden */
+    getEachAsync<T>(source: string, ...params: ISQLiteVariadicBindParams): AsyncIterableIterator<T>;
+    /**
+     * A convenience wrapper around `prepareAsync()`, `SQLiteStatement.executeAsync()`,
+     * `ISQLiteExecuteAsyncResult.getAllAsync()`, and `SQLiteStatement.finalizeAsync()`.
+     */
+    getAllAsync<T>(source: string, params: ISQLiteBindParams): Promise<T[]>;
+    /** @hidden */
+    getAllAsync<T>(source: string, ...params: ISQLiteVariadicBindParams): Promise<T[]>;
+    /**
+     * A convenience wrapper around `prepareSync()`, `SQLiteStatement.executeSync()`, and
+     * `SQLiteStatement.finalizeSync()`.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    runSync(source: string, params: ISQLiteBindParams): ISQLiteRunResult;
+    /** @hidden */
+    runSync(source: string, ...params: ISQLiteVariadicBindParams): ISQLiteRunResult;
+    /**
+     * A convenience wrapper around `prepareSync()`, `SQLiteStatement.executeSync()`,
+     * `ISQLiteExecuteSyncResult.getFirstSync()`, and `SQLiteStatement.finalizeSync()`.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    getFirstSync<T>(source: string, params: ISQLiteBindParams): T | null;
+    /** @hidden */
+    getFirstSync<T>(source: string, ...params: ISQLiteVariadicBindParams): T | null;
+    /**
+     * A convenience wrapper around `prepareSync()`, `SQLiteStatement.executeSync()`, the
+     * `ISQLiteExecuteSyncResult` iterator, and `SQLiteStatement.finalizeSync()`.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    getEachSync<T>(source: string, params: ISQLiteBindParams): IterableIterator<T>;
+    /** @hidden */
+    getEachSync<T>(source: string, ...params: ISQLiteVariadicBindParams): IterableIterator<T>;
+    /**
+     * A convenience wrapper around `prepareSync()`, `SQLiteStatement.executeSync()`,
+     * `ISQLiteExecuteSyncResult.getAllSync()`, and `SQLiteStatement.finalizeSync()`.
+     * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+     */
+    getAllSync<T>(source: string, params: ISQLiteBindParams): T[];
+    /** @hidden */
+    getAllSync<T>(source: string, ...params: ISQLiteVariadicBindParams): T[];
+    /** Synchronizes the local database with the remote libSQL server (libSQL integration only). */
+    syncLibSQL(): Promise<void>;
+}
+/** The default directory new databases are created in. */
+export declare const defaultDatabaseDirectory: string;
+/**
+ * Pre-bundled SQLite extensions. Bundling one (e.g. `sqlite-vec`) is a manual native-config
+ * step this package does not automate — see the README.
+ */
+export declare const bundledExtensions: Record<string, {
+    libPath: string;
+    entryPoint: string;
+} | undefined>;
+/**
+ * Opens a database.
+ * @param databaseName The database file name to open.
+ * @param options Open options — see `IOpenDatabaseOptions` for the `onInit` deviation from
+ *   upstream (documented in the README).
+ * @param directory The directory the database file is located in. Defaults to
+ *   `defaultDatabaseDirectory`.
+ */
+export declare function openDatabaseAsync(databaseName: string, options?: IOpenDatabaseOptions, directory?: string): Promise<SQLiteDatabase>;
+/**
+ * Opens a database.
+ * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+ */
+export declare function openDatabaseSync(databaseName: string, options?: IOpenDatabaseOptions, directory?: string): SQLiteDatabase;
+/**
+ * Given `Uint8Array` data, [deserializes it to an in-memory database](https://sqlite.org/c3ref/deserialize.html).
+ * @param serializedData The binary array from `SQLiteDatabase.serializeAsync()`.
+ */
+export declare function deserializeDatabaseAsync(serializedData: Uint8Array, options?: ISQLiteOpenOptions): Promise<SQLiteDatabase>;
+/**
+ * Given `Uint8Array` data, [deserializes it to an in-memory database](https://sqlite.org/c3ref/deserialize.html).
+ * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+ */
+export declare function deserializeDatabaseSync(serializedData: Uint8Array, options?: ISQLiteOpenOptions): SQLiteDatabase;
+/** Deletes a database file. */
+export declare function deleteDatabaseAsync(databaseName: string, directory?: string): Promise<void>;
+/**
+ * Deletes a database file.
+ * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+ */
+export declare function deleteDatabaseSync(databaseName: string, directory?: string): void;
+/**
+ * Backs up a database to another database.
+ * @see https://www.sqlite.org/c3ref/backup_finish.html
+ */
+export declare function backupDatabaseAsync(options: {
+    sourceDatabase: SQLiteDatabase;
+    sourceDatabaseName?: string;
+    destDatabase: SQLiteDatabase;
+    destDatabaseName?: string;
+}): Promise<void>;
+/**
+ * Backs up a database to another database.
+ * > **Note:** Running heavy tasks with this function can block the JavaScript thread.
+ * @see https://www.sqlite.org/c3ref/backup_finish.html
+ */
+export declare function backupDatabaseSync(options: {
+    sourceDatabase: SQLiteDatabase;
+    sourceDatabaseName?: string;
+    destDatabase: SQLiteDatabase;
+    destDatabaseName?: string;
+}): void;
+/**
+ * Adds a listener for database changes.
+ * > **Note:** requires `enableChangeListener: true` in `ISQLiteOpenOptions` when opening.
+ */
+export declare function addDatabaseChangeListener(listener: (event: IDatabaseChangeEvent) => void): EventSubscription;