feat(appkit): add opt-in generated database reads

[ditadi]

Stack

• #525 — the database runtime
  • #526 — the typed plugin API
    • #527 — generated reads ← you are here
      • #528 — mutations and hooks
        • #529 — playground example

Each PR targets the one above it, so the diff shown here is only the delta on top of #526. Review in order.

What

Adds the first HTTP surface: crudRoutes projects the typed read API from #526 onto generated GET /:table and GET /:table/:id routes. It is off by default and opt-in per table, because a generated route is reachable by anyone the app admits.

database({
  schema,
  crudRoutes: { tables: ["notes"] },
  hooks: {
    notes: {
      serialize: (row) => ({ ...row, excerpt: String(row.body).slice(0, 80) }),
    },
  },
});

GET /api/database/notes?where={"author":{"eq":"ada"}}&order={"createdAt":"desc"}&limit=20
→ { "items": [...], "limit": 20, "offset": 0 }

GET /api/database/notes/42
→ { "id": 42, "body": "...", "createdAt": "..." }

Only writes are missing after this PR; they arrive in the next one.

Changes

Exposure is a decision per table (crud/exposure.ts)

crudRoutes accepts false (the default), true, or { tables: [...] }, and the table names are checked against the schema type, so a typo does not silently expose nothing. An enabled table is also what makes it includable from its neighbours: a relation whose target is not enabled cannot be included, so one table's data sits behind exactly one decision rather than leaking through a join.

The query grammar is bounded before any SQL runs (crud/query.ts)

where, order, select, include, limit, and offset are decoded from the raw query string — not from Express's normalized req.query, which would accept repeated and array-shaped parameters. Every decoded piece is checked against the table's compiled columns: an unknown column, an operator the column's kind does not support, or a value that fails its codec is a 400 before the plugin is asked for anything.

The budgets are explicit constants in defaults.ts and are all enforced at decode time: query string size, where nesting depth and condition count, order field count, offset ceiling, and the number of rows the include tree may materialize. limit defaults to a page and is capped by the same wire cap a typed caller sees, so HTTP cannot ask for more than server code can.

Rejections name a fixed parameter and a fixed sentence. The decoder never echoes caller-supplied text back into the response.

Rows are shaped, not forwarded (crud/contract.ts, crud/codecs.ts)

Each enabled table compiles once into a CrudTable: its public columns, their codecs, its primary key decoder, and a projection that drops private columns. A row is projected before it reaches the optional serialize hook, so a serializer cannot re-expose a column the schema marked private, and the hook's output is re-sanitized against depth and node budgets afterwards. serialize is typed to return synchronously — a Promise does not compile — because it runs inside the response path.

Responses are bounded and never cached

The encoded body is measured before it is sent, so a request that would exceed the byte budget fails as 413 instead of streaming a partial answer. Every generated read sends Cache-Control: no-store: the same URL answers differently once the table changes.

Pagination is stable

The list handler appends the primary key to whatever order the caller asked for, so rows with equal sort keys cannot reshuffle between pages. A table without a primary key has no tie-breaker to append, so it must name its own order and is told so.

Spans

Each generated read runs inside a span named for its route template, not its URL, and a failure is recorded as not_found, rejected, or failed — derived from the safe status code, so cardinality stays bounded and no caller input reaches the span.

Known limitation

Text filters accept caller-supplied like/ilike patterns, and this beta adds no statement cancellation below the connector, so an expensive pattern runs to completion while holding its pooled connection. This is documented on CrudRoutesConfig alongside the note that generated routes carry no per-user filter.

Verification

• pnpm vitest run — 4109 passing, 1 skipped; new suites cover the query decoder and its budgets, the codecs, the row contract, the route handlers, and the read spans
• pnpm -r typecheck — clean across all packages
• pnpm run generate:types, pnpm run sync:template, and pnpm run docs:build produce no drift