turbine-orm 0.7.1 → 0.8.0

package/dist/query.d.ts

@@ -207,7 +207,17 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     timeout?: number;
 }
 export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> extends FindManyArgs<T, R, W> {
-    /** Number of rows to fetch per internal FETCH batch (default: 100) */
+    /**
+     * Number of rows to fetch per internal FETCH batch (default: 1000).
+     *
+     * Trade-off: larger batches reduce network round-trips (important for
+     * high-latency connections like Neon) but increase per-batch memory.
+     * At 1000 rows x ~500 bytes/row the default is ~500 KB per batch.
+     *
+     * When the total result set fits within one batch, the stream avoids
+     * cursor overhead entirely (no BEGIN / DECLARE / CLOSE / COMMIT) by
+     * using a speculative `SELECT ... LIMIT batchSize+1` first.
+     */
     batchSize?: number;
 }
 export interface CreateArgs<T> {
@@ -370,6 +380,25 @@ export interface ArrayFilter {
     /** Check if array is empty: array_length(column, 1) IS NULL */
     isEmpty?: boolean;
 }
+/** Cached SQL template paired with its prepared-statement name. */
+export interface SqlCacheEntry {
+    sql: string;
+    name: string;
+}
+/**
+ * FNV-1a 64-bit hash returning 16 lowercase hex chars.
+ * Single-loop string iteration. Uses BigInt for 64-bit math.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function fnv1a64Hex(s: string): string;
+/**
+ * Derive a prepared-statement name from a SQL string.
+ * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
+ *
+ * @internal Exported for testing only.
+ */
+export declare function sqlToPreparedName(sql: string): string;
 export interface DeferredQuery<T> {
     /** SQL text with $1, $2 placeholders */
     sql: string;
@@ -379,6 +408,8 @@ export interface DeferredQuery<T> {
     transform: (result: pg.QueryResult) => T;
     /** Tag for debugging / logging */
     tag: string;
+    /** Prepared statement name (t_<16hex>). Set when SQL cache is enabled. */
+    preparedName?: string;
 }
 /** Middleware function type — imported from client to avoid circular deps */
 type MiddlewareFn = (params: {
@@ -402,17 +433,36 @@ export interface QueryInterfaceOptions {
      * full tables).
      */
     warnOnUnlimited?: boolean;
+    /**
+     * Enable prepared statements. When true, queries are submitted with a
+     * `{ name, text, values }` object 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).
+     */
+    preparedStatements?: boolean;
+    /**
+     * Enable the SQL template cache. When true, repeated queries with the
+     * same shape (same keys, operators, relations — different values) reuse
+     * cached SQL text instead of rebuilding from scratch.
+     *
+     * Default: `true`. Set to `false` as a nuclear kill switch.
+     */
+    sqlCache?: boolean;
 }
 export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
     private readonly table;
     private readonly schema;
     private readonly tableMeta;
-    /** SQL template cache: cacheKey → sql string (params are always positional $1,$2,...) */
-    private readonly sqlCache;
+    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
+    private readonly sqlTemplateCache;
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
+    private readonly preparedStatementsEnabled;
+    private readonly sqlCacheEnabled;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
      * the user is not spammed once per row. Per-instance state — each
@@ -422,10 +472,31 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * cross-table sharing.
      */
     private readonly warnedTables;
+    /** Cache hit/miss counters for diagnostics */
+    private cacheHits;
+    private cacheMisses;
     /** Pre-computed column type lookups (avoids linear scans per query) */
     private readonly columnPgTypeMap;
     private readonly columnArrayTypeMap;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /**
+     * Return cache hit/miss statistics for this QueryInterface instance.
+     * Useful for monitoring and benchmarking.
+     */
+    cacheStats(): {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        size: number;
+    };
+    /**
+     * Look up or build a SQL template in the cache.
+     * On miss, calls `build()` to generate the SQL, stores the entry, and returns it.
+     * On hit, increments counters and returns the cached entry.
+     *
+     * When `sqlCache` is disabled, always calls `build()` without caching.
+     */
+    private acquireSql;
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires
@@ -467,9 +538,21 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * Stream rows from a findMany query using PostgreSQL cursors.
      * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
      *
-     * Uses DECLARE CURSOR within a dedicated transaction on a single pooled connection.
-     * The cursor is automatically closed and the connection released when iteration
-     * completes or is terminated early (e.g. `break` from `for await`).
+     * **Speculative fast-path:** Before opening a cursor, issues a single
+     * `SELECT ... LIMIT batchSize+1`. If the result fits within `batchSize`,
+     * all rows are yielded immediately with zero cursor overhead (no BEGIN /
+     * DECLARE / CLOSE / COMMIT). Only when the result overflows does the
+     * method fall back to the full cursor path.
+     *
+     * **Cursor path:** Uses DECLARE CURSOR within a dedicated transaction on a
+     * single pooled connection. The cursor is automatically closed and the
+     * connection released when iteration completes or is terminated early
+     * (e.g. `break` from `for await`).
+     *
+     * **Snapshot semantics note:** The speculative fast-path runs outside a
+     * transaction. If the result overflows and the cursor path is opened, the
+     * cursor runs in its own transaction — spanning two separate snapshots.
+     * For strict single-snapshot semantics, wrap the call in `$transaction`.
      *
      * @example
      * ```ts
@@ -538,6 +621,59 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * clause numbering continues correctly afterward.
      */
     private buildSetClause;
+    /**
+     * Produce a value-invariant fingerprint of a where clause.
+     * Same keys + same operator shapes + same combinator structure => same string.
+     * Different values (e.g. id=1 vs id=999) => identical fingerprint.
+     *
+     * @internal Exposed as package-private for testing via class access.
+     */
+    fingerprintWhere(where: Record<string, unknown>): string;
+    /**
+     * Fingerprint a relation filter sub-where for some/every/none.
+     */
+    private fingerprintRelFilter;
+    /**
+     * Walk a where clause and push ONLY values into `params`, in the EXACT same
+     * order that `buildWhereClause` pushes them. Used on cache hit to fill params
+     * without rebuilding SQL.
+     *
+     * @internal Exposed as package-private for testing.
+     */
+    collectWhereParams(where: Record<string, unknown>, params: unknown[]): void;
+    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
+    private collectRelFilterParams;
+    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
+    private collectOperatorParams;
+    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
+    private collectJsonFilterParams;
+    /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
+    private collectArrayFilterParams;
+    /**
+     * Produce a fingerprint for a `with` clause tree. Recursion mirrors
+     * buildSelectWithRelations / buildRelationSubquery.
+     *
+     * @internal Exposed as package-private for testing.
+     */
+    withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
+    /**
+     * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
+     * buildRelationSubquery param-push order.
+     */
+    private collectWithParams;
+    /**
+     * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
+     */
+    private collectRelationSubqueryParams;
+    /**
+     * Fingerprint SET clauses for update/updateMany.
+     * Captures key names + operator types (set/increment/etc) but not values.
+     */
+    private fingerprintSet;
+    /**
+     * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
+     */
+    private collectSetParams;
     /** Build WHERE clause from a where object (supports operators, NULL, OR) */
     private buildWhere;
     /**