fastify-auto-sqlapi 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -11,6 +11,69 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
 
 ### Added
 
+- **`ApiRequest` — one seam between the core and the HTTP framework.** The engines, the schema
+  builders and the write pipeline never read a property off the request: it arrives from the
+  route, is forwarded to `getTenantId`, `validate` and the hooks, and is otherwise untouched. That
+  dependency was spread over thirteen files as a `FastifyRequest` type import; it is now declared
+  once in `src/types/request.ts` and exported from the package. `ApiRequest` *is* `FastifyRequest`,
+  so nothing changes for consumers — hooks keep their exact types. A new dependency-cruiser rule
+  fails the build on a `fastify` import (type-only included) anywhere under `src/lib/`,
+  `src/types/` or `src/bin/` but that file, and the two Fastify bridge helpers that lived in
+  `lib/` (`setupSwagger`, the `sqlApi` decorator) moved to `src/routes/` so the rule needs no
+  exceptions. See [ADR 0018](./docs/adr/0018-one-seam-to-the-http-framework.md).
+
+- **Views are supported explicitly, and PostgreSQL materialized views at all.** A view was
+  already usable — both introspections read `information_schema.columns`, which lists view
+  columns like any other — but the generator treated it as a base table and **invented a
+  primary key from the column types**: on an aggregating view that takes a count as the key,
+  and `get/:id`, `update` and `delete` then address rows by it, silently. Introspection now
+  reports `is_view` on both engines, the generated Schema carries `isView`, and the table
+  generator refuses to guess: it uses `id` when the view has one and says the key was *inferred,
+  not read from the database*, and otherwise writes a `TODO_pick_a_unique_column` placeholder
+  with `operations: ['search']` and a real `defaultOrder` — a config that works as generated,
+  since search never reads the primary key. Writes start off in the template but are **not**
+  blocked at runtime: a view the engine can make updatable is a legitimate projection layer.
+  PostgreSQL **materialized views** are now introspected from `pg_catalog`; they are absent from
+  `information_schema` and were being skipped without a word. `sqlapi-generate-schema` prints
+  the views it found and the assumptions it had to make. See
+  [ADR 0016](./docs/adr/0016-a-view-is-a-table-config.md).
+
+- **Columns the database computes are no longer offered as writable.** A
+  `GENERATED ALWAYS AS (<expr>)` column — PostgreSQL STORED, MySQL VIRTUAL or STORED — is
+  rejected by both engines when a write so much as names it, and the whole statement fails.
+  The plugin used to advertise those columns as ordinary writable fields, so a client sending
+  back what a read had just returned got a `500` for a payload nobody could have made valid.
+  `sqlapi-generate-schema` now detects them and records them in the generated Schema's
+  `generatedFields`; the runtime drops them from the insert, update and bulk-upsert bodies
+  (main and secondaries) and again inside the engines, which `sqlApi.*` reaches without those
+  schemas. **Regenerating the Schema files is enough** — the exclusion does not live in the
+  `Table*.ts` the generator never overwrites. The CLI also prints the columns it found, per
+  table, since a generated source file is not always read. See
+  [ADR 0015](./docs/adr/0015-non-writable-columns.md).
+- **`writeExclude` on `defineTable`** — the write-side counterpart of `readExclude`, for the
+  non-writable columns introspection cannot know about (one a trigger owns, one a migration is
+  about to drop). Reads are untouched: the field stays projected, filterable and orderable. It
+  runs **after** the write hooks, unlike `excludeFromCreation` which is sanitized before them
+  (ADR 0005): a hook cannot put back a value the database will refuse. `defineTable` rejects an
+  unknown field, the primary key, and a field that is also `readExclude`d. It is static and
+  applies to everyone — a rule that depends on *who* is asking is still product logic (ADR 0004).
+- **The agent manifest marks non-writable fields** `readOnly`, alongside the existing
+  `writeOnly` for `readExclude`.
+
+- **`afterRead` — the read-side hook.** The counterpart of `beforeInsert`/`beforeUpdate`, for
+  turning a stored representation back into the API one: decrypting a column, unpacking a blob,
+  rescaling a unit. Called **once per result set** with camelCase rows mutated **in place** and
+  awaited, so a hook that calls a remote KMS gets one invocation per page instead of one per row.
+  Declared on the table that **owns** the column and it follows a join: the hook runs wherever
+  that table's rows surface — `get`, `search`, and a `joinMultiple`/`joinLeft` declared on
+  another table, with `ctx.source` and `ctx.alias` saying which — so a relation elsewhere needs
+  no extra wiring, the way `readExclude` and `tenantScope` already work (ADR 0010). It does not
+  run on `joinGroup` (aggregates, not table rows) nor on an empty result, and rows cannot be
+  added or removed: the pagination `COUNT` has already run. On the main table it runs *after* the
+  join side queries, which correlate on the values the database returned, so a hook rewriting the
+  column a relation joins on cannot break the correlation. `SearchParams`/`GetParams` now carry
+  the optional `request`, which `sqlApi.search()`/`sqlApi.get()` forward when given one.
+
 - **`tenantScope` over several owner columns — `{ anyOf: [...] }`.** A row that belongs to two
   parties and is visible to either — a message (`sender_id` / `recipient_id`), a transfer
   (`from_account_id` / `to_account_id`), a shift swap — could not be expressed before, leaving
@@ -83,8 +146,58 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
   `LEFT JOIN` alias), so the filter applied nothing. They are now rejected with a `400` naming
   the reason and pointing at `joinMustExist` on the same relation.
 
+- **The update body requires the primary key**, which identifies the row it updates
+  (`PUT /rest/:table` carries it in `main`). The generated PK field is `Optional` — it is
+  absent on insert — and that modifier reached the update body unchanged, so a request omitting
+  `main.id` built its `WHERE` on `undefined` instead of being rejected. The code comment said
+  "PK required" all along.
+- **A secondary now runs the child table's `beforeInsert`.** `processSecondaries` already applied
+  the child's `excludeFromCreation` and its `tenantScope` but skipped its `beforeInsert`, so a
+  table whose hook *transformed* a value — encrypting a column, normalising a unit — stored the
+  raw client value whenever its rows arrived as another table's children, and the correct one
+  through its own route. Nothing failed at write time; the row read back as garbage later. The
+  hook runs after the exclusion strip and before the engine's FK auto-fill, which stays
+  authoritative, and receives the transaction connection. The child's `validate` and
+  `afterInsert` deliberately still do not run — see
+  [ADR 0014](./docs/adr/0014-what-follows-a-write-join.md). **Breaking** for a `beforeInsert`
+  written assuming it only ever ran on its own table's route.
+- **The get response schema honours `readExclude`**, like the search response already did; it
+  previously advertised fields the engine never selects. It now lives in `lib/schema/get.ts`
+  (`GetTableResponse`) instead of inline in the route, which is how it had drifted.
+  `schemaOverrides` stays where it was — write bodies only: an override rules what the API
+  accepts from now on, while the rows already stored predate it, so narrowing the response
+  would promise something no one can retroactively make true.
+
 ### Fixed
 
+- **A `tenantScope` naming a schema field instead of a column now fails at startup.**
+  `tenantScope` names real DB columns — the scope is applied to the SQL, after the payload has
+  been converted, and `through.foreignField` belongs to a parent table that may have no config of
+  its own. Nothing checked it, so writing `organizationId` where the column is `organization_id`
+  passed `defineTable` and surfaced as `column "organizationId" does not exist` on every request
+  to the table: an opaque `500`, failing closed but saying nothing. All four positions are now
+  checked (`column`, each `anyOf` entry, `through.localField`, and `through.foreignField` against
+  the parent schema). The check is narrow by design — it fires only when the name *is* a schema
+  field whose column differs, so a column absent from the schema raises nothing and a camelCase
+  database, where `col()` is the identity, raises nothing either.
+- **The `no-static-optional-peer` gate had never been able to fire.** `includeOnly: '^src/'` in
+  `.dependency-cruiser.mjs` dropped every npm edge from the dependency graph, so the rule meant to
+  stop a static import of `pg` / `mysql2` / `@fastify/*` — which breaks installs that use the other
+  dialect — matched nothing, ever. The graph now keeps npm dependencies as leaves, and the rule is
+  qualified to what its name says: static, value-level imports only, since a type-only import is
+  erased at compile time and a dynamic one is what the rule asks for. Both gates were verified by
+  introducing a violation and watching them fail.
+- **`defineTable` never validated `primary`.** A primary key naming a field the schema does not
+  have passed startup untouched and became a raw SQL error on the first request — a `500`. It
+  now throws at `defineTable` time, naming the field and the operations that need it. The one
+  exception is exact: a table exposing only `search` and declaring its own `defaultOrder` never
+  reads `primary`, which is the shape generated for a view whose key could not be inferred.
+- **PostgreSQL identity columns made a table impossible to insert into.**
+  `GENERATED ... AS IDENTITY` reports no `column_default`, which is what the generator read to
+  decide that the database fills a column in — so the primary key came out **mandatory** in the
+  write body while PostgreSQL rejected any explicit value for it (`Column "id" is an identity
+  column defined as GENERATED ALWAYS`). Identity columns are now flagged like MySQL's
+  `AUTO_INCREMENT`: the field is Optional and the CLI lists it under `excludeFromCreation`.
 - **Join validation no longer depends on the main result set.** `joinMultiple` / `joinLeft` /
   `joinGroup` skip their side query entirely when the main query matched no rows, so everything
   validated inside it was skipped with it — the same request answered 400 or 200 depending on