@inixiative/json-rules 3.20.0 → 3.21.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,13 @@ 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'`; a sum always exists. To count no values as
215
+ low, say so: `any: [count == 0, avg < 3]`. A NULL or absent array is empty, and NULL items are
216
+ skipped, as SQL's `SUM` / `AVG` skip them.
212
217
 
213
218
  ### Value Expressions
214
219
 
@@ -228,7 +233,7 @@ already use. `evaluateValue(expression, row, options)` takes what `check()` take
228
233
  | `{ list: [item, …], distinct? }` *(experimental)* | the same list; `distinct: true` keeps the first of equal items |
229
234
 
230
235
  `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),
236
+ values, as SQL's `AVG`, and in an aggregate rule), `count` (the rows; with `aggregate.field`, the rows whose field has a value),
232
237
  `min` and `max` (numbers or dates, the value as stored; null over no rows), and `distinct`
233
238
  (strings, enums, dates, booleans or numbers: the values without repeats, first seen first, NULLs
234
239
  skipped; `[]` over no rows). The window
@@ -1178,7 +1183,7 @@ getOperatorsForKind('Int', 'toPrisma');
1178
1183
  // { field: ['equals', 'notEquals', 'lessThan', …], date: [] } — operators that kind takes on that target
1179
1184
 
1180
1185
  getArrayOperators('toSql'); // ['empty', 'notEmpty']
1181
- getAggregateOperators(); // ['equals', 'notEquals', 'lessThan', …, 'between', 'notBetween']
1186
+ getAggregateOperators(); // ['equals', 'notEquals', 'lessThan', …, 'notBetween', 'exists', 'notExists']
1182
1187
 
1183
1188
  getValueShape('between', 'field'); // 'range'
1184
1189
  getValueShape('between', 'date'); // 'dateRange'
@@ -1188,7 +1193,7 @@ getValueShape('between', 'date'); // 'dateRange'
1188
1193
  | --- | --- |
1189
1194
  | `getOperatorsForKind(kind, target?)` | `{ field, date }`: the field and date operators a `FieldKind` takes, narrowed to one target when given. |
1190
1195
  | `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. |
1196
+ | `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
1197
  | `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
1198
  | `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
1199