Vex · guide

Seed and lock

Every read the app depends on, stored under a name when the app starts. The endpoint replays them and generates nothing.

Install it

pnpm add @niscorp/vex @niscorp/prism @niscorp/strata zod @electric-sql/pglite

Step 1 of 5

The database and the engine

Start with a Postgres in the process and two bookings in it. PGlite is Postgres compiled to run wherever Node runs, and Vex talks to it through the same adapter it uses for a real one.

The engine reads the schema when it introspects: tables, columns, keys, and the relations between them. Everything Vex checks a query against comes from that read.

The database and the engine

import { PGlite } from '@electric-sql/pglite';
import { createPostgresAdapter, createQueryEngine, handleDiscovery, handleQuery, seedCache } from '@niscorp/vex';
import { createPglitePool } from '@niscorp/vex/pglite';

const db = new PGlite();
await db.exec(`
  CREATE TABLE bookings (id text PRIMARY KEY, night text, member text, seats integer);
  INSERT INTO bookings VALUES ('B-2040', '2026-10-24', 'Ada', 1), ('B-2041', '2026-10-24', 'Grace', 2);
`);
const engine = createQueryEngine({ adapter: createPostgresAdapter({ pool: createPglitePool(db) }) });
await engine.introspect();

Step 2 of 5

Seed the reads

An app does not generate the reads it depends on. It writes them, as documents in Vex’s grammar, and seeds them under names when it starts. seedCache stores each entry protected, so no request can replace it.

The first read takes a value, the night, as $context. The second takes nothing. Neither says who may read what: that is the policy’s, and it is placed into the statement when the read runs.

Seed the reads

await seedCache(engine.cache, [
  {
    fingerprint: 'boxoffice/coming',
    dsl: {
      from: ['bookings'],
      fields: ['bookings.member', 'bookings.seats'],
      filter: { eq: ['bookings.night', { $context: 'night' }] },
    },
  },
  {
    fingerprint: 'boxoffice/members',
    dsl: {
      from: ['bookings'],
      fields: ['bookings.member'],
      distinct: true,
      sort: [{ field: 'bookings.member', dir: 'asc' }],
    },
  },
]);

Step 3 of 5

Lock the endpoint

What a server serves is a handler, and this is its configuration. locked: true makes it replay-only: anything stored under a name is answered, and anything that would need a model is refused. The app runs with no model.

Lock the endpoint

const config = { engine, locked: true };

Step 4 of 5

GET: what there is

handleDiscovery is what a GET on the endpoint answers: every stored name, what each takes, and what it returns. None of it is written by anyone. The input is read off the document, each $context typed by the column it sits beside.

GET: what there is

const discovery = await handleDiscovery(config);
for (const entry of discovery.fingerprints) {
  console.log(entry.fingerprint, 'takes', Object.keys(entry.context ?? {}));
}

A client, or an agent, learns what to call from the endpoint itself.

Step 5 of 5

POST: a question nobody stored

A POST carries a name and its values, or an intent and a shape. This one has no name, so it would need generation, and the endpoint is locked. The handler answers as a server would: a status, and a JSON body that says why.

POST: a question nobody stored

const request = { intent: 'Who booked the most seats?', shape: [{ member: '' }] };
const response = await handleQuery(config, request, {});
console.log(response.status, JSON.stringify(response.body));

Then

Run it.

Two reads listed with what each takes, and a question nobody stored refused with locked.

Run it

npx tsx seed.mts

It prints

boxoffice/coming takes [ 'night' ]
boxoffice/members takes []
400 {"error":"locked","message":"This endpoint is replay-only — unknown or changed fingerprints cannot generate here."}