@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 +30 -7
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +10 -5
- package/dist/index.d.ts +10 -5
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
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
|
|
211
|
-
|
|
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
|
|
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
|
|
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', …, '
|
|
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()` |
|
|
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
|
|