turbine-orm 0.30.0 → 0.32.0

package/dist/query/filters.d.ts

@@ -5,7 +5,7 @@
  * compiler. Kept out of builder.ts so the class file stays about SQL assembly
  * and execution rather than filter-shape bookkeeping.
  */
-import type { ArrayFilter, JsonFilter, OrderBySpec, OrderDirection, TextSearchFilter, VectorFilter, VectorOrderBy, WhereOperator } from './types.js';
+import type { ArrayFilter, ColumnRef, JsonFilter, JsonPathOrderBy, OrderBySpec, OrderDirection, RelationPickOrderBy, TextSearchFilter, VectorFilter, VectorOrderBy, WhereOperator } from './types.js';
 /** Check if a value is a where operator object (has at least one known operator key) */
 export declare function isWhereOperator(value: unknown): value is WhereOperator;
 /**
@@ -15,11 +15,30 @@ export declare function isWhereOperator(value: unknown): value is WhereOperator;
  * bind values and return false, as do arrays and Dates.
  */
 export declare function isUnmatchedPlainObject(value: unknown): boolean;
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+export declare const COLUMN_REF_OPERATORS: Set<string>;
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+export declare function isColumnRef(value: unknown): value is ColumnRef;
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 export declare function fingerprintOperatorShape(value: WhereOperator): string;
 /**
@@ -127,6 +146,26 @@ export declare function isVectorFilter(value: unknown): value is VectorFilter;
 export declare function isVectorOrderBy(value: unknown): value is VectorOrderBy;
 /** Check if an orderBy value is an explicit `{ sort, nulls? }` spec. */
 export declare function isOrderBySpec(value: unknown): value is OrderBySpec;
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+export declare function isJsonPathOrderBy(value: unknown): value is JsonPathOrderBy;
+/**
+ * Check if an orderBy value is a pick-row relation ordering:
+ * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
+ * required — `pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * relation whose target has real columns literally named `pick` and `by`
+ * (whose values are direction strings or `{ sort, nulls }` specs, never an
+ * object with `orderBy`) still falls through to column ordering. `distance`
+ * (vector), `sort` (OrderBySpec), and a top-level array `path` (JSON-path
+ * ordering) are excluded up front.
+ */
+export declare function isRelationPickOrderBy(value: unknown): value is RelationPickOrderBy;
 /**
  * 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

@@ -36,17 +36,48 @@ export function isUnmatchedPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Operator keys that accept a {@link ColumnRef} (`{ col: 'otherField' }`)
+ * value for column-to-column comparison. `in`/`notIn` and the LIKE operators
+ * take values only.
+ */
+export const COLUMN_REF_OPERATORS = new Set(['equals', 'not', 'gt', 'gte', 'lt', 'lte']);
+/**
+ * Check if an operator value is a column reference: a plain object whose ONLY
+ * key is `col` with a string value. Anything else (extra keys, non-string
+ * `col`) is treated as a plain value so JSON payloads that merely contain a
+ * `col` property keep their equality meaning.
+ */
+export function isColumnRef(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && keys[0] === 'col' && typeof value.col === 'string';
+}
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
  * param pushed), so null-ness is part of the shape — without it a cache entry
  * warmed by `{ not: 5 }` would serve `{ not: null }` with a desynced param list.
+ *
+ * Column references ({@link ColumnRef}) compile the referenced column into the
+ * SQL TEXT (no param bound), so the referenced field name is part of the shape
+ *: `{ equals: { col: 'a' } }` and `{ equals: { col: 'b' } }` must never share
+ * a cache entry. The name is JSON-encoded so exotic field names cannot collide
+ * with other fingerprint tokens.
  */
 export function fingerprintOperatorShape(value) {
     const obj = value;
     const opKeys = Object.keys(obj)
         .filter((k) => k !== 'mode')
-        .map((k) => ((k === 'equals' || k === 'not') && obj[k] === null ? `${k}:null` : k))
+        .map((k) => {
+        const v = obj[k];
+        if ((k === 'equals' || k === 'not') && v === null)
+            return `${k}:null`;
+        if (COLUMN_REF_OPERATORS.has(k) && isColumnRef(v))
+            return `${k}:col(${JSON.stringify(v.col)})`;
+        return k;
+    })
         .sort();
     const modeStr = value.mode === 'insensitive' ? ':i' : '';
     return `op(${opKeys.join(',')}${modeStr})`;
@@ -249,6 +280,47 @@ export function isVectorOrderBy(value) {
 export function isOrderBySpec(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) && 'sort' in value;
 }
+/**
+ * Check if an orderBy value is a JSON-path ordering: `{ path: [...] }` with an
+ * ARRAY path. The array requirement disambiguates from relation orderBy values
+ * (whose entries are directions/specs keyed by target column: a target column
+ * literally named `path` maps to a string direction, never an array), and the
+ * `distance`/`sort` exclusions keep vector and spec shapes out.
+ */
+export function isJsonPathOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value)
+        return false;
+    return Array.isArray(value.path);
+}
+/**
+ * Check if an orderBy value is a pick-row relation ordering:
+ * `{ pick: { orderBy, ... }, by, direction?, nulls? }`. The full shape is
+ * required — `pick` must be an object carrying `orderBy`, `by` must be
+ * present, and no keys outside `{ pick, by, direction, nulls }` — so a to-one
+ * relation whose target has real columns literally named `pick` and `by`
+ * (whose values are direction strings or `{ sort, nulls }` specs, never an
+ * object with `orderBy`) still falls through to column ordering. `distance`
+ * (vector), `sort` (OrderBySpec), and a top-level array `path` (JSON-path
+ * ordering) are excluded up front.
+ */
+export function isRelationPickOrderBy(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if ('distance' in value || 'sort' in value || Array.isArray(value.path))
+        return false;
+    const v = value;
+    if (!('pick' in v) || !('by' in v))
+        return false;
+    if (typeof v.pick !== 'object' || v.pick === null || Array.isArray(v.pick) || !('orderBy' in v.pick))
+        return false;
+    for (const key of Object.keys(v)) {
+        if (key !== 'pick' && key !== 'by' && key !== 'direction' && key !== 'nulls')
+            return false;
+    }
+    return true;
+}
 /**
  * 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, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, 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, 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 { 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/types.d.ts

@@ -18,20 +18,48 @@ export type OrderDirection = 'asc' | 'desc';
  * Precedence: per-query arg > client `relationLoadStrategy` config > `'join'`.
  */
 export type RelationLoadStrategy = 'join' | 'batched';
+/**
+ * Reference to ANOTHER COLUMN of the same table inside a where operator,
+ * enabling column-to-column comparison:
+ *
+ * ```ts
+ * where: { currentVersionId: { equals: { col: 'publishedVersionId' } } }
+ * // → WHERE "current_version_id" = "published_version_id"
+ * ```
+ *
+ * Accepted by `equals`, `not`, `gt`, `gte`, `lt`, and `lte`. The referenced
+ * field resolves through the table's columnMap (camelCase accepted, same as a
+ * where key) and compiles to a quoted identifier: NO parameter is bound.
+ * An unknown referenced field throws {@link ValidationError} (E003).
+ *
+ * Notes:
+ *  - `mode: 'insensitive'` cannot be combined with a column reference: it
+ *    throws E003 (use `client.sql` for `lower(a) = lower(b)`).
+ *  - On json/jsonb columns `equals` routes to the JSONB containment filter
+ *    first, so `{ equals: { col } }` there is treated as a JSON value, not a
+ *    column reference.
+ *
+ * `F` narrows the referenced name to the table's field names when the
+ * surrounding {@link WhereClause} knows the entity type.
+ */
+export interface ColumnRef<F extends string = string> {
+    col: F;
+}
 /** Operator object for advanced where filtering */
-export interface WhereOperator<V = unknown> {
+export interface WhereOperator<V = unknown, F extends string = string> {
     /**
      * Explicit equality: `{ equals: value }` → `column = $n`.
      * `{ equals: null }` → `column IS NULL`.
+     * `{ equals: { col: 'otherField' } }` → `column = "other_field"` ({@link ColumnRef}).
      * On json/jsonb columns `equals` routes to the JSONB containment filter
      * ({@link JsonFilter}) instead.
      */
-    equals?: V | null;
-    gt?: V;
-    gte?: V;
-    lt?: V;
-    lte?: V;
-    not?: V | null;
+    equals?: V | ColumnRef<F> | null;
+    gt?: V | ColumnRef<F>;
+    gte?: V | ColumnRef<F>;
+    lt?: V | ColumnRef<F>;
+    lte?: V | ColumnRef<F>;
+    not?: V | ColumnRef<F> | null;
     in?: V[];
     notIn?: V[];
     contains?: string;
@@ -50,7 +78,7 @@ export interface WhereOperator<V = unknown> {
  * - A text search filter object ({ search, config? })
  * - A vector distance filter object ({ distance: { to, metric, lt } }) for pgvector columns
  */
-export type WhereValue<V = unknown> = (V extends Array<infer U> ? TypedRelationFilter<U> : V extends Date ? V : V extends object ? V | TypedToOneFilter<V> | WhereClause<V> : V) | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
+export type WhereValue<V = unknown, F extends string = string> = (V extends Array<infer U> ? TypedRelationFilter<U> : V extends Date ? V : V extends object ? V | TypedToOneFilter<V> | WhereClause<V> : V) | WhereOperator<V, F> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
 /** Relation filter on a to-many relation property. */
 export interface TypedRelationFilter<U> {
     some?: WhereClause<U>;
@@ -71,7 +99,7 @@ export interface TypedToOneFilter<V> {
  * Relation names can be used with some/every/none sub-filters.
  */
 export type WhereClause<T> = {
-    [K in keyof T]?: WhereValue<T[K]>;
+    [K in keyof T]?: WhereValue<T[K], Extract<keyof T, string>>;
 } & {
     OR?: WhereClause<T>[];
     AND?: WhereClause<T>[];
@@ -148,7 +176,7 @@ export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ?
 export interface WithOptions<NestedR extends object = {}> {
     with?: TypedWithClause<NestedR>;
     where?: Record<string, unknown>;
-    orderBy?: Record<string, OrderDirection | OrderBySpec>;
+    orderBy?: Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy | RelationOrderBy>;
     limit?: number;
     /** Only include these fields from the relation */
     select?: Record<string, boolean>;
@@ -568,20 +596,87 @@ export type HavingClause<T> = {
 } & {
     [K in keyof T & string]?: HavingAggregateFilter;
 };
+/**
+ * A JSON-path group key in {@link GroupByArgs.by}: groups by the value
+ * extracted at `path` from a json/jsonb column. Emits
+ * `(col #>> $n::text[]) AS "alias"` in SELECT and the same expression in
+ * GROUP BY (the path is bound as one text[] param, never interpolated).
+ * Result rows key by `alias` (default: the last path segment; a collision
+ * with another result key throws {@link ValidationError} E003).
+ */
+export interface JsonPathGroupKey {
+    /** json/jsonb column (camelCase field name, columnMap-resolved). */
+    field: string;
+    /** JSON path into the column (each element a key or array index). Bound as one text[] param. */
+    path: (string | number)[];
+    /** Result key for the group value. Defaults to the last path segment. */
+    alias?: string;
+}
+/**
+ * A JSON-path aggregate target inside `_sum` / `_avg` / `_min` / `_max` of
+ * {@link GroupByArgs}: aggregates the value extracted at `path` from a
+ * json/jsonb column, e.g. `SUM((col #>> $n::text[])::numeric)`. The arg key
+ * is the result alias. `_sum`/`_avg` always cast numeric (a text sum is
+ * meaningless); `_min`/`_max` compare as text unless `type: 'numeric'`.
+ */
+export interface JsonPathAggregateTarget {
+    /** json/jsonb column (camelCase field name, columnMap-resolved). */
+    field: string;
+    /** JSON path into the column (each element a key or array index). Bound as one text[] param. */
+    path: (string | number)[];
+    /** Comparison/aggregation kind. `_sum`/`_avg` are always numeric; `_min`/`_max` default to text. */
+    type?: 'numeric' | 'text';
+}
+/**
+ * Per-aggregate spec map for `_sum` / `_avg` / `_min` / `_max` in
+ * {@link GroupByArgs}: `true` keeps the existing plain-column behavior (the
+ * key is a column field name); a {@link JsonPathAggregateTarget} aggregates a
+ * JSON path (the key doubles as the result alias).
+ */
+export type GroupByAggregateSpec<T> = Partial<Record<keyof T & string, boolean>> | Record<string, boolean | JsonPathAggregateTarget>;
+/**
+ * DISTINCT ON row source for {@link GroupByArgs} (PostgreSQL only: other
+ * engines throw {@link UnsupportedFeatureError} E017): the groupBy runs over
+ * one representative row per `columns` combination instead of the raw table.
+ *
+ * ```sql
+ * FROM (
+ *   SELECT DISTINCT ON ("instance_id") * FROM "versions"
+ *   WHERE <args.where> ORDER BY "instance_id", "created_at" DESC
+ * ) AS "versions"
+ * ```
+ *
+ * `orderBy` is REQUIRED (it decides which row survives per combination:
+ * without it the picked row would be nondeterministic); the wrapper ORDER BY
+ * is `columns` first, then this orderBy. `args.where` applies INSIDE the
+ * wrapper (filter before picking).
+ */
+export interface GroupByDistinctOn<T> {
+    /** DISTINCT ON columns: one surviving row per combination. */
+    columns: (keyof T & string)[];
+    /** Which row survives per combination (required for determinism). */
+    orderBy: Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy>;
+}
 export interface GroupByArgs<T> {
-    by: (keyof T & string)[];
+    /** Group keys: plain column field names and/or JSON-path keys ({@link JsonPathGroupKey}). */
+    by: ((keyof T & string) | JsonPathGroupKey)[];
     where?: WhereClause<T>;
+    /**
+     * PostgreSQL only: group over one representative row per column combination
+     * (`SELECT DISTINCT ON … ORDER BY …` row source). See {@link GroupByDistinctOn}.
+     */
+    distinctOn?: GroupByDistinctOn<T>;
     /** Include count of each group */
     _count?: true;
-    /** Sum of numeric fields in each group */
-    _sum?: Partial<Record<keyof T & string, boolean>>;
-    /** Average of numeric fields in each group */
-    _avg?: Partial<Record<keyof T & string, boolean>>;
-    /** Minimum value of fields in each group */
-    _min?: Partial<Record<keyof T & string, boolean>>;
-    /** Maximum value of fields in each group */
-    _max?: Partial<Record<keyof T & string, boolean>>;
-    /** Filter whole groups by their aggregate values (SQL HAVING). */
+    /** Sum of numeric fields (or JSON paths: see {@link JsonPathAggregateTarget}) in each group */
+    _sum?: GroupByAggregateSpec<T>;
+    /** Average of numeric fields (or JSON paths) in each group */
+    _avg?: GroupByAggregateSpec<T>;
+    /** Minimum value of fields (or JSON paths) in each group */
+    _min?: GroupByAggregateSpec<T>;
+    /** Maximum value of fields (or JSON paths) in each group */
+    _max?: GroupByAggregateSpec<T>;
+    /** Filter whole groups by their aggregate values (SQL HAVING). JSON-path aggregates key by their alias. */
     having?: HavingClause<T>;
     /** Order groups (supports {@link OrderBySpec} for NULLS placement). */
     orderBy?: Record<string, OrderDirection | OrderBySpec>;
@@ -741,6 +836,32 @@ export interface OrderBySpec {
     sort: OrderDirection;
     nulls?: 'first' | 'last';
 }
+/**
+ * Ordering by a JSON path on a json/jsonb column of the SAME table:
+ *
+ * ```ts
+ * orderBy: { data: { path: ['weight'], direction: 'asc', type: 'numeric' } }
+ * // → ORDER BY ("data" #>> $n::text[])::numeric ASC
+ * ```
+ *
+ * The path is bound as a single text[] parameter (never interpolated).
+ * Comparison rule: values extracted from the path compare as TEXT by default;
+ * pass `type: 'numeric'` to cast for numeric comparison (`::numeric` on
+ * PostgreSQL). The column must be json/jsonb: anything else throws
+ * {@link ValidationError} (E003). Non-Postgres engines route through the same
+ * dialect JSON-extract hook the JSON where-filters use. Cross-relation
+ * (lateral) JSON ordering is NOT supported: same-table columns only.
+ */
+export interface JsonPathOrderBy {
+    /** JSON path into the column (each element a key or array index). Bound as one text[] param. */
+    path: (string | number)[];
+    /** Sort direction. Defaults to `'asc'`. */
+    direction?: OrderDirection;
+    /** Comparison kind for the extracted value. Defaults to `'text'`; `'numeric'` adds a numeric cast. */
+    type?: 'numeric' | 'text';
+    /** NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}). */
+    nulls?: 'first' | 'last';
+}
 /**
  * Ordering by a relation, keyed by the relation name in an {@link OrderByClause}:
  *
@@ -753,13 +874,83 @@ export interface OrderBySpec {
 export type RelationOrderBy = {
     _count: OrderDirection;
 } | Record<string, OrderDirection | OrderBySpec>;
+/**
+ * The ordering value extracted from the picked row in a
+ * {@link RelationPickOrderBy}: either a plain target column name (camelCase,
+ * columnMap-resolved) or a JSON path into a json/jsonb target column.
+ * Values extracted from a JSON path compare as TEXT by default; pass
+ * `type: 'numeric'` to add a numeric cast.
+ */
+export type RelationPickBy = string | {
+    /** json/jsonb column on the relation target. */
+    field: string;
+    /**
+     * JSON path into the column (each element a key or array index). Bound
+     * as ONE param: a text[] on PostgreSQL, a `'$'`-rooted JSONPath string
+     * on engines whose JSON functions take one (SQLite/MySQL/SQL Server).
+     */
+    path: (string | number)[];
+    /** Comparison kind for the extracted value. Defaults to `'text'`. */
+    type?: 'numeric' | 'text';
+};
+/**
+ * Pick-row relation ordering: order a parent query by a value read from ONE
+ * related row of a hasMany relation, keyed by the relation name in an
+ * {@link OrderByClause}. Compiles to a correlated scalar subquery in ORDER BY:
+ *
+ * ```ts
+ * orderBy: {
+ *   versions: {
+ *     pick: { orderBy: { createdAt: 'desc' } }, // which related row
+ *     by: { field: 'data', path: ['title'] },   // value to sort the parents by
+ *     direction: 'asc',
+ *     nulls: 'last',
+ *   },
+ * }
+ * // → ORDER BY (SELECT ord0."data" #>> $n::text[] FROM "versions" ord0
+ * //             WHERE ord0."instance_id" = "instances"."id"
+ * //             ORDER BY ord0."created_at" DESC LIMIT 1) ASC NULLS LAST
+ * ```
+ *
+ * `pick.orderBy` is REQUIRED (it makes the picked row deterministic) and
+ * supports the same surface as a relation `with` orderBy on the target (plain
+ * columns, {@link OrderBySpec} nulls, {@link JsonPathOrderBy}). `pick.where`
+ * optionally filters the candidate rows before picking. hasMany relations
+ * only; top-level findMany orderBy only (manyToMany, to-one relations, and
+ * nested `with` orderBy throw {@link ValidationError} E003).
+ */
+export interface RelationPickOrderBy {
+    /** Which related row supplies the value. */
+    pick: {
+        /** Inner ORDER BY choosing the row (required for determinism). */
+        orderBy: Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy>;
+        /** Optional filter on the candidate rows before picking. */
+        where?: Record<string, unknown>;
+    };
+    /** The value on the picked row to order the parents by. */
+    by: RelationPickBy;
+    /** Sort direction for the parents. Defaults to `'asc'`. */
+    direction?: OrderDirection;
+    /**
+     * NULLS placement (PostgreSQL / SQLite only: see {@link OrderBySpec}).
+     *
+     * A parent with NO related rows sorts by NULL. When `nulls` is not set,
+     * pick ordering defaults to `NULLS LAST` in BOTH directions, so parents
+     * with zero related rows always come last (Postgres's own DESC default is
+     * NULLS FIRST, which would put every childless parent at the top of a
+     * "highest first" sort). Set `nulls` explicitly to override.
+     */
+    nulls?: 'first' | 'last';
+}
 /**
  * An orderBy clause maps each key to one of:
  *  - a plain direction (`'asc'` / `'desc'`),
  *  - an {@link OrderBySpec} (`{ sort, nulls }`) for NULLS placement,
+ *  - for json/jsonb columns, a JSON-path ordering ({@link JsonPathOrderBy}),
  *  - for pgvector columns, a KNN distance ordering ({@link VectorOrderBy}),
  *  - for a relation name, a {@link RelationOrderBy} (`_count` for to-many, a
- *    target column for to-one).
+ *    target column for to-one) or a pick-row ordering
+ *    ({@link RelationPickOrderBy}, hasMany only).
  */
-export type OrderByClause = Record<string, OrderDirection | OrderBySpec | VectorOrderBy | RelationOrderBy>;
+export type OrderByClause = Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy | VectorOrderBy | RelationOrderBy | RelationPickOrderBy>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {