turbine-orm 0.7.0 → 0.8.0

package/dist/query.d.ts

@@ -72,12 +72,26 @@ export interface WithClause {
  * Relation-aware with clause. When R (the relations map) is provided,
  * only keys from R are autocompleted. Used in public method signatures
  * so the compiler can narrow the return type.
+ *
+ * For typed maps, each relation accepts either `true` (default include) or a
+ * {@link WithOptions} object whose nested `with` is keyed against the relation
+ * target's own relations interface — this is what enables deep
+ * `WithResult` inference.
  */
 export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
-    [K in keyof R]?: true | WithOptions;
+    [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object>;
 };
-export interface WithOptions<_T = unknown> {
-    with?: WithClause;
+/**
+ * Options for an included relation.
+ *
+ * Generic over `NestedR` — the relations interface of the *target* entity —
+ * so the nested `with` clause is autocompleted with the correct relation keys
+ * and so {@link WithResult} can recursively infer the return type. Defaults to
+ * `{}` (no relation suggestions) for callers that use the unparameterized
+ * {@link WithClause}.
+ */
+export interface WithOptions<NestedR extends object = {}> {
+    with?: TypedWithClause<NestedR>;
     where?: Record<string, unknown>;
     orderBy?: Record<string, OrderDirection>;
     limit?: number;
@@ -86,18 +100,87 @@ export interface WithOptions<_T = unknown> {
     /** Exclude these fields from the relation */
     omit?: Record<string, boolean>;
 }
+/**
+ * A relation descriptor used by generated `*Relations` interfaces to make deep
+ * `with` clause inference work. It bundles three pieces of information that
+ * `WithResult` needs to recurse through nested relations:
+ *
+ *  - `__target`     — the target entity type (e.g. `Post`)
+ *  - `__cardinality`— `'many'` for hasMany, `'one'` for belongsTo / hasOne
+ *  - `__relations`  — the target entity's relations interface (for further recursion)
+ *
+ * **Generator contract (Track 3):** the code generator emits `*Relations`
+ * interfaces in the following shape so that `WithResult` can walk arbitrary
+ * nesting depth:
+ *
+ * ```ts
+ * export interface UserRelations {
+ *   posts:   RelationDescriptor<Post,    'many', PostRelations>;
+ *   profile: RelationDescriptor<Profile, 'one',  ProfileRelations>;
+ * }
+ * ```
+ *
+ * The brand fields are phantom — they exist only for type inference and have
+ * no runtime representation. The runtime always sees the parsed entity values
+ * (arrays for hasMany, single object or null for belongsTo / hasOne) — see the
+ * cardinality projection inside {@link WithResult}.
+ *
+ * **Backward compatibility:** legacy generated code emitted bare types
+ * (`posts: Post[]`, `profile: Profile | null`). `WithResult` still accepts that
+ * shape via a fallback branch — it just cannot recurse into nested `with` for
+ * those relations until the generator is updated.
+ *
+ * @typeParam Target      - The entity type the relation points at.
+ * @typeParam Cardinality - `'many'` (array) or `'one'` (single object | null).
+ * @typeParam Relations   - The target entity's own `*Relations` interface, or
+ *                          `{}` if the target has no relations of its own.
+ */
+export interface RelationDescriptor<Target, Cardinality extends 'one' | 'many', Relations extends object = {}> {
+    readonly __target?: Target;
+    readonly __cardinality?: Cardinality;
+    readonly __relations?: Relations;
+}
+/** Extract the target entity from a relation descriptor or bare relation type. */
+type RelationTarget<Rel> = Rel extends RelationDescriptor<infer Target, infer _C, infer _R> ? Target : Rel extends Array<infer Item> ? Item : Rel extends infer One | null ? One : Rel;
+/** Extract the target's relations map from a relation descriptor (or `{}` for bare types). */
+type RelationRelations<Rel> = Rel extends RelationDescriptor<infer _T, infer _C, infer R> ? R : {};
+/** Project the target type into its runtime shape (array for many, single for one). */
+type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T, infer Cardinality, infer _R> ? Cardinality extends 'many' ? Resolved[] : Resolved | null : Rel extends Array<infer _Item> ? Resolved[] : Resolved | null;
 /**
  * Compute the result type when relations are included via `with`.
  *
- * - When R is the default ({}) or W is empty, resolves to plain T.
- * - When R is a real relations map and W specifies relation keys, merges matching
- *   relation types from R onto T.
+ * Recursively walks the `with` clause, looking up each relation in `R` and:
+ *
+ *  1. If the relation is included with `true` (or no nested `with`), the
+ *     relation's bare resolved type is grafted onto `T` (e.g. `posts: Post[]`).
+ *  2. If the relation is included with a nested `with: {...}`, the recursion
+ *     looks up the target entity's relations interface (via the
+ *     {@link RelationDescriptor} brand fields the generator emits) and
+ *     recursively applies `WithResult` to the nested target. Cardinality is
+ *     re-applied at each level so a hasMany relation stays an array even after
+ *     deep nesting.
  *
- * @typeParam T - Base entity type (e.g. User)
- * @typeParam R - Relations map (e.g. { posts: Post[]; profile: Profile | null })
- * @typeParam W - The with clause object (e.g. { posts: true })
+ * **When `R` is `{}` (the default):** the recursion short-circuits and the
+ * function returns plain `T` — preserving the existing untyped escape hatch
+ * for callers that have not generated typed clients.
+ *
+ * **When `R` does not contain the requested relations:** the unknown keys are
+ * ignored (the runtime will throw a `RelationError`, but the type system stays
+ * permissive so the legacy `WithClause` index signature still typechecks).
+ *
+ * @typeParam T - Base entity type (e.g. `User`).
+ * @typeParam R - Relations map for `T` (e.g.
+ *                `{ posts: RelationDescriptor<Post, 'many', PostRelations>; ... }`).
+ *                Legacy bare shapes (`{ posts: Post[]; profile: Profile | null }`)
+ *                are also accepted, but cannot recurse beyond one level.
+ * @typeParam W - The `with` clause the user passed (e.g. `{ posts: true }` or
+ *                `{ posts: { with: { comments: true } } }`).
  */
-export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : [keyof W & keyof R] extends [never] ? T : T & Pick<R, keyof W & keyof R>;
+export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? [keyof W & keyof R] extends [never] ? T : T & {
+    [K in keyof W & keyof R]: W[K] extends true ? ApplyCardinality<R[K], RelationTarget<R[K]>> : W[K] extends {
+        with?: infer NestedW;
+    } ? NestedW extends object ? ApplyCardinality<R[K], WithResult<RelationTarget<R[K]>, RelationRelations<R[K]> & object, NestedW>> : ApplyCardinality<R[K], RelationTarget<R[K]>> : ApplyCardinality<R[K], RelationTarget<R[K]>>;
+} : T;
 export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
     where: WhereClause<T>;
     select?: Record<string, boolean>;
@@ -124,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> {
@@ -287,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;
@@ -296,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: {
@@ -311,23 +425,84 @@ type MiddlewareFn = (params: {
 export interface QueryInterfaceOptions {
     /** Default LIMIT applied to findMany() when no limit is specified */
     defaultLimit?: number;
-    /** Log a warning when findMany() is called without a limit */
+    /**
+     * Log a one-time warning when {@link QueryInterface.findMany} is called
+     * without a `limit`. Defaults to `true` so that accidental unbounded
+     * queries are surfaced loudly during development. Pass `false` to silence
+     * the warning entirely (e.g. for CLI tooling that intentionally streams
+     * 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
+     * QueryInterface is bound to a single table, so this set will only ever
+     * contain at most one entry, but using a Set keeps the API consistent with
+     * the audit's "Set<string>" guidance and leaves room for future
+     * 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
+     * exactly once per table without bleeding state between assertions.
+     */
+    resetUnlimitedWarnings(): void;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
@@ -347,14 +522,37 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     findUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
     buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T | null>;
     findMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>[]>;
+    /**
+     * Emit a one-time `console.warn` when {@link findMany} is called without an
+     * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
+     *
+     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
+     * loop calling `db.users.findMany()` thousands of times only logs once.
+     * Suppressed when `defaultLimit` is configured (the caller has already
+     * opted in to a bounded query) and when the user passed an explicit
+     * `limit`, `take`, or `cursor`.
+     */
+    private maybeWarnUnlimited;
     buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
     /**
      * 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
@@ -423,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;
     /**