@inixiative/json-rules 2.18.4 → 2.19.1

package/README.md

@@ -494,6 +494,42 @@ Not every backend supports every rule shape.
 | Windowing (`orderBy` / `take` / `skip`) | Yes | Extremal (`take:1`, aligned) | No |
 | `path: '$.field'` current-element / same-row refs | Yes | No | Yes |
 
+### NULL Semantics
+
+A negated operator is the complement of its positive form — the same answer
+`check()` gives, where `null !== 'x'` is simply true. SQL's three-valued logic
+disagrees (`col <> 'x'` is NULL, never true, for a NULL column), so the
+compilers carry NULL rows explicitly:
+
+| Rule | `check()` on `{ col: null }` | `toSql()` | `toPrisma()` (nullable column) |
+| --- | --- | --- | --- |
+| `notEquals 'x'` / `notContains` / `notMatches` / `notBetween` | matches | `(col <> $1 OR col IS NULL)` | `{ OR: [{ col: { not: 'x' } }, { col: { equals: null } }] }` |
+| `notIn ['x']` | matches | `(col <> ALL($1) OR col IS NULL)` | `{ OR: [{ col: { notIn: ['x'] } }, { col: { equals: null } }] }` |
+| `in ['x', null]` | matches | `(col = ANY($1) OR col IS NULL)` | `{ OR: [{ col: { in: ['x'] } }, { col: { equals: null } }] }` |
+| `notIn ['x', null]` | no match | `(col <> ALL($1) AND col IS NOT NULL)` | `{ AND: [{ col: { notIn: ['x'] } }, { col: { not: null } }] }` |
+| `equals` / `notEquals` with `path: '$.other'` | `null === null` | `IS [NOT] DISTINCT FROM` | — |
+| `exists` / `notExists` | `!= null` / `== null` | `IS NOT NULL` / `IS NULL` | `{ not: null }` / `{ equals: 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).
+Without `{ map, model }`, or on an entry that doesn't declare it, the bare
+`not` / `notIn` is emitted and NULL rows fall out, as they always did.
+
+Date rules answer the same way on both rails, from the other direction: a bare
+boundary is not something a NULL column satisfies, so `check()` reports the rule's
+ordinary non-match (honoring `error`) for a null or absent field, and the compilers
+keep the bare `<` / `NOT BETWEEN`. To match the never-seen rows too, ask for them:
+`{ any: [{ field, operator: 'notExists' }, { field, dateOperator: 'before', … }] }`.
+
+| Rule | `check()` on `{ col: null }` | `toSql()` | `toPrisma()` |
+| --- | --- | --- | --- |
+| any `dateOperator` | no match | `col < $1` (NULL never satisfies) | `{ col: { lt: … } }` |
+| `notExists` OR `before` | matches via the first arm | `(col IS NULL OR col < $1)` | `{ OR: [{ col: { equals: null } }, { col: { lt: … } }] }` |
+
+`0` is an instant (1970-01-01) and compares; `''` is malformed data and raises
+`"is not a valid date"`.
+
 ### Prisma Limitations
 
 - `matches` and `notMatches` are not supported by Prisma output