@danceroutine/tango-orm 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Del Moral Lopez
+
+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,104 @@
+# @danceroutine/tango-orm
+
+`@danceroutine/tango-orm` provides Tango's persistence layer.
+
+The default Tango path is model-first. A Tango model can expose `Model.objects`, the runtime loads database configuration on first use, and most application code stays focused on queries and CRUD flows rather than client wiring.
+
+## Install
+
+```bash
+pnpm add @danceroutine/tango-orm
+```
+
+Install the driver for the dialect you use:
+
+```bash
+pnpm add pg
+# or
+pnpm add better-sqlite3
+```
+
+## What the package does inside Tango
+
+The package is organized around five concerns:
+
+- `runtime`, for Tango-owned config loading and shared DB client lifecycle
+- `manager`, for Django-style `Model.objects` access
+- `connection`, for adapters and concrete DB clients
+- `query`, for composable query state and compilation
+- `transaction`, for explicit units of work
+
+Most applications can stay inside `Model.objects` and `QuerySet`.
+
+## Quick start
+
+```ts
+import { z } from 'zod';
+import '@danceroutine/tango-orm/runtime';
+import { Model, t } from '@danceroutine/tango-schema';
+
+const TodoReadSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    completed: z.coerce.boolean(),
+});
+
+export const TodoModel = Model({
+    namespace: 'app',
+    name: 'Todo',
+    schema: TodoReadSchema.extend({
+        id: t.primaryKey(z.number().int()),
+        title: z.string(),
+        completed: t.default(z.coerce.boolean(), 'false'),
+    }),
+});
+
+const todos = await TodoModel.objects.query().orderBy('-id').fetch(TodoReadSchema);
+```
+
+The side-effect import enables Tango's runtime-backed model augmentation for the process. After that, application code can query through `Model.objects` directly.
+
+## Main building blocks
+
+The root export includes:
+
+- runtime helpers such as `getTangoRuntime`
+- manager contracts such as `ModelManager`
+- connection helpers such as `connectDB`, `AdapterRegistry`, `PostgresAdapter`, and `SqliteAdapter`
+- query primitives such as `QuerySet`, `QBuilder`, `Q`, `QueryCompiler`, `TableMeta`, and `QueryExecutor`
+- `UnitOfWork`
+
+## Import style
+
+For most applications, root imports are the clearest choice:
+
+```ts
+import { Q, QuerySet, UnitOfWork } from '@danceroutine/tango-orm';
+```
+
+If you prefer explicit boundaries, the package also exposes `runtime`, `manager`, `connection`, `query`, and `transaction` subpaths.
+
+## Developer workflow
+
+```bash
+pnpm --filter @danceroutine/tango-orm build
+pnpm --filter @danceroutine/tango-orm typecheck
+pnpm --filter @danceroutine/tango-orm test
+```
+
+The package also has integration coverage for dialect-specific behavior:
+
+```bash
+pnpm --filter @danceroutine/tango-orm test:integration
+```
+
+## Bugs and support
+
+- Documentation: <https://tangowebframework.dev>
+- ORM topic: <https://tangowebframework.dev/topics/orm-and-repositories>
+- Query reference: <https://tangowebframework.dev/reference/orm-query-api>
+- Issue tracker: <https://github.com/danceroutine/tango/issues>
+
+## License
+
+MIT

package/dist/{PostgresAdapter-_X36-mLL.js → PostgresAdapter-C9a1XJRx.js}

@@ -4,26 +4,44 @@ import pg from "pg";
 var PostgresClient = class PostgresClient {
 	static BRAND = "tango.orm.postgres_client";
 	__tangoBrand = PostgresClient.BRAND;
-	static isPostgresClient(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === PostgresClient.BRAND;
-	}
 	constructor(pool, client) {
 		this.pool = pool;
 		this.client = client;
 	}
+	/**
+	* Narrow an unknown value to `PostgresClient`.
+	*/
+	static isPostgresClient(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === PostgresClient.BRAND;
+	}
+	/**
+	* Execute a SQL statement with optional bound parameters.
+	*/
 	async query(sql, params) {
 		const result = await this.client.query(sql, params);
 		return { rows: result.rows };
 	}
+	/**
+	* Begin a database transaction.
+	*/
 	async begin() {
 		await this.client.query("BEGIN");
 	}
+	/**
+	* Commit the active transaction.
+	*/
 	async commit() {
 		await this.client.query("COMMIT");
 	}
+	/**
+	* Roll back the active transaction.
+	*/
 	async rollback() {
 		await this.client.query("ROLLBACK");
 	}
+	/**
+	* Release client resources and close the associated pool.
+	*/
 	async close() {
 		this.client.release();
 		await this.pool.end();
@@ -37,9 +55,6 @@ var PostgresAdapter = class PostgresAdapter {
 	static BRAND = "tango.orm.postgres_adapter";
 	__tangoBrand = PostgresAdapter.BRAND;
 	name = "postgres";
-	static isPostgresAdapter(value) {
-		return typeof value === "object" && value !== null && value.__tangoBrand === PostgresAdapter.BRAND;
-	}
 	/**
 	* Declares capabilities of this database adapter.
 	* Used by the migration runner and query compiler to determine which
@@ -53,6 +68,15 @@ var PostgresAdapter = class PostgresAdapter {
 		concurrentIndex: true,
 		validateForeignKeys: true
 	};
+	/**
+	* Narrow an unknown value to `PostgresAdapter`.
+	*/
+	static isPostgresAdapter(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === PostgresAdapter.BRAND;
+	}
+	/**
+	* Open a Postgres connection pool and return a client-backed DB abstraction.
+	*/
 	async connect(config) {
 		const pool = new Pool({
 			connectionString: config.url,
@@ -70,4 +94,4 @@ var PostgresAdapter = class PostgresAdapter {
 
 //#endregion
 export { PostgresAdapter, PostgresClient };
-//# sourceMappingURL=PostgresAdapter-_X36-mLL.js.map
+//# sourceMappingURL=PostgresAdapter-C9a1XJRx.js.map

package/dist/PostgresAdapter-C9a1XJRx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresAdapter-C9a1XJRx.js","names":["pool: pg.Pool","client: pg.PoolClient","value: unknown","sql: string","params?: readonly unknown[]","value: unknown","config: AdapterConfig"],"sources":["../src/connection/clients/dialects/PostgresClient.ts","../src/connection/adapters/dialects/PostgresAdapter.ts"],"sourcesContent":["import type pg from 'pg';\nimport type { DBClient } from '../DBClient';\n\n/**\n * `DBClient` implementation backed by a PostgreSQL pool client.\n */\nexport class PostgresClient implements DBClient {\n    static readonly BRAND = 'tango.orm.postgres_client' as const;\n    readonly __tangoBrand: typeof PostgresClient.BRAND = PostgresClient.BRAND;\n\n    constructor(\n        private pool: pg.Pool,\n        private client: pg.PoolClient\n    ) {}\n\n    /**\n     * Narrow an unknown value to `PostgresClient`.\n     */\n    static isPostgresClient(value: unknown): value is PostgresClient {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === PostgresClient.BRAND\n        );\n    }\n\n    /**\n     * Execute a SQL statement with optional bound parameters.\n     */\n    async query<T = unknown>(sql: string, params?: readonly unknown[]): Promise<{ rows: T[] }> {\n        const result = await this.client.query(sql, params as unknown[]);\n        return { rows: result.rows as T[] };\n    }\n\n    /**\n     * Begin a database transaction.\n     */\n    async begin(): Promise<void> {\n        await this.client.query('BEGIN');\n    }\n\n    /**\n     * Commit the active transaction.\n     */\n    async commit(): Promise<void> {\n        await this.client.query('COMMIT');\n    }\n\n    /**\n     * Roll back the active transaction.\n     */\n    async rollback(): Promise<void> {\n        await this.client.query('ROLLBACK');\n    }\n\n    /**\n     * Release client resources and close the associated pool.\n     */\n    async close(): Promise<void> {\n        this.client.release();\n        await this.pool.end();\n    }\n}\n","import pg from 'pg';\nimport type { Adapter, AdapterConfig } from '../Adapter';\nimport type { DBClient } from '../../clients/DBClient';\nimport { PostgresClient } from '../../clients/dialects/PostgresClient';\n\nconst { Pool } = pg;\n\n/**\n * Postgres adapter that turns adapter config into a transactional `DBClient`.\n */\nexport class PostgresAdapter implements Adapter {\n    static readonly BRAND = 'tango.orm.postgres_adapter' as const;\n    readonly __tangoBrand: typeof PostgresAdapter.BRAND = PostgresAdapter.BRAND;\n    readonly name = 'postgres';\n    /**\n     * Declares capabilities of this database adapter.\n     * Used by the migration runner and query compiler to determine which\n     * SQL features can be safely used:\n     * - transactionalDDL: Postgres supports DDL inside transactions (safe rollback of schema changes)\n     * - concurrentIndex: Supports CREATE INDEX CONCURRENTLY (non-blocking index builds)\n     * - validateForeignKeys: Supports deferred FK validation via NOT VALID + VALIDATE CONSTRAINT\n     */\n    readonly features = {\n        transactionalDDL: true,\n        concurrentIndex: true,\n        validateForeignKeys: true,\n    };\n\n    /**\n     * Narrow an unknown value to `PostgresAdapter`.\n     */\n    static isPostgresAdapter(value: unknown): value is PostgresAdapter {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === PostgresAdapter.BRAND\n        );\n    }\n\n    /**\n     * Open a Postgres connection pool and return a client-backed DB abstraction.\n     */\n    async connect(config: AdapterConfig): Promise<DBClient> {\n        const pool = new Pool({\n            connectionString: config.url,\n            host: config.host,\n            port: config.port,\n            database: config.database,\n            user: config.user,\n            password: config.password,\n            max: config.maxConnections || 10,\n        });\n\n        const client = await pool.connect();\n        return new PostgresClient(pool, client);\n    }\n}\n"],"mappings":";;;IAMa,iBAAN,MAAM,eAAmC;CAC5C,OAAgB,QAAQ;CACxB,eAAqD,eAAe;CAEpE,YACYA,MACAC,QACV;AAAA,OAFU,OAAA;AAAA,OACA,SAAA;CACR;;;;CAKJ,OAAO,iBAAiBC,OAAyC;AAC7D,gBACW,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB,eAAe;CAE7E;;;;CAKD,MAAM,MAAmBC,KAAaC,QAAqD;EACvF,MAAM,SAAS,MAAM,KAAK,OAAO,MAAM,KAAK,OAAoB;AAChE,SAAO,EAAE,MAAM,OAAO,KAAa;CACtC;;;;CAKD,MAAM,QAAuB;AACzB,QAAM,KAAK,OAAO,MAAM,QAAQ;CACnC;;;;CAKD,MAAM,SAAwB;AAC1B,QAAM,KAAK,OAAO,MAAM,SAAS;CACpC;;;;CAKD,MAAM,WAA0B;AAC5B,QAAM,KAAK,OAAO,MAAM,WAAW;CACtC;;;;CAKD,MAAM,QAAuB;AACzB,OAAK,OAAO,SAAS;AACrB,QAAM,KAAK,KAAK,KAAK;CACxB;AACJ;;;;ACzDD,MAAM,EAAE,MAAM,GAAG;IAKJ,kBAAN,MAAM,gBAAmC;CAC5C,OAAgB,QAAQ;CACxB,eAAsD,gBAAgB;CACtE,OAAgB;;;;;;;;;CAShB,WAAoB;EAChB,kBAAkB;EAClB,iBAAiB;EACjB,qBAAqB;CACxB;;;;CAKD,OAAO,kBAAkBC,OAA0C;AAC/D,gBACW,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB,gBAAgB;CAE9E;;;;CAKD,MAAM,QAAQC,QAA0C;EACpD,MAAM,OAAO,IAAI,KAAK;GAClB,kBAAkB,OAAO;GACzB,MAAM,OAAO;GACb,MAAM,OAAO;GACb,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,UAAU,OAAO;GACjB,KAAK,OAAO,kBAAkB;EACjC;EAED,MAAM,SAAS,MAAM,KAAK,SAAS;AACnC,SAAO,IAAI,eAAe,MAAM;CACnC;AACJ"}

package/dist/PostgresAdapter-CBc1u8eT.js

@@ -0,0 +1,3 @@
+import { PostgresAdapter } from "./PostgresAdapter-C9a1XJRx.js";
+
+export { PostgresAdapter };

package/dist/SqliteAdapter-BJKNxCvS.js

@@ -0,0 +1,3 @@
+import { SqliteAdapter } from "./SqliteAdapter-Dp6VRXmz.js";
+
+export { SqliteAdapter };

package/dist/SqliteAdapter-Dp6VRXmz.js

@@ -0,0 +1,118 @@
+import { createRequire } from "node:module";
+
+//#region src/connection/clients/dialects/SqliteClient.ts
+var SqliteClient = class SqliteClient {
+	static BRAND = "tango.orm.sqlite_client";
+	__tangoBrand = SqliteClient.BRAND;
+	inTransaction = false;
+	constructor(db) {
+		this.db = db;
+	}
+	/**
+	* Narrow an unknown value to `SqliteClient`.
+	*/
+	static isSqliteClient(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === SqliteClient.BRAND;
+	}
+	/**
+	* Execute a SQL statement with optional parameters.
+	*
+	* `SELECT`/`PRAGMA` statements return row data; write statements return
+	* an empty row list.
+	*/
+	async query(sql, params) {
+		const stmt = this.db.prepare(sql);
+		const isPragmaWrite = /^\s*PRAGMA\b/i.test(sql) && /=/.test(sql);
+		const normalizedParams = params?.map((param) => this.normalizeParam(param));
+		if (!isPragmaWrite && stmt.reader) {
+			const rows = normalizedParams ? stmt.all(...normalizedParams) : stmt.all();
+			return { rows };
+		}
+		if (normalizedParams) stmt.run(...normalizedParams);
+else stmt.run();
+		return { rows: [] };
+	}
+	/**
+	* Begin a transaction if one is not already active.
+	*/
+	async begin() {
+		if (!this.inTransaction) {
+			this.db.prepare("BEGIN").run();
+			this.inTransaction = true;
+		}
+	}
+	/**
+	* Commit the active transaction.
+	*/
+	async commit() {
+		if (this.inTransaction) {
+			this.db.prepare("COMMIT").run();
+			this.inTransaction = false;
+		}
+	}
+	/**
+	* Roll back the active transaction.
+	*/
+	async rollback() {
+		if (this.inTransaction) {
+			this.db.prepare("ROLLBACK").run();
+			this.inTransaction = false;
+		}
+	}
+	/**
+	* Close the underlying SQLite handle.
+	*/
+	async close() {
+		this.db.close();
+	}
+	normalizeParam(value) {
+		if (isDateValue(value)) return value.toISOString();
+		if (typeof value === "boolean") return value ? 1 : 0;
+		return value;
+	}
+};
+function isDateValue(value) {
+	return typeof value === "object" && value !== null && typeof value.getTime === "function" && typeof value.toISOString === "function";
+}
+
+//#endregion
+//#region src/connection/adapters/dialects/SqliteAdapter.ts
+var SqliteAdapter = class SqliteAdapter {
+	static BRAND = "tango.orm.sqlite_adapter";
+	__tangoBrand = SqliteAdapter.BRAND;
+	name = "sqlite";
+	features = {
+		transactionalDDL: true,
+		concurrentIndex: false,
+		validateForeignKeys: false
+	};
+	/**
+	* Narrow an unknown value to `SqliteAdapter`.
+	*/
+	static isSqliteAdapter(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === SqliteAdapter.BRAND;
+	}
+	/**
+	* Open a SQLite database and apply baseline pragmas for durability/safety.
+	*/
+	async connect(config = {}) {
+		const Database = this.getDatabaseCtor();
+		const filename = typeof config.filename === "string" && config.filename.length > 0 ? config.filename : ":memory:";
+		const db = new Database(filename);
+		db.pragma("journal_mode = WAL");
+		db.pragma("foreign_keys = ON");
+		return new SqliteClient(db);
+	}
+	getDatabaseCtor() {
+		const require = createRequire(import.meta.url);
+		const moduleValue = require("better-sqlite3");
+		if (typeof moduleValue === "function") return moduleValue;
+		const defaultExport = moduleValue.default;
+		if (typeof defaultExport === "function") return defaultExport;
+		throw new TypeError("Failed to load better-sqlite3 constructor.");
+	}
+};
+
+//#endregion
+export { SqliteAdapter, SqliteClient };
+//# sourceMappingURL=SqliteAdapter-Dp6VRXmz.js.map

package/dist/SqliteAdapter-Dp6VRXmz.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SqliteAdapter-Dp6VRXmz.js","names":["db: Database.Database","value: unknown","sql: string","params?: readonly unknown[]","value: unknown","config: AdapterConfig"],"sources":["../src/connection/clients/dialects/SqliteClient.ts","../src/connection/adapters/dialects/SqliteAdapter.ts"],"sourcesContent":["import type Database from 'better-sqlite3';\nimport type { DBClient } from '../DBClient';\n\n/**\n * `DBClient` implementation backed by a synchronous `better-sqlite3` handle.\n */\nexport class SqliteClient implements DBClient {\n    static readonly BRAND = 'tango.orm.sqlite_client' as const;\n    readonly __tangoBrand: typeof SqliteClient.BRAND = SqliteClient.BRAND;\n    private inTransaction = false;\n\n    constructor(private db: Database.Database) {}\n\n    /**\n     * Narrow an unknown value to `SqliteClient`.\n     */\n    static isSqliteClient(value: unknown): value is SqliteClient {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === SqliteClient.BRAND\n        );\n    }\n\n    /**\n     * Execute a SQL statement with optional parameters.\n     *\n     * `SELECT`/`PRAGMA` statements return row data; write statements return\n     * an empty row list.\n     */\n    async query<T = unknown>(sql: string, params?: readonly unknown[]): Promise<{ rows: T[] }> {\n        const stmt = this.db.prepare(sql);\n        const isPragmaWrite = /^\\s*PRAGMA\\b/i.test(sql) && /=/.test(sql);\n\n        const normalizedParams = params?.map((param) => this.normalizeParam(param));\n\n        if (!isPragmaWrite && stmt.reader) {\n            const rows = normalizedParams ? stmt.all(...(normalizedParams as unknown[])) : stmt.all();\n            return { rows: rows as T[] };\n        }\n\n        if (normalizedParams) {\n            stmt.run(...(normalizedParams as unknown[]));\n        } else {\n            stmt.run();\n        }\n        return { rows: [] };\n    }\n\n    /**\n     * Begin a transaction if one is not already active.\n     */\n    async begin(): Promise<void> {\n        if (!this.inTransaction) {\n            this.db.prepare('BEGIN').run();\n            this.inTransaction = true;\n        }\n    }\n\n    /**\n     * Commit the active transaction.\n     */\n    async commit(): Promise<void> {\n        if (this.inTransaction) {\n            this.db.prepare('COMMIT').run();\n            this.inTransaction = false;\n        }\n    }\n\n    /**\n     * Roll back the active transaction.\n     */\n    async rollback(): Promise<void> {\n        if (this.inTransaction) {\n            this.db.prepare('ROLLBACK').run();\n            this.inTransaction = false;\n        }\n    }\n\n    /**\n     * Close the underlying SQLite handle.\n     */\n    async close(): Promise<void> {\n        this.db.close();\n    }\n\n    private normalizeParam(value: unknown): unknown {\n        if (isDateValue(value)) {\n            return value.toISOString();\n        }\n        if (typeof value === 'boolean') {\n            return value ? 1 : 0;\n        }\n        return value;\n    }\n}\n\nfunction isDateValue(value: unknown): value is Date {\n    return (\n        typeof value === 'object' &&\n        value !== null &&\n        typeof (value as { getTime?: unknown }).getTime === 'function' &&\n        typeof (value as { toISOString?: unknown }).toISOString === 'function'\n    );\n}\n","import { createRequire } from 'node:module';\nimport type { Database as BetterSqliteDatabase } from 'better-sqlite3';\nimport type { Adapter, AdapterConfig } from '../Adapter';\nimport type { DBClient } from '../../clients/DBClient';\nimport { SqliteClient } from '../../clients/dialects/SqliteClient';\n\ntype BetterSqliteCtor = new (filename: string, options?: unknown) => BetterSqliteDatabase;\n\n/**\n * SQLite adapter that creates a `better-sqlite3` backed `DBClient`.\n */\nexport class SqliteAdapter implements Adapter {\n    static readonly BRAND = 'tango.orm.sqlite_adapter' as const;\n    readonly __tangoBrand: typeof SqliteAdapter.BRAND = SqliteAdapter.BRAND;\n    readonly name = 'sqlite';\n    readonly features = {\n        transactionalDDL: true,\n        concurrentIndex: false,\n        validateForeignKeys: false,\n    };\n\n    /**\n     * Narrow an unknown value to `SqliteAdapter`.\n     */\n    static isSqliteAdapter(value: unknown): value is SqliteAdapter {\n        return (\n            typeof value === 'object' &&\n            value !== null &&\n            (value as { __tangoBrand?: unknown }).__tangoBrand === SqliteAdapter.BRAND\n        );\n    }\n\n    /**\n     * Open a SQLite database and apply baseline pragmas for durability/safety.\n     */\n    async connect(config: AdapterConfig = {}): Promise<DBClient> {\n        const Database = this.getDatabaseCtor();\n        const filename =\n            typeof config.filename === 'string' && config.filename.length > 0 ? config.filename : ':memory:';\n        const db = new Database(filename);\n        db.pragma('journal_mode = WAL');\n        db.pragma('foreign_keys = ON');\n\n        return new SqliteClient(db);\n    }\n\n    private getDatabaseCtor(): BetterSqliteCtor {\n        const require = createRequire(import.meta.url);\n        const moduleValue = require('better-sqlite3') as unknown;\n        if (typeof moduleValue === 'function') {\n            return moduleValue as BetterSqliteCtor;\n        }\n\n        const defaultExport = (moduleValue as { default?: unknown }).default;\n        if (typeof defaultExport === 'function') {\n            return defaultExport as BetterSqliteCtor;\n        }\n\n        throw new TypeError('Failed to load better-sqlite3 constructor.');\n    }\n}\n"],"mappings":";;;IAMa,eAAN,MAAM,aAAiC;CAC1C,OAAgB,QAAQ;CACxB,eAAmD,aAAa;CAChE,gBAAwB;CAExB,YAAoBA,IAAuB;AAAA,OAAvB,KAAA;CAAyB;;;;CAK7C,OAAO,eAAeC,OAAuC;AACzD,gBACW,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB,aAAa;CAE3E;;;;;;;CAQD,MAAM,MAAmBC,KAAaC,QAAqD;EACvF,MAAM,OAAO,KAAK,GAAG,QAAQ,IAAI;EACjC,MAAM,gBAAgB,gBAAgB,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI;EAEhE,MAAM,mBAAmB,QAAQ,IAAI,CAAC,UAAU,KAAK,eAAe,MAAM,CAAC;AAE3E,OAAK,iBAAiB,KAAK,QAAQ;GAC/B,MAAM,OAAO,mBAAmB,KAAK,IAAI,GAAI,iBAA+B,GAAG,KAAK,KAAK;AACzF,UAAO,EAAQ,KAAa;EAC/B;AAED,MAAI,iBACA,MAAK,IAAI,GAAI,iBAA+B;IAE5C,MAAK,KAAK;AAEd,SAAO,EAAE,MAAM,CAAE,EAAE;CACtB;;;;CAKD,MAAM,QAAuB;AACzB,OAAK,KAAK,eAAe;AACrB,QAAK,GAAG,QAAQ,QAAQ,CAAC,KAAK;AAC9B,QAAK,gBAAgB;EACxB;CACJ;;;;CAKD,MAAM,SAAwB;AAC1B,MAAI,KAAK,eAAe;AACpB,QAAK,GAAG,QAAQ,SAAS,CAAC,KAAK;AAC/B,QAAK,gBAAgB;EACxB;CACJ;;;;CAKD,MAAM,WAA0B;AAC5B,MAAI,KAAK,eAAe;AACpB,QAAK,GAAG,QAAQ,WAAW,CAAC,KAAK;AACjC,QAAK,gBAAgB;EACxB;CACJ;;;;CAKD,MAAM,QAAuB;AACzB,OAAK,GAAG,OAAO;CAClB;CAED,eAAuBF,OAAyB;AAC5C,MAAI,YAAY,MAAM,CAClB,QAAO,MAAM,aAAa;AAE9B,aAAW,UAAU,UACjB,QAAO,QAAQ,IAAI;AAEvB,SAAO;CACV;AACJ;AAED,SAAS,YAAYA,OAA+B;AAChD,eACW,UAAU,YACjB,UAAU,eACF,MAAgC,YAAY,qBAC5C,MAAoC,gBAAgB;AAEnE;;;;IC7FY,gBAAN,MAAM,cAAiC;CAC1C,OAAgB,QAAQ;CACxB,eAAoD,cAAc;CAClE,OAAgB;CAChB,WAAoB;EAChB,kBAAkB;EAClB,iBAAiB;EACjB,qBAAqB;CACxB;;;;CAKD,OAAO,gBAAgBG,OAAwC;AAC3D,gBACW,UAAU,YACjB,UAAU,QACT,MAAqC,iBAAiB,cAAc;CAE5E;;;;CAKD,MAAM,QAAQC,SAAwB,CAAE,GAAqB;EACzD,MAAM,WAAW,KAAK,iBAAiB;EACvC,MAAM,kBACK,OAAO,aAAa,YAAY,OAAO,SAAS,SAAS,IAAI,OAAO,WAAW;EAC1F,MAAM,KAAK,IAAI,SAAS;AACxB,KAAG,OAAO,qBAAqB;AAC/B,KAAG,OAAO,oBAAoB;AAE9B,SAAO,IAAI,aAAa;CAC3B;CAED,kBAA4C;EACxC,MAAM,UAAU,cAAc,OAAO,KAAK,IAAI;EAC9C,MAAM,cAAc,QAAQ,iBAAiB;AAC7C,aAAW,gBAAgB,WACvB,QAAO;EAGX,MAAM,gBAAiB,YAAsC;AAC7D,aAAW,kBAAkB,WACzB,QAAO;AAGX,QAAM,IAAI,UAAU;CACvB;AACJ"}

package/dist/connection/adapters/Adapter.d.ts

@@ -1,4 +1,7 @@
 import type { DBClient } from '../clients/DBClient';
+/**
+ * Connection options shared by built-in DB adapters.
+ */
 export interface AdapterConfig {
     url?: string;
     host?: string;
@@ -9,9 +12,15 @@ export interface AdapterConfig {
     filename?: string;
     maxConnections?: number;
 }
+/**
+ * Runtime adapter contract for establishing `DBClient` connections.
+ */
 export interface Adapter {
+    /** Stable adapter name used in configuration and registry lookup. */
     name: string;
+    /** Open a database connection and return a client abstraction. */
     connect(config: AdapterConfig): Promise<DBClient>;
+    /** SQL capability flags used by migrations/query orchestration. */
     features: {
         transactionalDDL: boolean;
         concurrentIndex: boolean;

package/dist/connection/adapters/AdapterRegistry.d.ts

@@ -1,17 +1,44 @@
 import type { Adapter, AdapterConfig } from './Adapter';
 import type { DBClient } from '../clients/DBClient';
+/**
+ * Runtime registry for database adapters.
+ *
+ * Use a custom instance when tests or applications need explicit control
+ * over supported adapters; use `getDefaultRegistry()` for the built-in set.
+ */
 export declare class AdapterRegistry {
     static readonly BRAND: "tango.orm.adapter_registry";
-    readonly __tangoBrand: typeof AdapterRegistry.BRAND;
     private static defaultRegistryInstance;
+    readonly __tangoBrand: typeof AdapterRegistry.BRAND;
     private adapters;
+    /**
+     * Narrow an unknown value to `AdapterRegistry`.
+     */
     static isAdapterRegistry(value: unknown): value is AdapterRegistry;
+    /**
+     * Return a lazily-initialized registry preloaded with built-in adapters.
+     */
     static getDefaultRegistry(): Promise<AdapterRegistry>;
+    /**
+     * Register an adapter under its declared `name`.
+     */
     register(adapter: Adapter): this;
+    /**
+     * Resolve an adapter by name, or throw a descriptive error.
+     */
     get(name: string): Adapter;
+    /**
+     * Check whether an adapter has been registered.
+     */
     has(name: string): boolean;
 }
+/**
+ * Connect to a database by adapter name using the provided (or default) registry.
+ */
 export declare function connectDB(config: AdapterConfig & {
     adapter: string;
 }, registry?: AdapterRegistry): Promise<DBClient>;
+/**
+ * Convenience helper that exposes the singleton default adapter registry.
+ */
 export declare function getDefaultAdapterRegistry(): Promise<AdapterRegistry>;

package/dist/connection/adapters/dialects/PostgresAdapter.d.ts

@@ -1,10 +1,12 @@
 import type { Adapter, AdapterConfig } from '../Adapter';
 import type { DBClient } from '../../clients/DBClient';
+/**
+ * Postgres adapter that turns adapter config into a transactional `DBClient`.
+ */
 export declare class PostgresAdapter implements Adapter {
     static readonly BRAND: "tango.orm.postgres_adapter";
     readonly __tangoBrand: typeof PostgresAdapter.BRAND;
     readonly name = "postgres";
-    static isPostgresAdapter(value: unknown): value is PostgresAdapter;
     /**
      * Declares capabilities of this database adapter.
      * Used by the migration runner and query compiler to determine which
@@ -18,5 +20,12 @@ export declare class PostgresAdapter implements Adapter {
         concurrentIndex: boolean;
         validateForeignKeys: boolean;
     };
+    /**
+     * Narrow an unknown value to `PostgresAdapter`.
+     */
+    static isPostgresAdapter(value: unknown): value is PostgresAdapter;
+    /**
+     * Open a Postgres connection pool and return a client-backed DB abstraction.
+     */
     connect(config: AdapterConfig): Promise<DBClient>;
 }

package/dist/connection/adapters/dialects/SqliteAdapter.d.ts

@@ -1,5 +1,8 @@
 import type { Adapter, AdapterConfig } from '../Adapter';
 import type { DBClient } from '../../clients/DBClient';
+/**
+ * SQLite adapter that creates a `better-sqlite3` backed `DBClient`.
+ */
 export declare class SqliteAdapter implements Adapter {
     static readonly BRAND: "tango.orm.sqlite_adapter";
     readonly __tangoBrand: typeof SqliteAdapter.BRAND;
@@ -9,6 +12,13 @@ export declare class SqliteAdapter implements Adapter {
         concurrentIndex: boolean;
         validateForeignKeys: boolean;
     };
+    /**
+     * Narrow an unknown value to `SqliteAdapter`.
+     */
     static isSqliteAdapter(value: unknown): value is SqliteAdapter;
-    connect(config: AdapterConfig): Promise<DBClient>;
+    /**
+     * Open a SQLite database and apply baseline pragmas for durability/safety.
+     */
+    connect(config?: AdapterConfig): Promise<DBClient>;
+    private getDatabaseCtor;
 }

package/dist/connection/clients/DBClient.d.ts

@@ -1,9 +1,17 @@
+/**
+ * Database client abstraction used by ORM and migrations.
+ */
 export interface DBClient {
+    /** Execute SQL with optional positional parameters. */
     query<T = unknown>(sql: string, params?: readonly unknown[]): Promise<{
         rows: T[];
     }>;
+    /** Begin a transaction. */
     begin(): Promise<void>;
+    /** Commit current transaction. */
     commit(): Promise<void>;
+    /** Roll back current transaction. */
     rollback(): Promise<void>;
+    /** Close underlying connection resources. */
     close(): Promise<void>;
 }

package/dist/connection/clients/dialects/PostgresClient.d.ts

@@ -1,17 +1,38 @@
 import type pg from 'pg';
 import type { DBClient } from '../DBClient';
+/**
+ * `DBClient` implementation backed by a PostgreSQL pool client.
+ */
 export declare class PostgresClient implements DBClient {
     private pool;
     private client;
     static readonly BRAND: "tango.orm.postgres_client";
     readonly __tangoBrand: typeof PostgresClient.BRAND;
-    static isPostgresClient(value: unknown): value is PostgresClient;
     constructor(pool: pg.Pool, client: pg.PoolClient);
+    /**
+     * Narrow an unknown value to `PostgresClient`.
+     */
+    static isPostgresClient(value: unknown): value is PostgresClient;
+    /**
+     * Execute a SQL statement with optional bound parameters.
+     */
     query<T = unknown>(sql: string, params?: readonly unknown[]): Promise<{
         rows: T[];
     }>;
+    /**
+     * Begin a database transaction.
+     */
     begin(): Promise<void>;
+    /**
+     * Commit the active transaction.
+     */
     commit(): Promise<void>;
+    /**
+     * Roll back the active transaction.
+     */
     rollback(): Promise<void>;
+    /**
+     * Release client resources and close the associated pool.
+     */
     close(): Promise<void>;
 }

package/dist/connection/clients/dialects/SqliteClient.d.ts

@@ -1,17 +1,42 @@
 import type Database from 'better-sqlite3';
 import type { DBClient } from '../DBClient';
+/**
+ * `DBClient` implementation backed by a synchronous `better-sqlite3` handle.
+ */
 export declare class SqliteClient implements DBClient {
     private db;
     static readonly BRAND: "tango.orm.sqlite_client";
     readonly __tangoBrand: typeof SqliteClient.BRAND;
     private inTransaction;
-    static isSqliteClient(value: unknown): value is SqliteClient;
     constructor(db: Database.Database);
+    /**
+     * Narrow an unknown value to `SqliteClient`.
+     */
+    static isSqliteClient(value: unknown): value is SqliteClient;
+    /**
+     * Execute a SQL statement with optional parameters.
+     *
+     * `SELECT`/`PRAGMA` statements return row data; write statements return
+     * an empty row list.
+     */
     query<T = unknown>(sql: string, params?: readonly unknown[]): Promise<{
         rows: T[];
     }>;
+    /**
+     * Begin a transaction if one is not already active.
+     */
     begin(): Promise<void>;
+    /**
+     * Commit the active transaction.
+     */
     commit(): Promise<void>;
+    /**
+     * Roll back the active transaction.
+     */
     rollback(): Promise<void>;
+    /**
+     * Close the underlying SQLite handle.
+     */
     close(): Promise<void>;
+    private normalizeParam;
 }

package/dist/connection/index.js

@@ -1,5 +1,5 @@
-import { PostgresAdapter, PostgresClient } from "../PostgresAdapter-_X36-mLL.js";
-import { SqliteAdapter, SqliteClient } from "../SqliteAdapter-J03fEjmr.js";
-import { AdapterRegistry, adapters_exports, clients_exports, connectDB, getDefaultAdapterRegistry } from "../connection-DytAsjC9.js";
+import { PostgresAdapter, PostgresClient } from "../PostgresAdapter-C9a1XJRx.js";
+import { SqliteAdapter, SqliteClient } from "../SqliteAdapter-Dp6VRXmz.js";
+import { AdapterRegistry, adapters_exports, clients_exports, connectDB, getDefaultAdapterRegistry } from "../connection-CVvycXus.js";
 
 export { AdapterRegistry, PostgresAdapter, PostgresClient, SqliteAdapter, SqliteClient, adapters_exports as adapters, clients_exports as clients, connectDB, getDefaultAdapterRegistry };

package/dist/{connection-DytAsjC9.js → connection-CVvycXus.js}

@@ -1,6 +1,6 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { PostgresAdapter, PostgresClient } from "./PostgresAdapter-_X36-mLL.js";
-import { SqliteAdapter, SqliteClient } from "./SqliteAdapter-J03fEjmr.js";
+import { PostgresAdapter, PostgresClient } from "./PostgresAdapter-C9a1XJRx.js";
+import { SqliteAdapter, SqliteClient } from "./SqliteAdapter-Dp6VRXmz.js";
 
 //#region src/connection/adapters/dialects/index.ts
 var dialects_exports$1 = {};
@@ -13,25 +13,37 @@ __export(dialects_exports$1, {
 //#region src/connection/adapters/AdapterRegistry.ts
 var AdapterRegistry = class AdapterRegistry {
 	static BRAND = "tango.orm.adapter_registry";
-	__tangoBrand = AdapterRegistry.BRAND;
 	static defaultRegistryInstance;
+	__tangoBrand = AdapterRegistry.BRAND;
 	adapters = new Map();
+	/**
+	* Narrow an unknown value to `AdapterRegistry`.
+	*/
 	static isAdapterRegistry(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === AdapterRegistry.BRAND;
 	}
+	/**
+	* Return a lazily-initialized registry preloaded with built-in adapters.
+	*/
 	static async getDefaultRegistry() {
 		if (AdapterRegistry.defaultRegistryInstance) return AdapterRegistry.defaultRegistryInstance;
 		AdapterRegistry.defaultRegistryInstance = new AdapterRegistry();
-		const { PostgresAdapter: PostgresAdapter$1 } = await import("./PostgresAdapter-DCF8T4vh.js");
-		const { SqliteAdapter: SqliteAdapter$1 } = await import("./SqliteAdapter-CBnxCznk.js");
+		const { PostgresAdapter: PostgresAdapter$1 } = await import("./PostgresAdapter-CBc1u8eT.js");
+		const { SqliteAdapter: SqliteAdapter$1 } = await import("./SqliteAdapter-BJKNxCvS.js");
 		AdapterRegistry.defaultRegistryInstance.register(new PostgresAdapter$1());
 		AdapterRegistry.defaultRegistryInstance.register(new SqliteAdapter$1());
 		return AdapterRegistry.defaultRegistryInstance;
 	}
+	/**
+	* Register an adapter under its declared `name`.
+	*/
 	register(adapter) {
 		this.adapters.set(adapter.name, adapter);
 		return this;
 	}
+	/**
+	* Resolve an adapter by name, or throw a descriptive error.
+	*/
 	get(name) {
 		const adapter = this.adapters.get(name);
 		if (!adapter) {
@@ -40,6 +52,9 @@ var AdapterRegistry = class AdapterRegistry {
 		}
 		return adapter;
 	}
+	/**
+	* Check whether an adapter has been registered.
+	*/
 	has(name) {
 		return this.adapters.has(name);
 	}
@@ -99,4 +114,4 @@ __export(connection_exports, {
 
 //#endregion
 export { AdapterRegistry, adapters_exports, clients_exports, connectDB, connection_exports, getDefaultAdapterRegistry };
-//# sourceMappingURL=connection-DytAsjC9.js.map
+//# sourceMappingURL=connection-CVvycXus.js.map