Fejl Error Utility

Common errors

• ERR_REQUIRE_ESM: require() of ES Module [path] from [path] not supported. Instead change the require of index.js in [path] to a dynamic import() which is available in all CommonJS modules.

  cause Attempting to use `require()` to import `fejl` in a CommonJS module, but `fejl` v4+ is an ES Module.
  fix Change your import statements from `const { Symbol } = require('fejl');` to `import { Symbol } from 'fejl';` and ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`).

• TypeError: MakeErrorClass is not a constructor

  cause This error can occur if you're trying to use `new MakeErrorClass()` directly, or if `MakeErrorClass` itself wasn't correctly imported in a CJS context when it's an ESM export, leading to an undefined import.
  fix Ensure `MakeErrorClass` is imported correctly using `import { MakeErrorClass } from 'fejl'` for ESM projects. The function itself returns a class constructor, so you would extend it, not instantiate it directly: `class MyError extends MakeErrorClass(...) {}`.

• Error: The configuration file is invalid (when I passed a different message to the constructor)

  cause Fejl's `MakeErrorClass` prioritizes the default message defined when creating the error class over any message argument passed to the constructor during instantiation.
  fix This is the intended behavior of `fejl`. If you need a dynamic error message, either create the class without a default message: `class MyError extends MakeErrorClass() {}`, or pass your dynamic message as a custom property: `new MyError(null, { myDynamicMessage: '...' })`.

Warnings

• breaking Fejl v4.0.0 introduced ESM support and removed the `make-error` dependency. This means `require()` statements will no longer work, and projects must use ES module `import` syntax. Additionally, the internal mechanism for extending `Error` changed, which might affect highly customized error implementations.
  Fix: Migrate your codebase to use ES module `import` statements. If you were directly leveraging `make-error` internals, you may need to refactor your custom error definitions.
• breaking With v4.0.0, the minimum supported Node.js version was bumped to Node.js 18. Running `fejl` on older Node.js versions will result in compatibility errors due to package.json `exports` field and other modern syntax.
  Fix: Upgrade your Node.js runtime environment to version 18 or newer.
• gotcha When creating a custom error class with `MakeErrorClass`, the `message` provided during class definition (e.g., `'Default Message'`) takes precedence over any message passed directly to the constructor when instantiating the error (e.g., `new MyError('My custom message')`). The constructor message will be ignored for the `message` property.
  Fix: If you need a dynamic message, either define the error class without a default message, or store the dynamic message in a custom property on the error instance, rather than relying on it to override the default `message`.
• breaking Fejl v3.0.0 bumped the minimum supported Node.js version to Node.js 14. While v4 now requires Node 18, users upgrading from versions prior to v3 should be aware of this intermediate breaking change.
  Fix: Upgrade Node.js to version 14 or higher (or 18+ if using Fejl v4).

Install

• npm install fejl npm
• yarn add fejl yarn
• pnpm add fejl pnpm

Imports

• MakeErrorClass
  wrong:

  const { MakeErrorClass } = require('fejl')

  correct:

  import { MakeErrorClass } from 'fejl'

  Fejl v4+ is ESM-only; CommonJS `require` will lead to errors.
• NotFound
  wrong:

  import NotFound from 'fejl/lib/http'

  correct:

  import { NotFound } from 'fejl'

  Specific HTTP errors like `NotFound` are named exports from the main package. Direct path imports might not be stable or work with ESM exports.
• InvalidConfigError
  wrong:

  import { InvalidConfigError } from 'fejl'

  correct:

  class MyCustomError extends MakeErrorClass('Default Message') {}

  `InvalidConfigError` is an example of a *user-defined* error class using `MakeErrorClass`, not a pre-exported symbol from the `fejl` package itself.

Quickstart

Demonstrates creating a custom error class with default properties, handling it, and using static assertion methods with built-in HTTP errors.

import { MakeErrorClass, NotFound } from 'fejl';

// 1. Create a custom error class with a default message and properties
class InvalidConfigError extends MakeErrorClass(
  'The configuration file is invalid',
  { infoUrl: 'https://example.com/error-info' }
) {}

// 2. Demonstrate throwing and catching a custom error
try {
  throw new InvalidConfigError('Custom message ignored');
} catch (err) {
  console.log(`Error Name: ${err.name}`); // InvalidConfigError
  console.log(`Error Message: ${err.message}`); // The configuration file is invalid (default message is used)
  console.log(`Error Info URL: ${err.infoUrl}`); // https://example.com/error-info
  console.log(`Is instance of InvalidConfigError? ${err instanceof InvalidConfigError}`); // true
}

// 3. Use a built-in HTTP error with static assertion
class UserNotFoundError extends NotFound {}

function getUserById(id) {
  const user = id === 1 ? { id: 1, name: 'Alice' } : null;
  // Use static assert to throw if 'user' is falsy
  UserNotFoundError.assert(user, `User with ID ${id} not found.`);
  return user;
}

try {
  getUserById(2);
} catch (err) {
  console.log(`\nHTTP Error Name: ${err.name}`); // NotFound
  console.log(`HTTP Error Message: ${err.message}`); // User with ID 2 not found.
  console.log(`HTTP Status Code: ${err.statusCode}`); // 404
}