@genesislcap/mock-server 15.54.0 → 15.55.0

package/README.md

@@ -136,10 +136,11 @@ covers the server-side behaviors real projects lean on:
   }
   ```
 
-- **Join predicates and anti-joins** — a view join takes a `where(joinRow,
-  baseRow)` predicate for matches the `on` equality alone can't express
-  (side-specific price joins), and `antiJoins` keeps only base rows with NO
-  match (the `USER_WITHOUT_DETAIL` pattern):
+- **Join predicates and anti-joins** — beyond the GSF join model (see
+  [Views: the join model](#views-the-join-model); a side-specific price join
+  is a constant link there), a view join takes a `where(joinRow, viewRow,
+  { tables })` predicate for matches no link can express, and `antiJoins`
+  keeps only base rows with NO match (the `USER_WITHOUT_DETAIL` pattern):
 
   ```ts
   views: {
@@ -162,6 +163,112 @@ covers the server-side behaviors real projects lean on:
   `store.rowKey(table, row)` to `broadcastTableChange`; sequence generation
   still requires a single `pkField`.
 
+## Views: the join model
+
+A `ViewDef` is a GSF view (`view("TRADE_VIEW", TRADE) { joins { } fields { } }`)
+and behaves as GSF 8.15.x views do (genesis-pal `view/join/*.kt`,
+`ViewStructureReaderImpl.kt`; genesis-codegen `ViewRepoConfigGenerator.kt`):
+
+```ts
+views: {
+  TRADE_VIEW: {
+    base: 'TRADE',
+    select: { TRADE_PRICE: 'PRICE' }, // TRADE.PRICE withAlias "TRADE_PRICE"
+    joins: [
+      // joining(COUNTERPARTY, backwardsJoin = true) {
+      //   on(TRADE.COUNTERPARTY_ID to COUNTERPARTY { COUNTERPARTY_ID }) }
+      {
+        table: 'COUNTERPARTY',
+        on: ['COUNTERPARTY_ID', 'COUNTERPARTY_ID'],
+        backwardsJoin: true,
+        select: { COUNTERPARTY_NAME: 'NAME' }, // COUNTERPARTY.NAME withAlias "COUNTERPARTY_NAME"
+      },
+      // joining(INSTRUMENT, JoinType.INNER) { on(...)
+      //   .joining(EXCHANGE) { on(INSTRUMENT { EXCHANGE_ID } to EXCHANGE { EXCHANGE_ID }) } }
+      { table: 'INSTRUMENT', type: 'INNER', on: ['INSTRUMENT_ID', 'INSTRUMENT_ID'] },
+      {
+        table: 'EXCHANGE',
+        fromAlias: 'INSTRUMENT',
+        on: ['EXCHANGE_ID', 'EXCHANGE_ID'],
+        select: { EXCHANGE_CITY: 'CITY' },
+      },
+      // val BID = INSTRUMENT_PRICE withAlias "BID"
+      // joining(BID) { on(TRADE.INSTRUMENT_ID to BID { INSTRUMENT_ID }).and(BID { SIDE } to "BID") }
+      {
+        table: 'INSTRUMENT_PRICE',
+        alias: 'BID',
+        on: [['INSTRUMENT_ID', 'INSTRUMENT_ID'], { to: 'SIDE', value: 'BID' }],
+      },
+    ],
+    // derivedField("SPREAD", DOUBLE) { withInput(TRADE.PRICE, BID.PX) { price, bid -> ... } }
+    derived: { SPREAD: (row, { tables }) => (tables.BID ? row.TRADE_PRICE - tables.BID.PX : null) },
+    derivedTypes: { SPREAD: 'DOUBLE' },
+  },
+}
+```
+
+| GSF view DSL | `ViewDef` / `JoinDef` |
+|---|---|
+| `view("V", TRADE)` | `base: 'TRADE'`. `baseAlias` names it inside the view (default: the table name) |
+| `joining(T)`, `joining(T, JoinType.INNER)` | `{ table: 'T' }`, `type: 'INNER'`. The default is `'OUTER'`, as in GSF |
+| `val A = T withAlias "A"`, `joining(A)` | `alias: 'A'`, needed to join one table twice. Default: the table name |
+| `on(TRADE.F to T { G })` | `on: ['F', 'G']`: the source row's field, then the joined table's |
+| `.and(...)` | `on: [['F', 'G'], ['F2', 'G2']]`: every link must hold |
+| `.and(OTHER { F } to T { G })`, a link from another table of the view | `{ fromAlias: 'OTHER', from: 'F', to: 'G' }` |
+| `.and(T { G } to "VALUE")` | `{ to: 'G', value: 'VALUE' }`, compared with `===`, so use the column's own type |
+| `.joining(U) { ... }` nested in T's join | a later join with `fromAlias: 'T'` |
+| `backwardsJoin = true` | `backwardsJoin: true` (see the live changes below) |
+| `T.F withAlias "X"`, `T.F withPrefix "P"`, `T.F` | the join's `select`: `{ X: 'F' }`, `{ P_F: 'F' }`, `{ F: 'F' }`. Base-table aliases go in `ViewDef.select` |
+| `derivedField("D", DOUBLE) { withInput(A.F, B.G) { ... } }` | `derived: { D: (row, { tables }) => ... }` and `derivedTypes: { D: 'DOUBLE' }` |
+| `fields { ... }` | `fields`: the output names, in order |
+
+**Rows.**
+- Joins run in order. A join with `fromAlias` reads its key fields from that table's row.
+- A join without `fromAlias` reads them from the view row built so far: the base row's columns, overlaid by the selects of the joins before it. For a GSF view that is the base row's field. It also lets a join key on an earlier join's selected column, which is how chained joins were written before `fromAlias`.
+- A null or missing key value matches nothing, because GSF builds no join request from it. Falsy values such as `0` and `''` do match.
+- GSF only lets a dataserver read a view whose joins are one-to-one (their links cover a unique index), so a valid view has at most one match. When there are more, the last one in table order wins, or with a `where` the first that passes, as before this model. One-to-many fan-out is not modelled.
+- An OUTER join that finds nothing keeps the row, with that join's columns unset (`null` on the wire for a declared view).
+- An INNER join that finds nothing drops the row.
+- A join whose source table found nothing finds nothing either. So an INNER join nested under an OUTER one also drops the row when the outer join misses.
+- `derived(row, { tables })` and `where(joinRow, viewRow, { tables })`:
+  - `row` / `viewRow` is the view row so far: the base columns plus the selects.
+  - `tables` holds every table's source row by alias, so a derived field can read columns the view doesn't expose. An OUTER miss is `undefined`.
+- Registration throws on a definition GSF would refuse to compile: a join with no link, an alias given twice, or a `fromAlias` (of a join or a link) that is neither the base nor an earlier join.
+- A table joined twice, or the base table joined to itself, with no alias still works, as it did before aliases existed. The later join goes by no name, and the name keeps meaning the first table. Give it an `alias` to read it by name.
+
+**Metadata.**
+- Every column takes its type, enum values and size from its source table, through aliases and nested joins.
+- A joined column keeps its own nullability only when its join is reached from the base through INNER joins alone. Any other joined column is nullable (GSF `transformOutputFields`).
+- Derived fields take `derivedTypes`.
+
+**Live changes** (fidelity `'gsf'`):
+- **Base-table change.** The view row is rebuilt from the changed base row.
+  - A MODIFY that makes an INNER join miss is pushed as a `DELETE`.
+  - One that makes it match is pushed as an `INSERT`.
+  - An INSERT that doesn't make it into the view pushes nothing.
+  - This is GSF's mapping of view updates (genesis-db `Bulk.kt` `mapNullable`).
+- **Joined-table change.** It is pushed only through joins with `backwardsJoin: true`, at any depth. GSF's view docs say that by default only root-table updates are published, and a joined table's need a backwards join (`ViewStructureReaderImpl.kt`; `JoinRepo.kt` listens to a joined table only for one). Without one, the client sees the joined table's new values when the view row's base row next changes.
+- **What a backwards join pushes.** The view is compared as it was before the change and as it is after:
+  - an `INSERT` for a row an INNER join now lets in;
+  - a `DELETE` for a row it drops;
+  - a `MODIFY` for a row joined to the changed record (before or after), or whose values changed;
+  - nothing for the rest.
+- **A row joined to the changed record is pushed even when its values look unchanged.** The "before" is the store's: each record as it was before its first modify that no broadcast has announced yet, plus the records a key lost. A client may hold newer values than that, for example from a snapshot taken after an unannounced change.
+  - GSF's client index compares against what each client holds, and sends nothing for a modify that changes no exposed field.
+  - So here a change to a column the view doesn't expose still pushes the rows joined to it. The values are unchanged, which clients take as a no-op.
+- **Anti-joins** are not a GSF construct, so a change to an anti-joined table is always pushed, as `INSERT`s and `DELETE`s.
+- **A DELETE broadcast before its row is removed** counts the row as gone.
+- **A view that joins its own base table** gets each changed base row once, from the base-table path.
+- **Change rows through the store and broadcast them.** Use `insertRow` / `updateRow` / `deleteRow` and call `broadcastTableChange`. A stored row mutated in place leaves no earlier state to compare against.
+
+**Behaviour change.** Up to 15.53, a change to any joined table pushed every held view row as a MODIFY. Now a join needs `backwardsJoin: true`, as on GSF, and only the rows it inserts, deletes or joins are pushed. `fidelity: 'legacy'` keeps the old behaviour and ignores `backwardsJoin`.
+
+**Not modelled:**
+- parameterised joins (`asParameter`) and lambda joins;
+- `withFormat`;
+- one-to-many views (GSF dataservers can't read them);
+- a dataserver query's own `backwardsJoin = false` (GSF's default is `true`).
+
 ## Record identity, ROW_REF and sequences
 
 Every stored row carries `RECORD_ID` and `TIMESTAMP`, as every Genesis table
@@ -196,7 +303,8 @@ row does (genesis-db `InsertOperation.kt`):
   `broadcastTableChange`, and a pk-only row passed to `broadcast()` is matched
   to its record, a just-deleted one included. A view row is rebuilt from the
   changed base row, so a view's own `pkField` doesn't matter, and a MODIFY that
-  takes the row out of the view (an anti-join) is pushed as a DELETE.
+  takes the row out of the view (an INNER join or an anti-join) is pushed as a
+  DELETE.
 - **Live DELETE** is `ROW: [{DETAILS: {OPERATION: 'DELETE', ROW_REF}}]` and
   nothing else. The store remembers every record a key lost until a broadcast
   announces it (`broadcastTableChange`, or `broadcast()` with a DELETE), so a
@@ -560,6 +668,7 @@ createMockServer({ ...config, fidelity: 'legacy' });
 | `META_REQUEST` content | The GSF shapes below; event META too | `{NAME, TYPE}` fields, `KEY: []` on dataservers, `REPLY_FIELD` alone on request servers; events are unknown |
 | `JSON_SCHEMA_REQUEST` content | Per resource type, as below | One minimal `{DETAILS: {properties: {F: {type}}, required}}` as both INBOUND and OUTBOUND; a query or request-server name resolves to its source table |
 | Declared schemas (`TableDef.fields`, query and view `fields`, `derivedTypes`) | Used for metadata and rows | Ignored: metadata is inferred, rows go out as stored |
+| A change to a table a view joins | Pushed only through joins with `backwardsJoin: true`, as the view rows it inserts, deletes or changes ([Views](#views-the-join-model)) | Every view row pushed as a MODIFY, whatever the join |
 | `DATA_LOGON` `ORDER_BY` / `REVERSE` / `FIELDS`, criteria on unexposed fields | Honoured / `LOGON_NACK` | Ignored |
 | `REQ_` | As in [Request servers](#request-servers-req_): `PARAMETRIC_TYPE`, criteria-only paging and ordering, `REQUEST` wildcards, ranges and arrays, a reply block, `MSG_NACK` failures | Every matching row in insertion order; `REQUEST` from the top level or `DETAILS`, `'*'`/`null`/`''` match anything, an array value any of its values; `CRITERIA_MATCH` fails open; no `RECORD_ID`/`TIMESTAMP`; errors as a `REP_` with `ERROR` |
 | Unknown resource | `MSG_NACK` 404 (the client's promise rejects) | A typed reply with `ERROR: [{CODE: 'UNKNOWN_RESOURCE'}]` (the promise resolves) |
@@ -611,8 +720,10 @@ appName: 'showcase', // enum class names: global.genesis.gen.dao.enums.<appName>
   server puts there (leave it unset on dates: foundation-forms spots a date by
   `org.joda.time.DateTime`). `optional` decides whether an event payload may leave the field
   out (see events below); an ENUM with no `values` sends no `VALID_VALUES` and no `enum`.
-- **Views** take their base table's fields, each join's `select` columns typed from the joined
-  table (nullable), and `derivedTypes` for derived fields (inferred from rows when missing).
+- **Views** take their base table's fields and `select` aliases, each join's `select` columns
+  typed from the joined table at any depth (nullable unless reached from the base through INNER
+  joins only; see [Views: the join model](#views-the-join-model)), and `derivedTypes` for
+  derived fields (inferred from rows when missing).
   `ViewDef.fields` is the view's `fields { }` block: the view then exposes only those, in that
   order (keep the key in it).
 - **`QueryDef.fields`** is the query's `fields { }` block: rows **and** metadata carry only those
@@ -719,8 +830,8 @@ past `MAX_VIEW`). A row is in scope while it passes the query `filter`,
 So a new row arrives as an `INSERT`, a row a MODIFY brings back into the
 criteria arrives as an `INSERT` (recorded: `DELETE` on leaving, `INSERT` on
 re-entering, same `ROW_REF`), and rows the client never got — including rows
-cut off by `MAX_VIEW`, and the hundreds of view rows a change to a joined table
-re-materializes — get no MODIFYs or DELETEs at all. A waiting row's page later
+cut off by `MAX_VIEW`, and the view rows a change to a joined table touches —
+get no MODIFYs or DELETEs at all. A waiting row's page later
 delivers its current values. Nothing absorbed uses a `SEQUENCE_ID`.
 
 An `INSERT` is pushed even when the view already holds `MAX_VIEW` rows. The
@@ -1008,8 +1119,10 @@ Where this engine still differs from the real server:
 
 - Live MODIFYs carry the **full row**. The real server sends only the changed
   fields; a full row is a superset, which clients tolerate.
-- A change to a **joined table** pushes a MODIFY for every held view row, not
-  only the rows whose values changed.
+- A change through a view's **backwards join** pushes a MODIFY to every held
+  row joined to the changed record, even when no column the view exposes
+  changed. The real server compares against what the client holds and sends
+  nothing then (see [Views](#views-the-join-model)).
 - There is no **moving view**. Once the view holds `MAX_VIEW` rows, live
   INSERTs are still pushed instead of also evicting the oldest row.
 - Without `ORDER_BY`, snapshots are in **insertion order** (with or without
@@ -1037,7 +1150,8 @@ the criteria grammar, store, metadata inference, and event-table inference
 plus end-to-end WS/HTTP tests (auth gating, filtered-subscription DELETE
 delivery, keyed `REQ_*` lookups, session reuse, clean shutdown — and, in
 `test/dataserver.test.ts`, the GSF envelopes, paging and the `'legacy'`
-fidelity mode; `test/requestReply.test.ts` covers both kinds of request server)
+fidelity mode; `test/requestReply.test.ts` covers both kinds of request server,
+`test/views.test.ts` the view join model and its live pushes)
 via `node --test`, no build step. Only `test/**/*.test.ts`
 files are run, so shared helpers (`test/support.ts`) can sit beside them.
 

package/dist/db/schema.js

@@ -7,6 +7,7 @@ import { isLegacyFidelity } from "../protocol/fidelity.js";
 import { daoClassOf, titleCase } from "../protocol/fieldTypes.js";
 import { RECORD_FIELDS, RECORD_ID, TIMESTAMP } from "./identity.js";
 import { deriveFields } from "./metadata.js";
+import { planView } from "./views.js";
 export function pkFieldsOf(def) {
     return Array.isArray(def.pkField) ? def.pkField : [def.pkField];
 }
@@ -67,27 +68,39 @@ function derivedTypeDef(name, entry) {
 function viewOf(name, config, store) {
     return store.views.get(name) ?? config.views?.[name];
 }
-// A view over a declared base table: the base table's columns, each join's
-// selected columns typed from the joined table (nullable, since a base row
-// may have no match), and the derived fields typed from derivedTypes (or
+// A view over a declared base table: the base table's columns and its
+// `select` aliases, each join's selected columns typed from the joined table
+// (at any depth), and the derived fields typed from derivedTypes (or
 // inferred from the view's rows when not given) — narrowed to the view's
-// fields block when it has one.
+// fields block when it has one. A joined column keeps its own nullability
+// only when its join is reached from the base through INNER joins alone;
+// any other may find no match, so it is nullable (GSF's
+// transformOutputFields).
 function declaredViewFields(viewName, view, config, store) {
+    const plan = planView(viewName, view);
     const fields = new Map();
-    for (const field of resolveSourceSchema(view.base, config, store).fields) {
+    const baseFields = resolveSourceSchema(view.base, config, store).fields;
+    for (const field of baseFields)
         fields.set(field.name, field);
+    const aliased = (name, source, nullable) => {
+        const { title: _title, ...rest } = source ?? {
+            name,
+            type: 'STRING',
+            nullable: true,
+            generated: false,
+        };
+        return { ...rest, name, nullable: nullable ?? rest.nullable, generated: false };
+    };
+    for (const [name, sourceField] of Object.entries(view.select ?? {})) {
+        const source = baseFields.find((field) => field.name === sourceField);
+        fields.set(name, aliased(name, source, undefined));
     }
-    for (const join of view.joins ?? []) {
+    for (const join of plan.joins) {
         const joined = resolveSourceSchema(join.table, config, store).fields;
-        for (const [alias, sourceField] of Object.entries(join.select ?? {})) {
+        const nullable = join.alwaysMatched ? undefined : true;
+        for (const [name, sourceField] of Object.entries(join.def.select ?? {})) {
             const source = joined.find((field) => field.name === sourceField);
-            const { title: _title, ...rest } = source ?? {
-                name: alias,
-                type: 'STRING',
-                nullable: true,
-                generated: false,
-            };
-            fields.set(alias, { ...rest, name: alias, nullable: true, generated: false });
+            fields.set(name, aliased(name, source, nullable));
         }
     }
     const derivedNames = Object.keys(view.derived ?? {});
@@ -284,6 +297,8 @@ function sourceFieldNames(source, config, store) {
     if (!base)
         return view.fields;
     const names = new Set(base);
+    for (const alias of Object.keys(view.select ?? {}))
+        names.add(alias);
     for (const join of view.joins ?? []) {
         for (const alias of Object.keys(join.select ?? {}))
             names.add(alias);

package/dist/db/store.d.ts

@@ -1,4 +1,9 @@
 import type { Row, TableDef, ViewDef } from '../types.ts';
+import { type PlannedAntiJoin, type PlannedJoin, type ViewEntry } from './views.ts';
+export interface ViewRowsSource {
+    base?: Row[];
+    rowsOf?: (entry: PlannedJoin | PlannedAntiJoin) => Row[] | undefined;
+}
 type Pk = string;
 export declare class Store {
     private tables;
@@ -8,6 +13,7 @@ export declare class Store {
     private clock;
     private seedRows;
     private removedRows;
+    private previousRows;
     readonly views: Map<string, ViewDef>;
     registerTable(tableName: string, definition: TableDef): this;
     private counterOf;
@@ -17,6 +23,7 @@ export declare class Store {
     private stampSeedRow;
     private stampNewRow;
     private noteRemoved;
+    private notePrevious;
     private observeGeneratedValues;
     nextSequenceValue(sequencePrefix: string, width: number): string;
     private generateSequenceValue;
@@ -30,9 +37,12 @@ export declare class Store {
     updateRow(tableName: string, pk: Pk, patch: Row): Row | undefined;
     deleteRow(tableName: string, pk: Pk): boolean;
     takeRemovedRows(tableName: string, key: Pk): Row[];
+    takePreviousRecord(tableName: string, row: Row): Row | undefined;
     takeRemovedRecordsFor(resourceName: string, row: Row): Row[];
     getViewRows(viewName: string, tables?: Record<string, Row[]>): Row[];
-    private materializeView;
+    getViewRowsFrom(viewName: string, source: ViewRowsSource): Row[];
+    getViewEntriesFrom(viewName: string, source: ViewRowsSource): ViewEntry[];
+    private viewOf;
     getResourceRows(resourceName: string): Row[];
     getMetadataRows(resourceName: string): Row[];
     getPkFields(resourceName: string): string[];

package/dist/db/store.js

@@ -1,6 +1,7 @@
 // In-memory tables + views + sequence generation. No persistence, no external deps.
 // This is the "database" — disposable and rebuilt from seed data on every server start.
 import { RECORD_ID, RecordClock, recordKey, TIMESTAMP, withoutRecordFields } from "./identity.js";
+import { materializeEntries, planView, } from "./views.js";
 // The generators of a table, the key's own sequence first. A SEQUENCE with
 // neither its own prefix nor the table's can't mint anything and is left to
 // the caller.
@@ -82,6 +83,10 @@ export class Store {
     // MAX_REMOVED_PER_KEY records and a table its last MAX_REMOVED_KEYS keys,
     // for handlers that delete without ever broadcasting.
     removedRows = new Map();
+    // Per table, each record a modify changed since a broadcast last announced
+    // it, as it was before the first such modify (by RECORD_ID) — see
+    // takePreviousRecord. Bounded like removedRows.
+    previousRows = new Map();
     views = new Map();
     registerTable(tableName, definition) {
         const { pkField, sequencePrefix, sequenceWidth = 3, sequenceFormat = 'prefix', rows = [], } = definition;
@@ -109,6 +114,7 @@ export class Store {
         this.tables.set(tableName, table);
         this.tableConfig.set(tableName, config);
         this.removedRows.delete(tableName);
+        this.previousRows.delete(tableName);
         this.seedRows.set(tableName, rows.map((row) => ({ ...row })));
         // Each counter starts after the highest value the seed rows carry (two
         // fields of one table sharing a prefix share the counter). The key's
@@ -145,7 +151,9 @@ export class Store {
         }
         return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
     }
+    // Throws on a join model GSF would refuse to compile (see planView).
     registerView(viewName, definition) {
+        planView(viewName, definition);
         this.views.set(viewName, definition);
         return this;
     }
@@ -196,6 +204,21 @@ export class Store {
         if (removed.size > MAX_REMOVED_KEYS)
             removed.delete(removed.keys().next().value);
     }
+    notePrevious(tableName, row) {
+        const id = recordKey(row);
+        if (id === undefined)
+            return;
+        let previous = this.previousRows.get(tableName);
+        if (!previous) {
+            previous = new Map();
+            this.previousRows.set(tableName, previous);
+        }
+        if (previous.has(id))
+            return;
+        previous.set(id, row);
+        if (previous.size > MAX_REMOVED_KEYS)
+            previous.delete(previous.keys().next().value);
+    }
     // A supplied value inside a generator's own range must advance its counter
     // too. Without this, inserting e.g. 'TR002' by hand leaves the counter at
     // 2, and the next generated insert mints 'TR002' again and silently
@@ -326,6 +349,7 @@ export class Store {
         if (!table || !config || !table.has(pk))
             return undefined;
         const existing = table.get(pk);
+        this.notePrevious(tableName, existing);
         const updated = { ...existing, ...patch };
         updated[RECORD_ID] = existing[RECORD_ID];
         updated[TIMESTAMP] = this.clock.next();
@@ -364,61 +388,57 @@ export class Store {
         removed?.delete(key);
         return records;
     }
+    // Reads and clears how a record was before the modifies no broadcast has
+    // announced yet changed it (undefined when none did): with the removed
+    // records, what a live change to a joined table is diffed against.
+    takePreviousRecord(tableName, row) {
+        const id = recordKey(row);
+        const previous = this.previousRows.get(tableName);
+        if (id === undefined || !previous)
+            return undefined;
+        const record = previous.get(id);
+        previous.delete(id);
+        return record;
+    }
     // The same, for a row of a table or view given by its (base) pk fields —
     // what a public broadcast(resource, 'DELETE', pkStub) names.
     takeRemovedRecordsFor(resourceName, row) {
         const located = this.locateRecord(resourceName, row);
         return located ? this.takeRemovedRows(located.tableName, located.key) : [];
     }
-    // Materializes a view: base table left-joined to related tables (optionally
-    // narrowed by per-join `where` predicates), minus anti-joined rows, plus
-    // derived fields. `tables` substitutes the rows of any table the view reads
-    // (its base or a joined one) — e.g. one base row, to build that row's view
-    // row, or a table's earlier state, to rebuild the view as it was.
+    // Materializes a view (see the README's "Views: the join model"): base
+    // rows minus anti-joined ones, joined in order — OUTER keeps a row with no
+    // match, INNER drops it — plus the select aliases and derived fields.
+    // `tables` substitutes the rows of any table the view reads (its base or a
+    // joined one) — e.g. a table's earlier state, to rebuild the view as it
+    // was.
     getViewRows(viewName, tables = {}) {
+        const rowsOf = (tableName) => Object.hasOwn(tables, tableName) ? tables[tableName] : this.getAllRows(tableName);
+        return this.getViewRowsFrom(viewName, {
+            base: rowsOf(this.viewOf(viewName).base),
+            rowsOf: (entry) => rowsOf(entry.table),
+        });
+    }
+    // The same, with the base rows given apart from the joined ones — e.g. one
+    // base row, to build that row's view row when the base table is also joined
+    // — and a join's or anti-join's rows given by its planned entry (undefined:
+    // the table as it is).
+    getViewRowsFrom(viewName, source) {
+        return this.getViewEntriesFrom(viewName, source).map((entry) => entry.row);
+    }
+    // The same, each row with the row every join matched (in join order).
+    getViewEntriesFrom(viewName, source) {
+        const view = this.viewOf(viewName);
+        return materializeEntries(viewName, view, {
+            base: source.base ?? this.getAllRows(view.base),
+            rowsOf: (entry) => source.rowsOf?.(entry) ?? this.getAllRows(entry.table),
+        });
+    }
+    viewOf(viewName) {
         const view = this.views.get(viewName);
         if (!view)
             throw new Error(`Unknown view: ${viewName}`);
-        return this.materializeView(view, (tableName) => Object.hasOwn(tables, tableName) ? tables[tableName] : this.getAllRows(tableName));
-    }
-    materializeView(view, getRows) {
-        let rows = getRows(view.base).map((row) => ({ ...row }));
-        for (const antiJoin of view.antiJoins ?? []) {
-            const joinRows = getRows(antiJoin.table);
-            rows = rows.filter((row) => !joinRows.some((joinRow) => joinRow[antiJoin.on[1]] === row[antiJoin.on[0]] &&
-                (antiJoin.where?.(joinRow, row) ?? true)));
-        }
-        for (const join of view.joins ?? []) {
-            const joinRows = getRows(join.table);
-            // A `where` predicate sees the base row, so an index keyed on the `on`
-            // field alone can't answer it — scan per base row instead.
-            const joinIndex = join.where ? undefined : new Map();
-            if (joinIndex) {
-                for (const row of joinRows) {
-                    joinIndex.set(row[join.on[1]], row);
-                }
-            }
-            rows = rows.map((row) => {
-                const match = joinIndex
-                    ? joinIndex.get(row[join.on[0]])
-                    : joinRows.find((joinRow) => joinRow[join.on[1]] === row[join.on[0]] && join.where(joinRow, row));
-                const merged = { ...row };
-                for (const [alias, sourceField] of Object.entries(join.select ?? {})) {
-                    merged[alias] = match?.[sourceField];
-                }
-                return merged;
-            });
-        }
-        if (view.derived) {
-            rows = rows.map((row) => {
-                const merged = { ...row };
-                for (const [field, compute] of Object.entries(view.derived)) {
-                    merged[field] = compute(row);
-                }
-                return merged;
-            });
-        }
-        return rows;
+        return view;
     }
     // Resolves a queryable resource (table or view) by name to its current rows.
     getResourceRows(resourceName) {
@@ -439,9 +459,13 @@ export class Store {
         if (live.length > 0)
             return live.map(withoutRecordFields);
         const view = this.views.get(resourceName);
+        const seedOf = (tableName) => this.seedRows.get(tableName) ?? [];
         const seed = view
-            ? this.materializeView(view, (tableName) => this.seedRows.get(tableName) ?? [])
-            : (this.seedRows.get(resourceName) ?? []);
+            ? this.getViewRowsFrom(resourceName, {
+                base: seedOf(view.base),
+                rowsOf: (entry) => seedOf(entry.table),
+            })
+            : seedOf(resourceName);
         return seed.map(withoutRecordFields);
     }
     // Row-identity fields for a table or view; empty when unknown.

package/dist/db/views.d.ts

@@ -0,0 +1,42 @@
+import type { AntiJoinDef, JoinDef, Row, ViewDef } from '../types.ts';
+export type PlannedLink = {
+    kind: 'field';
+    fromAlias: string | undefined;
+    from: string;
+    to: string;
+} | {
+    kind: 'value';
+    to: string;
+    value: unknown;
+};
+export interface PlannedJoin {
+    def: JoinDef;
+    table: string;
+    alias: string | undefined;
+    fromAlias: string;
+    links: PlannedLink[];
+    inner: boolean;
+    backwardsJoin: boolean;
+    alwaysMatched: boolean;
+}
+export interface PlannedAntiJoin {
+    def: AntiJoinDef;
+    table: string;
+    links: PlannedLink[];
+}
+export interface ViewPlan {
+    baseAlias: string;
+    joins: PlannedJoin[];
+    antiJoins: PlannedAntiJoin[];
+}
+export declare function planView(viewName: string, view: ViewDef): ViewPlan;
+export interface ViewRowSource {
+    base: Row[];
+    rowsOf: (entry: PlannedJoin | PlannedAntiJoin) => Row[];
+}
+export interface ViewEntry {
+    row: Row;
+    matches: Array<Row | undefined>;
+}
+export declare function materializeEntries(viewName: string, view: ViewDef, source: ViewRowSource): ViewEntry[];
+export declare function entriesReading(plan: ViewPlan, tableName: string): Array<PlannedJoin | PlannedAntiJoin>;