@inixiative/json-rules 3.18.0 → 3.19.1

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
@@ -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`. A rule's own flag wins. Read by `check()`, `toSql()` and `toPrisma()`. |
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. |