@edium/halifax 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,88 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0]
+
+A breaking release with two themes: **permissive, minimal-by-default resource definitions**
+(declare the exceptions, not the boilerplate), and a **full real-database CI matrix** that
+verifies every supported engine for real.
+
+### Added
+
+- **Full real-database CI matrix** — the integration suite now runs against **six** engines,
+  each in its own container: PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, and SQLite
+  (embedded). Previously only PostgreSQL, MySQL, and SQLite ran in CI.
+- `docker-compose.test.yml` (one service per engine) and `scripts/integration-matrix.sh` /
+  `pnpm test:integration:all` to bring the databases up and run the suite against each — the
+  same path CI uses, so local and CI runs are identical.
+- Prisma schemas for SQL Server (`schema.mssql.prisma`) and CockroachDB
+  (`schema.cockroachdb.prisma`, using `sequence()` ids to stay 32-bit-safe), and the
+  `@prisma/adapter-mssql` driver adapter.
+- An ID-kind-aware integration suite: assertions adapt to the engine's key type (integer vs
+  MongoDB `ObjectId`), so one suite runs honestly across every engine.
+
+### Changed (breaking)
+
+- **`ResourceDefinition` is permissive and minimal.** Only `routePrefix`, `repository`, and
+  `fields` are required — and `fields` only when the repository exposes no schema of its own.
+  - `name` is now **optional** — it defaults to a title-cased form of `routePrefix`
+    (`'blog-posts'` → `'Blog Posts'`) and can still be overridden.
+  - **`fields` is now optional and override-aware.** When the repository exposes a field schema
+    (any `PrismaAdapter` built with a `model`, and everything from `createPrismaResources`), that
+    schema is the base and the resource's `fields` are merged over it **by name** as sparse
+    overrides — so you list a field only to _change_ it. With a bare adapter, `fields` remains
+    the authoritative allow-list.
+- **Field flags are permissive by default.** `filterable`, `sortable`, `selectable`, and now
+  **`writable`** all default to `true`. Previously `writable` defaulted to `false` — bodies now
+  accept any defined field unless you set `writable: false`. The **primary key is protected**: it
+  is non-writable by default (set `writable: true` to opt in).
+- **Page size is bounded by generous defaults — at most 5000 records per request.**
+  `defaultLimit: 5000` and `maxLimit: 5000` (exported as `DEFAULT_PAGE_LIMIT` / `MAX_PAGE_LIMIT`)
+  apply when a resource sets none — large enough for typical "show everything" UIs, a seatbelt
+  against an accidental unbounded scan of a large table. Previously an unset limit returned every
+  row, uncapped. The response `count` is always the true total, so a capped page is never a silent
+  drop. Set `defaultLimit: 0` to skip the default bound (return all rows when `?limit=` is omitted)
+  and `maxLimit: 0` to remove the cap — use both to disable pagination entirely.
+- **`RepositoryCapabilities` trimmed to the two flags that carry their weight:** removed
+  `supportsTransactions` (no transaction feature existed) and `supportsQueryAst` (always true;
+  implied by the presence of `executeQuery`). `supportsIncludes` now has teeth — the router
+  rejects `?include=` with `422` when a repository reports `supportsIncludes: false`. The
+  `Repository` interface gained optional `fields` / `relations` / `idField` for schema exposure.
+- **Widened the `@prisma/client` peer dependency to `>=6.0.0`** (was `>=7.0.0`). `PrismaAdapter`
+  imports nothing from `@prisma/client` and only calls stable model-delegate methods, so it runs
+  unchanged on Prisma 6 or 7. CI exercises Prisma 7 only, so Prisma 6 is best-effort; its main
+  draw is MongoDB, which Prisma 7 does not yet support. See README_REPO_ADAPTERS.md for the
+  schema/client differences a Prisma 6 project needs.
+
+### Removed
+
+- **MongoDB** from the advertised supported-database list and the CI matrix. Prisma ORM v7
+  dropped MongoDB support ("coming soon in v7"), and the matrix targets Prisma 7. MongoDB still
+  works on **Prisma 6** (now also supported — see above). The forward-ready `schema.mongodb.prisma`
+  and an `ObjectId`-aware integration suite remain in the repo so MongoDB rejoins the matrix
+  unchanged once Prisma 7 restores support.
+- The "PostgreSQL, MySQL, and SQLite run in CI; the rest use the same adapter and test harness"
+  documentation caveat — every advertised relational engine is now verified in CI against a real
+  database.
+- The deprecated auth aliases `AuthProvider`, `AllowAllAuthProvider`, `ApiKeyAuthProvider`, and
+  `PermissionAuthProvider`. Use `AuthStrategy`, `AllowAllAuthStrategy`, `ApiKeyAuthStrategy`, and
+  `JwtClaimsAuthStrategy` respectively.
+
+### Migration
+
+- Resource definitions can be slimmed dramatically: drop `name` (unless you want a specific one),
+  drop per-field `filterable`/`sortable`/`selectable`/`writable: true` flags, and drop
+  `defaultLimit`/`maxLimit` if 5000/5000 suit you.
+- **If your app relied on list endpoints returning _every_ row** (no limit), set
+  `defaultLimit: 0` and `maxLimit: 0` on those resources (or globally via
+  `createPrismaResources({ defaultLimit: 0, maxLimit: 0 })`) — otherwise results are now bounded
+  at 5000 by default.
+- If you relied on `writable` defaulting to `false`, audit your `fields`: any field that should
+  not be client-writable now needs an explicit `writable: false` (the primary key is already
+  protected automatically).
+- If you read `capabilities.supportsTransactions` or `capabilities.supportsQueryAst`, remove those
+  references (use `typeof repo.executeQuery === 'function'` to detect query-AST support).
+
 ## [1.0.0]
 
 First public release.
@@ -28,4 +110,5 @@ First public release.
 - **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action
   required permissions; and `filterable`/`sortable`/`selectable`/`writable` field flags.
 
+[2.0.0]: https://github.com/splayfee/halifax/releases/tag/v2.0.0
 [1.0.0]: https://github.com/splayfee/halifax/releases/tag/v1.0.0

package/README.md

@@ -14,21 +14,21 @@ The package is split into small, replaceable layers — nothing is imported into
 - 🚀 **Zero-boilerplate CRUD** — define a resource once and get standards-compliant REST endpoints (list, read, create, update, upsert, delete, bulk) with correct status codes and a consistent error shape.
 - 🧩 **Adapter-driven & swappable** — your HTTP framework, ORM/database, and auth provider are injected, not baked in. Switch any layer without touching your resource definitions.
 - 🌐 **4 HTTP frameworks, identical behavior** — Express 4/5, Fastify, HyperExpress, and Ultimate Express, all verified against one shared conformance suite.
-- 🗄️ **Many databases, one adapter** — PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, CockroachDB, and MongoDB via [Prisma](https://www.prisma.io/). The query builder compiles to portable Prisma calls (never raw SQL), so the **same client request behaves identically on every database** — switch engines by changing one line. (PostgreSQL, MySQL, and SQLite run in CI; the rest use the same adapter and test harness.)
+- 🗄️ **Six databases, one adapter** — PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, and SQLite via [Prisma](https://www.prisma.io/). The query builder compiles to portable Prisma calls (never raw SQL), so the **same client request behaves identically on every database** — switch engines by changing one line. Every engine is verified in CI against a real database — one matrix leg each, the same suite on all.
 - 🔎 **Dynamic query-builder endpoint** — let the front-end compose rich filtered/sorted/paginated queries "for free" (`AND`/`OR`/nesting, `IN`, `BETWEEN`, `CONTAINS`, …) without hand-writing endpoints. Fully validated — bad fields/operators return structured `4xx` errors, never leaked DB internals.
 - 🏢 **Multi-tenancy built in** — per-resource tenant scoping with fail-closed guarantees; one tenant can never read or write another's rows.
 - ⚡ **Pluggable read-through caching** — in-memory or Redis, per-resource TTLs, never-expire mode, automatic write-invalidation, tenant-safe keys, and a `Cache-Control` bust header.
 - 🔐 **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action permissions; and `filterable`/`sortable`/`selectable`/`writable` flags enforced on every request.
-- 🧪 **Type-safe & battle-tested** — strict TypeScript, ESM, ships full `.d.ts`; hundreds of unit tests plus real-database + Redis integration tests in CI.
+- 🧪 **Type-safe & battle-tested** — strict TypeScript, ESM, ships full `.d.ts`; hundreds of unit tests plus the full integration suite run against six real databases + Redis in CI.
 
 ## Current Support
 
-| Layer          | Supported                                                                     |
-| -------------- | ----------------------------------------------------------------------------- |
-| HTTP server    | Express 4/5, Fastify, HyperExpress, Ultimate Express                          |
-| ORM / database | Prisma 7 + Postgres, MySQL, MariaDB, SQL Server, SQLite, MongoDB, CockroachDB |
-| Auth           | API key, JWT/Bearer, Passport + JWT                                           |
-| Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)           |
+| Layer          | Supported                                                                 |
+| -------------- | ------------------------------------------------------------------------- |
+| HTTP server    | Express 4/5, Fastify, HyperExpress, Ultimate Express                      |
+| ORM / database | Prisma 6 or 7 + Postgres, MySQL, MariaDB, SQL Server, CockroachDB, SQLite |
+| Auth           | API key, JWT/Bearer, Passport + JWT                                       |
+| Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)       |
 
 Every HTTP adapter is interchangeable and behaves identically — same routes, status codes,
 error-body shape, and content negotiation — so you can switch frameworks without touching
@@ -38,9 +38,19 @@ your resource definitions, auth, or query logic. See
 The same is true across databases: the dynamic query-builder endpoint and all CRUD compile
 to portable Prisma Client calls (never raw SQL), so the **same client request behaves
 identically on every database** — switch engines by changing only the Prisma `provider`. The
-integration suite runs unchanged against Postgres, MySQL, and SQLite in CI to keep that honest.
-
-> **Roadmap** — This project welcomes community-written adapters for Drizzle, Sequelize, etc.
+integration suite runs unchanged against all six engines — Postgres, MySQL, MariaDB, SQL Server,
+CockroachDB, and SQLite — in CI (one matrix leg per engine) to keep that honest.
+
+> **MongoDB — coming back.** MongoDB is absent from the list above for one reason only:
+> **Prisma ORM v7 dropped its MongoDB connector** (Prisma's own guidance is to stay on v6 for
+> Mongo; v7 support is "coming soon"). This is a Prisma limitation, not a Halifax one —
+> `PrismaAdapter` is database-agnostic and never touches the connection. The
+> `schema.mongodb.prisma` and an `ObjectId`-aware integration suite are already in the repo, so
+> **the moment Prisma restores MongoDB support in v7, Halifax will add it back** — it rejoins
+> the CI matrix unchanged, with no API changes for you. Need MongoDB today? It still works on
+> **Prisma 6**, which Halifax also supports — see [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md).
+>
+> **Roadmap** — community-written adapters for Drizzle, Sequelize, etc. are also welcome.
 
 ## Install
 
@@ -64,22 +74,18 @@ import {
 
 const prisma = new PrismaClient({ adapter: new PrismaPg(process.env.DATABASE_URL!) })
 
+// Permissive + minimal by default: only `routePrefix`, `repository`, and `fields` are required.
+// Every field is filterable / sortable / selectable / writable unless you turn it off, and the
+// primary key is never writable. Every CRUD action is enabled unless you disable it.
 const posts: ResourceDefinition = {
-  name: 'Post',
   routePrefix: 'posts',
-  defaultLimit: 50,
-  maxLimit: 200,
-  fields: [
-    { name: 'id', filterable: true, sortable: true },
-    { name: 'title', filterable: true, sortable: true, writable: true },
-    { name: 'content', writable: true },
-    { name: 'published', filterable: true, writable: true }
-  ],
-  permissions: {
-    allowUpdateMany: false,
-    allowDeleteMany: false
-  },
-  repository: new PrismaAdapter({ delegate: prisma.post })
+  repository: new PrismaAdapter({ delegate: prisma.post }),
+  fields: [{ name: 'id' }, { name: 'title' }, { name: 'content' }, { name: 'published' }]
+
+  // Everything below is OPTIONAL — shown here just to illustrate the exceptions you *can* set:
+  // name: 'Post',                       // defaults to a title-cased routePrefix ('posts' → 'Posts')
+  // permissions: { allowDeleteMany: false }, // all actions on by default; list only what to disable
+  // defaultLimit: 5000, maxLimit: 5000, // these are the defaults already (0 / 0 = no pagination)
 }
 
 const app = express()
@@ -91,58 +97,74 @@ app.use(
 app.listen(3000)
 ```
 
+> **Even less boilerplate.** For a Prisma-backed API, `createPrismaResources(prisma, Prisma.dmmf.datamodel.models)`
+> derives a fully-configured resource for **every** model — no `fields`, no `routePrefix`, nothing
+> to hand-write — and you override only the exceptions per model. The hand-built resource above is
+> the path for custom, non-Prisma repositories. See
+> [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) for both, and
+> [README_AUTOCRUD.md](./README_AUTOCRUD.md) for a "verbose mode" resource with every option
+> annotated.
+
 ## Documentation
 
 | Guide                                                | Contents                                                                                      |
 | ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | [README_AUTOCRUD.md](./README_AUTOCRUD.md)           | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes |
-| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 setup, `PrismaAdapter` options, capabilities, custom repositories                    |
+| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 (and 6) setup, `PrismaAdapter` options, capabilities, custom repositories            |
 | [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters          |
 | [README_AUTH.md](./README_AUTH.md)                   | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, custom `authorize`      |
 | [README_MULTITENANCY.md](./README_MULTITENANCY.md)   | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour |
 | [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)   | Query-builder payload, comparisons, nested filters, portable Prisma execution                 |
 | [README_CACHE.md](./README_CACHE.md)                 | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header               |
 
+## Examples
+
+Runnable, self-contained examples live in [`examples/`](./examples) — each is a complete server
+you can start with `pnpm tsx examples/<file>.ts`:
+
+- **One per HTTP adapter** — `http-express.ts` (the canonical one, with an annotated "verbose
+  mode"), `http-fastify.ts`, `http-hyper-express.ts`, `http-ultimate-express.ts`. Same resources,
+  same behaviour; only the framework wiring differs.
+- **One per database** — `db-postgres.ts`, `db-mysql.ts`, `db-mariadb.ts`, `db-mssql.ts`,
+  `db-cockroachdb.ts`, `db-sqlite.ts`. Express + Prisma against each engine; only the driver
+  adapter and connection string change.
+
 ## Running Integration Tests
 
-The integration suite tests the full stack against a real PostgreSQL database.
+The integration suite runs the full stack against a **real database**, and the _same_ suite runs
+unchanged against every supported engine. `docker-compose.test.yml` brings up one container per
+engine (SQLite is embedded, so it needs none); `HALIFAX_DB` + `DATABASE_URL` select which one a
+run targets, and `globalSetup` runs `prisma generate` + `prisma db push` automatically.
 
-### 1. Start a Postgres container
+### Run against every database
 
 ```bash
-docker run -d \
-  --name halifax-test-db \
-  --restart unless-stopped \
-  -e POSTGRES_USER=postgres \
-  -e POSTGRES_PASSWORD=postgres \
-  -e POSTGRES_DB=halifax_test \
-  -p 5432:5432 \
-  postgres:17
+docker compose -f docker-compose.test.yml up -d --wait   # postgres, mysql, mariadb, mssql, cockroachdb, redis
+pnpm test:integration:all                                 # runs the suite against all six engines
+docker compose -f docker-compose.test.yml down -v         # tear everything down
 ```
 
-### 2. Create `.env.test`
+### Run against a single database
+
+`pnpm test:integration` targets PostgreSQL by default (via `.env.test`). To target one specific
+engine, use the matrix script — it sets the right `DATABASE_URL` for you:
 
 ```bash
-DATABASE_URL="postgresql://postgres:postgres@localhost:5432/halifax_test"
+docker compose -f docker-compose.test.yml up -d --wait cockroachdb redis
+bash scripts/integration-matrix.sh cockroachdb       # or: postgres | mysql | mariadb | mssql | sqlite
 ```
 
-### 3. Run
+Or the classic single-Postgres flow with a `.env.test` file:
 
 ```bash
-pnpm test:integration
+# .env.test
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/halifax_test"
 ```
 
-`globalSetup` runs `prisma generate` and `prisma db push` automatically before any test executes.
-
-### Subsequent runs
-
 ```bash
-docker start halifax-test-db
 pnpm test:integration
 ```
 
-### Tear down
-
-```bash
-docker stop halifax-test-db && docker rm halifax-test-db
-```
+> MongoDB is not in the matrix yet — Prisma 7 dropped MongoDB support (coming soon in v7). The
+> schema and ObjectId-aware suite are already in place and rejoin the matrix unchanged once
+> Prisma supports it.

package/README_AUTOCRUD.md

@@ -8,31 +8,61 @@ Halifax generates REST endpoints automatically from a `ResourceDefinition`. Defi
 import type { ResourceDefinition } from '@edium/halifax'
 import { postRepository } from './repositories/post.js'
 
+// Permissive + minimal by default. Only `routePrefix`, `repository`, and `fields` are
+// required — and `fields` only when the repository can't supply its own schema (see below).
 export const postResource: ResourceDefinition = {
-  name: 'Post',
   routePrefix: 'posts',
-  defaultLimit: 50, // applied when the caller omits ?limit=
-  maxLimit: 200, // requests above this are silently capped
+  repository: postRepository,
   fields: [
-    { name: 'id', filterable: true, sortable: true },
-    { name: 'title', filterable: true, sortable: true, writable: true },
-    { name: 'content', writable: true },
+    { name: 'id' }, // primary key — non-writable automatically
+    { name: 'title' },
+    { name: 'content' },
+    { name: 'published' },
+    { name: 'authorId', writable: false }, // the only "exceptions" you need to spell out:
+    { name: 'createdAt', writable: false } // FK + server-managed timestamp are read-only
+  ]
+}
+```
+
+> **Why so few fields?** When the repository already knows the model schema — any
+> `PrismaAdapter` built with a `model`, and everything from `createPrismaResources` — you can
+> omit `fields` entirely; the repository's schema becomes the base and anything you list is
+> merged over it **by name** as a sparse override. So you declare a field only to _change_ it
+> (e.g. `{ name: 'content', writable: false }`). The bare adapter above (no model) is the path
+> for **custom, non-Prisma repositories**, where `fields` is how you declare the API surface.
+
+### Verbose mode — every option, defaults made explicit
+
+Nothing here is required; this is the same resource with every knob turned and annotated, so
+you can see exactly what the minimal form above is defaulting to.
+
+```ts
+export const postResource: ResourceDefinition = {
+  routePrefix: 'posts',
+  repository: postRepository,
+  name: 'Post', // default: title-cased routePrefix ('posts' → 'Posts')
+  fields: [
+    // Every flag defaults to `true`; the primary key is non-writable unless opted in.
+    { name: 'id', filterable: true, sortable: true, selectable: true, writable: false },
+    { name: 'title', filterable: true, sortable: true, selectable: true, writable: true },
+    { name: 'content', selectable: true, writable: true },
     { name: 'published', filterable: true, writable: true },
-    { name: 'authorId', filterable: true },
-    { name: 'createdAt', filterable: false, sortable: true, selectable: true }
+    { name: 'authorId', filterable: true, writable: false },
+    { name: 'createdAt', sortable: true, writable: false }
   ],
-  relations: [{ name: 'author', includable: true }],
+  relations: [{ name: 'author', includable: true }], // default: includable when listed
   permissions: {
+    // All nine actions default to `true` — list only the ones you DISABLE.
     allowDeleteMany: false
   },
   requiredPermissions: {
     readMany: ['posts.read'],
-    readOne: ['posts.read'],
     create: ['posts.create'],
-    updateOne: ['posts.update'],
     deleteOne: ['posts.delete']
   },
-  repository: postRepository
+  defaultLimit: 5000, // default: 5000   (0 = return all rows when ?limit= is omitted)
+  maxLimit: 5000, // default: 5000   (0 = no cap)
+  cache: { ttlSeconds: 30 } // default: caching off
 }
 ```
 
@@ -66,14 +96,14 @@ GET /api/v1/posts/507f1f77bcf86cd799439011
 
 ## Field Flags
 
-Each entry in `fields` accepts four optional boolean flags. All default to `true` — only set them explicitly to `false` to restrict access.
+Each entry in `fields` accepts four optional boolean flags. All default to `true` — only set them explicitly to `false` to restrict access. The lone exception: the **primary key** is non-writable by default (it comes from the URL / database); set `writable: true` on it if you really want clients to supply it.
 
 | Flag         | Effect when `false`                                                   |
 | ------------ | --------------------------------------------------------------------- |
 | `filterable` | Rejects the field as a query-string filter (`?fieldName=value`) → 400 |
 | `sortable`   | Rejects the field in `?order=` and query-builder `orderBy` → 400      |
 | `selectable` | Rejects the field in `?fields=` and query-builder `fields` → 400      |
-| `writable`   | Silently strips the field from POST / PATCH request bodies            |
+| `writable`   | Silently strips the field from POST / PATCH / PUT request bodies      |
 
 Example — `role` is fully locked down; `createdAt` can be read and sorted but never written or filtered:
 
@@ -88,16 +118,28 @@ fields: [
 
 ## Pagination
 
-Set `defaultLimit` and `maxLimit` on the resource:
+**By default a list endpoint returns at most 5000 records.** Page size is bounded by generous
+defaults — **`defaultLimit: 5000`** (used when the caller omits `?limit=`) and **`maxLimit: 5000`**
+(the hard ceiling) — a seatbelt against an accidental unbounded scan of a large table, nothing
+more. The response `count` is always the true total matching the query, so a capped page is never
+a _silent_ drop — a client can see when `count` exceeds the number of returned rows. Override
+either per resource:
 
 ```ts
 {
-  defaultLimit: 50,   // used when the caller omits ?limit=
-  maxLimit:     200,  // requests above this are silently capped to 200
+  defaultLimit: 25,   // smaller default page for this resource
+  maxLimit:     5000, // allow larger pages here
 }
 ```
 
-Neither is required. Without them, page size is unlimited and fully caller-controlled.
+**Disabling pagination.** Set a limit to `0` to remove that bound. `defaultLimit: 0` returns all
+rows when `?limit=` is omitted; `maxLimit: 0` removes the cap. Use both to turn pagination off
+entirely (every request returns the full result set) — handy when migrating an app that has
+always pulled all rows:
+
+```ts
+{ defaultLimit: 0, maxLimit: 0 } // no pagination — return everything
+```
 
 ## Query-String Filtering and Pagination
 
@@ -107,7 +149,7 @@ GET /api/v1/posts?limit=25&offset=0&order=-createdAt&published=true&fields=id,ti
 
 | Parameter       | Description                                                            |
 | --------------- | ---------------------------------------------------------------------- |
-| `limit`         | Page size. Capped by `maxLimit`; defaults to `defaultLimit` if set.    |
+| `limit`         | Page size. Capped by `maxLimit`; defaults to `defaultLimit` (5000).    |
 | `offset`        | Number of rows to skip.                                                |
 | `order`         | Comma-separated field names. Prefix `-` for descending.                |
 | `fields`        | Comma-separated field names to include in the response.                |

package/README_QUERYBUILDER.md

@@ -2,7 +2,7 @@
 
 The query builder exposes an advanced `POST /:resource/query` endpoint that accepts a structured JSON payload (an AST — abstract syntax tree) describing filters, sorting, pagination, and projection. It lets the front-end compose rich list queries "for free", without the back-end adding custom endpoints. (The path segment defaults to `query`; override it with the `queryBuilderPath` option.)
 
-**Database-agnostic by design.** The payload is fully validated against the resource — every field name, comparison, sort, and nesting depth — and invalid input returns a structured `400`/`422` _before_ any database call. The validated AST is then compiled to portable **Prisma Client** calls (never raw SQL), so the exact same request behaves identically on PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, CockroachDB, and MongoDB. Switch databases by changing only the Prisma `provider` — your client code never changes.
+**Database-agnostic by design.** The payload is fully validated against the resource — every field name, comparison, sort, and nesting depth — and invalid input returns a structured `400`/`422` _before_ any database call. The validated AST is then compiled to portable **Prisma Client** calls (never raw SQL), so the exact same request behaves identically on PostgreSQL, MySQL/MariaDB, SQL Server, CockroachDB, and SQLite. Switch databases by changing only the Prisma `provider` — your client code never changes.
 
 It is enabled by default; disable it per-resource with the `allowReadManyWithQueryBuilder` permission:
 

package/README_REPO_ADAPTERS.md

@@ -31,14 +31,12 @@ Repositories declare what they support through a `capabilities` property. Read i
 
 ```ts
 interface RepositoryCapabilities {
-  supportsIncludes: boolean // ORM relation loading
-  supportsTransactions: boolean // transaction wrapping
-  supportsCreateManyReturn: boolean // createMany returns the created records
-  supportsQueryAst: boolean // executes the query-builder AST
+  supportsIncludes: boolean // ORM relation loading; when false the router rejects ?include= with 422
+  supportsCreateManyReturn: boolean // createMany returns the created records (vs. an empty array)
 }
 ```
 
-`PrismaAdapter` implements `updateMany` / `deleteMany` / `executeQuery` for every database (they compile to portable Prisma Client calls) and reports `supportsQueryAst: true`.
+`PrismaAdapter` reports `supportsIncludes: true` and `supportsCreateManyReturn: <returnCreated>`. It implements `updateMany` / `deleteMany` / `executeQuery` for every database (they compile to portable Prisma Client calls).
 
 ## Prisma 7 Repository Adapter
 
@@ -156,6 +154,81 @@ new PrismaAdapter({
 
 `select` (field projection) and `include` (relation loading) are mutually exclusive in Prisma. The adapter enforces this automatically: when `fields` is specified, it builds a `select` and ignores `include`; when only `include` is specified, it builds an `include`.
 
+## Where does the field schema come from?
+
+A resource always needs a field schema — it's the allow-list that powers filtering, sorting, projection, and field-level write security. There is no schemaless resource; the router throws at registration if it can't find one. The schema can come from **two places**:
+
+1. **Derived from the model (preferred for Prisma).** When the `PrismaAdapter` knows the model, it exposes `fields`/`relations`/`idField`, and the resource can omit `fields` entirely — or list only the ones it wants to **change** (merged by name as sparse overrides). The zero-config way to get there is `createPrismaResources`, which builds a ready-to-serve resource for every model from Prisma's DMMF:
+
+   ```ts
+   import { Prisma, PrismaClient } from '@prisma/client'
+   import { PrismaPg } from '@prisma/adapter-pg'
+   import { createPrismaResources, createExpressCrudRouter } from '@edium/halifax'
+
+   const prisma = new PrismaClient({ adapter: new PrismaPg(process.env.DATABASE_URL!) })
+
+   // One line → a resource per model, fields and relations derived. No `fields` arrays anywhere.
+   const resources = createPrismaResources(prisma, Prisma.dmmf.datamodel.models, {
+     // Optional per-model tweaks — the only place you write anything:
+     models: {
+       AuditLog: { permissions: { allowDeleteOne: false, allowDeleteMany: false } }
+     }
+   })
+
+   app.use('/api/v1', createExpressCrudRouter(resources, { authStrategy }))
+   ```
+
+2. **Declared on the resource (for custom repositories).** A "bare" adapter — `new PrismaAdapter({ delegate })` with no model, or any **non-Prisma** `Repository` (in-memory, an external API, a different ORM) — has no schema to introspect. There, the resource's `fields` array **is** the schema, and it is required. This is the only situation where you hand-write `fields`, and it's the price of Halifax not having a model to read.
+
+**Rule of thumb:** for Prisma, prefer `createPrismaResources` (or pass `model` to the adapter) and declare a field only to override it; reach for a hand-written `fields` array only when the repository genuinely has no schema to offer.
+
+## Prisma 6 (also supported)
+
+Halifax's `peerDependencies` allow `@prisma/client >=6.0.0`, so it runs on **Prisma 6 or Prisma 7**. `PrismaAdapter` is database- and version-agnostic: it imports nothing from `@prisma/client` and only calls standard model-delegate methods (`findMany`, `findUnique`, `findFirst`, `create`, `createMany`, `update`, `updateMany`, `delete`, `deleteMany`, `upsert`, `count`) that behave identically across both majors. **You** construct the client and pass `prisma.<model>` as the `delegate` — Halifax never touches the parts that differ between the versions.
+
+> **Caveats.** Halifax's CI matrix exercises **Prisma 7 only** — Prisma 6 is supported on the strength of that stable delegate surface, not a dedicated CI leg, so treat it as best-effort and pin/test your own app against it. Prisma 7 is the recommended path; the main reason to stay on (or drop to) Prisma 6 today is **MongoDB**, which Prisma 7 does not yet support. When Prisma 7 restores MongoDB, prefer upgrading over remaining on 6.
+
+What you implement differently on Prisma 6 (everything below is your project's Prisma setup — no Halifax code changes):
+
+| Concern            | Prisma 7 (shown above)                                           | Prisma 6                                                                                   |
+| ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Datasource `url`   | Forbidden in `schema.prisma`; lives in `prisma.config.ts`        | `url = env("DATABASE_URL")` goes **back in the `datasource` block**                        |
+| `prisma.config.ts` | Required (CLI reads the url from it)                             | Not used — the CLI reads the url from the schema                                           |
+| Runtime client     | **Must** pass a driver adapter (`new PrismaClient({ adapter })`) | Plain `new PrismaClient()` works (built-in engine); driver adapters are opt-in (see below) |
+| Driver adapters    | Default, no flag                                                 | Behind `previewFeatures = ["driverAdapters"]` in the `generator` block, if you want them   |
+| MongoDB            | Not supported                                                    | **Supported** via the built-in connector — `new PrismaClient()`, `provider = "mongodb"`    |
+
+A minimal Prisma 6 setup (engine-based client, no adapter):
+
+```prisma
+// prisma/schema.prisma  (Prisma 6)
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+}
+```
+
+```ts
+// src/db.ts  (Prisma 6 — no driver adapter needed)
+import { PrismaClient } from '@prisma/client'
+
+export const prisma = new PrismaClient()
+```
+
+```ts
+// MongoDB on Prisma 6 — ObjectId keys; Halifax's :id validation already accepts them
+model Post {
+  id    String @id @default(auto()) @map("_id") @db.ObjectId
+  title String
+}
+```
+
+From there, the `PrismaAdapter` usage (`new PrismaAdapter({ delegate: prisma.post })`) and everything else in this guide is identical.
+
 ## Supported Databases
 
 The **same `PrismaAdapter`** works with every database Prisma supports — there is no adapter-per-database. All CRUD and the query builder compile to portable Prisma Client calls, so behaviour is identical across engines. To switch databases you change only the Prisma `provider` and driver adapter:
@@ -167,11 +240,10 @@ The **same `PrismaAdapter`** works with every database Prisma supports — there
 | MySQL / MariaDB | `mysql`           | `@prisma/adapter-mariadb`        |
 | SQL Server      | `sqlserver`       | `@prisma/adapter-mssql`          |
 | SQLite          | `sqlite`          | `@prisma/adapter-better-sqlite3` |
-| MongoDB         | `mongodb`         | _(built-in connector)_           |
 
-The integration suite runs unchanged against PostgreSQL, MySQL, and SQLite in CI to keep this honest; the others use the same harness (`HALIFAX_DB=<db>`).
+The integration suite runs unchanged against **all six** engines in CI — PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, and SQLite, one matrix leg each (`HALIFAX_DB=<db>`) — so the "behaviour is identical across engines" claim is enforced, not asserted.
 
-**MongoDB note.** Mongo keys are 24-character `ObjectId` strings (`@id @default(auto()) @map("_id") @db.ObjectId`). Halifax's `:id` route validation accepts integers, UUIDs, **and** ObjectIds, so id-based routes work on Mongo out of the box.
+**MongoDB note.** MongoDB is absent from the table above because **Prisma 7 dropped its MongoDB connector** (it's "coming soon" in v7) — and the table/CI matrix target Prisma 7. MongoDB still works **on Prisma 6**, which Halifax also supports (see the Prisma 6 section above) — Mongo keys are 24-character `ObjectId` strings (`@id @default(auto()) @map("_id") @db.ObjectId`), and Halifax's `:id` route validation already accepts integers, UUIDs, **and** ObjectIds, so id-based routes work on Mongo out of the box. The forward-ready `schema.mongodb.prisma` and an ObjectId-aware integration suite rejoin the CI matrix unchanged the moment Prisma 7 supports MongoDB again.
 
 ## Targeting database Views
 
@@ -183,9 +255,6 @@ const activeUsersResource: ResourceDefinition = {
   routePrefix: 'active-users',
   fields: [{ name: 'id' }, { name: 'email', filterable: true }],
   permissions: {
-    allowReadOne: true,
-    allowReadMany: true,
-    allowReadManyWithQueryBuilder: true,
     allowCreate: false,
     allowUpdateOne: false,
     allowUpdateMany: false,

package/dist/adapters/http/ExpressAdapter.d.ts

@@ -1,17 +1,46 @@
-import type { Express } from 'express';
+import type { Request, Response } from 'express';
 import { Router } from 'express';
 import type { HttpMethod, HttpRouteHandler, HttpServer } from '../../core/types.js';
 import { type CrudApiOptions } from '../../core/crudRouter.js';
 import type { ResourceDefinition } from '../../core/types.js';
-/** Adapts an Express `App` or `Router` to Halifax's {@link HttpServer} interface. */
+/** A route-registration method as exposed by an Express app or router (e.g. `app.get`). */
+type ExpressRouteRegistrar = (path: string, handler: (req: Request, res: Response) => void) => void;
+/**
+ * The minimal slice of an Express application or router that Halifax actually drives.
+ *
+ * Typing against this structural interface — rather than importing the concrete `Express`
+ * type from a specific `@types/express` major — is what lets {@link ExpressHttpServer}
+ * accept an Express **4** or **5** app/router interchangeably: both versions structurally
+ * satisfy it, and the published `.d.ts` no longer pins consumers to one `@types/express`
+ * version. The route methods (`get`/`post`/.../`all`) and `listen` are present and
+ * signature-compatible across both majors.
+ */
+export interface ExpressAppLike {
+    get: ExpressRouteRegistrar;
+    post: ExpressRouteRegistrar;
+    put: ExpressRouteRegistrar;
+    patch: ExpressRouteRegistrar;
+    delete: ExpressRouteRegistrar;
+    all: ExpressRouteRegistrar;
+    /** Present on an `App` but not a `Router`; when absent, {@link ExpressHttpServer.start} is a no-op. */
+    listen?: (port: number, host: string | undefined, callback: () => void) => unknown;
+}
+/**
+ * Adapts an Express `App` or `Router` to Halifax's {@link HttpServer} interface.
+ *
+ * Works with both Express 4 and Express 5 — the adapter only uses the route methods,
+ * `listen`, and the request/response surface that are identical across both majors, and
+ * every route path it registers uses plain segments and `:id` named params (never `*`
+ * path wildcards), so it sidesteps the Express 5 `path-to-regexp` routing-syntax change.
+ */
 export declare class ExpressHttpServer implements HttpServer {
     private readonly app;
     /**
-     * @param app - Express application or router to register routes on.
+     * @param app - Express application or router to register routes on (Express 4 or 5).
      *   When an `App` is provided, `start()` will call `listen()`.
      *   When a `Router` is provided, `start()` is a no-op.
      */
-    constructor(app: Express | Router);
+    constructor(app: ExpressAppLike);
     /**
      * Registers a route on the Express app for the given method and path.
      * @param method - HTTP method (or `'*'` to register a catch-all via `app.all`).
@@ -37,4 +66,4 @@ export type ExpressCrudRouterOptions = CrudApiOptions;
  * @returns An Express `Router` ready to mount with `app.use('/api', router)`.
  */
 export declare function createExpressCrudRouter(resources: ResourceDefinition[], options?: ExpressCrudRouterOptions): Router;
-//# sourceMappingURL=ExpressAdapter.d.ts.map
+export {};