Modern Errors HTTP Response Plugin

Common errors

• ERR_REQUIRE_ESM: require() of ES Module modern-errors-http not supported

  cause You are attempting to use CommonJS `require()` to import `modern-errors-http`, which is an ES module.
  fix Change your import statement to `import modernErrorsHttp from 'modern-errors-http'` and ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`).

• Error: Cannot find module 'modern-errors' or 'modern-errors-http'

  cause `modern-errors` is a peer dependency, and both packages must be installed separately.
  fix Run `npm install modern-errors modern-errors-http` to ensure both the plugin and its core dependency are present.

• TypeError: BaseError.httpResponse is not a function

  cause The `modernErrorsHttp` plugin was not correctly added to your `ModernError.subclass` definition, or you are calling `error.httpResponse()` on an instance after v2.2.0 when the static method `BaseError.httpResponse(error)` should be used.
  fix Ensure your `BaseError` subclass correctly includes `plugins: [modernErrorsHttp]` and call `BaseError.httpResponse(error)` passing the error instance as an argument.

Warnings

• breaking `modern-errors-http` v5.x and later require Node.js version `18.18.0` or higher.
  Fix: Ensure your Node.js environment is updated to `18.18.0` or newer. Earlier versions will not work.
• breaking `modern-errors-http` v5.x requires `modern-errors` v7.0.3 or higher as a peer dependency. Installing `modern-errors-http` without the correct `modern-errors` version will lead to runtime errors.
  Fix: Install the required peer dependency: `npm install modern-errors@^7.0.3` or `yarn add modern-errors@^7.0.3`.
• deprecated The instance method `error.httpResponse()` was deprecated in v2.2.0. While still supported, it's recommended to use the static method.
  Fix: Instead of `error.httpResponse()`, use the static method `BaseError.httpResponse(error)` where `BaseError` is your plugin-configured error class.
• gotcha This package is distributed exclusively as an ES module (ESM). Attempting to import it using CommonJS `require()` will result in an error.
  Fix: Configure your project to use ES modules. This typically involves setting `"type": "module"` in your `package.json` and using `import` statements. For TypeScript, ensure your `tsconfig.json` outputs ES modules (e.g., `"module": "Node16"` or `"ESNext"`).

Install

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

Imports

• modernErrorsHttp
  wrong:

  const modernErrorsHttp = require('modern-errors-http')

  correct:

  import modernErrorsHttp from 'modern-errors-http'

  This package is ESM-only. CommonJS `require()` is not supported.
• ModernError
  wrong:

  const ModernError = require('modern-errors')

  correct:

  import ModernError from 'modern-errors'

  The peer dependency `modern-errors` is also ESM-only, requiring `import` syntax.
• HttpResponse
  wrong:

  import { HttpResponse } from 'modern-errors-http'

  correct:

  import type { HttpResponse } from 'modern-errors-http'

  The `HttpResponse` type defines the shape of the RFC 7807 problem details object returned by the plugin. Use `import type` to avoid runtime import issues.

Quickstart

Demonstrates how to integrate the modern-errors-http plugin, define custom HTTP errors, and generate RFC 7807 compliant problem detail objects for API responses.

import ModernError from 'modern-errors';
import modernErrorsHttp from 'modern-errors-http';

// 1. Extend ModernError with the HTTP plugin
export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsHttp],
});

// 2. Define a custom error with HTTP-specific properties
export const AuthError = BaseError.subclass('AuthError', {
  http: {
    type: 'https://example.com/probs/auth',
    status: 401,
    title: 'Authentication Failed'
  },
});

// 3. Create an instance of the custom error
const error = new AuthError('Could not authenticate the provided credentials.', {
  http: {
    instance: '/users/62/login',
    extra: { userId: 62, attemptedUsername: 'testuser' },
  },
});

// 4. Convert the error to an RFC 7807 compliant HTTP response object
const httpResponseObject = BaseError.httpResponse(error);

// In a real application, this 'httpResponseObject' would be sent as a JSON response body.
console.log(JSON.stringify(httpResponseObject, null, 2));
/*
Expected output (stack trace will vary):
{
  "type": "https://example.com/probs/auth",
  "status": 401,
  "title": "Authentication Failed",
  "detail": "Could not authenticate the provided credentials.",
  "instance": "/users/62/login",
  "stack": "AuthError: Could not authenticate the provided credentials.\n    at ...",
  "extra": {
    "userId": 62,
    "attemptedUsername": "testuser"
  }
}
*/