@symbiote-native/sqlite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# @symbiote-native/sqlite
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-sqlite`](https://github.com/expo/expo/tree/main/packages/expo-sqlite) usable from every
+adapter — `Database`, `Statement`, `Session` (transactions and changesets), a Bun-style SQL
+tagged-template helper, and a SQLite-backed key-value store. Built the same way as
+[`@symbiote-native/secure-store`](../secure-store): an `expo-modules-core`-based wrapper (see the
+`symbiote-expo-native-module` project skill for the full mechanism — why `expo-modules-core` is
+depended on directly and never the `expo` meta-package, why the upstream JS is hand-ported into
+`core/` rather than imported, and how autolinking picks up the native module).
+
+Every adapter — React, Vue, Svelte, Solid, Angular — ships its own idiomatic `<SQLiteProvider>` /
+`useSQLiteContext` equivalent (see "Provider / context" below), reachable from its own subpath.
+Each subpath re-exports the full `src/core/` barrel too, so importing from `@symbiote-native/sqlite/react`
+(etc.) is a strict superset of importing from the package root.
+
+expo-sqlite's native classes — `NativeDatabase`, `NativeStatement`, `NativeSession` — are **plain
+constructors** exposed as properties on the required native module (`new
+ExpoSQLite.NativeDatabase(...)`), unlike `@symbiote-native/audio`'s JSI-backed `SharedObject`
+subclasses. There is nothing to subclass here: this package's `SQLiteDatabase` /
+`SQLiteStatement` / `SQLiteSession` wrapper classes hold a native instance and forward to it,
+exactly like upstream's own.
+
+## Install
+
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --sqlite
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --sqlite
+```
+
+Either way: installs `@symbiote-native/sqlite` and wires the native autolinking automatically — see
+[`@symbiote-native/cli`](../cli).
+
+<details>
+<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+
+```bash
+npm install @symbiote-native/sqlite
+```
+
+`expo-sqlite` and `expo-modules-core` come along as regular dependencies, pinned to exact
+versions — never install either yourself, and never add the `expo` meta-package to your project
+(it bundles its own Metro/Babel pipeline, which conflicts with this project's own). `await-lock`
+is a real runtime dependency of the kv-store (see "Shape" below), not a native-only placeholder.
+
+### Required one-time step: native autolinking wiring
+
+Same one-time step as every other `expo-modules-core` package this project ships — see
+[`@symbiote-native/local-auth`'s README](../local-auth/README.md#required-one-time-step-native-autolinking-wiring)
+and the `symbiote-expo-native-module` project skill. Nothing package-specific: iOS autolinks the
+`Expo` pod automatically; Android's Gradle project + native-module map entry is generated by
+[`@symbiote-native/expo-modules-link`](../expo-modules-link)'s aggregator from this package's
+`native-link.json` on every install.
+
+expo-sqlite compiles its own vendored SQLite amalgamation from source per platform (it does not
+link the OS's system `libsqlite3`) — expect `pod install`/the first Android build touching this
+package to be noticeably heavier than a package that only links a prebuilt framework. That is
+expected, not a broken build.
+
+</details>
+
+## Shape
+
+```
+src/core/   native-database.ts / native-statement.ts / native-session.ts — the ambient
+            `declare class` surface expo-sqlite's native module exposes, ported type-only.
+            native-module.ts — resolves `ExpoSQLite` via expo-modules-core's requireNativeModule.
+            sqlite-database.ts / sqlite-statement.ts / sqlite-session.ts — the real wrapper
+            classes, holding a native instance and forwarding to it.
+            sqlite-tagged-query.ts — the `db.sql`...`` tagged-template helper.
+            storage.ts — SQLiteStorage, the SQLite-backed key-value store (its own subpath, see
+            below). query-utils.ts / path-utils.ts / param-utils.ts — framework/native-free
+            helpers (SQL-shape parsing, database-path joining, bind-param normalization).
+```
+
+`@symbiote-native/sqlite/kv-store` is a **separate subpath**, not re-exported from the package
+root — `SQLiteStorage`/`AsyncStorage`/`Storage` pull in `await-lock` and open their own database
+lazily on first use; an app that only wants `Database`/`Statement`/`sql` should not pay for that
+by importing it transitively.
+
+## Use it
+
+```ts
+import { openDatabaseAsync } from '@symbiote-native/sqlite';
+
+const db = await openDatabaseAsync('app.db');
+await db.execAsync('CREATE TABLE IF NOT EXISTS todos (id INTEGER PRIMARY KEY, title TEXT)');
+await db.runAsync('INSERT INTO todos (title) VALUES (?)', 'Buy milk');
+const todos = await db.getAllAsync<{ id: number; title: string }>('SELECT * FROM todos');
+```
+
+The SQL tagged-template helper (Bun-style, automatically parameterized):
+
+```ts
+const users = await db.sql<User>`SELECT * FROM users WHERE age > ${21}`;
+const rows = await db.sql`SELECT name, age FROM users`.values(); // [["Alice", 30], ...]
+const user = await db.sql<User>`SELECT * FROM users WHERE id = ${id}`.first();
+for await (const user of db.sql<User>`SELECT * FROM users`.each()) {
+  /* ... */
+}
+```
+
+Transactions:
+
+```ts
+await db.withTransactionAsync(async () => {
+  await db.runAsync('UPDATE accounts SET balance = balance - ? WHERE id = ?', 100, from);
+  await db.runAsync('UPDATE accounts SET balance = balance + ? WHERE id = ?', 100, to);
+}); // rolls back and re-throws if the task throws
+```
+
+The key-value store, from its own subpath:
+
+```ts
+import { AsyncStorage } from '@symbiote-native/sqlite/kv-store';
+
+await AsyncStorage.setItem('token', 'secret');
+const token = await AsyncStorage.getItem('token'); // string | null
+```
+
+### `onInit` — a deliberate deviation from upstream
+
+Upstream only exposes `onInit` as a `SQLiteProviderProps` field, called by its React
+`<SQLiteProvider>` after opening, before rendering children. Here `onInit` is exposed directly on
+`openDatabaseAsync`/`openDatabaseSync` instead — called once, right after the native handle opens,
+before the function returns:
+
+```ts
+const db = await openDatabaseAsync('app.db', {
+  onInit: async db => {
+    await db.execAsync('CREATE TABLE IF NOT EXISTS todos (id INTEGER PRIMARY KEY, title TEXT)');
+  },
+});
+```
+
+This gives an adapter with no view-tree context — a plain module-scope call, or Angular's
+`SqliteService` — a "run this once right after open" hook without needing a Provider to exist
+first. Every Provider above forwards its own `onInit` prop straight into `openDatabaseAsync`
+rather than calling it a second time. `openDatabaseSync` rejects (throws) if its `onInit` returns
+a `Promise`, rather than silently racing it.
+
+## Provider / context (per adapter)
+
+Each adapter's Provider opens the database once (closing and reopening if its config props
+change), renders nothing until it resolves, and hands the open `SQLiteDatabase` to descendants.
+On failure it calls `onError` if given, else the failure propagates through whatever error
+channel is idiomatic to that framework (a rethrow, an unhandled rejection, a resource-read
+throw — see each adapter's own source comment for the exact mechanism). `onInit` is forwarded to
+`openDatabaseAsync` (which already runs it — see below), not called a second time.
+
+**React** (`@symbiote-native/sqlite/react`):
+
+```tsx
+import { SQLiteProvider, useSQLiteContext } from '@symbiote-native/sqlite/react';
+
+<SQLiteProvider databaseName="app.db" onInit={migrate}>
+  <Main />
+</SQLiteProvider>;
+
+function Main() {
+  const db = useSQLiteContext();
+  // ...
+}
+```
+
+`useSuspense` is also supported (React's own primitive — `<Suspense>` shows its fallback instead
+of the Provider rendering `null`).
+
+**Vue** (`@symbiote-native/sqlite/vue`):
+
+```ts
+import { SQLiteProvider, useSQLiteContext } from '@symbiote-native/sqlite/vue';
+// <SQLiteProvider database-name="app.db"><Main /></SQLiteProvider> in a template
+// useSQLiteContext() inside a descendant's setup()
+```
+
+**Svelte** (`@symbiote-native/sqlite/svelte`):
+
+```svelte
+<script>
+  import { SQLiteProvider, useSQLiteContext } from '@symbiote-native/sqlite/svelte';
+</script>
+
+<SQLiteProvider databaseName="app.db">
+  <Main />
+</SQLiteProvider>
+```
+
+**Solid** (`@symbiote-native/sqlite/solid`):
+
+```tsx
+import { SQLiteProvider, useSQLiteContext } from '@symbiote-native/sqlite/solid';
+
+<SQLiteProvider databaseName="app.db">
+  <Main />
+</SQLiteProvider>;
+```
+
+**Angular** (`@symbiote-native/sqlite/angular`) — DI, not a template Provider (this project's
+established Angular idiom, see `@symbiote-native/navigation`'s own context service):
+
+```ts
+import { SqliteService, provideSqliteDatabase } from '@symbiote-native/sqlite/angular';
+
+// app config / module providers:
+provideSqliteDatabase({ databaseName: 'app.db', onInit: migrate });
+
+// any component/service:
+constructor(private readonly sqlite: SqliteService) {}
+// this.sqlite.database() — an Angular `resource()`-backed signal
+```
+
+None of the five ports upstream's `assetSource` option (see "Deliberately out of scope" below).
+React's `useSuspense` has no equivalent on the other four — Vue/Solid have their own native
+`<Suspense>`/`createResource` primitives an app can compose around the Provider itself if wanted;
+Svelte and Angular have none, and none of the four non-React Providers builds a second opt-in
+code path for it (a deliberate framework-idiom divergence, not a gap — each adapter's own source
+file says so at the top).
+
+## Error handling
+
+Native errors surface as a plain thrown `Error`/rejected `Promise` — upstream's ~12 native
+`Exception`/`GenericException` JS classes are not ported, same convention as every other
+module-only package this project ships. Trigger conditions, from the vendored native source
+(`.vendors/expo` @ `origin/sdk-57`, `packages/expo-sqlite/{android,ios}`):
+
+| Message contains                                   | Triggered by                                                                     |
+| --------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `Could not open database` / invalid path             | The native `sqlite3_open` call for the resolved path failed.                     |
+| `Database '<name>' not found`                        | Deleting a database that was never opened / does not exist on disk.              |
+| `Unable to delete database '<name>' that is currently open` | `deleteDatabaseAsync`/`Sync` on a database with a still-open connection. Close it first. |
+| `Unable to delete the database file for '<name>' database` | The file delete itself failed after the open-connection check passed.            |
+| `Access to closed resource`                          | Any call on a `SQLiteDatabase`/`SQLiteStatement`/`SQLiteSession` after `close*`/`finalize*`. |
+| `Invalid bind parameter`                              | A bind value's type SQLite's C binding layer cannot marshal.                     |
+| `Invalid arguments: ...`                              | A malformed call into the native layer (wrong argument shape).                   |
+| `ERR_INTERNAL_SQLITE_ERROR` (code) / raw SQLite message | SQLite itself rejected the statement — malformed SQL, constraint violation, etc. |
+| `Unsupported operations`                              | An operation the current build (e.g. a non-libSQL build calling `syncLibSQL()`) does not support. |
+
+## Deliberately out of scope
+
+- **The `assetSource` bundled-database-file option**
+  (`openDatabaseAsync(name, options, { assetSource })`) — needs `expo-asset`'s
+  `Asset.fromModule`, which this project deliberately does not depend on (same exclusion class as
+  `@symbiote-native/audio`'s `Asset`-instance form of `AudioSource` — see that package's README).
+  A file-copy-based alternative through [`@symbiote-native/file-system`](../file-system)'s
+  `File`/`Directory` API is possible but not wired here.
+- **The `expo-sqlite/plugin` config plugin** (libSQL / `sqlite-vec` extension bundling config) —
+  manual per-app native configuration, same convention as
+  [`@symbiote-native/notifications`'s README](../notifications/README.md) documenting manual
+  Firebase/entitlement setup. `bundledExtensions`/`loadExtensionAsync`/`loadExtensionSync` are
+  still exported and work against whatever extensions your app's own native build actually
+  bundles — they just require you to wire that bundling yourself.
+- **`importAssetDatabaseAsync`** — copies a bundled asset database into place at first launch;
+  layers on top of the `assetSource` exclusion above, so it is out of scope for the same reason.
+- **Web-only surfaces** (`ExpoSQLite.web.ts`, `WebStorage.ts`) — this project targets iOS +
+  Android only.
+- **expo-sqlite's own DevTools-browser-extension wiring** (`SQLiteDevToolsClient.ts`) — this
+  project has no equivalent of Expo's DevTools plugin.
+
+## Test it
+
+```bash
+pnpm vitest run packages/sqlite
+```
+
+The core tests fake the native module in place of `requireNativeModule`'s runtime resolution —
+`ExpoSQLite` only exists on a device, so a headless run would otherwise throw at import. Unlike
+this project's other `expo-modules-core` wrappers, the fake here (`src/core/native-fakes.ts`)
+wraps a **real [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) database** rather
+than a hand-rolled stub, so tests exercise genuine SQL behavior — real transactions, real
+constraint errors, real column shapes — not a guess at what SQLite would do. `better-sqlite3` is
+a devDependency only; it is never shipped to a consumer and is excluded from the published
+tarball alongside the fakes themselves.
+
+Real database-file persistence across app restarts, native extension loading, and libSQL sync can
+only be verified on a device or emulator.

package/build/angular/index.d.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export * from './sqlite.service';

package/build/angular/index.js

@@ -0,0 +1,2 @@
+export * from '../core/index.js';
+export * from './sqlite.service.js';

package/build/angular/sqlite.service.d.ts

@@ -0,0 +1,41 @@
+import { InjectionToken, type OnDestroy, type Provider } from '@angular/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 declare const SQLITE_CONFIG: InjectionToken<ISqliteConfig>;
+/**
+ * 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 declare function provideSqliteDatabase(config: ISqliteConfig): Provider;
+export declare class SqliteService implements OnDestroy {
+    private readonly config;
+    private readonly onErrorHandler;
+    private readonly dbResource;
+    /**
+     * 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: import("@angular/core").WritableSignal<import(".").SQLiteDatabase | undefined>;
+    /** The open failure, if any — reading `error()` itself never throws, only `database()` does. */
+    readonly error: import("@angular/core").Signal<Error | undefined>;
+    readonly isLoading: import("@angular/core").Signal<boolean>;
+    constructor();
+    /** Opens (or re-opens, for a new config) the app-wide database. */
+    open(config: ISqliteConfig): void;
+    ngOnDestroy(): void;
+}

package/build/angular/sqlite.service.js

@@ -0,0 +1,127 @@
+// 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.
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { Injectable, InjectionToken, effect, inject, resource, signal, } from '@angular/core';
+import { openDatabaseAsync } from '../core/index.js';
+export const SQLITE_CONFIG = new InjectionToken('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) {
+    return { provide: SQLITE_CONFIG, useValue: config };
+}
+let SqliteService = (() => {
+    let _classDecorators = [Injectable({ providedIn: 'root' })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var SqliteService = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            SqliteService = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        config = signal(undefined);
+        onErrorHandler = signal(undefined);
+        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)`).
+         */
+        database = this.dbResource.value;
+        /** The open failure, if any — reading `error()` itself never throws, only `database()` does. */
+        error = this.dbResource.error;
+        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) {
+            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() {
+            // `hasValue()` never throws, unlike reading `.value()` directly on an errored resource.
+            if (!this.dbResource.hasValue())
+                return;
+            void this.dbResource.value().closeAsync();
+        }
+    };
+    return SqliteService = _classThis;
+})();
+export { SqliteService };

package/build/core/index.d.ts

@@ -0,0 +1,10 @@
+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/build/core/index.js

@@ -0,0 +1,6 @@
+export { SQLiteDatabase, defaultDatabaseDirectory, bundledExtensions, openDatabaseAsync, openDatabaseSync, deserializeDatabaseAsync, deserializeDatabaseSync, deleteDatabaseAsync, deleteDatabaseSync, backupDatabaseAsync, backupDatabaseSync, addDatabaseChangeListener, } from './sqlite-database.js';
+export { SQLiteStatement } from './sqlite-statement.js';
+export { SQLiteSession } from './sqlite-session.js';
+export { SQLiteTaggedQuery } from './sqlite-tagged-query.js';
+export { parseSQLQuery } from './query-utils.js';
+export { createDatabasePath, basename } from './path-utils.js';

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

@@ -0,0 +1,65 @@
+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);
+    initAsync(): Promise<void>;
+    isInTransactionAsync(): Promise<boolean>;
+    closeAsync(): Promise<void>;
+    execAsync(source: string): Promise<void>;
+    serializeAsync(databaseName: string): Promise<Uint8Array>;
+    prepareAsync(nativeStatement: NativeStatement, source: string): Promise<NativeStatement>;
+    createSessionAsync(nativeSession: NativeSession, dbName: string): Promise<NativeSession>;
+    loadExtensionAsync(libPath: string, entryPoint?: string): Promise<void>;
+    initSync(): void;
+    isInTransactionSync(): boolean;
+    closeSync(): void;
+    execSync(source: string): void;
+    serializeSync(databaseName: string): Uint8Array;
+    prepareSync(nativeStatement: NativeStatement, source: string): NativeStatement;
+    createSessionSync(nativeSession: NativeSession, dbName: string): NativeSession;
+    loadExtensionSync(libPath: string, entryPoint?: string): void;
+    /** Only available when the native module was built against a libSQL-backed SQLite. */
+    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 declare function flattenOpenOptions(options: ISQLiteOpenOptions): IFlattenedOpenOptions;
+export {};

package/build/core/native-database.js

@@ -0,0 +1,13 @@
+/** Flattens `ISQLiteOpenOptions` into the shape the native module expects. */
+export function flattenOpenOptions(options) {
+    const { libSQLOptions, ...restOptions } = options;
+    const result = { ...restOptions };
+    if (libSQLOptions) {
+        Object.assign(result, {
+            libSQLUrl: libSQLOptions.url,
+            libSQLAuthToken: libSQLOptions.authToken,
+            libSQLRemoteOnly: libSQLOptions.remoteOnly,
+        });
+    }
+    return result;
+}

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

@@ -0,0 +1,25 @@
+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';
+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 declare const expoSQLite: INativeSQLiteModule;

package/build/core/native-module.js

@@ -0,0 +1,17 @@
+// 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 { NativeDatabase } from './native-database.js';
+import { NativeSession } from './native-session.js';
+import { NativeStatement } from './native-statement.js';
+const EXPO_SQLITE_MODULE_NAME = 'ExpoSQLite';
+export const expoSQLite = requireNativeModule(EXPO_SQLITE_MODULE_NAME);

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

@@ -0,0 +1,20 @@
+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 {
+    attachAsync(database: ISQLiteAnyDatabase, table: string | null): Promise<void>;
+    enableAsync(database: ISQLiteAnyDatabase, enabled: boolean): Promise<void>;
+    closeAsync(database: ISQLiteAnyDatabase): Promise<void>;
+    createChangesetAsync(database: ISQLiteAnyDatabase): Promise<INativeChangeset>;
+    createInvertedChangesetAsync(database: ISQLiteAnyDatabase): Promise<INativeChangeset>;
+    applyChangesetAsync(database: ISQLiteAnyDatabase, changeset: IChangeset | INativeChangeset): Promise<void>;
+    invertChangesetAsync(database: ISQLiteAnyDatabase, changeset: IChangeset | INativeChangeset): Promise<INativeChangeset>;
+    attachSync(database: ISQLiteAnyDatabase, table: string | null): void;
+    enableSync(database: ISQLiteAnyDatabase, enabled: boolean): void;
+    closeSync(database: ISQLiteAnyDatabase): void;
+    createChangesetSync(database: ISQLiteAnyDatabase): INativeChangeset;
+    createInvertedChangesetSync(database: ISQLiteAnyDatabase): INativeChangeset;
+    applyChangesetSync(database: ISQLiteAnyDatabase, changeset: IChangeset | INativeChangeset): void;
+    invertChangesetSync(database: ISQLiteAnyDatabase, changeset: IChangeset | INativeChangeset): INativeChangeset;
+}

package/build/core/native-session.js

@@ -0,0 +1 @@
+export {};