🧱 ts-errors

📘 This README is also available in 🇫🇷 French and 🇬🇧 English.

Handle HTTP errors painlessly — with elegance, strict typing, and a touch of emoji ✨

A minimalist TypeScript library to create, format, and manage HTTP errors with style, structure, and expressiveness. Compatible with JavaScript, Express, and external loggers like winston, pino, etc.

💡 Why ts-errors ?

Because errors deserve better than throw new Error("Oops").
ts-errors helps you to:

• Give meaning to your errors (categories, details, typing)
• Display them clearly (console, logs, API)
• Integrate them easily into your stack (Express, Winston, etc.)

✨ Features

• ✅ Extensible CustomError class with emoji, statusCode, category, details

• 🎯 Ready-to-use errors (NotFoundError, UnauthorizedError, etc.)

• 🎨 Formatted output: compact, colorized, or tabular

• ⚙️ Built-in Express middleware

• 🔌 External logger support (winston, pino, etc.)

• 📦 Zero external dependencies

• 🧠 Strict typing + JS/TS autocompletion

🚀 Installation

npm install ts-errors

⚙️ Quick Start

TypeScript

import { NotFoundError } from "ts-errors";

throw NotFoundError("User not found", { userId: 42 });

JavaScript

const { NotFoundError } = require("ts-errors");

throw NotFoundError("User not found", { userId: 42 });

🧩Using CustomError

import { CustomError } from "ts-errors";

throw new CustomError("Something went wrong", 500, {
  context: "DB connection",
});

🧰 Express Middleware

import express from "express";
import { errorMiddleware, NotFoundError } from "ts-errors";

const app = express();

app.get("/user/:id", (req, res, next) => {
  next(NotFoundError("User not found", { id: req.params.id }));
});

app.use(errorMiddleware);

The errorMiddleware automatically serializes and sends JSON responses to the client.

⚙️ Global Configuration

import { CustomError } from "ts-errors";

CustomError.settings = {
  showEmoji: false,
  defaultCompact: true,
  colorize: false,
};

🔌 External Logger Integration

import { CustomError } from "ts-errors";
import winston from "winston";

const logger = winston.createLogger({
  /* config */
});

CustomError.setLogger(logger, "error");

🖼️ Formatted Output

try {
  throw NotFoundError("Page not found", { url: "/404" });
} catch (err) {
  if (err instanceof CustomError) {
    err.log(); // Affiche l’erreur formatée dans la console
  }
}

Console Output example

+----+----------------+------------+----------------+--------------+
|    | Message        | StatusCode | Details        | Category     |
+----+----------------+------------+----------------+--------------+
| ⁉️ | Page not found | 404        | {"url":"/404"} | Client Error |
+----+----------------+------------+----------------+--------------+

In your terminal

If details are too long, they're truncates in the table and printed bellow.

+----+----------------+------------+-----------------------------------+--------------+
|    | Message        | StatusCode | Details                           | Category     |
+----+----------------+------------+-----------------------------------+--------------+
| ⁉️ | Page not found | 404        | {"url":"/404","detail":"You ca... | Client Error |
+----+----------------+------------+-----------------------------------+--------------+

Details (full):
{
  "url": "/404",
  "detail": "You can add any detail here"
}

In your terminal.

⚡ Available Errors

• BadRequestError
• UnauthorizedError
• ForbiddenError
• NotFoundError
• ConflictError
• UnprocessableEntityError
• TooManyRequestsError
• InternalServerError
• ServiceUnavailableError
• GatewayTimeoutError

📚 CustomError API

Methods

• log() — prints the formatted error
• formatedMessage(compact, showEmoji, colorize) — returns a styled message
• toJSON() — serializes the error for API responses

🧱 Package Structure

export * from "./CustomError";
export * from "./createError";
export * from "./errorHelpers";
export * from "./middlewares/errorMiddleware";

🧪 Tests

npm test

🛡️ License

MIT — see LICENSE for details. You're free to use and modify this library as you see fit.

✨ Auteur

Made with ❤️ & TypeScript by HeleneB1 — creative technologist & digital art director.