turbine-orm 0.50.0 → 0.51.0

package/dist/query/where.d.ts

@@ -94,7 +94,7 @@ interface ColumnRefContext {
      * The operator's own RAW (unquoted) column name. The `column` argument the
      * operator builders receive is already quoted on the build side and raw on
      * the collect side, so the temporal bind rewrite resolves the column's type
-     * from here instead — the one value both sides pass identically.
+     * from here instead, the one value both sides pass identically.
      */
     rawColumn: string;
 }
@@ -105,7 +105,7 @@ interface ColumnRefContext {
  * `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
+ * 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`.
  */
@@ -114,7 +114,7 @@ interface WhereScope {
     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)`, `"target".` for EXISTS sub-wheres, `t0.` for aliases. */
     qualifier: string;
     /** The `parentTable` correlation argument for nested `buildRelationFilter` calls. */
     relationParent: string;
@@ -168,7 +168,7 @@ export declare function collectScalarParams(qi: BuilderCtx, key: string, value:
  * Param-collect mirror of {@link buildRelationFilter} for one relation-filter
  * object (`{ some/every/none/is/isNot }`, already normalized). Pushes, per
  * present branch and in the canonical order some→none→every→is→isNot, the
- * branch's sub-where params THEN the target table's global-filter params —
+ * branch's sub-where params THEN the target table's global-filter params -
  * exactly the order buildRelationFilter emits. When no global filter applies
  * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
  * Shared by every collect site that mirrors buildRelationFilter
@@ -226,7 +226,7 @@ export declare function targetGlobalFilterAlias(qi: BuilderCtx, targetTable: str
 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`
+ * (unaliased) table name, the form used inside relation-filter `EXISTS`
  * subqueries. Pushes its params; `''` when none. Mirror:
  * {@link collectTargetGlobalFilterExists}.
  */
@@ -247,7 +247,7 @@ export declare function globalFilterCacheSegment(qi: BuilderCtx): string;
 /**
  * True when the USER-supplied `where` compiles to no predicate (`{}`,
  * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
- * signal the empty-`where` guard needs — the compiled emptiness, NOT the
+ * signal the empty-`where` guard needs, the compiled emptiness, NOT the
  * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
  * any configured global filter, so a global filter never lets an unguarded
  * mass mutation through.
@@ -269,7 +269,7 @@ export declare function buildWhereClause(qi: BuilderCtx, where: Record<string, u
  */
 export declare function buildScalarClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[], andClauses: string[]): void;
 /**
- * A {@link WhereHost} with no relations — used to fingerprint a sub-where
+ * A {@link WhereHost} with no relations, used to fingerprint a sub-where
  * whose target table is unknown (`schema.tables[t]` miss). `walkWhere` reads
  * only `tableMeta.relations`, so every key falls to the scalar path, matching
  * the pre-unification `meta?.relations` short-circuit.
@@ -283,7 +283,7 @@ export declare function aliasWhereScope(qi: BuilderCtx, targetTable: string, met
 /**
  * Compile a scoped sub-where to SQL. Serves BOTH the relation-filter EXISTS
  * body ({@link buildSubWhereForRelation}) and the relation `with`-clause
- * `where` ({@link buildAliasWhere}) — the emitted SQL is byte-identical to the
+ * `where` ({@link buildAliasWhere}), the emitted SQL is byte-identical to the
  * former hand-mirrored walkers, since it renders the same clauses in the same
  * ({@link walkWhere}-canonical) key order.
  */
@@ -292,8 +292,8 @@ export declare function buildScopedWhere(qi: BuilderCtx, scope: WhereScope, wher
  * Emit the SQL clause(s) for one scalar key of a scoped sub-where. Reproduces
  * the null / JSON / array / operator / equality fall-through both former
  * walkers shared (relation sub-wheres and alias wheres carry no vector or
- * text-search scalar surface, so — unlike the top-level {@link buildScalarClause}
- * — those shapes are not special-cased here and keep their historical
+ * text-search scalar surface, so, unlike the top-level {@link buildScalarClause}
+ * - those shapes are not special-cased here and keep their historical
  * equality-guard behavior).
  */
 export declare function buildScopedScalarClause(qi: BuilderCtx, scope: WhereScope, field: string, value: unknown, params: unknown[], clauses: string[]): void;
@@ -340,7 +340,7 @@ export declare function pgTypeForColumn(_qi: BuilderCtx, meta: TableMetadata, co
  * the UTC-component literal, so a predicate matches the value a write of the
  * same `Date` stored.
  *
- * This is a VALUE transform only — it never changes the emitted SQL — so the
+ * This is a VALUE transform only, it never changes the emitted SQL, so the
  * SQL-template cache is unaffected, and it is applied on the cache-hit
  * param-collect path as well as the build path.
  *
@@ -353,13 +353,13 @@ export declare function coerceWhereOperand(qi: BuilderCtx, meta: TableMetadata,
  * Introspection stores each column's `udt_name` in `pgTypes` and every
  * database enum in `schema.enums` (typname → labels); a column whose type
  * matches an enum key needs an explicit `::"EnumName"` cast on its write
- * binds — bulk-insert forms like `UNNEST($1::text[])` otherwise type the
+ * binds, bulk-insert forms like `UNNEST($1::text[])` otherwise type the
  * value as text and Postgres refuses the implicit text→enum coercion
  * ("column X is of type Y but expression is of type text").
  *
  * Postgres-only by construction: gated on the active dialect being
  * `postgresql` AND on `schema.enums` having entries (only PG introspection
- * produces them — `defineSchema` and the other engines leave it empty), so
+ * produces them, `defineSchema` and the other engines leave it empty), so
  * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
  */
 export declare function enumTypeForColumn(qi: BuilderCtx, column: string): string | null;
@@ -382,7 +382,7 @@ export declare function assertBindableEqualityValue(qi: BuilderCtx, rawColumn: s
 /**
  * Build the user-supplied `where` filter of a relation `with` clause against
  * the relation's table alias. Supports the same scalar surface as the
- * top-level WHERE builder — equality, IS NULL, operator objects (incl.
+ * top-level WHERE builder, equality, IS NULL, operator objects (incl.
  * `mode: 'insensitive'`), and OR/AND/NOT combinators. Unknown operator
  * objects throw via {@link assertBindableEqualityValue}.
  *
@@ -395,7 +395,7 @@ export declare function collectAliasWhereParams(qi: BuilderCtx, targetTable: str
 /**
  * Value-invariant, shape-aware fingerprint for a relation `with` clause's
  * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
- * can emit — equality vs null vs operator sets vs combinators — or two
+ * can emit, equality vs null vs operator sets vs combinators, or two
  * differently-shaped wheres would share one cached SQL string.
  */
 export declare function fingerprintAliasWhere(qi: BuilderCtx, where: Record<string, unknown>, targetTable?: string): string;
@@ -444,7 +444,7 @@ export declare function requireArrayColumns(qi: BuilderCtx): void;
  * Resolve a {@link VectorMetric} to its pgvector distance operator from a
  * fixed allow-list, validating the target column is actually a `vector`
  * column. Throws {@link ValidationError} for an unknown metric or a
- * non-vector column — a user-supplied string can never become a SQL operator.
+ * non-vector column, a user-supplied string can never become a SQL operator.
  */
 export declare function vectorOperator(qi: BuilderCtx, field: string, rawColumn: string, metric: string): string;
 /**
@@ -456,8 +456,8 @@ export declare function vectorOperator(qi: BuilderCtx, field: string, rawColumn:
  */
 export declare function pushVectorParam(qi: BuilderCtx, field: string, _rawColumn: string, to: unknown, params: unknown[]): string;
 /**
- * Prisma-compat: a plain object on a to-one relation key —
- * `where: { vendor: { name: { contains: 'x' } } }` — is an implicit `is`
+ * Prisma-compat: a plain object on a to-one relation key -
+ * `where: { vendor: { name: { contains: 'x' } } }`, is an implicit `is`
  * filter. Normalize it to `{ is: obj }` so all downstream handling (SQL,
  * params, fingerprint) sees one canonical shape. To-many relations still
  * require an explicit `some`/`every`/`none` (a bare object there is
@@ -468,7 +468,7 @@ export declare function normalizeRelationFilter(_qi: BuilderCtx, relDef: Relatio
  * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
  * udt_names, but SQLite/MySQL introspection surfaces the DECLARED type
  * (e.g. `JSON`), so every JSON-feature gate compares through this predicate
- * — build and collect sides alike, keeping the SQL-cache lockstep.
+ * - build and collect sides alike, keeping the SQL-cache lockstep.
  */
 export declare function isJsonColumnType(_qi: BuilderCtx, colType: string): boolean;
 export declare function getColumnPgType(qi: BuilderCtx, column: string): string;
@@ -478,13 +478,32 @@ export declare function getColumnPgType(qi: BuilderCtx, column: string): string;
  */
 export declare function getArrayElementType(_qi: BuilderCtx, pgType: string): string;
 /**
- * Validate and enumerate the range comparisons (`gt`/`gte`/`lt`/`lte`) on a
- * JSON filter, in the fixed {@link JSON_RANGE_OPERATORS} order. Shared by
- * the SQL-build path ({@link buildJsonFilterClauses}) and the cache-hit
- * param-collect path ({@link collectJsonFilterParams}) so both always agree
- * on which params are pushed — and both throw identically for invalid
- * shapes, so a warmed cache can never skip validation.
+ * 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.
+ *
+ * Both shapes used to compile to NOTHING. `buildJsonFilterClauses` only ever
+ * emitted a clause for a key it recognized, so `{ path: ['title'],
+ * string_contains: 'x' }`, the Prisma spelling, and an easy typo besides -
+ * produced an empty clause list, the predicate vanished, and the query
+ * returned EVERY row. Inside an `AND` it silently dropped that conjunct, so a
+ * tenant scope written this way widened to the whole table. The equivalent
+ * typo on a scalar column has always thrown; this closes the inconsistency.
+ *
+ * Called from both the SQL-build path and the cache-hit param-collect path, so
+ * a warmed SQL cache cannot skip the check.
  */
+export declare function assertJsonFilterKeys(filter: JsonFilter, column: string): void;
+/**
+ * Validate and enumerate the substring comparisons on a JSON filter, in the
+ * fixed {@link JSON_STRING_OPERATORS} order. Shared by the build and collect
+ * paths exactly like {@link jsonRangeEntries}, so both agree on the params
+ * pushed and both throw identically on an invalid shape.
+ */
+export declare function jsonStringEntries(filter: JsonFilter, column: string): {
+    op: string;
+    pattern: (escaped: string) => string;
+    value: string;
+}[];
 export declare function jsonRangeEntries(_qi: BuilderCtx, filter: JsonFilter, column: string): {
     sqlOp: string;
     value: number | string;
@@ -500,19 +519,19 @@ export declare function jsonRangeEntries(_qi: BuilderCtx, filter: JsonFilter, co
 export declare function buildJsonFilterClauses(qi: BuilderCtx, column: string, filter: JsonFilter, params: unknown[]): string[];
 /**
  * Bind value for a JSON path parameter, encoded per dialect. PostgreSQL's
- * `#>>` takes a `text[]` (the segments as strings — or `nativeForm` when the
+ * `#>>` takes a `text[]` (the segments as strings, or `nativeForm` when the
  * caller has a specific native binding, e.g. JsonFilter's raw path array).
  * Every other engine's JSON function (`json_extract` / `JSON_EXTRACT` /
  * `JSON_VALUE`) takes a `'$'`-rooted JSONPath STRING: binding the raw array
  * would arrive as `'["a"]'` (the driver shims JSON.stringify non-primitive
  * params) and fail at runtime with the engine's bad-JSON-path error. The
- * encoded path stays a bound parameter — never spliced into SQL text — so
+ * encoded path stays a bound parameter, never spliced into SQL text, so
  * the build/collect param mirrors stay in lockstep and injection-safe.
  */
 export declare function jsonPathParam(qi: BuilderCtx, path: readonly (string | number)[], nativeForm?: unknown): unknown;
 /**
  * Cast an extracted JSON path text value to a numeric type for range
- * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to
+ * comparison. PostgreSQL uses `(expr)::numeric` (exact, the right way to
  * compare JSON numbers, and `::float` would lose precision on big ints);
  * other dialects route through {@link Dialect.castAggregate} (SQLite/MySQL/
  * SQL Server have no `::` operator) as a float cast.

package/dist/query/where.js

@@ -12,7 +12,7 @@
  */
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { camelToSnake, normalizeKeyColumns } from '../schema.js';
-import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, isArrayFilter, isColumnRef, isJsonFilter, isUnmatchedPlainObject, isWhereOperator, JSON_RANGE_OPERATORS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
+import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, isArrayFilter, isColumnRef, isJsonFilter, isUnmatchedPlainObject, isWhereOperator, JSON_FILTER_KEYS, JSON_RANGE_OPERATORS, JSON_STRING_OPERATORS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
 import { coerceTemporalValue, escapeLike, OPERATOR_KEYS, ownLookup } from './utils.js';
 import { classifyScalarForSql, fingerprintScalarToken, walkWhere, } from './where-compile.js';
 /**
@@ -174,7 +174,7 @@ export function collectScalarParams(qi, key, value, params) {
  * Param-collect mirror of {@link buildRelationFilter} for one relation-filter
  * object (`{ some/every/none/is/isNot }`, already normalized). Pushes, per
  * present branch and in the canonical order some→none→every→is→isNot, the
- * branch's sub-where params THEN the target table's global-filter params —
+ * branch's sub-where params THEN the target table's global-filter params -
  * exactly the order buildRelationFilter emits. When no global filter applies
  * the gf calls are no-ops, so this stays byte-identical to the pre-0.28 path.
  * Shared by every collect site that mirrors buildRelationFilter
@@ -192,7 +192,7 @@ export function collectRelationFilterParams(qi, relDef, filterObj, params) {
     }
     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.
+        // filter, otherwise `every` is trivially true and no subquery is built.
         if (buildSubWhereForRelation(qi, target, filterObj.every, []) !== null) {
             collectRelFilterParams(qi, target, filterObj.every, params);
             collectTargetGlobalFilterExists(qi, target, params);
@@ -263,6 +263,7 @@ export function collectOperatorParams(qi, column, op, params, refCtx) {
  * comparison values in {@link JSON_RANGE_OPERATORS} order.
  */
 export function collectJsonFilterParams(qi, filter, params, column) {
+    assertJsonFilterKeys(filter, column);
     let pathPushed = false;
     const pushPathOnce = () => {
         if (!pathPushed) {
@@ -288,6 +289,10 @@ export function collectJsonFilterParams(qi, filter, params, column) {
         pushPathOnce();
         params.push(value);
     }
+    for (const { pattern, value } of jsonStringEntries(filter, column)) {
+        pushPathOnce();
+        params.push(pattern(escapeLike(value)));
+    }
 }
 /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
 export function collectArrayFilterParams(qi, filter, params) {
@@ -343,7 +348,7 @@ export function resolveGlobalFilter(qi, table, skip = qi.currentSkip) {
         return null;
     const obj = resolved;
     // An all-undefined filter (e.g. `{ tenantId: undefined }`) contributes
-    // nothing — treat it as absent so it never emits a dangling clause.
+    // nothing, treat it as absent so it never emits a dangling clause.
     if (Object.keys(obj).every((k) => obj[k] === undefined))
         return null;
     return obj;
@@ -388,7 +393,7 @@ export function collectTargetGlobalFilterAlias(qi, targetTable, params) {
 }
 /**
  * SQL clause for `targetTable`'s global filter rendered against the bare
- * (unaliased) table name — the form used inside relation-filter `EXISTS`
+ * (unaliased) table name, the form used inside relation-filter `EXISTS`
  * subqueries. Pushes its params; `''` when none. Mirror:
  * {@link collectTargetGlobalFilterExists}.
  */
@@ -450,7 +455,7 @@ export function globalFilterCacheSegment(qi) {
 /**
  * True when the USER-supplied `where` compiles to no predicate (`{}`,
  * `{ id: undefined }`, `{ OR: [{ a: undefined }] }`, …). This is the exact
- * signal the empty-`where` guard needs — the compiled emptiness, NOT the
+ * signal the empty-`where` guard needs, the compiled emptiness, NOT the
  * fingerprint (which is non-empty for an all-undefined `OR`/`AND`). It ignores
  * any configured global filter, so a global filter never lets an unguarded
  * mass mutation through.
@@ -572,7 +577,7 @@ export function buildScalarClause(qi, key, value, params, andClauses) {
     }
 }
 /**
- * A {@link WhereHost} with no relations — used to fingerprint a sub-where
+ * A {@link WhereHost} with no relations, used to fingerprint a sub-where
  * whose target table is unknown (`schema.tables[t]` miss). `walkWhere` reads
  * only `tableMeta.relations`, so every key falls to the scalar path, matching
  * the pre-unification `meta?.relations` short-circuit.
@@ -624,7 +629,7 @@ export function aliasWhereScope(qi, targetTable, meta, alias) {
 /**
  * Compile a scoped sub-where to SQL. Serves BOTH the relation-filter EXISTS
  * body ({@link buildSubWhereForRelation}) and the relation `with`-clause
- * `where` ({@link buildAliasWhere}) — the emitted SQL is byte-identical to the
+ * `where` ({@link buildAliasWhere}), the emitted SQL is byte-identical to the
  * former hand-mirrored walkers, since it renders the same clauses in the same
  * ({@link walkWhere}-canonical) key order.
  */
@@ -665,8 +670,8 @@ export function buildScopedWhere(qi, scope, where, params) {
  * Emit the SQL clause(s) for one scalar key of a scoped sub-where. Reproduces
  * the null / JSON / array / operator / equality fall-through both former
  * walkers shared (relation sub-wheres and alias wheres carry no vector or
- * text-search scalar surface, so — unlike the top-level {@link buildScalarClause}
- * — those shapes are not special-cased here and keep their historical
+ * text-search scalar surface, so, unlike the top-level {@link buildScalarClause}
+ * - those shapes are not special-cased here and keep their historical
  * equality-guard behavior).
  */
 export function buildScopedScalarClause(qi, scope, field, value, params, clauses) {
@@ -866,7 +871,7 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
     // DOMAIN of correlated rows in EVERY branch: `some`/`none`/`is`/`isNot`
     // 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
+    // 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).
     const gfAnd = () => {
@@ -901,10 +906,10 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
             clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${gf} AND NOT (${filterClause}))`);
         }
         else {
-            // "every" with empty filter = true (all match trivially) — gf irrelevant.
+            // "every" with empty filter = true (all match trivially), gf irrelevant.
         }
     }
-    // "is": EXISTS — for to-one relations (same SQL as "some").
+    // "is": EXISTS, for to-one relations (same SQL as "some").
     // `is: null` = "no related row" (Prisma semantics) → NOT EXISTS.
     if (filterObj.is !== undefined) {
         if (filterObj.is === null) {
@@ -917,7 +922,7 @@ export function buildRelationFilter(qi, _relName, relDef, filterObj, params, par
             clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation}${filterAnd}${gfAnd()})`);
         }
     }
-    // "isNot": NOT EXISTS — for to-one relations (same SQL as "none").
+    // "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) {
@@ -958,7 +963,7 @@ export function pgTypeForColumn(_qi, meta, column) {
  * the UTC-component literal, so a predicate matches the value a write of the
  * same `Date` stored.
  *
- * This is a VALUE transform only — it never changes the emitted SQL — so the
+ * This is a VALUE transform only, it never changes the emitted SQL, so the
  * SQL-template cache is unaffected, and it is applied on the cache-hit
  * param-collect path as well as the build path.
  *
@@ -979,13 +984,13 @@ export function coerceWhereOperand(qi, meta, column, value) {
  * Introspection stores each column's `udt_name` in `pgTypes` and every
  * database enum in `schema.enums` (typname → labels); a column whose type
  * matches an enum key needs an explicit `::"EnumName"` cast on its write
- * binds — bulk-insert forms like `UNNEST($1::text[])` otherwise type the
+ * binds, bulk-insert forms like `UNNEST($1::text[])` otherwise type the
  * value as text and Postgres refuses the implicit text→enum coercion
  * ("column X is of type Y but expression is of type text").
  *
  * Postgres-only by construction: gated on the active dialect being
  * `postgresql` AND on `schema.enums` having entries (only PG introspection
- * produces them — `defineSchema` and the other engines leave it empty), so
+ * produces them, `defineSchema` and the other engines leave it empty), so
  * SQLite/MySQL/MSSQL/PowDB output is byte-identical.
  */
 export function enumTypeForColumn(qi, column) {
@@ -996,7 +1001,7 @@ export function enumTypeForColumn(qi, column) {
         return null;
     // Cross-schema guard (N-5): introspection records pgTypeSchema ONLY when
     // the column's type lives OUTSIDE the introspected schema. A same-named
-    // enum in another schema must not get this schema's cast — search_path
+    // enum in another schema must not get this schema's cast, search_path
     // would resolve `::"status"` to the wrong type. Skipping the cast restores
     // the pre-cast behavior for such columns. Columns without pgTypeSchema
     // (same-schema types, defineSchema/legacy metadata) keep the cast.
@@ -1041,7 +1046,7 @@ export function assertBindableEqualityValue(qi, rawColumn, value, columnPgType,
 /**
  * Build the user-supplied `where` filter of a relation `with` clause against
  * the relation's table alias. Supports the same scalar surface as the
- * top-level WHERE builder — equality, IS NULL, operator objects (incl.
+ * top-level WHERE builder, equality, IS NULL, operator objects (incl.
  * `mode: 'insensitive'`), and OR/AND/NOT combinators. Unknown operator
  * objects throw via {@link assertBindableEqualityValue}.
  *
@@ -1060,7 +1065,7 @@ export function collectAliasWhereParams(qi, targetTable, targetMeta, where, para
 /**
  * Value-invariant, shape-aware fingerprint for a relation `with` clause's
  * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
- * can emit — equality vs null vs operator sets vs combinators — or two
+ * can emit, equality vs null vs operator sets vs combinators, or two
  * differently-shaped wheres would share one cached SQL string.
  */
 export function fingerprintAliasWhere(qi, where, targetTable) {
@@ -1182,18 +1187,18 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
         params.push(qi.inParam(cv(op.notIn)));
         clauses.push(qi.inClause(column, qi.p(params.length), true));
     }
-    const buildLikeClause = (paramRef) => op.mode === 'insensitive' ? qi.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
+    const insensitive = op.mode === 'insensitive';
     if (op.contains !== undefined) {
         params.push(`%${escapeLike(op.contains)}%`);
-        clauses.push(`${buildLikeClause(qi.p(params.length))} ESCAPE '\\'`);
+        clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
     }
     if (op.startsWith !== undefined) {
         params.push(`${escapeLike(op.startsWith)}%`);
-        clauses.push(`${buildLikeClause(qi.p(params.length))} ESCAPE '\\'`);
+        clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
     }
     if (op.endsWith !== undefined) {
         params.push(`%${escapeLike(op.endsWith)}`);
-        clauses.push(`${buildLikeClause(qi.p(params.length))} ESCAPE '\\'`);
+        clauses.push(buildLikeClause(qi, column, qi.p(params.length), insensitive));
     }
     return clauses;
 }
@@ -1228,7 +1233,7 @@ export function requireArrayColumns(qi) {
  * Resolve a {@link VectorMetric} to its pgvector distance operator from a
  * fixed allow-list, validating the target column is actually a `vector`
  * column. Throws {@link ValidationError} for an unknown metric or a
- * non-vector column — a user-supplied string can never become a SQL operator.
+ * non-vector column, a user-supplied string can never become a SQL operator.
  */
 export function vectorOperator(qi, field, rawColumn, metric) {
     if (!qi.dialect.supportsVector) {
@@ -1275,8 +1280,8 @@ export function pushVectorParam(qi, field, _rawColumn, to, params) {
     return `${qi.p(params.length)}::vector`;
 }
 /**
- * Prisma-compat: a plain object on a to-one relation key —
- * `where: { vendor: { name: { contains: 'x' } } }` — is an implicit `is`
+ * Prisma-compat: a plain object on a to-one relation key -
+ * `where: { vendor: { name: { contains: 'x' } } }`, is an implicit `is`
  * filter. Normalize it to `{ is: obj }` so all downstream handling (SQL,
  * params, fingerprint) sees one canonical shape. To-many relations still
  * require an explicit `some`/`every`/`none` (a bare object there is
@@ -1297,7 +1302,7 @@ export function normalizeRelationFilter(_qi, relDef, filterObj) {
  * Case-insensitive json/jsonb column-type check. Postgres reports lowercase
  * udt_names, but SQLite/MySQL introspection surfaces the DECLARED type
  * (e.g. `JSON`), so every JSON-feature gate compares through this predicate
- * — build and collect sides alike, keeping the SQL-cache lockstep.
+ * - build and collect sides alike, keeping the SQL-cache lockstep.
  */
 export function isJsonColumnType(_qi, colType) {
     const t = colType.toLowerCase();
@@ -1334,9 +1339,92 @@ export function getArrayElementType(_qi, pgType) {
  * JSON filter, in the fixed {@link JSON_RANGE_OPERATORS} order. Shared by
  * the SQL-build path ({@link buildJsonFilterClauses}) and the cache-hit
  * param-collect path ({@link collectJsonFilterParams}) so both always agree
- * on which params are pushed — and both throw identically for invalid
+ * on which params are pushed, and both throw identically for invalid
  * shapes, so a warmed cache can never skip validation.
  */
+/**
+ * One LIKE comparison, honoring `mode: 'insensitive'` through the dialect and
+ * always carrying the `ESCAPE '\'` clause that pairs with {@link escapeLike}.
+ *
+ * Shared by the scalar `contains` / `startsWith` / `endsWith` operators and by
+ * the JSON substring operators, so the two can never drift into escaping their
+ * operands the same way but comparing them differently.
+ */
+function buildLikeClause(qi, column, paramRef, insensitive) {
+    const base = insensitive ? qi.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
+    return `${base} ESCAPE '\\'`;
+}
+/**
+ * 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.
+ *
+ * Both shapes used to compile to NOTHING. `buildJsonFilterClauses` only ever
+ * emitted a clause for a key it recognized, so `{ path: ['title'],
+ * string_contains: 'x' }`, the Prisma spelling, and an easy typo besides -
+ * produced an empty clause list, the predicate vanished, and the query
+ * returned EVERY row. Inside an `AND` it silently dropped that conjunct, so a
+ * tenant scope written this way widened to the whole table. The equivalent
+ * typo on a scalar column has always thrown; this closes the inconsistency.
+ *
+ * Called from both the SQL-build path and the cache-hit param-collect path, so
+ * a warmed SQL cache cannot skip the check.
+ */
+export function assertJsonFilterKeys(filter, column) {
+    const obj = filter;
+    const present = Object.keys(obj).filter((k) => obj[k] !== undefined);
+    for (const key of present) {
+        if (JSON_FILTER_KEYS.has(key))
+            continue;
+        const suggestion = JSON_PRISMA_SPELLINGS[key];
+        throw new ValidationError(`[turbine] Unknown JSON filter operator "${key}" on ${column}.` +
+            (suggestion ? ` Did you mean \`${suggestion}\`?` : '') +
+            ` Supported operators: ${[...JSON_FILTER_KEYS].sort().join(', ')}.`);
+    }
+    // `mode` and `path` are modifiers, not comparisons: a filter made only of
+    // those compares nothing, which is exactly the silent no-op shape above.
+    if (present.length > 0 && present.every((k) => k === 'path' || k === 'mode')) {
+        throw new ValidationError(`[turbine] JSON filter on ${column} selects a \`path\` but has no comparison. ` +
+            `Add one of: ${[...JSON_FILTER_KEYS]
+                .filter((k) => k !== 'path' && k !== 'mode')
+                .sort()
+                .join(', ')}.`);
+    }
+}
+/**
+ * The Prisma spelling of each JSON operator, so a migrator who writes the
+ * name they already know gets told the turbine one instead of a bare list.
+ */
+const JSON_PRISMA_SPELLINGS = {
+    string_contains: 'stringContains',
+    string_starts_with: 'stringStartsWith',
+    string_ends_with: 'stringEndsWith',
+    array_contains: 'contains',
+    startsWith: 'stringStartsWith',
+    endsWith: 'stringEndsWith',
+};
+/**
+ * Validate and enumerate the substring comparisons on a JSON filter, in the
+ * fixed {@link JSON_STRING_OPERATORS} order. Shared by the build and collect
+ * paths exactly like {@link jsonRangeEntries}, so both agree on the params
+ * pushed and both throw identically on an invalid shape.
+ */
+export function jsonStringEntries(filter, column) {
+    const entries = [];
+    for (const [op, pattern] of Object.entries(JSON_STRING_OPERATORS)) {
+        const value = filter[op];
+        if (value === undefined)
+            continue;
+        if (filter.path === undefined) {
+            throw new ValidationError(`[turbine] JSON operator '${op}' on ${column} requires a \`path\` ` +
+                `(e.g. { path: ['meta', 'title'], ${op}: ${JSON.stringify(value)} }).`);
+        }
+        if (typeof value !== 'string') {
+            throw new ValidationError(`[turbine] JSON operator '${op}' on ${column} requires a string, got ${JSON.stringify(value)}.`);
+        }
+        entries.push({ op, pattern, value });
+    }
+    return entries;
+}
 export function jsonRangeEntries(_qi, filter, column) {
     const entries = [];
     for (const [op, sqlOp] of Object.entries(JSON_RANGE_OPERATORS)) {
@@ -1367,6 +1455,7 @@ export function jsonRangeEntries(_qi, filter, column) {
  * stays byte-identical to {@link collectJsonFilterParams}.
  */
 export function buildJsonFilterClauses(qi, column, filter, params) {
+    assertJsonFilterKeys(filter, column);
     const clauses = [];
     // Lazily bind the path once; reuse the same $N in every extraction clause.
     let pathParamIdx = null;
@@ -1407,17 +1496,25 @@ export function buildJsonFilterClauses(qi, column, filter, params) {
         const lhs = typeof value === 'number' ? castJsonNumeric(qi, extract) : extract;
         clauses.push(`${lhs} ${sqlOp} ${qi.p(params.length)}`);
     }
+    // Substring comparisons on the extracted path. The operand is LIKE-escaped
+    // exactly like the scalar `contains` family, so a value containing `%` or
+    // `_` matches literally instead of turning into a wildcard.
+    for (const { pattern, value } of jsonStringEntries(filter, column)) {
+        const extract = pathExtract();
+        params.push(pattern(escapeLike(value)));
+        clauses.push(buildLikeClause(qi, extract, qi.p(params.length), filter.mode === 'insensitive'));
+    }
     return clauses;
 }
 /**
  * Bind value for a JSON path parameter, encoded per dialect. PostgreSQL's
- * `#>>` takes a `text[]` (the segments as strings — or `nativeForm` when the
+ * `#>>` takes a `text[]` (the segments as strings, or `nativeForm` when the
  * caller has a specific native binding, e.g. JsonFilter's raw path array).
  * Every other engine's JSON function (`json_extract` / `JSON_EXTRACT` /
  * `JSON_VALUE`) takes a `'$'`-rooted JSONPath STRING: binding the raw array
  * would arrive as `'["a"]'` (the driver shims JSON.stringify non-primitive
  * params) and fail at runtime with the engine's bad-JSON-path error. The
- * encoded path stays a bound parameter — never spliced into SQL text — so
+ * encoded path stays a bound parameter, never spliced into SQL text, so
  * the build/collect param mirrors stay in lockstep and injection-safe.
  */
 export function jsonPathParam(qi, path, nativeForm) {
@@ -1429,7 +1526,7 @@ export function jsonPathParam(qi, path, nativeForm) {
 }
 /**
  * Cast an extracted JSON path text value to a numeric type for range
- * comparison. PostgreSQL uses `(expr)::numeric` (exact — the right way to
+ * comparison. PostgreSQL uses `(expr)::numeric` (exact, the right way to
  * compare JSON numbers, and `::float` would lose precision on big ints);
  * other dialects route through {@link Dialect.castAggregate} (SQLite/MySQL/
  * SQL Server have no `::` operator) as a float cast.

package/dist/query/writes.d.ts

@@ -20,10 +20,10 @@ import type { BuilderCtx } from './where.js';
  *
  * Two value shapes need rewriting, both a JS `Date` on a temporal column:
  *
- * 1. A time-of-day column (`time` / `timetz`) — the driver serializes a `Date`
+ * 1. A time-of-day column (`time` / `timetz`), the driver serializes a `Date`
  *    as a full ISO timestamp with the process offset and Postgres answers
  *    `22007 invalid input syntax for type time`. Rewritten on every engine.
- * 2. A zone-less `date` / `timestamp` column on PostgreSQL — the driver's
+ * 2. A zone-less `date` / `timestamp` column on PostgreSQL, the driver's
  *    local-offset serialization stores the PROCESS's calendar fields, so in a
  *    non-UTC process the stored value is wrong and (because the read path
  *    interprets an offset-less value as UTC) does not round-trip. Rewritten to
@@ -85,17 +85,36 @@ export declare function piiColumns(_qi: BuilderCtx, meta: TableMetadata): Set<st
 export declare function piiFields(_qi: BuilderCtx, meta: TableMetadata): string[];
 /**
  * The `RETURNING` / `OUTPUT` selection for a write on this table. A table with
- * no PII column returns `'*'` (every column — byte-identical SQL to before);
+ * no PII column returns `'*'` (every column, byte-identical SQL to before);
  * a table WITH PII columns returns an explicit quoted list of every non-PII
  * column so the PII values never leave the database on a write. A PII-tagged
  * PRIMARY KEY column is kept in the projection regardless (the returned row
- * must stay addressable): tag sensitive data, not keys — a PII PK is
+ * must stay addressable): tag sensitive data, not keys, a PII PK is
  * documented out of scope for stripping. Writes accept no `select`/`includePii`
  * (unlike reads), so this is the whole write-return policy at the SQL level;
  * {@link parseWriteRow} remains as a defense-in-depth strip (a no-op once the
  * SQL already excludes the columns). Derived purely from static per-table
  * schema metadata, so the write SQL cache needs no extra key segment.
  */
+/**
+ * Return `data` with every `updatedAt`-tagged column the caller did not name
+ * set to `now`, or the original object when the table has none.
+ *
+ * Prisma's `@updatedAt` has no turbine equivalent, so a migrated application
+ * had to remember the field on every single update, and the value is usually
+ * load-bearing in the response body, so forgetting it is a silent staleness
+ * bug rather than a crash. The tag is opt-in per column and never inferred
+ * from a column's name, so a schema that does not use it emits byte-identical
+ * SQL and an application already managing its own timestamp is untouched.
+ *
+ * The timestamp is generated CLIENT-side (like Prisma) rather than as a SQL
+ * `now()`, so it flows through the same temporal coercion as any other bound
+ * `Date` and lands in UTC on every engine.
+ *
+ * An explicit value always wins, including an explicit `null`: naming the
+ * column is a statement of intent.
+ */
+export declare function applyUpdatedAtColumns(qi: BuilderCtx, data: Record<string, unknown>): Record<string, unknown>;
 export declare function writeReturningColumns(qi: BuilderCtx): ReturningSelection;
 /**
  * String form of {@link writeReturningColumns} for a `SELECT` list (the
@@ -132,7 +151,7 @@ export declare function assertNoGeneratedColumns(qi: BuilderCtx, data: Record<st
  *
  * Supports plain values and atomic operator objects ({ set, increment,
  * decrement, multiply, divide }). An operator object is detected ONLY when
- * it has EXACTLY one key that is one of the 5 operator keys — this avoids
+ * it has EXACTLY one key that is one of the 5 operator keys, this avoids
  * misinterpreting JSON column values like `{ set: 'x' }` as operators
  * (real operator objects always have exactly one key, and a plain JSON
  * payload that happens to have a single `set` key is extremely unusual).