turbine-orm 0.30.0 → 0.31.0

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,20 @@ 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);
+}
 /**
  * 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, GroupByArgs, HavingClause, JsonFilter, JsonPathOrderBy, 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 { 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>;
@@ -741,6 +769,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}:
  *
@@ -757,9 +811,10 @@ export type RelationOrderBy = {
  * 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).
  */
-export type OrderByClause = Record<string, OrderDirection | OrderBySpec | VectorOrderBy | RelationOrderBy>;
+export type OrderByClause = Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy | VectorOrderBy | RelationOrderBy>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.30.0",
+  "version": "0.31.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": {