@inixiative/json-rules 3.4.0 → 3.4.1

package/README.md

@@ -1228,8 +1228,7 @@ const [query] = toSourceQueries(narrowing);
 // query.composedWhere => the node's `where` AND the source's eligibility, narrowed as a rule is
 // query.prisma => { model: 'User', distinct: ['region'], select: { region: true }, where: { AND: [...] } }
 // query.sql => { sql: 'SELECT DISTINCT "t0"."region" FROM "User" AS "t0" WHERE (...)', params: ['t-42', true] }
-// `prisma` is null for a source read across a bridge (see "Sources across a bridge" below).
-if (query.prisma === null) throw new Error(query.sql.error);
+// A query with `recheck` (a source across a bridge) returns candidates; see "Sources across a bridge".
 const { distinct, select, where } = query.prisma;
 const rows = await prisma.user.findMany({ distinct, select, where });
 const values = materializeSourceQuery(query, rows); // { path, mapName, model, field, options: [{ value }] }
@@ -1243,8 +1242,8 @@ const projection = projectLens(narrowing, { sourceValues: [values] });
 
 | Function | Purpose |
 | --- | --- |
-| `toSourceQueries(lensOrNarrowing, options?)` | `SourceQuery[]`, one per sourced field: `{ path, mapName, model, field, label?, groupBy?, composedWhere, prisma, sql }`. `options` is the clock (`now`, `timeZone`, `weekStart`) a relative date in the where compiles with — required for one, a plain usage error without it; bind a lens's binds with `bindLens` first. `prisma.steps` is present when the where needs `executePrismaPlan`. `sql.sql` is `null` with an `error` when SQL can't express the where. A where that crosses a bridge has no query at all: `prisma` is `null` and `sql.error` says so — a database holds one side of it, so materialize it with `materializeSources` over rows holding both. `distinct` is the value and a sibling label column; a grouped source or a dotted label drops it, so every label comes back and the least one is picked. |
-| `materializeSourceQuery(query, rows, { rowShape? })` | One query's fetched rows as `SourceValues`. `rowShape` is `'prisma'` (default: a dotted `label` and each `groupBy` axis come nested) or `'sql'` (they come flat as `__label` / `__group_i`). Options are deduplicated and sorted. |
+| `toSourceQueries(lensOrNarrowing, options?)` | `SourceQuery[]`, one per sourced field: `{ path, mapName, model, field, label?, groupBy?, composedWhere, prisma, sql, recheck? }`. `options` is the clock (`now`, `timeZone`, `weekStart`) a relative date in the where compiles with — required for one, a plain usage error without it; bind a lens's binds with `bindLens` first. `prisma.steps` is present when the where needs `executePrismaPlan`. `sql.sql` is `null` with an `error` when SQL can't express the where. A source that reads across a bridge gets an over-fetching query and a `recheck`: its rows are candidates, not options (see "Sources across a bridge"). `distinct` is the value and a sibling label column; a grouped source or a dotted label drops it, so every label comes back and the least one is picked. |
+| `materializeSourceQuery(query, rows, { rowShape?, lens?, now?, … })` | One query's fetched rows as `SourceValues`. `rowShape` is `'prisma'` (default: a dotted `label` and each `groupBy` axis come nested) or `'sql'` (they come flat as `__label` / `__group_i`). Options are deduplicated and sorted. A query with `recheck` needs `lens` and rows holding the far side: it re-checks each candidate (`check`, with the clock and bindings given) and reads a bridged label or axis from the far side; a missing far side is a `UsageError`. |
 | `materializeSources(lensOrNarrowing, rows, options?)` | `SourceValues[]` for every sourced field, from the rows the lens fetches — `toLensSelect`'s rows as fetched, or as `projectRows(…, { keepGrantColumns: true })` keeps them. A viewer's projection drops what sources read: a row lacking any key a read walks — through each relation and list element to the column — that a source or a grant on its path reads throws a `UsageError` (a fetch returns every key it selects, NULL as `null`). The path is walked down the rows — the tree is its link — each level's grants met, and each row it reaches must meet, through `check()` with `options`, its visit's grants, its source `where` narrowed as a rule is, the guards of the relations its label and axes cross and the values the lens allows — so it offers what `toSourceQueries` does. A scalar-list field gives one option per element; a value takes its least label. A `from: 'mapDefaults'` source throws (see below). |
 
 Options never offer a value the lens disallows: `projectLens` drops fetched values outside a
@@ -1296,29 +1295,57 @@ carries down only in the layer that declares it: every layer before or after it
 theirs, so a child's pointer can only narrow what its parent gave, and a tenant layer added after a
 pointer always narrows it. How depends on how it scopes: through `mapDefaults` (the model's own
 grant or source) the pointer still offers unlinked rows; through a root `where` the grant can only
-reach the pointer down the path, so it offers just the linked rows — and across a bridge, where no
-grant crosses, no query at all (it is routed to caller rows, below). Scope tenancy through `mapDefaults` to keep a pointer's unlinked rows.
+reach the pointer down the path, so it offers just the linked rows — and across a bridge the
+grant comes back as the query's `recheck` (below). Scope tenancy through `mapDefaults` to keep a pointer's unlinked rows.
 A pointer whose model declares no source fails `validateNarrowing` (`invalid_source`) and throws
 from `projectLens` (by path) / `toSourceQueries` / `materializeSources`, even where a layer hides
 its field; `projectLens(…, { by: 'model' })` and `describeRuleSources` read the lens without
 validating it. Across a bridge it is how a picker gets options at all: the
 model source compiles against the far map alone, with that map's own tenancy, where a path source
-has no query (see "Sources across a bridge"). A grant a path can't carry down — a relation whose
+over-fetches and re-checks (see "Sources across a bridge"). A grant a path can't carry down — a relation whose
 map declares no inverse — is a `LensRefusal`, never an empty list. `materializeSources` refuses a pointer — a fetched collection can't hold unlinked
 rows; query it with `toSourceQueries` and `materializeSourceQuery`.
 
 #### Sources across a bridge
 
-A source whose path, `where`, `label` or an axis reads across a bridge has neither a database form (no
-database holds both sides) nor a fetch form (`toLensSelect` selects no bridge). `toSourceQueries`
-returns it with `prisma: null`, `sql.sql: null` and an `sql.error` that names the path. Materialize
-it yourself: pass `materializeSources` the rows at the source's path, each holding the bridged
-row inline under its bridge field — for a `FanUser.email` source reading
-`salesforce:Contact.industry`, `{ id, email, crmId, 'salesforce:Contact': { id, industry } }`
-(the `indexBridges` output). A pointer whose model source crosses a bridge is materialized the same
-way, over the rows you supply. Every key a read walks must be there — the bridged row as one row
-where the bridge names one, each column a source or a grant reads — or `materializeSources` throws a
-`UsageError` rather than offer a wrong set.
+A source whose path, `where`, `label` or an axis reads across a bridge can't be decided by one
+database — each holds one side. `toSourceQueries` still returns a real query for the side it can
+see, and marks it with `recheck`:
+
+- **The query over-fetches.** What reads across the bridge compiles to TRUE (the compilers'
+  over-fetch), so the query never pre-filters on what it can't see: its rows are a **superset** of
+  the true options. Everything local is still decided by the database.
+- **`recheck` is what the database couldn't decide** — the conjuncts of `composedWhere` that read
+  across a bridge, or `true` when only the label or an axis does. **If `recheck` is present, the
+  query's rows are candidates, not options.** A source that reads no bridge has no `recheck`.
+- **The query selects local columns only:** the value, a local label and local axes, the local
+  columns `recheck` reads, and each crossed bridge's local `on` key (under the local relations the
+  read crosses first). It drops `distinct`, since candidates differ in what the re-check reads. A
+  label or axis across the bridge is not selected.
+- **Load the far side, then materialize.** Put the far row inline on each candidate under its
+  bridge field (the `indexBridges` shape — one row, or a list where the bridge names many) and
+  call `materializeSourceQuery(query, rows, { lens, rowShape?, now? })`. It requires every key the
+  re-check and a bridged label or axis read, as `materializeSources` does — a candidate without
+  the far side, a far row without a column read, or a list where the bridge names one row throws a
+  `UsageError` — keeps the candidates `check(recheck, row)` holds, and reads the label and axes
+  across the bridge from the far side, in either row shape. Without `lens` it throws.
+- **A source past a bridge** (its path crosses one) is queried against its own model's map; the
+  grants above it are carried back across the bridge through the far model's bridge field, and
+  come back as its `recheck` — so each candidate holds the near rows inline
+  (`{ id, industry, 'prisma:FanUser': [{ email, … }] }`).
+- **SQL rows are flat**, so a bridged query whose re-check reads through a local relation has
+  `sql.sql: null` (with `sql.error`); run the Prisma form.
+
+```ts
+const [query] = toSourceQueries(lens, { now });
+const candidates = await prisma[query.model].findMany(query.prisma); // superset
+const rows = query.recheck === undefined ? candidates : await loadFarSide(candidates); // your join
+const values = materializeSourceQuery(query, rows, { lens, now });
+```
+
+`materializeSources` over fetched rows still answers a path source across a bridge when the caller
+supplies the root rows with the far side inline (`{ id, email, crmId, 'salesforce:Contact': { id,
+industry } }`); a pointer (`from: 'mapDefaults'`) always goes through the query.
 
 ### Fetching Under a Lens