turbine-orm 0.77.1 → 0.78.0

package/dist/query/where.js

@@ -230,7 +230,8 @@ export function collectRelationFilterParams(qi, relDef, filterObj, params, depth
     if (filterObj.every !== undefined && filterObj.every !== null) {
         // gf is only emitted (build) when the `every` sub-where compiles to a
         // filter, otherwise `every` is trivially true and no subquery is built.
-        if (buildSubWhereForRelation(qi, target, filterObj.every, [], depth + 1) !== null) {
+        if (buildSubWhereForRelation(qi, target, qi.q(target), filterObj.every, [], depth + 1) !==
+            null) {
             collectRelFilterParams(qi, target, filterObj.every, params, depth + 1);
             collectTargetGlobalFilterExists(qi, target, params);
         }
@@ -250,7 +251,9 @@ export function collectRelFilterParams(qi, targetTable, subWhere, params, depth
     const meta = qi.schema.tables[targetTable];
     if (!meta)
         return;
-    collectScopedWhereParams(qi, relationWhereScope(qi, targetTable, meta), subWhere, params, depth);
+    // The FROM-item reference only shapes SQL text, never params, so the bare
+    // name serves the collect mirror whether or not the build path aliased it.
+    collectScopedWhereParams(qi, relationWhereScope(qi, targetTable, meta, qi.q(targetTable)), subWhere, params, depth);
 }
 /**
  * Collect params from operator clauses. Mirrors buildOperatorClauses:
@@ -268,8 +271,11 @@ export function collectOperatorParams(qi, column, op, params, refCtx) {
     };
     // Mirrors buildOperatorClauses' temporal bind rewrite exactly.
     const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
+    const insensitive = op.mode === 'insensitive';
     if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
         assertBindableEqualsOperand(op.equals, `"${column}"`);
+        if (insensitive)
+            assertInsensitiveOperand(op.equals, 'equals', column);
         params.push(cv(op.equals));
     }
     if (op.gt !== undefined && !skipRef(op.gt))
@@ -280,12 +286,25 @@ export function collectOperatorParams(qi, column, op, params, refCtx) {
         params.push(cv(op.lt));
     if (op.lte !== undefined && !skipRef(op.lte))
         params.push(cv(op.lte));
-    if (op.not !== undefined && op.not !== null && !skipRef(op.not))
+    if (op.not !== undefined && op.not !== null && !skipRef(op.not)) {
+        if (insensitive)
+            assertInsensitiveOperand(op.not, 'not', column);
         params.push(cv(op.not));
-    if (op.in !== undefined)
+    }
+    if (op.in !== undefined) {
+        if (insensitive) {
+            assertInsensitiveOperand(op.in, 'in', column);
+            requireInsensitiveList(qi, column, 'in');
+        }
         params.push(qi.inParam(cv(op.in)));
-    if (op.notIn !== undefined)
+    }
+    if (op.notIn !== undefined) {
+        if (insensitive) {
+            assertInsensitiveOperand(op.notIn, 'notIn', column);
+            requireInsensitiveList(qi, column, 'notIn');
+        }
         params.push(qi.inParam(cv(op.notIn)));
+    }
     if (op.contains !== undefined)
         params.push(`%${likeOperand(qi, op.contains)}%`);
     if (op.startsWith !== undefined)
@@ -451,16 +470,16 @@ export function collectTargetGlobalFilterAlias(qi, targetTable, params) {
     collectAliasWhereParams(qi, targetTable, meta, gf, params);
 }
 /**
- * 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 function targetGlobalFilterExists(qi, targetTable, params) {
+export function targetGlobalFilterExists(qi, targetTable, targetRef, params) {
     const gf = resolveGlobalFilter(qi, targetTable);
     if (!gf)
         return '';
-    return buildSubWhereForRelation(qi, targetTable, gf, params) ?? '';
+    return buildSubWhereForRelation(qi, targetTable, targetRef, gf, params) ?? '';
 }
 /** Param-collect mirror of {@link targetGlobalFilterExists}. */
 export function collectTargetGlobalFilterExists(qi, targetTable, params) {
@@ -681,29 +700,81 @@ export function scopedWhereHost(qi, meta) {
     }
     return host;
 }
-/** Build the scope for a relation-filter EXISTS sub-where over the bare target table. */
-export function relationWhereScope(qi, targetTable, meta) {
+/**
+ * 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 function relationWhereScope(qi, targetTable, meta, targetRef) {
     return {
         meta,
         table: targetTable,
-        qualifier: `${qi.q(targetTable)}.`,
-        relationParent: targetTable,
+        qualifier: `${targetRef}.`,
+        relationParent: targetRef,
         host: scopedWhereHost(qi, meta),
         unknownColumn: (field) => new ValidationError(`Unknown field "${field}" in relation filter for table "${targetTable}". ` +
             `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`),
     };
 }
-/** Build the scope for a relation `with`-clause `where` compiled against `alias`. */
+/**
+ * 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 function aliasWhereScope(qi, targetTable, meta, alias) {
+    if (alias.includes('"')) {
+        throw new ValidationError(`Internal: aliasWhereScope was given the rendered reference ${alias} for table "${targetTable}", ` +
+            'but it takes a bare alias and quotes it itself. Use renderedRefWhereScope for an already-quoted reference.');
+    }
     return {
         meta,
         table: targetTable,
         qualifier: `${alias}.`,
-        relationParent: alias,
+        // Rendered through the quoter (`"t0"`), which is what a nested relation
+        // filter always emitted for this parent; PostgreSQL folds the unquoted
+        // alias to the same identifier. The empty alias the collect mirror passes
+        // never reaches SQL text.
+        relationParent: alias === '' ? alias : qi.q(alias),
         host: scopedWhereHost(qi, meta),
         unknownColumn: (field) => new ValidationError(`Unknown column "${field}" in where for table "${targetTable}"`),
     };
 }
+/**
+ * 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 function renderedRefWhereScope(qi, targetTable, meta, targetRef) {
+    return {
+        ...relationWhereScope(qi, targetTable, meta, targetRef),
+        unknownColumn: (field) => new ValidationError(`Unknown column "${field}" in where for table "${targetTable}"`),
+    };
+}
+/**
+ * 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 function buildRenderedRefWhere(qi, targetTable, targetMeta, targetRef, where, params) {
+    return buildScopedWhere(qi, renderedRefWhereScope(qi, targetTable, targetMeta, targetRef), where, params);
+}
 /**
  * Compile a scoped sub-where to SQL. Serves BOTH the relation-filter EXISTS
  * body ({@link buildSubWhereForRelation}) and the relation `with`-clause
@@ -898,11 +969,45 @@ export function fingerprintScopedWhere(qi, host, where, depth = 0) {
     }
     return parts.join('&');
 }
+/**
+ * The alias a relation-filter subquery's FROM item takes when the bare table
+ * name would be captured by the correlation (see {@link buildRelationFilter}).
+ * Derived from the WHERE walk depth rather than from a counter: the depth is a
+ * pure function of the where SHAPE, which the cache fingerprint already
+ * encodes, so the same fingerprint always yields the same SQL text, and two
+ * nested levels are one depth apart and therefore never share a name.
+ */
+function relationFilterAlias(depth) {
+    return `rf${depth}`;
+}
 /**
  * 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 function buildRelationFilter(qi, _relName, relDef, filterObj, params, parentTable, 
+export function buildRelationFilter(qi, _relName, relDef, filterObj, params, parentRef, 
 /**
  * Nesting depth of the WHERE walk that reached this relation filter. Each
  * relation descent is a level too: `{ posts: { some: { comments: { some:
@@ -914,8 +1019,12 @@ depth = 0) {
     const targetMeta = qi.schema.tables[targetTable];
     if (!targetMeta)
         return null;
-    const qt = qi.q(targetTable);
-    const qSelf = qi.q(parentTable ?? qi.table);
+    const qSelf = parentRef ?? qi.q(qi.table);
+    const qTargetName = qi.q(targetTable);
+    // `qt` is how the subquery REFERS to its FROM item (bare name or alias);
+    // `fromTarget` is the FROM item itself (`"t"` or `"t" rf0`).
+    const qt = qTargetName === qSelf ? relationFilterAlias(depth) : qTargetName;
+    const fromTarget = qt === qTargetName ? qTargetName : `${qTargetName} ${qt}`;
     const clauses = [];
     // Correlation: link child table to parent table (supports composite FKs)
     let correlation;
@@ -925,13 +1034,16 @@ depth = 0) {
         // parent.pk and silently match nothing, so route through the junction:
         //   EXISTS (SELECT 1 FROM junction
         //           WHERE junction.targetKey = target.pk AND junction.sourceKey = parent.ref)
-        // All bare table names (no aliases), so the scoped sub-where machinery and
-        // nested relation filters inside the branch keep their qualification. The
-        // fragment binds no params, so collectRelationFilterParams needs no mirror.
+        // The target reference is `qt` (bare or aliased, see above), and the
+        // junction is aliased by the same capture rule should its name coincide
+        // with either side. The fragment binds no params, so
+        // collectRelationFilterParams needs no mirror.
         if (!relDef.through) {
             throw new ValidationError(`manyToMany relation "${relDef.name}" is missing a \`through\` junction descriptor.`);
         }
-        const qJunction = qi.q(relDef.through.table);
+        const qJunctionName = qi.q(relDef.through.table);
+        const qJunction = qJunctionName === qSelf || qJunctionName === qt ? `rj${depth}` : qJunctionName;
+        const fromJunction = qJunction === qJunctionName ? qJunctionName : `${qJunctionName} ${qJunction}`;
         const targetKeys = normalizeKeyColumns(relDef.through.targetKey);
         const targetPk = targetMeta.primaryKey;
         if (targetPk.length === 0) {
@@ -954,7 +1066,7 @@ depth = 0) {
         const parentLink = sourceKeys
             .map((jcol, i) => `${qJunction}.${qi.q(jcol)} = ${qSelf}.${qi.q(refKeys[i])}`)
             .join(' AND ');
-        correlation = `EXISTS (SELECT 1 FROM ${qJunction} WHERE ${targetLink} AND ${parentLink})`;
+        correlation = `EXISTS (SELECT 1 FROM ${fromJunction} WHERE ${targetLink} AND ${parentLink})`;
     }
     else if (relDef.type === 'hasMany' || relDef.type === 'hasOne') {
         // parent.pk = child.fk
@@ -969,10 +1081,10 @@ depth = 0) {
     // ignore filtered-out rows, and `every` quantifies over only the surviving
     // rows ("every NON-deleted related row matches P"). It is ANDed into the
     // correlation and its params pushed AFTER the per-branch filter, mirrored
-    // exactly in collectWhereParams' relation-filter branch. `qt` is the bare
-    // target table, matching the `FROM ${qt}` here (see targetGlobalFilterExists).
+    // exactly in collectWhereParams' relation-filter branch. Rendered against
+    // `qt`, the same reference the FROM item and the sub-where use.
     const gfAnd = () => {
-        const gf = targetGlobalFilterExists(qi, targetTable, params);
+        const gf = targetGlobalFilterExists(qi, targetTable, qt, params);
         return gf ? ` AND ${gf}` : '';
     };
     // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
@@ -981,26 +1093,26 @@ depth = 0) {
     // which also skips null. Unreachable via normalization today, guarded anyway.
     if (filterObj.some !== undefined && filterObj.some !== null) {
         const subWhere = filterObj.some;
-        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
+        const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
         const filterAnd = filterClause ? ` AND ${filterClause}` : '';
-        clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
+        clauses.push(`EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${filterAnd}${gfAnd()})`);
     }
     // "none": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND filter AND gf)
     if (filterObj.none !== undefined && filterObj.none !== null) {
         const subWhere = filterObj.none;
-        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
+        const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
         const filterAnd = filterClause ? ` AND ${filterClause}` : '';
-        clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
+        clauses.push(`NOT EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${filterAnd}${gfAnd()})`);
     }
     // "every": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND gf AND NOT (filter))
     if (filterObj.every !== undefined && filterObj.every !== null) {
         const subWhere = filterObj.every;
-        const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
+        const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
         if (filterClause) {
             // gf params pushed AFTER filter params (collect mirrors this order), but
             // placed textually inside the domain so it restricts which rows count.
             const gf = gfAnd();
-            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gf} AND NOT (${filterClause}))`);
+            clauses.push(`NOT EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${gf} AND NOT (${filterClause}))`);
         }
         else {
             // "every" with empty filter = true (all match trivially), gf irrelevant.
@@ -1010,26 +1122,26 @@ depth = 0) {
     // `is: null` = "no related row" (Prisma semantics) → NOT EXISTS.
     if (filterObj.is !== undefined) {
         if (filterObj.is === null) {
-            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gfAnd()})`);
+            clauses.push(`NOT EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${gfAnd()})`);
         }
         else {
             const subWhere = filterObj.is;
-            const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
+            const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
             const filterAnd = filterClause ? ` AND ${filterClause}` : '';
-            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
+            clauses.push(`EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
     }
     // "isNot": NOT EXISTS, for to-one relations (same SQL as "none").
     // `isNot: null` = "a related row exists" → EXISTS.
     if (filterObj.isNot !== undefined) {
         if (filterObj.isNot === null) {
-            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gfAnd()})`);
+            clauses.push(`EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${gfAnd()})`);
         }
         else {
             const subWhere = filterObj.isNot;
-            const filterClause = buildSubWhereForRelation(qi, targetTable, subWhere, params, depth + 1);
+            const filterClause = buildSubWhereForRelation(qi, targetTable, qt, subWhere, params, depth + 1);
             const filterAnd = filterClause ? ` AND ${filterClause}` : '';
-            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
+            clauses.push(`NOT EXISTS (SELECT 1 FROM ${fromTarget} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
     }
     return clauses.length > 0 ? clauses.join(' AND ') : null;
@@ -1038,11 +1150,11 @@ depth = 0) {
  * Build WHERE clause conditions for a relation filter subquery.
  * Uses the target table's column mapping to resolve field names.
  */
-export function buildSubWhereForRelation(qi, targetTable, subWhere, params, depth = 0) {
+export function buildSubWhereForRelation(qi, targetTable, targetRef, subWhere, params, depth = 0) {
     const meta = qi.schema.tables[targetTable];
     if (!meta)
         return null;
-    return buildScopedWhere(qi, relationWhereScope(qi, targetTable, meta), subWhere, params, depth);
+    return buildScopedWhere(qi, relationWhereScope(qi, targetTable, meta, targetRef), subWhere, params, depth);
 }
 /**
  * Resolve a column's Postgres type from an arbitrary table's metadata
@@ -1215,6 +1327,7 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
     // Temporal bind rewrite, identical to `collectOperatorParams`. Value-only, so
     // the emitted SQL (and therefore the template cache) is untouched.
     const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
+    const insensitive = op.mode === 'insensitive';
     if (op.equals !== undefined) {
         if (op.equals === null) {
             clauses.push(`${column} IS NULL`);
@@ -1224,8 +1337,10 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
         }
         else {
             assertBindableEqualsOperand(op.equals, column);
+            if (insensitive)
+                assertInsensitiveOperand(op.equals, 'equals', column);
             params.push(cv(op.equals));
-            clauses.push(`${column} = ${qi.p(params.length)}`);
+            clauses.push(insensitiveEquality(column, '=', qi.p(params.length), insensitive));
         }
     }
     if (op.gt !== undefined) {
@@ -1272,19 +1387,32 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} != ${columnRefSql(qi, op.not, refCtx, op.mode)}`);
         }
         else {
+            if (insensitive)
+                assertInsensitiveOperand(op.not, 'not', column);
             params.push(cv(op.not));
-            clauses.push(`${column} != ${qi.p(params.length)}`);
+            clauses.push(insensitiveEquality(column, '!=', qi.p(params.length), insensitive));
         }
     }
     if (op.in !== undefined) {
+        if (insensitive) {
+            assertInsensitiveOperand(op.in, 'in', column);
+            requireInsensitiveList(qi, column, 'in');
+        }
         params.push(qi.inParam(cv(op.in)));
-        clauses.push(qi.inClause(column, qi.p(params.length), false));
+        clauses.push(insensitive
+            ? insensitiveInClause(qi, column, qi.p(params.length), false, 'in')
+            : qi.inClause(column, qi.p(params.length), false));
     }
     if (op.notIn !== undefined) {
+        if (insensitive) {
+            assertInsensitiveOperand(op.notIn, 'notIn', column);
+            requireInsensitiveList(qi, column, 'notIn');
+        }
         params.push(qi.inParam(cv(op.notIn)));
-        clauses.push(qi.inClause(column, qi.p(params.length), true));
+        clauses.push(insensitive
+            ? insensitiveInClause(qi, column, qi.p(params.length), true, 'notIn')
+            : qi.inClause(column, qi.p(params.length), true));
     }
-    const insensitive = op.mode === 'insensitive';
     if (op.contains !== undefined) {
         params.push(`%${likeOperand(qi, op.contains)}%`);
         clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
@@ -1479,6 +1607,91 @@ function buildLikeClause(qi, column, paramRef, insensitive) {
     const base = insensitive ? qi.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
     return `${base} ESCAPE '\\'`;
 }
+/**
+ * One equality-family comparison (`=` / `!=`) honoring `mode: 'insensitive'`.
+ *
+ * `mode` is a sibling key of `equals` / `not` / `in` / `notIn` on
+ * {@link WhereOperator}, and it used to be read by the three LIKE operators
+ * ONLY, so `{ equals: 'dup name', mode: 'insensitive' }` compiled to a
+ * case-sensitive `"name" = $1` and returned zero rows where `ILIKE` found the
+ * variants, with no error. The fold is `LOWER(col) = LOWER($n)`: exact,
+ * portable to every engine, and computed by the DATABASE on both sides, because
+ * the JavaScript `toLowerCase()` and PostgreSQL's `LOWER` disagree on `İ` and
+ * `ß`, so folding the operand client-side would compare two different
+ * alphabets. Without the mode the emitted text is byte-identical to before.
+ */
+function insensitiveEquality(column, operator, paramRef, insensitive) {
+    return insensitive ? `LOWER(${column}) ${operator} LOWER(${paramRef})` : `${column} ${operator} ${paramRef}`;
+}
+/**
+ * The `in` / `notIn` comparison under `mode: 'insensitive'`.
+ *
+ * The fold is the engine's on BOTH sides: the column is lowered by `LOWER`,
+ * and so is every list element, inside `unnest`. The list stays ONE bound
+ * `text[]`, so the statement text (and therefore its cache key) is independent
+ * of the list length. `NOT IN` keeps SQL's NULL semantics, matching the plain
+ * `!= ALL`.
+ *
+ * PostgreSQL only; {@link requireInsensitiveList} is the gate, and it runs on
+ * the param path as well so a warm template cannot slip past it.
+ */
+function insensitiveInClause(qi, column, paramRef, negated, operator) {
+    requireInsensitiveList(qi, column, operator);
+    return `LOWER(${column}) ${negated ? 'NOT IN' : 'IN'} (SELECT LOWER(v) FROM unnest(${paramRef}::text[]) AS v(v))`;
+}
+/**
+ * Gate `mode: 'insensitive'` on `in` / `notIn` to PostgreSQL.
+ *
+ * The property the operator has to hold is that the COLUMN and the LIST
+ * ELEMENTS are folded by the SAME function. Break that and `equals` and `in`
+ * answer the same operand with DIFFERENT rows on the same engine, which is a
+ * wrong row and not an error.
+ *
+ * The first cut broke it: the column went through the engine's `LOWER` while
+ * the elements went through JavaScript's `toLowerCase()`. Those are two
+ * alphabets. SQLite's `LOWER` is ASCII-only, so over the rows `CAFÉ` and
+ * `café` the operand `'CAFÉ'` matched `CAFÉ` through `equals` and `café`
+ * through `in` - not an exotic-codepoint edge case but every non-ASCII letter
+ * on that engine.
+ *
+ * Folding the elements in SQL instead is not reachable from here for the other
+ * dialects: each unpacks a bound IN list in a subquery of its OWN shape
+ * (`json_each` / `JSON_TABLE` / `OPENJSON`) whose projection is written by the
+ * dialect, not by this module, and the length-independence the SQL-template
+ * cache depends on rules out the other portable form, one placeholder per
+ * element. Restoring the operator on those engines means a dialect hook that
+ * projects the folded element, one correct implementation per engine. Until
+ * then a typed refusal is the honest outcome. `equals`, `not` and the LIKE
+ * operators are unaffected: they fold a single operand the engine can reach.
+ *
+ * Called from BOTH the build and the cache-hit param-collect path, mirroring
+ * every other gate in this module.
+ */
+function requireInsensitiveList(qi, column, operator) {
+    if (qi.dialect.name === 'postgresql')
+        return;
+    throw new UnsupportedFeatureError(`mode: 'insensitive' on \`${operator}\` (${column})`, qi.dialect.name, "Case-folding a bound list needs the engine to lower every element in SQL, which this dialect's " +
+        'IN-list form cannot express. Lowering them in JavaScript instead would fold the list and the ' +
+        `column by two different functions, so \`equals\` and \`${operator}\` would return different rows ` +
+        'for the same operand. Write the list as branches: ' +
+        "`{ OR: [{ field: { equals: a, mode: 'insensitive' } }, ...] }`.");
+}
+/**
+ * Refuse `mode: 'insensitive'` beside a non-string equality operand (E003).
+ * `LOWER(5)` is a type error the engine would raise in its own words on the
+ * build path and, worse, a warm template would bind the value without ever
+ * reaching the engine's check for the SQL it was compiled against, so the
+ * refusal runs on both the build and the collect side. The value itself stays
+ * out of the message (safe error mode renders keys, never values).
+ */
+function assertInsensitiveOperand(value, operator, column) {
+    const ok = Array.isArray(value) ? value.every((v) => typeof v === 'string') : typeof value === 'string';
+    if (ok)
+        return;
+    throw new ValidationError(`mode: 'insensitive' on ${column} requires a string operand for '${operator}' ` +
+        `(received ${Array.isArray(value) ? 'a list with a non-string element' : typeof value}). ` +
+        `Case folding applies to text; drop the mode or compare a string.`);
+}
 /**
  * Refuse a {@link JsonFilter} carrying a key that is not a JSON operator, and
  * refuse a filter that selects a `path` but never compares it.

package/dist/query/writes.d.ts

@@ -164,8 +164,17 @@ export declare function assertNoGeneratedColumns(qi: BuilderCtx, data: Record<st
  * Returns the SQL fragment (e.g., `"view_count" = "view_count" + $3`) and
  * pushes any required params onto the shared params array so that WHERE
  * clause numbering continues correctly afterward.
- */
-export declare function buildSetClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[]): string;
+ *
+ * `refQualifier` prefixes the column REFERENCE an arithmetic operator reads
+ * from (`"view_count" = <qualifier>"view_count" + $n`). A plain `UPDATE` has
+ * one table in scope and passes nothing; `upsert` passes the table name,
+ * because inside `ON CONFLICT ... DO UPDATE SET` the target table and
+ * `excluded` are BOTH in scope and a bare reference is 42702 on PostgreSQL.
+ * The assignment target on the left stays bare on every engine (it can only
+ * ever be the target table's column), and `set` / literal values reference no
+ * column at all, so their SQL is byte-identical with or without a qualifier.
+ */
+export declare function buildSetClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[], refQualifier?: string): string;
 /**
  * Reject a `data` value that reached {@link buildSetClause}'s plain-value
  * fallthrough as a plain object with exactly ONE key that is not a known