@orkestrel/sqlite 0.0.1 → 0.0.2

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

@@ -1,7 +1,316 @@
-export type * from './types.js';
-export * from './constants.js';
-export * from './errors.js';
-export * from './helpers.js';
-export * from './factories.js';
-export * from './SQLiteDatabase.js';
-export * from './SQLiteStatement.js';
+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 { }

package/dist/src/server/index.js

@@ -0,0 +1,339 @@
+import { isArray, isObject, isPromiseLike } from "@orkestrel/contract";
+import { DatabaseSync } from "node:sqlite";
+//#region src/server/constants.ts
+/**
+* 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`.
+*/
+var SQLITE_CONSTRAINT = 19;
+/**
+* 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`.
+*/
+var SQLITE_BUSY = 5;
+//#endregion
+//#region src/server/errors.ts
+/**
+* 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
+* 	}
+* }
+* ```
+*/
+var SQLiteError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "SQLiteError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Whether a value is a {@link SQLiteError}.
+*
+* @param value - The value to test
+* @returns `true` when `value` is a `SQLiteError`
+*/
+function isSQLiteError(value) {
+	return value instanceof SQLiteError;
+}
+//#endregion
+//#region src/server/helpers.ts
+/**
+* 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`
+*/
+function wrapError(error) {
+	if (error instanceof SQLiteError) return error;
+	const errcode = isObject(error) && "errcode" in error && typeof error.errcode === "number" ? error.errcode : void 0;
+	const message = error instanceof Error ? error.message : "Unknown SQLite error";
+	return new SQLiteError(errcode !== void 0 && (errcode & 255) === 19 ? "CONSTRAINT" : errcode !== void 0 && (errcode & 255) === 5 ? "BUSY" : "UNKNOWN", message, errcode !== void 0 ? { errcode } : void 0);
+}
+/**
+* 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
+*/
+function bindParameters(parameters) {
+	if (parameters === void 0) return { positional: [] };
+	if (isArray(parameters)) return { positional: parameters };
+	return { named: parameters };
+}
+//#endregion
+//#region src/server/SQLiteStatement.ts
+/**
+* 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).
+*/
+var SQLiteStatement = class {
+	#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);
+			return {
+				changes: Number(result.changes),
+				rowid: Number(result.lastInsertRowid)
+			};
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	get(parameters) {
+		this.#require();
+		try {
+			const bound = bindParameters(parameters);
+			return "named" in bound ? this.#statement.get(bound.named) : this.#statement.get(...bound.positional);
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	all(parameters) {
+		this.#require();
+		try {
+			const bound = bindParameters(parameters);
+			return "named" in bound ? this.#statement.all(bound.named) : this.#statement.all(...bound.positional);
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	iterate(parameters) {
+		this.#require();
+		let native;
+		try {
+			const bound = bindParameters(parameters);
+			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
+//#region src/server/SQLiteDatabase.ts
+/**
+* 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.
+*/
+var SQLiteDatabase = class {
+	#path;
+	#readonly;
+	#timeout;
+	#foreignKeys;
+	#bigints;
+	#database;
+	constructor(options) {
+		this.#path = options.path ?? ":memory:";
+		this.#readonly = options.readonly;
+		this.#timeout = options.timeout;
+		this.#foreignKeys = options.foreignKeys;
+		this.#bigints = options.bigints;
+	}
+	get path() {
+		return this.#path;
+	}
+	get connected() {
+		return this.#database !== void 0;
+	}
+	get transacting() {
+		return this.#database?.isTransaction ?? false;
+	}
+	connect() {
+		if (this.#database === void 0) this.#database = new DatabaseSync(this.#path, {
+			readOnly: this.#readonly,
+			timeout: this.#timeout,
+			enableForeignKeyConstraints: this.#foreignKeys,
+			readBigInts: this.#bigints
+		});
+	}
+	close() {
+		this.#database?.close();
+		this.#database = void 0;
+	}
+	/** Close the connection — enables `using db = createSQLiteDatabase(...)`. */
+	[Symbol.dispose]() {
+		this.close();
+	}
+	exec(sql) {
+		try {
+			this.#require().exec(sql);
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	prepare(sql) {
+		try {
+			const database = this.#require();
+			return new SQLiteStatement(database.prepare(sql), () => this.#database !== database);
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	transaction(scope) {
+		this.begin();
+		let result;
+		try {
+			result = scope();
+		} catch (error) {
+			try {
+				this.rollback();
+			} catch {}
+			throw error;
+		}
+		if (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);
+		const row = this.prepare("PRAGMA " + name).get();
+		return row ? Object.values(row)[0] : void 0;
+	}
+	#require() {
+		if (this.#database === void 0) throw new SQLiteError("CLOSED", "Database is not connected — call connect() first");
+		return this.#database;
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* 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' }
+* ```
+*/
+function createSQLiteDatabase(options) {
+	return new SQLiteDatabase(options ?? {});
+}
+//#endregion
+export { SQLITE_BUSY, SQLITE_CONSTRAINT, SQLiteDatabase, SQLiteError, SQLiteStatement, bindParameters, createSQLiteDatabase, isSQLiteError, wrapError };
+
+//# sourceMappingURL=index.js.map