@inixiative/json-rules 3.15.0 → 3.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -654,7 +654,7 @@ null`.
654
654
  | `string.fuzzy` | `false` | Default for a rule's `fuzzy` (`true` or a `FuzzyConfig` `{ maxDistance?, maxRatio? }`): typo-tolerant `contains` / `notContains` on strings. A rule's own flag wins. The compilers have no fuzzy form: they refuse `contains` / `notContains` whenever fuzzy is on, by the rule or by this default. |
655
655
  | `prismaOptions.datasource.provider` | `'postgresql'` | The Prisma connector. `toPrisma()` emits `mode: 'insensitive'` only for `postgresql`, `cockroachdb` and `mongodb`; the others are case-insensitive by collation and reject it. `toPrisma(rule, { datasource: { provider } })` overrides it per call. |
656
656
  | `prismaOptions.anyNull` | your `@prisma/client`'s | Prisma's `AnyNull` for Json null checks (see above); set it only to use another client's. |
657
- | `clock.finestUnit` | `'second'` | The finest clock unit a rule may read: one of `CLOCK_UNITS`, or its plural (`'hours'` reads as `'hour'`); anything else throws when a rule reads the clock. A comparison that reads the clock (its value, or an end of its range, is a relative date) fails when any unit it names is finer, the offset moving it included: `check`, `toPrisma` and `toSql` throw and `validateRule` reports `clock_unit_below_floor`. The rule decides as written, so an amount read from the row or a binding (`{ minutes: { path } }`, a null one too) fails the same, and a bound whole expression is held to it once bound. Under `'hour'`, `{ ago: { minutes: 30 } }`, `{ this: 'minute' }` and `{ ago: { days: 1 } }` offset by `{ ago: { minutes: 5 } }` fail. A comparison that reads no clock (an absolute date, a column compare) is never refused, offset or not. A caller whose finest tick is an hour sets it once at boot. |
657
+ | `clock.finestUnit` | `'second'` | The finest unit a date rule may name: one of `CLOCK_UNITS`, or its plural (`'hours'` reads as `'hour'`); anything else throws when a date rule is evaluated. Every unit a date rule names counts, in its value (a relative date, either end of a range) and in its offset, whatever it compares against: a relative date, an absolute one or another column. A finer one fails: `check`, `toPrisma` and `toSql` throw and `validateRule` reports `clock_unit_below_floor`. The rule decides as written, so an amount read from the row or a binding (`{ minutes: { path } }`, a null one too) fails the same, and a bound whole expression is held to it once bound. Under `'hour'`, `{ ago: { minutes: 30 } }`, `{ this: 'minute' }`, and any compare offset by `{ ago: { minutes: 5 } }` fail. A caller whose finest tick is an hour sets it once at boot. |
658
658
 
659
659
  ```ts
660
660
  import { engineGlobals } from '@inixiative/json-rules';
@@ -792,7 +792,7 @@ toLensWhereSql(lens, { columns, tables });
792
792
  exactly, so a `_ci` column (MySQL's default) also matches `'Advocate'` for `'advocate'`; compare a
793
793
  binary-collated column where that matters.
794
794
 
795
- `toLensWhereSql(lens, { columns, tables? })` mirrors the lens: the root path's `where`s under `root` (null
795
+ `toLensWhereSql(lens, { columns, tables?, toMany? })` mirrors the lens: the root path's `where`s under `root` (null
796
796
  when it has none), each relation path's own under `relations`, keyed by the path, and each model
797
797
  default's (`mapDefaults[map].models[model].where`) under `mapDefaults`, keyed the same way — one
798
798
  predicate per model however many paths reach it. Each is the `where` as its layer wrote it: a
@@ -818,6 +818,56 @@ the lens hides throws, and its condition's fields are checked from the relation,
818
818
  model it sits on. A model default compiles to one predicate for every path that reaches its
819
819
  model, so it throws when a to-many relation it reads carries different clamps on two of them.
820
820
 
821
+ **Join mode — `toMany: 'join'`.** For a caller that can't run a correlated subquery (an Omni
822
+ topic rebuilds one as its own query and loses the correlation), the root's `where` reads a to-many
823
+ relation on the row the caller's join brings instead. Nothing about the join is a new option: the
824
+ caller LEFT JOINs each to-many relation the root's `where` reads (a relation the lens declares),
825
+ ON the map's relation keys (`relationKeys`, the same keys a to-one relation's existence reads) AND
826
+ `relations['<path>']` AND the related model's `mapDefaults` entry, and reads the related columns as
827
+ `columns['<path>.<field>']`. `tables` is not read. A join the `where` does not read only fans the
828
+ rows out (count distinct); a read of a relation the caller did not join fails loudly (a missing
829
+ column).
830
+
831
+ ```ts
832
+ toLensWhereSql(lens, { columns, toMany: 'join' });
833
+ // root: "(${fan_users.deleted_at} IS NULL AND ${fan_user_affiliation.fan_user_uuid} IS NOT NULL)"
834
+ // relations: { affiliations: "(${fan_user_affiliation.affiliation} = 'advocate' AND ${fan_user_affiliation.ended_at} IS NULL)" }
835
+ // the topic: LEFT JOIN fan_user_affiliation ON <keys> AND relations.affiliations [AND its model default]
836
+ ```
837
+
838
+ - **What compiles:** `notEmpty` is `<key> IS NOT NULL`, and `any(cond)` is
839
+ `(<key> IS NOT NULL AND cond)`, with `cond` on the joined columns. The key is the first key
840
+ column: a matched row's key equals the parent's and is never NULL, an unmatched row is all NULL,
841
+ so one column decides. `cond` may hold on a missing value (`endedAt notExists`): the
842
+ `IS NOT NULL` guard has already dropped the all-NULL row of a parent with no rows.
843
+ - **Positive operators only.** `empty`, `none` and `all` can hold with no rows (the catalog's
844
+ `holdsOnNoRows`), which takes an anti-join, not the topic's join — `all(cond)` is
845
+ `none(NOT cond)`, and the join drops the parents with no rows that `all` keeps. They throw, as do
846
+ the counts, `exists` / `notExists` on the relation (a to-many relation has one spelling, an
847
+ `arrayOperator` rule) and a field read through it (`affiliations.affiliation`).
848
+ - **The root's `where` only.** A relation path's `where` sits in that relation's ON, ahead of the
849
+ joins below it, and a model default compiles once for every path that reaches its model, where
850
+ the join exists only on the paths the lens shows: either one reading a to-many relation throws.
851
+ So do a to-many relation, or any relation, read inside a joined `any`.
852
+ - **One `any` per relation.** One joined row stands for the relation, so two `any` rules on it
853
+ (`any advocate AND any prospect`, in one `where` or across layers) would need one row to meet
854
+ both, where `check()` lets each find its own: it throws. Write one `any` whose condition says
855
+ which row (`any: [advocate, prospect]` for either). `notEmpty` beside an `any` is fine.
856
+ - **One alias per model default.** `mapDefaults` holds one predicate per model, on
857
+ `columns['<Model>.<field>']`, so it can sit on one table alias. A joined relation whose model has
858
+ a default `where` throws when the root's `where` needs that default on a second alias too: a
859
+ to-many self-relation (the root is that model as well), or two joined relations that reach one
860
+ model. Compile with `toMany: 'subquery'`, which carries the default inside each `EXISTS`.
861
+ - **The layer guard.** The ON carries every clamp on the relation, from every layer, but `check()`
862
+ reads a `where` through the clamps of the layers above its own only. So a root `where` that
863
+ reads a joined relation throws when one of that relation's clamps (its path `where` or its
864
+ model's default) sits in the `where`'s own layer or a later one, naming the path and both layers.
865
+ Move the clamp into an earlier narrowing: then the ON is exactly what `check()` reads.
866
+ - **`any(cond)` hides rows.** The rows that fail `cond` are gone from the whole query, not only
867
+ from the filter; `check()` hides nothing. Where you can, write the condition as the relation's
868
+ `where` (in a layer above) and have the root read `notEmpty`.
869
+ - **Fan-out.** A joined to-many relation repeats the parent once per related row: count distinct.
870
+
821
871
  **Absent, not hidden.** A row a relation's `where` filters out is absent from the SQL join, so a
822
872
  negation through that relation holds for it; `check()` under the lens treats the row as hidden.
823
873
  The lens is a projection: the difference is accepted and documented.