@inixiative/json-rules 3.15.1 → 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 +51 -1
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +13 -2
- package/dist/index.d.ts +13 -2
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -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.
|