chore: merge feat/common-api-utils into main

Author: exec-unit

src/common/decorators/index.ts

@@ -0,0 +1,2 @@
+export { ParseBody, ParseQuery, ParseParams, allowUnknown } from './parse.decorators.js'
+export { ApiZodBody, ApiZodResponse } from './swagger.decorators.js'

src/common/decorators/parse.decorators.ts

@@ -0,0 +1,148 @@
+import {
+  createParamDecorator,
+  type ExecutionContext,
+  BadRequestException,
+} from '@nestjs/common'
+import type { z } from 'zod'
+import { ZodError } from 'zod'
+import type { Request } from 'express'
+import { ApiBody, ApiQuery, ApiParam } from '@nestjs/swagger'
+import { zodToOpenAPI } from './swagger.decorators.js'
+
+const SKIP_STRICT = Symbol('SKIP_STRICT')
+type SchemaWithMetadata = z.ZodType & { [SKIP_STRICT]?: boolean }
+
+// Cache strict schemas to avoid recreating them on every request
+const strictSchemaCache = new WeakMap<z.ZodType, z.ZodType>()
+
+export function allowUnknown<T extends z.ZodType>(schema: T): T {
+  ;(schema as SchemaWithMetadata)[SKIP_STRICT] = true
+  return schema
+}
+
+function getStrictSchema(schema: z.ZodType): z.ZodType {
+  const schemaWithMeta = schema as SchemaWithMetadata
+
+  if (schemaWithMeta[SKIP_STRICT] === true) {
+    return schema
+  }
+
+  if (!('strict' in schema && typeof schema.strict === 'function')) {
+    return schema
+  }
+
+  let cached = strictSchemaCache.get(schema)
+  if (!cached) {
+    cached = (schema.strict as () => z.ZodType)()
+    strictSchemaCache.set(schema, cached)
+  }
+  return cached
+}
+
+/** Validates `request.body` with the given Zod schema and injects Swagger metadata. */
+export function ParseBody(schema: z.ZodType) {
+  const paramDecorator = createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest<Request>()
+    try {
+      return getStrictSchema(schema).parse(request.body)
+    } catch (error) {
+      if (error instanceof ZodError) throw error
+      throw new BadRequestException('Validation failed')
+    }
+  })()
+
+  return (target: object, propertyKey: string | symbol, parameterIndex: number) => {
+    paramDecorator(target, propertyKey, parameterIndex)
+
+    const openApiSchema = zodToOpenAPI(schema)
+    const descriptor = Object.getOwnPropertyDescriptor(target, propertyKey)
+    if (descriptor && openApiSchema) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+      ApiBody({ schema: openApiSchema as any })(target, propertyKey, descriptor)
+    }
+  }
+}
+
+/** Validates `request.query` with the given Zod schema and injects Swagger metadata. */
+export function ParseQuery(schema: z.ZodType) {
+  const paramDecorator = createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest<Request>()
+    try {
+      return schema.parse(request.query)
+    } catch (error) {
+      if (error instanceof ZodError) throw error
+      throw new BadRequestException('Validation failed')
+    }
+  })()
+
+  return (target: object, propertyKey: string | symbol, parameterIndex: number) => {
+    paramDecorator(target, propertyKey, parameterIndex)
+
+    const openApiSchema = zodToOpenAPI(schema)
+    const descriptor = Object.getOwnPropertyDescriptor(target, propertyKey)
+
+    if (
+      descriptor &&
+      openApiSchema &&
+      'type' in openApiSchema &&
+      openApiSchema['type'] === 'object' &&
+      'properties' in openApiSchema
+    ) {
+      const properties = openApiSchema['properties'] as Record<string, unknown>
+      const requiredFields = (openApiSchema['required'] as string[] | undefined) ?? []
+
+      for (const [key, propSchema] of Object.entries(properties)) {
+        const isRequired = requiredFields.includes(key)
+        const desc = (propSchema as { description?: string }).description
+
+        ApiQuery({
+          name: key,
+          required: isRequired,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+          schema: propSchema as any,
+          ...(desc ? { description: desc } : {}),
+        })(target, propertyKey, descriptor)
+      }
+    }
+  }
+}
+
+/** Validates `request.params` with the given Zod schema and injects Swagger metadata. */
+export function ParseParams(schema: z.ZodType) {
+  const paramDecorator = createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest<Request>()
+    try {
+      return schema.parse(request.params)
+    } catch (error) {
+      if (error instanceof ZodError) throw error
+      throw new BadRequestException('Validation failed')
+    }
+  })()
+
+  return (target: object, propertyKey: string | symbol, parameterIndex: number) => {
+    paramDecorator(target, propertyKey, parameterIndex)
+
+    const openApiSchema = zodToOpenAPI(schema)
+    const descriptor = Object.getOwnPropertyDescriptor(target, propertyKey)
+
+    if (
+      descriptor &&
+      openApiSchema &&
+      'type' in openApiSchema &&
+      openApiSchema['type'] === 'object' &&
+      'properties' in openApiSchema
+    ) {
+      const properties = openApiSchema['properties'] as Record<string, unknown>
+      for (const [key, propSchema] of Object.entries(properties)) {
+        const desc = (propSchema as { description?: string }).description
+
+        ApiParam({
+          name: key,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment
+          schema: propSchema as any,
+          ...(desc ? { description: desc } : {}),
+        })(target, propertyKey, descriptor)
+      }
+    }
+  }
+}

src/common/decorators/swagger.decorators.ts

@@ -0,0 +1,54 @@
+import { applyDecorators } from '@nestjs/common'
+import { ApiBody, ApiResponse } from '@nestjs/swagger'
+import {
+  extendZodWithOpenApi,
+  OpenAPIRegistry,
+  OpenApiGeneratorV3,
+} from '@asteasolutions/zod-to-openapi'
+import { z } from 'zod'
+
+extendZodWithOpenApi(z)
+
+/** Converts a Zod schema into an OpenAPI V3 SchemaObject. */
+export function zodToOpenAPI(schema: z.ZodType): Record<string, unknown> | undefined {
+  const registry = new OpenAPIRegistry()
+  registry.register('Temp', schema)
+  const generator = new OpenApiGeneratorV3(registry.definitions)
+  const doc = generator.generateComponents()
+  return doc.components?.schemas?.['Temp'] as unknown as
+    Record<string, unknown> | undefined
+}
+
+/** Creates an ApiBody decorator from a Zod schema. */
+export function ApiZodBody(schema: z.ZodType, description?: string) {
+  const openApiSchema = zodToOpenAPI(schema)
+  if (!openApiSchema) return applyDecorators()
+
+  return applyDecorators(
+    ApiBody({
+      ...(description ? { description } : {}),
+      // SchemaObject typings between zod-to-openapi and nestjs/swagger can have slight mismatches
+
+      schema: openApiSchema,
+    }),
+  )
+}
+
+/** Creates an ApiResponse decorator from a Zod schema. */
+export function ApiZodResponse(
+  status: number | 'default',
+  schema: z.ZodType,
+  description?: string,
+) {
+  const openApiSchema = zodToOpenAPI(schema)
+  if (!openApiSchema) return applyDecorators()
+
+  return applyDecorators(
+    ApiResponse({
+      status,
+      ...(description ? { description } : {}),
+
+      schema: openApiSchema,
+    }),
+  )
+}

src/common/exceptions/zod-exception.filter.ts

@@ -0,0 +1,157 @@
+import {
+  type ArgumentsHost,
+  Catch,
+  type ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common'
+import type { Request, Response } from 'express'
+
+// ---------------------------------------------------------------------------
+// Response shape types
+// ---------------------------------------------------------------------------
+
+interface ValidationIssue {
+  field: string
+  message: string
+  code: string
+  /** Present when the issue is an invalid_union - shows per-branch errors. */
+  unionErrors?: ValidationIssue[][]
+}
+
+interface ErrorBody {
+  statusCode: number
+  error: string
+  message: string
+  path: string
+  timestamp: string
+  /** Present only for 400 Bad Request validation responses. */
+  issues?: ValidationIssue[]
+}
+
+// ---------------------------------------------------------------------------
+// Raw Zod issue shape (subset we actually use)
+// ---------------------------------------------------------------------------
+
+interface RawZodIssue {
+  code: string
+  path: (string | number)[]
+  message: string
+  errors?: RawZodIssue[][]
+}
+
+interface ZodErrorLike extends Error {
+  issues: RawZodIssue[]
+}
+
+/**
+ * Catches every unhandled exception across the entire application.
+ * Normalises the response shape and logs 5xx errors as errors, 4xx as warnings.
+ * ZodError is parsed into a structured `issues` array with nested union errors.
+ * Local exception filters in individual controllers take precedence.
+ */
+@Catch()
+export class ZodExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(ZodExceptionFilter.name)
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp()
+    const request = ctx.getRequest<Request>()
+    const response = ctx.getResponse<Response>()
+
+    const resolved = this.resolveException(exception)
+    const body: ErrorBody = {
+      statusCode: resolved.status,
+      error: this.statusToText(resolved.status),
+      message: resolved.message,
+      path: request.url,
+      timestamp: new Date().toISOString(),
+      ...(resolved.issues !== undefined && { issues: resolved.issues }),
+    }
+
+    if (resolved.status >= 500) {
+      this.logger.error(
+        `${request.method} ${request.url} → ${String(resolved.status)}: ${resolved.message}`,
+        exception instanceof Error ? exception.stack : String(exception),
+      )
+    } else {
+      this.logger.warn(
+        `${request.method} ${request.url} → ${String(resolved.status)}: ${resolved.message}`,
+      )
+    }
+
+    response.status(resolved.status).json(body)
+  }
+
+  // ---------------------------------------------------------------------------
+
+  private statusToText(status: number): string {
+    const map: Record<number, string> = {
+      400: 'Bad Request',
+      401: 'Unauthorized',
+      403: 'Forbidden',
+      404: 'Not Found',
+      409: 'Conflict',
+      422: 'Unprocessable Entity',
+      429: 'Too Many Requests',
+      500: 'Internal Server Error',
+      502: 'Bad Gateway',
+      503: 'Service Unavailable',
+    }
+    return map[status] ?? `HTTP ${String(status)}`
+  }
+
+  private resolveException(exception: unknown): {
+    status: number
+    message: string
+    issues?: ValidationIssue[]
+  } {
+    if (exception instanceof HttpException) {
+      const res = exception.getResponse()
+      const resObj = typeof res === 'object' ? (res as Record<string, unknown>) : null
+      const message =
+        resObj !== null && 'message' in resObj
+          ? String(resObj['message'])
+          : exception.message
+      return { status: exception.getStatus(), message }
+    }
+
+    // ZodError thrown by @ParseBody / @ParseQuery decorators - invalid client input
+    if (exception instanceof Error && exception.constructor.name === 'ZodError') {
+      const zod = exception as ZodErrorLike
+      return {
+        status: HttpStatus.BAD_REQUEST,
+        message: 'Validation failed',
+        issues: zod.issues.map((issue) => this.formatIssue(issue)),
+      }
+    }
+
+    return { status: HttpStatus.INTERNAL_SERVER_ERROR, message: 'Internal server error' }
+  }
+
+  private formatIssue(issue: RawZodIssue): ValidationIssue {
+    const field = issue.path.length > 0 ? issue.path.join('.') : '(root)'
+    const base: ValidationIssue = { field, message: issue.message, code: issue.code }
+
+    if (issue.code === 'invalid_union' && Array.isArray(issue.errors)) {
+      const branches = issue.errors.map((branch) =>
+        branch.map((i) => this.formatIssue(i)),
+      )
+      // Deduplicate across branches: identical field+code+message pairs collapse into one
+      const seen = new Set<string>()
+      base.unionErrors = branches
+        .map((branch) =>
+          branch.filter((i) => {
+            const key = `${i.field}|${i.code}|${i.message}`
+            if (seen.has(key)) return false
+            seen.add(key)
+            return true
+          }),
+        )
+        .filter((branch) => branch.length > 0)
+    }
+
+    return base
+  }
+}

src/common/index.ts

@@ -0,0 +1,4 @@
+export * from './decorators/index.js'
+export { ZodExceptionFilter } from './exceptions/zod-exception.filter.js'
+export { RequestIdMiddleware } from './middleware/request-id.middleware.js'
+export { HttpLoggerMiddleware } from './middleware/http-logger.middleware.js'