@inixiative/json-rules 4.1.0 → 4.3.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
@@ -641,7 +641,7 @@ An enum compares exactly against its declared values. String, pattern and ordere
641
641
  don't apply to one, and the compilers refuse them. A case-insensitive equality or membership, or
642
642
  one naming a value the enum doesn't declare, compiles to a membership test over the declared
643
643
  values `check()` would match (plus the NULL arm for a negation). The field map must list the
644
- values (prisma-map does).
644
+ values (field-map's Prisma reader does).
645
645
 
646
646
  ```ts
647
647
  // map: { models: { U: { fields: { role: { kind: 'enum', type: 'Role' } } } }, enums: { Role: ['admin', 'member'] } }
@@ -769,9 +769,10 @@ for real rows (a pseudo record a grant is checked against), so a rule passes onl
769
769
  pins. `check()` only; the compilers read real columns.
770
770
 
771
771
  `validateRule(rule, { positive: true })` refuses every shape that can hold on a missing value
772
- (`if`/`then`/`else`, array and aggregate rules, the negations, `isEmpty` and `notExists`), so a rule
773
- checked that way passes only on what the row carries. A rule that means "no value" says `equals
774
- null`.
772
+ (`if`/`then`/`else`, array and aggregate rules, the negations, `isEmpty` and `notExists`) and every
773
+ null check (`equals null`, `in` with null among its values), so a rule checked that way passes only
774
+ on what the row carries. A null check holds on every row without a value, which is how a rule ends
775
+ up granting everything; name the value that is there instead (a kind, an explicit `'none'`).
775
776
 
776
777
  ## Engine Globals
777
778
 
@@ -1083,7 +1084,7 @@ and `in [null, …]` carry the same hop arms: a user with no profile has a NULL
1083
1084
 
1084
1085
  `toPrisma()` can only add the null arm when it knows the column is nullable, because
1085
1086
  an `equals: null` on a NOT NULL column is a Prisma validation error. Nullability
1086
- comes from the field map: `FieldMapEntry.isRequired: false` (prisma-map emits it).
1087
+ comes from the field map: `FieldMapEntry.isRequired: false` (field-map's Prisma reader emits it).
1087
1088
  Without `{ map, model }`, or on an entry that doesn't declare it, the bare
1088
1089
  `not` / `notIn` is emitted and NULL rows fall out.
1089
1090
 
@@ -1194,7 +1195,8 @@ Rules:
1194
1195
  Lens & bridges:
1195
1196
 
1196
1197
  - `Lens`, `LensNarrowing`, `ModelNarrowing`, `ModelDefaultNarrowing`, `NarrowingDefaults`, `EnumNarrowing`, `SourceSpec`, `SourceEntry`
1197
- - `FieldMap`, `FieldMapEntry`, `ModelEntry`, `SourceOption`, `FieldMapSet`, `Bridge`, `BridgeEndpoint`, `BridgeCardinality`, `BridgeDictionary`
1198
+ - `LensFieldMap`, `LensModelEntry`, `FieldMapEntry`, `BridgeEntry`, `SourceOption`, `FieldMapSet`, `Bridge`, `BridgeEndpoint`, `BridgeCardinality`, `BridgeDictionary` (the schema types themselves, `FieldMap` / `ModelEntry` / `FieldEntry`, are [`@inixiative/field-map`](https://github.com/inixiative/field-map)'s)
1199
+ - Typed spellings over a literal map (`typeof prismaMap`, as `field-map generate` writes it): `ConditionOn`, `ModelNarrowingOn`, `LensNarrowingOn`, `UncheckedPath`
1198
1200
  - `createLens`, `storeLens`, `composeLens`, `StoredLens`, `stitchFieldMaps`, `indexBridges`, `validateFieldMaps`, `assertValidFieldMaps`
1199
1201
  - `validateNarrowing`, `assertValidNarrowing`, `validateRuleInLens`, `narrowRule`, `coerceRule`
1200
1202
  - `bindLens`, `listLensBindings`, `getLensRoot`, `clampLens`, `LensClamps`
@@ -1401,7 +1403,7 @@ The `Lens` primitive is a schema-aware view layer over one or more `FieldMap`s.
1401
1403
 
1402
1404
  ### FieldMap & FieldMapSet
1403
1405
 
1404
- A `FieldMap` is `{ models, enums? }`: models keyed by name, plus an optional enum registry scoped to that source. A `FieldMapSet` groups one or more `FieldMap`s and declares the cross-source edges between them:
1406
+ A `FieldMap` is `{ models, enums? }`: models keyed by name, plus an optional enum registry scoped to that source. The type, the Prisma reader (`field-map generate`), the JSON Schema reader and the own-property readers are [`@inixiative/field-map`](https://github.com/inixiative/field-map)'s; json-rules reads a map as a `LensFieldMap` (a `FieldMap`, with its bridges stitched in and a projection's options). A `FieldMapSet` groups one or more `FieldMap`s and declares the cross-source edges between them:
1405
1407
 
1406
1408
  ```ts
1407
1409
  import { stitchFieldMaps } from '@inixiative/json-rules';
@@ -1750,6 +1752,28 @@ const holds = forRecheck.filter((row) => check(narrowRule(rule, narrowing), row,
1750
1752
  | `toLensSelect(lensOrNarrowing, options?)` | `{ select }` for `findMany` at the base model. It selects each visit's visible columns and the relations turned on there (one that is off is not fetched; the model-default tree bounds it), and every column a `where` on the way reads. A to-many relation carries its visit's clamps compiled as its `where`, so related rows come pre-narrowed, unless a clamp reads that list: a clamp reads it whole, as the database does, so it is fetched whole and `projectRows` cuts it. A to-one relation takes no `where` in Prisma, so `projectRows` drops one its clamp hides. A relation that shows no column (one turned on with all its columns hidden, or one a clamp reads only for presence or a count) is fetched by its key alone (the join key, else `id`), even a hidden one, as a clamp's columns are; never another column. The fetch carries it for the re-check and a viewer's projection drops it; a model with no key is not fetched, and presence on it can't be re-checked from fetched rows. A root that shows no column is selected by its `id` likewise. Bridges are skipped. It also selects what each projected source reads (the value, its label and axes, and every column and relation its option query's condition reads), as it does a clamp's columns, so `materializeSources` over the fetched rows offers what the database does; a viewer's projection drops them. For a source across a bridge that is its local reads: what it reads on this side, hidden or not, and each crossed bridge's local `on` key, so the rows plus the far side loaded under its bridge field answer it. A to-many relation's clamp that needs a counting step (a count or an aggregate), or has a window toPrisma can't compile, is refused (a `LensRefusal`, which `validateNarrowing` reports) before anything compiles. `options` is the clock for compiling the clamps. The root's own clamps are the query's `where`: `toPrisma(rule, { lens })`. |
1751
1753
  | `projectRows(lensOrNarrowing, rows, options?)` | Rows cut to what the lens shows, recursively. Hidden columns, and relations that are off or omitted, are removed. A row a visit's `where` hides is dropped from the root or a list, and a to-one row becomes `null`. `keepClampColumns: true` keeps the columns those `where`s and the projected sources read, even hidden ones, and a hidden to-one row, or a hidden row of a list a clamp reads, as those columns alone, so `check(narrowRule(rule, lens), row)` re-tests the clamps as the database does, for any rule the lens admits; that output carries hidden values, so never return it to a viewer. The other options (`now`, `bindings`) are what each `where` is checked with. A `Decimal` column's value, whether a Decimal.js-like object such as Prisma's `Decimal` (anything with `toNumber()`) or a numeric string, comes back a number, a list column element by element; a non-numeric value passes through. Plain JSON out. |
1752
1754
 
1755
+ ### Supplied bridges (no join)
1756
+
1757
+ A bridge usually joins on a field of each side (`on`). A **supplied bridge** has none: its far row
1758
+ is not found by a key, the caller puts it on the record under its endpoint key, and the lens reads
1759
+ it like any bridge. Who is acting is the case it exists for (permissions' `actor:` rows).
1760
+
1761
+ ```ts
1762
+ const bridge: Bridge = {
1763
+ endpoints: [{ fieldMap: 'app', model: 'Doc' }, { fieldMap: 'actor', model: 'User' }],
1764
+ cardinality: 'oneToOne',
1765
+ };
1766
+ // lens root: relations: { 'actor:User': {} }
1767
+ check({ field: 'ownerId', operator: Operator.equals, path: 'actor:User.id' }, {
1768
+ ...doc,
1769
+ 'actor:User': user,
1770
+ });
1771
+ ```
1772
+
1773
+ A supplied bridge is one-to-one; an `on` on one side only is refused (`stitchFieldMaps`).
1774
+ `indexBridges` skips it, and a source read across it fetches no local key. `isJoinedBridge`
1775
+ tells the two apart (`JoinedBridge`, `SuppliedBridge`).
1776
+
1753
1777
  ### Evaluating Across Bridges
1754
1778
 
1755
1779
  `path:` refs (used for value comparisons) walk via the same dotted-path mechanism as `field:`. Bridge keys (`'salesforce:Contact'`) are plain object properties, so `path: 'salesforce:Contact.industry'` works in both `field:` (left side) and `path:` (right side) positions.