fastify-auto-sqlapi 0.2.1 → 0.2.2

package/docs/adr/0015-non-writable-columns.md

@@ -0,0 +1,86 @@
+# 0015. A column the database computes is not writable — `writeExclude` (narrows 0004)
+
+- **Status**: accepted
+- **Date**: 2026-08-28
+
+## Context
+
+[ADR 0004](./0004-updates-always-open.md) rejected `excludeFromUpdate`: a static per-field
+write block, proposed to protect `isAdmin`, `createdAt` and ownership columns. It lost on one
+argument — those cases are **session-dependent**, a static list cannot express them, and
+offering one would give a false sense of security to consumers who used it for exactly that.
+That reasoning stands unchanged.
+
+It does not, however, cover a case the plugin met later: a column the database itself refuses
+to be told about.
+
+```sql
+subtotal INTEGER GENERATED ALWAYS AS (qty * price) STORED
+```
+
+Both engines reject the whole statement — not the field — when a write so much as names such a
+column: `428C9 cannot insert a non-DEFAULT value into column "subtotal"` on PostgreSQL,
+`ER_NON_DEFAULT_VALUE_FOR_GENERATED_COLUMN` on MySQL. Yet nothing in the generated schema said
+so, so the column was offered as an ordinary writable field, and a client that sent it back
+what a read had just returned got a **500** — a raw driver error, per
+[ADR 0006](./0006-raw-db-errors.md) — for a payload nobody could have made valid.
+
+The same blind spot hid `GENERATED ... AS IDENTITY`, which has no `column_default` to reveal
+that the database fills it in: the generated field came out mandatory and the table could not
+be inserted into at all.
+
+## Decision
+
+Fields the database computes are excluded from every write path. The CLI records them in the
+generated Schema's `generatedFields`, and the runtime removes them from the insert, update and
+bulk-upsert bodies (main and secondaries) and again inside the engines, which `sqlApi.*`
+reaches without those schemas.
+
+`ITable.writeExclude` exposes the same mechanism for the columns introspection cannot know
+about — one a trigger owns, one a migration is about to drop.
+
+This narrows 0004 rather than reversing it, and the boundary is what the exclusion is *about*:
+
+- **a fact about the column** — the database rejects the value whoever assigned it, so there is
+  no configuration in which offering the field helps anyone. This ADR.
+- **a rule about the caller** — who may change what, when. Still product logic, still
+  `beforeUpdate` / `validate` / a dedicated endpoint. Still ADR 0004.
+
+Three consequences follow from that boundary and are enforced:
+
+- `writeExclude` runs **after** the write hooks — the opposite of `excludeFromCreation`, which
+  is sanitized before them so a hook can assign the field ([ADR 0005](./0005-insert-pipeline-sanitize-before-hooks.md)).
+  A hook cannot put back a value the database will refuse.
+- `defineTable` rejects a field that is also in `readExclude`: neither readable nor writable is
+  what removing it from the Schema means.
+- `defineTable` rejects the primary key, which the update body needs to identify the row.
+
+## Alternatives considered
+
+- **`Schema.generatedFields` only, no public key** — rejected: it covers the introspected case
+  and nothing else, and a consumer whose schema is hand-written or whose column is owned by a
+  trigger would be back to a driver error with no way out.
+- **Let the write through and map the driver error to a 400** — rejected: it contradicts
+  [ADR 0006](./0006-raw-db-errors.md) (no SQLSTATE→HTTP mapping), it costs a round trip to the
+  database to learn what the schema already knew, and the field would still be advertised as
+  writable in Swagger and in the agent manifest.
+- **Trim the column out of the generated Schema** — rejected: that removes it from reads too,
+  and a computed column is precisely the one a client wants to read.
+- **Reopen 0004 and add a general `excludeFromUpdate`** — rejected: the false-sense-of-security
+  argument is untouched by anything here. The documentation for `writeExclude` says what it is
+  not for, and the key deliberately has no per-caller or per-role dimension that would invite
+  the misuse 0004 warned about.
+
+## Consequences
+
+- Under Fastify's default `removeAdditional: true`, a computed column in a write body is
+  **stripped silently** rather than rejected; the row is written with the value the database
+  computed. With `removeAdditional: false` the closed body schema answers 400. Either way the
+  driver error is gone — which was the point.
+- A consumer upgrading gets the fix from **regenerating the Schema files alone**: the exclusion
+  travels in `generatedFields`, not in the `Table*.ts` the generator never overwrites.
+- The generated `Table*.ts` names the computed columns in a comment and leaves `writeExclude`
+  commented out, and `sqlapi-generate-schema` prints them per table — a generated source file
+  is not always read, its command's output is.
+- Reads are untouched: a computed column stays projected, filterable, orderable and
+  aggregatable, because it is a real column with a real value.

package/docs/adr/0016-a-view-is-a-table-config.md

@@ -0,0 +1,92 @@
+# 0016. A view is a table config — the generator refuses to invent its primary key
+
+- **Status**: accepted
+- **Date**: 2026-08-28
+
+## Context
+
+Views were never designed for, and they worked anyway: both introspections read
+`information_schema.columns`, which lists view columns exactly like table columns, so
+`sqlapi-generate-schema` produced a Schema and searching the result worked with no special
+support. Three things underneath that were wrong.
+
+**The primary key was invented in silence.** A view carries no `PRIMARY KEY` constraint, so
+`is_primary` is false on every column and the generated Schema had no `primaryKey`. The table
+generator then fell through to its heuristic for hand-written schemas: `id` if present,
+otherwise **the first integer column**, otherwise the first column of any kind. On
+`SELECT status, count(*) AS order_count ... GROUP BY status` that hands back `order_count` — a
+count — as the key, and `get/:id`, `update` and `delete` then address rows by it. Nothing said
+so, in the file or on the console.
+
+**Nothing validated `primary` at all.** `defineTable` checked `tenantScope`, `readExclude`,
+`computedFields` and alias uniqueness, but a `primary` naming a field the schema does not have
+passed straight through and became a raw SQL error on the first request — a 500, per
+[ADR 0006](./0006-raw-db-errors.md).
+
+**PostgreSQL materialized views were invisible.** They are not in `information_schema` at all;
+they live only in `pg_catalog`. They were skipped without a word — and a materialized view is
+precisely the kind of expensive read one wants to expose.
+
+## Decision
+
+A view **is** a table config. No `ViewName` file, no `View*` type, no `readOnly` flag: the
+plugin has one concept for "a relation with columns you can query" and a view is that one. A
+second name would fork the `dbTables` keys, the generator, the docs and the manifest to express
+nothing the existing vocabulary cannot.
+
+What changes is what may be **assumed**, and all of it lives in the generator and in startup
+validation, not in the runtime semantics:
+
+- Introspection reports `is_view` on both engines, and PostgreSQL materialized views are read
+  from `pg_catalog` and reported the same way. The generated Schema carries `isView: true`.
+- For a view the generator **never guesses a key from a column type**. It accepts `id` when the
+  view has one — a strong enough signal — and says in the file that the key was *inferred, not
+  read from the database*. With no `id`, it writes a `TODO_pick_a_unique_column` placeholder
+  rather than a wrong answer.
+- A view's generated config starts read-only: `operations: ['search', 'get']`, or
+  `['search']` when the key is unresolved. `defaultOrder` names a real column, so search never
+  falls back to the placeholder, and the config **works as generated** — the TODO is a note for
+  whoever wants to widen it, not a defect.
+- `defineTable` now validates `primary` against the schema fields. The exception is exact and
+  narrow: a table exposing **only** `search` and naming its own `defaultOrder` never reads
+  `primary`, so it is allowed. Anything else fails at startup.
+- `sqlapi-generate-schema` prints the views it found and both assumptions it had to make. A
+  generated source file is not always read; the output of the command that produced it is.
+
+Writes through a view are **not** blocked at runtime. A view simple enough for the engine to
+make updatable accepts INSERT and UPDATE on both PostgreSQL and MySQL, and using one as a
+projection or permission layer is a legitimate pattern the plugin has no business refusing. The
+read-only start is the *generated template* — a file the developer then owns — which is a
+different thing from the runtime default that [ADR 0002](./0002-open-by-default.md) settles.
+That default is untouched: a hand-written view config with no `operations` still exposes
+everything.
+
+## Alternatives considered
+
+- **`ViewName` files / a distinct type** — rejected: it forks a concept for no expressive gain
+  and breaks the one-name-per-concept rule the glossary exists to enforce.
+- **A `readOnly: true` flag on `defineTable`** — rejected: a second spelling of
+  `operations: ['search', 'get']`.
+- **Blocking writes to views at runtime** — rejected: simple views are genuinely updatable on
+  both engines (verified), and the plugin cannot tell which ones from the schema alone. It
+  would remove a working feature to prevent an error the database already reports.
+- **Keep guessing the key, just add a comment** — rejected: the wrong-key failure is silent and
+  addresses *rows*, which is the worst kind. A placeholder that refuses to start is the loud
+  version of the same information.
+- **Skip views entirely, or leave materialized views unsupported and document it** — rejected:
+  they already worked for reads, which is the case that matters, and silence about a relation
+  the database has is the least defensible of the options.
+
+## Consequences
+
+- A view without an `id` column needs one manual edit before it can serve anything but
+  `search`. That is the point: the edit is a decision about uniqueness that only the author of
+  the view can make.
+- `defineTable` now throws at startup on a `primary` that names no schema field. A config that
+  relied on that tolerance — a primary key deliberately kept out of the Schema — has to name a
+  schema field or restrict itself to `operations: ['search']`.
+- Materialized views appear in generation runs where they did not before, so a project that
+  regenerates with `--all` will find new `Table*.ts` files for them.
+- The `is_view` flag is generator-facing. Nothing in the request path branches on it: a view
+  searches, filters, orders, paginates, joins and (when the database allows) writes through the
+  same code as a base table.

package/docs/adr/0017-the-schema-is-the-contract.md

@@ -0,0 +1,85 @@
+# 0017. The database schema is the API contract — by default, and only by default
+
+- **Status**: accepted
+- **Date**: 2026-08-28
+
+## Context
+
+The first objection this plugin meets is always the same: *it couples the API to the database.*
+Change a column and you change the API, and through it every client.
+
+The objection is real and worth answering precisely, because the imprecise answer ("it's fine
+for internal tools") concedes more than it has to and defends less than it should.
+
+## Decision
+
+The database schema is the API contract **by default**. That is the mechanism, not a shortcut,
+and it rests on three things.
+
+**The coupling is exposed, not created.** A hand-written CRUD layer over the same tables is
+coupled to exactly the same schema — it just retypes it. Rename a column there and you edit the
+model, the DTO, the mapper, the validator, the Swagger annotation and the client, in six places
+instead of one. What that layer genuinely buys is different: an indirection that lets the
+contract stay still while the schema moves. That is a real thing to want, and it is paid for
+continuously and cashed in rarely. This plugin makes the opposite bet, and states it.
+
+**It is checked, not implied.** The Schema files are generated from `information_schema`, so a
+schema change that breaks the API breaks it when you regenerate and compile — for TypeScript
+consumers, at build time. A hand-written mapper that nobody remembered to update fails in
+production instead. (Untyped clients — a browser fetch — still find out at runtime; the
+generated Swagger and `GET {prefix}/agent/manifest.md` are what they check against.)
+
+**It is a default, and every part of it is overridable.** The exposed shape is not forced to be
+the stored shape:
+
+| To decouple | Use |
+|---|---|
+| a column exists but must never be read | `readExclude` |
+| a column exists but must never be written | `writeExclude` ([ADR 0015](./0015-non-writable-columns.md)) |
+| a column must not exist for the API at all | trim it out of the Schema |
+| the API type must be stricter than the column | `schemaOverrides` |
+| the API value is derived, not stored | `computedFields` |
+| the stored representation is not the API one | `afterRead` (decrypt, unpack, rescale) |
+| a table must not have all seven routes | `operations` |
+| a relation must be named for the API, not the DB | the relation `alias`, plus its `fields` allowlist |
+| a filter has no column behind it | `extraFilters` + `extendedCondition` |
+| different callers need different surfaces | register the plugin more than once, under different prefixes |
+
+And when none of that fits, the operation is not a CRUD operation: write the route by hand and
+call `app.sqlApi.*` inside it. That is not the fallback path — it is the design. The custom
+route keeps filters, joins, tenant scoping, hooks and validation; what it does not keep is the
+assumption that the endpoint looks like a table.
+
+**Where the objection is right.** A public or third-party API — consumers you cannot redeploy
+alongside your schema, a contract with a version number and a deprecation policy — is a surface
+whose stability has to outlive refactors. There an indirection that survives schema movement
+earns its cost, and generating that surface from the schema is the wrong default. Do not
+auto-expose it: keep those tables off the auto routes with `operations`, or behind their own
+hand-written endpoints, and let the plugin serve the surface it is for.
+
+That surface is the internal one: back-office and admin tools where superadmin, admin and
+tenant-admin roles need full control over the domain, the schema *is* the domain model, and the
+people who change a column are the people who change the screen that shows it. There, the
+translation layer has no reader — it exists only to be kept in sync with the thing it
+translates.
+
+## Alternatives considered
+
+- **A mapping/DTO layer inside the plugin** — rejected: that is the hand-written layer again,
+  re-expressed as configuration instead of code, with the same maintenance cost and less
+  freedom. The per-concern levers above cover what most projects actually need to hide or
+  reshape, and a custom route covers the rest without inventing a second schema language.
+- **Frozen schema snapshots, versioned independently of the database** — rejected: a second
+  source of truth to keep in sync, which is precisely what [ADR 0001](./0001-no-orm-raw-sql.md)
+  refused when it refused an ORM's models and migrations.
+- **Saying nothing and letting readers work it out** — rejected: it is the first question every
+  reviewer asks, and an unanswered one reads as an unconsidered one.
+
+## Consequences
+
+- Renaming a column changes the API field. Accepted: it is one regeneration, and typed
+  consumers fail to compile rather than failing quietly.
+- The plugin is not the right tool for a versioned public API, and says so in the README rather
+  than leaving it to be discovered.
+- Every "the API should not look like the table" request has a specific answer in the table
+  above, or is a custom route. Neither is a gap in the plugin.

package/docs/adr/0018-one-seam-to-the-http-framework.md

@@ -0,0 +1,68 @@
+# 0018. The HTTP framework is reachable through one seam — `ApiRequest`
+
+- **Status**: accepted
+- **Date**: 2026-08-29
+
+## Context
+
+The question was what it would take to serve the same engine over something other than Fastify.
+Measuring first turned up a codebase that was already almost free of one:
+
+- of 74 files under `src/`, 26 named a Fastify type and **not one imported a value from it**;
+- **nothing under `src/lib/` ever read a property off the request** — no `body`, no `params`, no
+  `log`. It arrives from the route, is forwarded to `getTenantId`, `validate` and the hooks, and
+  is otherwise untouched;
+- `httpError` produces a plain `Error` carrying `statusCode`. Fastify happens to read that; the
+  plugin does not produce it *for* Fastify.
+
+So the engine, the schema builders and the write pipeline depend on a web framework for exactly
+one thing: the **name of a type they never dereference**. That dependency was spread across
+thirteen files, where every new hook signature quietly widened it, and nothing prevented an
+engine from starting to read `request.headers` tomorrow.
+
+## Decision
+
+The request type is declared once, in `src/types/request.ts`, and everything in the core refers
+to that name:
+
+```ts
+export type ApiRequest = FastifyRequest;
+```
+
+`.dependency-cruiser.mjs` enforces it: `http-framework-behind-one-seam` fails the build on a
+`fastify` import — **including a type-only one** — anywhere under `src/lib/`, `src/types/` or
+`src/bin/` other than that file. The two Fastify bridge helpers that lived in `lib/`
+(`setup-swagger`, `sql-api-decorator`) moved to `src/routes/`, which is where the adapter is, so
+the rule needs no exceptions.
+
+A plain alias, not a generic parameter on `ITable`. `ITable` appears as a bare type in over a
+hundred places; threading `<Req>` through all of them — and through `DbTables`, and every
+`*Params` — changes the public type surface today to buy a property that only pays off once the
+core ships as a package of its own. The alias makes the seam **one file**, which is the whole
+requirement, and leaves the generic available later without having spent anything on it now.
+
+This decision is about where the dependency lives, not about supporting a second framework. It
+records what the measurement found, and stops it from silently degrading.
+
+## Alternatives considered
+
+- **`ITable<F, Req = FastifyRequest>`** — rejected for now, as above: the churn is large, it
+  changes the public types, and mixed `DbTables` maps get awkward. It is the right shape for a
+  three-package split and can be done then, from this seam, in one file's worth of decisions.
+- **Leave `FastifyRequest` inline and write the constraint in the docs** — rejected: a property
+  that thirteen files must remember is a property that lasts until the next hook is added.
+  Gates, not documentation (ADR 0012).
+- **Make the core read nothing by typing the request as `unknown`** — rejected: it would break
+  every consumer's typed hook to express something the consumer does not need to know.
+
+## Consequences
+
+- Consumers see no change: `ApiRequest` *is* `FastifyRequest`, and it is exported from the
+  package for anyone declaring a hook outside a `defineTable` call.
+- The core cannot regress. An engine that starts naming a Fastify type fails `npm run verify`.
+- A second HTTP adapter is now a question about `src/routes/` (582 lines) plus what Fastify does
+  for free — request validation against the generated schemas, and response serialization, which
+  is part of the contract rather than plumbing — and not a question about the engine at all.
+- Fixing the rule so it could fire revealed that `no-static-optional-peer` had never been able
+  to: `includeOnly: '^src/'` dropped every npm edge from the graph. It is live now, qualified to
+  what its name says (static, value-level imports of optional peers).

package/docs/adr/README.md

@@ -28,6 +28,11 @@ not by editing history.
 | [0011](./0011-join-fields-allowlist.md) | Per-relation field restriction is an allowlist, not a blocklist |
 | [0012](./0012-anti-duplication-tooling.md) | Repository rules are enforced by executable gates, not by documentation |
 | [0013](./0013-sanitized-db-errors.md) | Database error messages are sanitized on the wire by default (narrows 0006) |
+| [0014](./0014-what-follows-a-write-join.md) | A secondary runs the child table's transform, not its verdicts |
+| [0015](./0015-non-writable-columns.md) | A column the database computes is not writable — `writeExclude` (narrows 0004) |
+| [0016](./0016-a-view-is-a-table-config.md) | A view is a table config — the generator refuses to invent its primary key |
+| [0017](./0017-the-schema-is-the-contract.md) | The database schema is the API contract — by default, and only by default |
+| [0018](./0018-one-seam-to-the-http-framework.md) | The HTTP framework is reachable through one seam — `ApiRequest` |
 
 ## When to write one
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",

package/dist/lib/setup-swagger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"setup-swagger.d.ts","sourceRoot":"","sources":["../../src/lib/setup-swagger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAkB,MAAM,aAAa,CAAC;AAEvE,wBAAsB,YAAY,CAChC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

package/dist/lib/sql-api-decorator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sql-api-decorator.d.ts","sourceRoot":"","sources":["../../src/lib/sql-api-decorator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,eAAe;QACvB,MAAM,EAAE,MAAM,CAAC;KAChB;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC3B,IAAI,CA2BN"}