{"id":15615,"library":"fejl","title":"Fejl Error Utility","description":"Fejl is a JavaScript and TypeScript utility library designed to streamline the creation and management of custom error classes in Node.js applications. Currently in its stable v4.0.1 release, Fejl offers a predictable release cadence with major versions typically introducing significant changes like ESM support or Node.js version bumps. Its core functionality revolves around `MakeErrorClass`, which allows developers to define custom error types with default messages and properties, drastically reducing boilerplate compared to native `Error` extension. Key differentiators include static `assert` and `makeAssert` methods for concise conditional error throwing, and a collection of pre-defined HTTP error classes. Fejl aims to improve code readability and maintainability by centralizing error definitions and providing convenient assertion patterns.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/jeffijoe/fejl","tags":["javascript","typescript"],"install":[{"cmd":"npm install fejl","lang":"bash","label":"npm"},{"cmd":"yarn add fejl","lang":"bash","label":"yarn"},{"cmd":"pnpm add fejl","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Fejl v4+ is ESM-only; CommonJS `require` will lead to errors.","wrong":"const { MakeErrorClass } = require('fejl')","symbol":"MakeErrorClass","correct":"import { MakeErrorClass } from 'fejl'"},{"note":"Specific HTTP errors like `NotFound` are named exports from the main package. Direct path imports might not be stable or work with ESM exports.","wrong":"import NotFound from 'fejl/lib/http'","symbol":"NotFound","correct":"import { NotFound } from 'fejl'"},{"note":"`InvalidConfigError` is an example of a *user-defined* error class using `MakeErrorClass`, not a pre-exported symbol from the `fejl` package itself.","wrong":"import { InvalidConfigError } from 'fejl'","symbol":"InvalidConfigError","correct":"class MyCustomError extends MakeErrorClass('Default Message') {}"}],"quickstart":{"code":"import { MakeErrorClass, NotFound } from 'fejl';\n\n// 1. Create a custom error class with a default message and properties\nclass InvalidConfigError extends MakeErrorClass(\n  'The configuration file is invalid',\n  { infoUrl: 'https://example.com/error-info' }\n) {}\n\n// 2. Demonstrate throwing and catching a custom error\ntry {\n  throw new InvalidConfigError('Custom message ignored');\n} catch (err) {\n  console.log(`Error Name: ${err.name}`); // InvalidConfigError\n  console.log(`Error Message: ${err.message}`); // The configuration file is invalid (default message is used)\n  console.log(`Error Info URL: ${err.infoUrl}`); // https://example.com/error-info\n  console.log(`Is instance of InvalidConfigError? ${err instanceof InvalidConfigError}`); // true\n}\n\n// 3. Use a built-in HTTP error with static assertion\nclass UserNotFoundError extends NotFound {}\n\nfunction getUserById(id) {\n  const user = id === 1 ? { id: 1, name: 'Alice' } : null;\n  // Use static assert to throw if 'user' is falsy\n  UserNotFoundError.assert(user, `User with ID ${id} not found.`);\n  return user;\n}\n\ntry {\n  getUserById(2);\n} catch (err) {\n  console.log(`\\nHTTP Error Name: ${err.name}`); // NotFound\n  console.log(`HTTP Error Message: ${err.message}`); // User with ID 2 not found.\n  console.log(`HTTP Status Code: ${err.statusCode}`); // 404\n}\n","lang":"typescript","description":"Demonstrates creating a custom error class with default properties, handling it, and using static assertion methods with built-in HTTP errors."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js runtime environment to version 18 or newer.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade Node.js to version 14 or higher (or 18+ if using Fejl v4).","message":"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.","severity":"breaking","affected_versions":"3.0.0 - <4.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` to import `fejl` in a CommonJS module, but `fejl` v4+ is an ES Module.","error":"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."},{"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(...) {}`.","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.","error":"TypeError: MakeErrorClass is not a constructor"},{"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: '...' })`.","cause":"Fejl's `MakeErrorClass` prioritizes the default message defined when creating the error class over any message argument passed to the constructor during instantiation.","error":"Error: The configuration file is invalid (when I passed a different message to the constructor)"}],"ecosystem":"npm"}