@octane-xplat/sqlite 0.9.0 → 0.10.0

package/README.md

@@ -1,14 +1,14 @@
 # `@octane-xplat/sqlite`
 
+```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.
 
-```sh
-pnpm add @octane-xplat/sqlite
-```
-
 ```ts
 import { openDatabase, supported } from '@octane-xplat/sqlite'
 
@@ -28,7 +28,34 @@ 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.
 
-Design notes: [`docs/sqlite-notes.md`](../../docs/sqlite-notes.md);
-limits: [known limits](../../docs/known-limits.md). Exercised by the
+```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,6 +1,6 @@
 {
   "name": "@octane-xplat/sqlite",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Cross-target SQLite persistence — sqlite-wasm worker on web, @nativescript-community/sqlite on iOS/Android",
   "repository": {
     "type": "git",

package/src/db.web.ts

@@ -4,16 +4,42 @@ 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.
-		worker = new Worker(new URL('./worker.web.ts', import.meta.url), { type: 'module' })
-		worker.onmessage = (event: MessageEvent<{ id: number; result?: unknown; error?: string }>) => {
+		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)
 
@@ -28,6 +54,20 @@ const ensureWorker = (): Worker => {
 				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
@@ -37,48 +77,63 @@ const call = <T>(op: string, ...args: unknown[]): Promise<T> =>
 	new Promise((resolve, reject) => {
 		const id = ++nextId
 		pending.set(id, { resolve, reject })
-		ensureWorker().postMessage({ id, op, args })
+		try {
+			ensureWorker().postMessage({ id, op, args })
+		} catch (error) {
+			pending.delete(id)
+			reject(toError(error))
+		}
 	})
 
 class WebSqliteDb implements SqliteDb {
-	isOpen = true
-	constructor(readonly persistent: boolean) {}
+	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', sql, params ?? null)
+		return call<void>('execute', this.databaseId, sql, params ?? null)
 	}
 	select = <T = SqliteRow>(sql: string, params?: SqliteParams): Promise<T[]> => {
 		this.ensureOpen()
-		return call<T[]>('select', sql, params ?? null)
+		return call<T[]>('select', this.databaseId, sql, params ?? null)
 	}
 	selectArray = (sql: string, params?: SqliteParams) => {
 		this.ensureOpen()
-		return call<any[]>('selectArray', sql, params ?? null)
+		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', sql, params ?? null)
+		return call<T | null>('get', this.databaseId, sql, params ?? null)
 	}
 	getArray = (sql: string, params?: SqliteParams) => {
 		this.ensureOpen()
-		return call<any[] | null>('getArray', sql, params ?? null)
+		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')
+		await call('begin', this.databaseId)
 		try {
 			const result = await action(this)
-			await call('commit')
+			await call('commit', this.databaseId)
 			return result
 		} catch (error) {
-			await call('rollback').catch(() => {})
+			await call('rollback', this.databaseId).catch(() => {})
 			throw error
 		}
 	}
@@ -101,19 +156,20 @@ class WebSqliteDb implements SqliteDb {
 	}
 	getUserVersion = () => {
 		this.ensureOpen()
-		return call<number>('getUserVersion')
+		return call<number>('getUserVersion', this.databaseId)
 	}
 	setUserVersion = (version: number) => {
 		this.ensureOpen()
-		return call<void>('setUserVersion', version | 0)
+		return call<void>('setUserVersion', this.databaseId, version | 0)
 	}
 	close = async () => {
 		if (!this.isOpen) {
 			return
 		}
 
-		this.isOpen = false
-		await call('close').catch(() => {})
+		this.closed = true
+		openDatabases.delete(this.databaseId)
+		await call('close', this.databaseId).catch(() => {})
 	}
 }
 
@@ -121,8 +177,23 @@ export const openDatabase = async (
 	name: string,
 	_options?: OpenDatabaseOptions,
 ): Promise<SqliteDb> => {
-	const result = await call<{ persistent: boolean }>('open', name)
-	return new WebSqliteDb(result.persistent)
+	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) => call<boolean>('delete', name)
+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/worker.web.ts

@@ -15,10 +15,31 @@ import wasmUrl from '@sqlite.org/sqlite-wasm/sqlite3.wasm?url'
 type Sqlite3 = Awaited<ReturnType<typeof sqlite3InitModule>>
 const sqlite3Promise = sqlite3InitModule({ locateFile: () => wasmUrl })
 
-let db: any = null
-let dbName = ''
-let sahPool: any = null
-let persistent = false
+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]
@@ -26,17 +47,10 @@ const normalizeParams = (params: any) =>
 const open = async (name: string) => {
 	const sqlite3: Sqlite3 = await sqlite3Promise
 	const file = name.startsWith('/') ? name : `/${name}`
+	const sahPool = await getSahPool(sqlite3)
 
-	if (db) {
-		db.close()
-	}
-
-	db = null
-	sahPool ??=
-		typeof (sqlite3 as any).installOpfsSAHPoolVfs === 'function'
-			? await (sqlite3 as any).installOpfsSAHPoolVfs().catch(() => null)
-			: null
-
+	let db: any
+	let persistent = false
 	if (sahPool) {
 		db = new sqlite3.oo1.DB(file, 'c', sahPool.vfsName)
 		persistent = true
@@ -48,51 +62,65 @@ const open = async (name: string) => {
 		persistent = false
 	}
 
-	dbName = file
-	return { persistent, version: sqlite3.version.libVersion }
+	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[] = []
 
-	if (db && dbName === file) {
-		db.close()
-		db = null
+	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 Boolean(sahPool.unlink(file))
+		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 true
+		return { deleted: true, databaseIds }
 	} catch {
-		return false
+		return { deleted: false, databaseIds }
 	}
 }
 
 const handlers: Record<string, (...args: any[]) => unknown> = {
 	open,
 	delete: deleteDb,
-	execute: (sql: string, params?: any) => db.exec({ sql, bind: normalizeParams(params) }),
-	select: (sql: string, params?: any) => db.selectObjects(sql, normalizeParams(params)),
-	selectArray: (sql: string, params?: any) => db.selectArrays(sql, normalizeParams(params)),
-	get: (sql: string, params?: any) => db.selectObjects(sql, normalizeParams(params))[0] ?? null,
-	getArray: (sql: string, params?: any) => db.selectArrays(sql, normalizeParams(params))[0] ?? null,
-	begin: () => db.exec('BEGIN'),
-	commit: () => db.exec('COMMIT'),
-	rollback: () => db.exec('ROLLBACK'),
-	getUserVersion: () => db.selectValue('PRAGMA user_version'),
-	setUserVersion: (version: number) => db.exec(`PRAGMA user_version = ${version | 0}`),
-	close: () => {
-		if (db) {
-			db.close()
+	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
 		}
 
-		db = null
+		entry.db.close()
+		databases.delete(id)
 	},
 }
 
@@ -106,10 +134,6 @@ self.onmessage = async (event: MessageEvent<{ id: number; op: string; args: any[
 			throw new Error(`unknown sqlite op: ${op}`)
 		}
 
-		if (!db && op !== 'open' && op !== 'delete') {
-			throw new Error('sqlite db is not open')
-		}
-
 		const result = await handler(...args)
 
 		;(self as any).postMessage({ id, result })