turbine-orm 0.7.0 → 0.8.0

package/dist/errors.js

@@ -17,6 +17,9 @@ export const TurbineErrorCode = {
     FOREIGN_KEY_VIOLATION: 'TURBINE_E009',
     NOT_NULL_VIOLATION: 'TURBINE_E010',
     CHECK_VIOLATION: 'TURBINE_E011',
+    DEADLOCK_DETECTED: 'TURBINE_E012',
+    SERIALIZATION_FAILURE: 'TURBINE_E013',
+    PIPELINE: 'TURBINE_E014',
 };
 /** Base error class for all Turbine errors */
 export class TurbineError extends Error {
@@ -27,6 +30,47 @@ export class TurbineError extends Error {
         this.code = code;
     }
 }
+let errorMessageMode = 'safe';
+/**
+ * Set the global NotFoundError message mode. Called from the TurbineClient
+ * constructor when `TurbineConfig.errorMessages` is provided.
+ *
+ *   - `'safe'`    (default): the message includes only the keys of the where
+ *     clause (e.g. `where: { id, email }`). Values are redacted.
+ *   - `'verbose'`: the message includes the full JSON-serialized where
+ *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+ */
+export function setErrorMessageMode(mode) {
+    errorMessageMode = mode;
+}
+/** Returns the current NotFoundError message mode. Exported for tests. */
+export function getErrorMessageMode() {
+    return errorMessageMode;
+}
+/**
+ * Render a `where` clause for error messages. In 'safe' mode (the default),
+ * only the keys are shown; values are stripped to avoid leaking PII into logs.
+ * Nested AND/OR/NOT combinators are recursively rendered.
+ */
+function renderWhereForMessage(where, mode) {
+    if (mode === 'verbose') {
+        try {
+            return JSON.stringify(where);
+        }
+        catch {
+            return '[unserializable]';
+        }
+    }
+    // safe mode: keys only
+    if (where === null || where === undefined)
+        return '';
+    if (typeof where !== 'object')
+        return '';
+    const keys = Object.keys(where);
+    if (keys.length === 0)
+        return '{}';
+    return `{ ${keys.join(', ')} }`;
+}
 /**
  * Thrown when a record is not found (findUniqueOrThrow, findFirstOrThrow,
  * update/delete against a non-matching row, etc.)
@@ -36,8 +80,16 @@ export class TurbineError extends Error {
  *   - `new NotFoundError({ table, where, operation, cause, message })`
  *
  * When called with an options object and no explicit `message`, a Prisma-style
- * message is built automatically, e.g.:
+ * message is built automatically. By default, only the where-clause keys are
+ * shown to avoid leaking PII into logs:
+ *   `[turbine] findUniqueOrThrow on "users" found no record matching where: { id }`
+ *
+ * Set `setErrorMessageMode('verbose')` (or pass `errorMessages: 'verbose'` to
+ * the TurbineClient constructor) to include the full where values:
  *   `[turbine] findUniqueOrThrow on "users" found no record matching where: {"id":1}`
+ *
+ * The full `where` object, `table`, and `operation` are always available as
+ * structured properties on the error instance regardless of mode.
  */
 export class NotFoundError extends TurbineError {
     table;
@@ -54,11 +106,11 @@ export class NotFoundError extends TurbineError {
         let message = input.message;
         if (!message) {
             if (operation && table) {
-                const wherePart = where !== undefined ? ` matching where: ${JSON.stringify(where)}` : '';
+                const wherePart = where !== undefined ? ` matching where: ${renderWhereForMessage(where, errorMessageMode)}` : '';
                 message = `[turbine] ${operation} on "${table}" found no record${wherePart}`;
             }
             else if (table) {
-                const wherePart = where !== undefined ? ` matching where ${JSON.stringify(where)}` : '';
+                const wherePart = where !== undefined ? ` matching where ${renderWhereForMessage(where, errorMessageMode)}` : '';
                 message = `[turbine] No record found in "${table}"${wherePart}`;
             }
             else {
@@ -194,6 +246,71 @@ export class NotNullViolationError extends TurbineError {
         this.table = table;
     }
 }
+/**
+ * Thrown when Postgres detects a deadlock (pg code 40P01).
+ *
+ * This error is **retryable** — when caught, callers can safely retry the
+ * transaction (typically with backoff). Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... });
+ * } catch (err) {
+ *   if (err instanceof DeadlockError) {
+ *     // safe to retry
+ *   }
+ * }
+ * ```
+ */
+export class DeadlockError extends TurbineError {
+    /** Marks this error as safe to retry */
+    isRetryable = true;
+    constraint;
+    constructor(opts = {}) {
+        const { constraint, cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const pgMessage = cause?.message;
+            message = pgMessage ? `[turbine] Deadlock detected: ${pgMessage}` : '[turbine] Deadlock detected';
+        }
+        super(TurbineErrorCode.DEADLOCK_DETECTED, message, { cause });
+        this.name = 'DeadlockError';
+        this.constraint = constraint;
+    }
+}
+/**
+ * Thrown when a Serializable transaction fails due to a serialization
+ * conflict (pg code 40001 — `could not serialize access due to ...`).
+ *
+ * This error is **retryable** — by Postgres documentation, the recommended
+ * response is to re-run the entire transaction. Catch it explicitly:
+ *
+ * ```ts
+ * try {
+ *   await db.$transaction(async (tx) => { ... }, { isolationLevel: 'Serializable' });
+ * } catch (err) {
+ *   if (err instanceof SerializationFailureError) {
+ *     // safe to retry the whole transaction
+ *   }
+ * }
+ * ```
+ */
+export class SerializationFailureError extends TurbineError {
+    /** Marks this error as safe to retry */
+    isRetryable = true;
+    constructor(opts = {}) {
+        const { cause } = opts;
+        let message = opts.message;
+        if (!message) {
+            const pgMessage = cause?.message;
+            message = pgMessage
+                ? `[turbine] Serializable transaction conflict: ${pgMessage}`
+                : '[turbine] Serializable transaction conflict';
+        }
+        super(TurbineErrorCode.SERIALIZATION_FAILURE, message, { cause });
+        this.name = 'SerializationFailureError';
+    }
+}
 /** Thrown when a CHECK constraint is violated (pg code 23514) */
 export class CheckConstraintError extends TurbineError {
     constraint;
@@ -214,6 +331,46 @@ export class CheckConstraintError extends TurbineError {
         this.table = table;
     }
 }
+/**
+ * Thrown when a non-transactional pipeline has partial failures.
+ *
+ * In non-transactional mode (`{ transactional: false }`), each query executes
+ * independently. If one or more queries fail, the pipeline rejects with a
+ * `PipelineError` that carries per-query results so callers can inspect which
+ * succeeded and which failed.
+ *
+ * ```ts
+ * try {
+ *   await db.pipeline([q1, q2, q3], { transactional: false });
+ * } catch (err) {
+ *   if (err instanceof PipelineError) {
+ *     for (const slot of err.results) {
+ *       if (slot.status === 'error') console.error(slot.error);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class PipelineError extends TurbineError {
+    /** Per-query results: each slot is either `{status:'ok', value}` or `{status:'error', error}` */
+    results;
+    /** Zero-based index of the first query that failed */
+    failedIndex;
+    /** Tag of the first query that failed (from DeferredQuery.tag) */
+    failedTag;
+    constructor(opts) {
+        const { results, failedIndex, failedTag, cause } = opts;
+        const failedCount = results.filter((r) => r.status === 'error').length;
+        const message = opts.message ??
+            `[turbine] Pipeline completed with ${failedCount} error(s) out of ${results.length} queries` +
+                (failedTag ? ` (first failure: ${failedTag} at index ${failedIndex})` : '');
+        super(TurbineErrorCode.PIPELINE, message, { cause });
+        this.name = 'PipelineError';
+        this.results = results;
+        this.failedIndex = failedIndex;
+        this.failedTag = failedTag;
+    }
+}
 /**
  * Parse column names out of a pg `detail` string like:
  *   "Key (email)=(foo@bar) already exists."
@@ -234,6 +391,8 @@ function parseColumnsFromDetail(detail) {
  *   23503 (foreign_key_violation) -> ForeignKeyError
  *   23502 (not_null_violation)    -> NotNullViolationError
  *   23514 (check_violation)       -> CheckConstraintError
+ *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
+ *   40001 (serialization_failure) -> SerializationFailureError (retryable)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */
@@ -271,6 +430,15 @@ export function wrapPgError(err) {
                 table: e.table,
                 cause: err,
             });
+        case '40P01':
+            return new DeadlockError({
+                constraint: e.constraint,
+                cause: err,
+            });
+        case '40001':
+            return new SerializationFailureError({
+                cause: err,
+            });
         default:
             return err;
     }

package/dist/generate.d.ts

@@ -21,4 +21,10 @@ export declare function generate(options: GenerateOptions): {
     outDir: string;
     files: string[];
 };
+/**
+ * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
+ * and *Relations brand-field interfaces). Exported so tests can pin the
+ * generator output without writing files to disk.
+ */
+export declare function generateTypes(schema: SchemaMetadata): string;
 //# sourceMappingURL=generate.d.ts.map

package/dist/generate.js

@@ -60,8 +60,33 @@ function generatedFileHeader() {
         '',
     ];
 }
-function generateTypes(schema) {
+/**
+ * Generate the contents of `types.ts` (entity interfaces, *Create / *Update,
+ * and *Relations brand-field interfaces). Exported so tests can pin the
+ * generator output without writing files to disk.
+ */
+export function generateTypes(schema) {
     const lines = [...generatedFileHeader()];
+    // We import UpdateOperatorInput so generated *Update types can express
+    // atomic increment / decrement / multiply / divide / set operators on
+    // numeric columns (TASK-3.4).
+    //
+    // RelationDescriptor is the brand-field interface that lets `WithResult`
+    // recurse through nested `with` clauses at any depth. The generator emits
+    // each `*Relations` member as a `RelationDescriptor<Target, Cardinality,
+    // TargetRelations>` so users get full deep `with`-clause type inference
+    // out of the box (TASK-2.1).
+    lines.push("import type { RelationDescriptor, UpdateOperatorInput } from 'turbine-orm';");
+    lines.push('');
+    // Pre-compute which tables have relations so we know whether to thread
+    // `${TargetType}Relations` (for deep inference) or `{}` (the no-relations
+    // default) into each `RelationDescriptor`. Built once up-front because
+    // relations can point at tables we haven't iterated to yet.
+    const tablesWithRelations = new Set();
+    for (const t of Object.values(schema.tables)) {
+        if (Object.keys(t.relations).length > 0)
+            tablesWithRelations.add(t.name);
+    }
     // Generate enum types
     for (const [enumName, labels] of Object.entries(schema.enums)) {
         const typeName = snakeToPascal(enumName);
@@ -103,27 +128,33 @@ function generateTypes(schema) {
         lines.push('};');
         lines.push('');
         // --- Update input type (all fields optional except PK) ---
+        // Numeric columns additionally accept `UpdateOperatorInput<number>` so
+        // users can write `{ viewCount: { increment: 1 } }` without an `as any`.
         const nonPkCols = table.columns.filter((c) => !table.primaryKey.includes(c.name));
         lines.push(`/** Input type for updating a row in \`${table.name}\` */`);
         lines.push(`export type ${typeName}Update = {`);
         for (const col of nonPkCols) {
-            lines.push(`  ${col.field}?: ${col.tsType};`);
+            lines.push(`  ${col.field}?: ${updateFieldType(col.tsType)};`);
         }
         lines.push('};');
         lines.push('');
         // --- Relations map (for type-safe `with` clauses) ---
+        //
+        // Each relation is emitted as a `RelationDescriptor<Target, Cardinality,
+        // TargetRelations>` brand-field interface. This is what enables the
+        // recursive `WithResult` type to walk through nested `with` clauses at
+        // any depth — `RelationRelations<R[K]>` reads the third type parameter
+        // and threads it into the next recursion step. If the target table has
+        // no relations of its own, the descriptor uses `{}` (the default).
         const hasRelations = Object.keys(table.relations).length > 0;
         if (hasRelations) {
             lines.push(`/** Available relations for the \`${table.name}\` table */`);
             lines.push(`export interface ${typeName}Relations {`);
             for (const [relName, rel] of Object.entries(table.relations)) {
                 const targetType = entityName(rel.to);
-                if (rel.type === 'hasMany') {
-                    lines.push(`  ${relName}: ${targetType}[];`);
-                }
-                else {
-                    lines.push(`  ${relName}: ${targetType} | null;`);
-                }
+                const cardinality = rel.type === 'hasMany' ? "'many'" : "'one'";
+                const targetRelations = tablesWithRelations.has(rel.to) ? `${targetType}Relations` : '{}';
+                lines.push(`  ${relName}: RelationDescriptor<${targetType}, ${cardinality}, ${targetRelations}>;`);
             }
             lines.push('}');
             lines.push('');
@@ -227,8 +258,8 @@ function generateIndex(schema) {
     const tableEntries = Object.values(schema.tables);
     const lines = [
         ...generatedFileHeader(),
-        "import { TurbineClient as BaseTurbineClient, QueryInterface } from 'turbine-orm';",
-        "import type { TurbineConfig } from 'turbine-orm';",
+        "import { TurbineClient as BaseTurbineClient, TransactionClient as BaseTransactionClient, QueryInterface } from 'turbine-orm';",
+        "import type { TurbineConfig, TransactionOptions } from 'turbine-orm';",
         "import { SCHEMA } from './metadata.js';",
     ];
     // Import all entity types and relations maps
@@ -241,6 +272,41 @@ function generateIndex(schema) {
     }
     lines.push(`import type { ${typeImports.join(', ')} } from './types.js';`);
     lines.push('');
+    // -------------------------------------------------------------------------
+    // TypedTransactionClient — same typed table accessors as TurbineClient,
+    // but scoped to a single transaction connection. The runtime instance is
+    // an ordinary `TransactionClient` from turbine-orm; this declaration just
+    // teaches TypeScript about the auto-attached accessors so users get
+    // autocomplete inside `db.$transaction(async (tx) => tx.users.create(...))`.
+    // -------------------------------------------------------------------------
+    lines.push('/**');
+    lines.push(' * Transaction-scoped client with the same typed table accessors as TurbineClient.');
+    lines.push(' * Created automatically by `db.$transaction(async (tx) => ...)` — never instantiate');
+    lines.push(' * directly. All queries run on a dedicated connection within a BEGIN/COMMIT block.');
+    lines.push(' */');
+    lines.push('export class TypedTransactionClient extends BaseTransactionClient {');
+    for (const table of tableEntries) {
+        const typeName = entityName(table.name);
+        const accessor = snakeToCamelStr(table.name);
+        const hasRelations = Object.keys(table.relations).length > 0;
+        const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
+        lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
+        lines.push(`  declare readonly ${accessor}: QueryInterface<${genericArgs}>;`);
+    }
+    lines.push('}');
+    lines.push('');
+    // Augment the class with a typed `$transaction` overload via interface
+    // merging. This adds an additional callable signature whose callback
+    // parameter is narrowed to `TypedTransactionClient`, while the base
+    // signature (callback parameter `BaseTransactionClient`) remains valid.
+    lines.push('export interface TypedTransactionClient {');
+    lines.push('  /**');
+    lines.push('   * Nested transaction via SAVEPOINT. The callback receives a typed');
+    lines.push('   * `TypedTransactionClient` so all table accessors auto-complete.');
+    lines.push('   */');
+    lines.push('  $transaction<R>(fn: (tx: TypedTransactionClient) => Promise<R>): Promise<R>;');
+    lines.push('}');
+    lines.push('');
     // Generate the client class with JSDoc
     lines.push('/**');
     lines.push(' * Generated Turbine client with typed table accessors.');
@@ -275,6 +341,22 @@ function generateIndex(schema) {
     lines.push('  }');
     lines.push('}');
     lines.push('');
+    // Augment TurbineClient via interface merging with a typed $transaction
+    // overload. The callback parameter is narrowed to `TypedTransactionClient`
+    // so users get autocomplete on `tx.users`, `tx.posts`, etc. The base
+    // signature (callback parameter `BaseTransactionClient`) remains valid as
+    // an overload, so prior usage continues to typecheck.
+    lines.push('export interface TurbineClient {');
+    lines.push('  /**');
+    lines.push('   * Run a callback inside a transaction. The callback receives a typed');
+    lines.push('   * `TypedTransactionClient` with autocompletion for every table accessor.');
+    lines.push('   */');
+    lines.push('  $transaction<R>(');
+    lines.push('    fn: (tx: TypedTransactionClient) => Promise<R>,');
+    lines.push('    options?: TransactionOptions,');
+    lines.push('  ): Promise<R>;');
+    lines.push('}');
+    lines.push('');
     // Factory function with JSDoc
     lines.push('/**');
     lines.push(' * Create a new Turbine client instance.');
@@ -316,4 +398,32 @@ function quoteIfNeeded(s) {
 function snakeToCamelStr(s) {
     return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
+/**
+ * Build the update-input field type for a column. Numeric columns become
+ * `T | UpdateOperatorInput<number> | null?` so users can write atomic
+ * operators (`{ increment: 1 }`, `{ multiply: 2 }`, etc.) without casts.
+ *
+ * The check is purely structural — if the column's TS type contains
+ * `'number'` (e.g. `number`, `number | null`), it's eligible. Other
+ * scalar types (`string`, `boolean`, `Date`, `unknown`, `Buffer`,
+ * `Date | null`, etc.) pass through unchanged.
+ */
+function updateFieldType(tsType) {
+    // Strip parens for the regex check; preserve the original string in the output.
+    if (containsNumberType(tsType)) {
+        return `${tsType} | UpdateOperatorInput<number>`;
+    }
+    return tsType;
+}
+/**
+ * Detect whether a TypeScript type expression contains the `number` primitive
+ * as a top-level union member. Conservative on purpose — only matches
+ * `number`, `number | null`, `null | number`, etc., not `number[]` or
+ * `Record<string, number>`.
+ */
+function containsNumberType(tsType) {
+    // Tokenize on `|` and check each member.
+    const parts = tsType.split('|').map((p) => p.trim());
+    return parts.some((p) => p === 'number');
+}
 //# sourceMappingURL=generate.js.map

package/dist/index.d.ts

@@ -33,11 +33,11 @@
  * ```
  */
 export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, } from './client.js';
-export { CheckConstraintError, CircularRelationError, ConnectionError, ForeignKeyError, MigrationError, NotFoundError, NotNullViolationError, RelationError, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, type PipelineResultSlot, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
-export { executePipeline, type PipelineResults } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type OrderDirection, QueryInterface, type RelationFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query.js';
+export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type CountArgs, type CreateArgs, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type JsonFilter, type OrderDirection, QueryInterface, type RelationDescriptor, type RelationFilter, type TypedWithClause, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type WithClause, type WithOptions, type WithResult, } from './query.js';
 export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
 export { ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type SchemaDef, type TableDef, table, } from './schema-builder.js';

package/dist/index.js

@@ -35,13 +35,13 @@
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
 // Error types
-export { CheckConstraintError, CircularRelationError, ConnectionError, ForeignKeyError, MigrationError, NotFoundError, NotNullViolationError, RelationError, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, PipelineError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, ValidationError, wrapPgError, } from './errors.js';
 // Code generation
 export { generate } from './generate.js';
 // Introspection
 export { introspect } from './introspect.js';
 // Pipeline
-export { executePipeline } from './pipeline.js';
+export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder
 export { QueryInterface, } from './query.js';
 // Schema utilities

package/dist/pipeline-submittable.d.ts

@@ -0,0 +1,94 @@
+/**
+ * turbine-orm — Real Postgres pipeline protocol implementation
+ *
+ * Uses the pg extended-query protocol wire methods (parse/bind/describe/execute/sync)
+ * exposed on pg.Client's Connection object to send multiple queries in a single
+ * TCP flush. This achieves true 1-RTT pipeline execution instead of the sequential
+ * await-per-query approach.
+ *
+ * The approach (listener-swap):
+ *   1. Detach the pg.Client's event listeners from the Connection
+ *   2. Attach our own state-machine listeners
+ *   3. Cork the TCP stream, push all protocol messages, uncork (one TCP write)
+ *   4. Drive a state machine over backend response events
+ *   5. Restore original listeners and release the client
+ *
+ * This is the same pattern used by pg-cursor and pg-query-stream, but extended
+ * to handle N queries in a single pipeline.
+ */
+import type { EventEmitter } from 'node:events';
+import type { DeferredQuery } from './query.js';
+/** The pg Connection object — an EventEmitter with wire-protocol methods */
+export interface PgConnection extends EventEmitter {
+    stream: {
+        cork?: () => void;
+        uncork?: () => void;
+        writable?: boolean;
+        destroy?: (err?: Error) => void;
+        write?: (...args: unknown[]) => boolean;
+    };
+    parse(query: {
+        text: string;
+        name?: string;
+        types?: number[];
+    }): void;
+    bind(config: {
+        portal?: string;
+        statement?: string;
+        values?: unknown[];
+        binary?: boolean;
+        valueMapper?: (val: unknown, index: number) => unknown;
+    }): void;
+    describe(msg: {
+        type: 'S' | 'P';
+        name?: string;
+    }): void;
+    execute(config: {
+        portal?: string;
+        rows?: number;
+    }): void;
+    sync(): void;
+}
+/** A pg PoolClient with the internal fields we need */
+export interface PgPoolClient {
+    connection: PgConnection;
+    /** pg.Client sets this to control query queue draining */
+    readyForQuery: boolean;
+    /** Type parser overrides (if the client has custom type parsers) */
+    _types?: unknown;
+    release(err?: Error | boolean): void;
+}
+export interface PipelineRunOptions {
+    /**
+     * Whether to wrap the pipeline in BEGIN/COMMIT (default: true).
+     * When true, all queries execute atomically. On error, ROLLBACK is sent.
+     * When false, each query gets its own Sync message for error isolation.
+     */
+    transactional?: boolean;
+    /** Timeout in milliseconds. If exceeded, the connection is destroyed. */
+    timeout?: number;
+}
+/**
+ * Execute multiple queries using the Postgres extended-query pipeline protocol.
+ *
+ * All protocol messages are buffered into a single TCP write via cork/uncork.
+ * The backend processes them in order and sends back results which our state
+ * machine collects.
+ *
+ * @param client - A pg PoolClient with an accessible Connection
+ * @param queries - Array of DeferredQuery descriptors
+ * @param options - Pipeline options (transactional, timeout)
+ * @returns Array of transformed results in the same order as queries
+ */
+export declare function runPipelined<T extends readonly DeferredQuery<unknown>[]>(client: PgPoolClient, queries: T, options?: PipelineRunOptions): Promise<unknown[]>;
+/**
+ * Check whether a pool client supports the extended-query pipeline protocol.
+ *
+ * Returns true if the client has a Connection object with the required wire
+ * protocol methods (parse, bind, describe, execute, sync) and is an EventEmitter.
+ *
+ * Returns false for HTTP-based drivers (Neon HTTP, Vercel Postgres), mock pools,
+ * and any pool that doesn't expose pg internals.
+ */
+export declare function supportsExtendedPipeline(poolClient: unknown): poolClient is PgPoolClient;
+//# sourceMappingURL=pipeline-submittable.d.ts.map