@inixiative/json-rules 3.20.0 → 3.22.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
@@ -207,8 +207,16 @@ Computes `sum` or `avg` of an array and compares the result to a value.
207
207
  }
208
208
  ```
209
209
 
210
- Empty-array semantics: `sum([]) = 0` and `avg([]) = 0`. A NULL or absent array is empty, and
211
- NULL items are skipped, as SQL's `SUM` / `AVG` skip them.
210
+ Empty-array semantics: `sum([]) = 0`, and `avg([])` is NULL, as SQL's `AVG` is: nothing has no
211
+ average. An average over no values is compared as a NULL column is — a positive operator
212
+ (`lessThan`, `equals`, `between`, …) doesn't hold, a negated one (`notEquals`, `notBetween`) does —
213
+ and `negate()` adds the "no values" arm, the aggregate's own `notExists`, as it adds `notExists`
214
+ to a field's. Ask for it directly with `operator: 'exists'` / `'notExists'` (or, as on a field,
215
+ `equals` / `notEquals` `null`); a sum always exists. An aggregate rule's `coerceType` (a numeric
216
+ kind) parses each item before it is added (`'3'` → 3), as `coerceType` does on a field; without
217
+ it the items must be numbers. To count no values as
218
+ low, say so: `any: [count == 0, avg < 3]`. A NULL or absent array is empty, and NULL items are
219
+ skipped, as SQL's `SUM` / `AVG` skip them.
212
220
 
213
221
  ### Value Expressions
214
222
 
@@ -228,7 +236,7 @@ already use. `evaluateValue(expression, row, options)` takes what `check()` take
228
236
  | `{ list: [item, …], distinct? }` *(experimental)* | the same list; `distinct: true` keeps the first of equal items |
229
237
 
230
238
  `aggregate.mode` is one of `VALUE_AGGREGATE_MODES`: `sum` (0 over no rows), `avg` (null over no
231
- values, as SQL's `AVG`; an aggregate rule still compares 0), `count` (the rows; with `aggregate.field`, the rows whose field has a value),
239
+ values, as SQL's `AVG`, and in an aggregate rule), `count` (the rows; with `aggregate.field`, the rows whose field has a value),
232
240
  `min` and `max` (numbers or dates, the value as stored; null over no rows), and `distinct`
233
241
  (strings, enums, dates, booleans or numbers: the values without repeats, first seen first, NULLs
234
242
  skipped; `[]` over no rows). The window
@@ -237,7 +245,8 @@ runs first (filter → order → skip → take), then `condition`. An aggregate
237
245
 
238
246
  Values compare as stored, kind by kind: `distinct` keeps `1`, `Decimal('1')`, `1n` and `'1'` as
239
247
  four values, which shows mixed data rather than hiding it. To read them as one kind, give
240
- `distinct`, `min` or `max` a `coerceType` (as on a field rule): `coerceType: 'Decimal'` reads all four
248
+ `distinct`, `min` or `max` a `coerceType` (as on a field rule; on `sum` / `avg` it parses each
249
+ item before adding it, as on an aggregate rule): `coerceType: 'Decimal'` reads all four
241
250
  as 1, `'Int'` lets `min` / `max` order a string column of numbers (`'9'` before `'10'`), and
242
251
  `'DateTime'` reads date strings as dates (a zoneless one in the evaluation's `timeZone`). A coercion
243
252
  must be one the column can become, checked at save: a string reads as anything it parses to, a
@@ -1062,6 +1071,7 @@ positive operator, ask for them:
1062
1071
  - `path: '$.field'` column-to-column comparisons are not supported by Prisma `WHERE`; no scope ref (`$$.` path, prefixed `field`) compiles
1063
1072
  - count-based and aggregate relation operators require `{ map, model }`
1064
1073
  - aggregate rules on JSON/native stored arrays are not supported by Prisma; use `toSql()` or `check()` for those
1074
+ - an aggregate rule compared against a column (`path`) is refused: Prisma computes the aggregate in a `groupBy`, whose `having` can't read the parent row
1065
1075
  - element conditions (`all` / `any` / `none` / counts) over a scalar list or a Json array are not supported by Prisma; test a list's membership with `contains`
1066
1076
  - a field path through a to-many relation (`posts.title`) is an error on both compilers; compare its rows with an array rule on `posts`
1067
1077
  - Prisma loads a NULL scalar-list column as `[]`, so `check()` over Prisma-loaded rows reads it as an empty list while the compilers read NULL; a list Prisma writes is never NULL, so this only matters for rows written outside Prisma
@@ -1088,7 +1098,20 @@ engines themselves differ:
1088
1098
  `check()` compares UTF-16 code units, Postgres the column's collation.
1089
1099
  - An array or aggregate rule on a Json value that isn't an array is a data error. `check()`
1090
1100
  throws on it; SQL can't raise per row, so it reads the value as an empty array, for an
1091
- aggregate and for `empty` / `notEmpty` alike.
1101
+ aggregate and for `empty` / `notEmpty` alike. Prisma's `notEmpty` holds on an array only, as
1102
+ SQL's does, but Prisma has no filter for "not an array", so its `empty` doesn't match one: on
1103
+ Prisma a non-array value satisfies neither `notEmpty` nor its negation, and an `all` whose
1104
+ condition is a `notEmpty` (compiled as no item where it fails) carries that through.
1105
+ - A Json-array `sum` / `avg` over numbers stored as strings (`["1", "2"]`): without
1106
+ `coerceType`, `check()` throws on them, and SQL casts them with `::numeric`. Give the aggregate
1107
+ rule `coerceType: 'Float'` (or `'Int'` / `'Decimal'`) and `check()` parses each item as SQL does.
1108
+ Postgres's `numeric` also parses text JavaScript doesn't (`'1_000'`, `'Infinity'`, `'NaN'`,
1109
+ `'1e400'`); `check()` keeps its error on those.
1110
+ - `check()` adds JavaScript doubles; SQL adds exact `numeric`. A Json array `[0.1, 0.2]` sums to
1111
+ `0.30000000000000004` in `check()` and `0.3` in SQL, so `sum equals 0.3` holds on SQL only.
1112
+ Compare a computed sum with a tolerance (`between`) rather than `equals`.
1113
+ - Under `coerceType: 'Decimal'`, an item past 15 significant digits — a Decimal object or a
1114
+ numeric string — throws in `check()` rather than round; SQL's `numeric` reads it exactly.
1092
1115
 
1093
1116
  ## TypeScript Types
1094
1117
 
@@ -1178,7 +1201,7 @@ getOperatorsForKind('Int', 'toPrisma');
1178
1201
  // { field: ['equals', 'notEquals', 'lessThan', …], date: [] } — operators that kind takes on that target
1179
1202
 
1180
1203
  getArrayOperators('toSql'); // ['empty', 'notEmpty']
1181
- getAggregateOperators(); // ['equals', 'notEquals', 'lessThan', …, 'between', 'notBetween']
1204
+ getAggregateOperators(); // ['equals', 'notEquals', 'lessThan', …, 'notBetween', 'exists', 'notExists']
1182
1205
 
1183
1206
  getValueShape('between', 'field'); // 'range'
1184
1207
  getValueShape('between', 'date'); // 'dateRange'
@@ -1188,7 +1211,7 @@ getValueShape('between', 'date'); // 'dateRange'
1188
1211
  | --- | --- |
1189
1212
  | `getOperatorsForKind(kind, target?)` | `{ field, date }`: the field and date operators a `FieldKind` takes, narrowed to one target when given. |
1190
1213
  | `getArrayOperators(target?)` | The array operators, narrowed to one target when given. |
1191
- | `getAggregateOperators()` | The comparisons an aggregate rule takes. Every target compiles all of them. |
1214
+ | `getAggregateOperators()` | What an aggregate rule asks of its number: the comparisons, and `exists` / `notExists` (an average over no values has none). Every target compiles all of them. |
1192
1215
  | `getValueShape(operator, family)` | The operand an operator takes (`'scalar'`, `'range'`, `'dayList'`, …). `family` is `'field'`, `'date'` or `'array'`, since `between` is both a field and a date operator. Throws on an operator the family doesn't have. |
1193
1216
  | `getConditionShapeKeys(shape)` | `{ required, optional }`: the keys a node of a `ConditionShape` (`'all'`, `'any'`, `'if'`, `'field'`, `'aggregate'`, `'array'`, `'date'`) must have and the keys it may. A literal `true` / `false` is a condition too. |
1194
1217