Throwable HTTP Errors

Common errors

• TypeError: Class constructor BadRequest cannot be invoked without 'new'

  cause Attempting to call an error class directly as a function instead of instantiating it with `new`.
  fix Always use the `new` keyword when creating an instance of an error class, e.g., `throw new Errors.BadRequest('Invalid data')`.

• UnhandledPromiseRejectionWarning: [ErrorName]: [Error Message]

  cause An asynchronous function `throw` an `HttpError` but the calling context did not `await` the promise or failed to catch the rejection.
  fix Ensure all `async` functions that might throw an error are called with `await` within a `try/catch` block, or that the returned promise has a `.catch()` handler.

• Errors is not defined

  cause Using `Errors` or specific error classes (e.g., `BadRequest`) without correctly importing them, especially when mixing CommonJS `require` with ESM `import` or vice-versa.
  fix For CommonJS, use `const Errors = require('throwable-http-errors');`. For ESM/TypeScript, use named imports: `import { BadRequest } from 'throwable-http-errors;`.

• Property 'status' does not exist on type 'Error'.

  cause Trying to access the `status` property on a generic `Error` object in TypeScript without first asserting it's an `HttpError` instance.
  fix In TypeScript, use a type guard to check if the error is an instance of `HttpError` before accessing `status`: `if (err instanceof HttpError) { console.log(err.status); }`.

Warnings

• gotcha The library encourages a paradigm shift from passing errors to `next(err)` to explicitly `throw new Errors.SomeError()` within `async` functions. While `next(err)` still works, leveraging `throw` with `try/catch` is the intended modern usage for better code readability and control flow.
  Fix: Adopt `try/catch` blocks around asynchronous operations and `throw new Errors.SomeError()` instead of `return next(new Errors.SomeError())`.
• gotcha When migrating from `throwable-http-errors` v1 (if it existed) to v2.x, ensure `instanceof` checks are still valid. Although no explicit breaking changes are documented for v1 to v2 API methods, major version bumps often imply changes in underlying structure or exported symbols. Always test your error handling middleware thoroughly.
  Fix: Review the library's official changelog (if available) for `throwable-http-errors` v1 to v2. Ensure your error handling middleware correctly identifies and processes `HttpError` instances, potentially using `err instanceof HttpError`.
• gotcha Unlike some other HTTP error libraries (e.g., `http-errors`), `throwable-http-errors` primarily provides pre-defined error classes for standard HTTP status codes (e.g., `BadRequest`, `NotFound`). While it includes a base `HttpError` class, directly creating generic errors by status code (e.g., `new Errors(400, 'message')`) is not the primary pattern.
  Fix: Always use the specific named error classes (e.g., `new BadRequest('Invalid input')`) for clarity and consistency, rather than attempting to instantiate a generic error with a status code unless explicitly supported by the `HttpError` base class.

Install

• npm install throwable-http-errors npm
• yarn add throwable-http-errors yarn
• pnpm add throwable-http-errors pnpm

Imports

• AllErrors (CommonJS)
  wrong:

  import Errors from 'throwable-http-errors';

  correct:

  const Errors = require('throwable-http-errors');

  For CommonJS environments, the main export is an object containing all error classes.
• SpecificError (ESM/TypeScript)
  wrong:

  import Errors from 'throwable-http-errors'; const { BadRequest } = Errors;

  correct:

  import { BadRequest, InternalServerError } from 'throwable-http-errors';

  For ESM and TypeScript, individual error classes are named exports. The CommonJS default export `Errors` is primarily for `require`.
• BaseHttpError (TypeScript)

  import { HttpError } from 'throwable-http-errors';

  All specific HTTP error classes extend from `HttpError`. This is useful for `instanceof` checks.

Quickstart

Demonstrates creating and handling throwable HTTP errors within an Express.js API using `async/await` and a global error middleware, showcasing `BadRequest` and `NotFound` errors.

import express from 'express';
import { BadRequest, NotFound, InternalServerError } from 'throwable-http-errors';

const app = express();
app.use(express.json());

interface Pet { id: string; name: string; type: string; }

// Dummy database and controller
const pets: Pet[] = [{ id: '1', name: 'Buddy', type: 'Dog' }];
const PetsController = {
  create: async (data: any): Promise<Pet> => {
    if (!data || !data.name || !data.type) {
      throw new BadRequest('Pet name and type are required.');
    }
    const newPet: Pet = { id: String(pets.length + 1), ...data };
    pets.push(newPet);
    return newPet;
  },
  getById: async (id: string): Promise<Pet> => {
    const pet = pets.find(p => p.id === id);
    if (!pet) {
      throw new NotFound(`Pet with ID ${id} not found.`);
    }
    return pet;
  }
};

app.post('/pets', async (req, res, next) => {
  try {
    const pet = await PetsController.create(req.body);
    res.status(201).send({ status: true, data: pet });
  } catch (e) {
    next(e); // Pass error to the global error handler
  }
});

app.get('/pets/:id', async (req, res, next) => {
  try {
    const pet = await PetsController.getById(req.params.id);
    res.status(200).send({ status: true, data: pet });
  } catch (e) {
    next(e);
  }
});

// Global error handling middleware
app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
  // All throwable-http-errors instances have a 'status' property
  if (err.status) {
    return res.status(err.status).json({ status: false, message: err.message });
  } else {
    console.error(err);
    return res.status(500).json({ status: false, message: 'Internal Server Error' });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Try: POST /pets with { "name": "Fluffy", "type": "Cat" }');
  console.log('Then: GET /pets/1');
});