api-error-normalizer

A lightweight, type-safe TypeScript library for normalizing API errors into a consistent, standardized format. Perfect for Express.js applications and REST APIs.

Features

• Consistent Error Format - Standardize all error responses across your API
• Type-Safe - Full TypeScript support with comprehensive type definitions
• Express Middleware - Drop-in middleware for Express applications
• Flexible - Handle errors from any source (built-in errors, custom objects, strings, etc.)
• Lightweight - Zero dependencies, minimal bundle size
• Customizable - Configure error codes, status codes, and error mapping
• Production-Ready - Includes proper error logging and stack traces

Installation

npm install api-error-normalizer

Or with yarn:

yarn add api-error-normalizer

Or with pnpm:

pnpm add api-error-normalizer

Quick Start

Basic Usage

import { normalizeError } from 'api-error-normalizer';

// Normalize any error
const error = new Error('Something went wrong');
const normalized = normalizeError(error);

console.log(normalized);
// Output:
// {
//   status: 500,
//   code: 'Error',
//   message: 'Something went wrong'
// }

Express Middleware

import express from 'express';
import { errorNormalizerMiddleware } from 'api-error-normalizer';

const app = express();

// Your routes here
app.get('/api/users', (req, res) => {
  throw new Error('Database connection failed');
});

// Error handling middleware (must be last)
app.use(errorNormalizerMiddleware);

app.listen(3000, () => console.log('Server running on port 3000'));

API Reference

normalizeError(error, options?)

Normalizes any error into a standard format.

Parameters:

• error (any) - The error to normalize. Can be:

  • Error objects
  • Plain objects with error properties
  • Strings
  • Custom error classes
  • null or undefined

• options (NormalizerOptions, optional):

  • env (string) - Environment mode ('development' or 'production'). In development, includes stack traces
  • log (function) - Custom logging function for error tracking

Returns:

NormalizedError object with:

• status (number) - HTTP status code (default: 500)
• code (string) - Error code/name (default: 'UNKNOWN_ERROR')
• message (string) - Human-readable error message
• details (any, optional) - Additional error details or metadata

Example:

import { normalizeError } from 'api-error-normalizer';

// Normalize built-in Error
const error1 = normalizeError(new Error('User not found'));

// Normalize custom object
const error2 = normalizeError({
  code: 'VALIDATION_ERROR',
  message: 'Invalid email format',
  status: 400,
  details: { field: 'email' }
});

// Normalize with options
const error3 = normalizeError(error1, {
  env: 'development',
  log: (err) => console.error('Error logged:', err)
});

errorNormalizerMiddleware

Express error handling middleware that catches and normalizes errors.

Usage:

app.use(errorNormalizerMiddleware);

Must be registered after all other middleware and route handlers.

Error Format

All normalized errors follow this consistent structure:

interface NormalizedError {
  status: number;        // HTTP status code (200-599)
  code: string;          // Error code/type identifier
  message: string;       // Human-readable message
  details?: any;         // Optional additional data
}

Examples

Handling Database Errors

import { normalizeError } from 'api-error-normalizer';

try {
  // Database operation
  await db.query('SELECT * FROM users WHERE id = ?', [userId]);
} catch (error) {
  const normalized = normalizeError(error, {
    env: process.env.NODE_ENV
  });
  
  res.status(normalized.status).json({ error: normalized });
}

Custom Error Objects

class ValidationError extends Error {
  constructor(message: string, public fields: Record<string, string>) {
    super(message);
    this.name = 'ValidationError';
  }
}

const error = new ValidationError('Validation failed', {
  email: 'Invalid email format',
  password: 'Too short'
});

const normalized = normalizeError(error);
// {
//   status: 500,
//   code: 'ValidationError',
//   message: 'Validation failed'
// }

Global Error Handling

import express from 'express';
import { errorNormalizerMiddleware } from 'api-error-normalizer';

const app = express();

// Routes
app.get('/api/data', async (req, res) => {
  try {
    const data = await fetchData();
    res.json(data);
  } catch (error) {
    next(error); // Pass to error handler
  }
});

// Global error handler
app.use((err: any, req: any, res: any, next: any) => {
  errorNormalizerMiddleware(err, req, res, next);
});

app.listen(3000);

TypeScript Support

This library includes complete TypeScript definitions:

import type { NormalizedError, NormalizerOptions } from 'api-error-normalizer';

const handleError = (error: unknown, options?: NormalizerOptions): NormalizedError => {
  return normalizeError(error, options);
};

Options

NormalizerOptions

interface NormalizerOptions {
  env?: 'development' | 'production';
  log?: (error: NormalizedError, req?: Request) => void;
}

• env: Controls whether stack traces are included in the normalized error

  • 'development': Includes full error details and stack traces
  • 'production': Minimal error information for security

• log: Custom logging function for error tracking and monitoring

  • Useful for integrating with logging services (Winston, Bunyan, etc.)

Common HTTP Status Codes

The library maps errors to appropriate HTTP status codes:

Code	Status	Description
ValidationError	400	Invalid input data
NotFoundError	404	Resource not found
UnauthorizedError	401	Authentication required
ForbiddenError	403	Access denied
ConflictError	409	Resource conflict
InternalServerError	500	Server error

Best Practices

1. Use in Error Handlers - Apply middleware/function at the end of your error handling chain
2. Log Errors - Use the log option to track errors in production
3. Custom Codes - Create custom error classes with meaningful error codes
4. Environment-Aware - Set env to 'production' in production to hide stack traces
5. Type Safety - Always use TypeScript for better type checking

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Changelog

1.0.0

• Initial release
• Basic error normalization
• Express middleware support
• Full TypeScript support

Support

For issues, questions, or suggestions, please open an issue on GitHub.

---

Made for better API error handling