@edium/halifax 2.0.0 → 2.2.0

package/README_OPENAPI.md

@@ -0,0 +1,471 @@
+# OpenAPI Support
+
+Halifax can automatically generate a complete [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) specification from your registered resources — no manual annotation required. For Prisma-backed resources, field types are introspected directly from the DMMF schema. For custom repositories, you can optionally annotate individual fields.
+
+Two routes are added automatically at your mount point:
+
+| Route               | Description                                 |
+| ------------------- | ------------------------------------------- |
+| `GET /openapi.json` | Raw OpenAPI 3.1 spec (JSON)                 |
+| `GET /docs`         | Swagger UI — interactive browser-based docs |
+
+---
+
+## Quick start
+
+```ts
+import { createExpressCrudRouter } from '@edium/halifax'
+
+app.use(
+  '/api/v1',
+  createExpressCrudRouter(resources, {
+    openapi: {
+      title: 'My API',
+      version: '1.0.0',
+      servers: [{ url: 'https://api.example.com/v1' }]
+    }
+  })
+)
+```
+
+Then visit:
+
+- **http://localhost:3000/api/v1/docs** — Swagger UI
+- **http://localhost:3000/api/v1/openapi.json** — raw spec
+
+---
+
+## Enabling only in non-production environments
+
+Use the `enabled` flag to gate docs behind an environment check:
+
+```ts
+openapi: {
+  enabled: process.env.NODE_ENV !== 'production',
+  title: 'My API',
+  version: '1.0.0'
+}
+```
+
+When `enabled` is `false` (or the `openapi` key is omitted entirely), no extra routes are registered and the spec generator is never called — zero overhead in production.
+
+### Recommended environment pattern
+
+```ts
+const openApiConfig =
+  process.env.ENABLE_DOCS === 'true'
+    ? {
+        title: 'My API',
+        version: '1.0.0',
+        servers: [{ url: `${process.env.BASE_URL}/api/v1` }]
+      }
+    : undefined
+
+app.use(
+  '/api/v1',
+  createExpressCrudRouter(resources, {
+    openapi: openApiConfig
+  })
+)
+```
+
+Set `ENABLE_DOCS=true` in `.env.development`, `.env.test`, and `.env.staging`. Leave it unset (or `false`) in production.
+
+---
+
+## All options
+
+```ts
+interface OpenApiOptions {
+  enabled?: boolean // default: true when object is present
+  title?: string // default: 'Halifax API'
+  version?: string // default: '1.0.0'
+  description?: string // markdown supported
+  servers?: Array<{ url: string; description?: string }>
+  envelope?: string | null // mirrors CrudApiOptions.envelope — auto-propagated
+  specPath?: string // default: '/openapi.json'
+  docsPath?: string // default: '/docs'
+}
+```
+
+### Custom paths
+
+```ts
+openapi: {
+  specPath: '/spec/openapi.json',
+  docsPath: '/api-reference'
+}
+// → GET /api/v1/spec/openapi.json
+// → GET /api/v1/api-reference
+```
+
+---
+
+## Type introspection
+
+### Prisma resources (automatic)
+
+When you use `PrismaAdapter` or `createPrismaResources`, Halifax reads the Prisma DMMF and maps types automatically:
+
+| Prisma type | OpenAPI type | Format      |
+| ----------- | ------------ | ----------- |
+| `String`    | `string`     | —           |
+| `Int`       | `integer`    | `int32`     |
+| `BigInt`    | `integer`    | `int64`     |
+| `Float`     | `number`     | `float`     |
+| `Decimal`   | `number`     | `double`    |
+| `Boolean`   | `boolean`    | —           |
+| `DateTime`  | `string`     | `date-time` |
+| `Json`      | `object`     | —           |
+| `Bytes`     | `string`     | `binary`    |
+
+No configuration needed. Types flow through automatically.
+
+### Custom / non-Prisma repositories
+
+Add optional `type` and `format` to any `FieldDefinition`:
+
+```ts
+const orders: ResourceDefinition = {
+  routePrefix: 'orders',
+  repository: myCustomRepo,
+  fields: [
+    { name: 'id', type: 'integer', writable: false },
+    { name: 'total', type: 'number', format: 'double' },
+    { name: 'status', type: 'string' },
+    { name: 'paid', type: 'boolean' },
+    { name: 'createdAt', type: 'string', format: 'date-time', writable: false }
+  ]
+}
+```
+
+Fields without a `type` default to `string`.
+
+---
+
+## Generated endpoints
+
+The spec documents exactly the operations your `permissions` allow. Disabled operations are omitted entirely.
+
+### Collection routes — `/{resource}`
+
+| Method   | Permission flag   | Summary                                    |
+| -------- | ----------------- | ------------------------------------------ |
+| `GET`    | `allowReadMany`   | List records (paginated, filtered, sorted) |
+| `POST`   | `allowCreate`     | Create one or many records                 |
+| `PATCH`  | `allowUpdateMany` | Bulk-update matching records               |
+| `DELETE` | `allowDeleteMany` | Bulk-delete matching records               |
+
+### Item routes — `/{resource}/{id}`
+
+| Method   | Permission flag  | Summary                    |
+| -------- | ---------------- | -------------------------- |
+| `GET`    | `allowReadOne`   | Get one record by ID       |
+| `PATCH`  | `allowUpdateOne` | Partially update a record  |
+| `PUT`    | `allowUpsertOne` | Create or replace a record |
+| `DELETE` | `allowDeleteOne` | Delete a record            |
+
+### Query route — `/{resource}/query`
+
+| Method | Permission flag                 | Summary                |
+| ------ | ------------------------------- | ---------------------- |
+| `POST` | `allowReadManyWithQueryBuilder` | Advanced query builder |
+
+---
+
+## Query string parameters (GET endpoints)
+
+Every list endpoint (`GET /{resource}`) documents the following parameters:
+
+| Parameter           | Type            | Description                                                                            |
+| ------------------- | --------------- | -------------------------------------------------------------------------------------- |
+| `limit`             | integer         | Maximum records to return (capped by `maxLimit`).                                      |
+| `offset`            | integer         | Records to skip for pagination.                                                        |
+| `fields`            | string          | Comma-separated field names to include. Enum of available names is shown.              |
+| `order`             | string          | Sort expression: `field:asc` or `field:desc`, comma-separated. Sortable fields listed. |
+| `include`           | string          | Comma-separated relation names to eager-load. Enum of available names is shown.        |
+| _filterable fields_ | varies          | One query param per filterable field for simple equality filters.                      |
+| `X-Correlation-ID`  | string (header) | Optional. Echoed back in the response header for tracing.                              |
+
+**Example:** `GET /posts?limit=20&offset=0&published=true&order=createdAt:desc&fields=id,title,createdAt`
+
+> For range, LIKE, IN, or OR conditions, use `POST /{resource}/query` instead.
+
+---
+
+## Request / response shapes
+
+### List response (`GET` and `POST .../query`)
+
+```json
+{
+  "count": 42,
+  "results": [{ "id": 1, "title": "Hello", "published": true }]
+}
+```
+
+`count` is the total matching rows before pagination. `results` is the current page.
+
+### Create (`POST /{resource}`)
+
+Send a single object or an array:
+
+```json
+{ "title": "Hello", "published": false }
+```
+
+```json
+[{ "title": "Hello" }, { "title": "World" }]
+```
+
+Returns the created record(s) with HTTP `201`. Supports the `Idempotency-Key` header.
+
+### Update one (`PATCH /{resource}/{id}`)
+
+Partial update — only the fields present in the body are changed:
+
+```json
+{ "published": true }
+```
+
+Returns the updated record with HTTP `200`.
+
+### Upsert (`PUT /{resource}/{id}`)
+
+Create or replace a record at the given ID. Always returns HTTP `200`.
+
+### Bulk update (`PATCH /{resource}`)
+
+The body combines `QueryOptions` fields (to select records) with an `update` key (the fields to set):
+
+```json
+{
+  "where": [{ "field": "status", "comparison": "=", "value": "draft" }],
+  "update": { "status": "archived" }
+}
+```
+
+`where` is **required** (at least one filter) — this prevents accidental full-table updates.
+
+Response: `{ "updated": [<ids>], "results": [<records>] }`
+
+### Bulk delete (`DELETE /{resource}`)
+
+The body is a `QueryOptions` object. `where` is **required**:
+
+```json
+{
+  "where": [{ "field": "deletedAt", "comparison": "IS NOT NULL" }]
+}
+```
+
+Response: `{ "deleted": [<ids or records>] }`
+
+### Delete one (`DELETE /{resource}/{id}`)
+
+Response: `{ "deleted": true }` with HTTP `200`.
+
+---
+
+## POST .../query — advanced query builder
+
+The query builder endpoint accepts a `QueryOptions` body for full-featured filtering:
+
+```json
+{
+  "where": [
+    { "field": "published", "comparison": "=", "value": true },
+    { "field": "createdAt", "comparison": ">=", "value": "2024-01-01T00:00:00Z" },
+    {
+      "operator": "OR",
+      "children": [
+        { "field": "title", "comparison": "CONTAINS", "value": "Halifax" },
+        { "field": "title", "comparison": "STARTS WITH", "value": "Hello" }
+      ]
+    }
+  ],
+  "orderBy": [{ "field": "createdAt", "direction": "desc" }],
+  "limit": 20,
+  "offset": 0,
+  "fields": ["id", "title", "createdAt"],
+  "include": ["author"]
+}
+```
+
+### Supported comparison operators
+
+| Operator          | Description               | Value format        |
+| ----------------- | ------------------------- | ------------------- |
+| `=`               | Equals                    | scalar              |
+| `<>`              | Not equals                | scalar              |
+| `<` `>` `<=` `>=` | Numeric / date comparison | scalar              |
+| `IN`              | In list                   | `[val1, val2, ...]` |
+| `NOT IN`          | Not in list               | `[val1, val2, ...]` |
+| `BETWEEN`         | Inclusive range           | `[min, max]`        |
+| `NOT BETWEEN`     | Outside range             | `[min, max]`        |
+| `LIKE`            | SQL LIKE (`%` wildcard)   | string              |
+| `NOT LIKE`        | SQL NOT LIKE              | string              |
+| `CONTAINS`        | Substring match           | string              |
+| `STARTS WITH`     | Prefix match              | string              |
+| `ENDS WITH`       | Suffix match              | string              |
+| `IS NULL`         | Null check                | _(omit value)_      |
+| `IS NOT NULL`     | Not null check            | _(omit value)_      |
+
+### AND / OR precedence
+
+Flat `where` arrays use **AND-precedence over OR** (same as SQL). Use `children` groups with an `operator` for explicit parenthesisation:
+
+```json
+{
+  "where": [
+    { "field": "active", "comparison": "=", "value": true },
+    {
+      "operator": "OR",
+      "children": [
+        { "field": "role", "comparison": "=", "value": "admin" },
+        { "field": "role", "comparison": "=", "value": "moderator" }
+      ]
+    }
+  ]
+}
+```
+
+Equivalent SQL: `WHERE active = true AND (role = 'admin' OR role = 'moderator')`
+
+---
+
+## Response envelopes
+
+When `envelope` is configured on the router or per-resource, the spec reflects it:
+
+```ts
+createExpressCrudRouter(resources, {
+  envelope: 'data',
+  openapi: { title: 'My API', version: '1.0.0' }
+})
+```
+
+All success response schemas automatically wrap under the envelope key:
+
+```json
+{ "data": { "id": 1, "title": "Hello" } }
+```
+
+Per-resource `envelope` takes precedence over the API-wide default (including `null` to opt out).
+
+---
+
+## Error responses
+
+All error responses share a consistent shape:
+
+```json
+{
+  "errors": [{ "code": "NOT_FOUND", "message": "Not found." }]
+}
+```
+
+### HTTP status codes
+
+| Code  | Meaning                | When raised                                                                      |
+| ----- | ---------------------- | -------------------------------------------------------------------------------- |
+| `400` | Bad Request            | Invalid ID format, malformed query params or body, invalid filter expressions    |
+| `401` | Unauthorized           | Missing or invalid auth credentials                                              |
+| `403` | Forbidden              | Valid credentials but insufficient permissions                                   |
+| `404` | Not Found              | Record with the given ID does not exist                                          |
+| `405` | Method Not Allowed     | HTTP method not enabled for this resource                                        |
+| `406` | Not Acceptable         | Client's `Accept` header excludes `application/json`                             |
+| `415` | Unsupported Media Type | Body-carrying request with non-JSON `Content-Type`                               |
+| `422` | Unprocessable Entity   | Unknown fields in body, missing required filter, empty update payload            |
+| `500` | Internal Server Error  | Unexpected repository or framework error                                         |
+| `501` | Not Implemented        | Repository does not support this operation (e.g. upsert, updateMany, deleteMany) |
+
+---
+
+## Security schemes (Authorize button in Swagger UI)
+
+Halifax automatically reads the security scheme from your `authStrategy` and wires it into the spec. The Swagger UI "Authorize" button appears pre-configured — no extra setup needed.
+
+| Strategy                                   | Scheme documented                                    |
+| ------------------------------------------ | ---------------------------------------------------- |
+| `ApiKeyAuthStrategy`                       | `apiKey` in header (uses the configured header name) |
+| `JwtClaimsAuthStrategy`                    | `http` bearer JWT                                    |
+| `PassportJwtStrategy`                      | `http` bearer JWT                                    |
+| `Auth0JwtStrategy` / `FirebaseJwtStrategy` | `http` bearer JWT                                    |
+| `PassportSessionStrategy`                  | `apiKey` in cookie (`connect.sid`)                   |
+| `AllowAllAuthStrategy` / custom            | No security requirement                              |
+
+### Custom strategy
+
+Implement `openApiScheme()` on your custom strategy and it's picked up automatically:
+
+```ts
+class MyHmacStrategy implements AuthStrategy {
+  async authenticate(req) {
+    /* ... */
+  }
+
+  openApiScheme(): SecurityScheme {
+    return { type: 'apiKey', in: 'header', name: 'X-Signature' }
+  }
+}
+```
+
+### Override without touching the strategy
+
+Pass `securityScheme` directly in `openapi` options to override whatever the strategy reports:
+
+```ts
+openapi: {
+  title: 'My API',
+  securityScheme: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }
+}
+```
+
+---
+
+## Using the spec programmatically
+
+`generateOpenApiSpec` is exported and can be called standalone — no server needed:
+
+```ts
+import { generateOpenApiSpec } from '@edium/halifax'
+
+const spec = generateOpenApiSpec(resources, {
+  title: 'My API',
+  version: '1.0.0'
+})
+
+// Write to disk
+import { writeFileSync } from 'fs'
+writeFileSync('openapi.json', JSON.stringify(spec, null, 2))
+
+// Or pass to a CI validation tool
+import { validate } from '@redocly/openapi-core'
+await validate({ document: spec })
+```
+
+This is useful for:
+
+- **CI spec validation** — catch breaking changes before deploy
+- **Code generation** — pipe into `openapi-typescript`, `@hey-api/openapi-ts`, or `@edium/halifax-codegen`
+- **Static hosting** — publish the spec alongside your deployed API
+
+---
+
+## Frequently asked questions
+
+**Do I need to restart the server to update the spec?**
+No. The spec is generated once at startup from the registered resource definitions. Restart is only needed when you change resource definitions in code.
+
+**Does it work with Fastify / HyperExpress?**
+The `openapi` option is on `CrudApiOptions` which is shared by all HTTP adapters. For non-Express adapters use `registerCrudApi` directly — the spec and docs routes are registered on whatever `HttpServer` adapter you provide.
+
+**Can I add authentication to the docs route?**
+The `/docs` and `/openapi.json` routes bypass your `authStrategy` since they're registered after the resource routes without the auth wrapper. To protect them, mount them behind your own middleware before calling `createExpressCrudRouter`.
+
+**Why does the spec use `results` instead of `data` for list responses?**
+`results` is the field name in Halifax's internal `ListResult` type. The spec accurately reflects what the API actually returns.
+
+**Can I use this spec for client code generation?**
+Yes. Feed `openapi.json` into any OpenAPI generator. Phase 4 of the Halifax roadmap (`@edium/halifax-codegen`) will generate a fully-typed TanStack Query client directly from this spec.

package/README_REPO_ADAPTERS.md

@@ -245,6 +245,83 @@ The integration suite runs unchanged against **all six** engines in CI — Postg
 
 **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.
 
+## Drizzle ORM Adapter
+
+`DrizzleAdapter` implements the full `Repository` interface against any Drizzle-compatible database. It lives behind a sub-path export so `drizzle-orm` is never a hard dependency when unused:
+
+```bash
+pnpm add drizzle-orm
+```
+
+```ts
+import { DrizzleAdapter } from '@edium/halifax/drizzle'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import { usersTable } from './schema'
+
+const db = drizzle(postgres(process.env.DATABASE_URL!))
+
+const usersResource: ResourceDefinition = {
+  routePrefix: 'users',
+  repository: new DrizzleAdapter(db, usersTable)
+  // No `fields` needed — derived automatically from the table schema.
+}
+```
+
+### Supported databases
+
+`DrizzleAdapter` works with any driver Drizzle supports. The commonly used ones:
+
+| Database       | Drizzle driver import        |
+| -------------- | ---------------------------- |
+| PostgreSQL     | `drizzle-orm/postgres-js`    |
+| MySQL          | `drizzle-orm/mysql2`         |
+| SQLite         | `drizzle-orm/better-sqlite3` |
+| LibSQL / Turso | `drizzle-orm/libsql`         |
+
+### Type introspection
+
+`DrizzleAdapter` calls `getTableColumns()` on your table and derives the Halifax field schema automatically — types, primary key, and `writable` flags are all inferred. For OpenAPI generation, Drizzle column types are mapped to their OpenAPI equivalents:
+
+| Drizzle `dataType` | OpenAPI type | Format      |
+| ------------------ | ------------ | ----------- |
+| `string`           | `string`     | —           |
+| `number`           | `number`     | —           |
+| `boolean`          | `boolean`    | —           |
+| `bigint`           | `integer`    | `int64`     |
+| `date`             | `string`     | `date-time` |
+| `json`             | `object`     | —           |
+| `buffer`           | `string`     | `binary`    |
+
+### Constructor options
+
+```ts
+new DrizzleAdapter(db, table, config?, scope?)
+```
+
+| Parameter        | Type                  | Description                                                                                                                                         |
+| ---------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `db`             | Drizzle DB instance   | Any Drizzle-compatible database connection.                                                                                                         |
+| `table`          | Drizzle `Table`       | Your table schema (e.g. `usersTable`).                                                                                                              |
+| `config.idField` | `string` (optional)   | Primary key field name. Defaults to auto-detecting the first column marked `.primaryKey()`. Set explicitly for composite PKs or non-standard names. |
+| `scope`          | `TenantScope \| null` | Tenant scope. Set by `withScope()` internally — do not pass directly.                                                                               |
+
+### Multi-tenancy
+
+`DrizzleAdapter` supports per-resource tenant scoping via `withScope()` exactly like `PrismaAdapter`. See [README_MULTITENANCY.md](./README_MULTITENANCY.md) for how to configure it on the resource.
+
+### Static field derivation
+
+You can derive the field schema without constructing a full adapter instance:
+
+```ts
+import { DrizzleAdapter } from '@edium/halifax/drizzle'
+import { usersTable } from './schema'
+
+const fields = DrizzleAdapter.fieldsFromTable(usersTable)
+// Use as the `fields` array in a ResourceDefinition, or inspect for overrides.
+```
+
 ## Targeting database Views
 
 A database **view is just a model** to Halifax. Prisma exposes a `view` block as a delegate with the same read API as a model (`prisma.activeUsers.findMany()`), so you point a resource's repository at it and disable writes:

package/README_TYPES.md

@@ -0,0 +1,114 @@
+# Types — `@edium/halifax`
+
+All publicly exported TypeScript type aliases, enums, and constants. Interfaces are in [README_INTERFACES.md](./README_INTERFACES.md); classes are in [README_CLASSES.md](./README_CLASSES.md).
+
+---
+
+## Type Aliases
+
+### Core / Resource
+
+| Type               | Import path      | Definition                                                                                                                                       | Description                                                                                                                                |
+| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `CrudAction`       | `@edium/halifax` | `'create' \| 'readOne' \| 'readMany' \| 'readManyWithQueryBuilder' \| 'updateOne' \| 'updateMany' \| 'upsertOne' \| 'deleteOne' \| 'deleteMany'` | Identifies a single CRUD operation. Used in `requiredPermissions` maps and `AuthorizeParams`.                                              |
+| `FieldType`        | `@edium/halifax` | `'string' \| 'integer' \| 'number' \| 'boolean' \| 'object'`                                                                                     | OpenAPI-compatible scalar type for a field. Set on `FieldDefinition.type` for custom repos; auto-populated by Prisma and Drizzle adapters. |
+| `HttpMethod`       | `@edium/halifax` | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| '*'`                                                                                         | HTTP methods supported by Halifax routes. `'*'` is used for 405 catch-all handlers.                                                        |
+| `HttpRouteHandler` | `@edium/halifax` | `(req: HttpRequest, res: HttpResponse) => Promise<void> \| void`                                                                                 | Function signature for framework-agnostic route handlers passed to `HttpServer.registerRoute`.                                             |
+
+### Auth
+
+| Type             | Import path      | Definition                                                                                                               | Description                                                                                                                            |
+| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `SecurityScheme` | `@edium/halifax` | `{ type: 'apiKey'; in: 'header' \| 'query' \| 'cookie'; name: string } \| { type: 'http'; scheme: 'bearer' \| 'basic' }` | OpenAPI 3.1 security scheme descriptor returned by `AuthStrategy.openApiScheme()`. Used to populate the Swagger UI "Authorize" button. |
+
+### Response envelopes
+
+| Type                        | Import path      | Definition                                    | Description                                                                                     |
+| --------------------------- | ---------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `ListResult<TRecord>`       | `@edium/halifax` | `{ count: number; results: TRecord[] }`       | Returned by `getMany` and `executeQuery`. `count` is the total matching rows before pagination. |
+| `QueryResult<TRecord>`      | `@edium/halifax` | `{ count?: number; results: TRecord[] }`      | Returned by `executeQuery` (query-builder endpoint). `count` is optional.                       |
+| `UpdateManyResult<TRecord>` | `@edium/halifax` | `{ updated: unknown[]; results?: TRecord[] }` | Returned by `updateMany`. `updated` is the list of affected IDs.                                |
+| `DeleteManyResult`          | `@edium/halifax` | `{ deleted: unknown[] }`                      | Returned by `deleteMany`. `deleted` is the list of affected IDs.                                |
+
+### Query AST
+
+| Type          | Import path      | Definition                            | Description                                                             |
+| ------------- | ---------------- | ------------------------------------- | ----------------------------------------------------------------------- |
+| `QueryScalar` | `@edium/halifax` | `string \| number \| boolean \| null` | Scalar value accepted by filter comparison operators in `IQueryFilter`. |
+
+### HTTP adapter type aliases
+
+These are aliased to `CrudApiOptions` — documented in [README_INTERFACES.md](./README_INTERFACES.md).
+
+| Type                               | Import path      | Description                                                                                                      |
+| ---------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `ExpressCrudRouterOptions`         | `@edium/halifax` | Alias of `CrudApiOptions`. The options type accepted by `createExpressCrudRouter`.                               |
+| `FastifyCrudPluginOptions`         | `@edium/halifax` | Alias of `CrudApiOptions`. The options type accepted by `createFastifyCrudPlugin`.                               |
+| `FastifyCrudPlugin`                | `@edium/halifax` | `(instance: FastifyAppLike) => Promise<void>`. Type of the Fastify plugin returned by `createFastifyCrudPlugin`. |
+| `HyperExpressCrudRouterOptions`    | `@edium/halifax` | Alias of `CrudApiOptions`. The options type accepted by `createHyperExpressCrudRouter`.                          |
+| `UltimateExpressCrudRouterOptions` | `@edium/halifax` | Alias of `CrudApiOptions`. The options type accepted by `createUltimateExpressCrudRouter`.                       |
+
+### Drizzle sub-path (`@edium/halifax/drizzle`)
+
+| Type           | Import path              | Definition                  | Description                                                                                                                               |
+| -------------- | ------------------------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `AnyDrizzleDB` | `@edium/halifax/drizzle` | `any`                       | A Drizzle database connection of any driver type. Typed as `any` because Drizzle does not export a single unified DB type across drivers. |
+| `ColumnMap`    | `@edium/halifax/drizzle` | `Record<string, AnyColumn>` | Map from column name to Drizzle `AnyColumn`, used internally by the AST compiler. Useful when writing custom Drizzle query extensions.    |
+
+---
+
+## Enums
+
+All three enums are re-exported from `@edium/halifax-types` through the main `@edium/halifax` entry point.
+
+### `SqlComparison`
+
+Comparison operators used in `IQueryFilter.comparison`. Accepted by the query-builder endpoint (`POST /:resource/query`) and `QueryBuilder` methods.
+
+| Value                | Operator      | Notes                     |
+| -------------------- | ------------- | ------------------------- |
+| `Equal`              | `=`           |                           |
+| `NotEqual`           | `<>`          |                           |
+| `LessThan`           | `<`           |                           |
+| `LessThanOrEqual`    | `<=`          |                           |
+| `GreaterThan`        | `>`           |                           |
+| `GreaterThanOrEqual` | `>=`          |                           |
+| `In`                 | `IN`          | `value1` must be an array |
+| `NotIn`              | `NOT IN`      | `value1` must be an array |
+| `Between`            | `BETWEEN`     | Use `value1` and `value2` |
+| `NotBetween`         | `NOT BETWEEN` | Use `value1` and `value2` |
+| `Like`               | `LIKE`        | `%` wildcard              |
+| `NotLike`            | `NOT LIKE`    |                           |
+| `Contains`           | `CONTAINS`    | Substring match           |
+| `StartsWith`         | `STARTS WITH` | Prefix match              |
+| `EndsWith`           | `ENDS WITH`   | Suffix match              |
+| `IsNull`             | `IS NULL`     | Omit `value1`             |
+| `IsNotNull`          | `IS NOT NULL` | Omit `value1`             |
+
+### `SqlOperator`
+
+Logical operator that joins a filter condition to the next sibling condition in a `where` array.
+
+| Value | Description                                  |
+| ----- | -------------------------------------------- |
+| `And` | `AND` — the next condition must also be true |
+| `Or`  | `OR` — the next condition is an alternative  |
+
+### `SqlOrder`
+
+Sort direction for `ISort.order` and `QueryBuilder.orderBy`.
+
+| Value  | Direction           |
+| ------ | ------------------- |
+| `ASC`  | Ascending (default) |
+| `DESC` | Descending          |
+
+---
+
+## Constants
+
+| Constant                 | Import path      | Value              | Description                                                                                                                                      |
+| ------------------------ | ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `DEFAULT_PAGE_LIMIT`     | `@edium/halifax` | `5000`             | Default page size applied when a resource sets no `defaultLimit` and the caller omits `?limit=`. Set `defaultLimit: 0` on a resource to disable. |
+| `MAX_PAGE_LIMIT`         | `@edium/halifax` | `5000`             | Default hard cap on page size. Requests above this are silently capped. Set `maxLimit: 0` on a resource to remove the cap.                       |
+| `defaultCrudPermissions` | `@edium/halifax` | All actions `true` | The `CrudPermissions` object applied to every resource — all nine CRUD actions enabled. Override per-resource with `permissions`.                |