turbine-orm 0.50.0 → 0.51.0

package/dist/query/filters.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Where-filter type guards and shape helpers
+ * turbine-orm, Where-filter type guards and shape helpers
  *
  * Pure detection / fingerprint utilities used by the query builder's WHERE
  * compiler. Kept out of builder.ts so the class file stays about SQL assembly
@@ -10,7 +10,7 @@ import type { ArrayFilter, ColumnRef, JsonFilter, JsonPathOrderBy, OrderBySpec,
 export declare function isWhereOperator(value: unknown): value is WhereOperator;
 /**
  * True for a *plain object literal* that reached an equality fallthrough
- * without matching any known filter shape — the misspelled-operator case.
+ * without matching any known filter shape, the misspelled-operator case.
  * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
  * bind values and return false, as do arrays and Dates.
  */
@@ -31,7 +31,7 @@ export declare function isColumnRef(value: unknown): value is ColumnRef;
 /**
  * Fingerprint the SHAPE of a where-operator object. Null-valued `equals` /
  * `not` compile to parameterless `IS NULL` / `IS NOT NULL` (different SQL, no
- * param pushed), so null-ness is part of the shape — without it a cache entry
+ * 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
@@ -44,7 +44,7 @@ export declare function fingerprintOperatorShape(value: WhereOperator): string;
 /**
  * Guard for the value of an `equals` operator reaching the plain-equality
  * operator path. A plain object literal can only legitimately be an equality
- * value on a json/jsonb column — and those route to the JSONB filter branch
+ * value on a json/jsonb column, and those route to the JSONB filter branch
  * BEFORE the operator branch, so any plain object that reaches here is a
  * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
  * SQL-build path and the cache-hit param-collect path so a warmed cache can
@@ -56,16 +56,21 @@ export declare function assertBindableEqualsOperand(value: unknown, column: stri
  * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
  * enumerate object keys in this exact order: fingerprints sort keys, so two
  * where clauses with the same fields in different insertion order share one
- * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * cache entry, if build/collect iterated insertion order, the cached SQL's
  * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
  * Array order (OR/AND members) is positional and is never sorted.
  */
 export declare function sortedKeys(obj: Record<string, unknown>): string[];
 /** {@link sortedKeys}, but yielding `[key, value]` pairs. */
 export declare function sortedEntries<V>(obj: Record<string, V>): [string, V][];
-/** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
+/** Known atomic-update operator keys, used to detect operator objects vs plain JSON values */
 export declare const UPDATE_OPERATOR_KEYS: Set<string>;
-/** Known JSONB operator keys */
+/**
+ * Known JSONB operator keys. `stringContains` / `stringStartsWith` /
+ * `stringEndsWith` are appended below, once {@link JSON_STRING_OPERATORS} is
+ * declared: they have no `WhereOperator` counterpart, so their presence is an
+ * unambiguous JSON-filter signal.
+ */
 export declare const JSONB_OPERATOR_KEYS: Set<string>;
 /**
  * JSON range comparison operators → SQL comparison tokens, in the FIXED order
@@ -77,16 +82,31 @@ export declare const JSONB_OPERATOR_KEYS: Set<string>;
  * and they always require `path`.
  */
 export declare const JSON_RANGE_OPERATORS: Record<'gt' | 'gte' | 'lt' | 'lte', string>;
+/**
+ * JSON substring operators → the LIKE pattern each one builds around its
+ * escaped operand, in the FIXED order the build and collect paths iterate
+ * them. These compare the TEXT at `path` (which every one of them requires),
+ * so they are the JSON counterpart of the scalar `contains` / `startsWith` /
+ * `endsWith` operators rather than of jsonb containment.
+ *
+ * They are deliberately NOT named `contains` / `startsWith` / `endsWith`:
+ * `contains` on a JSON column already means whole-document containment
+ * (`@>`), and silently changing that would break every existing caller.
+ */
+export declare const JSON_STRING_OPERATORS: Record<'stringContains' | 'stringStartsWith' | 'stringEndsWith', (escaped: string) => string>;
+export declare const JSON_FILTER_KEYS: ReadonlySet<string>;
 /**
  * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
  * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
- * because a numeric comparison compiles to a `::numeric` cast — a different
- * SQL text than the text comparison — so the two must never share a cached
- * SQL entry.
+ * because a numeric comparison compiles to a `::numeric` cast, a different
+ * SQL text than the text comparison, so the two must never share a cached
+ * SQL entry. `mode` is part of the shape for the same reason: it selects
+ * between `LIKE` and the dialect's case-insensitive form, which is different
+ * SQL text.
  */
 export declare function fingerprintJsonFilterShape(filter: JsonFilter): string;
 /**
- * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * JSONB operator keys that are *unique* to {@link JsonFilter}, they cannot
  * appear in any other where-filter shape, so the presence of one of these is
  * an unambiguous signal that the user meant a JSON filter. Used by the
  * strict-validation path so that `{ contains: 'foo' }` (which is also a valid

package/dist/query/filters.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Where-filter type guards and shape helpers
+ * turbine-orm, Where-filter type guards and shape helpers
  *
  * Pure detection / fingerprint utilities used by the query builder's WHERE
  * compiler. Kept out of builder.ts so the class file stays about SQL assembly
@@ -24,7 +24,7 @@ export function isWhereOperator(value) {
 }
 /**
  * True for a *plain object literal* that reached an equality fallthrough
- * without matching any known filter shape — the misspelled-operator case.
+ * without matching any known filter shape, the misspelled-operator case.
  * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
  * bind values and return false, as do arrays and Dates.
  */
@@ -57,7 +57,7 @@ export function isColumnRef(value) {
 /**
  * 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
+ * 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
@@ -85,7 +85,7 @@ export function fingerprintOperatorShape(value) {
 /**
  * Guard for the value of an `equals` operator reaching the plain-equality
  * operator path. A plain object literal can only legitimately be an equality
- * value on a json/jsonb column — and those route to the JSONB filter branch
+ * value on a json/jsonb column, and those route to the JSONB filter branch
  * BEFORE the operator branch, so any plain object that reaches here is a
  * mistake (e.g. `{ equals: { foo: 1 } }` on a text column). Shared by the
  * SQL-build path and the cache-hit param-collect path so a warmed cache can
@@ -103,7 +103,7 @@ export function assertBindableEqualsOperand(value, column) {
  * cache fingerprint. The SQL-build and cache-hit param-collect paths MUST
  * enumerate object keys in this exact order: fingerprints sort keys, so two
  * where clauses with the same fields in different insertion order share one
- * cache entry — if build/collect iterated insertion order, the cached SQL's
+ * cache entry, if build/collect iterated insertion order, the cached SQL's
  * `$N` placeholders would bind the wrong values (cross-tenant-leak class).
  * Array order (OR/AND members) is positional and is never sorted.
  */
@@ -117,9 +117,14 @@ export function sortedEntries(obj) {
 // ---------------------------------------------------------------------------
 // Atomic-update / JSONB / Array / text-search / vector key sets
 // ---------------------------------------------------------------------------
-/** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
+/** Known atomic-update operator keys, used to detect operator objects vs plain JSON values */
 export const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
-/** Known JSONB operator keys */
+/**
+ * Known JSONB operator keys. `stringContains` / `stringStartsWith` /
+ * `stringEndsWith` are appended below, once {@link JSON_STRING_OPERATORS} is
+ * declared: they have no `WhereOperator` counterpart, so their presence is an
+ * unambiguous JSON-filter signal.
+ */
 export const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
 /**
  * JSON range comparison operators → SQL comparison tokens, in the FIXED order
@@ -136,23 +141,71 @@ export const JSON_RANGE_OPERATORS = {
     lt: '<',
     lte: '<=',
 };
+/**
+ * JSON substring operators → the LIKE pattern each one builds around its
+ * escaped operand, in the FIXED order the build and collect paths iterate
+ * them. These compare the TEXT at `path` (which every one of them requires),
+ * so they are the JSON counterpart of the scalar `contains` / `startsWith` /
+ * `endsWith` operators rather than of jsonb containment.
+ *
+ * They are deliberately NOT named `contains` / `startsWith` / `endsWith`:
+ * `contains` on a JSON column already means whole-document containment
+ * (`@>`), and silently changing that would break every existing caller.
+ */
+export const JSON_STRING_OPERATORS = {
+    stringContains: (escaped) => `%${escaped}%`,
+    stringStartsWith: (escaped) => `${escaped}%`,
+    stringEndsWith: (escaped) => `%${escaped}`,
+};
+/**
+ * Every key a {@link JsonFilter} may carry. Used by the strict-key check so an
+ * unrecognized operator is REFUSED rather than dropped.
+ *
+ * This existed as tribal knowledge spread across `buildJsonFilterClauses` and
+ * `collectJsonFilterParams`: each simply ignored what it did not recognize, so
+ * `{ path: ['title'], string_contains: 'x' }` (the Prisma spelling) compiled to
+ * no predicate at all and returned every row of the table. The scalar operator
+ * path has always thrown on an unknown key; this set is what lets the JSON path
+ * behave the same way.
+ */
+for (const k of Object.keys(JSON_STRING_OPERATORS))
+    JSONB_OPERATOR_KEYS.add(k);
+export const JSON_FILTER_KEYS = new Set([
+    'path',
+    'equals',
+    'contains',
+    'hasKey',
+    'mode',
+    ...Object.keys(JSON_RANGE_OPERATORS),
+    ...Object.keys(JSON_STRING_OPERATORS),
+]);
 /**
  * Value-invariant shape fingerprint for a {@link JsonFilter}. Range operators
  * are annotated with the comparison value's kind (`#n` numeric / `#s` string)
- * because a numeric comparison compiles to a `::numeric` cast — a different
- * SQL text than the text comparison — so the two must never share a cached
- * SQL entry.
+ * because a numeric comparison compiles to a `::numeric` cast, a different
+ * SQL text than the text comparison, so the two must never share a cached
+ * SQL entry. `mode` is part of the shape for the same reason: it selects
+ * between `LIKE` and the dialect's case-insensitive form, which is different
+ * SQL text.
  */
 export function fingerprintJsonFilterShape(filter) {
     const obj = filter;
     const parts = Object.keys(obj)
         .filter((k) => obj[k] !== undefined)
         .sort()
-        .map((k) => (k in JSON_RANGE_OPERATORS ? `${k}#${typeof obj[k] === 'number' ? 'n' : 's'}` : k));
+        .map((k) => {
+        if (k in JSON_RANGE_OPERATORS)
+            return `${k}#${typeof obj[k] === 'number' ? 'n' : 's'}`;
+        // `mode` carries its VALUE, not just its presence: 'insensitive' and any
+        // other spelling select different SQL, so they must not share an entry.
+        if (k === 'mode')
+            return `mode#${String(obj[k])}`;
+        return k;
+    });
     return `json(${parts.join(',')})`;
 }
 /**
- * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
+ * JSONB operator keys that are *unique* to {@link JsonFilter}, they cannot
  * appear in any other where-filter shape, so the presence of one of these is
  * an unambiguous signal that the user meant a JSON filter. Used by the
  * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
@@ -160,7 +213,7 @@ export function fingerprintJsonFilterShape(filter) {
  * set: on non-JSON columns it is a plain equality operator (`WhereOperator`),
  * so it must fall through instead of throwing.
  */
-export const JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey']);
+export const JSONB_UNIQUE_KEYS = new Set(['path', 'hasKey', ...Object.keys(JSON_STRING_OPERATORS)]);
 /** Check if a value is a JSONB filter object */
 export function isJsonFilter(value) {
     if (value === null ||

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Query builder barrel
+ * turbine-orm, Query builder barrel
  *
  * Re-exports every public symbol from the query submodules so that
  * `import { … } from './query/index.js'` is a drop-in replacement for the

package/dist/query/index.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Query builder barrel
+ * turbine-orm, Query builder barrel
  *
  * Re-exports every public symbol from the query submodules so that
  * `import { … } from './query/index.js'` is a drop-in replacement for the

package/dist/query/relations.d.ts

@@ -21,11 +21,11 @@ import type { BuilderCtx } from './where.js';
  * generation (see {@link buildRelationShape}) and consumed by the
  * transform to map key-less positional arrays back to keyed objects.
  *
- * - `keys` — camelCase field names in emitted array position, INCLUDING nested
+ * - `keys`, camelCase field names in emitted array position, INCLUDING nested
  *   relation slots (a nested relation occupies one more position after the
  *   scalar columns, in `sortedEntries(with)` order).
- * - `nested` — sub-shape for each key in `keys` that is itself a relation slot.
- * - `cardinality` — `'one'` (belongsTo/hasOne, a single positional array or
+ * - `nested`, sub-shape for each key in `keys` that is itself a relation slot.
+ * - `cardinality`, `'one'` (belongsTo/hasOne, a single positional array or
  *   null) vs `'many'` (an array of positional arrays).
  */
 export interface RelationShape {
@@ -58,7 +58,7 @@ export declare function collectRelationSubqueryParams(qi: BuilderCtx, relDef: Re
  * Value-shape fingerprint for a single orderBy entry, so two queries whose
  * ORDER BY differs only in nulls placement, vector metric, or relation-count
  * vs relation-column never collide on one cached SQL string. Captures the
- * SQL-shaping bits (direction, nulls, metric, relation keys) — never values.
+ * SQL-shaping bits (direction, nulls, metric, relation keys), never values.
  */
 export declare function orderByEntryFingerprint(qi: BuilderCtx, d: unknown, targetTable?: string): string;
 export declare function buildOrderBy(qi: BuilderCtx, orderBy: OrderByClause, params?: unknown[], lateralSink?: string[]): string;
@@ -70,7 +70,7 @@ export declare function buildOrderBy(qi: BuilderCtx, orderBy: OrderByClause, par
 export declare function isRelationOrderByValue(_qi: BuilderCtx, value: unknown): boolean;
 /**
  * Render the ` NULLS FIRST` / ` NULLS LAST` suffix for a column ordering.
- * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar — on any
+ * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar, on any
  * other engine a caller asking for explicit nulls placement gets a clear
  * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
  */
@@ -225,7 +225,7 @@ export declare function collectManyToManyTargetGlobalFilter(qi: BuilderCtx, relD
 /**
  * Param-collect mirror of {@link buildRelationCountExpr}'s global-filter
  * params (hasMany direct filter, or manyToMany EXISTS-on-target). Only pushes
- * when a filter applies — no-op otherwise.
+ * when a filter applies, no-op otherwise.
  */
 export declare function collectRelationCountParams(qi: BuilderCtx, relDef: RelationDef, params: unknown[]): void;
 export declare function getCamelDateFields(qi: BuilderCtx, table: string, meta: TableMetadata): Set<string>;
@@ -277,7 +277,7 @@ export declare function makeNestedParser(qi: BuilderCtx, withClause: WithClause,
 /**
  * Return a shallow copy of a top-level row with each relation column decoded
  * from its positional array(s) into the object representation. Only relation
- * columns are positional — base scalar columns stay object-keyed — so the
+ * columns are positional, base scalar columns stay object-keyed, so the
  * result is exactly what the object encoding would have handed parseNestedRow.
  */
 export declare function decodePositionalRelations(qi: BuilderCtx, row: Record<string, unknown>, shapes: Record<string, RelationShape>): Record<string, unknown>;
@@ -319,7 +319,7 @@ export interface FlattenNode {
     alias: string;
     /** Alias of the real target table inside the derived table (`f0s`). */
     srcAlias: string;
-    /** Target-side correlation columns (provably unique — see {@link provableUniqueTargetKey}). */
+    /** Target-side correlation columns (provably unique, see {@link provableUniqueTargetKey}). */
     keyColumns: string[];
     /**
      * Match discriminator. A top-level node projects the constant `1` (its
@@ -394,7 +394,7 @@ export declare function provableUniqueTargetKey(relDef: RelationDef, targetMeta:
  * it emits today, down to the cache key).
  *
  * The plan is a pure function of the schema, the `with` clause shape and
- * `includePii` — never of any bound value — so the build path, the cache-hit
+ * `includePii`, never of any bound value, so the build path, the cache-hit
  * param-collect path and the row assembler can each recompute it and agree.
  */
 export declare function planFlattenWith(qi: BuilderCtx, table: string, withClause: WithClause, includePii?: boolean): FlattenPlan | null;