@inixiative/json-rules 3.6.0 → 3.9.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,115 @@ 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 { ArrayOperator, 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')"
+
+toWhereSql(
+  {
+    field: 'affiliations',
+    arrayOperator: ArrayOperator.any,
+    condition: { field: 'affiliation', operator: Operator.equals, value: 'advocate' },
+  },
+  {
+    columns: {
+      uuid: '${fan_users.uuid}',
+      'affiliations.fanUserUuid': 'a.fanUserUuid',
+      'affiliations.affiliation': 'a.affiliation',
+    },
+    tables: { affiliations: 'FanUserAffiliation AS a' },
+    map,
+    mapName: 'prisma',
+    model: 'FanUser',
+  },
+);
+// => "EXISTS (SELECT 1 FROM FanUserAffiliation AS a WHERE a.fanUserUuid = ${fan_users.uuid} AND (a.affiliation = 'advocate'))"
+
+toLensWhereSql(lens, { columns, tables });
+// => { 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`), and `any` / `all` / `none` / `empty` / `notEmpty` over a to-many relation
+  (below). Anything else — another operator, a date rule, a count or windowed array rule, an
+  aggregate, `if` / `then` / `else` — throws, naming it. So do binds, `path` (column-to-column),
+  offsets, `coerceType`, case-insensitivity, a path across a bridge, a field rule 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.
+- **To-many relations:** an array rule on a to-many relation of the model is one subquery on the
+  relation's table, keyed to the row: `any` / `notEmpty` is `EXISTS`, `none` / `empty` is
+  `NOT EXISTS`, and `all` is `NOT EXISTS` of a row whose condition `IS NOT TRUE` — a NULL result
+  fails, as in `check()`. The map gives the keys (`relationKeys`; a composite key ANDs every pair):
+  the row's side reads `columns['<key>']`, the related side `columns['<relation>.<key>']`.
+  `tables['<relation>']` is the table, written after `FROM` as given, with the alias its columns
+  read. The condition compiles as above and reads `columns['<relation>.<field>']`; a to-many
+  relation of the related rows nests (`tables['<relation>.<relation>']`). A relation behind
+  another one (`profile.affiliations`), a relation missing from `tables`, `atLeast` / `atMost` /
+  `exactly`, a window (`filter` / `orderBy` / `take` / `skip`) and a fieldless array rule throw.
+- **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, tables? })` 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.
+
+An array rule on a to-many relation has no join to put that relation's clamps on, so its subquery
+carries them: the relation path's own `where` and the related model's default, ANDed beside the
+key (outside the `IS NOT TRUE` of an `all`, as `check()` filters the rows before it tests them).
+It carries only the clamps of the layers above the layer that wrote the `where`, which is what
+`check()` reads it through: a layer's clamps narrow the layers after it, never its own conditions.
+A clamp in the same layer or a later one stays out, so a later layer can't widen what a `none` or
+an `empty` admitted. Each clamp reads its own relations through the layers above its own. The
+clamps are still reported at their own path and model. `tables` reads like `columns`: by the
+relation's path from the lens model in a path `where` (`affiliations`), by
+`'<Model>.<relation>'` in a model default (`FanUser.affiliations`). An array rule on a relation
+the lens hides throws, and its condition's fields are checked from the relation, not from the
+model it sits on. A model default compiles to one predicate for every path that reaches its
+model, so it throws when a to-many relation it reads carries different clamps on two of them.
+
+**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 +955,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: