turbine-orm 0.39.0 → 0.40.0

package/dist/cli/migrate.d.ts

@@ -13,6 +13,7 @@
  */
 import type { DatabaseAdapter } from '../adapters/index.js';
 import { type Dialect } from '../dialect.js';
+import { type DestructiveStatement } from './destructive.js';
 export interface MigrationFile {
     /** Full filename (e.g. "20260325120000_create_users.sql") */
     filename: string;
@@ -91,6 +92,38 @@ export interface MigrationRecipe {
  * in here without touching {@link createMigration} or the CLI handler.
  */
 export declare const MIGRATION_RECIPES: Record<string, MigrationRecipe>;
+/**
+ * The UP/DOWN body produced by {@link buildDiffMigrationBody}, plus the
+ * destructive statements found in each direction so the CLI can warn loudly.
+ */
+export interface DiffMigrationBody {
+    /** Annotated UP SQL (destructive statements flagged with loud comments). */
+    up: string;
+    /** Annotated DOWN SQL, or an irreversible placeholder when none is derivable. */
+    down: string;
+    /** Destructive statements detected in the UP direction. */
+    destructiveUp: DestructiveStatement[];
+    /** Destructive statements detected in the DOWN direction. */
+    destructiveDown: DestructiveStatement[];
+}
+/**
+ * Build a migration UP/DOWN body from a `schemaDiff()` result.
+ *
+ * - UP is the diff's forward statements. DOWN is the diff's reverse statements
+ *   when derivable, otherwise a clearly-commented "irreversible" placeholder.
+ * - Destructive statements in EITHER direction (a lossy `ALTER COLUMN ... TYPE`
+ *   in UP, a `DROP TABLE`/`DROP COLUMN` reverse in DOWN) are flagged inline and,
+ *   when any exist, a loud file-level banner is prepended to UP.
+ * - Any diff `warnings` (changes the diff refuses to apply automatically, e.g.
+ *   enum value removals) are surfaced as `-- NOTE:` comments in UP.
+ *
+ * Pure and DB-free, so it is unit-testable from a synthesized diff.
+ */
+export declare function buildDiffMigrationBody(diff: {
+    statements: string[];
+    reverseStatements: string[];
+    warnings?: string[];
+}): DiffMigrationBody;
 /**
  * Create a new migration file.
  *

package/dist/cli/migrate.js

@@ -202,6 +202,84 @@ export const MIGRATION_RECIPES = {
         build: buildBackfillRecipe,
     },
 };
+/** Loud file-level banner prepended when a diff migration contains destructive statements. */
+const DESTRUCTIVE_MIGRATION_BANNER = [
+    '-- ============================================================',
+    '-- WARNING: this migration contains DESTRUCTIVE statement(s).',
+    '-- Each one is flagged inline below. `turbine migrate up` refuses',
+    '-- destructive statements by default: it asks you to confirm',
+    '-- interactively, or you must pass --allow-destructive. Review',
+    '-- every flagged statement carefully before running.',
+    '-- ============================================================',
+];
+/**
+ * Annotate a list of SQL statements: scan each for data-destroying operations
+ * (via {@link scanDestructiveSql}) and prefix any offender with loud, commented
+ * warnings. Statements are left intact so the existing `migrate up` gate still
+ * refuses them by default; the comments just make the danger visible on review.
+ */
+function annotateDiffStatements(statements) {
+    const destructive = [];
+    const out = [];
+    for (const raw of statements) {
+        const stmt = raw.trim();
+        if (!stmt)
+            continue;
+        const hits = scanDestructiveSql(stmt);
+        if (hits.length > 0) {
+            destructive.push(...hits);
+            for (const h of hits) {
+                out.push(`-- !! DESTRUCTIVE [${h.kind}] ${h.target}: ${DESTRUCTIVE_KIND_LABEL[h.kind]}`);
+            }
+            out.push('-- !! Refused by default. Confirm interactively or pass --allow-destructive to run it.');
+        }
+        out.push(stmt.endsWith(';') ? stmt : `${stmt};`);
+    }
+    return { text: out.join('\n'), destructive };
+}
+/**
+ * Build a migration UP/DOWN body from a `schemaDiff()` result.
+ *
+ * - UP is the diff's forward statements. DOWN is the diff's reverse statements
+ *   when derivable, otherwise a clearly-commented "irreversible" placeholder.
+ * - Destructive statements in EITHER direction (a lossy `ALTER COLUMN ... TYPE`
+ *   in UP, a `DROP TABLE`/`DROP COLUMN` reverse in DOWN) are flagged inline and,
+ *   when any exist, a loud file-level banner is prepended to UP.
+ * - Any diff `warnings` (changes the diff refuses to apply automatically, e.g.
+ *   enum value removals) are surfaced as `-- NOTE:` comments in UP.
+ *
+ * Pure and DB-free, so it is unit-testable from a synthesized diff.
+ */
+export function buildDiffMigrationBody(diff) {
+    const up = annotateDiffStatements(diff.statements);
+    const hasReverse = diff.reverseStatements.length > 0;
+    const down = hasReverse
+        ? annotateDiffStatements(diff.reverseStatements)
+        : { text: '', destructive: [] };
+    const upParts = [];
+    if (up.destructive.length > 0 || down.destructive.length > 0) {
+        upParts.push(...DESTRUCTIVE_MIGRATION_BANNER, '');
+    }
+    if (diff.warnings && diff.warnings.length > 0) {
+        for (const w of diff.warnings)
+            upParts.push(`-- NOTE: ${w}`);
+        upParts.push('');
+    }
+    upParts.push(up.text || '-- (no statements: schema already matches the database)');
+    const downText = hasReverse
+        ? down.text
+        : [
+            '-- irreversible, write manually',
+            '-- The diff produced no reversible statements for this change. Write the',
+            '-- rollback SQL by hand, or leave this section empty for a one-way migration.',
+        ].join('\n');
+    return {
+        up: upParts.join('\n'),
+        down: downText,
+        destructiveUp: up.destructive,
+        destructiveDown: down.destructive,
+    };
+}
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------

package/dist/client.d.ts

@@ -241,6 +241,16 @@ export interface TurbineConfig {
      * Default: `true`. Set to `false` as a nuclear kill switch.
      */
     sqlCache?: boolean;
+    /**
+     * Maximum number of distinct SQL templates each per-table LRU cache retains.
+     *
+     * Default: `1000`. Values are parameterized (`$1, $2, …`) and never fragment
+     * the cache, so this bounds distinct query SHAPES. Raise it for apps with a
+     * very large surface of query shapes to lift the hit rate at the cost of
+     * memory; lower it to cap memory. `0` disables caching entirely (identical to
+     * `sqlCache: false`); a negative value is ignored (treated as the default).
+     */
+    sqlCacheSize?: number;
     /** SQL dialect implementation. Defaults to PostgreSQL. Internal Phase-1 seam for dialect packages. */
     dialect?: Dialect;
     /**

package/dist/client.js

@@ -366,6 +366,7 @@ export class TurbineClient {
             globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
+            sqlCacheSize: config.sqlCacheSize,
             dialect: config.dialect,
             // Non-SQL backends (PowDB) inject a factory that builds their own query
             // interface (PowqlInterface) instead of the SQL QueryInterface. SQL engines

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
 export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';

package/dist/powql.js

@@ -38,7 +38,7 @@ import { randomUUID } from 'node:crypto';
 import { NotFoundError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError } from './errors.js';
 import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, coerceNativeValue, isJsonColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, powqlColumnType, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb.js';
-import { isJsonFilter, isRelationPickOrderBy } from './query/filters.js';
+import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
@@ -713,7 +713,7 @@ export class PowqlInterface {
     buildOrder(orderBy, params, alias) {
         if (!orderBy)
             return '';
-        const keys = Object.entries(orderBy).filter(([, dir]) => dir !== undefined);
+        const keys = orderByEntries(orderBy).filter(([, dir]) => dir !== undefined);
         if (!keys.length)
             return '';
         const parts = keys.map(([field, dir]) => {
@@ -2168,7 +2168,11 @@ export class PowqlInterface {
             }
             const having = this.buildHaving(args.having, params, aggInner);
             const order = this.buildGroupOrder(args.orderBy, byOrderExprs, aggOrderExprs);
-            const powql = `${this.qt}${filter} group ${groupExprs.join(', ')}${having}${order} { ${proj.join(', ')} }`;
+            // LIMIT / OFFSET over the result groups, applied after ORDER BY (mirrors
+            // the SQL groupBy). offset 0 is a no-op, matching findMany.
+            const limitClause = args.limit !== undefined ? ` limit ${this.param(args.limit, params)}` : '';
+            const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
+            const powql = `${this.qt}${filter} group ${groupExprs.join(', ')}${having}${order}${limitClause}${offsetClause} { ${proj.join(', ')} }`;
             const { rows, native: resultNative } = await this.exec(powql, params, args.timeout, 'groupBy');
             // Reshape: group keys → user fields (coerced / null-disambiguated),
             // aggregates → nested `{ _sum: { field } }`; discriminators are stripped.
@@ -2274,7 +2278,7 @@ export class PowqlInterface {
             return keys.join(', ') || '(none)';
         };
         const parts = [];
-        for (const [key, value] of Object.entries(orderBy)) {
+        for (const [key, value] of orderByEntries(orderBy)) {
             if (value === undefined)
                 continue;
             if (aggBlocks.has(key)) {

package/dist/query/aggregates.d.ts

@@ -25,7 +25,7 @@ export declare function buildGroupBy<T extends object>(qi: BuilderCtx, args: Gro
  * no `$n` renumbering). An aggregate key that was not requested, or an unknown
  * by-key, throws {@link ValidationError} E003 listing the valid keys.
  */
-export declare function buildGroupByOrderBy(qi: BuilderCtx, orderBy: GroupByOrderBy, byOrderExprs: Map<string, string>, aggOrderExprs: Map<string, string>): string;
+export declare function buildGroupByOrderBy(qi: BuilderCtx, orderBy: GroupByOrderBy | GroupByOrderBy[], byOrderExprs: Map<string, string>, aggOrderExprs: Map<string, string>): string;
 /**
  * Validate a JSON-path target (group key or aggregate target) in groupBy:
  * the field must resolve to a real json/jsonb column and the path must be a

package/dist/query/aggregates.js

@@ -10,7 +10,7 @@
  */
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { snakeToCamel } from '../schema.js';
-import { isJsonPathOrderBy, isVectorOrderBy, normalizeOrderBy } from './filters.js';
+import { isJsonPathOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries } from './filters.js';
 import * as whereMod from './where.js';
 export function buildGroupBy(qi, args) {
     const meta = qi.schema.tables[qi.table];
@@ -168,6 +168,16 @@ export function buildGroupBy(qi, args) {
         if (orderSql)
             sql += ` ORDER BY ${orderSql}`;
     }
+    // LIMIT / OFFSET over the result groups, applied AFTER ORDER BY. Routed
+    // through the dialect pagination hook (parameterized on PG/SQLite/SQL Server,
+    // inlined on MySQL); params append after the WHERE/HAVING/ORDER BY params, so
+    // no `$n` renumbering. `offset` without a deterministic `orderBy` yields an
+    // arbitrary window (same caveat as findMany).
+    if (args.limit !== undefined || args.offset !== undefined) {
+        const limitPh = args.limit !== undefined ? qi.paginationRef(args.limit, params) : undefined;
+        const offsetPh = args.offset !== undefined ? qi.paginationRef(args.offset, params) : undefined;
+        sql += qi.buildPagination(limitPh, offsetPh, args.orderBy !== undefined);
+    }
     return {
         sql,
         params,
@@ -255,7 +265,7 @@ export function buildGroupByOrderBy(qi, orderBy, byOrderExprs, aggOrderExprs) {
         return keys.join(', ') || '(none)';
     };
     const parts = [];
-    for (const [key, value] of Object.entries(orderBy)) {
+    for (const [key, value] of orderByEntries(orderBy)) {
         if (value === undefined)
             continue;
         // Aggregate ordering blocks.

package/dist/query/builder.d.ts

@@ -12,7 +12,7 @@
  */
 import type pg from 'pg';
 import type { SchemaMetadata } from '../schema.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, GroupByResult, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause } from './types.js';
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './deferred.js';
 import type { DeferredQuery, MiddlewareFn, QueryInterfaceOptions } from './deferred.js';
 export declare class QueryInterface<T extends object, R extends object = {}> {
@@ -20,7 +20,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly table;
     private readonly schema;
     private readonly tableMeta;
-    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
+    /**
+     * SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name).
+     * Capacity is set once in the constructor from `options.sqlCacheSize`
+     * (default 1000). See {@link QueryInterfaceOptions.sqlCacheSize}.
+     */
     private readonly sqlTemplateCache;
     /**
      * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
@@ -423,7 +427,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     }>;
     count(args?: CountArgs<T>): Promise<number>;
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
-    groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
+    /**
+     * Group rows and compute per-group aggregates (Prisma-style). The result row
+     * type is INFERRED from the args: each `by` field carries its entity field
+     * type, `_count` is always a number, and each requested `_sum` / `_avg` /
+     * `_min` / `_max` block maps its fields to properly typed values (see
+     * {@link GroupByResult}). Grouping by a JSON-path key yields a runtime alias
+     * that cannot be typed, so those columns are not projected onto the row type.
+     */
+    groupBy<A extends GroupByArgs<T>>(args: A): Promise<GroupByResult<T, A>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
     buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
     aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;

package/dist/query/builder.js

@@ -16,7 +16,7 @@ import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '..
 import { camelToSnake, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
 import { includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, stripFields, } from './batched-loader.js';
-import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, sortedEntries, } from './filters.js';
+import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
 import { LRUCache, ownLookup, parseDbDate, sqlToPreparedName } from './utils.js';
 import * as whereMod from './where.js';
@@ -149,8 +149,12 @@ export class QueryInterface {
     table;
     schema;
     tableMeta;
-    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
-    sqlTemplateCache = new LRUCache(1000);
+    /**
+     * SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name).
+     * Capacity is set once in the constructor from `options.sqlCacheSize`
+     * (default 1000). See {@link QueryInterfaceOptions.sqlCacheSize}.
+     */
+    sqlTemplateCache;
     /**
      * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
      * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
@@ -278,7 +282,13 @@ export class QueryInterface {
                 : warnOpt !== false;
         this.utcTimestamps = options?.utcTimestamps !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
-        this.sqlCacheEnabled = options?.sqlCache !== false;
+        // SQL template cache capacity. `sqlCacheSize: 0` disables caching entirely
+        // (mirrors `sqlCache: false`); any positive integer sets the LRU bound;
+        // undefined keeps the historical 1000-entry default. A negative value is
+        // treated as the default rather than throwing.
+        const sqlCacheSize = options?.sqlCacheSize;
+        this.sqlCacheEnabled = options?.sqlCache !== false && sqlCacheSize !== 0;
+        this.sqlTemplateCache = new LRUCache(sqlCacheSize !== undefined && sqlCacheSize > 0 ? Math.floor(sqlCacheSize) : 1000);
         this.dialect = options?.dialect ?? postgresDialect;
         this.relationLoadStrategy = options?.relationLoadStrategy ?? 'join';
         this.jsonEncoding = options?.jsonEncoding ?? 'object';
@@ -1074,7 +1084,7 @@ export class QueryInterface {
         // Checked BEFORE the SQL cache so build and warm-cache paths throw
         // identically (same rule as the vector guard inside the distinct branch).
         if (args?.distinct && args.distinct.length > 0 && args.orderBy) {
-            for (const d of Object.values(args.orderBy)) {
+            for (const [, d] of orderByEntries(args.orderBy)) {
                 if (this.isRelationOrderByValue(d)) {
                     throw new ValidationError('[turbine] `distinct` cannot be combined with relation orderBy (pick-row, `_count`, or ' +
                         'to-one relation ordering): the outer re-order cannot reference the parent table.');
@@ -1093,8 +1103,13 @@ export class QueryInterface {
         // Build fingerprint for cache lookup
         const whereFp = hasWhere ? this.fingerprintWhere(whereObj) : '';
         const withFp = args?.with ? this.withFingerprint(args.with) : '';
+        // Flatten via orderByEntries so the object form (`{ a, b }`) and the
+        // Prisma-style array form (`[{ a }, { b }]`) fingerprint from the SAME
+        // ordered entry list the build/collect paths consume. An array's element
+        // order is authoritative and preserved here, so a permuted array is a
+        // distinct key (correct, it emits a different ORDER BY).
         const orderFp = args?.orderBy
-            ? Object.entries(args.orderBy)
+            ? orderByEntries(args.orderBy)
                 .map(([k, d]) => `${k}:${this.orderByEntryFingerprint(d, ownLookup(this.tableMeta.relations, k)?.to)}`)
                 .join(',')
             : '';
@@ -1163,11 +1178,15 @@ export class QueryInterface {
                 // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
+                    // Resolve the seek direction per cursor field from the flattened
+                    // orderBy entries (last wins, matching object-key semantics), so both
+                    // the object and array orderBy forms drive the cursor comparison.
+                    const orderDirByKey = new Map(orderByEntries(args.orderBy));
                     const cursorConditions = cursorEntries.map(([k, v]) => {
                         const col = this.toSqlColumn(k);
                         // orderBy values can be the { sort, nulls } spec form: normalize
                         // before comparing, or a desc spec would seek the ascending side.
-                        const dir = args.orderBy?.[k];
+                        const dir = orderDirByKey.get(k);
                         const desc = isOrderBySpec(dir) ? dir.sort === 'desc' : dir === 'desc';
                         const op = desc ? '<' : '>';
                         freshParams.push(v);
@@ -1188,7 +1207,7 @@ export class QueryInterface {
                 // need two levels: inner DISTINCT ON ordered by the distinct columns then
                 // the user's order (picks the right representative row), outer re-ordered
                 // by the user's order alone.
-                if (Object.values(args.orderBy).some((d) => isVectorOrderBy(d))) {
+                if (orderByEntries(args.orderBy).some(([, d]) => isVectorOrderBy(d))) {
                     throw new ValidationError('[turbine] `distinct` cannot be combined with vector distance ordering.');
                 }
                 const userOrder = this.buildOrderBy(args.orderBy, freshParams);
@@ -1602,6 +1621,14 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     // groupBy (with aggregate functions)
     // -------------------------------------------------------------------------
+    /**
+     * Group rows and compute per-group aggregates (Prisma-style). The result row
+     * type is INFERRED from the args: each `by` field carries its entity field
+     * type, `_count` is always a number, and each requested `_sum` / `_avg` /
+     * `_min` / `_max` block maps its fields to properly typed values (see
+     * {@link GroupByResult}). Grouping by a JSON-path key yields a runtime alias
+     * that cannot be typed, so those columns are not projected onto the row type.
+     */
     async groupBy(args) {
         return this.executeWithMiddleware('groupBy', args, async () => {
             const deferred = this.buildGroupBy(args);
@@ -1768,7 +1795,7 @@ export class QueryInterface {
      * order exactly so the cached-SQL param re-collection stays in lockstep.
      */
     collectOrderByParams(orderBy, params) {
-        for (const [key, dir] of Object.entries(orderBy)) {
+        for (const [key, dir] of orderByEntries(orderBy)) {
             if (isVectorOrderBy(dir)) {
                 const rawColumn = this.toColumn(key);
                 // Re-run the same validation as buildOrderBy so the collect path can

package/dist/query/deferred.d.ts

@@ -107,6 +107,17 @@ export interface QueryInterfaceOptions {
      * unparseable value keeps the check fully off.
      */
     sqlCache?: boolean;
+    /**
+     * Maximum number of distinct SQL templates the per-table LRU cache retains.
+     *
+     * Default: `1000`. Raise it for apps with a very large number of distinct
+     * query SHAPES (not values, since values are parameterized and never fragment the
+     * cache) to lift the hit rate at the cost of memory; lower it to cap memory.
+     * `0` disables the cache entirely, exactly like `sqlCache: false`. A negative
+     * value is ignored (treated as the default). Applied per QueryInterface (one
+     * per table).
+     */
+    sqlCacheSize?: number;
     /** SQL dialect implementation. Defaults to PostgreSQL. */
     dialect?: Dialect;
     /**

package/dist/query/filters.d.ts

@@ -173,6 +173,23 @@ export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrde
  * ordering) are excluded up front.
  */
 export declare function isRelationPickOrderBy(value: unknown): value is RelationPickOrderBy;
+/**
+ * Flatten an orderBy input into an ordered list of `[field, value]` entries.
+ *
+ * Accepts BOTH the classic single-object form (`{ a: 'asc', b: 'desc' }`,
+ * whose insertion order is authoritative) and the Prisma-style array form
+ * (`[{ a: 'asc' }, { b: 'desc' }]`, whose array order is authoritative). The
+ * array form removes the reliance on JS object key iteration order for
+ * multi-key sorts. Each array element may carry one or more keys; they expand
+ * left-to-right. `undefined`/non-object elements are skipped.
+ *
+ * Undefined-VALUED entries are preserved (mirroring `Object.entries`) so each
+ * consumer keeps its own `dir !== undefined` filtering exactly as before. This
+ * is THE single flattening authority: every ORDER BY compile / collect /
+ * fingerprint path routes through it so the array and object forms stay in
+ * lockstep across build, param-collect, and cache-key fingerprint.
+ */
+export declare function orderByEntries(orderBy: unknown): [string, unknown][];
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/query/filters.js

@@ -332,6 +332,38 @@ export function isRelationPickOrderBy(value) {
     }
     return true;
 }
+/**
+ * Flatten an orderBy input into an ordered list of `[field, value]` entries.
+ *
+ * Accepts BOTH the classic single-object form (`{ a: 'asc', b: 'desc' }`,
+ * whose insertion order is authoritative) and the Prisma-style array form
+ * (`[{ a: 'asc' }, { b: 'desc' }]`, whose array order is authoritative). The
+ * array form removes the reliance on JS object key iteration order for
+ * multi-key sorts. Each array element may carry one or more keys; they expand
+ * left-to-right. `undefined`/non-object elements are skipped.
+ *
+ * Undefined-VALUED entries are preserved (mirroring `Object.entries`) so each
+ * consumer keeps its own `dir !== undefined` filtering exactly as before. This
+ * is THE single flattening authority: every ORDER BY compile / collect /
+ * fingerprint path routes through it so the array and object forms stay in
+ * lockstep across build, param-collect, and cache-key fingerprint.
+ */
+export function orderByEntries(orderBy) {
+    if (Array.isArray(orderBy)) {
+        const entries = [];
+        for (const element of orderBy) {
+            if (element !== null && typeof element === 'object' && !Array.isArray(element)) {
+                for (const kv of Object.entries(element))
+                    entries.push(kv);
+            }
+        }
+        return entries;
+    }
+    if (orderBy !== null && typeof orderBy === 'object') {
+        return Object.entries(orderBy);
+    }
+    return [];
+}
 /**
  * Normalize an orderBy value into `{ direction, nulls }`. Accepts a plain
  * direction string or an {@link OrderBySpec}. Used by every ORDER BY compile

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, HavingClause, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationPickBy, RelationPickOrderBy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationPickBy, RelationPickOrderBy, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';

package/dist/query/relations.js

@@ -16,7 +16,7 @@ import { CircularRelationError, RelationError, UnsupportedFeatureError, Validati
 import { missingIndexForRelation } from '../index-advisor.js';
 import { camelToSnake, normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import { resolveCountRelations } from './batched-loader.js';
-import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, normalizeOrderBy, sortedEntries, } from './filters.js';
+import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, normalizeOrderBy, orderByEntries, sortedEntries, } from './filters.js';
 import { ownLookup } from './utils.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -128,7 +128,7 @@ export function withFingerprint(qi, withClause, table, depth = 0) {
         // orderBy shape (OrderBySpec nulls placement changes the SQL, so fingerprint it)
         if (opts.orderBy) {
             const targetRels = qi.schema.tables[relDef.to]?.relations;
-            const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${orderByEntryFingerprint(qi, d, targetRels?.[k]?.to)}`);
+            const oEntries = orderByEntries(opts.orderBy).map(([k, d]) => `${k}:${orderByEntryFingerprint(qi, d, targetRels?.[k]?.to)}`);
             subParts.push(`o=${oEntries.join(',')}`);
         }
         // limit presence, but on inline-pagination engines (MySQL) the literal
@@ -191,7 +191,7 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
     //   orderBy params → where params → limit param → nested-with params
     //   (always, both paths).
     if (relDef.type === 'manyToMany') {
-        const m2mOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const m2mOrderEntries = spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
         if (nativeOrderPath && m2mOrderEntries.length > 0) {
             collectRelationOrderParams(qi, targetTable, targetMeta, m2mOrderEntries, params);
         }
@@ -213,7 +213,7 @@ export function collectRelationSubqueryParams(qi, relDef, spec, params, _parentR
         return;
     }
     // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
-    const relOrderEntries = spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const hasOrder = relOrderEntries.length > 0;
     const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
     // Non-wrapped path: nested relations BEFORE where/limit
@@ -317,7 +317,7 @@ export function buildOrderBy(qi, orderBy, params, lateralSink) {
     // orderBy keys (object values that are neither a vector nor an OrderBySpec)
     // are validated in the relation branch below, so skip them here.
     if (process.env.NODE_ENV !== 'production') {
-        for (const [key, value] of Object.entries(orderBy)) {
+        for (const [key, value] of orderByEntries(orderBy)) {
             if (isRelationOrderByValue(qi, value) && ownLookup(qi.tableMeta.relations, key))
                 continue;
             const snakeKey = camelToSnake(key);
@@ -329,7 +329,7 @@ export function buildOrderBy(qi, orderBy, params, lateralSink) {
     }
     const meta = qi.schema.tables[qi.table];
     let relOrdCounter = 0;
-    return Object.entries(orderBy)
+    return orderByEntries(orderBy)
         .map(([key, value]) => {
         // Vector KNN ordering: { distance: { to, metric, direction? } }
         if (isVectorOrderBy(value)) {
@@ -1381,7 +1381,7 @@ export function buildRelationSubquery(qi, relDef, spec, params, parentRef, alias
     // An orderBy with no defined entries (`orderBy: {}`) is treated as absent —
     // it must neither trigger the wrap (dropping nested relations) nor render a
     // dangling `ORDER BY `. `limit: 0` is meaningful (LIMIT 0) and DOES wrap.
-    const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = spec !== true && spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || relOrderEntries.length > 0);
     // manyToMany takes a dedicated JOIN-through-junction path. Nested relations,
     // where, orderBy, and select/omit are handled there (the target alias is the
@@ -1552,7 +1552,7 @@ export function buildManyToManySubquery(qi, relDef, spec, params, parentRef, ali
     // `orderBy: {}` (no defined entries) is treated as absent: it must not
     // render a dangling `ORDER BY `. Param pushes here land BEFORE the
     // spec.where params, mirrored by collectRelationSubqueryParams' m2m branch.
-    const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+    const relOrderEntries = spec !== true && spec.orderBy ? orderByEntries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
     let orderClause = '';
     if (relOrderEntries.length > 0) {
         orderClause = buildRelationOrderClause(qi, targetTable, targetMeta, talias, relOrderEntries, params);