@ydbjs/query/dist/index.d.ts

High-level, type-safe YQL query and transaction client for YDB. Supports tagged template syntax, parameter binding, transactions, and statistics.

import type { Abortable } from 'node:events';
import type { Driver } from '@ydbjs/core';
import { Query } from './query.js';
import { UnsafeString } from './yql.js';
export type SQL = <T extends any[] = unknown[], P extends any[] = unknown[]>(strings: string | TemplateStringsArray, ...values: P) => Query<T>;
export type RegisterPrecommitHook = (fn: () => Promise<void> | void) => void;
export type TX = SQL & {
    nodeId: bigint;
    sessionId: string;
    transactionId: string;
    registerPrecommitHook: RegisterPrecommitHook;
};
interface SessionContextCallback<T> {
    (signal: AbortSignal): Promise<T>;
}
interface TransactionExecuteOptions extends Abortable {
    isolation?: 'serializableReadWrite' | 'snapshotReadOnly';
    idempotent?: boolean;
}
interface TransactionContextCallback<T> {
    (tx: TX, signal: AbortSignal): Promise<T>;
}
export interface QueryClient extends SQL, AsyncDisposable {
    do<T = unknown>(fn: SessionContextCallback<T>): Promise<T>;
    do<T = unknown>(options: any, fn: SessionContextCallback<T>): Promise<T>;
    begin<T = unknown>(fn: TransactionContextCallback<T>): Promise<T>;
    begin<T = unknown>(options: TransactionExecuteOptions, fn: TransactionContextCallback<T>): Promise<T>;
    transaction<T = unknown>(fn: TransactionContextCallback<T>): Promise<T>;
    transaction<T = unknown>(options: TransactionExecuteOptions, fn: TransactionContextCallback<T>): Promise<T>;
    /**
     * Create an UnsafeString that represents a DB identifier (table, column).
     * When used in a query, the identifier will be escaped.
     *
     * **WARNING: This function does not offer any protection against SQL injections,
     *            so you must validate any user input beforehand.**
     *
     * @example ```ts
     * const query = sql`SELECT * FROM ${sql.identifier('my-table')}`;
     * // 'SELECT * FROM `my-table`'
     * ```
     */
    identifier(value: string | {
        toString(): string;
    }): UnsafeString;
}
/**
 * Creates a query client for executing YQL queries and managing transactions.
 *
 * @param driver - The YDB driver instance used to communicate with the database.
 * @returns A `QueryClient` object that provides methods for executing queries and managing transactions.
 *
 * @remarks
 * The returned client provides a tagged template function for YQL queries, as well as transactional helpers.
 *
 * @example
 * ```typescript
 * const client = query(driver);
 * const result = await client`SELECT 1;`;
 * ```
 *
 * @example
 * ```typescript
 * await client.transaction(async (yql, signal) => {
 *   const res = await yql`SELECT * FROM users WHERE id = ${userId}`;
 *   // ...
 * });
 * ```
 *
 * @see {@link QueryClient}
 */
export declare function query(driver: Driver): QueryClient;
export {};
//# sourceMappingURL=index.d.ts.map