Use HTTP Error

A TypeScript library that provides a robust and type-safe way to handle HTTP errors in modern JavaScript applications.

🚀 Features

• ✅ Type-safe HTTP error handling
• 🔍 Built-in support for common HTTP status codes
• 📦 Stack trace parsing and formatting
• 🔄 Easy conversion between different formats (JSON, Response, String)
• 🔒 Context and custom headers support
• 🎯 Error wrapping and type checking
• 🔗 Fully compatible with Web API Response interface

📦 Installation

yarn add use-http-error

🛠️ Usage

Basic Usage

import HttpError from 'use-http-error';

// Create a basic HTTP error
const error = new HttpError(404);
console.log(error.message); // "Not Found"
console.log(error.status); // 404

// Create an error with custom message
const customError = new HttpError(400, 'Invalid input parameters');

Advanced Configuration

// Create error with context and headers
const error = new HttpError(500, 'Internal Server Error', {
	context: { errorCode: 'DB_CONNECTION_FAILED' },
	headers: new Headers({
		'retry-after': '30'
	})
});

Error Conversion

// Convert to JSON
const jsonError = error.toJson();
/*
{
  context: { errorCode: 'DB_CONNECTION_FAILED' },
  message: 'Internal Server Error',
  stack: [...],
  status: 500
}
*/

// Convert to Response
const response = error.toResponse();
// Returns Web API Response object

// Convert to string
console.log(error.toString()); // "500 - Internal Server Error"

Static Methods

Error Wrapping

// Wrap number status
const numberError = HttpError.wrap(404);

// Wrap string message
const messageError = HttpError.wrap('Not Found', 404);

// Wrap regular Error
const regularError = new Error('Database connection failed');
const wrappedError = HttpError.wrap(regularError, 500);

Type Checking

const error = new HttpError(404);
const regularError = new Error('Regular error');

console.log(HttpError.is(error)); // true
console.log(HttpError.is(regularError)); // false

JSON Conversion

// Create from JSON
const json = {
	context: { foo: 'bar' },
	message: 'Unauthorized Access',
	stack: [],
	status: 401
};

const error = HttpError.fromJson(json);

Quick Conversions

// Convert to JSON directly
const jsonError = HttpError.json(404);
// or
const jsonError = HttpError.json('Not Found', 404);
// or
const jsonError = HttpError.json(new Error('Custom error'), 500);

// Convert to Response directly
const response = HttpError.response(404);
// or with custom message and status
const response = HttpError.response('Service unavailable', 503);

// Convert to string directly
const errorString = HttpError.string(404); // "404 - Not Found"
// or with custom message
const errorString = HttpError.string('Invalid input', 400);

Stack Trace Control

// Disable stack traces globally
HttpError.includeStack = false;

const error = new HttpError(500);
console.log(error.toJson().stack); // []

// Re-enable stack traces
HttpError.includeStack = true;

🧪 Testing

# Run tests
yarn test

📄 Types

Error Types

type Context = Record<string, any> | null;

type Json = {
	context: Context;
	message: string;
	stack: ErrorStackParser.StackFrame[];
	status: number;
};

Constructor Options

type HttpErrorOptions = {
	context?: Context;
	headers?: Headers;
};

📝 Notes

• Status codes are automatically clamped between 400 and 599
• Default messages are provided for common HTTP status codes
• Stack traces can be globally enabled/disabled
• All instances include a httpError: true property for type checking
• Headers are automatically merged when converting to Response

🤝 Contributing

Contributions, issues and feature requests are welcome!

📝 License

MIT © Felipe Rohde

⭐ Show your support

Give a ⭐️ if this project helped you!

👨‍💻 Author

Felipe Rohde

• Twitter: @felipe_rohde
• Github: @feliperohdee
• Email: feliperohdee@gmail.com