testing ADR - architectural decisions

docs/adr/0003-standardized-input-validation-using-middleware.md

@@ -0,0 +1,70 @@
+# 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.
+
+### Example Usage:
+
+```typescript
+// In flyer.routes.ts
+
+import { z } from 'zod';
+import { validateRequest } from '../middleware/validation';
+
+// Define the schema for the GET /:id route
+const getFlyerSchema = z.object({
+  params: z.object({
+    id: z.string().pipe(z.coerce.number().int().positive()),
+  }),
+});
+
+// Apply the middleware to the route
+router.get('/:id', validateRequest(getFlyerSchema), async (req, res, next) => {
+    try {
+        // req.params.id is now guaranteed to be a positive number
+        const flyerId = req.params.id;
+        const flyer = await db.flyerRepo.getFlyerById(flyerId);
+        res.json(flyer);
+    } catch (error) {
+        next(error);
+    }
+});
+```
+
+## Consequences
+
+### Positive
+
+*   **DRY and Declarative**: Validation logic is defined once in a schema and removed from route handlers.
+*   **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
+
+*   **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.