Standard HTTP Error Class

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` syntax for `standard-http-error` in a Node.js environment configured as CommonJS, or using an incorrect named import in an ESM context.
  fix If in a CommonJS file, use `const HttpError = require('standard-http-error');`. If in an ES module, use `import HttpError from 'standard-http-error';` to leverage Node.js's CJS-ESM interop.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

  cause Trying to `require()` a package that is ESM-only from a CommonJS context. While `standard-http-error` is CJS, this error can appear if a build system incorrectly tries to apply ESM logic to it.
  fix Ensure your module resolution and bundling configuration correctly identifies `standard-http-error` as a CommonJS module. If you are consuming it in an ESM project, use `import HttpError from 'standard-http-error';`.

• Property 'status' does not exist on type 'HttpError' (TypeScript error)

  cause While `HttpError` instances have `status`, `statusCode`, and `statusMessage` aliases, the TypeScript definitions might not expose these directly as enumerable properties, or the context implies a plain `Error` type.
  fix Access `err.code` and `err.message` directly as they are the primary enumerable properties. If you specifically need the aliases for downstream compatibility, use `(err as any).status` or ensure your type definition explicitly includes these non-enumerable properties.

Warnings

• breaking The `standard-http-error` package (v2.x) is distributed as CommonJS. Directly using ESM `import { HttpError } from 'standard-http-error'` in a pure ES module environment without proper Node.js CJS interop or a bundler might lead to `SyntaxError` or `ERR_REQUIRE_ESM` errors.
  Fix: Use the CommonJS `const HttpError = require('standard-http-error');` or the ESM default import `import HttpError from 'standard-http-error';` which Node.js's CJS interop handles.
• gotcha For compatibility with some frameworks, `HttpError` sets `status`, `statusCode`, and `statusMessage` as non-enumerable aliases of `code` and `message`. These properties will not appear when the error object is stringified (e.g., via `JSON.stringify`), which can be unexpected for serialization.
  Fix: To serialize these specific properties, explicitly copy them to a new object or use a custom serializer. For example: `JSON.stringify({ code: err.code, message: err.message, status: err.status })`.
• gotcha The official documentation demonstrates subclassing `HttpError` using pre-ES6 `Object.create(HttpError.prototype, { ... })`. While still functional, developers using modern TypeScript or ES6+ `class extends` syntax might encounter subtle differences in `name` and `stack` behavior if not careful, compared to the library's internal handling.
  Fix: When subclassing with modern `class extends`, ensure `super()` is called correctly and consider explicitly setting `this.name = this.constructor.name;` if needed, although the base `standard-error` library aims to handle this.

Install

• npm install standard-http-error npm
• yarn add standard-http-error yarn
• pnpm add standard-http-error pnpm

Imports

• HttpError
  wrong:

  import { HttpError } from 'standard-http-error';

  correct:

  import HttpError from 'standard-http-error';

  The core library is CommonJS-only (v2.x), exporting `HttpError` as a default. TypeScript/ESM interop typically handles this as a default import. Named import will fail.
• HttpError

  const HttpError = require('standard-http-error');

  This is the native CommonJS import pattern as shown in the package's documentation.
• HttpError.NOT_FOUND

  if (err.code === HttpError.NOT_FOUND) { /* ... */ }

  Static properties representing HTTP status codes (e.g., `UNAUTHORIZED`, `FORBIDDEN`) are exposed directly on the `HttpError` class. These are primarily for comparison, not direct import.

Quickstart

Demonstrates creating `HttpError` instances with numeric codes, named codes, custom messages, and custom properties, and catching them with `instanceof`.

import HttpError from 'standard-http-error';

try {
  // Create an HTTP error with a specific code
  throw new HttpError(404);
} catch (err) {
  if (err instanceof HttpError) {
    console.log(`Caught HttpError: ${err.name} (${err.code}) - ${err.message}`); // Output: HttpError (404) - Not Found
  }
}

try {
  // Create an HTTP error with a named code and custom message
  throw new HttpError(HttpError.FORBIDDEN, 'Access to this resource is denied');
} catch (err) {
  if (err instanceof HttpError) {
    console.log(`Caught HttpError: ${err.name} (${err.code}) - ${err.message}`); // Output: HttpError (403) - Access to this resource is denied
  }
}

try {
  // Create an HTTP error with custom properties
  throw new HttpError(412, 'Bad CSRF Token', { url: '/api/resource', userId: 'user123' });
} catch (err) {
  if (err instanceof HttpError) {
    console.log(`Caught HttpError with custom props: ${err.code} - ${err.message}. URL: ${err.url}, User: ${err.userId}`);
  }
}