@orkestrel/sqlite 0.0.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,35 @@
+# @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.
+
+## Install
+
+```sh
+npm install @orkestrel/sqlite
+```
+
+## Requirements
+
+- Node.js >= 24
+- `node:sqlite` (Node's built-in SQLite module)
+- Server-only — no CommonJS/browser split, single Node-native surface
+
+## Status
+
+Pre-release. The public API documented in
+[`guides/src/sqlite.md`](https://github.com/orkestrel/sqlite/blob/main/guides/src/sqlite.md)
+is implemented and covered by tests, but the package has not yet reached a
+stable `1.0` release.
+
+## Package
+
+Published as a single Node-only surface per the `exports` field in
+`package.json` — one `.` entry backed by a CommonJS build of `src/server`
+(required by `node:sqlite`'s CJS-only shape at this Node version).
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

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

@@ -0,0 +1,29 @@
+import type { SQLiteDatabaseInterface, SQLiteDatabaseOptions, SQLiteStatementInterface, SQLiteValue } from './types.js';
+/**
+ * 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;
+ * `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.
+ */
+export declare class SQLiteDatabase implements SQLiteDatabaseInterface {
+    #private;
+    constructor(options: SQLiteDatabaseOptions);
+    get path(): string;
+    get connected(): 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;
+    pragma(name: string, value?: string | number): SQLiteValue | undefined;
+}

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

@@ -0,0 +1,23 @@
+import type { StatementSync } from 'node:sqlite';
+import type { SQLiteParameters, SQLiteRow, SQLiteRunResult, SQLiteStatementInterface } from './types.js';
+/**
+ * A prepared statement over `node:sqlite`'s `StatementSync` — the only way the
+ * 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).
+ */
+export declare class SQLiteStatement implements SQLiteStatementInterface {
+    #private;
+    constructor(statement: StatementSync);
+    run(parameters?: SQLiteParameters): SQLiteRunResult;
+    get(parameters?: SQLiteParameters): SQLiteRow | undefined;
+    all(parameters?: SQLiteParameters): readonly SQLiteRow[];
+    iterate(parameters?: SQLiteParameters): IterableIterator<SQLiteRow>;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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;
+/**
+ * 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;

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

@@ -0,0 +1,34 @@
+import type { SQLiteErrorCode } from './types.js';
+/**
+ * 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>>);
+}
+/**
+ * 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;

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

@@ -0,0 +1,25 @@
+import type { SQLiteDatabaseInterface, SQLiteDatabaseOptions } from './types.js';
+/**
+ * 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 '@src/server'
+ *
+ * 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;

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

@@ -0,0 +1,38 @@
+import type { SQLiteParameters, SQLiteValue } from './types.js';
+import { SQLiteError } from './errors.js';
+/**
+ * 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;
+/**
+ * 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>>;
+};

package/dist/src/server/index.cjs

@@ -0,0 +1,294 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
+let node_sqlite = require("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 = (0, _orkestrel_contract.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 ((0, _orkestrel_contract.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)`. 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).
+*/
+var SQLiteStatement = class {
+	#statement;
+	constructor(statement) {
+		this.#statement = statement;
+		this.#statement.setAllowBareNamedParameters(true);
+	}
+	run(parameters) {
+		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) {
+		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) {
+		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) {
+		try {
+			const bound = bindParameters(parameters);
+			return "named" in bound ? this.#statement.iterate(bound.named) : this.#statement.iterate(...bound.positional);
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+};
+//#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;
+* `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.
+*/
+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;
+	}
+	connect() {
+		if (this.#database === void 0) this.#database = new node_sqlite.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 {
+			return new SQLiteStatement(this.#require().prepare(sql));
+		} catch (error) {
+			throw wrapError(error);
+		}
+	}
+	transaction(scope) {
+		this.exec("BEGIN");
+		try {
+			const result = scope();
+			this.exec("COMMIT");
+			return result;
+		} catch (error) {
+			try {
+				this.exec("ROLLBACK");
+			} catch {}
+			throw error;
+		}
+	}
+	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 '@src/server'
+*
+* 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
+exports.SQLITE_BUSY = SQLITE_BUSY;
+exports.SQLITE_CONSTRAINT = SQLITE_CONSTRAINT;
+exports.SQLiteDatabase = SQLiteDatabase;
+exports.SQLiteError = SQLiteError;
+exports.SQLiteStatement = SQLiteStatement;
+exports.bindParameters = bindParameters;
+exports.createSQLiteDatabase = createSQLiteDatabase;
+exports.isSQLiteError = isSQLiteError;
+exports.wrapError = wrapError;
+
+//# sourceMappingURL=index.cjs.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,7 @@
+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';

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

@@ -0,0 +1,101 @@
+/**
+ * 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 type SQLiteValue = null | number | bigint | string | Uint8Array;
+/** A result row — a record of column name to {@link SQLiteValue}. */
+export type SQLiteRow = Record<string, SQLiteValue>;
+/**
+ * Bind parameters for a prepared statement — positional (an array, bound to `?`)
+ * or named (a record, bound to bare `:name` placeholders).
+ */
+export type SQLiteParameters = readonly SQLiteValue[] | Readonly<Record<string, SQLiteValue>>;
+/** The outcome of a non-query statement (`INSERT` / `UPDATE` / `DELETE` / DDL). */
+export interface SQLiteRunResult {
+    readonly changes: number;
+    readonly rowid: number;
+}
+/**
+ * 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 type SQLiteErrorCode = 'CLOSED' | 'CONSTRAINT' | 'BUSY' | 'UNKNOWN';
+/**
+ * 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 interface SQLiteDatabaseOptions {
+    readonly path?: string;
+    readonly readonly?: boolean;
+    readonly timeout?: number;
+    readonly foreignKeys?: boolean;
+    readonly bigints?: boolean;
+}
+/**
+ * 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 interface SQLiteStatementInterface {
+    run(parameters?: SQLiteParameters): SQLiteRunResult;
+    get(parameters?: SQLiteParameters): SQLiteRow | undefined;
+    all(parameters?: SQLiteParameters): readonly SQLiteRow[];
+    iterate(parameters?: SQLiteParameters): IterableIterator<SQLiteRow>;
+}
+/**
+ * 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. `[Symbol.dispose]` closes the connection (same as
+ * `close`), enabling `using` to release it deterministically at the end of a
+ * block.
+ */
+export interface SQLiteDatabaseInterface {
+    readonly path: string;
+    readonly connected: boolean;
+    connect(): void;
+    close(): void;
+    exec(sql: string): void;
+    prepare(sql: string): SQLiteStatementInterface;
+    transaction<R>(scope: () => R): R;
+    pragma(name: string, value?: string | number): SQLiteValue | undefined;
+    [Symbol.dispose](): void;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "@orkestrel/sqlite",
+	"version": "0.0.1",
+	"description": "A typed, synchronous SQLite wrapper for the @orkestrel line — prepared statements over node:sqlite. Part of the @orkestrel line.",
+	"keywords": [
+		"database",
+		"node",
+		"node:sqlite",
+		"server",
+		"sqlite",
+		"typescript"
+	],
+	"homepage": "https://github.com/orkestrel/sqlite#readme",
+	"bugs": "https://github.com/orkestrel/sqlite/issues",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/orkestrel/sqlite.git"
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"main": "./dist/src/server/index.cjs",
+	"types": "./dist/src/server/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/src/server/index.d.ts",
+			"import": "./dist/src/server/index.cjs",
+			"require": "./dist/src/server/index.cjs",
+			"default": "./dist/src/server/index.cjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"clean": "node -e \"try{require('node:fs').rmSync('dist',{recursive:true,force:true})}catch{}\"",
+		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
+		"tmp:txt": "node -e \"const fs=require('node:fs'),p=require('node:path');function walk(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){const f=p.join(d,e.name);if(e.isDirectory()){walk(f)}else if(!e.name.endsWith('.md')&&!e.name.endsWith('.txt')){const t=f+'.txt';if(!fs.existsSync(t)){fs.renameSync(f,t)}else{console.warn('Skipping '+f+' — target exists: '+t)}}}}try{walk('tmp')}catch(e){if(e.code!=='ENOENT')throw e}\"",
+		"lint": "oxlint --config .oxlintrc.json --fix .",
+		"check": "tsc --noEmit --project tsconfig.json",
+		"check:src": "npm run check:src:server",
+		"check:src:server": "tsc --noEmit -p configs/src/tsconfig.server.json",
+		"format": "oxfmt --config .oxfmtrc.json --write .",
+		"format:check": "oxfmt --config .oxfmtrc.json --check .",
+		"lint:check": "oxlint --config .oxlintrc.json .",
+		"test": "npm run test:src && npm run test:guides",
+		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:server",
+		"test:src:server": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:server",
+		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
+		"build": "npm run clean && npm run build:src",
+		"build:src": "npm run build:src:server",
+		"build:src:server": "vite build --config configs/src/vite.server.config.ts && tsc -p configs/src/tsconfig.server.json",
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run check:src && npm run build && npm test"
+	},
+	"dependencies": {
+		"@orkestrel/contract": "^0.0.1"
+	},
+	"devDependencies": {
+		"@orkestrel/guide": "^0.0.1",
+		"@types/node": "^26.1.1",
+		"oxfmt": "^0.58.0",
+		"oxlint": "^1.73.0",
+		"typescript": "^6.0.3",
+		"vite": "^8.1.4",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=24"
+	}
+}