turbine-orm 0.7.1 → 0.8.0

package/dist/client.d.ts

@@ -23,7 +23,7 @@
  */
 import pg from 'pg';
 import { type ErrorMessageMode } from './errors.js';
-import { type PipelineResults } from './pipeline.js';
+import { type PipelineOptions, type PipelineResults } from './pipeline.js';
 import { type DeferredQuery, QueryInterface, type QueryInterfaceOptions } from './query.js';
 import type { SchemaMetadata } from './schema.js';
 /**
@@ -125,6 +125,23 @@ export interface TurbineConfig {
      * programmatic access regardless of mode.
      */
     errorMessages?: ErrorMessageMode;
+    /**
+     * Enable prepared statements. Queries are submitted with `{ name, text, values }`
+     * to the pg driver, which caches the parse+plan on the server per connection.
+     *
+     * Default: `true` for Turbine-owned pools, `false` for external pools (serverless
+     * drivers may not support named statements).
+     *
+     * Override with `TURBINE_DISABLE_PREPARED=1` env var.
+     */
+    preparedStatements?: boolean;
+    /**
+     * Enable the SQL template cache. Repeated queries with the same shape reuse
+     * cached SQL text instead of rebuilding from scratch.
+     *
+     * Default: `true`. Set to `false` as a nuclear kill switch.
+     */
+    sqlCache?: boolean;
 }
 /** Parameters passed to middleware functions */
 export interface MiddlewareParams {
@@ -236,9 +253,21 @@ export declare class TurbineClient {
     /**
      * Execute multiple queries in a single database round-trip.
      *
-     * Pass the result of any `.build*()` method on a table accessor.
+     * Two call styles:
+     *   - `db.pipeline(q1, q2, q3)` — rest params (backward-compatible)
+     *   - `db.pipeline([q1, q2, q3], { transactional: false })` — array + options
+     *
+     * On pg.Pool-backed connections with TCP, this uses the real Postgres
+     * extended-query pipeline protocol (one TCP flush, one round-trip).
+     * On HTTP-based drivers it falls back to sequential execution.
+     */
+    pipeline<T extends readonly DeferredQuery<unknown>[]>(...args: T | [T, PipelineOptions?]): Promise<PipelineResults<T>>;
+    /**
+     * Check whether the underlying pool supports the real pipeline protocol.
+     * Returns `true` for standard pg.Pool TCP connections, `false` for HTTP
+     * drivers (Neon HTTP, Vercel Postgres, etc.) and mock pools.
      */
-    pipeline<T extends readonly DeferredQuery<unknown>[]>(...queries: T): Promise<PipelineResults<T>>;
+    pipelineSupported(): Promise<boolean>;
     /**
      * Execute a raw SQL query with parameter interpolation via tagged templates.
      *

package/dist/client.js

@@ -23,7 +23,7 @@
  */
 import pg from 'pg';
 import { setErrorMessageMode, TimeoutError, wrapPgError } from './errors.js';
-import { executePipeline } from './pipeline.js';
+import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface } from './query.js';
 /** Maps isolation level names to SQL */
 const ISOLATION_LEVELS = {
@@ -128,9 +128,15 @@ export class TransactionClient {
         // Return a minimal pool-compatible object that routes queries
         // through the transaction client
         return {
-            query: async (text, values) => {
+            query: async (textOrConfig, values) => {
                 try {
-                    return await client.query(text, values);
+                    if (typeof textOrConfig === 'string') {
+                        return await client.query(textOrConfig, values);
+                    }
+                    // Object form for prepared statements: { name, text, values }
+                    // pg.PoolClient.query accepts QueryConfig but the overloads make TS
+                    // unhappy with the union, so we cast through unknown.
+                    return await client.query(textOrConfig);
                 }
                 catch (err) {
                     throw wrapPgError(err);
@@ -184,9 +190,13 @@ export class TurbineClient {
         }
         this.logging = config.logging ?? false;
         this.schema = schema;
+        // Respect env var kill switch
+        const envDisablePrepared = typeof process !== 'undefined' && process.env?.TURBINE_DISABLE_PREPARED === '1';
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
+            preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
+            sqlCache: config.sqlCache ?? true,
         };
         // Apply NotFoundError message redaction mode (default: safe — values are
         // stripped from messages to avoid leaking PII into error logs).
@@ -300,13 +310,41 @@ export class TurbineClient {
     /**
      * Execute multiple queries in a single database round-trip.
      *
-     * Pass the result of any `.build*()` method on a table accessor.
+     * Two call styles:
+     *   - `db.pipeline(q1, q2, q3)` — rest params (backward-compatible)
+     *   - `db.pipeline([q1, q2, q3], { transactional: false })` — array + options
+     *
+     * On pg.Pool-backed connections with TCP, this uses the real Postgres
+     * extended-query pipeline protocol (one TCP flush, one round-trip).
+     * On HTTP-based drivers it falls back to sequential execution.
      */
-    async pipeline(...queries) {
+    async pipeline(...args) {
+        let queries;
+        let options;
+        // Detect which overload was used
+        if (args.length > 0 &&
+            Array.isArray(args[0]) &&
+            args[0].every((item) => item && typeof item === 'object' && 'sql' in item)) {
+            // Array form: pipeline([q1, q2], opts?)
+            queries = args[0];
+            options = args[1];
+        }
+        else {
+            // Rest-param form: pipeline(q1, q2, q3)
+            queries = args;
+        }
         if (this.logging) {
             console.log(`[turbine] Pipeline: ${queries.length} queries — ${queries.map((q) => q.tag).join(', ')}`);
         }
-        return executePipeline(this.pool, queries);
+        return executePipeline(this.pool, queries, options);
+    }
+    /**
+     * Check whether the underlying pool supports the real pipeline protocol.
+     * Returns `true` for standard pg.Pool TCP connections, `false` for HTTP
+     * drivers (Neon HTTP, Vercel Postgres, etc.) and mock pools.
+     */
+    async pipelineSupported() {
+        return pipelineSupported(this.pool);
     }
     // -------------------------------------------------------------------------
     // Raw SQL — tagged template literal escape hatch

package/dist/errors.d.ts

@@ -19,6 +19,7 @@ export declare const TurbineErrorCode: {
     readonly CHECK_VIOLATION: "TURBINE_E011";
     readonly DEADLOCK_DETECTED: "TURBINE_E012";
     readonly SERIALIZATION_FAILURE: "TURBINE_E013";
+    readonly PIPELINE: "TURBINE_E014";
 };
 export type TurbineErrorCode = (typeof TurbineErrorCode)[keyof typeof TurbineErrorCode];
 /** Base error class for all Turbine errors */
@@ -207,6 +208,49 @@ export declare class CheckConstraintError extends TurbineError {
         cause?: unknown;
     });
 }
+/** Result slot for a single query in a non-transactional pipeline */
+export type PipelineResultSlot = {
+    status: 'ok';
+    value: unknown;
+} | {
+    status: 'error';
+    error: Error;
+};
+/**
+ * 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 declare class PipelineError extends TurbineError {
+    /** Per-query results: each slot is either `{status:'ok', value}` or `{status:'error', error}` */
+    readonly results: PipelineResultSlot[];
+    /** Zero-based index of the first query that failed */
+    readonly failedIndex?: number;
+    /** Tag of the first query that failed (from DeferredQuery.tag) */
+    readonly failedTag?: string;
+    constructor(opts: {
+        message?: string;
+        results: PipelineResultSlot[];
+        failedIndex?: number;
+        failedTag?: string;
+        cause?: unknown;
+    });
+}
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.

package/dist/errors.js

@@ -19,6 +19,7 @@ export const TurbineErrorCode = {
     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 {
@@ -330,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."

package/dist/index.d.ts

@@ -33,10 +33,10 @@
  * ```
  */
 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, DeadlockError, type ErrorMessageMode, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, RelationError, SerializationFailureError, setErrorMessageMode, 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 { 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';

package/dist/index.js

@@ -35,13 +35,13 @@
 // Client
 export { TransactionClient, TurbineClient, } from './client.js';
 // Error types
-export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, RelationError, SerializationFailureError, setErrorMessageMode, 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