@orkestrel/sqlite 0.0.1 → 0.0.2

package/README.md

@@ -1,9 +1,13 @@
 # @orkestrel/sqlite
 
-A typed, synchronous SQLite wrapper for the `@orkestrel` line — a thin,
-zero-dependency skin over Node's built-in `node:sqlite` (`DatabaseSync` /
-`StatementSync`) giving prepared statements, transactions, and pragmas. Built
-on `@orkestrel/contract` for its boundary narrowing.
+A typed, synchronous SQLite wrapper for the `@orkestrel` line — a thin skin
+over Node's built-in `node:sqlite` (`DatabaseSync` / `StatementSync`) giving
+prepared statements, transactions, and pragmas, with a single runtime
+dependency: `@orkestrel/contract`, used for its boundary narrowing.
+
+`node:sqlite` is experimental on current Node versions — importing this
+package emits an `ExperimentalWarning` at runtime until Node stabilizes the
+module.
 
 ## Install
 

package/dist/src/server/index.cjs

@@ -112,21 +112,32 @@ function bindParameters(parameters) {
 * wrapper runs SQL.
 *
 * @remarks
-* Created by `database.prepare(sql)`. Bare named parameters are enabled on
-* construction so a record's keys bind without the SQL prefix character. Each
-* method binds the optional parameters (an array spread to `?` placeholders, a
-* record passed as a single named object) and executes synchronously, mapping any
-* native fault to a `SQLiteError`. Row values arrive as the native
-* {@link SQLiteRow} types; the typed layer above (the driver) imposes a precise
-* shape through a contract rather than re-narrowing here (AGENTS §14).
+* Created by `database.prepare(sql)`, which threads a liveness check (internal —
+* this constructor's second parameter is not part of the documented surface).
+* Bare named parameters are enabled on construction so a record's keys bind
+* without the SQL prefix character. Each method first gates on that liveness
+* check, throwing a `CLOSED` `SQLiteError` once the owning connection has been
+* closed — a statement prepared on a connection that is later closed and then
+* reconnected stays `CLOSED`; a fresh statement must be prepared on the new
+* connection. Each method then binds the optional parameters (an array spread
+* to `?` placeholders, a record passed as a single named object) and executes
+* synchronously, mapping any native fault to a `SQLiteError` — including a
+* mid-stream fault from `iterate`'s lazy native iterator, stepped inside its own
+* try/catch so a fault on a later row is mapped exactly like an eager one. Row
+* values arrive as the native {@link SQLiteRow} types; the typed layer above
+* (the driver) imposes a precise shape through a contract rather than
+* re-narrowing here (AGENTS §14).
 */
 var SQLiteStatement = class {
 	#statement;
-	constructor(statement) {
+	#closed;
+	constructor(statement, closed) {
 		this.#statement = statement;
+		this.#closed = closed;
 		this.#statement.setAllowBareNamedParameters(true);
 	}
 	run(parameters) {
+		this.#require();
 		try {
 			const bound = bindParameters(parameters);
 			const result = "named" in bound ? this.#statement.run(bound.named) : this.#statement.run(...bound.positional);
@@ -139,6 +150,7 @@ var SQLiteStatement = class {
 		}
 	}
 	get(parameters) {
+		this.#require();
 		try {
 			const bound = bindParameters(parameters);
 			return "named" in bound ? this.#statement.get(bound.named) : this.#statement.get(...bound.positional);
@@ -147,6 +159,7 @@ var SQLiteStatement = class {
 		}
 	}
 	all(parameters) {
+		this.#require();
 		try {
 			const bound = bindParameters(parameters);
 			return "named" in bound ? this.#statement.all(bound.named) : this.#statement.all(...bound.positional);
@@ -155,12 +168,30 @@ var SQLiteStatement = class {
 		}
 	}
 	iterate(parameters) {
+		this.#require();
+		let native;
 		try {
 			const bound = bindParameters(parameters);
-			return "named" in bound ? this.#statement.iterate(bound.named) : this.#statement.iterate(...bound.positional);
+			native = "named" in bound ? this.#statement.iterate(bound.named) : this.#statement.iterate(...bound.positional);
 		} catch (error) {
 			throw wrapError(error);
 		}
+		return this.#stream(native);
+	}
+	#require() {
+		if (this.#closed()) throw new SQLiteError("CLOSED", "Statement is closed — its connection was closed; prepare a new statement");
+	}
+	*#stream(native) {
+		for (;;) {
+			let result;
+			try {
+				result = native.next();
+			} catch (error) {
+				throw wrapError(error);
+			}
+			if (result.done === true) return;
+			yield result.value;
+		}
 	}
 };
 //#endregion
@@ -174,10 +205,13 @@ var SQLiteStatement = class {
 * private gate that throws a `CLOSED` `SQLiteError` before `connect` or after
 * `close`. `exec` runs result-less SQL; `prepare` compiles a `SQLiteStatement`;
 * `transaction` wraps a scope in `BEGIN` / `COMMIT`, rolling back on a throw;
-* `pragma` reads (or sets then reads) one PRAGMA value — `name` is trusted
+* `begin` / `commit` / `rollback` expose those same primitives directly for a
+* long-lived or externally-driven transaction; `pragma` reads (or sets then
+* reads) one PRAGMA value — `name` is trusted
 * internal use only, never untrusted input, since pragma names cannot be bound
-* as parameters. A native fault surfaces as a `SQLiteError` mapped at the
-* boundary.
+* as parameters. `transacting` reports whether a transaction is currently open
+* (node:sqlite's `isTransaction`), `false` when not connected. A native fault
+* surfaces as a `SQLiteError` mapped at the boundary.
 */
 var SQLiteDatabase = class {
 	#path;
@@ -199,6 +233,9 @@ var SQLiteDatabase = class {
 	get connected() {
 		return this.#database !== void 0;
 	}
+	get transacting() {
+		return this.#database?.isTransaction ?? false;
+	}
 	connect() {
 		if (this.#database === void 0) this.#database = new node_sqlite.DatabaseSync(this.#path, {
 			readOnly: this.#readonly,
@@ -224,23 +261,40 @@ var SQLiteDatabase = class {
 	}
 	prepare(sql) {
 		try {
-			return new SQLiteStatement(this.#require().prepare(sql));
+			const database = this.#require();
+			return new SQLiteStatement(database.prepare(sql), () => this.#database !== database);
 		} catch (error) {
 			throw wrapError(error);
 		}
 	}
 	transaction(scope) {
-		this.exec("BEGIN");
+		this.begin();
+		let result;
 		try {
-			const result = scope();
-			this.exec("COMMIT");
-			return result;
+			result = scope();
 		} catch (error) {
 			try {
-				this.exec("ROLLBACK");
+				this.rollback();
 			} catch {}
 			throw error;
 		}
+		if ((0, _orkestrel_contract.isPromiseLike)(result)) {
+			try {
+				this.rollback();
+			} catch {}
+			throw new SQLiteError("UNKNOWN", "transaction(scope) requires a synchronous scope — an async or Promise-returning scope cannot commit or roll back before its awaited work runs; use begin() / commit() / rollback() directly for a transaction that spans async caller code");
+		}
+		this.commit();
+		return result;
+	}
+	begin() {
+		this.exec("BEGIN");
+	}
+	commit() {
+		this.exec("COMMIT");
+	}
+	rollback() {
+		this.exec("ROLLBACK");
 	}
 	pragma(name, value) {
 		if (value !== void 0) this.exec("PRAGMA " + name + " = " + value);
@@ -268,7 +322,7 @@ var SQLiteDatabase = class {
 *
 * @example
 * ```ts
-* import { createSQLiteDatabase } from '@src/server'
+* import { createSQLiteDatabase } from '@orkestrel/sqlite'
 *
 * const db = createSQLiteDatabase({ path: ':memory:' })
 * db.connect()

package/dist/src/server/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["#statement","#path","#readonly","#timeout","#foreignKeys","#bigints","#database","#require"],"sources":["../../../src/server/constants.ts","../../../src/server/errors.ts","../../../src/server/helpers.ts","../../../src/server/SQLiteStatement.ts","../../../src/server/SQLiteDatabase.ts","../../../src/server/factories.ts"],"sourcesContent":["// The wrapper's numeric SQLite result codes (AGENTS §5 constants file).\n\n/**\n * SQLite result code for a constraint violation (`SQLITE_CONSTRAINT`).\n *\n * @remarks\n * A native `errcode` packs the primary result in its low byte, with extended codes\n * in the high bits (e.g. `SQLITE_CONSTRAINT_UNIQUE`), so the low byte is masked off\n * before comparing. Read only by `wrapError`.\n */\nexport const SQLITE_CONSTRAINT = 19\n\n/**\n * SQLite result code for a locked-database fault (`SQLITE_BUSY`).\n *\n * @remarks\n * A native `errcode` packs the primary result in its low byte, with extended codes\n * in the high bits, so the low byte is masked off before comparing. Read only by\n * `wrapError`.\n */\nexport const SQLITE_BUSY = 5\n","import type { SQLiteErrorCode } from './types.js'\n\n// Errors for the SQLite wrapper. A single `SQLiteError` carries a\n// machine-readable `code` mapped from the native `node:sqlite` fault at the\n// boundary (`wrapError`), so a `catch` branches on `error.code` rather than\n// parsing a message. Mirrors the IndexedDB wrapper's `IndexedDBError`; its three\n// codes are deliberately lean — the wrapper sits right on the raw SQLite surface,\n// where the constraint fault is the one worth naming, `CLOSED` is the\n// wrapper-lifecycle fault, and everything else is `UNKNOWN` (AGENTS §12).\n\n/**\n * An error thrown by the SQLite wrapper.\n *\n * @remarks\n * Carries a {@link SQLiteErrorCode} and an optional `context` record (e.g. the\n * native SQLite `errcode`). Construct it directly for the `CLOSED`\n * wrapper-lifecycle fault; the internal `wrapError` maps a native `node:sqlite`\n * error to the right code at the boundary. Narrow a caught value with\n * {@link isSQLiteError}.\n *\n * @example\n * ```ts\n * try {\n * \tstatement.run({ id: 'u1' })\n * } catch (error) {\n * \tif (isSQLiteError(error) && error.code === 'CONSTRAINT') {\n * \t\t// a UNIQUE / PRIMARY KEY violation\n * \t}\n * }\n * ```\n */\nexport class SQLiteError extends Error {\n\treadonly code: SQLiteErrorCode\n\treadonly context?: Readonly<Record<string, unknown>>\n\n\tconstructor(code: SQLiteErrorCode, message: string, context?: Readonly<Record<string, unknown>>) {\n\t\tsuper(message)\n\t\tthis.name = 'SQLiteError'\n\t\tthis.code = code\n\t\tthis.context = context\n\t}\n}\n\n/**\n * Whether a value is a {@link SQLiteError}.\n *\n * @param value - The value to test\n * @returns `true` when `value` is a `SQLiteError`\n */\nexport function isSQLiteError(value: unknown): value is SQLiteError {\n\treturn value instanceof SQLiteError\n}\n","import type { SQLiteParameters, SQLiteValue } from './types.js'\nimport { isArray, isObject } from '@orkestrel/contract'\nimport { SQLITE_BUSY, SQLITE_CONSTRAINT } from './constants.js'\nimport { SQLiteError } from './errors.js'\n\n// The wrapper's boundary helpers, shared by `SQLiteDatabase` and `SQLiteStatement`:\n// `wrapError` maps a thrown native `node:sqlite` error to a typed `SQLiteError`\n// (the one honest narrowing point — `isObject` + `in`, never `as`, per AGENTS\n// §14), and `bindParameters` normalizes the wrapper's `SQLiteParameters` to the\n// shape a native `StatementSync` call expects (positional spread vs. a single\n// named record). Both are pure.\n\n/**\n * Convert a thrown native `node:sqlite` error into a typed {@link SQLiteError}.\n *\n * @remarks\n * The single boundary mapping for the wrapper. The thrown value arrives as\n * `unknown` and is narrowed with `isObject` + the `in` operator (never `as`, and\n * not `isRecord` — a native `node:sqlite` error is an `Error` instance, so its\n * prototype fails the plain-record test) to read its `errcode` — a numeric SQLite\n * result code whose low byte identifies a constraint violation\n * (`SQLITE_CONSTRAINT`), mapped to code `'CONSTRAINT'`; a locked-database fault\n * (`SQLITE_BUSY`) is mapped to `'BUSY'`; anything else is `'UNKNOWN'`. The\n * original message is preserved and `{ errcode }` carried in `context` when\n * present. An already-typed `SQLiteError` is returned unchanged.\n *\n * @param error - The thrown value to convert\n * @returns The equivalent `SQLiteError`\n */\nexport function wrapError(error: unknown): SQLiteError {\n\tif (error instanceof SQLiteError) return error\n\tconst errcode =\n\t\tisObject(error) && 'errcode' in error && typeof error.errcode === 'number'\n\t\t\t? error.errcode\n\t\t\t: undefined\n\tconst message = error instanceof Error ? error.message : 'Unknown SQLite error'\n\tconst code =\n\t\terrcode !== undefined && (errcode & 0xff) === SQLITE_CONSTRAINT\n\t\t\t? 'CONSTRAINT'\n\t\t\t: errcode !== undefined && (errcode & 0xff) === SQLITE_BUSY\n\t\t\t\t? 'BUSY'\n\t\t\t\t: 'UNKNOWN'\n\treturn new SQLiteError(code, message, errcode !== undefined ? { errcode } : undefined)\n}\n\n/**\n * Normalize {@link SQLiteParameters} to the binding shape a native `StatementSync`\n * call expects.\n *\n * @remarks\n * Positional parameters (an array) bind to `?` placeholders and are spread into\n * the call; named parameters (a record) bind to bare `:name` placeholders and are\n * passed as a single leading object. Returning a discriminated result keeps the\n * `SQLiteStatement` dispatch typed against the native overloads without `as`.\n *\n * @param parameters - The wrapper parameters, or `undefined` for none\n * @returns `{ positional }` for an array (empty when omitted) or `{ named }` for a record\n */\nexport function bindParameters(\n\tparameters?: SQLiteParameters,\n):\n\t| { readonly positional: readonly SQLiteValue[] }\n\t| { readonly named: Readonly<Record<string, SQLiteValue>> } {\n\tif (parameters === undefined) return { positional: [] }\n\tif (isArray<SQLiteValue>(parameters)) return { positional: parameters }\n\treturn { named: parameters }\n}\n","import type { StatementSync } from 'node:sqlite'\nimport type {\n\tSQLiteParameters,\n\tSQLiteRow,\n\tSQLiteRunResult,\n\tSQLiteStatementInterface,\n} from './types.js'\nimport { bindParameters, wrapError } from './helpers.js'\n\n/**\n * A prepared statement over `node:sqlite`'s `StatementSync` — the only way the\n * wrapper runs SQL.\n *\n * @remarks\n * Created by `database.prepare(sql)`. Bare named parameters are enabled on\n * construction so a record's keys bind without the SQL prefix character. Each\n * method binds the optional parameters (an array spread to `?` placeholders, a\n * record passed as a single named object) and executes synchronously, mapping any\n * native fault to a `SQLiteError`. Row values arrive as the native\n * {@link SQLiteRow} types; the typed layer above (the driver) imposes a precise\n * shape through a contract rather than re-narrowing here (AGENTS §14).\n */\nexport class SQLiteStatement implements SQLiteStatementInterface {\n\treadonly #statement: StatementSync\n\n\tconstructor(statement: StatementSync) {\n\t\tthis.#statement = statement\n\t\tthis.#statement.setAllowBareNamedParameters(true)\n\t}\n\n\trun(parameters?: SQLiteParameters): SQLiteRunResult {\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\tconst result =\n\t\t\t\t'named' in bound\n\t\t\t\t\t? this.#statement.run(bound.named)\n\t\t\t\t\t: this.#statement.run(...bound.positional)\n\t\t\treturn { changes: Number(result.changes), rowid: Number(result.lastInsertRowid) }\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\tget(parameters?: SQLiteParameters): SQLiteRow | undefined {\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\treturn 'named' in bound\n\t\t\t\t? this.#statement.get(bound.named)\n\t\t\t\t: this.#statement.get(...bound.positional)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\tall(parameters?: SQLiteParameters): readonly SQLiteRow[] {\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\treturn 'named' in bound\n\t\t\t\t? this.#statement.all(bound.named)\n\t\t\t\t: this.#statement.all(...bound.positional)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\titerate(parameters?: SQLiteParameters): IterableIterator<SQLiteRow> {\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\treturn 'named' in bound\n\t\t\t\t? this.#statement.iterate(bound.named)\n\t\t\t\t: this.#statement.iterate(...bound.positional)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n}\n","import { DatabaseSync } from 'node:sqlite'\nimport type {\n\tSQLiteDatabaseInterface,\n\tSQLiteDatabaseOptions,\n\tSQLiteStatementInterface,\n\tSQLiteValue,\n} from './types.js'\nimport { SQLiteError } from './errors.js'\nimport { wrapError } from './helpers.js'\nimport { SQLiteStatement } from './SQLiteStatement.js'\n\n/**\n * A synchronous SQLite database over `node:sqlite`'s `DatabaseSync`.\n *\n * @remarks\n * Created by `createSQLiteDatabase`. It connects lazily (`connect` opens the\n * underlying `DatabaseSync`, idempotent) and every operation routes through a\n * private gate that throws a `CLOSED` `SQLiteError` before `connect` or after\n * `close`. `exec` runs result-less SQL; `prepare` compiles a `SQLiteStatement`;\n * `transaction` wraps a scope in `BEGIN` / `COMMIT`, rolling back on a throw;\n * `pragma` reads (or sets then reads) one PRAGMA value — `name` is trusted\n * internal use only, never untrusted input, since pragma names cannot be bound\n * as parameters. A native fault surfaces as a `SQLiteError` mapped at the\n * boundary.\n */\nexport class SQLiteDatabase implements SQLiteDatabaseInterface {\n\treadonly #path: string\n\treadonly #readonly: boolean | undefined\n\treadonly #timeout: number | undefined\n\treadonly #foreignKeys: boolean | undefined\n\treadonly #bigints: boolean | undefined\n\t#database: DatabaseSync | undefined\n\n\tconstructor(options: SQLiteDatabaseOptions) {\n\t\tthis.#path = options.path ?? ':memory:'\n\t\tthis.#readonly = options.readonly\n\t\tthis.#timeout = options.timeout\n\t\tthis.#foreignKeys = options.foreignKeys\n\t\tthis.#bigints = options.bigints\n\t}\n\n\tget path(): string {\n\t\treturn this.#path\n\t}\n\n\tget connected(): boolean {\n\t\treturn this.#database !== undefined\n\t}\n\n\tconnect(): void {\n\t\tif (this.#database === undefined) {\n\t\t\tthis.#database = new DatabaseSync(this.#path, {\n\t\t\t\treadOnly: this.#readonly,\n\t\t\t\ttimeout: this.#timeout,\n\t\t\t\tenableForeignKeyConstraints: this.#foreignKeys,\n\t\t\t\treadBigInts: this.#bigints,\n\t\t\t})\n\t\t}\n\t}\n\n\tclose(): void {\n\t\tthis.#database?.close()\n\t\tthis.#database = undefined\n\t}\n\n\t/** Close the connection — enables `using db = createSQLiteDatabase(...)`. */\n\t[Symbol.dispose](): void {\n\t\tthis.close()\n\t}\n\n\texec(sql: string): void {\n\t\ttry {\n\t\t\tthis.#require().exec(sql)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\tprepare(sql: string): SQLiteStatementInterface {\n\t\ttry {\n\t\t\treturn new SQLiteStatement(this.#require().prepare(sql))\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\ttransaction<R>(scope: () => R): R {\n\t\tthis.exec('BEGIN')\n\t\ttry {\n\t\t\tconst result = scope()\n\t\t\tthis.exec('COMMIT')\n\t\t\treturn result\n\t\t} catch (error) {\n\t\t\t// A ROLLBACK fault (e.g. the database was closed by the scope) must never\n\t\t\t// mask the scope's own error — the caller needs to see why it failed.\n\t\t\ttry {\n\t\t\t\tthis.exec('ROLLBACK')\n\t\t\t} catch {\n\t\t\t\t// swallowed — the original `error` is what the caller needs to see\n\t\t\t}\n\t\t\tthrow error\n\t\t}\n\t}\n\n\t// Pragmas cannot use bind parameters, so the value is interpolated — safe for\n\t// the trusted internal names this layer is called with.\n\tpragma(name: string, value?: string | number): SQLiteValue | undefined {\n\t\tif (value !== undefined) this.exec('PRAGMA ' + name + ' = ' + value)\n\t\tconst row = this.prepare('PRAGMA ' + name).get()\n\t\treturn row ? Object.values(row)[0] : undefined\n\t}\n\n\t// The single connection gate — every operation requires an open database.\n\t#require(): DatabaseSync {\n\t\tif (this.#database === undefined) {\n\t\t\tthrow new SQLiteError('CLOSED', 'Database is not connected — call connect() first')\n\t\t}\n\t\treturn this.#database\n\t}\n}\n","import type { SQLiteDatabaseInterface, SQLiteDatabaseOptions } from './types.js'\nimport { SQLiteDatabase } from './SQLiteDatabase.js'\n\n/**\n * Create a synchronous SQLite database over `node:sqlite`.\n *\n * @remarks\n * The wrapper connects lazily — call `connect` (or it is required by the first\n * operation, which throws `CLOSED` until then). This is the lower-level native\n * handle a higher-level typed database engine would be built on; here it ships\n * as the standalone, server-native SQLite surface.\n *\n * @param options - The database `path` (a file path, or `':memory:'` by default)\n * @returns A typed {@link SQLiteDatabaseInterface}\n *\n * @example\n * ```ts\n * import { createSQLiteDatabase } from '@src/server'\n *\n * const db = createSQLiteDatabase({ path: ':memory:' })\n * db.connect()\n * db.exec('CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT)')\n * db.prepare('INSERT INTO users VALUES (?, ?)').run(['u1', 'Ada'])\n * db.prepare('SELECT name FROM users WHERE id = ?').get(['u1']) // { name: 'Ada' }\n * ```\n */\nexport function createSQLiteDatabase(options?: SQLiteDatabaseOptions): SQLiteDatabaseInterface {\n\treturn new SQLiteDatabase(options ?? {})\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["#statement","#closed","#require","#stream","#path","#readonly","#timeout","#foreignKeys","#bigints","#database","#require"],"sources":["../../../src/server/constants.ts","../../../src/server/errors.ts","../../../src/server/helpers.ts","../../../src/server/SQLiteStatement.ts","../../../src/server/SQLiteDatabase.ts","../../../src/server/factories.ts"],"sourcesContent":["// The wrapper's numeric SQLite result codes (AGENTS §5 constants file).\n\n/**\n * SQLite result code for a constraint violation (`SQLITE_CONSTRAINT`).\n *\n * @remarks\n * A native `errcode` packs the primary result in its low byte, with extended codes\n * in the high bits (e.g. `SQLITE_CONSTRAINT_UNIQUE`), so the low byte is masked off\n * before comparing. Read only by `wrapError`.\n */\nexport const SQLITE_CONSTRAINT = 19\n\n/**\n * SQLite result code for a locked-database fault (`SQLITE_BUSY`).\n *\n * @remarks\n * A native `errcode` packs the primary result in its low byte, with extended codes\n * in the high bits, so the low byte is masked off before comparing. Read only by\n * `wrapError`.\n */\nexport const SQLITE_BUSY = 5\n","import type { SQLiteErrorCode } from './types.js'\n\n// Errors for the SQLite wrapper. A single `SQLiteError` carries a\n// machine-readable `code` mapped from the native `node:sqlite` fault at the\n// boundary (`wrapError`), so a `catch` branches on `error.code` rather than\n// parsing a message. Mirrors the IndexedDB wrapper's `IndexedDBError`; its three\n// codes are deliberately lean — the wrapper sits right on the raw SQLite surface,\n// where the constraint fault is the one worth naming, `CLOSED` is the\n// wrapper-lifecycle fault, and everything else is `UNKNOWN` (AGENTS §12).\n\n/**\n * An error thrown by the SQLite wrapper.\n *\n * @remarks\n * Carries a {@link SQLiteErrorCode} and an optional `context` record (e.g. the\n * native SQLite `errcode`). Construct it directly for the `CLOSED`\n * wrapper-lifecycle fault; the internal `wrapError` maps a native `node:sqlite`\n * error to the right code at the boundary. Narrow a caught value with\n * {@link isSQLiteError}.\n *\n * @example\n * ```ts\n * try {\n * \tstatement.run({ id: 'u1' })\n * } catch (error) {\n * \tif (isSQLiteError(error) && error.code === 'CONSTRAINT') {\n * \t\t// a UNIQUE / PRIMARY KEY violation\n * \t}\n * }\n * ```\n */\nexport class SQLiteError extends Error {\n\treadonly code: SQLiteErrorCode\n\treadonly context?: Readonly<Record<string, unknown>>\n\n\tconstructor(code: SQLiteErrorCode, message: string, context?: Readonly<Record<string, unknown>>) {\n\t\tsuper(message)\n\t\tthis.name = 'SQLiteError'\n\t\tthis.code = code\n\t\tthis.context = context\n\t}\n}\n\n/**\n * Whether a value is a {@link SQLiteError}.\n *\n * @param value - The value to test\n * @returns `true` when `value` is a `SQLiteError`\n */\nexport function isSQLiteError(value: unknown): value is SQLiteError {\n\treturn value instanceof SQLiteError\n}\n","import type { SQLiteParameters, SQLiteValue } from './types.js'\nimport { isArray, isObject } from '@orkestrel/contract'\nimport { SQLITE_BUSY, SQLITE_CONSTRAINT } from './constants.js'\nimport { SQLiteError } from './errors.js'\n\n// The wrapper's boundary helpers, shared by `SQLiteDatabase` and `SQLiteStatement`:\n// `wrapError` maps a thrown native `node:sqlite` error to a typed `SQLiteError`\n// (the one honest narrowing point — `isObject` + `in`, never `as`, per AGENTS\n// §14), and `bindParameters` normalizes the wrapper's `SQLiteParameters` to the\n// shape a native `StatementSync` call expects (positional spread vs. a single\n// named record). Both are pure.\n\n/**\n * Convert a thrown native `node:sqlite` error into a typed {@link SQLiteError}.\n *\n * @remarks\n * The single boundary mapping for the wrapper. The thrown value arrives as\n * `unknown` and is narrowed with `isObject` + the `in` operator (never `as`, and\n * not `isRecord` — a native `node:sqlite` error is an `Error` instance, so its\n * prototype fails the plain-record test) to read its `errcode` — a numeric SQLite\n * result code whose low byte identifies a constraint violation\n * (`SQLITE_CONSTRAINT`), mapped to code `'CONSTRAINT'`; a locked-database fault\n * (`SQLITE_BUSY`) is mapped to `'BUSY'`; anything else is `'UNKNOWN'`. The\n * original message is preserved and `{ errcode }` carried in `context` when\n * present. An already-typed `SQLiteError` is returned unchanged.\n *\n * @param error - The thrown value to convert\n * @returns The equivalent `SQLiteError`\n */\nexport function wrapError(error: unknown): SQLiteError {\n\tif (error instanceof SQLiteError) return error\n\tconst errcode =\n\t\tisObject(error) && 'errcode' in error && typeof error.errcode === 'number'\n\t\t\t? error.errcode\n\t\t\t: undefined\n\tconst message = error instanceof Error ? error.message : 'Unknown SQLite error'\n\tconst code =\n\t\terrcode !== undefined && (errcode & 0xff) === SQLITE_CONSTRAINT\n\t\t\t? 'CONSTRAINT'\n\t\t\t: errcode !== undefined && (errcode & 0xff) === SQLITE_BUSY\n\t\t\t\t? 'BUSY'\n\t\t\t\t: 'UNKNOWN'\n\treturn new SQLiteError(code, message, errcode !== undefined ? { errcode } : undefined)\n}\n\n/**\n * Normalize {@link SQLiteParameters} to the binding shape a native `StatementSync`\n * call expects.\n *\n * @remarks\n * Positional parameters (an array) bind to `?` placeholders and are spread into\n * the call; named parameters (a record) bind to bare `:name` placeholders and are\n * passed as a single leading object. Returning a discriminated result keeps the\n * `SQLiteStatement` dispatch typed against the native overloads without `as`.\n *\n * @param parameters - The wrapper parameters, or `undefined` for none\n * @returns `{ positional }` for an array (empty when omitted) or `{ named }` for a record\n */\nexport function bindParameters(\n\tparameters?: SQLiteParameters,\n):\n\t| { readonly positional: readonly SQLiteValue[] }\n\t| { readonly named: Readonly<Record<string, SQLiteValue>> } {\n\tif (parameters === undefined) return { positional: [] }\n\tif (isArray<SQLiteValue>(parameters)) return { positional: parameters }\n\treturn { named: parameters }\n}\n","import type { StatementSync } from 'node:sqlite'\nimport type {\n\tSQLiteParameters,\n\tSQLiteRow,\n\tSQLiteRunResult,\n\tSQLiteStatementInterface,\n} from './types.js'\nimport { SQLiteError } from './errors.js'\nimport { bindParameters, wrapError } from './helpers.js'\n\n/**\n * A prepared statement over `node:sqlite`'s `StatementSync` — the only way the\n * wrapper runs SQL.\n *\n * @remarks\n * Created by `database.prepare(sql)`, which threads a liveness check (internal —\n * this constructor's second parameter is not part of the documented surface).\n * Bare named parameters are enabled on construction so a record's keys bind\n * without the SQL prefix character. Each method first gates on that liveness\n * check, throwing a `CLOSED` `SQLiteError` once the owning connection has been\n * closed — a statement prepared on a connection that is later closed and then\n * reconnected stays `CLOSED`; a fresh statement must be prepared on the new\n * connection. Each method then binds the optional parameters (an array spread\n * to `?` placeholders, a record passed as a single named object) and executes\n * synchronously, mapping any native fault to a `SQLiteError` — including a\n * mid-stream fault from `iterate`'s lazy native iterator, stepped inside its own\n * try/catch so a fault on a later row is mapped exactly like an eager one. Row\n * values arrive as the native {@link SQLiteRow} types; the typed layer above\n * (the driver) imposes a precise shape through a contract rather than\n * re-narrowing here (AGENTS §14).\n */\nexport class SQLiteStatement implements SQLiteStatementInterface {\n\treadonly #statement: StatementSync\n\treadonly #closed: () => boolean\n\n\tconstructor(statement: StatementSync, closed: () => boolean) {\n\t\tthis.#statement = statement\n\t\tthis.#closed = closed\n\t\tthis.#statement.setAllowBareNamedParameters(true)\n\t}\n\n\trun(parameters?: SQLiteParameters): SQLiteRunResult {\n\t\tthis.#require()\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\tconst result =\n\t\t\t\t'named' in bound\n\t\t\t\t\t? this.#statement.run(bound.named)\n\t\t\t\t\t: this.#statement.run(...bound.positional)\n\t\t\treturn { changes: Number(result.changes), rowid: Number(result.lastInsertRowid) }\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\tget(parameters?: SQLiteParameters): SQLiteRow | undefined {\n\t\tthis.#require()\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\treturn 'named' in bound\n\t\t\t\t? this.#statement.get(bound.named)\n\t\t\t\t: this.#statement.get(...bound.positional)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\tall(parameters?: SQLiteParameters): readonly SQLiteRow[] {\n\t\tthis.#require()\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\treturn 'named' in bound\n\t\t\t\t? this.#statement.all(bound.named)\n\t\t\t\t: this.#statement.all(...bound.positional)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\titerate(parameters?: SQLiteParameters): IterableIterator<SQLiteRow> {\n\t\tthis.#require()\n\t\tlet native: IterableIterator<SQLiteRow>\n\t\ttry {\n\t\t\tconst bound = bindParameters(parameters)\n\t\t\tnative =\n\t\t\t\t'named' in bound\n\t\t\t\t\t? this.#statement.iterate(bound.named)\n\t\t\t\t\t: this.#statement.iterate(...bound.positional)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t\treturn this.#stream(native)\n\t}\n\n\t// The single liveness gate — every operation requires the owning connection\n\t// to still be open (mirrors SQLiteDatabase#require).\n\t#require(): void {\n\t\tif (this.#closed()) {\n\t\t\tthrow new SQLiteError(\n\t\t\t\t'CLOSED',\n\t\t\t\t'Statement is closed — its connection was closed; prepare a new statement',\n\t\t\t)\n\t\t}\n\t}\n\n\t// Pulls from the native lazy iterator one step at a time, each step inside\n\t// its own try/catch — a mid-stream native fault (e.g. an out-of-range\n\t// integer on a later row) is mapped to a SQLiteError exactly like an eager\n\t// fault, instead of escaping raw from the caller's for...of.\n\t*#stream(native: IterableIterator<SQLiteRow>): IterableIterator<SQLiteRow> {\n\t\tfor (;;) {\n\t\t\tlet result: IteratorResult<SQLiteRow>\n\t\t\ttry {\n\t\t\t\tresult = native.next()\n\t\t\t} catch (error) {\n\t\t\t\tthrow wrapError(error)\n\t\t\t}\n\t\t\tif (result.done === true) return\n\t\t\tyield result.value\n\t\t}\n\t}\n}\n","import { DatabaseSync } from 'node:sqlite'\nimport type {\n\tSQLiteDatabaseInterface,\n\tSQLiteDatabaseOptions,\n\tSQLiteStatementInterface,\n\tSQLiteValue,\n} from './types.js'\nimport { isPromiseLike } from '@orkestrel/contract'\nimport { SQLiteError } from './errors.js'\nimport { wrapError } from './helpers.js'\nimport { SQLiteStatement } from './SQLiteStatement.js'\n\n/**\n * A synchronous SQLite database over `node:sqlite`'s `DatabaseSync`.\n *\n * @remarks\n * Created by `createSQLiteDatabase`. It connects lazily (`connect` opens the\n * underlying `DatabaseSync`, idempotent) and every operation routes through a\n * private gate that throws a `CLOSED` `SQLiteError` before `connect` or after\n * `close`. `exec` runs result-less SQL; `prepare` compiles a `SQLiteStatement`;\n * `transaction` wraps a scope in `BEGIN` / `COMMIT`, rolling back on a throw;\n * `begin` / `commit` / `rollback` expose those same primitives directly for a\n * long-lived or externally-driven transaction; `pragma` reads (or sets then\n * reads) one PRAGMA value — `name` is trusted\n * internal use only, never untrusted input, since pragma names cannot be bound\n * as parameters. `transacting` reports whether a transaction is currently open\n * (node:sqlite's `isTransaction`), `false` when not connected. A native fault\n * surfaces as a `SQLiteError` mapped at the boundary.\n */\nexport class SQLiteDatabase implements SQLiteDatabaseInterface {\n\treadonly #path: string\n\treadonly #readonly: boolean | undefined\n\treadonly #timeout: number | undefined\n\treadonly #foreignKeys: boolean | undefined\n\treadonly #bigints: boolean | undefined\n\t#database: DatabaseSync | undefined\n\n\tconstructor(options: SQLiteDatabaseOptions) {\n\t\tthis.#path = options.path ?? ':memory:'\n\t\tthis.#readonly = options.readonly\n\t\tthis.#timeout = options.timeout\n\t\tthis.#foreignKeys = options.foreignKeys\n\t\tthis.#bigints = options.bigints\n\t}\n\n\tget path(): string {\n\t\treturn this.#path\n\t}\n\n\tget connected(): boolean {\n\t\treturn this.#database !== undefined\n\t}\n\n\tget transacting(): boolean {\n\t\treturn this.#database?.isTransaction ?? false\n\t}\n\n\tconnect(): void {\n\t\tif (this.#database === undefined) {\n\t\t\tthis.#database = new DatabaseSync(this.#path, {\n\t\t\t\treadOnly: this.#readonly,\n\t\t\t\ttimeout: this.#timeout,\n\t\t\t\tenableForeignKeyConstraints: this.#foreignKeys,\n\t\t\t\treadBigInts: this.#bigints,\n\t\t\t})\n\t\t}\n\t}\n\n\tclose(): void {\n\t\tthis.#database?.close()\n\t\tthis.#database = undefined\n\t}\n\n\t/** Close the connection — enables `using db = createSQLiteDatabase(...)`. */\n\t[Symbol.dispose](): void {\n\t\tthis.close()\n\t}\n\n\texec(sql: string): void {\n\t\ttry {\n\t\t\tthis.#require().exec(sql)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\tprepare(sql: string): SQLiteStatementInterface {\n\t\ttry {\n\t\t\tconst database = this.#require()\n\t\t\t// Capture this specific connection instance — a later `close()` clears\n\t\t\t// `#database`, and a subsequent `connect()` creates a NEW instance, so\n\t\t\t// identity comparison (not just \"is a connection open\") keeps a statement\n\t\t\t// prepared on the OLD connection permanently CLOSED after reconnect.\n\t\t\treturn new SQLiteStatement(database.prepare(sql), () => this.#database !== database)\n\t\t} catch (error) {\n\t\t\tthrow wrapError(error)\n\t\t}\n\t}\n\n\ttransaction<R>(scope: () => R): R {\n\t\tthis.begin()\n\t\tlet result: R\n\t\ttry {\n\t\t\tresult = scope()\n\t\t} catch (error) {\n\t\t\t// A ROLLBACK fault (e.g. the database was closed by the scope) must never\n\t\t\t// mask the scope's own error — the caller needs to see why it failed.\n\t\t\ttry {\n\t\t\t\tthis.rollback()\n\t\t\t} catch {\n\t\t\t\t// swallowed — the original `error` is what the caller needs to see\n\t\t\t}\n\t\t\tthrow error\n\t\t}\n\t\tif (isPromiseLike(result)) {\n\t\t\t// An async scope returns before its awaited work runs, so committing here\n\t\t\t// would commit prematurely — roll back and reject instead of silently\n\t\t\t// racing the caller's still-pending work.\n\t\t\ttry {\n\t\t\t\tthis.rollback()\n\t\t\t} catch {\n\t\t\t\t// swallowed — the guard error below is what the caller needs to see\n\t\t\t}\n\t\t\tthrow new SQLiteError(\n\t\t\t\t'UNKNOWN',\n\t\t\t\t'transaction(scope) requires a synchronous scope — an async or Promise-returning scope cannot commit or roll back before its awaited work runs; use begin() / commit() / rollback() directly for a transaction that spans async caller code',\n\t\t\t)\n\t\t}\n\t\tthis.commit()\n\t\treturn result\n\t}\n\n\tbegin(): void {\n\t\tthis.exec('BEGIN')\n\t}\n\n\tcommit(): void {\n\t\tthis.exec('COMMIT')\n\t}\n\n\trollback(): void {\n\t\tthis.exec('ROLLBACK')\n\t}\n\n\t// Pragmas cannot use bind parameters, so the value is interpolated — safe for\n\t// the trusted internal names this layer is called with.\n\tpragma(name: string, value?: string | number): SQLiteValue | undefined {\n\t\tif (value !== undefined) this.exec('PRAGMA ' + name + ' = ' + value)\n\t\tconst row = this.prepare('PRAGMA ' + name).get()\n\t\treturn row ? Object.values(row)[0] : undefined\n\t}\n\n\t// The single connection gate — every operation requires an open database.\n\t#require(): DatabaseSync {\n\t\tif (this.#database === undefined) {\n\t\t\tthrow new SQLiteError('CLOSED', 'Database is not connected — call connect() first')\n\t\t}\n\t\treturn this.#database\n\t}\n}\n","import type { SQLiteDatabaseInterface, SQLiteDatabaseOptions } from './types.js'\nimport { SQLiteDatabase } from './SQLiteDatabase.js'\n\n/**\n * Create a synchronous SQLite database over `node:sqlite`.\n *\n * @remarks\n * The wrapper connects lazily — call `connect` (or it is required by the first\n * operation, which throws `CLOSED` until then). This is the lower-level native\n * handle a higher-level typed database engine would be built on; here it ships\n * as the standalone, server-native SQLite surface.\n *\n * @param options - The database `path` (a file path, or `':memory:'` by default)\n * @returns A typed {@link SQLiteDatabaseInterface}\n *\n * @example\n * ```ts\n * import { createSQLiteDatabase } from '@orkestrel/sqlite'\n *\n * const db = createSQLiteDatabase({ path: ':memory:' })\n * db.connect()\n * db.exec('CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT)')\n * db.prepare('INSERT INTO users VALUES (?, ?)').run(['u1', 'Ada'])\n * db.prepare('SELECT name FROM users WHERE id = ?').get(['u1']) // { name: 'Ada' }\n * ```\n */\nexport function createSQLiteDatabase(options?: SQLiteDatabaseOptions): SQLiteDatabaseInterface {\n\treturn new SQLiteDatabase(options ?? {})\n}\n"],"mappings":"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"}

package/dist/src/server/index.d.cts

@@ -0,0 +1,316 @@
+import { StatementSync } from 'node:sqlite';
+
+/**
+ * Normalize {@link SQLiteParameters} to the binding shape a native `StatementSync`
+ * call expects.
+ *
+ * @remarks
+ * Positional parameters (an array) bind to `?` placeholders and are spread into
+ * the call; named parameters (a record) bind to bare `:name` placeholders and are
+ * passed as a single leading object. Returning a discriminated result keeps the
+ * `SQLiteStatement` dispatch typed against the native overloads without `as`.
+ *
+ * @param parameters - The wrapper parameters, or `undefined` for none
+ * @returns `{ positional }` for an array (empty when omitted) or `{ named }` for a record
+ */
+export declare function bindParameters(parameters?: SQLiteParameters): {
+    readonly positional: readonly SQLiteValue[];
+} | {
+    readonly named: Readonly<Record<string, SQLiteValue>>;
+};
+
+/**
+ * Create a synchronous SQLite database over `node:sqlite`.
+ *
+ * @remarks
+ * The wrapper connects lazily — call `connect` (or it is required by the first
+ * operation, which throws `CLOSED` until then). This is the lower-level native
+ * handle a higher-level typed database engine would be built on; here it ships
+ * as the standalone, server-native SQLite surface.
+ *
+ * @param options - The database `path` (a file path, or `':memory:'` by default)
+ * @returns A typed {@link SQLiteDatabaseInterface}
+ *
+ * @example
+ * ```ts
+ * import { createSQLiteDatabase } from '@orkestrel/sqlite'
+ *
+ * const db = createSQLiteDatabase({ path: ':memory:' })
+ * db.connect()
+ * db.exec('CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT)')
+ * db.prepare('INSERT INTO users VALUES (?, ?)').run(['u1', 'Ada'])
+ * db.prepare('SELECT name FROM users WHERE id = ?').get(['u1']) // { name: 'Ada' }
+ * ```
+ */
+export declare function createSQLiteDatabase(options?: SQLiteDatabaseOptions): SQLiteDatabaseInterface;
+
+/**
+ * Whether a value is a {@link SQLiteError}.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is a `SQLiteError`
+ */
+export declare function isSQLiteError(value: unknown): value is SQLiteError;
+
+/**
+ * SQLite result code for a locked-database fault (`SQLITE_BUSY`).
+ *
+ * @remarks
+ * A native `errcode` packs the primary result in its low byte, with extended codes
+ * in the high bits, so the low byte is masked off before comparing. Read only by
+ * `wrapError`.
+ */
+export declare const SQLITE_BUSY = 5;
+
+/**
+ * SQLite result code for a constraint violation (`SQLITE_CONSTRAINT`).
+ *
+ * @remarks
+ * A native `errcode` packs the primary result in its low byte, with extended codes
+ * in the high bits (e.g. `SQLITE_CONSTRAINT_UNIQUE`), so the low byte is masked off
+ * before comparing. Read only by `wrapError`.
+ */
+export declare const SQLITE_CONSTRAINT = 19;
+
+/**
+ * A synchronous SQLite database over `node:sqlite`'s `DatabaseSync`.
+ *
+ * @remarks
+ * Created by `createSQLiteDatabase`. It connects lazily (`connect` opens the
+ * underlying `DatabaseSync`, idempotent) and every operation routes through a
+ * private gate that throws a `CLOSED` `SQLiteError` before `connect` or after
+ * `close`. `exec` runs result-less SQL; `prepare` compiles a `SQLiteStatement`;
+ * `transaction` wraps a scope in `BEGIN` / `COMMIT`, rolling back on a throw;
+ * `begin` / `commit` / `rollback` expose those same primitives directly for a
+ * long-lived or externally-driven transaction; `pragma` reads (or sets then
+ * reads) one PRAGMA value — `name` is trusted
+ * internal use only, never untrusted input, since pragma names cannot be bound
+ * as parameters. `transacting` reports whether a transaction is currently open
+ * (node:sqlite's `isTransaction`), `false` when not connected. A native fault
+ * surfaces as a `SQLiteError` mapped at the boundary.
+ */
+export declare class SQLiteDatabase implements SQLiteDatabaseInterface {
+    #private;
+    constructor(options: SQLiteDatabaseOptions);
+    get path(): string;
+    get connected(): boolean;
+    get transacting(): boolean;
+    connect(): void;
+    close(): void;
+    /** Close the connection — enables `using db = createSQLiteDatabase(...)`. */
+    [Symbol.dispose](): void;
+    exec(sql: string): void;
+    prepare(sql: string): SQLiteStatementInterface;
+    transaction<R>(scope: () => R): R;
+    begin(): void;
+    commit(): void;
+    rollback(): void;
+    pragma(name: string, value?: string | number): SQLiteValue | undefined;
+}
+
+/**
+ * A synchronous SQLite database over `node:sqlite`'s `DatabaseSync` — a lean,
+ * typed, zero-dependency layer exposing prepared statements, transactions, and
+ * pragmas. Synchronous because `node:sqlite` is; the SQLite *driver* (Chunk 3)
+ * adapts it to the async `DriverInterface`.
+ *
+ * @remarks
+ * Connects lazily — `connect` opens the underlying `DatabaseSync` (idempotent),
+ * and every operation requires an open connection, throwing a `CLOSED`
+ * {@link SQLiteError} before `connect` or after `close`. `exec` runs SQL with no
+ * results (DDL, pragmas); `prepare` compiles a {@link SQLiteStatementInterface};
+ * `transaction` runs a scope between `BEGIN` and `COMMIT`, rolling back on a
+ * throw; `pragma` reads (or sets then reads) a single PRAGMA value — `name` is
+ * trusted internal use only, never untrusted input, since pragma names cannot
+ * be bound as parameters. `transacting` reports whether a transaction is
+ * currently open on this connection — node:sqlite's `isTransaction` (wraps
+ * `sqlite3_get_autocommit()`); `false` when not connected. `begin` / `commit` /
+ * `rollback` are the same `BEGIN` / `COMMIT` / `ROLLBACK` primitives
+ * `transaction` composes internally, exposed directly for a long-lived or
+ * externally-driven transaction that a single synchronous scope cannot
+ * express — `transaction(scope)` remains the right tool whenever the whole
+ * transaction fits in one synchronous scope. `[Symbol.dispose]` closes the
+ * connection (same as `close`), enabling `using` to release it
+ * deterministically at the end of a block.
+ */
+export declare interface SQLiteDatabaseInterface {
+    readonly path: string;
+    readonly connected: boolean;
+    readonly transacting: boolean;
+    connect(): void;
+    close(): void;
+    exec(sql: string): void;
+    prepare(sql: string): SQLiteStatementInterface;
+    transaction<R>(scope: () => R): R;
+    /**
+     * Open a transaction (`BEGIN`). Throws the native fault — including a
+     * nested `BEGIN` while one is already open — as a {@link SQLiteError}; a
+     * caller composing its own transaction alongside others should branch on
+     * {@link SQLiteDatabaseInterface.transacting} first rather than catch this
+     * (see the Practices section in `guides/src/sqlite.md`).
+     */
+    begin(): void;
+    /** Commit the currently open transaction (`COMMIT`); throws the native fault as a {@link SQLiteError} when none is open. */
+    commit(): void;
+    /** Roll back the currently open transaction (`ROLLBACK`); throws the native fault as a {@link SQLiteError} when none is open. */
+    rollback(): void;
+    pragma(name: string, value?: string | number): SQLiteValue | undefined;
+    [Symbol.dispose](): void;
+}
+
+/**
+ * Options for `createSQLiteDatabase`.
+ *
+ * @remarks
+ * `path` is the database file path, or the special name `':memory:'` for an
+ * in-memory database (the default when omitted). `readonly` opens the
+ * connection read-only (native `readOnly`) — an absent file fails to open
+ * rather than being created. `timeout` is the busy-timeout in milliseconds
+ * (native `timeout`) — how long SQLite retries a locked database before
+ * failing with a `BUSY` {@link SQLiteError}; defaults to `0` (fail
+ * immediately) when omitted. `foreignKeys` enables foreign-key constraint
+ * enforcement (native `enableForeignKeyConstraints`); `node:sqlite` defaults
+ * this to `true` when omitted. `bigints` reads `INTEGER` columns back as
+ * `bigint` (native `readBigInts`) — writes already accept `bigint` regardless
+ * of this option, so a stored integer beyond `Number.MAX_SAFE_INTEGER` throws
+ * on read unless `bigints` is enabled; enabling it returns EVERY integer
+ * column as `bigint`, not just out-of-range ones, closing that read/write
+ * asymmetry at the cost of `bigint` values for ordinary small integers too.
+ */
+export declare interface SQLiteDatabaseOptions {
+    readonly path?: string;
+    readonly readonly?: boolean;
+    readonly timeout?: number;
+    readonly foreignKeys?: boolean;
+    readonly bigints?: boolean;
+}
+
+/**
+ * An error thrown by the SQLite wrapper.
+ *
+ * @remarks
+ * Carries a {@link SQLiteErrorCode} and an optional `context` record (e.g. the
+ * native SQLite `errcode`). Construct it directly for the `CLOSED`
+ * wrapper-lifecycle fault; the internal `wrapError` maps a native `node:sqlite`
+ * error to the right code at the boundary. Narrow a caught value with
+ * {@link isSQLiteError}.
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	statement.run({ id: 'u1' })
+ * } catch (error) {
+ * 	if (isSQLiteError(error) && error.code === 'CONSTRAINT') {
+ * 		// a UNIQUE / PRIMARY KEY violation
+ * 	}
+ * }
+ * ```
+ */
+export declare class SQLiteError extends Error {
+    readonly code: SQLiteErrorCode;
+    readonly context?: Readonly<Record<string, unknown>>;
+    constructor(code: SQLiteErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/**
+ * A machine-readable {@link SQLiteError} code.
+ *
+ * @remarks
+ * `'BUSY'` is retryable — it means a locked database was still held by another
+ * connection when the `timeout` (see {@link SQLiteDatabaseOptions}) elapsed; a
+ * caller may retry the operation, typically after backing off briefly.
+ */
+export declare type SQLiteErrorCode = 'CLOSED' | 'CONSTRAINT' | 'BUSY' | 'UNKNOWN';
+
+/**
+ * Bind parameters for a prepared statement — positional (an array, bound to `?`)
+ * or named (a record, bound to bare `:name` placeholders).
+ */
+export declare type SQLiteParameters = readonly SQLiteValue[] | Readonly<Record<string, SQLiteValue>>;
+
+/** A result row — a record of column name to {@link SQLiteValue}. */
+export declare type SQLiteRow = Record<string, SQLiteValue>;
+
+/** The outcome of a non-query statement (`INSERT` / `UPDATE` / `DELETE` / DDL). */
+export declare interface SQLiteRunResult {
+    readonly changes: number;
+    readonly rowid: number;
+}
+
+/**
+ * A prepared statement over `node:sqlite`'s `StatementSync` — the only way the
+ * wrapper runs SQL.
+ *
+ * @remarks
+ * Created by `database.prepare(sql)`, which threads a liveness check (internal —
+ * this constructor's second parameter is not part of the documented surface).
+ * Bare named parameters are enabled on construction so a record's keys bind
+ * without the SQL prefix character. Each method first gates on that liveness
+ * check, throwing a `CLOSED` `SQLiteError` once the owning connection has been
+ * closed — a statement prepared on a connection that is later closed and then
+ * reconnected stays `CLOSED`; a fresh statement must be prepared on the new
+ * connection. Each method then binds the optional parameters (an array spread
+ * to `?` placeholders, a record passed as a single named object) and executes
+ * synchronously, mapping any native fault to a `SQLiteError` — including a
+ * mid-stream fault from `iterate`'s lazy native iterator, stepped inside its own
+ * try/catch so a fault on a later row is mapped exactly like an eager one. Row
+ * values arrive as the native {@link SQLiteRow} types; the typed layer above
+ * (the driver) imposes a precise shape through a contract rather than
+ * re-narrowing here (AGENTS §14).
+ */
+export declare class SQLiteStatement implements SQLiteStatementInterface {
+    #private;
+    constructor(statement: StatementSync, closed: () => boolean);
+    run(parameters?: SQLiteParameters): SQLiteRunResult;
+    get(parameters?: SQLiteParameters): SQLiteRow | undefined;
+    all(parameters?: SQLiteParameters): readonly SQLiteRow[];
+    iterate(parameters?: SQLiteParameters): IterableIterator<SQLiteRow>;
+}
+
+/**
+ * A prepared statement — the only way the wrapper runs SQL (no query DSL; the
+ * core database layer owns querying, exactly as the IndexedDB wrapper does).
+ *
+ * @remarks
+ * Reached through `database.prepare(sql)`. Each method binds the optional
+ * `parameters` (an array spread to positional `?` placeholders, or a record bound
+ * to bare named placeholders) and executes synchronously: `run` for a non-query,
+ * `get` for the first row, `all` for every row, `iterate` for a lazy stream. A
+ * native fault surfaces as a {@link SQLiteError}.
+ */
+export declare interface SQLiteStatementInterface {
+    run(parameters?: SQLiteParameters): SQLiteRunResult;
+    get(parameters?: SQLiteParameters): SQLiteRow | undefined;
+    all(parameters?: SQLiteParameters): readonly SQLiteRow[];
+    iterate(parameters?: SQLiteParameters): IterableIterator<SQLiteRow>;
+}
+
+/**
+ * A value SQLite stores and returns natively — the SQL ↔ JS bridge.
+ *
+ * @remarks
+ * `node:sqlite` maps `NULL` / `INTEGER` / `REAL` / `TEXT` / `BLOB` to exactly
+ * these JS types (integers arrive as `number`, or `bigint` only past 2^53).
+ */
+export declare type SQLiteValue = null | number | bigint | string | Uint8Array;
+
+/**
+ * Convert a thrown native `node:sqlite` error into a typed {@link SQLiteError}.
+ *
+ * @remarks
+ * The single boundary mapping for the wrapper. The thrown value arrives as
+ * `unknown` and is narrowed with `isObject` + the `in` operator (never `as`, and
+ * not `isRecord` — a native `node:sqlite` error is an `Error` instance, so its
+ * prototype fails the plain-record test) to read its `errcode` — a numeric SQLite
+ * result code whose low byte identifies a constraint violation
+ * (`SQLITE_CONSTRAINT`), mapped to code `'CONSTRAINT'`; a locked-database fault
+ * (`SQLITE_BUSY`) is mapped to `'BUSY'`; anything else is `'UNKNOWN'`. The
+ * original message is preserved and `{ errcode }` carried in `context` when
+ * present. An already-typed `SQLiteError` is returned unchanged.
+ *
+ * @param error - The thrown value to convert
+ * @returns The equivalent `SQLiteError`
+ */
+export declare function wrapError(error: unknown): SQLiteError;
+
+export { }