@inixiative/json-rules 3.5.4 → 3.7.0

package/README.md

@@ -645,6 +645,7 @@ import { engineGlobals } from '@inixiative/json-rules';
 engineGlobals.set('string.caseInsensitive', true);
 engineGlobals.get('string.caseInsensitive'); // true
 engineGlobals.set('prismaOptions.datasource.provider', 'mysql');
+engineGlobals.set('sql.dialect', SqlDialect.mysql); // what toWhereSql / toLensWhereSql write
 engineGlobals.reset(); // back to the defaults
 
 // A scoped override: merged over the current state for the duration of a synchronous callback.
@@ -694,6 +695,70 @@ as `toPrisma()` takes it. A set without `mapName` throws.
 toSql(rule, { map: lens, mapName: 'prisma', model: 'Post' });
 ```
 
+## Inline Predicates — `toWhereSql`, `toLensWhereSql`
+
+Two small helpers write a condition, or a lens's row filters, as a SQL predicate for a caller
+that names its own columns and writes its own joins (an Omni topic, for one). They write the
+engine's `sql.dialect` — `SqlDialect.postgres` by default, `SqlDialect.mysql` the other — and
+are not a second `toSql`: `toSql` and `toPrisma` are unchanged.
+
+```ts
+import { engineGlobals, Operator, SqlDialect, toLensWhereSql, toWhereSql } from '@inixiative/json-rules';
+
+engineGlobals.set('sql.dialect', SqlDialect.mysql);
+
+toWhereSql(
+  { field: 'affiliation', operator: Operator.in, value: ['advocate', 'consultant'] },
+  { columns: { affiliation: '${fan_user.affiliation}' }, map, mapName: 'prisma', model: 'FanUser' },
+);
+// => "${fan_user.affiliation} IN ('advocate', 'consultant')"
+
+toLensWhereSql(lens, { columns });
+// => { root: '…' | null, relations: {}, mapDefaults: { prisma: { models: { BrandReferenceRequestFanUser: "${brand_reference_request_fan_user.affiliation} = 'advocate'" } } } }
+```
+
+- **Operators:** `equals`, `notEquals`, `in`, `notIn`, `exists`, `notExists`, inside `all` / `any`
+  (and `true` / `false`). Anything else — another operator, a date, array or aggregate rule,
+  `if` / `then` / `else` — throws, naming it. So do binds, `path` (column-to-column), offsets,
+  `coerceType`, case-insensitivity, a path across a bridge or through a to-many relation, anything
+  Json (a stored JSON null is a value to SQL and null to `check()`), and a DateTime or list
+  *value*. A DateTime's or list's existence compiles: `deletedAt notExists`, a lens's soft-delete
+  `where`, is `… IS NULL`. A rule with no `value` throws, as on every rail.
+- **Map:** `map` / `mapName` / `model` are required. A value is checked against its column's
+  kind (`leafFitViolations`, as `validateNarrowing` checks it) and an undeclared path is refused —
+  MySQL casts a mistyped literal instead of erroring, so `score = TRUE` would match 1 where
+  `check()` matches nothing. The map also finds a to-one relation's key for its `exists`
+  (`columns['<relation>.<key>']`: the related row's key, NULL when there is none), and says which
+  values have no form here.
+- **Columns:** `columns` maps a field path to the caller's SQL, used as written; the engine writes
+  no joins and no identifiers. A path missing from it throws, naming the path — it never falls back
+  to a quoted name, which MySQL's default mode reads as a string literal.
+- **Values** are written inline — there are no placeholders to fill. A string doubles `'`; on
+  MySQL it doubles `\` too (MySQL's default mode reads a backslash as an escape;
+  `NO_BACKSLASH_ESCAPES` is not supported). `in` is `IN (…)`; an enum compares as written, with no
+  cast.
+- **NULL rows:** negations keep them, as on every rail: `notEquals` / `notIn` are ORed with
+  `IS NULL`; `in [x, null]` matches NULL, `notIn [x, null]` doesn't.
+- **Collation:** `=` and `IN` compare under the column's collation. check() compares strings
+  exactly, so a `_ci` column (MySQL's default) also matches `'Advocate'` for `'advocate'`; compare a
+  binary-collated column where that matters.
+
+`toLensWhereSql(lens, { columns })` mirrors the lens: the root path's `where`s under `root` (null
+when it has none), each relation path's own under `relations`, keyed by the path, and each model
+default's (`mapDefaults[map].models[model].where`) under `mapDefaults`, keyed the same way — one
+predicate per model however many paths reach it. Each is the `where` as its layer wrote it: a
+parent layer's clamp on a hop is reported at that hop's path, never folded into what a later
+layer wrote through it. A `where` that reads through a relation the lens hides throws — that
+hop's clamps have no path to report at, and `check()` still carries them. A lens that spans maps
+reports every map's defaults; a caller writing one database reads its own map's. A path `where` reads `columns` by its path from the lens model (`status` at the root,
+`brandReferenceRequestFanUsers.id` below it); a model default by `'<Model>.<field>'`
+(`BrandReferenceRequestFanUser.affiliation`). It does not compile through `toSql`'s `{ lens }`
+path, which would fold the lens's `where`s into the predicate a second time.
+
+**Absent, not hidden.** A row a relation's `where` filters out is absent from the SQL join, so a
+negation through that relation holds for it; `check()` under the lens treats the row as hidden.
+The lens is a projection: the difference is accepted and documented.
+
 ## Backend Support Matrix
 
 Not every backend supports every rule shape.
@@ -845,6 +910,7 @@ Lens & bridges:
 - `projectLens`, `walkLensPath`, `readLensValue`, `LensValue`, `describeRule`, `describeRuleSources`
 - `toLensSelect`, `projectRows`, `LensSelect`, `LensRelationSelect`, `LensSelectOptions`, `ProjectRowsOptions`
 - `toSourceQueries`, `materializeSources`, `materializeSourceQuery`
+- `toLensWhereSql`, `LensWhereSql`, `LensWhereSqlOptions`
 - `PathProjection`, `ProjectedVisit`, `ProjectLensOptions`, `LensPathHop`, `LensPathResolution`, `RuleDescription`, `RuleSourceDescription`, `SourceQuery`, `SourcePrismaQuery`, `SourceSqlQuery`, `SourceSelect`, `SourceValues`, `SourceRowShape`, `MaterializeSourceQueryOptions`
 
 A lens has three forms, each with its own job:
@@ -875,7 +941,7 @@ const lens = composeLens('delegate-7', { user, 'org-acme': orgAcme, 'delegate-7'
 ### Operator Catalog
 
 What a rule builder can offer for a field. The catalog's constants are `FieldKind`,
-`RuleTarget`, `ValueShape`, `NUMERIC_KINDS` and `ALL_KINDS`; `getValueShape(operator, family)` takes an
+`RuleTarget`, `ValueShape`, `ConditionShape`, `NUMERIC_KINDS` and `ALL_KINDS`; `getValueShape(operator, family)` takes an
 `OperatorFamily` (`'field' | 'date' | 'array'`).
 
 ```ts
@@ -902,6 +968,7 @@ getValueShape('between', 'date'); // 'dateRange'
 | `getArrayOperators(target?)` | The array operators, narrowed to one target when given. |
 | `getAggregateOperators()` | The comparisons an aggregate rule takes. Every target compiles all of them. |
 | `getValueShape(operator, family)` | The operand an operator takes (`'scalar'`, `'range'`, `'dayList'`, …). `family` is `'field'`, `'date'` or `'array'`, since `between` is both a field and a date operator. Throws on an operator the family doesn't have. |
+| `getConditionShapeKeys(shape)` | `{ required, optional }`: the keys a node of a `ConditionShape` (`'all'`, `'any'`, `'if'`, `'field'`, `'aggregate'`, `'array'`, `'date'`) must have and the keys it may. A literal `true` / `false` is a condition too. |
 
 To ask whether a whole rule runs on a target (windows, scope refs and operators together), use
 `validateRule(rule, { target })`.