@edium/halifax 1.0.0

package/README_CACHE.md

@@ -0,0 +1,164 @@
+# Caching
+
+Halifax can serve reads from a **pluggable read-through cache**. It sits at the repository
+layer — _below_ the router's auth checks — so every request is still authenticated and
+authorized; only the database round-trip is skipped. Writes automatically invalidate the
+cache, and clients can force a refresh with a header.
+
+- **Read-through**: `getOne`, `getMany`, and the query-builder route are cached.
+- **Auto-invalidation**: any write (`create`/`update`/`upsert`/`delete`, single or bulk) to a
+  resource instantly invalidates that resource's cached reads.
+- **Tenant-safe**: cache keys embed the tenant scope, so one tenant can never read another's
+  cached rows.
+- **Pluggable store**: in-memory by default; ship a Redis (or any) store by implementing a
+  tiny interface.
+- **Never-expire** option and a **cache-bust header** for on-demand refresh.
+
+## Enabling caching
+
+Turn it on per-resource, or set an API-wide default. Per-resource config wins.
+
+```ts
+import { createExpressCrudRouter, InMemoryCacheStore } from '@edium/halifax'
+
+// Per-resource:
+const countryResource: ResourceDefinition = {
+  name: 'Country',
+  routePrefix: 'countries',
+  fields: [{ name: 'id' }, { name: 'name', filterable: true }],
+  cache: { ttlSeconds: 300 }, // cache reads for 5 minutes
+  repository: countryRepo
+}
+
+// …or an API-wide default applied to every resource:
+createExpressCrudRouter([countryResource, postResource], {
+  cache: { ttlSeconds: 60 }
+})
+```
+
+| Setting                    | Meaning                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------ |
+| `cache: { ttlSeconds: N }` | Cache reads for `N` seconds (per resource).                                    |
+| `cache: { ttlSeconds: 0 }` | **Never expire** — cache forever (until a write invalidates it).               |
+| `cache: false`             | Disable caching for this resource even when an API-wide default is set.        |
+| _(omitted)_                | Inherit the API-wide `cache.ttlSeconds` default, if any; otherwise no caching. |
+
+### Lookup tables (a common use case)
+
+Reference/lookup tables — countries, categories, currencies — are read constantly and change
+rarely, so they are the ideal cache target. Cache them **forever** and let writes invalidate:
+
+```ts
+const categoryResource: ResourceDefinition = {
+  name: 'Category',
+  routePrefix: 'categories',
+  fields: [{ name: 'id' }, { name: 'name', filterable: true, writable: true }],
+  cache: { ttlSeconds: 0 }, // never expire — refreshed only when a category is written
+  repository: categoryRepo
+}
+```
+
+## In-memory store (default)
+
+When you enable caching without supplying a store, Halifax uses an in-process
+`InMemoryCacheStore`. It's perfect for a single instance and for tests, with no dependencies:
+
+```ts
+import { createExpressCrudRouter, InMemoryCacheStore } from '@edium/halifax'
+
+createExpressCrudRouter(resources, {
+  cache: { ttlSeconds: 60, store: new InMemoryCacheStore() } // store is optional here
+})
+```
+
+> For multi-instance deployments use a shared store (below) so the cache and its invalidation
+> are consistent across processes.
+
+## Redis store
+
+`RedisCacheStore` wraps any Redis client matching a tiny duck-typed interface
+(`get` / `set(key, value, { EX })` / `del`) — the [`redis`](https://www.npmjs.com/package/redis)
+v4 client matches it directly, so Halifax doesn't depend on a specific Redis package.
+
+```ts
+import { createClient } from 'redis'
+import { createExpressCrudRouter, RedisCacheStore } from '@edium/halifax'
+
+const redis = createClient({ url: process.env.REDIS_URL })
+await redis.connect()
+
+createExpressCrudRouter(resources, {
+  cache: {
+    ttlSeconds: 300,
+    store: new RedisCacheStore(redis, { keyPrefix: 'halifax:' }) // keyPrefix is optional
+  }
+})
+```
+
+Values are JSON-serialised; a TTL of `0` stores the key with no Redis expiry (never-expire).
+The optional `keyPrefix` namespaces a shared Redis instance.
+
+## Busting the cache (force refresh)
+
+A client can bypass the cache for a single request with a header. By default Halifax honours
+the standard **`Cache-Control: no-cache`** (or `no-store`) request header:
+
+```bash
+curl https://api.example.com/api/countries -H 'Cache-Control: no-cache'
+```
+
+That request reads fresh from the database **and** repopulates the cache, so subsequent
+requests are fast again. Writes still invalidate the cache on their own — busting is only for
+on-demand reads.
+
+Use a custom header instead via `cache.bustHeader`; with a custom header, the cache busts
+whenever the header is present with any non-empty value:
+
+```ts
+createExpressCrudRouter(resources, {
+  cache: { ttlSeconds: 60, bustHeader: 'X-Cache-Bust' }
+})
+```
+
+```bash
+curl https://api.example.com/api/countries -H 'X-Cache-Bust: 1'
+```
+
+## How invalidation works
+
+Each resource (per tenant) has a version counter in the store. Cached read keys embed the
+current version; a write bumps the version, so all previously-cached reads for that
+resource/tenant are instantly unreachable and fall out by TTL. There is no key scanning, which
+keeps invalidation cheap on Redis.
+
+## Custom store
+
+Implement the `CacheStore` interface to back the cache with anything (Memcached, a CDN KV,
+etc.):
+
+```ts
+import type { CacheStore } from '@edium/halifax'
+
+class MyCacheStore implements CacheStore {
+  async get(key: string): Promise<unknown> {
+    /* … */
+  }
+  async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
+    /* TTL of 0/undefined = no expiry */
+  }
+  async delete(key: string): Promise<void> {
+    /* … */
+  }
+}
+```
+
+You can also wrap a repository directly with `createCachingRepository(repo, { store, ttlSeconds, namespace })`
+if you need caching outside the HTTP layer.
+
+## Testing
+
+- **Unit** (`pnpm test:unit`) — `InMemoryCacheStore`, the caching decorator, and the
+  `Cache-Control` header wiring are covered with no external services.
+- **Integration** (`pnpm test:integration`) — a Redis-backed lookup-table scenario runs
+  against a real Redis container (set `REDIS_URL`), proving cache hits, never-expire, key
+  presence, header busting, and write invalidation. CI runs it on a `redis:7` service.

package/README_HTTP_ADAPTERS.md

@@ -0,0 +1,309 @@
+# HTTP Adapters
+
+Halifax's HTTP layer is swappable. Every transport implements the same interface:
+
+```ts
+interface HttpServer {
+  registerRoute(method: string, path: string, handler: HttpHandler): void
+  start(port: number, host?: string): Promise<void> | void
+}
+```
+
+Halifax ships **four** first-party adapters. They are interchangeable: every adapter
+produces the same routes, status codes, error-body shape (`{ errors: [{ code, message }] }`),
+`Allow`/`X-Correlation-ID` headers, content negotiation (406/415), and method-not-allowed
+(405) behaviour. Switching frameworks does not require any change to your resource
+definitions, auth strategy, or query logic.
+
+| Framework        | Import path                       | Factory                           | Mount style                        |
+| ---------------- | --------------------------------- | --------------------------------- | ---------------------------------- |
+| Express 4 / 5    | `@edium/halifax/express`          | `createExpressCrudRouter`         | `app.use('/api', router)`          |
+| Fastify          | `@edium/halifax/fastify`          | `createFastifyCrudPlugin`         | `app.register(plugin, { prefix })` |
+| HyperExpress     | `@edium/halifax/hyper-express`    | `createHyperExpressCrudRouter`    | `app.use('/api', router)`          |
+| Ultimate Express | `@edium/halifax/ultimate-express` | `createUltimateExpressCrudRouter` | `app.use('/api', router)`          |
+
+Each adapter is published as its own subpath entry point, so you only ever load the
+framework you actually use — the others are optional peer dependencies and are never
+imported unless you import their subpath.
+
+> **A note on routing parity.** Express, HyperExpress, and Ultimate Express all use the
+> same `:id` named-parameter routing and `app.all` / `app.any` catch-all, so behaviour is
+> identical. Fastify uses a radix-tree router (static segments beat parameters) rather than
+> registration order; the adapter compensates so all documented CRUD, 404, 400, 405, 406,
+> and 415 behaviour matches the others exactly. The only observable difference is for
+> contrived paths that collide a static segment with `:id` (e.g. `GET /posts/query`),
+> which is not a real-world CRUD scenario.
+
+---
+
+## Express Adapter
+
+Works seamlessly with both **Express 4 and Express 5** — the same code runs unchanged on
+either major.
+
+### Install
+
+```bash
+# Express 5
+pnpm add @edium/halifax express
+pnpm add -D @types/express
+
+# …or Express 4 — equally supported
+pnpm add @edium/halifax express@4
+pnpm add -D @types/express@4
+```
+
+### `createExpressCrudRouter`
+
+Returns a standard Express `Router` that you mount wherever you like.
+
+```ts
+import express from 'express'
+import { createExpressCrudRouter } from '@edium/halifax/express'
+import { authStrategy } from './auth.js'
+import { postResource } from './resources/post.js'
+
+export function createApp() {
+  const app = express()
+  app.use(express.json())
+  app.use('/api/v1', createExpressCrudRouter([postResource], { authStrategy }))
+  return app
+}
+```
+
+#### Options
+
+All four factories accept the same options object:
+
+| Option             | Type                                   | Description                                                 |
+| ------------------ | -------------------------------------- | ----------------------------------------------------------- |
+| `authStrategy`     | `AuthStrategy`                         | Auth strategy applied to every route (default: `AllowAll`)  |
+| `tenant`           | `TenantOptions`                        | Multi-tenant isolation config (see README_MULTITENANCY.md)  |
+| `queryBuilderPath` | `string`                               | Path segment for the query-builder route (default: `query`) |
+| `cache`            | `{ store?, ttlSeconds?, bustHeader? }` | Read-through caching (see README_CACHE.md)                  |
+
+### `ExpressHttpServer` (lower-level)
+
+```ts
+import { ExpressHttpServer } from '@edium/halifax/express'
+import { registerCrudApi } from '@edium/halifax'
+
+const server = new ExpressHttpServer(app)
+registerCrudApi(server, [postResource], { authStrategy })
+server.start(3000)
+```
+
+---
+
+## Fastify Adapter
+
+Fastify's mounting mechanism is plugins-with-prefixes rather than mountable routers, so
+the idiomatic equivalent of `createExpressCrudRouter` is a **plugin**.
+
+### Install
+
+```bash
+pnpm add @edium/halifax fastify
+```
+
+### `createFastifyCrudPlugin`
+
+```ts
+import Fastify from 'fastify'
+import { createFastifyCrudPlugin } from '@edium/halifax/fastify'
+import { authStrategy } from './auth.js'
+import { postResource } from './resources/post.js'
+
+const app = Fastify()
+await app.register(createFastifyCrudPlugin([postResource], { authStrategy }), {
+  prefix: '/api/v1'
+})
+await app.listen({ port: 3000 })
+```
+
+Fastify parses JSON request bodies automatically — no body-parser registration is needed.
+The adapter installs a catch-all content-type parser inside its plugin scope so non-JSON
+payloads produce Halifax's structured `415` rather than Fastify's default error page.
+
+### `FastifyHttpServer` (lower-level)
+
+```ts
+import Fastify from 'fastify'
+import { FastifyHttpServer } from '@edium/halifax/fastify'
+import { registerCrudApi } from '@edium/halifax'
+
+const app = Fastify()
+registerCrudApi(new FastifyHttpServer(app), [postResource], { authStrategy })
+await app.listen({ port: 3000 })
+```
+
+---
+
+## HyperExpress Adapter
+
+[HyperExpress](https://github.com/kartikk221/hyper-express) is a high-performance,
+Express-flavoured framework built on uWebSockets.js.
+
+### Install
+
+```bash
+pnpm add @edium/halifax hyper-express
+```
+
+### `createHyperExpressCrudRouter`
+
+```ts
+import HyperExpress from 'hyper-express'
+import { createHyperExpressCrudRouter } from '@edium/halifax/hyper-express'
+import { authStrategy } from './auth.js'
+import { postResource } from './resources/post.js'
+
+const server = new HyperExpress.Server()
+server.use('/api/v1', createHyperExpressCrudRouter([postResource], { authStrategy }))
+await server.listen(3000)
+```
+
+No body-parsing middleware is required: the adapter downloads and parses the JSON body for
+you (and leaves non-JSON bodies unparsed so the router can return the structured `415`).
+
+### `HyperExpressHttpServer` (lower-level)
+
+```ts
+import HyperExpress from 'hyper-express'
+import { HyperExpressHttpServer } from '@edium/halifax/hyper-express'
+import { registerCrudApi } from '@edium/halifax'
+
+const server = new HyperExpress.Server()
+registerCrudApi(new HyperExpressHttpServer(server), [postResource], { authStrategy })
+await server.listen(3000)
+```
+
+---
+
+## Ultimate Express Adapter
+
+[Ultimate Express](https://github.com/dimdenGD/ultimate-express) is a drop-in
+reimplementation of the Express API on top of uWebSockets.js. Usage is identical to the
+Express adapter.
+
+### Install
+
+```bash
+pnpm add @edium/halifax ultimate-express
+```
+
+### `createUltimateExpressCrudRouter`
+
+```ts
+import express from 'ultimate-express'
+import { createUltimateExpressCrudRouter } from '@edium/halifax/ultimate-express'
+import { authStrategy } from './auth.js'
+import { postResource } from './resources/post.js'
+
+const app = express()
+app.use(express.json())
+app.use('/api/v1', createUltimateExpressCrudRouter([postResource], { authStrategy }))
+app.listen(3000)
+```
+
+### `UltimateExpressHttpServer` (lower-level)
+
+```ts
+import express from 'ultimate-express'
+import { UltimateExpressHttpServer } from '@edium/halifax/ultimate-express'
+import { registerCrudApi } from '@edium/halifax'
+
+const app = express()
+registerCrudApi(new UltimateExpressHttpServer(app), [postResource], { authStrategy })
+app.listen(3000)
+```
+
+> **Note** — `ultimate-express` and `hyper-express` depend on `uWebSockets.js`, which is
+> distributed only as a git repository (not on the npm registry). If your package manager
+> blocks "exotic" git sub-dependencies (pnpm does by default), allow them — this repo's
+> `.npmrc` sets `block-exotic-subdeps=false` for exactly this reason.
+
+---
+
+## With Passport
+
+If you are using `PassportJwtStrategy` with Express or Ultimate Express, initialize
+Passport before mounting the router:
+
+```ts
+import passport from 'passport'
+
+app.use(passport.initialize())
+app.use('/api/v1', createExpressCrudRouter([postResource], { authStrategy }))
+```
+
+---
+
+## Implementing a Custom HTTP Adapter
+
+To support any other framework, implement `HttpServer`. The contract is small: map the
+framework's request/response onto Halifax's `HttpRequest` / `HttpResponse`, route `'*'` to
+the framework's "any method" handler (for 405 fallbacks), and make `start()` listen.
+
+```ts
+import type { HttpServer, HttpRouteHandler, HttpMethod } from '@edium/halifax'
+import { registerCrudApi } from '@edium/halifax'
+
+class MyAdapter implements HttpServer {
+  constructor(private app: MyFramework) {}
+
+  registerRoute(method: HttpMethod, path: string, handler: HttpRouteHandler) {
+    const run = (req, res) =>
+      handler(
+        {
+          method: req.method,
+          params: req.params,
+          query: req.query,
+          body: req.body,
+          headers: req.headers,
+          raw: req
+        },
+        {
+          raw: res,
+          status(code) {
+            res.statusCode = code
+            return this
+          },
+          json(payload) {
+            res.json(payload)
+          },
+          send(payload) {
+            res.send(payload)
+          },
+          setHeader(name, value) {
+            res.setHeader(name, value)
+          }
+        }
+      )
+    if (method === '*') this.app.any(path, run)
+    else this.app[method.toLowerCase()](path, run)
+  }
+
+  async start(port: number, host?: string) {
+    await this.app.listen(port, host)
+  }
+}
+
+registerCrudApi(new MyAdapter(app), [postResource], { authStrategy })
+```
+
+The four first-party adapters in `src/adapters/http/` are the best reference
+implementations — each is a small, self-contained file.
+
+---
+
+## Testing
+
+Every adapter is verified against a single shared **Express-parity contract**
+(`tests/helpers/adapterContract.ts`): the identical set of HTTP assertions is run against
+all frameworks so "behaves exactly like Express" is enforced by construction.
+
+- **Unit** (`pnpm test:unit`) — runs the contract against each adapter with an in-memory
+  repository; no database required.
+- **Integration** (`pnpm test:integration`) — runs a Prisma + PostgreSQL HTTP contract
+  against each adapter. Requires `DATABASE_URL` in `.env.test`; skipped when unset.

package/README_MULTITENANCY.md

@@ -0,0 +1,162 @@
+# Multi-Tenancy
+
+Halifax can confine every generated endpoint to a single tenant — a company, organization,
+workspace, or any row-ownership boundary — so that one customer can never read or write
+another customer's data through the API. Tenant isolation is **optional**, **opt-in**, and
+enforced at the data-access layer where it cannot be bypassed by crafted query strings or
+request bodies.
+
+## How it works
+
+Two pieces combine to produce a per-request constraint:
+
+1. **The tenant field** — a column on the model that stores the tenant key (e.g. `companyId`).
+   Declared per-resource via `ResourceDefinition.tenant`, or auto-detected (see below).
+2. **The tenant value** — the key the _current caller_ is bound to (e.g. their `company.id`).
+   Produced per-request by `tenant.resolveId(ctx)`, which reads it from the authenticated
+   session/token — **never** from client-supplied input.
+
+For each request, Halifax resolves the value and asks the repository for a **scoped clone**
+(`repository.withScope({ field, value })`). That clone applies the constraint to every
+operation:
+
+| Operation                              | What the scope does                                                               |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| `GET /resource` (list & query-builder) | AND-s `field = value` into the `WHERE` (and the count)                            |
+| `GET /resource/:id`                    | Reads via `findFirst` with the tenant filter → foreign rows return `404`          |
+| `POST /resource`                       | **Stamps** `field = value` onto the body, overriding any client-supplied value    |
+| `PATCH /resource/:id`                  | Verifies ownership first; **strips** the tenant field so rows can't change owners |
+| `PATCH /resource` (updateMany)         | AND-s the tenant filter into the `WHERE`; strips the tenant field from the `SET`  |
+| `PUT /resource/:id` (upsert)           | Refuses to overwrite a row owned by another tenant (`404`); stamps on create      |
+| `DELETE /resource/:id`                 | Deletes via a scoped `deleteMany` → foreign rows report "not found"               |
+| `DELETE /resource` (deleteMany)        | AND-s the tenant filter into the `WHERE`                                          |
+
+## Quick start
+
+```ts
+import express from 'express'
+import { PrismaClient } from '@prisma/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+import {
+  createPrismaResources,
+  createExpressCrudRouter,
+  PassportSessionStrategy
+} from '@edium/halifax'
+import { Prisma } from '@prisma/client'
+
+const prisma = new PrismaClient({ adapter: new PrismaPg(process.env.DATABASE_URL!) })
+
+// Generate resources for every model; mark any model that has a `companyId` column
+// as tenant-scoped on it.
+const resources = createPrismaResources(prisma, Prisma.dmmf.datamodel.models, {
+  tenantField: 'companyId'
+})
+
+const app = express()
+app.use(express.json())
+// ...session + passport middleware run before Halifax...
+
+app.use(
+  '/api/v3',
+  createExpressCrudRouter(resources, {
+    authStrategy: new PassportSessionStrategy(),
+    tenant: {
+      // Derive the tenant key from the authenticated session — never from the request body.
+      resolveId: ({ req }) => (req.raw as any).session?.company?.id ?? null
+    }
+  })
+)
+```
+
+That's the whole integration: one `tenantField` to auto-detect scoped models, and one
+`resolveId` to supply the caller's tenant. Models without a `companyId` column are left
+global (unscoped) automatically.
+
+## Configuration
+
+### API-level: `tenant` on `CrudApiOptions`
+
+```ts
+interface TenantOptions {
+  /** Resolve the caller's tenant key from the authenticated request. */
+  resolveId: (ctx: { auth; req; resource }) => unknown | Promise<unknown>
+  /** Default column to auto-detect scoping on. Defaults to 'tenantId'. */
+  field?: string
+  /** Fail-closed when no tenant resolves. Defaults to true. */
+  strict?: boolean
+}
+```
+
+> `resolveId` runs **after** authentication, so `ctx.auth` is the resolved `AuthContext`
+> and `ctx.req.raw` is the underlying framework request (e.g. the Express `Request`, with
+> `session` / `user` populated). Pull the tenant from there.
+
+### Resource-level: `tenant` on `ResourceDefinition`
+
+| Value            | Meaning                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| `{ field: 'x' }` | Scope this resource on column `x`.                                                          |
+| `false`          | Opt this resource **out** of an otherwise tenant-scoped API.                                |
+| _omitted_        | Auto-scope on the API's default `field` **if** the model has that column; otherwise global. |
+
+When generating with `createPrismaResources`, set it per model:
+
+```ts
+createPrismaResources(prisma, models, {
+  tenantField: 'companyId',
+  models: {
+    // Override the column for one model:
+    Invoice: { tenant: { field: 'orgId' } },
+    // Expose a global reference table to all tenants:
+    Country: { tenant: false }
+  }
+})
+```
+
+## Security model
+
+Tenant scoping is designed to **fail closed**. The guarantees:
+
+- **Enforced at the data layer.** The constraint is applied inside the repository on every
+  read, write, and bulk operation — not as middleware a route could skip.
+- **Server-derived value only.** The tenant value comes from `resolveId` (your auth/session),
+  never from the URL, query string, or body. A client-supplied `?companyId=` or a `companyId`
+  in the body is **overridden** (writes) or **AND-ed against** (reads), so it cannot widen access.
+- **No `OR` escape in the query builder.** Caller-supplied filters are nested as a
+  parenthesised group AND-ed beneath the tenant predicate — `companyId = $1 AND ( ...your filters... )`
+  — so an `OR` in the advanced query can never break out of the tenant boundary.
+- **Rows can't change owners.** The tenant field is stripped from update/upsert payloads.
+- **Cross-tenant rows are invisible.** Reads/updates/deletes of another tenant's row behave
+  as "not found" (`404`/no-op), never leaking existence.
+- **Misconfiguration is fatal, not silent.** If a resource is tenant-scoped but its repository
+  doesn't implement `withScope`, `createExpressCrudRouter` throws at startup rather than
+  serving the resource unscoped.
+- **Strict by default.** If `resolveId` returns `null`/`undefined` for a scoped resource, the
+  request is rejected with `403`. Set `strict: false` only to deliberately allow cross-tenant
+  ("god mode") access for callers with no tenant.
+
+### Defense in depth
+
+API-level scoping does not replace database-level controls. For a hard guarantee even against
+bugs elsewhere in your stack, pair Halifax scoping with PostgreSQL **Row-Level Security**
+policies keyed on the same tenant column.
+
+### What is _not_ scoped
+
+Relations eager-loaded via `?include=` are returned as Prisma resolves them; if a related
+model also needs isolation, expose it as its own scoped resource rather than relying on the
+include.
+
+## Custom repositories
+
+Any repository can support scoping by implementing the optional `withScope` method, which must
+return a **new** instance bound to the scope (never mutate the original):
+
+```ts
+withScope(scope: TenantScope): Repository<...> {
+  return new MyRepository({ ...this.options, scope })
+}
+```
+
+`PrismaAdapter` implements this for you. A repository that omits `withScope` simply cannot be
+used for a tenant-scoped resource — the router refuses to register it, by design.