import { Registry } from '@juit/pgproxy-types';
import { PGResult } from './result';
import type { PGProvider } from './provider';
/**
 * Options to create a `PGClient`
 *
 * As an alternative to using URLs, a `PGClient` can be instantiated with
 * options passed in this object.
 */
export interface PGClientOptions {
    /** The protocol used to connect to the database (defaults to "psql") */
    readonly protocol?: string;
    /** The PostgreSQL database to connect to */
    readonly database?: string;
    /** The user to authenticate as */
    readonly username?: string;
    /** The password to use for authentication */
    readonly password?: string;
    /** The host to connect to */
    readonly host?: string;
    /** The port to connect to */
    readonly port?: number;
    /** Any additional options to pass to the provider */
    readonly parameters?: Record<string, string | number | boolean>;
}
/** An interface representing a SQL query to a database */
export interface PGQuery {
    /** The SQL query to execute optionally containing placeholders. */
    readonly query: string;
    /** Any parameter replacement for `$x` placeholders. */
    readonly params?: readonly any[];
}
/** An interface for an object that can execute queries on a database */
export interface PGQueryable {
    /**
     * Execute a query on the database
     *
     * @param text - The SQL query to execute optionally containing placeholders.
     * @param params - Any parameter replacement for `$x` placeholders.
     */
    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>;
    /**
     * Execute a query on the database
     *
     * @param query - An object containing the query (both the SQL string and its
     *                related parameters) to execute
     */
    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(query: PGQuery): Promise<PGResult<Row, Tuple>>;
}
/**
 * An interface for an object that can execute queries _and transactions_
 * on a database
 */
export interface PGTransactionable extends PGQueryable {
    /**
     * Start a transaction by issuing a `BEGIN` statement
     *
     * @returns `true` if a transaction was created, or `false` if `begin()` was
     *          already called and a transaction was already started.
     */
    begin(): Promise<boolean>;
    /** Commit a transaction by issuing a `COMMIT` statement */
    commit(): Promise<void>;
    /** Cancel a transaction by issuing a `ROLLBACK` statement */
    rollback(): Promise<void>;
}
/**
 * A connection to a database that can be asynchronously disposed of.
 */
export interface PGConnection extends PGTransactionable, AsyncDisposable {
    /** Forcedly close the underlying connection to the database */
    close(): Promise<void>;
}
/** A consumer for a {@link PGTransactionable} connection */
export type PGConsumer<T> = (connection: PGTransactionable) => T | PromiseLike<T>;
/** The PostgreSQL client */
export interface PGClient extends PGQueryable, AsyncDisposable {
    /** The {@link @juit/pgproxy-types#Registry} used to parse results from PostgreSQL */
    readonly registry: Registry;
    /** The URL used to create this provider, devoid of any credentials */
    readonly url: Readonly<URL>;
    /**
     * Execute a _single_ query on the database.
     *
     * Invoking the `query` method on a {@link (PGClient:interface)} does NOT
     * guarantee that the query will be executed on the same connection, therefore
     * things like _transactions_ will be immediately rolled back after the query.
     *
     * @param text - The SQL query to execute optionally containing placeholders.
     * @param params - Any parameter replacement for `$x` placeholders.
     */
    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(text: string, params?: readonly any[]): Promise<PGResult<Row, Tuple>>;
    /**
     * Execute a _single_ query on the database.
     *
     * Invoking the `query` method on a {@link (PGClient:interface)} does NOT
     * guarantee that the query will be executed on the same connection, therefore
     * things like _transactions_ will be immediately rolled back after the query.
     *
     * @param query - An object containing the query (both the SQL string and its
     *                related parameters) to execute
     */
    query<Row extends Record<string, any> = Record<string, any>, Tuple extends readonly any[] = readonly any[]>(query: PGQuery): Promise<PGResult<Row, Tuple>>;
    /**
     * Connect to the database and return an _async disposable_
     * {@link PGConnection}.
     */
    connect(): Promise<PGConnection>;
    /**
     * Connect to the database to execute a number of different queries.
     *
     * The `consumer` will be passed a {@link PGTransactionable} instance backed
     * by the _same_ connection to the database, therefore transactions can be
     * safely executed in the context of the consumer function itself.
     */
    connect<T>(consumer: PGConsumer<T>): Promise<T>;
    /**
     * Destroy any resource and underlying connection associated with this
     * instance's {@link PGProvider}.
     */
    destroy(): Promise<void>;
}
/** A constructor for {@link (PGClient:interface)} instances */
export interface PGClientConstructor {
    new (url?: string | URL): PGClient;
    new (provider: PGProvider): PGClient;
    new (options: PGClientOptions): PGClient;
}
/**
 * The PostgreSQL client
 */
export declare const PGClient: PGClientConstructor;