import { db } from '@stacksjs/database';
/**
 * Execute a callback within a database transaction.
 *
 * The transaction will automatically commit if the callback succeeds,
 * or rollback if an error is thrown.
 *
 * Every query that belongs to the transaction must execute through the `tx`
 * callback handle. The model executor is a separate execution surface and is
 * not rebound to this handle, so `User.find()` or an instance relation call
 * inside the callback cannot be assumed to observe uncommitted `tx` writes.
 *
 * @example
 * ```ts
 * await transaction(async (tx) => {
 *   await tx.insertInto('users').values({ name: 'Alice' }).execute()
 *   await tx.insertInto('profiles').values({ user_id: 1 }).execute()
 * })
 * ```
 */
export declare function transaction<T>(callback: (tx: TransactionHandle) => Promise<T>, options?: TransactionOptions): Promise<T>;
/**
 * Create a savepoint within a transaction for nested rollback support.
 *
 * @example
 * ```ts
 * await transaction(async (tx) => {
 *   await tx.insertInto('users').values({ name: 'Bob' }).execute()
 *
 *   await savepoint(async (sp) => {
 *     await sp.insertInto('logs').values({ action: 'created' }).execute()
 *     // If this fails, only this savepoint rolls back
 *   })
 * })
 * ```
 */
export declare function savepoint<T>(callback: (sp: TransactionHandle) => Promise<T>): Promise<T>;
/**
 * Wrap a function to automatically run within a transaction when called.
 *
 * @example
 * ```ts
 * const createUserWithProfile = transactional(async (tx, name: string, bio: string) => {
 *   const user = await tx.insertInto('users').values({ name }).returningAll().executeTakeFirst()
 *   await tx.insertInto('profiles').values({ user_id: user.id, bio }).execute()
 *   return user
 * })
 *
 * // Usage - automatically wrapped in transaction
 * const user = await createUserWithProfile('Alice', 'Hello world')
 * ```
 */
export declare function transactional<TArgs extends unknown[], R>(fn: (tx: TransactionHandle, ...args: TArgs) => Promise<R>, options?: TransactionOptions): (...args: TArgs) => Promise<R>;
export declare interface TransactionOptions {
  retries?: number
  isolation?: 'read committed' | 'repeatable read' | 'serializable'
  readOnly?: boolean
  onRollback?: (error: unknown) => void
  afterRollback?: () => void
}
/**
 * Transaction handle. Aliases the project's `db` type so callers get
 * the same fluent query API inside the callback as outside, without
 * the previous untyped `(tx: any)` signature that erased intellisense
 * and let typo'd column names slip through to runtime.
 */
export type TransactionHandle = typeof db;