@inixiative/json-rules 3.18.0 → 3.19.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 +83 -1
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +121 -19
- package/dist/index.d.ts +121 -19
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -43,6 +43,7 @@ check(rule, { age: 16 }); // "Must be 18 or older"
|
|
|
43
43
|
- `if` / `then` / `else`
|
|
44
44
|
- array validation against nested object elements
|
|
45
45
|
- array aggregates: `sum` and `avg` across numeric arrays or relation lists
|
|
46
|
+
- value expressions: compute a value (`count`, `sum`, `avg`, `min`, `max`, `distinct`, a path, if / else) from a row with `evaluateValue`
|
|
46
47
|
- ordered windowing: first/last `N` with `orderBy` / `take` / `skip` (`check()`; `toPrisma()` compiles the extremal case and a `filter` alone)
|
|
47
48
|
- date comparisons with timezone-aware runtime evaluation
|
|
48
49
|
- relative & calendar date expressions ("last 30 days", "this month") via `within` and `ago`/`ahead`/`this`/`last`/`next`
|
|
@@ -209,6 +210,87 @@ Computes `sum` or `avg` of an array and compares the result to a value.
|
|
|
209
210
|
Empty-array semantics: `sum([]) = 0` and `avg([]) = 0`. A NULL or absent array is empty, and
|
|
210
211
|
NULL items are skipped, as SQL's `SUM` / `AVG` skip them.
|
|
211
212
|
|
|
213
|
+
### Value Expressions
|
|
214
|
+
|
|
215
|
+
A value expression computes a value from a row instead of testing it, in the grammar rules
|
|
216
|
+
already use. `evaluateValue(expression, row, options)` takes what `check()` takes (`bindings`,
|
|
217
|
+
`now`, `timeZone`, `weekStart`) and evaluates in memory.
|
|
218
|
+
|
|
219
|
+
| Shape | Returns |
|
|
220
|
+
| --- | --- |
|
|
221
|
+
| `5`, `'gold'`, `true`, `null`, a Date | the literal, as a stored value is written |
|
|
222
|
+
| `{ value }` | the literal (an object literal needs this form) |
|
|
223
|
+
| `{ path }` | the value at the path (`$.` for the row), null when absent |
|
|
224
|
+
| `{ bind }` | the bound value |
|
|
225
|
+
| `{ field, aggregate: { mode, field? }, filter?, orderBy?, take?, skip?, condition? }` | the aggregate rule's shape without `operator` / `value`: the aggregate itself |
|
|
226
|
+
| `{ if, then, else? }` | `then` when the condition holds, else `else` (null with no `else`) |
|
|
227
|
+
| `[item, …]` *(experimental)* | a list: each item's value; an `if` with no `else` that doesn't hold adds nothing |
|
|
228
|
+
| `{ list: [item, …], distinct? }` *(experimental)* | the same list; `distinct: true` keeps the first of equal items |
|
|
229
|
+
|
|
230
|
+
`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),
|
|
232
|
+
`min` and `max` (numbers or dates, the value as stored; null over no rows), and `distinct`
|
|
233
|
+
(strings, enums, dates, booleans or numbers: the values without repeats, first seen first, NULLs
|
|
234
|
+
skipped; `[]` over no rows). The window
|
|
235
|
+
runs first (filter → order → skip → take), then `condition`. An aggregate rule still compares
|
|
236
|
+
`sum` / `avg` only.
|
|
237
|
+
|
|
238
|
+
Values compare as stored, kind by kind: `distinct` keeps `1`, `Decimal('1')`, `1n` and `'1'` as
|
|
239
|
+
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
|
|
241
|
+
as 1, `'Int'` lets `min` / `max` order a string column of numbers (`'9'` before `'10'`), and
|
|
242
|
+
`'DateTime'` reads date strings as dates (a zoneless one in the evaluation's `timeZone`). A coercion
|
|
243
|
+
must be one the column can become, checked at save: a string reads as anything it parses to, a
|
|
244
|
+
number or date as another number, date or string, a boolean or enum as a string; Json and Bytes
|
|
245
|
+
read as nothing, and nothing reads as an enum. A numeric object read as a number throws past 15
|
|
246
|
+
significant digits, as a bigint past the safe range does. A value that won't coerce stays as it is: `distinct` returns it, so dirty data shows (`['3', 'abc']`
|
|
247
|
+
as `Int` gives `[3, 'abc']`), and `min` / `max` throw on it. A Decimal column orders by value without
|
|
248
|
+
`coerceType`; `min` / `max` return the Decimal as stored. `min` / `max` never order raw strings: character-code order
|
|
249
|
+
(`'Zebra'` before `'apple'`) would disagree with a database collation. `distinct` over strings
|
|
250
|
+
takes `caseInsensitive` (default: the engine's `string.caseInsensitive`), keeping the first spelling
|
|
251
|
+
seen; it lowers strings, which is close to, not the same as, a case- and accent-insensitive
|
|
252
|
+
collation such as MySQL's default.
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
// How many reference asks in the last 90 days
|
|
256
|
+
const asksLast90Days = {
|
|
257
|
+
field: 'brandReferenceRequestFanUsers',
|
|
258
|
+
aggregate: { mode: 'count' },
|
|
259
|
+
filter: {
|
|
260
|
+
all: [
|
|
261
|
+
{ field: 'affiliation', operator: Operator.equals, value: 'advocate' },
|
|
262
|
+
{ field: 'activatedAt', dateOperator: DateOperator.onOrAfter, value: { ago: { days: 90 } } },
|
|
263
|
+
],
|
|
264
|
+
},
|
|
265
|
+
};
|
|
266
|
+
evaluateValue(asksLast90Days, advocate, { now }); // 2
|
|
267
|
+
|
|
268
|
+
// The date of the last ask
|
|
269
|
+
const lastAskAt = {
|
|
270
|
+
field: 'brandReferenceRequestFanUsers',
|
|
271
|
+
aggregate: { mode: 'max', field: 'activatedAt' },
|
|
272
|
+
filter: { field: 'activatedAt', operator: Operator.exists },
|
|
273
|
+
};
|
|
274
|
+
|
|
275
|
+
// First match is an if / else chain; the last else is the default
|
|
276
|
+
const tier = {
|
|
277
|
+
if: { field: 'fanMissions', arrayOperator: ArrayOperator.atLeast, count: 3, condition: true },
|
|
278
|
+
then: { value: 'gold' },
|
|
279
|
+
else: { value: 'none' },
|
|
280
|
+
};
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
What a consumer checks before saving one:
|
|
284
|
+
|
|
285
|
+
| Function | Purpose |
|
|
286
|
+
| --- | --- |
|
|
287
|
+
| `validateValue(expr)` / `assertValidValue(expr)` | The shape, without data: each node exactly one kind, known keys, a known mode, and every condition it holds valid as `validateRule` sees it. |
|
|
288
|
+
| `inferValueType(expr, lens?)` | `{ kind, isList, nullable }`: a literal's kind, a path's column kind through the lens, `count` → `Int`, `sum` → the column's numeric kind, `avg` → `Float` (`Decimal` stays `Decimal`, nullable), `min` / `max` → the column's kind (nullable), `distinct` → a list of the column's kind (never null); with `coerceType`, that kind. Branches and list items must agree; two numeric kinds read as `Decimal` when either is, else `Float`. Throws on an expression with no type. The lens is needed wherever a column's kind is read. |
|
|
289
|
+
| `valueClockUnit(expr)` | `clockUnit` over every condition the expression holds: a 90-day window reads `day`. |
|
|
290
|
+
| `describeValue(expr, lens)` | Its type, the dotted paths it reads (`brandReferenceRequestFanUsers.activatedAt`), its clock unit, and every issue (shape, lens gate, type) as `{ path, code, message }`, without throwing. |
|
|
291
|
+
|
|
292
|
+
Value expressions evaluate in memory only; `toPrisma` / `toSql` do not compile them.
|
|
293
|
+
|
|
212
294
|
### Date Rule
|
|
213
295
|
|
|
214
296
|
```ts
|
|
@@ -650,7 +732,7 @@ null`.
|
|
|
650
732
|
|
|
651
733
|
| Key | Default | Governs |
|
|
652
734
|
| --- | --- | --- |
|
|
653
|
-
| `string.caseInsensitive` | `false` | Default for a rule's `caseInsensitive
|
|
735
|
+
| `string.caseInsensitive` | `false` | Default for a rule's `caseInsensitive`, and for a `distinct` value's. A rule's own flag wins. Read by `check()`, `toSql()`, `toPrisma()` and `evaluateValue()`. |
|
|
654
736
|
| `string.fuzzy` | `false` | Default for a rule's `fuzzy` (`true` or a `FuzzyConfig` `{ maxDistance?, maxRatio? }`): typo-tolerant `contains` / `notContains` on strings. A rule's own flag wins. The compilers have no fuzzy form: they refuse `contains` / `notContains` whenever fuzzy is on, by the rule or by this default. |
|
|
655
737
|
| `prismaOptions.datasource.provider` | `'postgresql'` | The Prisma connector. `toPrisma()` emits `mode: 'insensitive'` only for `postgresql`, `cockroachdb` and `mongodb`; the others are case-insensitive by collation and reject it. `toPrisma(rule, { datasource: { provider } })` overrides it per call. |
|
|
656
738
|
| `prismaOptions.anyNull` | your `@prisma/client`'s | Prisma's `AnyNull` for Json null checks (see above); set it only to use another client's. |
|