Torben Sorensen
186ed484b7
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 2m40s
80 lines
4.5 KiB
Markdown
80 lines
4.5 KiB
Markdown
# ADR-003: Standardized Input Validation using Middleware
|
|
|
|
**Date**: 2025-12-12
|
|
|
|
**Status**: Proposed
|
|
|
|
## Context
|
|
|
|
Our Express route handlers currently perform manual validation of request parameters, queries, and bodies. This involves repetitive boilerplate code using `parseInt`, `isNaN`, and type checks like `Array.isArray`. This approach has several disadvantages:
|
|
|
|
1. **Code Duplication**: The same validation logic (e.g., checking for a valid integer ID) is repeated across many different routes.
|
|
2. **Cluttered Business Logic**: Route handlers are cluttered with validation code, obscuring their primary business logic.
|
|
3. **Inconsistent Error Messages**: Manual validation can lead to inconsistent error messages for similar validation failures across the API.
|
|
4. **Error-Prone**: It is easy to forget a validation check, leading to unexpected data types being passed to service and repository layers, which could cause runtime errors.
|
|
|
|
## Decision
|
|
|
|
We will adopt a schema-based approach for input validation using the `zod` library and a custom Express middleware.
|
|
|
|
1. **Adopt `zod` for Schema Definition**: We will use `zod` to define clear, type-safe schemas for the `params`, `query`, and `body` of each API request. `zod` provides powerful and declarative validation rules and automatically infers TypeScript types.
|
|
|
|
2. **Create a Reusable Validation Middleware**: A generic `validateRequest(schema)` middleware will be created. This middleware will take a `zod` schema, parse the incoming request against it, and handle success and error cases.
|
|
- On successful validation, the parsed and typed data will be attached to the `req` object (e.g., `req.body` will be replaced with the parsed body), and `next()` will be called.
|
|
- On validation failure, the middleware will call `next()` with a custom `ValidationError` containing a structured list of issues, which `ADR-001`'s `errorHandler` can then format into a user-friendly `400 Bad Request` response.
|
|
|
|
3. **Refactor Routes**: All route handlers will be refactored to use this new middleware, removing all manual validation logic.
|
|
|
|
4. **(New) Resilient Type Inference**: To achieve full type safety, we will use **inline type assertions** with `z.infer<typeof schema>`. This ensures the code inside the handler is fully typed and benefits from IntelliSense without creating complex utility types that conflict with Express's `RequestHandler` signature.
|
|
|
|
### Example Usage (Refined Pattern)
|
|
|
|
```typescript
|
|
// In flyer.routes.ts
|
|
|
|
import { z } from 'zod';
|
|
import { validateRequest } from '../middleware/validation';
|
|
|
|
// 1. Define the schema
|
|
const getFlyerSchema = z.object({
|
|
params: z.object({
|
|
id: z.string().pipe(z.coerce.number().int().positive()),
|
|
}),
|
|
});
|
|
|
|
// 2. Infer the type from the schema for local use
|
|
type GetFlyerRequest = z.infer<typeof getFlyerSchema>;
|
|
|
|
// 3. Apply the middleware and use an inline cast for the request
|
|
router.get('/:id', validateRequest(getFlyerSchema), async (req, res, next) => {
|
|
// Cast 'req' to the inferred type.
|
|
// This provides full type safety for params, query, and body.
|
|
const { params } = req as unknown as GetFlyerRequest;
|
|
|
|
try {
|
|
const flyer = await db.flyerRepo.getFlyerById(params.id); // params.id is 'number'
|
|
res.json(flyer);
|
|
} catch (error) {
|
|
next(error);
|
|
}
|
|
});
|
|
```
|
|
|
|
## Consequences
|
|
|
|
### Positive
|
|
|
|
**Reduced Complexity**: Avoids maintaining a complex ValidatedRequestHandler utility type that could conflict with Express or TypeScript upgrades.
|
|
**Explicit Contracts**: By defining the Request type right next to the route, the contract for that endpoint is immediately visible.
|
|
**Improved Readability**: Route handlers become much cleaner and focus exclusively on their core business logic.
|
|
**Type Safety**: `zod` schemas provide strong compile-time and runtime type safety, reducing bugs.
|
|
**Consistent and Detailed Errors**: The `errorHandler` can be configured to provide consistent, detailed validation error messages for all routes (e.g., "Query parameter 'limit' must be a positive integer").
|
|
**Robustness**: Prevents invalid data from ever reaching the service or database layers.
|
|
|
|
### Negative
|
|
|
|
**Minor Verbosity**: Requires one extra line (type ... = z.infer<...>) and a controlled cast (as unknown as ...) within the handler function.
|
|
**New Dependency**: Introduces `zod` as a new project dependency.
|
|
**Learning Curve**: Developers need to learn the `zod` schema definition syntax.
|
|
**Refactoring Effort**: Requires a one-time effort to create schemas and refactor all existing routes to use the `validateRequest` middleware.
|