@edium/halifax 2.1.0 → 2.2.0

package/README_HOOKS.md

@@ -0,0 +1,275 @@
+# Halifax — Lifecycle Hooks
+
+Hooks let you inject custom logic **before or after any CRUD operation** without writing a custom repository or HTTP middleware. They are defined per-resource under the `hooks` key on `ResourceDefinition`.
+
+## Quick example
+
+```ts
+import {
+  createExpressCrudRouter,
+  PrismaAdapter,
+  AuthorizationError,
+  type ResourceDefinition
+} from '@edium/halifax'
+
+const posts: ResourceDefinition = {
+  routePrefix: 'posts',
+  repository: new PrismaAdapter({ delegate: prisma.post }),
+  hooks: {
+    // Stamp createdBy / updatedBy from the authenticated user
+    beforeCreate: (data, { auth }) => ({ ...data, createdBy: auth.userId }),
+    beforeUpdateOne: (id, data, { auth }) => ({ ...data, updatedBy: auth.userId }),
+
+    // Emit a domain event after every new post is saved
+    afterCreate: async (result) => {
+      await events.emit('post.created', result)
+    },
+
+    // Block callers from reading soft-deleted posts (belt-and-suspenders on top of auth)
+    afterReadOne: (result) => {
+      if (result.deletedAt) throw new AuthorizationError('Not found.')
+      return result
+    }
+  }
+}
+```
+
+---
+
+## How hooks work
+
+### Before hooks
+
+Called **before the database operation**. They receive the incoming data and can:
+
+| Return                          | Effect                                                                                                                                                                                                       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A **modified copy** of the data | The modified value is used instead of the original.                                                                                                                                                          |
+| `void` / `undefined`            | The original value is used unchanged.                                                                                                                                                                        |
+| **Throw any `Error`**           | The operation is aborted and Halifax sends the appropriate HTTP error response. Use Halifax error classes (`BadRequestError`, `AuthorizationError`, `UnprocessableEntityError`, …) for precise status codes. |
+
+### After hooks
+
+Called **after the database operation, before the HTTP response is sent**. They receive the raw DB result (before `readRoles`/`selectable` field-filtering) and can:
+
+| Return                            | Effect                                                                                       |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| A **modified copy** of the result | The modified value is sent to the client (field-filtering is applied afterwards).            |
+| `void` / `undefined`              | The original result is used unchanged.                                                       |
+| **Throw any `Error`**             | A successful DB write is replaced with an error response (useful for post-write validation). |
+
+### Hook context
+
+Every hook receives a context object as its last argument:
+
+```ts
+interface HookContext {
+  auth: AuthContext // resolved caller identity (userId, roles, permissions, claims)
+  resource: ResourceDefinition // the normalized resource being accessed
+  req: HttpRequest // raw HTTP request — headers, raw framework request, etc.
+}
+```
+
+---
+
+## Full hook reference
+
+### Create — `POST /resource`
+
+| Hook           | Signature                         | Notes                                                                            |
+| -------------- | --------------------------------- | -------------------------------------------------------------------------------- |
+| `beforeCreate` | `(data, ctx) => data \| void`     | Fires **once per record** — both for single-object and array POST bodies.        |
+| `afterCreate`  | `(result, ctx) => result \| void` | Fires **once per record**. Sees the full DB record before `readRoles` filtering. |
+
+### Read — `GET /resource`
+
+| Hook             | Signature                               | Notes                                                          |
+| ---------------- | --------------------------------------- | -------------------------------------------------------------- |
+| `beforeReadMany` | `(options, ctx) => ListOptions \| void` | Modify pagination, inject extra `where` filters, force a sort. |
+| `afterReadMany`  | `(result, ctx) => ListResult \| void`   | Transform the full `{ count, results }` envelope.              |
+
+### Read — `GET /resource/:id`
+
+| Hook            | Signature                         | Notes                                 |
+| --------------- | --------------------------------- | ------------------------------------- |
+| `beforeReadOne` | `(id, ctx) => void`               | Throw to block; cannot modify the ID. |
+| `afterReadOne`  | `(result, ctx) => result \| void` | Attach computed / virtual fields.     |
+
+### Update — `PATCH /resource/:id`
+
+| Hook              | Signature                         | Notes                                                |
+| ----------------- | --------------------------------- | ---------------------------------------------------- |
+| `beforeUpdateOne` | `(id, data, ctx) => data \| void` | Modify the update payload (e.g. stamp audit fields). |
+| `afterUpdateOne`  | `(result, ctx) => result \| void` | Transform the updated record.                        |
+
+### Bulk update — `PATCH /resource`
+
+| Hook               | Signature                                   | Notes                                            |
+| ------------------ | ------------------------------------------- | ------------------------------------------------ |
+| `beforeUpdateMany` | `(query, data, ctx) => void`                | Throw to block; cannot modify the query or data. |
+| `afterUpdateMany`  | `(result, ctx) => UpdateManyResult \| void` | Transform the `{ updated, results? }` response.  |
+
+### Upsert — `PUT /resource/:id`
+
+| Hook              | Signature                         | Notes                           |
+| ----------------- | --------------------------------- | ------------------------------- |
+| `beforeUpsertOne` | `(id, data, ctx) => data \| void` | Modify the upsert payload.      |
+| `afterUpsertOne`  | `(result, ctx) => result \| void` | Transform the resulting record. |
+
+### Delete — `DELETE /resource/:id`
+
+| Hook              | Signature           | Notes                                                                            |
+| ----------------- | ------------------- | -------------------------------------------------------------------------------- |
+| `beforeDeleteOne` | `(id, ctx) => void` | The record still exists when this fires. Throw to abort.                         |
+| `afterDeleteOne`  | `(id, ctx) => void` | The record is gone. Use for cleanup or event emission. Does **not** fire on 404. |
+
+### Bulk delete — `DELETE /resource`
+
+| Hook               | Signature                                   | Notes                                 |
+| ------------------ | ------------------------------------------- | ------------------------------------- |
+| `beforeDeleteMany` | `(query, ctx) => void`                      | Throw to block.                       |
+| `afterDeleteMany`  | `(result, ctx) => DeleteManyResult \| void` | Transform the `{ deleted }` response. |
+
+### Query builder — `POST /resource/query`
+
+| Hook          | Signature                               | Notes                                                                                    |
+| ------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `beforeQuery` | `(query, ctx) => IQueryOptions \| void` | Augment or restrict the query (e.g. inject a mandatory filter the client cannot remove). |
+| `afterQuery`  | `(result, ctx) => QueryResult \| void`  | Transform the `{ count, results }` response.                                             |
+
+---
+
+## Common patterns
+
+### Stamp audit fields
+
+```ts
+hooks: {
+  beforeCreate:    (data, { auth }) => ({ ...data, createdBy: auth.userId }),
+  beforeUpdateOne: (id, data, { auth }) => ({ ...data, updatedBy: auth.userId }),
+}
+```
+
+### Emit domain events
+
+```ts
+hooks: {
+  afterCreate:    async (result) => events.emit('post.created', result),
+  afterUpdateOne: async (result) => events.emit('post.updated', result),
+  afterDeleteOne: async (id)     => events.emit('post.deleted', { id }),
+}
+```
+
+### Enforce ownership on reads
+
+```ts
+import { AuthorizationError } from '@edium/halifax'
+
+hooks: {
+  beforeReadOne: async (id, { auth }) => {
+    const record = await db.post.findUnique({ where: { id: Number(id) } })
+    if (record?.ownerId !== auth.userId) throw new AuthorizationError()
+  }
+}
+```
+
+### Restrict query-builder results to the caller's own data
+
+Works as a server-side guard that clients cannot bypass, similar to tenant scoping:
+
+```ts
+hooks: {
+  beforeQuery: (query, { auth }) => ({
+    ...query,
+    where: [
+      ...(query.where ?? []),
+      { field: 'ownerId', comparison: '=', value1: auth.userId, operator: 'AND' }
+    ]
+  })
+}
+```
+
+### Soft-delete interception
+
+Block reads on soft-deleted records even after the DB returns them:
+
+```ts
+hooks: {
+  afterReadOne:  (result) => { if (result.deletedAt) throw new NotFoundError(); return result },
+  afterReadMany: (result) => ({
+    ...result,
+    results: result.results.filter((r) => !r.deletedAt),
+    count: result.results.filter((r) => !r.deletedAt).length
+  })
+}
+```
+
+### Validate business rules before a write
+
+```ts
+import { UnprocessableEntityError } from '@edium/halifax'
+
+hooks: {
+  beforeCreate: async (data) => {
+    const exists = await db.user.findUnique({ where: { email: data.email } })
+    if (exists) throw new UnprocessableEntityError('Email already registered.')
+    return data
+  }
+}
+```
+
+---
+
+## TypeScript generics
+
+Hook callbacks are fully typed when you pass generics to `ResourceDefinition`:
+
+```ts
+interface Post {
+  id: number
+  title: string
+  body: string
+  createdBy?: string
+}
+
+const posts: ResourceDefinition<Post, Omit<Post, 'id' | 'createdBy'>, Partial<Post>> = {
+  routePrefix: 'posts',
+  repository: new PrismaAdapter({ delegate: prisma.post }),
+  hooks: {
+    // `data` is typed as `Omit<Post, 'id' | 'createdBy'>` ✓
+    beforeCreate: (data, { auth }) => ({ ...data, createdBy: auth.userId }),
+    // `result` is typed as `Post` ✓
+    afterCreate: (result) => result
+  }
+}
+```
+
+---
+
+## Execution order
+
+For a `POST /resource` call, the full pipeline is:
+
+```
+request
+  → auth & authorization check
+  → field write-filtering (writable / writeRoles)
+  → beforeCreate (per item)
+  → repository.createOne / .createMany
+  → afterCreate (per item)
+  → field read-filtering (selectable / readRoles)
+  → response
+```
+
+Hooks run **inside** the existing error-catching wrapper, so any `Error` thrown is automatically serialized as `{ errors: [{ code, message }] }` and the correct HTTP status is set.
+
+---
+
+## Relation to other extension points
+
+| Extension point          | When to use                                                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| **Hooks**                | Per-resource logic that runs inside the Halifax pipeline (stamping, eventing, ownership checks, data transformation). |
+| **AuthStrategy**         | Cross-resource authentication and coarse-grained authorization applied to every route.                                |
+| **Repository wrapper**   | Low-level data-access customization (query rewriting, custom SQL, alternative storage).                               |
+| **Framework middleware** | Transport-level concerns: CORS, rate limiting, request ID injection, body parsing.                                    |