@inixiative/json-rules 3.23.0 → 4.1.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 +33 -2
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +40 -5
- package/dist/index.d.ts +40 -5
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -302,6 +302,37 @@ What a consumer checks before saving one:
|
|
|
302
302
|
|
|
303
303
|
Value expressions evaluate in memory only; `toPrisma` / `toSql` do not compile them.
|
|
304
304
|
|
|
305
|
+
### Categorize
|
|
306
|
+
|
|
307
|
+
`categorize(categorization, row, options)` puts a row in a category: cases checked in order, each
|
|
308
|
+
an `if` (a rule) and a `then` (a value expression), with the options `check()` takes.
|
|
309
|
+
|
|
310
|
+
```ts
|
|
311
|
+
categorize(
|
|
312
|
+
{
|
|
313
|
+
cases: [
|
|
314
|
+
{ if: { field: 'deals', operator: 'greaterThanEquals', value: 10 }, then: 'gold' },
|
|
315
|
+
{ if: { field: 'deals', operator: 'greaterThanEquals', value: 3 }, then: 'silver' },
|
|
316
|
+
],
|
|
317
|
+
default: 'bronze',
|
|
318
|
+
},
|
|
319
|
+
{ deals: 4 },
|
|
320
|
+
); // 'silver'
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
| Key | Meaning |
|
|
324
|
+
| --- | --- |
|
|
325
|
+
| `cases` | `[{ if, then }]`, in order |
|
|
326
|
+
| `match` | `'first'` (the default): the first case that holds gives the value, and later cases are not checked. `'all'`: every case that holds, in case order, as a list |
|
|
327
|
+
| `default` | the value when no case holds (under `all`, a list of it); with none, `null` (`[]` under `all`) |
|
|
328
|
+
|
|
329
|
+
A `then` can be any value expression: a field/value map is `{ value: { status: 'canceled' } }`.
|
|
330
|
+
A case that throws stops the categorization; it never falls through to a later case or the
|
|
331
|
+
default, which would give a value its author ordered below it. `validateCategorization` /
|
|
332
|
+
`assertValidCategorization` check the shape without data: known keys, a known `match`, each `if`
|
|
333
|
+
as `validateRule` sees it and each `then` and the `default` as `validateValue` does. In memory
|
|
334
|
+
only, like value expressions.
|
|
335
|
+
|
|
305
336
|
### Date Rule
|
|
306
337
|
|
|
307
338
|
```ts
|
|
@@ -1491,8 +1522,8 @@ Composition across chained narrowings is pure intersection: relations are turned
|
|
|
1491
1522
|
| `validateNarrowing(narrowing)` | Returns `{ ok, errors: { path, message, code }[] }` for structural or chain problems, one code each: `not_in_lens`, `not_visible` (an item an ancestor hid, or a relation the parent doesn't show), `conflicting_selection` (picks beside an omitted column), `wrong_kind` (a relation named in `picks`, among others), `value_not_allowed`, `invalid_source` (a source label / axis crossing a relation that is off, among others), `invalid_binding`, `invalid_value_source`, `scope_out_of_bounds`, the codes of the `LensRefusal`s it folds in (`unsupported_clamp`, among others), plus the lens gate's codes for a `where`. `assertValidNarrowing` throws instead. Call at narrowing construction. |
|
|
1492
1523
|
| `assertValidFieldMaps(set)` | Throws when a field name in any map holds `.` or `:` (a path step and a bridge marker). `validateFieldMaps(set)` returns `{ ok, errors }` with code `invalid_field_name`. To check a single map, wrap it: `assertValidFieldMaps({ maps: { prisma: map } })`. |
|
|
1493
1524
|
| `projectLens(lens)` | Returns `Record<dottedPath, ProjectedVisit>`: each path the relations turned on reach keys its own resolved narrowing (path picks/omits/enums chain-intersected ∩ `mapDefaults` for the target model); a relation field appears only where it is on. Sibling paths to the same model stay independent. Use for SDK-contract / OpenAPI emission, search-field enumeration, validation whitelists. See [docs/LENS.md §10](./docs/LENS.md). |
|
|
1494
|
-
| `describeRuleSources(rule, lens)` | The values a rule names at each source the lens declares, keyed like `projectLens` (`path` + `field`, with the source's `mapName` / `model`).
|
|
1495
|
-
| `validateRuleInLens(rule, lens)` | Validates a user rule's field paths and enum values against the narrowed lens, path-aware. Returns `{ ok, errors: { path, message, code }[] }` like `validateRule` (codes such as `not_in_lens`, `operator_kind_mismatch`, `invalid_value`, `value_not_allowed`). Every relation a field, a value ref, an offset or an `orderBy` / aggregate field crosses must be turned on. A bare value `path` is a root-row column, gated like a field. The security gate. |
|
|
1525
|
+
| `describeRuleSources(rule, lens)` | The values a rule names at each source the lens declares, keyed like `projectLens` (`path` + `field`, with the source's `mapName` / `model`). Each field is walked scope by scope as `validateRuleInLens` walks it, so a path the gate refuses (one continuing past a to-many relation) is silent, and `mapDefaults` sources answer wherever a relation turned on reaches their model. `dynamic: true` when the set can't be enumerated: a `path` / `bind` leaf, an offset or a read amount that moves the value, a substring / pattern / range / window operator, or an operator the catalog doesn't know; callers fail closed on it. The reverse question for a reference registry ("which rows does this rule name"): join `model` + `values`. |
|
|
1526
|
+
| `validateRuleInLens(rule, lens)` | Validates a user rule's field paths and enum values against the narrowed lens, path-aware. Returns `{ ok, errors: { path, message, code }[] }` like `validateRule` (codes such as `not_in_lens`, `operator_kind_mismatch`, `invalid_value`, `value_not_allowed`). Every relation a field, a value ref, an offset or an `orderBy` / aggregate field crosses must be turned on, and none may cross a to-many relation outside an array rule (`posts.title` is refused, as both compilers refuse it; read `posts` with an array rule). A path may address through one; a rule may only cross one under an iterator: see [docs/LENS.md, Address vs cross](docs/LENS.md#address-vs-cross-to-many-relations). A bare value `path` is a root-row column, gated like a field. The security gate. |
|
|
1496
1527
|
| `describeRule(rule, lens)` | `{ sources, bridgesCrossed, supportedTargets, errors }`: the maps a rule reads, whether it crosses a bridge, which of `check` / `toPrisma` / `toSql` can run it (by the rule's shape, as `validateRule` reads it; a compiler may still refuse a field's kind, such as a date rule on a String column on Prisma), and the lens gate's `ValidationIssue`s. For routing and UX; `validateRuleInLens` stays the gate. |
|
|
1497
1528
|
| `getLensRoot(lensOrNarrowing)` | The base lens a narrowing chain is rooted at; a lens is its own. Throws on a cyclic chain. |
|
|
1498
1529
|
| `clampLens(lens, clamps)` | The lens with `clamps` (`{ root?: { where }, mapDefaults?: { [map]: { models: { [model]: { where?, sources? } } } } }`) ANDed into its first narrowing over the base lens, one added over a bare lens; later layers kept as they were. Only the first layer's clamps read the whole schema, so a clamp on what a later layer hides goes here. A source's `where` ANDs; its `label` / `groupBy` win, and a source clamp on a field with none adds that option set. Wheres only narrow. |
|