Error Handler Middleware

A comprehensive Express error handler middleware that provides standardized error responses for all domain-specific errors from various packages including router-middleware and authentication-middleware.

Features

- ✅ Standardized Error Responses - Consistent error format across all error types
- ✅ Domain Error Support - Built-in handling for validation, authentication, authorization, and not found errors
- ✅ Zod Validation Errors - Detailed field-by-field validation error messages
- ✅ Type-Safe - Full TypeScript support with detailed error types
- ✅ Customizable - Custom formatters, error handlers, and skip conditions
- ✅ Environment Aware - Different behavior for development and production
- ✅ Logging Support - Built-in error logging with custom handler support
- ✅ Stack Traces - Optional stack traces in development mode

Installation

``bash
pnpm add @verisure-italy/error-handler-middleware
`

Quick Start

$3

`typescript
import express from 'express'
import { errorHandler } from '@verisure-italy/error-handler-middleware'

const app = express()

// ... your routes ...

// Add error handler as the last middleware
app.use(errorHandler())
`

$3

`typescript
import { errorHandler } from '@verisure-italy/error-handler-middleware'

app.use(
errorHandler({
logErrors: true,
showDetails: process.env.NODE_ENV !== 'production',
includeStackTrace: process.env.NODE_ENV === 'development',
})
)
`

Error Response Format

All errors follow a consistent structure:

`typescript
interface ErrorResponse {
error: string // Error type (e.g., "Validation Error")
message: string // Human-readable message
statusCode: number // HTTP status code
code: string // Machine-readable error code
timestamp: string // ISO 8601 timestamp
path?: string // Request path where error occurred
details?: any // Additional error details (environment-dependent)
}
`

Supported Error Types

$3

From router-middleware with Zod:

`typescript
// Request
POST /api/users
{
"username": "",
"roles": []
}

// Response
{
"error": "Validation Error",
"message": "The request contains invalid data",
"statusCode": 422,
"code": "VALIDATION_ERROR",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users",
"details": [
{
"field": "username",
"message": "String must contain at least 1 character(s)",
"code": "too_small",
"value": ""
},
{
"field": "roles",
"message": "Array must contain at least 1 element(s)",
"code": "too_small",
"value": []
}
]
}
`

$3

From authentication-middleware:

`typescript
// Response
{
"error": "Authentication Error",
"message": "Invalid token",
"statusCode": 401,
"code": "UNAUTHORIZED",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users"
}
`

$3

From router-middleware ACL:

`typescript
// Response
{
"error": "Authorization Error",
"message": "You do not have permission to access this resource",
"statusCode": 403,
"code": "FORBIDDEN",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users/123"
}
`

$3

From router-middleware param resolver:

`typescript
// Response
{
"error": "Not Found",
"message": "User not found",
"statusCode": 404,
"code": "NOT_FOUND",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users/unknown-id"
}
`

$3

Any unhandled error:

`typescript
// Development Response (showDetails: true)
{
"error": "Internal Server Error",
"message": "Cannot read property 'id' of undefined",
"statusCode": 500,
"code": "INTERNAL_ERROR",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users",
"details": {
"name": "TypeError",
"stack": [
"TypeError: Cannot read property 'id' of undefined",
" at UserController.create (/app/controllers/user.js:15:20)",
" ..."
]
}
}

// Production Response (showDetails: false)
{
"error": "Internal Server Error",
"message": "An unexpected error occurred",
"statusCode": 500,
"code": "INTERNAL_ERROR",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users"
}
`

Configuration

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| includeStackTrace | boolean | NODE_ENV !== 'production' | Include stack trace in error response |
| logErrors | boolean | NODE_ENV === 'development' | Log errors to console |
| showDetails | boolean | NODE_ENV !== 'production' | Show detailed error information |
| onError | (error, req, res) => void \| Promise | undefined | Custom error handler (for logging, monitoring, etc.) |
| skipError | (error, req) => boolean | () => false | Skip handling for specific errors |
| formatters | object | {} | Custom formatters for specific error types |

Advanced Usage

$3

`typescript
import { errorHandler } from '@verisure-italy/error-handler-middleware'
import { logger } from './logger'

app.use(
errorHandler({
onError: async (error, req, res) => {
// Log to external service (e.g., Sentry, DataDog)
await logger.error('API Error', {
error: error.message,
stack: error.stack,
path: req.path,
method: req.method,
userId: req._auth?.user?.id,
statusCode: res.statusCode,
})
},
})
)
`

$3

`typescript
app.use(
errorHandler({
skipError: (error, req) => {
// Skip 404 errors on static files
if (error.statusCode === 404 && req.path.startsWith('/static')) {
return true
}

// Skip specific error types
if (error.code === 'CUSTOM_ERROR') {
return true
}

return false
},
})
)
`

$3

`typescript
app.use(
errorHandler({
formatters: {
validation: (error) => ({
error: 'Invalid Input',
message: 'Please check your input and try again',
statusCode: 422,
code: 'INVALID_INPUT',
timestamp: new Date().toISOString(),
details: {
fields: error.errors?.map(e => e.field) || [],
},
}),
authentication: (error) => ({
error: 'Auth Failed',
message: 'Please log in to continue',
statusCode: 401,
code: 'AUTH_REQUIRED',
timestamp: new Date().toISOString(),
}),
},
})
)
`

$3

`typescript
const errorConfig = {
development: {
logErrors: true,
showDetails: true,
includeStackTrace: true,
},
production: {
logErrors: false,
showDetails: false,
includeStackTrace: false,
onError: async (error, req) => {
// Send to monitoring service
await sentry.captureException(error, {
extra: { path: req.path, method: req.method },
})
},
},
}

app.use(
errorHandler(errorConfig[process.env.NODE_ENV] || errorConfig.development)
)
`

Integration with Router Middleware

Perfect integration with @verisure-italy/router-middleware:

`typescript
import express from 'express'
import { createRouter, createRestResource } from '@verisure-italy/router-middleware'
import { errorHandler } from '@verisure-italy/error-handler-middleware'
import { User, userSchema } from '@verisure-italy/aaa-types'

const app = express()

// Router middleware
const userRoutes = createRestResource({
dataModel: 'user',
basePath: '/users',
sharedOptions: {
secure: true,
acl: { allow: { roles: ['ROLE_AAA_ADMIN'] } },
},
methodOptions: {
create: {
validate: { body: userSchema.omit({ id: true }) },
},
},
})

app.use('/api', createRouter(userRoutes, { / config / }))

// Error handler (MUST be last)
app.use(errorHandler({
logErrors: true,
showDetails: process.env.NODE_ENV !== 'production',
}))
`

Error handling flow:

1. Validation Error (from Zod in router-middleware)
- Middleware catches validation error
- Error handler formats with field-by-field details
- Returns 422 with detailed validation errors

2. Authentication Error (from authentication-middleware)
- Middleware catches auth error
- Error handler formats
- Returns 401 with clear auth message

3. Authorization Error (from ACL in router-middleware)
- Middleware catches forbidden error
- Error handler formats
- Returns 403 with permission message

Type Checking

The middleware provides TypeScript utilities to check error types:

`typescript
import {
isDomainError,
isValidationError,
isAuthenticationError,
isAuthorizationError,
isNotFoundError,
isZodError,
} from '@verisure-italy/error-handler-middleware'

app.use(
errorHandler({
onError: (error) => {
if (isValidationError(error)) {
console.log('Validation failed:', error.errors)
} else if (isAuthenticationError(error)) {
console.log('Auth failed')
} else if (isZodError(error)) {
console.log('Zod validation issues:', error.issues)
}
},
})
)
`

Best Practices

$3

The error handler MUST be the last middleware:

`typescript
// ✅ Correct order
app.use(bodyParser.json())
app.use(authMiddleware)
app.use('/api', router)
app.use(errorHandler()) // Last!

// ❌ Wrong order
app.use(errorHandler()) // Too early!
app.use('/api', router)
`

$3

`typescript
// ✅ Good
app.use(errorHandler({
showDetails: process.env.NODE_ENV !== 'production',
logErrors: process.env.NODE_ENV === 'development',
}))

// ❌ Bad - exposes sensitive info in production
app.use(errorHandler({
showDetails: true,
includeStackTrace: true,
}))
`

$3

`typescript
// ✅ Good - log to monitoring service
app.use(errorHandler({
onError: async (error, req) => {
if (process.env.NODE_ENV === 'production') {
await monitoring.captureException(error, {
tags: { path: req.path, method: req.method },
})
}
},
}))
`

$3

`typescript
// ✅ Good - fallback if error handler fails
app.use(errorHandler())

// Fallback handler
app.use((error, req, res, next) => {
res.status(500).json({ error: 'Something went wrong' })
})
`

Examples

$3

`typescript
import express from 'express'
import { createRouter, createRestResource } from '@verisure-italy/router-middleware'
import { dynamoAuthMiddleware } from '@verisure-italy/authentication-middleware'
import { errorHandler } from '@verisure-italy/error-handler-middleware'
import { User, userSchema } from '@verisure-italy/aaa-types'

const app = express()

// Body parser
app.use(express.json())

// Authentication
app.use(
dynamoAuthMiddleware({
dynamoConfig: { region: 'eu-west-1' },
tokenTableName: 'access_tokens',
userTableName: 'users',
})
)

// API routes
const userRoutes = createRestResource({
dataModel: 'user',
basePath: '/users',
methods: ['create', 'read', 'update', 'list', 'delete'],
sharedOptions: {
secure: true,
acl: { allow: { roles: ['ROLE_AAA_ADMIN'] } },
},
methodOptions: {
create: {
validate: { body: userSchema.omit({ id: true }) },
},
update: {
validate: { body: userSchema.partial().omit({ id: true }) },
},
},
})

app.use(
'/api',
createRouter(userRoutes, {
dataModels: { user: { tableName: 'users', idField: 'id' } },
})
)

// 404 handler
app.use((req, res, next) => {
const error: any = new Error('Route not found')
error.statusCode = 404
error.code = 'NOT_FOUND'
next(error)
})

// Error handler (MUST be last!)
app.use(
errorHandler({
logErrors: true,
showDetails: process.env.NODE_ENV !== 'production',
onError: async (error, req) => {
// Log to monitoring service in production
if (process.env.NODE_ENV === 'production') {
await logger.error(error, {
path: req.path,
method: req.method,
})
}
},
})
)

app.listen(3000, () => {
console.log('Server running on http://localhost:3000')
})
`

Error Response Examples

$3

`json
{
"error": "Validation Error",
"message": "The request contains invalid data",
"statusCode": 422,
"code": "VALIDATION_ERROR",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users",
"details": [
{
"field": "username",
"message": "String must contain at least 1 character(s)",
"code": "too_small",
"value": ""
},
{
"field": "roles",
"message": "Array must contain at least 1 element(s)",
"code": "too_small",
"value": []
},
{
"field": "email",
"message": "Invalid email",
"code": "invalid_string",
"value": "not-an-email"
}
]
}
`

$3

`json
{
"error": "Authentication Error",
"message": "Token expired",
"statusCode": 401,
"code": "UNAUTHORIZED",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users"
}
`

$3

`json
{
"error": "Authorization Error",
"message": "You do not have permission to access this resource",
"statusCode": 403,
"code": "FORBIDDEN",
"timestamp": "2025-10-24T10:30:00.000Z",
"path": "/api/users/123"
}
``

License

MIT