// src/types/express.d.ts
import { Request, Response, NextFunction } from 'express';
import { Logger } from 'pino';
import * as qs from 'qs';

/**
 * This file uses declaration merging to add a custom `log` property to the
 * global Express Request interface. This makes the request-scoped logger
 * available in a type-safe way in all route handlers, as required by ADR-004.
 */
declare global {
  namespace Express {
    export interface Request {
      log: Logger;
    }
  }
}

/**
 * Defines a more accurate type for asynchronous Express route handlers.
 * Standard `RequestHandler` requires `next` to be present, which is often unused
 * in modern async/await handlers, leading to linting errors. This type makes `next` optional.
 *
 * It also allows for more specific typing of the request body, query, and params.
 */
export type AsyncRequestHandler<
  P = Record<string, string>,
  ResBody = unknown,
  ReqBody = unknown,
  ReqQuery = qs.ParsedQs
> = (
  req: Request<P, ResBody, ReqBody, ReqQuery>,
  res: Response<ResBody>,
  next?: NextFunction
) => Promise<void | unknown>;