🧱 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.)

Requirements: Node >= 18, TypeScript >= 5

NPM | GitHub

✨ 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

# With npm
npm install @heleneb1/ts-errors

# Or yarn
yarn add @heleneb1/ts-errors

⚙️ Quick Start

👀 Demo

📹 View fullscreen

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",
});

⚠️ Creating a CustomError Correctly

The order of arguments matters!

💡 Signature:

new CustomError(
  message: string,                // error text
  statusCode?: number,            // HTTP status code (default 500)
  details?: Record<string, any>   // additional info
)

✅ Correct example:

throw new CustomError("Joke not found", 404, {
  info: `Joke with id ${id} not found 😔`, // free text, add anything you want
});

❌ Example to avoid:

// Wrong order → statusCode will be replaced by the details object
throw new CustomError("Joke not found", { jokeId: id }, 404);

💡 Tip: You can also pass an object directly:

throw new CustomError({
  message: "Joke not found",
  statusCode: 404,
  details: { jokeId: id },
});

🧰 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,
};
CustomError.config({ showEmoji: true, colorize: true });
CustomError.setLogger(myWinstonLogger, "error");

🔌 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
  }
}

🗃️ Access as Table or JSON

Each CustomError can be displayed as a table in the console using log() or retrieved as JSON using toJSON().

import { NotFoundError, CustomError } from "ts-errors";

try {
  throw NotFoundError(undefined, { userId: 42 });
} catch (err) {
  if (err instanceof CustomError) {
    // Display as a table in the console
    err.log();

    // Get the JSON object for API or other usage

    console.log(err.toJSON());
  }
}

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 run test

📝 Changelog

• 1.0.0 — Initial release

🛡️ 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.