@inixiative/json-rules 2.19.7 → 2.20.0

package/README.md

@@ -534,6 +534,13 @@ compilers carry NULL rows explicitly:
 | `equals` / `notEquals` with `path: '$.other'` | `null === null` | `IS [NOT] DISTINCT FROM` | — |
 | `exists` / `notExists` | `!= null` / `== null` | `IS NOT NULL` / `IS NULL` | `{ not: null }` / `{ equals: null }` |
 
+The **absent set** of a path is wider than a NULL leaf: an optional to-one hop can be NULL too,
+and `{ rel: { col: { equals: null } } }` only matches when the relation exists. So every negation
+also carries `{ rel: { is: null } }` for each optional to-one hop on the path (licensed by the
+relation entry's `isRequired: false`) — `profile.bio notEquals 'x'` compiles to
+`{ OR: [{ profile: { bio: { not: 'x' } } }, { profile: { bio: { equals: null } } }, { profile: { is: null } }] }`,
+matching check() (a missing hop reads as `undefined`) and toSql (LEFT JOIN + `IS NULL`).
+
 `toPrisma()` can only add the null arm when it knows the column is nullable —
 an `equals: null` on a NOT NULL column is a Prisma validation error. Nullability
 comes from the field map: `FieldMapEntry.isRequired: false` (prisma-map emits it).
@@ -807,6 +814,7 @@ Composition across chained narrowings is pure intersection. `where` clauses are
 | --- | --- |
 | `validateNarrowing(narrowing)` | Throws on structural or chain violations (incl. unresolvable `where` paths and items invisible from ancestors). Call at narrowing construction. |
 | `projectByPath(lens)` | Returns `Map<dottedPath, ProjectedVisit>` — each declared path keys its own resolved narrowing (path picks/omits/enums chain-intersected ∩ `mapDefaults` for the target model). Sibling paths to the same model stay independent. Use for SDK-contract / OpenAPI emission, search-field enumeration, validation whitelists. See [docs/LENS.md §10](./docs/LENS.md). |
+| `ruleSourceValues(lens, rule)` | The values a rule names at each source the lens declares, keyed like `projectByPath` (`path` + `field`, with the source's `mapName` / `model`). Resolved via `walkLensPath`, so `mapDefaults` sources answer wherever their model appears. `dynamic: true` when the set can't be enumerated: a `path` / `bind` leaf, a substring / pattern / range / window operator, or an operator the catalog doesn't know — callers fail closed on it. The reverse question for a reference registry ("which rows does this rule name") — join `model` + `values`. |
 | `checkRuleAgainstLens(rule, lens)` | Validates a user rule's field paths and enum values against the narrowed lens, path-aware. Returns `{ ok, violations }`. The security gate. |
 | `applyLens(rule, narrowing)` | Composes the user rule with the lens's `where` clauses, injecting each at its anchor in the rule tree. Pass the result to `check` / `toPrisma` / `toSql`. |