turbine-orm 0.77.1 → 0.78.0

package/dist/query/types.d.ts

@@ -200,7 +200,13 @@ export interface WhereOperator<V = unknown, F extends string = string> {
     contains?: string;
     startsWith?: string;
     endsWith?: string;
-    /** Set to 'insensitive' to use ILIKE instead of LIKE for string comparisons */
+    /**
+     * `'insensitive'` makes the comparison case-insensitive on a string column:
+     * `contains` / `startsWith` / `endsWith` use ILIKE (or the dialect's
+     * equivalent), and `equals` (or a bare value), `not`, `in` and `notIn` fold
+     * case on both sides (`LOWER(...)`). A `mode` beside a non-string operand
+     * throws `ValidationError` (E003).
+     */
     mode?: 'default' | 'insensitive';
 }
 /**
@@ -988,8 +994,15 @@ export interface DeleteManyArgs<T, R extends object = {}> {
 }
 export interface UpsertArgs<T, R extends object = {}> {
     where: WhereClause<T, R>;
+    /** The row to insert when `where` matches nothing. Plain values only: there is no stored value to operate on yet. */
     create: Partial<T>;
-    update: Partial<T>;
+    /**
+     * Applied to the existing row on conflict. Each field takes a plain value or
+     * the same atomic {@link UpdateOperatorInput} `update()` takes, so
+     * `count: { increment: 1 }` adds to the stored value instead of overwriting
+     * it. Scalar fields only: nested relation writes are not part of an upsert.
+     */
+    update: UpdateInput<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */
@@ -1306,16 +1319,21 @@ type GroupByKeys<A> = A extends {
 /** The subset of `by` keys that are plain string field names on the entity `T`. */
 type GroupByFieldKeys<T, A> = Extract<GroupByKeys<A>, keyof T & string>;
 /**
- * `_sum` / `_avg` result block: every requested key maps to `number | null`
- * (an aggregate over zero matching rows is null). Present only when the args
- * actually requested the block. A JSON-path aggregate target keys by its arg
- * key (the alias), so `keyof S` covers both plain columns and JSON aliases.
+ * `_sum` / `_avg` result block: every requested key maps to
+ * `number | string | null`. A `string` comes back for an int8 / bigint or
+ * numeric / decimal source column, whose SUM and AVG PostgreSQL widens to
+ * arbitrary-precision `numeric` and whose exact text is returned to avoid
+ * precision loss (see {@link AggregateResult}); every other column, and every
+ * JSON-path aggregate, is a `number`; `null` is an aggregate over zero
+ * matching rows. Present only when the args actually requested the block. A
+ * JSON-path aggregate target keys by its arg key (the alias), so `keyof S`
+ * covers both plain columns and JSON aliases.
  */
 type GroupBySumAvgPart<A, Key extends '_sum' | '_avg'> = A extends {
     [P in Key]: infer S;
 } ? [S] extends [object] ? {
     [P in Key]: {
-        [K in keyof S & string]: number | null;
+        [K in keyof S & string]: number | string | null;
     };
 } : unknown : unknown;
 /**
@@ -1404,11 +1422,20 @@ export interface AggregateArgs<T, R extends object = {}> {
     /** Plan this query with its real parameter values. See {@link FindManyArgs.forceCustomPlan}. */
     forceCustomPlan?: boolean;
 }
-/** Result type for aggregate queries */
+/**
+ * Result type for aggregate queries.
+ *
+ * `_sum` / `_avg` are a `number` for int2 / int4 / float columns and a
+ * `string` for int8 / bigint and numeric / decimal columns: PostgreSQL widens
+ * SUM and AVG over those to arbitrary-precision `numeric`, and the exact text
+ * is returned to avoid precision loss, the same policy under which a `numeric`
+ * column value and an int8 value above 2^53 - 1 read back as strings. `null`
+ * is an aggregate over zero rows.
+ */
 export interface AggregateResult<T> {
     _count?: number | Record<string, number>;
-    _sum?: Partial<Record<keyof T & string, number | null>>;
-    _avg?: Partial<Record<keyof T & string, number | null>>;
+    _sum?: Partial<Record<keyof T & string, number | string | null>>;
+    _avg?: Partial<Record<keyof T & string, number | string | null>>;
     _min?: Partial<Record<keyof T & string, unknown>>;
     _max?: Partial<Record<keyof T & string, unknown>>;
 }
@@ -1618,10 +1645,37 @@ export interface JsonPathOrderBy {
  *  - to-one (belongsTo / hasOne): `{ author: { name: 'asc' } }`, orders by a
  *    correlated scalar subquery on the target column (an {@link OrderBySpec} with
  *    `nulls` is accepted too).
+ *  - a CHAIN of to-one hops: `{ author: { organization: { name: 'asc' } } }`.
+ *    Each further hop is a JOIN inside that same subquery, so the chain costs
+ *    one subquery whatever its length. The type admits a head relation plus
+ *    ten chained hops, eleven relation keys in all, which is exactly where the
+ *    builder stops (`MAX_ORDER_BY_RELATION_HOPS` in query/relations.ts, the
+ *    nested-`with` cap; a twelfth hop is E007). The bound is a countdown
+ *    through a fixed table rather than an unbounded self reference, so `tsc`
+ *    never has to report an excessively deep instantiation.
+ *
+ * The chain is keyed by `string`, not by the target's relation map, so it
+ * cannot tell a to-many hop from a to-one one: `{ author: { posts: { title } } }`
+ * typechecks and is refused by the builder with E003 (a to-many relation has
+ * no single value to order by; {@link RelationPickOrderBy} exists for that).
+ * Everything else about the shape is checked: a value at any depth is a
+ * direction, a `{ sort, nulls }` spec, or the next hop.
  */
 export type RelationOrderBy = {
     _count: OrderDirection;
-} | Record<string, OrderDirection | OrderBySpec>;
+} | RelationOrderByChain<10>;
+/**
+ * The to-one branch of {@link RelationOrderBy}: a map from a target column to
+ * a direction or an {@link OrderBySpec}, or from a further to-one relation to
+ * the next link, with `Hops` links still allowed beneath this one. At `0` the
+ * next link is `never`, so only columns remain.
+ */
+export type RelationOrderByChain<Hops extends number> = Record<string, OrderDirection | OrderBySpec | ([Hops] extends [0] ? never : RelationOrderByChain<RelationOrderByHopsLeft[Hops]>)>;
+/**
+ * `RelationOrderByHopsLeft[n]` is `n - 1`. Index 0 holds `never` and is never
+ * read: {@link RelationOrderByChain} stops before indexing it.
+ */
+type RelationOrderByHopsLeft = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
 /**
  * The ordering value extracted from the picked row in a
  * {@link RelationPickOrderBy}: either a plain target column name (camelCase,

package/dist/query/where.d.ts

@@ -181,22 +181,28 @@ interface ColumnRefContext {
 /**
  * A table-scoped WHERE compilation context for a sub-where that is NOT the
  * top-level `this.tableMeta` clause. Both relation-filter `EXISTS` sub-wheres
- * (correlated against the bare target table, `"target".col`) and relation
- * `with`-clause `where` filters (against a per-subquery alias, `t0.col`) compile
- * an arbitrary target table's where against a column qualifier. They differ ONLY
- * in that qualifier, the correlation parent handed to `buildRelationFilter`, and
- * the unknown-column error wording, so a single scoped build/collect/fingerprint
- * trio, driven by the SAME canonical {@link walkWhere} the top level uses, serves
- * both. See `buildScopedWhere` / `collectScopedWhereParams` / `fingerprintScopedWhere`.
+ * (correlated against the subquery's FROM item, the bare target table
+ * `"target".col` or its `rf0.col` alias, see {@link buildRelationFilter}) and
+ * relation `with`-clause `where` filters (against a per-subquery alias, `t0.col`)
+ * compile an arbitrary target table's where against a column qualifier. They
+ * differ ONLY in that qualifier, the correlation parent handed to
+ * `buildRelationFilter`, and the unknown-column error wording, so a single
+ * scoped build/collect/fingerprint trio, driven by the SAME canonical
+ * {@link walkWhere} the top level uses, serves both. See `buildScopedWhere` /
+ * `collectScopedWhereParams` / `fingerprintScopedWhere`.
  */
 interface WhereScope {
     /** The target table's metadata (column map, relations, types). */
     meta: TableMetadata;
     /** The target table name (used for host binding + error messages). */
     table: string;
-    /** SQL prefix before `q(col)`, `"target".` for EXISTS sub-wheres, `t0.` for aliases. */
+    /** SQL prefix before `q(col)`: the FROM item's reference (`"target".` / `rf0.` / `t0.`) plus a dot. */
     qualifier: string;
-    /** The `parentTable` correlation argument for nested `buildRelationFilter` calls. */
+    /**
+     * The RENDERED parent reference handed to nested `buildRelationFilter` calls
+     * as `parentRef`: the same reference `qualifier` is built from, so a nested
+     * filter correlates to the row this scope is compiling against.
+     */
     relationParent: string;
     /** {@link WhereHost} bound to `meta`, so {@link walkWhere} enumerates this scope's keys. */
     host: WhereHost;
@@ -321,12 +327,12 @@ export declare function targetGlobalFilterAlias(qi: BuilderCtx, targetTable: str
 /** Param-collect mirror of {@link targetGlobalFilterAlias}. */
 export declare function collectTargetGlobalFilterAlias(qi: BuilderCtx, targetTable: string, params: unknown[]): void;
 /**
- * SQL clause for `targetTable`'s global filter rendered against the bare
- * (unaliased) table name, the form used inside relation-filter `EXISTS`
- * subqueries. Pushes its params; `''` when none. Mirror:
- * {@link collectTargetGlobalFilterExists}.
+ * SQL clause for `targetTable`'s global filter rendered against `targetRef`,
+ * the relation-filter `EXISTS` subquery's FROM item (the bare table name, or
+ * its alias when {@link buildRelationFilter} had to alias it). Pushes its
+ * params; `''` when none. Mirror: {@link collectTargetGlobalFilterExists}.
  */
-export declare function targetGlobalFilterExists(qi: BuilderCtx, targetTable: string, params: unknown[]): string;
+export declare function targetGlobalFilterExists(qi: BuilderCtx, targetTable: string, targetRef: string, params: unknown[]): string;
 /** Param-collect mirror of {@link targetGlobalFilterExists}. */
 export declare function collectTargetGlobalFilterExists(qi: BuilderCtx, targetTable: string, params: unknown[]): void;
 /**
@@ -372,10 +378,47 @@ export declare function buildScalarClause(qi: BuilderCtx, key: string, value: un
  */
 export declare function emptyRelationsHost(qi: BuilderCtx, table: string): WhereHost;
 export declare function scopedWhereHost(qi: BuilderCtx, meta: TableMetadata): WhereHost;
-/** Build the scope for a relation-filter EXISTS sub-where over the bare target table. */
-export declare function relationWhereScope(qi: BuilderCtx, targetTable: string, meta: TableMetadata): WhereScope;
-/** Build the scope for a relation `with`-clause `where` compiled against `alias`. */
+/**
+ * Build the scope for a relation-filter EXISTS sub-where. `targetRef` is the
+ * subquery's FROM item as the SQL refers to it: the quoted target table, or the
+ * alias {@link buildRelationFilter} gave it when the bare name would have been
+ * captured by the correlation. Every column the sub-where names, and every
+ * nested relation filter's correlation parent, is qualified by that same
+ * reference, so the two can never point at different rows.
+ */
+export declare function relationWhereScope(qi: BuilderCtx, targetTable: string, meta: TableMetadata, targetRef: string): WhereScope;
+/**
+ * Build the scope for a relation `with`-clause `where` compiled against
+ * `alias`. The alias is BARE (`t0`), never a rendered reference: this scope
+ * quotes it itself for the nested-relation correlation parent, so a caller
+ * that hands over an already-quoted name gets `"""posts"""` inside an EXISTS
+ * body and a 42P01 that names the table three times. That happened twice, on
+ * two independent paths, from the same one-parameter-two-meanings ambiguity,
+ * so the ambiguity is refused here rather than corrected at each call site.
+ * A caller that genuinely holds a rendered reference wants
+ * {@link renderedRefWhereScope}.
+ */
 export declare function aliasWhereScope(qi: BuilderCtx, targetTable: string, meta: TableMetadata, alias: string): WhereScope;
+/**
+ * The scope for a `where` compiled against an ALREADY-RENDERED FROM-item
+ * reference: `"users"` inside `ON CONFLICT ... DO UPDATE`, or the quoted child
+ * table a batched follow-up selects from. One parameter with one meaning, used
+ * verbatim for the column qualifier AND for a nested relation filter's
+ * correlation parent, which is exactly the pair {@link aliasWhereScope} gets
+ * wrong when it is handed a rendered reference.
+ *
+ * It is {@link relationWhereScope} with the unknown-column wording of a plain
+ * `where`, because the filters compiled through it are `globalFilters` entries
+ * and a misconfigured one should read the same here as it does on the `update`
+ * path.
+ */
+export declare function renderedRefWhereScope(qi: BuilderCtx, targetTable: string, meta: TableMetadata, targetRef: string): WhereScope;
+/**
+ * Compile `where` against an already-rendered FROM-item reference. The seam
+ * both global-filter callers that hold one go through, so neither can reach
+ * {@link aliasWhereScope} by mistake again.
+ */
+export declare function buildRenderedRefWhere(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, targetRef: string, where: Record<string, unknown>, params: unknown[]): string | null;
 /**
  * Compile a scoped sub-where to SQL. Serves BOTH the relation-filter EXISTS
  * body ({@link buildSubWhereForRelation}) and the relation `with`-clause
@@ -415,8 +458,31 @@ export declare function fingerprintScopedWhere(qi: BuilderCtx, host: WhereHost,
 /**
  * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
  * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
+ *
+ * NAME CAPTURE, and the aliasing rule that closes it. The subquery correlates
+ * its FROM item to the parent row (`target.fk = parent.pk`). When the target
+ * is named bare and the parent reference is that same bare name, a
+ * self-referencing relation (`comments.parent_id -> comments.id`) compiles
+ * `"comments"."parent_id" = "comments"."id"`, and SQL resolves BOTH sides to
+ * the inner row: `some: {}` matched nothing, `none: {}` matched everything,
+ * `is: null` matched every row, and the defect propagated through nested
+ * filters and into the batched loader's follow-up query (which is a top-level
+ * findMany on the child table). So the FROM item is aliased EXACTLY when its
+ * quoted name equals `parentRef`, and the alias is then used for the
+ * correlation, the sub-where qualifier, the global-filter fragment and as the
+ * parent reference of nested filters. Every other relation filter keeps the
+ * bare-table template it always emitted, byte for byte. The rule is complete
+ * rather than a heuristic: the only reference the inner FROM item can capture
+ * is one that spells its own name, and a nested level whose parent is already
+ * an alias (`rf0`, `t0`, `ord0`) has no such reference to capture. The
+ * junction of a manyToMany branch gets the same treatment for the same reason.
+ *
+ * `parentRef` is the RENDERED reference of the row being correlated against:
+ * the quoted table at the top level (`undefined` here), an alias inside a
+ * relation `with` where (`"t0"`), or the enclosing filter's FROM reference for
+ * a nested relation filter.
  */
-export declare function buildRelationFilter(qi: BuilderCtx, _relName: string, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], parentTable?: string, 
+export declare function buildRelationFilter(qi: BuilderCtx, _relName: string, relDef: RelationDef, filterObj: Record<string, unknown>, params: unknown[], parentRef?: string, 
 /**
  * Nesting depth of the WHERE walk that reached this relation filter. Each
  * relation descent is a level too: `{ posts: { some: { comments: { some:
@@ -428,7 +494,7 @@ depth?: number): string | null;
  * Build WHERE clause conditions for a relation filter subquery.
  * Uses the target table's column mapping to resolve field names.
  */
-export declare function buildSubWhereForRelation(qi: BuilderCtx, targetTable: string, subWhere: Record<string, unknown>, params: unknown[], depth?: number): string | null;
+export declare function buildSubWhereForRelation(qi: BuilderCtx, targetTable: string, targetRef: string, subWhere: Record<string, unknown>, params: unknown[], depth?: number): string | null;
 /**
  * Resolve a column's Postgres type from an arbitrary table's metadata
  * (relation targets, not just `qi.table`).