Routing

Routing API Reference

defineRoute()

Register a route.

function defineRoute<TResult>(def: RouteDefinition): void
  • TResult: optional generic type for handler return value

createRouteGroup()

Create and return a route group.

function createRouteGroup(prefix: string, middlewares?: RouteMiddleware[]): RouteGroup

RouteDefinition

type RouteDefinition = {
  path: string
  method?: 'get' | 'post' | 'put' | 'delete' // Default: 'get'
  handler: (ctx: RequestContext) => Promise<TResult = unknown | HttpError>
  schema?: SchemaFactory
  middlewares?: RouteMiddleware[]
  files?: Record<string, FileValidation>
}

RequestContext

type RequestContext = {
  req: Express.Request
  res: Express.Response
  requestId: string
  logger: Logger
  user: unknown | undefined
  getFile: (name: string) => MulterFile | undefined
}

SchemaFactory

type SchemaFactory = (z: Zod) => {
  body?: ZodSchema
  query?: ZodSchema
  params?: ZodSchema | string[]
  response?: ZodSchema
}

RouteMiddleware

Define both a global or a route-level middleware

type RouteMiddleware = (ctx: RequestContext) => Promise<void | HttpError>

RouteGroup

type RouteGroup = {
  defineRoute: <TResult>(def: RouteDefinition): void
  createGroup: (prefix: string, middlewares?: RouteMiddleware[]): RouteGroup
}

FileValidation

type FileValidation = {
  maxSize?: number // Maximum size of the file, in bytes
  mimeTypes?: string[]
  extensions?: string[] // Extensions, e.g.: .png, .jpeg, etc.
}

MulterFile

type MulterFile = {
  fieldname: string
  originalname: string
  encoding: string
  mimetype: string
  size: number
  destination: string
  filename: string
  path: string
  buffer: Buffer
}

CompleteRequestEvent

type CompleteRequestEvent = {
  requestId: string
  timestamp: string // Date formatted as ISO 8601 string
  method: string
  path: string
  body: unknown
  query: unknown
  statusCode: number
  durationMs: number
}