@octane-xplat/sqlite 0.0.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+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

@@ -1,3 +1,61 @@
-# @octane-xplat/sqlite
+# `@octane-xplat/sqlite`
 
-Version 0.0.1 is a reservation stub so the automated release can publish this package name. It has no supported API. Use a later release for the implementation.
+```sh
+pnpm add @octane-xplat/sqlite
+```
+
+Cross-target SQLite persistence for Octane xplat apps:
+`@nativescript-community/sqlite` on iOS/Android, a `sqlite-wasm` worker
+with OPFS persistence on web, system `libsqlite3` via C-function interop
+on the macOS AppKit host, and an explicit `supported: false` on Windows.
+
+```ts
+import { openDatabase, supported } from '@octane-xplat/sqlite'
+
+const db = await openDatabase('trips.db') // { threading?: boolean } option, native only
+await db.execute('CREATE TABLE IF NOT EXISTS items(name TEXT)')
+await db.execute('INSERT INTO items VALUES (?)', ['Passport'])
+const rows = await db.selectArray('SELECT name FROM items')
+await db.close()
+```
+
+The `SqliteDb` surface: `execute`, `selectArray`, `getArray`, `each`
+(row callback), `getUserVersion`/`setUserVersion` for migrations, `close`.
+Params are `null | number | bigint | string | ArrayBuffer | Uint8Array`.
+`db.isOpen` reports liveness; `db.persistent` reports whether storage
+survives reloads — web only persists through OPFS, which needs a Worker
+and on some browsers cross-origin isolation, so check the flag before
+treating web data as durable. `deleteDatabase` removes a named database.
+Branch on `supported` where a target has no backend.
+
+```ts
+import { deleteDatabase } from '@octane-xplat/sqlite'
+
+if (supported) {
+	const database = await openDatabase('preview.db')
+	try {
+		console.log(database.isOpen, database.persistent)
+		await database.execute('CREATE TABLE IF NOT EXISTS items(name TEXT)')
+		const first = await database.getArray('SELECT name FROM items LIMIT 1')
+		await database.each(
+			'SELECT name FROM items',
+			[],
+			(error, row) => {
+				if (!error) console.log(row.name)
+			},
+			(error, count) => {
+				if (!error) console.log(count)
+			},
+		)
+		if ((await database.getUserVersion()) === 0) await database.setUserVersion(1)
+	} finally {
+		await database.close()
+	}
+	await deleteDatabase('preview.db') // This example database is disposable.
+}
+```
+
+Design notes: [`docs/notes/sqlite-notes.md`](../../docs/notes/sqlite-notes.md);
+limits: [known limits](../../docs/verify/known-limits.md). Exercised by the
+harness `Services` screen
+([`packages/app/src/Services.tsrx`](../app/src/Services.tsrx)).

package/package.json

@@ -1,18 +1,46 @@
 {
   "name": "@octane-xplat/sqlite",
-  "version": "0.0.1",
+  "version": "0.10.0",
   "description": "Cross-target SQLite persistence — sqlite-wasm worker on web, @nativescript-community/sqlite on iOS/Android",
   "repository": {
     "type": "git",
-    "url": "https://github.com/octane-xplat/octane-xplat.git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/sqlite"
   },
-  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/sqlite",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "files": [
-    "README.md",
-    "index.js",
-    "index.d.ts"
-  ]
-}
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": "./src/index.macos.ts",
+      "web": "./src/index.web.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript-community/sqlite": "3.5.9",
+    "@sqlite.org/sqlite-wasm": "3.53.4-build1"
+  },
+  "peerDependencies": {
+    "@nativescript/core": ">=9.1.0 <10"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "scripts": {
+    "test:packed": "node tests/packed-consumer.mjs"
+  }
+}

package/src/db.macos.ts

@@ -0,0 +1,343 @@
+/**
+ * macOS (AppKit/JSC host) backend: system libsqlite3 via C-function interop.
+ *
+ * The host runtime resolves declared C functions from the metadata bundle
+ * (metadata.macos.arm64.nsmd) — sqlite3.h and dlfcn.h are swept in during
+ * generation, so `dlopen` loads /usr/lib/libsqlite3.dylib and the sqlite3_*
+ * entry points are ordinary JS calls. This gives real file-backed sqlite with
+ * per-statement durability, identical semantics to the iOS/Android plugin.
+ *
+ * Depends on host metadata generated with the sqlite3/dlfcn umbrella imports
+ * (prebuilt metadata.nsmd >= the build that carries them); without it
+ * `supported` reports false and openDatabase rejects.
+ */
+import type { OpenDatabaseOptions, SqliteDb, SqliteParam, SqliteParams, SqliteRow } from './types'
+
+const host = globalThis as any
+const fs = host.require?.('node:fs')
+
+// SQLITE_TRANSIENT (-1): sqlite copies bound text/blob bytes. The marshaller
+// hands the C side a temporary buffer, so STATIC (0) reads freed memory.
+// Allocate the sentinel once — the runtime's Pointer→fn-pointer marshal is not
+// re-entrant; a fresh Pointer per call crashes on the second bind.
+let transientPtr: any = null
+const SQLITE_TRANSIENT = () => (transientPtr ??= new host.interop.Pointer(-1))
+const SQLITE_ROW = 100
+const SQLITE_DONE = 101
+const SQLITE_INTEGER = 1
+const SQLITE_FLOAT = 2
+const SQLITE_TEXT = 3
+const SQLITE_BLOB = 4
+
+let dlopened = false
+
+const ensureLib = () => {
+	if (dlopened) {
+		return
+	}
+
+	if (typeof host.dlopen !== 'function' || typeof host.sqlite3_open !== 'function') {
+		throw new Error('sqlite3 interop unavailable — host metadata predates the sqlite3/dlfcn sweep')
+	}
+
+	host.dlopen('/usr/lib/libsqlite3.dylib', 2)
+	dlopened = true
+}
+
+export const supported =
+	typeof host.dlopen === 'function' && typeof host.sqlite3_open === 'function'
+
+// NSApplicationSupportDirectory (14) / NSUserDomainMask (1).
+const databaseDir = (): string | null => {
+	try {
+		const urls = host.NSFileManager.defaultManager.URLsForDirectoryInDomains(14, 1)
+		if (!urls?.count) {
+			return null
+		}
+
+		return `${urls.objectAtIndex(0).path}/octane-sqlite`
+	} catch {
+		return null
+	}
+}
+
+const databasePath = (name: string): string | null => {
+	if (name === ':memory:') {
+		return null
+	}
+
+	const dir = databaseDir()
+	if (!dir || !fs) {
+		return null
+	}
+
+	try {
+		fs.mkdirSync(dir)
+	} catch {}
+
+	return `${dir}/${name.replace(/[^\w.-]/g, '_')}.sqlite3`
+}
+
+const toArray = (params?: SqliteParams): SqliteParam[] =>
+	params == null ? [] : Array.isArray(params) ? params : [params]
+
+const bind = (stmt: any, params: SqliteParam[]) => {
+	for (let i = 0; i < params.length; i++) {
+		const p = params[i]
+		const index = i + 1
+
+		if (p == null) {
+			host.sqlite3_bind_null(stmt, index)
+		} else if (typeof p === 'string') {
+			host.sqlite3_bind_text(stmt, index, p, -1, SQLITE_TRANSIENT())
+		} else if (typeof p === 'bigint') {
+			host.sqlite3_bind_int64(stmt, index, p)
+		} else if (typeof p === 'number') {
+			if (Number.isSafeInteger(p)) {
+				host.sqlite3_bind_int64(stmt, index, p)
+			} else {
+				host.sqlite3_bind_double(stmt, index, p)
+			}
+		} else {
+			const bytes = p instanceof ArrayBuffer ? new Uint8Array(p) : p
+			host.sqlite3_bind_blob(stmt, index, bytes, bytes.byteLength, SQLITE_TRANSIENT())
+		}
+	}
+}
+
+const columnValue = (stmt: any, index: number): any => {
+	switch (host.sqlite3_column_type(stmt, index)) {
+		case SQLITE_INTEGER: {
+			const v = host.sqlite3_column_int64(stmt, index)
+			return typeof v === 'bigint' && v >= -9007199254740991n && v <= 9007199254740991n
+				? Number(v)
+				: v
+		}
+		case SQLITE_FLOAT:
+			return host.sqlite3_column_double(stmt, index)
+		case SQLITE_TEXT:
+			return host.interop.stringFromCString(host.sqlite3_column_text(stmt, index))
+		case SQLITE_BLOB: {
+			const ptr = host.sqlite3_column_blob(stmt, index)
+			const len = host.sqlite3_column_bytes(stmt, index)
+
+			if (!ptr || !len) {
+				return new Uint8Array(0)
+			}
+
+			const data = host.NSData.alloc().initWithBytesLength(ptr, len)
+			return new Uint8Array(host.interop.bufferFromData(data))
+		}
+		default:
+			return null
+	}
+}
+
+class MacosSqliteDb implements SqliteDb {
+	isOpen = true
+	constructor(
+		private readonly db: any,
+		readonly persistent: boolean,
+	) {}
+
+	private ensureOpen() {
+		if (!this.isOpen) {
+			throw new Error('sqlite db is closed')
+		}
+	}
+
+	private err(): Error {
+		return new Error(host.interop.stringFromCString(host.sqlite3_errmsg(this.db)) || 'sqlite error')
+	}
+
+	// prepare → bind → step to completion → finalize. Rows are yielded through
+	// `onRow` (object or array shape chosen by the caller).
+	private run(
+		sql: string,
+		params: SqliteParam[],
+		onRow?: (stmt: any, cols: number) => void,
+	): number {
+		const ref = new host.interop.Reference()
+		const rc = host.sqlite3_prepare_v2(this.db, sql, -1, ref, null)
+
+		if (rc !== 0) {
+			throw this.err()
+		}
+
+		const stmt = ref.value
+		try {
+			bind(stmt, params)
+			const cols = host.sqlite3_column_count(stmt)
+			let rows = 0
+
+			while (true) {
+				const step = host.sqlite3_step(stmt)
+
+				if (step === SQLITE_ROW) {
+					rows++
+					onRow?.(stmt, cols)
+				} else if (step === SQLITE_DONE) {
+					return rows
+				} else {
+					throw this.err()
+				}
+			}
+		} finally {
+			host.sqlite3_finalize(stmt)
+		}
+	}
+
+	execute = async (sql: string, params?: SqliteParams): Promise<void> => {
+		this.ensureOpen()
+		this.run(sql, toArray(params))
+	}
+	select = async <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T[]> => {
+		this.ensureOpen()
+		const rows: T[] = []
+
+		this.run(sql, toArray(params), (stmt, cols) => {
+			const row: Record<string, unknown> = {}
+			for (let i = 0; i < cols; i++) {
+				row[host.interop.stringFromCString(host.sqlite3_column_name(stmt, i))] = columnValue(
+					stmt,
+					i,
+				)
+			}
+
+			rows.push(row as T)
+		})
+
+		return rows
+	}
+	selectArray = async (sql: string, params?: SqliteParams) => {
+		this.ensureOpen()
+		const rows: any[][] = []
+
+		this.run(sql, toArray(params), (stmt, cols) => {
+			const row: any[] = []
+			for (let i = 0; i < cols; i++) {
+				row.push(columnValue(stmt, i))
+			}
+
+			rows.push(row)
+		})
+
+		return rows
+	}
+	get = async <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T | null> => {
+		const rows = await this.select<T>(sql, params)
+		return rows[0] ?? null
+	}
+	getArray = async (sql: string, params?: SqliteParams) => {
+		const rows = await this.selectArray(sql, params)
+		return rows[0] ?? null
+	}
+	transaction = async <T>(action: (db: SqliteDb) => Promise<T>): Promise<T> => {
+		this.ensureOpen()
+		this.run('BEGIN', [])
+		try {
+			const result = await action(this)
+			this.run('COMMIT', [])
+			return result
+		} catch (error) {
+			try {
+				this.run('ROLLBACK', [])
+			} catch {}
+
+			throw error
+		}
+	}
+	each = async (
+		sql: string,
+		params: SqliteParams,
+		onRow: (error: Error | null, row: SqliteRow) => void,
+		onDone: (error: Error | null, count: number) => void,
+	) => {
+		this.ensureOpen()
+		let count = 0
+
+		try {
+			this.run(sql, toArray(params), (stmt, cols) => {
+				const row: SqliteRow = {}
+				for (let i = 0; i < cols; i++) {
+					row[host.interop.stringFromCString(host.sqlite3_column_name(stmt, i))] = columnValue(
+						stmt,
+						i,
+					)
+				}
+
+				onRow(null, row)
+				count++
+			})
+		} catch (error) {
+			onDone(error as Error, count)
+			throw error
+		}
+
+		onDone(null, count)
+		return count
+	}
+	getUserVersion = async (): Promise<number> => {
+		this.ensureOpen()
+		return Number((await this.getArray('PRAGMA user_version'))?.[0] ?? 0)
+	}
+	setUserVersion = async (version: number): Promise<void> => {
+		this.ensureOpen()
+		this.run(`PRAGMA user_version = ${version | 0}`, [])
+	}
+	close = async () => {
+		if (!this.isOpen) {
+			return
+		}
+
+		this.isOpen = false
+		host.sqlite3_close_v2(this.db)
+	}
+}
+
+export const openDatabase = async (
+	name: string,
+	_options?: OpenDatabaseOptions,
+): Promise<SqliteDb> => {
+	ensureLib()
+
+	const path = name === ':memory:' ? ':memory:' : databasePath(name)
+	const ref = new host.interop.Reference()
+	const rc = host.sqlite3_open(path ?? ':memory:', ref)
+
+	if (rc !== 0) {
+		const db = ref.value
+		const message = db
+			? host.interop.stringFromCString(host.sqlite3_errmsg(db))
+			: `open failed (rc=${rc})`
+
+		if (db) {
+			host.sqlite3_close_v2(db)
+		}
+
+		throw new Error(`sqlite open failed: ${message}`)
+	}
+
+	const db = ref.value
+	host.sqlite3_busy_timeout(db, 5000)
+	return new MacosSqliteDb(db, path != null)
+}
+
+export const deleteDatabase = async (name: string): Promise<boolean> => {
+	const path = databasePath(name)
+	if (!path) {
+		return false
+	}
+
+	let removed = false
+	const fm = host.NSFileManager.defaultManager
+
+	for (const suffix of ['', '-wal', '-shm', '-journal']) {
+		const target = `${path}${suffix}`
+		if (fs?.existsSync(target)) {
+			removed = !!fm.removeItemAtPathError(target, null) || removed
+		}
+	}
+
+	return removed
+}

package/src/db.ts

@@ -0,0 +1,54 @@
+import { knownFolders } from '@nativescript/core'
+import {
+	deleteDatabase as deleteNativeDatabase,
+	openOrCreate,
+	type SQLiteDatabase,
+} from '@nativescript-community/sqlite'
+
+import type { OpenDatabaseOptions, SqliteDb, SqliteParams, SqliteRow } from './types'
+
+export const supported = true
+
+const resolvePath = (name: string) =>
+	name.includes('/') ? name : knownFolders.documents().getFile(name).path
+
+class NativeSqliteDb implements SqliteDb {
+	readonly persistent = true
+	constructor(private readonly db: SQLiteDatabase) {}
+	get isOpen() {
+		return this.db.isOpen
+	}
+	execute = (sql: string, params?: SqliteParams) => this.db.execute(sql, params)
+	select = <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T[]> =>
+		this.db.select(sql, params) as Promise<T[]>
+	selectArray = (sql: string, params?: SqliteParams) => this.db.selectArray(sql, params)
+	// The plugin's getRaw reads resultDictionary before s.next() — get/getArray
+	// crash on iOS. select(selectN)[0] is the same contract, working code.
+	get = async <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T | null> =>
+		((await this.db.select(sql, params)) as T[])[0] ?? null
+	getArray = async (sql: string, params?: SqliteParams) =>
+		(await this.db.selectArray(sql, params))[0] ?? null
+	transaction = <T>(action: (db: SqliteDb) => Promise<T>): Promise<T> =>
+		this.db.transaction(() => action(this))
+	each = (
+		sql: string,
+		params: SqliteParams,
+		onRow: (error: Error | null, row: SqliteRow) => void,
+		onDone: (error: Error | null, count: number) => void,
+	): Promise<number> => this.db.each(sql, params, onRow, onDone)
+	getUserVersion = async () => this.db.getVersion() as number
+	setUserVersion = async (version: number) => {
+		this.db.setVersion(version)
+	}
+	close = async () => {
+		this.db.close()
+	}
+}
+
+export const openDatabase = async (
+	name: string,
+	options?: OpenDatabaseOptions,
+): Promise<SqliteDb> =>
+	new NativeSqliteDb(openOrCreate(resolvePath(name), { threading: options?.threading ?? true }))
+
+export const deleteDatabase = async (name: string) => deleteNativeDatabase(resolvePath(name))

package/src/db.unsupported.ts

@@ -0,0 +1,14 @@
+import type { OpenDatabaseOptions, SqliteDb } from './types'
+
+export const supported = false
+
+const unsupported = (name: string): never => {
+	throw new Error(
+		`@octane-xplat/sqlite is not supported on this platform yet (${name} not opened).`,
+	)
+}
+
+export const openDatabase = (_name: string, _options?: OpenDatabaseOptions): Promise<SqliteDb> =>
+	unsupported(_name)
+
+export const deleteDatabase = async (_name: string) => false

package/src/db.web.ts

@@ -0,0 +1,199 @@
+import type { OpenDatabaseOptions, SqliteDb, SqliteParams, SqliteRow } from './types'
+
+export const supported = true
+
+type Pending = { resolve: (value: any) => void; reject: (error: Error) => void }
+const pending = new Map<number, Pending>()
+const openDatabases = new Map<number, WebSqliteDb>()
+let nextId = 0
+let worker: Worker | null = null
+let workerGeneration = 0
+
+const toError = (reason: unknown) => (reason instanceof Error ? reason : new Error(String(reason)))
+
+const failWorker = (instance: Worker, error: Error) => {
+	if (worker !== instance) {
+		return
+	}
+
+	worker = null
+	workerGeneration++
+	instance.terminate()
+	openDatabases.clear()
+	for (const [id, entry] of pending) {
+		pending.delete(id)
+		entry.reject(error)
+	}
+}
+
+const ensureWorker = (): Worker => {
+	if (!worker) {
+		// Bundled by the consuming app's vite build (lib-mode workers are not
+		// emitted here — the leaf ships source). The wasm asset rides along via
+		// the ?url import inside the worker module.
+		const instance = new Worker(new URL('./worker.web.ts', import.meta.url), { type: 'module' })
+		worker = instance
+		instance.onmessage = (
+			event: MessageEvent<{ id: number; result?: unknown; error?: string }>,
+		) => {
+			if (worker !== instance) {
+				return
+			}
+
+			const { id, result, error } = event.data
+			const entry = pending.get(id)
+
+			if (!entry) {
+				return
+			}
+
+			pending.delete(id)
+			if (error != null) {
+				entry.reject(new Error(error))
+			} else {
+				entry.resolve(result)
+			}
+		}
+
+		instance.onerror = (event) => {
+			event.preventDefault()
+			failWorker(
+				instance,
+				new Error(`sqlite Web worker failed: ${event.message || 'startup or runtime error'}`),
+			)
+		}
+
+		instance.onmessageerror = () => {
+			failWorker(instance, new Error('sqlite Web worker sent an unreadable response'))
+		}
+
+		return instance
+	}
+
+	return worker
+}
+
+const call = <T>(op: string, ...args: unknown[]): Promise<T> =>
+	new Promise((resolve, reject) => {
+		const id = ++nextId
+		pending.set(id, { resolve, reject })
+		try {
+			ensureWorker().postMessage({ id, op, args })
+		} catch (error) {
+			pending.delete(id)
+			reject(toError(error))
+		}
+	})
+
+class WebSqliteDb implements SqliteDb {
+	private closed = false
+	constructor(
+		private readonly databaseId: number,
+		readonly persistent: boolean,
+		private readonly generation: number,
+	) {}
+	get isOpen() {
+		return !this.closed && this.generation === workerGeneration
+	}
+	private ensureOpen() {
+		if (!this.isOpen) {
+			throw new Error('sqlite db is closed')
+		}
+	}
+	invalidate() {
+		this.closed = true
+	}
+	execute = (sql: string, params?: SqliteParams) => {
+		this.ensureOpen()
+		return call<void>('execute', this.databaseId, sql, params ?? null)
+	}
+	select = <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T[]> => {
+		this.ensureOpen()
+		return call<T[]>('select', this.databaseId, sql, params ?? null)
+	}
+	selectArray = (sql: string, params?: SqliteParams) => {
+		this.ensureOpen()
+		return call<any[]>('selectArray', this.databaseId, sql, params ?? null)
+	}
+	get = <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T | null> => {
+		this.ensureOpen()
+		return call<T | null>('get', this.databaseId, sql, params ?? null)
+	}
+	getArray = (sql: string, params?: SqliteParams) => {
+		this.ensureOpen()
+		return call<any[] | null>('getArray', this.databaseId, sql, params ?? null)
+	}
+	// Messages are serialized on the single worker-side connection, so the
+	// BEGIN…COMMIT window can span several RPC calls safely.
+	transaction = async <T>(action: (db: SqliteDb) => Promise<T>): Promise<T> => {
+		this.ensureOpen()
+		await call('begin', this.databaseId)
+		try {
+			const result = await action(this)
+			await call('commit', this.databaseId)
+			return result
+		} catch (error) {
+			await call('rollback', this.databaseId).catch(() => {})
+			throw error
+		}
+	}
+	each = async (
+		sql: string,
+		params: SqliteParams,
+		onRow: (error: Error | null, row: SqliteRow) => void,
+		onDone: (error: Error | null, count: number) => void,
+	) => {
+		// Row callbacks can't stream back over postMessage cheaply for v1 —
+		// select then iterate. The contract is identical, the memory isn't.
+		const rows = await this.select(sql, params)
+
+		for (const row of rows) {
+			onRow(null, row)
+		}
+
+		onDone(null, rows.length)
+		return rows.length
+	}
+	getUserVersion = () => {
+		this.ensureOpen()
+		return call<number>('getUserVersion', this.databaseId)
+	}
+	setUserVersion = (version: number) => {
+		this.ensureOpen()
+		return call<void>('setUserVersion', this.databaseId, version | 0)
+	}
+	close = async () => {
+		if (!this.isOpen) {
+			return
+		}
+
+		this.closed = true
+		openDatabases.delete(this.databaseId)
+		await call('close', this.databaseId).catch(() => {})
+	}
+}
+
+export const openDatabase = async (
+	name: string,
+	_options?: OpenDatabaseOptions,
+): Promise<SqliteDb> => {
+	const generation = workerGeneration
+	const result = await call<{ databaseId: number; persistent: boolean }>('open', name)
+	if (generation !== workerGeneration) {
+		throw new Error('sqlite Web worker failed while opening the database')
+	}
+
+	const db = new WebSqliteDb(result.databaseId, result.persistent, generation)
+	openDatabases.set(result.databaseId, db)
+	return db
+}
+
+export const deleteDatabase = async (name: string) => {
+	const result = await call<{ deleted: boolean; databaseIds: number[] }>('delete', name)
+	for (const databaseId of result.databaseIds) {
+		openDatabases.get(databaseId)?.invalidate()
+		openDatabases.delete(databaseId)
+	}
+
+	return result.deleted
+}

package/src/db.windows.ts

@@ -0,0 +1 @@
+export * from './db.unsupported'

package/src/index.macos.ts

@@ -0,0 +1,2 @@
+export * from './db'
+export type * from './types'

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './db'
+export type * from './types'

package/src/index.web.ts

@@ -0,0 +1,2 @@
+export * from './db'
+export type * from './types'

package/src/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	// Package source is consumed as raw .ts (exports map → ./src/*), so
+	// consumer dev transforms resolve THIS directory's nearest tsconfig.json.
+	// @NativeClass()/decorator files need experimentalDecorators emit; without
+	// a discoverable config the transform emits TC39 `export @dec class`,
+	// which the device V8 cannot parse — SyntaxError at boot.
+	"extends": "../../../tsconfig.base.json"
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared contract for @octane-xplat/sqlite — every platform leaf exports the
+ * same names (the identical-exports invariant; the .web/.macos/.windows leaves
+ * are implementation swaps, not API changes).
+ */
+
+export type SqliteParam = null | number | bigint | string | ArrayBuffer | Uint8Array
+export type SqliteParams = SqliteParam | SqliteParam[]
+
+export interface SqliteRow {
+	[name: string]: SqliteParam
+}
+
+export interface OpenDatabaseOptions {
+	/**
+	 * Native only: route calls through the plugin's worker thread instead of
+	 * the JS thread. Defaults to true. Ignored on other platforms (the web
+	 * leaf always runs in a Worker).
+	 */
+	threading?: boolean
+}
+
+export interface SqliteDb {
+	readonly isOpen: boolean
+	/**
+	 * False when the backend opened a transient database — the web leaf only
+	 * persists through OPFS, which needs a Worker and, on some browsers,
+	 * cross-origin isolation. Always true on native.
+	 */
+	readonly persistent: boolean
+	execute(sql: string, params?: SqliteParams): Promise<void>
+	select<T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T[]>
+	selectArray(sql: string, params?: SqliteParams): Promise<SqliteParam[][]>
+	/** First row, or null. */
+	get<T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T | null>
+	/** First row as an array, or null. */
+	getArray(sql: string, params?: SqliteParams): Promise<SqliteParam[] | null>
+	/** Runs `action` inside a transaction; a throw rolls everything back. */
+	transaction<T>(action: (db: SqliteDb) => Promise<T>): Promise<T>
+	each(
+		sql: string,
+		params: SqliteParams,
+		onRow: (error: Error | null, row: SqliteRow) => void,
+		onDone: (error: Error | null, count: number) => void,
+	): Promise<number>
+	/** PRAGMA user_version — shared migration hook across platforms. */
+	getUserVersion(): Promise<number>
+	setUserVersion(version: number): Promise<void>
+	close(): Promise<void>
+}

package/src/worker.web.ts

@@ -0,0 +1,143 @@
+/// <reference lib="webworker" />
+/**
+ * sqlite-wasm host. Runs inside a module Worker spawned by db.web.ts; the
+ * client is a thin RPC layer so every API call is async on the JS side.
+ *
+ * Persistence preference order:
+ *   1. installOpfsSAHPoolVfs — OPFS via sync access handles, needs a Worker
+ *      but NOT cross-origin isolation (no COOP/COEP deployment constraint).
+ *   2. OpfsDb — the older OPFS backend; requires crossOriginIsolated.
+ *   3. oo1.DB('ct') — transient in-memory database.
+ */
+import sqlite3InitModule from '@sqlite.org/sqlite-wasm'
+import wasmUrl from '@sqlite.org/sqlite-wasm/sqlite3.wasm?url'
+
+type Sqlite3 = Awaited<ReturnType<typeof sqlite3InitModule>>
+const sqlite3Promise = sqlite3InitModule({ locateFile: () => wasmUrl })
+
+type DatabaseHandle = { db: any; name: string; persistent: boolean }
+const databases = new Map<number, DatabaseHandle>()
+let nextDatabaseId = 0
+let sahPoolPromise: Promise<any> | null = null
+
+const getSahPool = (sqlite3: Sqlite3) => {
+	sahPoolPromise ??= Promise.resolve()
+		.then(() =>
+			typeof (sqlite3 as any).installOpfsSAHPoolVfs === 'function'
+				? (sqlite3 as any).installOpfsSAHPoolVfs()
+				: null,
+		)
+		.catch(() => null)
+
+	return sahPoolPromise
+}
+
+const database = (id: number) => {
+	const entry = databases.get(id)
+	if (!entry) {
+		throw new Error(`sqlite db handle ${id} is not open`)
+	}
+
+	return entry
+}
+
+const normalizeParams = (params: any) =>
+	params == null ? undefined : Array.isArray(params) ? params : [params]
+
+const open = async (name: string) => {
+	const sqlite3: Sqlite3 = await sqlite3Promise
+	const file = name.startsWith('/') ? name : `/${name}`
+	const sahPool = await getSahPool(sqlite3)
+
+	let db: any
+	let persistent = false
+	if (sahPool) {
+		db = new sqlite3.oo1.DB(file, 'c', sahPool.vfsName)
+		persistent = true
+	} else if ('opfs' in sqlite3 && (sqlite3.oo1 as any).OpfsDb) {
+		db = new (sqlite3.oo1 as any).OpfsDb(file)
+		persistent = true
+	} else {
+		db = new sqlite3.oo1.DB(file, 'ct')
+		persistent = false
+	}
+
+	const databaseId = ++nextDatabaseId
+	databases.set(databaseId, { db, name: file, persistent })
+	return { databaseId, persistent, version: sqlite3.version.libVersion }
+}
+
+const deleteDb = async (name: string) => {
+	const file = name.startsWith('/') ? name : `/${name}`
+	const databaseIds: number[] = []
+
+	for (const [id, entry] of databases) {
+		if (entry.name === file) {
+			entry.db.close()
+			databases.delete(id)
+			databaseIds.push(id)
+		}
+	}
+
+	const sahPool = sahPoolPromise ? await sahPoolPromise : null
+	if (sahPool) {
+		return { deleted: Boolean(sahPool.unlink(file)), databaseIds }
+	}
+
+	// OpfsDb path: best-effort removal of the OPFS entry.
+	try {
+		const root = await navigator.storage.getDirectory()
+		await root.removeEntry(file.slice(1))
+		return { deleted: true, databaseIds }
+	} catch {
+		return { deleted: false, databaseIds }
+	}
+}
+
+const handlers: Record<string, (...args: any[]) => unknown> = {
+	open,
+	delete: deleteDb,
+	execute: (id: number, sql: string, params?: any) =>
+		database(id).db.exec({ sql, bind: normalizeParams(params) }),
+	select: (id: number, sql: string, params?: any) =>
+		database(id).db.selectObjects(sql, normalizeParams(params)),
+	selectArray: (id: number, sql: string, params?: any) =>
+		database(id).db.selectArrays(sql, normalizeParams(params)),
+	get: (id: number, sql: string, params?: any) =>
+		database(id).db.selectObjects(sql, normalizeParams(params))[0] ?? null,
+	getArray: (id: number, sql: string, params?: any) =>
+		database(id).db.selectArrays(sql, normalizeParams(params))[0] ?? null,
+	begin: (id: number) => database(id).db.exec('BEGIN'),
+	commit: (id: number) => database(id).db.exec('COMMIT'),
+	rollback: (id: number) => database(id).db.exec('ROLLBACK'),
+	getUserVersion: (id: number) => database(id).db.selectValue('PRAGMA user_version'),
+	setUserVersion: (id: number, version: number) =>
+		database(id).db.exec(`PRAGMA user_version = ${version | 0}`),
+	close: (id: number) => {
+		const entry = databases.get(id)
+		if (!entry) {
+			return
+		}
+
+		entry.db.close()
+		databases.delete(id)
+	},
+}
+
+self.onmessage = async (event: MessageEvent<{ id: number; op: string; args: any[] }>) => {
+	const { id, op, args } = event.data
+
+	try {
+		const handler = handlers[op]
+
+		if (!handler) {
+			throw new Error(`unknown sqlite op: ${op}`)
+		}
+
+		const result = await handler(...args)
+
+		;(self as any).postMessage({ id, result })
+	} catch (error: any) {
+		;(self as any).postMessage({ id, error: error?.message ?? String(error) })
+	}
+}

package/index.d.ts

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

package/index.js

@@ -1,2 +0,0 @@
-// Reservation stub; implementation will arrive in a later release.
-module.exports = {}