@vertz/db 0.2.14 → 0.2.16

package/dist/index.d.ts

@@ -39,6 +39,19 @@ declare function formatDiagnostic(diag: DiagnosticResult): string;
 */
 declare function explainError(message: string): string;
 /**
+* Query executor — wraps raw SQL execution with error mapping.
+*
+* Takes a query function (from the database driver) and wraps it to:
+* 1. Execute parameterized SQL
+* 2. Map PG errors to typed DbError subclasses
+* 3. Return typed QueryResult
+*/
+interface ExecutorResult<T> {
+	readonly rows: readonly T[];
+	readonly rowCount: number;
+}
+type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<ExecutorResult<T>>;
+/**
 * Database driver interface.
 *
 * Provides a unified interface for different database backends
@@ -56,6 +69,12 @@ interface DbDriver {
 		rowsAffected: number;
 	}>;
 	/**
+	* Execute a callback within a database transaction.
+	* The callback receives a transaction-scoped QueryFn.
+	* Optional — not all drivers support transactions (e.g., D1).
+	*/
+	beginTransaction?<T>(fn: (txQueryFn: QueryFn) => Promise<T>): Promise<T>;
+	/**
 	* Close the database connection.
 	*/
 	close(): Promise<void>;
@@ -94,6 +113,7 @@ interface ColumnBuilder<
 	readonly _meta: TMeta;
 	primary(options?: {
 		generate?: "cuid" | "uuid" | "nanoid";
+		generated?: boolean;
 	}): ColumnBuilder<TType, Omit<TMeta, "primary" | "hasDefault" | "generate"> & {
 		readonly primary: true;
 		readonly hasDefault: true;
@@ -290,28 +310,241 @@ interface TableOptions {
 	relations?: Record<string, RelationDef>;
 	indexes?: IndexDef[];
 }
+/** Operators available for comparable types (number, string, Date, bigint). */
+interface ComparisonOperators<T> {
+	readonly eq?: T;
+	readonly ne?: T;
+	readonly gt?: T;
+	readonly gte?: T;
+	readonly lt?: T;
+	readonly lte?: T;
+	readonly in?: readonly T[];
+	readonly notIn?: readonly T[];
+}
+/** Additional operators for string columns. */
+interface StringOperators {
+	readonly contains?: string;
+	readonly startsWith?: string;
+	readonly endsWith?: string;
+}
+/** The `isNull` operator — only available for nullable columns. */
+interface NullOperator {
+	readonly isNull?: boolean;
+}
+/**
+* Resolves the filter operators for a single column based on its inferred type
+* and nullable metadata.
+*
+* - All types get comparison + in/notIn
+* - String types additionally get contains, startsWith, endsWith
+* - Nullable columns additionally get isNull
+*
+* Uses [T] extends [string] to prevent union distribution -- ensures that a
+* union like 'admin' | 'editor' keeps the full union in each operator slot.
+*/
+type ColumnFilterOperators<
+	TType,
+	TNullable extends boolean
+> = ([TType] extends [string] ? ComparisonOperators<TType> & StringOperators : ComparisonOperators<TType>) & (TNullable extends true ? NullOperator : unknown);
+/** Determine whether a column is nullable from its metadata. */
+type IsNullable<C> = C extends ColumnBuilder<unknown, infer M> ? M extends {
+	readonly nullable: true;
+} ? true : false : false;
+/**
+* FilterType<TColumns> — typed where clause.
+*
+* Each key maps to either:
+* - A direct value (shorthand for `{ eq: value }`)
+* - An object with typed filter operators
+*/
+type FilterType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : InferColumnType<TColumns[K]> | ColumnFilterOperators<InferColumnType<TColumns[K]>, IsNullable<TColumns[K]>> };
+type OrderByType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : "asc" | "desc" };
+/**
+* SelectOption<TColumns> — the `select` field in query options.
+*
+* Either:
+* - `{ not: Annotation | Annotation[] }` — exclude columns by annotation(s)
+* - `{ [column]: true }` — explicitly pick columns
+*
+* The two forms are mutually exclusive, enforced via `never` mapped keys.
+*/
+type SelectOption<TColumns extends ColumnRecord> = ({
+	readonly not: AllAnnotations<TColumns> | readonly AllAnnotations<TColumns>[];
+} & { readonly [K in keyof TColumns]? : never }) | ({ readonly [K in keyof TColumns]? : true } & {
+	readonly not?: never;
+});
+/** Extract selected keys from a select map (keys set to `true`). */
+type SelectedKeys<
+	TColumns extends ColumnRecord,
+	TSelect
+> = { [K in keyof TSelect] : K extends keyof TColumns ? (TSelect[K] extends true ? K : never) : never }[keyof TSelect];
+/**
+* Normalize `not` value to a union of annotation strings.
+* - `'annotation'` → `'annotation'`
+* - `readonly ['a', 'b']` → `'a' | 'b'`
+*/
+type NormalizeAnnotations<T> = T extends readonly (infer F)[] ? F extends string ? F : never : T extends string ? T : never;
+/**
+* SelectNarrow<TColumns, TSelect> — applies a select clause to narrow the result type.
+*
+* - `{ not: 'sensitive' }` → excludes 'sensitive'-annotated AND 'hidden'-annotated columns
+* - `{ not: ['sensitive', 'patchable'] }` → excludes columns with ANY listed annotation + 'hidden'
+* - `{ id: true, name: true }` → picks only id and name
+* - `undefined` → default: excludes 'hidden'-annotated columns ($infer behavior)
+*/
+type SelectNarrow<
+	TColumns extends ColumnRecord,
+	TSelect
+> = TSelect extends {
+	not: infer TNot;
+} ? { [K in ColumnKeysWithoutAnyAnnotation<TColumns, NormalizeAnnotations<TNot> | "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends Record<string, true | undefined> ? { [K in SelectedKeys<TColumns, TSelect> & keyof TColumns] : InferColumnType<TColumns[K]> } : { [K in ColumnKeysWithoutAnyAnnotation<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> };
+/** Relations record — maps relation names to RelationDef. */
+type RelationsRecord = Record<string, RelationDef>;
+/**
+* The shape of include options for a given relations record.
+* Each relation can be:
+* - `true` — include with default fields
+* - An object with `select`, `where`, `orderBy`, `limit` constrained to target table columns
+*/
+type IncludeOption<TRelations extends RelationsRecord> = { [K in keyof TRelations]? : true | (RelationTarget<TRelations[K]> extends TableDef<infer TCols> ? {
+	select?: { [C in keyof TCols]? : true };
+	where?: FilterType<TCols>;
+	orderBy?: OrderByType<TCols>;
+	limit?: number;
+	/** Nested includes — untyped until full model registry is threaded through. */
+	include?: Record<string, unknown>;
+} : never) };
+/** Extract the target table from a RelationDef. */
+type RelationTarget<R> = R extends RelationDef<infer TTarget, "one" | "many"> ? TTarget : never;
+/** Extract the relation type ('one' | 'many') from a RelationDef. */
+type RelationType<R> = R extends RelationDef<TableDef<ColumnRecord>, infer TType> ? TType : never;
+/**
+* Resolve a single included relation.
+* - 'one' relations return a single object
+* - 'many' relations return an array
+* - When a `select` sub-clause is provided, the result is narrowed
+*/
+type ResolveOneInclude<
+	R extends RelationDef,
+	TIncludeValue,
+	_Depth extends readonly unknown[] = []
+> = TIncludeValue extends {
+	select: infer TSubSelect;
+} ? RelationTarget<R> extends TableDef<infer TCols> ? SelectNarrow<TCols, TSubSelect> : never : RelationTarget<R> extends TableDef<infer TCols> ? SelectNarrow<TCols, undefined> : never;
+/**
+* IncludeResolve<TRelations, TInclude, Depth> — resolves all included relations.
+*
+* Depth is tracked using a tuple counter. Default cap = 2.
+*/
+type IncludeResolve<
+	TRelations extends RelationsRecord,
+	TInclude,
+	_Depth extends readonly unknown[] = []
+> = _Depth["length"] extends 3 ? unknown : { [K in keyof TInclude as K extends keyof TRelations ? TInclude[K] extends false | undefined ? never : K : never] : K extends keyof TRelations ? RelationType<TRelations[K]> extends "many" ? ResolveOneInclude<TRelations[K], TInclude[K], _Depth>[] : ResolveOneInclude<TRelations[K], TInclude[K], _Depth> : never };
+/** Query options shape used by FindResult. */
+interface FindOptions<
+	TColumns extends ColumnRecord = ColumnRecord,
+	TRelations extends RelationsRecord = RelationsRecord
+> {
+	select?: SelectOption<TColumns>;
+	include?: IncludeOption<TRelations>;
+	where?: FilterType<TColumns>;
+	orderBy?: OrderByType<TColumns>;
+}
+/**
+* FindResult<TTable, TOptions> — the return type of a typed query.
+*
+* Combines:
+* - SelectNarrow for column selection
+* - IncludeResolve for relation includes
+*
+* TOptions is structurally typed (not constrained to FindOptions) so that
+* literal option objects flow through without widening.
+*/
+type FindResult<
+	TTable extends TableDef<ColumnRecord>,
+	TOptions = unknown,
+	TRelations extends RelationsRecord = RelationsRecord
+> = TTable extends TableDef<infer TColumns> ? SelectNarrow<TColumns, TOptions extends {
+	select: infer S;
+} ? S : undefined> & (TOptions extends {
+	include: infer I;
+} ? IncludeResolve<TRelations, I> : unknown) : never;
+/**
+* InsertInput<TTable> — standalone insert type utility.
+* Makes columns with defaults optional, all others required.
+*/
+type InsertInput<TTable extends TableDef<ColumnRecord>> = TTable["$insert"];
+/**
+* UpdateInput<TTable> — standalone update type utility.
+* All non-PK columns, all optional.
+*/
+type UpdateInput<TTable extends TableDef<ColumnRecord>> = TTable["$update"];
+/** A model entry in the database registry, pairing a table with its relations. */
+interface ModelEntry<
+	TTable extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
+	TRelations extends RelationsRecord = RelationsRecord
+> {
+	readonly table: TTable;
+	readonly relations: TRelations;
+}
 /**
-* Database Adapter Types for @vertz/db
+* Database<TModels> — type that carries the full model registry.
 *
-* Generic adapter interface that abstracts database operations.
-* Implemented by SQLite, D1, and other database adapters.
+* Used as the foundation for typed query methods (implemented in later tickets).
+* Provides type-safe access to table definitions and their relations.
 */
-interface ListOptions {
+interface Database<TModels extends Record<string, ModelEntry> = Record<string, ModelEntry>> {
+	readonly _models: TModels;
+}
+/** A single include entry with optional query constraints. */
+interface AdapterIncludeEntry {
+	select?: Record<string, true>;
 	where?: Record<string, unknown>;
 	orderBy?: Record<string, "asc" | "desc">;
 	limit?: number;
+	include?: Record<string, unknown>;
+}
+/** Include specification: maps relation names to `true` or structured entries. */
+type AdapterIncludeSpec = Record<string, true | AdapterIncludeEntry>;
+/**
+* Resolves the where clause type for a given entry.
+* When TEntry is the default (unparameterized), falls back to Record<string, unknown>.
+*/
+type ResolveWhere<TEntry extends ModelEntry> = TEntry extends ModelEntry<infer TTable> ? TTable extends TableDef<infer TCols> ? [ColumnRecord] extends [TCols] ? Record<string, unknown> : FilterType<TCols> : Record<string, unknown> : Record<string, unknown>;
+/**
+* Resolves the orderBy type for a given entry.
+* When TEntry is the default (unparameterized), falls back to Record<string, 'asc' | 'desc'>.
+*/
+type ResolveOrderBy<TEntry extends ModelEntry> = TEntry extends ModelEntry<infer TTable> ? TTable extends TableDef<infer TCols> ? [ColumnRecord] extends [TCols] ? Record<string, "asc" | "desc"> : OrderByType<TCols> : Record<string, "asc" | "desc"> : Record<string, "asc" | "desc">;
+/**
+* Resolves the include type for a given entry.
+* When TEntry is the default (unparameterized), falls back to AdapterIncludeSpec.
+*/
+type ResolveInclude<TEntry extends ModelEntry> = TEntry extends ModelEntry<TableDef<ColumnRecord>, infer TRels> ? [Record<string, never>] extends [TRels] ? AdapterIncludeSpec : IncludeOption<TRels> : AdapterIncludeSpec;
+interface ListOptions<TEntry extends ModelEntry = ModelEntry> {
+	where?: ResolveWhere<TEntry>;
+	orderBy?: ResolveOrderBy<TEntry>;
+	limit?: number;
 	/** Cursor-based pagination: fetch records after this ID. */
 	after?: string;
-}
-interface EntityDbAdapter {
-	get(id: string): Promise<Record<string, unknown> | null>;
-	list(options?: ListOptions): Promise<{
-		data: Record<string, unknown>[];
+	/** Relation include specification for relation loading. */
+	include?: ResolveInclude<TEntry>;
+}
+/** Options for get-by-id operations. */
+interface GetOptions<TEntry extends ModelEntry = ModelEntry> {
+	/** Relation include specification for relation loading. */
+	include?: ResolveInclude<TEntry>;
+}
+interface EntityDbAdapter<TEntry extends ModelEntry = ModelEntry> {
+	get(id: string, options?: GetOptions<TEntry>): Promise<TEntry["table"]["$response"] | null>;
+	list(options?: ListOptions<TEntry>): Promise<{
+		data: TEntry["table"]["$response"][];
 		total: number;
 	}>;
-	create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-	update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-	delete(id: string): Promise<Record<string, unknown> | null>;
+	create(data: TEntry["table"]["$create_input"]): Promise<TEntry["table"]["$response"]>;
+	update(id: string, data: TEntry["table"]["$update_input"]): Promise<TEntry["table"]["$response"]>;
+	delete(id: string): Promise<TEntry["table"]["$response"] | null>;
 }
 interface D1DatabaseBinding {
 	prepare(sql: string): D1PreparedStatement;
@@ -641,201 +874,6 @@ declare function toReadError(error: unknown, query?: string): ReadError;
 */
 declare function toWriteError(error: unknown, query?: string): WriteError;
 /**
-* Query executor — wraps raw SQL execution with error mapping.
-*
-* Takes a query function (from the database driver) and wraps it to:
-* 1. Execute parameterized SQL
-* 2. Map PG errors to typed DbError subclasses
-* 3. Return typed QueryResult
-*/
-interface ExecutorResult<T> {
-	readonly rows: readonly T[];
-	readonly rowCount: number;
-}
-type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<ExecutorResult<T>>;
-/** Operators available for comparable types (number, string, Date, bigint). */
-interface ComparisonOperators<T> {
-	readonly eq?: T;
-	readonly ne?: T;
-	readonly gt?: T;
-	readonly gte?: T;
-	readonly lt?: T;
-	readonly lte?: T;
-	readonly in?: readonly T[];
-	readonly notIn?: readonly T[];
-}
-/** Additional operators for string columns. */
-interface StringOperators {
-	readonly contains?: string;
-	readonly startsWith?: string;
-	readonly endsWith?: string;
-}
-/** The `isNull` operator — only available for nullable columns. */
-interface NullOperator {
-	readonly isNull?: boolean;
-}
-/**
-* Resolves the filter operators for a single column based on its inferred type
-* and nullable metadata.
-*
-* - All types get comparison + in/notIn
-* - String types additionally get contains, startsWith, endsWith
-* - Nullable columns additionally get isNull
-*
-* Uses [T] extends [string] to prevent union distribution -- ensures that a
-* union like 'admin' | 'editor' keeps the full union in each operator slot.
-*/
-type ColumnFilterOperators<
-	TType,
-	TNullable extends boolean
-> = ([TType] extends [string] ? ComparisonOperators<TType> & StringOperators : ComparisonOperators<TType>) & (TNullable extends true ? NullOperator : unknown);
-/** Determine whether a column is nullable from its metadata. */
-type IsNullable<C> = C extends ColumnBuilder<unknown, infer M> ? M extends {
-	readonly nullable: true;
-} ? true : false : false;
-/**
-* FilterType<TColumns> — typed where clause.
-*
-* Each key maps to either:
-* - A direct value (shorthand for `{ eq: value }`)
-* - An object with typed filter operators
-*/
-type FilterType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : InferColumnType<TColumns[K]> | ColumnFilterOperators<InferColumnType<TColumns[K]>, IsNullable<TColumns[K]>> };
-type OrderByType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : "asc" | "desc" };
-/**
-* SelectOption<TColumns> — the `select` field in query options.
-*
-* Either:
-* - `{ not: Annotation | Annotation[] }` — exclude columns by annotation(s)
-* - `{ [column]: true }` — explicitly pick columns
-*
-* The two forms are mutually exclusive, enforced via `never` mapped keys.
-*/
-type SelectOption<TColumns extends ColumnRecord> = ({
-	readonly not: AllAnnotations<TColumns> | readonly AllAnnotations<TColumns>[];
-} & { readonly [K in keyof TColumns]? : never }) | ({ readonly [K in keyof TColumns]? : true } & {
-	readonly not?: never;
-});
-/** Extract selected keys from a select map (keys set to `true`). */
-type SelectedKeys<
-	TColumns extends ColumnRecord,
-	TSelect
-> = { [K in keyof TSelect] : K extends keyof TColumns ? (TSelect[K] extends true ? K : never) : never }[keyof TSelect];
-/**
-* Normalize `not` value to a union of annotation strings.
-* - `'annotation'` → `'annotation'`
-* - `readonly ['a', 'b']` → `'a' | 'b'`
-*/
-type NormalizeAnnotations<T> = T extends readonly (infer F)[] ? F extends string ? F : never : T extends string ? T : never;
-/**
-* SelectNarrow<TColumns, TSelect> — applies a select clause to narrow the result type.
-*
-* - `{ not: 'sensitive' }` → excludes 'sensitive'-annotated AND 'hidden'-annotated columns
-* - `{ not: ['sensitive', 'patchable'] }` → excludes columns with ANY listed annotation + 'hidden'
-* - `{ id: true, name: true }` → picks only id and name
-* - `undefined` → default: excludes 'hidden'-annotated columns ($infer behavior)
-*/
-type SelectNarrow<
-	TColumns extends ColumnRecord,
-	TSelect
-> = TSelect extends {
-	not: infer TNot;
-} ? { [K in ColumnKeysWithoutAnyAnnotation<TColumns, NormalizeAnnotations<TNot> | "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends Record<string, true | undefined> ? { [K in SelectedKeys<TColumns, TSelect> & keyof TColumns] : InferColumnType<TColumns[K]> } : { [K in ColumnKeysWithoutAnyAnnotation<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> };
-/** Relations record — maps relation names to RelationDef. */
-type RelationsRecord = Record<string, RelationDef>;
-/**
-* The shape of include options for a given relations record.
-* Each relation can be:
-* - `true` — include with default fields
-* - An object with optional `select` clause for narrowing
-*/
-type IncludeOption<TRelations extends RelationsRecord> = { [K in keyof TRelations]? : true | {
-	select?: Record<string, true>;
-} };
-/** Extract the target table from a RelationDef. */
-type RelationTarget<R> = R extends RelationDef<infer TTarget, "one" | "many"> ? TTarget : never;
-/** Extract the relation type ('one' | 'many') from a RelationDef. */
-type RelationType<R> = R extends RelationDef<TableDef<ColumnRecord>, infer TType> ? TType : never;
-/**
-* Resolve a single included relation.
-* - 'one' relations return a single object
-* - 'many' relations return an array
-* - When a `select` sub-clause is provided, the result is narrowed
-*/
-type ResolveOneInclude<
-	R extends RelationDef,
-	TIncludeValue,
-	_Depth extends readonly unknown[] = []
-> = TIncludeValue extends {
-	select: infer TSubSelect;
-} ? RelationTarget<R> extends TableDef<infer TCols> ? SelectNarrow<TCols, TSubSelect> : never : RelationTarget<R> extends TableDef<infer TCols> ? SelectNarrow<TCols, undefined> : never;
-/**
-* IncludeResolve<TRelations, TInclude, Depth> — resolves all included relations.
-*
-* Depth is tracked using a tuple counter. Default cap = 2.
-*/
-type IncludeResolve<
-	TRelations extends RelationsRecord,
-	TInclude,
-	_Depth extends readonly unknown[] = []
-> = _Depth["length"] extends 3 ? unknown : { [K in keyof TInclude as K extends keyof TRelations ? TInclude[K] extends false | undefined ? never : K : never] : K extends keyof TRelations ? RelationType<TRelations[K]> extends "many" ? ResolveOneInclude<TRelations[K], TInclude[K], _Depth>[] : ResolveOneInclude<TRelations[K], TInclude[K], _Depth> : never };
-/** Query options shape used by FindResult. */
-interface FindOptions<
-	TColumns extends ColumnRecord = ColumnRecord,
-	TRelations extends RelationsRecord = RelationsRecord
-> {
-	select?: SelectOption<TColumns>;
-	include?: IncludeOption<TRelations>;
-	where?: FilterType<TColumns>;
-	orderBy?: OrderByType<TColumns>;
-}
-/**
-* FindResult<TTable, TOptions> — the return type of a typed query.
-*
-* Combines:
-* - SelectNarrow for column selection
-* - IncludeResolve for relation includes
-*
-* TOptions is structurally typed (not constrained to FindOptions) so that
-* literal option objects flow through without widening.
-*/
-type FindResult<
-	TTable extends TableDef<ColumnRecord>,
-	TOptions = unknown,
-	TRelations extends RelationsRecord = RelationsRecord
-> = TTable extends TableDef<infer TColumns> ? SelectNarrow<TColumns, TOptions extends {
-	select: infer S;
-} ? S : undefined> & (TOptions extends {
-	include: infer I;
-} ? IncludeResolve<TRelations, I> : unknown) : never;
-/**
-* InsertInput<TTable> — standalone insert type utility.
-* Makes columns with defaults optional, all others required.
-*/
-type InsertInput<TTable extends TableDef<ColumnRecord>> = TTable["$insert"];
-/**
-* UpdateInput<TTable> — standalone update type utility.
-* All non-PK columns, all optional.
-*/
-type UpdateInput<TTable extends TableDef<ColumnRecord>> = TTable["$update"];
-/** A model entry in the database registry, pairing a table with its relations. */
-interface ModelEntry<
-	TTable extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
-	TRelations extends RelationsRecord = RelationsRecord
-> {
-	readonly table: TTable;
-	readonly relations: TRelations;
-}
-/**
-* Database<TModels> — type that carries the full model registry.
-*
-* Used as the foundation for typed query methods (implemented in later tickets).
-* Provides type-safe access to table definitions and their relations.
-*/
-interface Database<TModels extends Record<string, ModelEntry> = Record<string, ModelEntry>> {
-	readonly _models: TModels;
-}
-/**
 * SQL tagged template literal and escape hatch.
 *
 * Provides a safe, composable way to write raw SQL with automatic parameterization.
@@ -1089,9 +1127,26 @@ interface DatabaseInternals<TModels extends Record<string, ModelEntry>> {
 	/** The computed tenant scoping graph. */
 	readonly tenantGraph: TenantGraph;
 }
+/**
+* Scoped client for use within a transaction callback.
+* Provides the same model delegates and raw query as DatabaseClient —
+* all operations execute within a single atomic transaction.
+*
+* Auto-commits on success, auto-rolls-back on error.
+*/
+type TransactionClient<TModels extends Record<string, ModelEntry>> = { readonly [K in keyof TModels] : ModelDelegate<TModels[K]> } & {
+	/** Execute a raw SQL query within the transaction. */
+	query<T = Record<string, unknown>>(fragment: SqlFragment): Promise<Result<QueryResult<T>, ReadError>>;
+};
 type DatabaseClient<TModels extends Record<string, ModelEntry>> = { readonly [K in keyof TModels] : ModelDelegate<TModels[K]> } & {
 	/** Execute a raw SQL query via the sql tagged template. */
 	query<T = Record<string, unknown>>(fragment: SqlFragment): Promise<Result<QueryResult<T>, ReadError>>;
+	/**
+	* Execute a callback within a database transaction.
+	* All operations on the `tx` client are atomic — auto-commits on success,
+	* auto-rolls-back if the callback throws.
+	*/
+	transaction<T>(fn: (tx: TransactionClient<TModels>) => Promise<T>): Promise<T>;
 	/** Close all pool connections. */
 	close(): Promise<void>;
 	/** Check if the database connection is healthy. */
@@ -1135,7 +1190,7 @@ declare function createDb<TModels extends Record<string, ModelEntry>>(options: C
 declare function createDatabaseBridgeAdapter<
 	TModels extends Record<string, ModelEntry>,
 	TName extends keyof TModels & string
->(db: DatabaseClient<TModels>, tableName: TName): EntityDbAdapter;
+>(db: DatabaseClient<TModels>, tableName: TName): EntityDbAdapter<TModels[TName]>;
 interface SqliteAdapterOptions<T extends ColumnRecord> {
 	/** The table schema definition */
 	schema: TableDef<T>;
@@ -1655,4 +1710,4 @@ type StrictKeys<
 	TAllowed extends string,
 	TTable extends string
 > = TRecord extends Record<string, unknown> ? { [K in keyof TRecord] : K extends TAllowed ? TRecord[K] : InvalidColumn<K & string, TTable> } : TRecord;
-export { validateIndexes, toWriteError, toReadError, resolveErrorCode, reset, push, parsePgError, parseMigrationName, migrateStatus, migrateDev, migrateDeploy, generateId, formatDiagnostic, explainError, diagnoseError, detectSchemaDrift, defineAnnotations, defaultSqliteDialect, defaultPostgresDialect, dbErrorToHttpError, d, createSqliteDriver2 as createSqliteDriver, createSqliteAdapter, createSnapshot, createRegistry, createPostgresDriver, createEnumRegistry, createDb, createDatabaseBridgeAdapter, createD1Driver, createD1Adapter, computeTenantGraph, baseline, WriteError, VarcharMeta, ValidateKeys, UpdateInput, UniqueConstraintErrorOptions, UniqueConstraintError, TenantGraph, TableDef, StrictKeys, SqliteDialect, SqliteAdapterOptions, SelectOption, SelectNarrow, SchemaSnapshot, SchemaLike, ResetResult, ResetOptions, RenameSuggestion, RelationDef, RegisteredEnum, ReadError, QueryResult, PushResult, PushOptions, PostgresDriver, PostgresDialect, PoolConfig, PgErrorInput, PgCodeToName, OrderByType, NotNullErrorOptions, NotNullError, NotFoundError, ModelSchemas, ModelOptions, ModelEntry, ModelDelegate, ModelDef, MixedSelectError, MigrationQueryFn, MigrationInfo, MigrationFile, MigrationError2 as MigrationError, MigrateStatusResult, MigrateStatusOptions, MigrateDevResult, MigrateDevOptions, MigrateDeployResult, MigrateDeployOptions, ListOptions, JsonbValidator, InvalidRelation, InvalidFilterType, InvalidColumn, InsertInput, InferColumnType, IndexType, IndexOptions, IndexDef, IncludeResolve, IncludeOption, HttpErrorResponse, FormatMeta, ForeignKeyErrorOptions, ForeignKeyError, FindResult, FindOptions, FilterType, EnumMeta, EntityDbAdapter, DriftEntry, Dialect, DiagnosticResult, DecimalMeta, DbQueryError, DbNotFoundError, DbErrorJson, DbErrorCodeValue, DbErrorCodeName, DbErrorCode, DbErrorBase, DbError, DbDriver, DbConstraintError, DbConnectionError, DatabaseInternals, DatabaseClient, Database, D1PreparedStatement, D1DatabaseBinding, D1AdapterOptions, CreateDbOptions, ConnectionPoolExhaustedError, ConnectionError, ColumnTypeMeta, ColumnMetadata, ColumnBuilder, CodeChange, CheckConstraintErrorOptions, CheckConstraintError, BaselineResult, BaselineOptions };
+export { validateIndexes, toWriteError, toReadError, resolveErrorCode, reset, push, parsePgError, parseMigrationName, migrateStatus, migrateDev, migrateDeploy, generateId, formatDiagnostic, explainError, diagnoseError, detectSchemaDrift, defineAnnotations, defaultSqliteDialect, defaultPostgresDialect, dbErrorToHttpError, d, createSqliteDriver2 as createSqliteDriver, createSqliteAdapter, createSnapshot, createRegistry, createPostgresDriver, createEnumRegistry, createDb, createDatabaseBridgeAdapter, createD1Driver, createD1Adapter, computeTenantGraph, baseline, WriteError, VarcharMeta, ValidateKeys, UpdateInput, UniqueConstraintErrorOptions, UniqueConstraintError, TransactionClient, TenantGraph, TableDef, StrictKeys, SqliteDialect, SqliteAdapterOptions, SelectOption, SelectNarrow, SchemaSnapshot, SchemaLike, ResetResult, ResetOptions, RenameSuggestion, RelationDef, RegisteredEnum, ReadError, QueryResult, PushResult, PushOptions, PostgresDriver, PostgresDialect, PoolConfig, PgErrorInput, PgCodeToName, OrderByType, NotNullErrorOptions, NotNullError, NotFoundError, ModelSchemas, ModelOptions, ModelEntry, ModelDelegate, ModelDef, MixedSelectError, MigrationQueryFn, MigrationInfo, MigrationFile, MigrationError2 as MigrationError, MigrateStatusResult, MigrateStatusOptions, MigrateDevResult, MigrateDevOptions, MigrateDeployResult, MigrateDeployOptions, ListOptions, JsonbValidator, InvalidRelation, InvalidFilterType, InvalidColumn, InsertInput, InferColumnType, IndexType, IndexOptions, IndexDef, IncludeResolve, IncludeOption, HttpErrorResponse, GetOptions, FormatMeta, ForeignKeyErrorOptions, ForeignKeyError, FindResult, FindOptions, FilterType, EnumMeta, EntityDbAdapter, DriftEntry, Dialect, DiagnosticResult, DecimalMeta, DbQueryError, DbNotFoundError, DbErrorJson, DbErrorCodeValue, DbErrorCodeName, DbErrorCode, DbErrorBase, DbError, DbDriver, DbConstraintError, DbConnectionError, DatabaseInternals, DatabaseClient, Database, D1PreparedStatement, D1DatabaseBinding, D1AdapterOptions, CreateDbOptions, ConnectionPoolExhaustedError, ConnectionError, ColumnTypeMeta, ColumnMetadata, ColumnBuilder, CodeChange, CheckConstraintErrorOptions, CheckConstraintError, BaselineResult, BaselineOptions, AdapterIncludeSpec, AdapterIncludeEntry };