modern-errors

You can wrap an existing error inside a new error using the cause option. modern-errors enhances the standard JavaScript cause behavior by directly merging the inner error into the outer error. This includes merging:

• message
• stack
• name
• AggregateError.errors
• Additional properties from props

Message Formatting: The outer error message is appended to the inner error message. If the outer message ends with : or :\n, it is prepended instead to maintain clean formatting.

try {
  // ...
} catch (cause) {
  // The inner error's message and stack are merged into InputError
  throw new InputError('Could not read the file.', { cause })
}

modern-errors automatically infers types for error properties (props), aggregate errors, and custom methods/properties defined in the custom block. You do not need to provide explicit type declarations for these values.

When using subclass, the resulting error instance will have correctly typed properties based on the values provided in the configuration.

const BaseError = ModernError.subclass('BaseError', {
  props: { userId: 5 as const },
  custom: class extends ModernError {
    isUserInput() {
      return true as const
    }
  },
})
const error = new BaseError('Wrong user name', {
  props: { userName: 'Alice' as const },
})
const { userId, userName } = error // Inferred type: `5` and `"Alice""
const result = error.isUserInput() // Inferred type: `true`

When using subclass(), properties defined in the parent's props option are inherited by all descendants. This allows you to define shared metadata (like isError: true) at the top of your hierarchy.

Subclasses can also define their own specific properties which will be merged with the parent's.

export const BaseError = ModernError.subclass('BaseError', {
  props: { isError: true },
})
export const InputError = BaseError.subclass('InputError', {
  props: { isUserError: true },
})

const error = new InputError('...')
console.log(error.isError) // true
console.log(error.isUserError) // true
console.log(error instanceof BaseError) // true
console.log(error instanceof InputError) // true

When designing modern-errors plugins, follow these principles to ensure they are safe and reusable:

• Avoid Global State: Do not modify global objects (like Error.prepareStackTrace()). This ensures your plugin can be used by other libraries without side effects.
• Concurrency Safety: Do not store stateful objects (like class instances or network connections) in the global plugin state. This ensures plugins are safe for parallel async logic. Instead:
  • Provide methods that return these objects.
  • Require users to create the objects and pass them as arguments to plugin methods.
• Separation of Concerns: If a plugin contains logic not specific to modern-errors, split it into a separate library. This keeps the plugin focused on integration and allows the core logic to be used independently.

When catching exceptions, you can narrow the type of the caught error to a specific error class using the standard TypeScript instanceof operator. This allows you to safely access properties and methods specific to that error class.

const InputError = BaseError.subclass('InputError', {
  props: { isUserError: true as const },
})

try {
  // ...
} catch (error) {
  // Narrows `error` type to `InputError`
  if (error instanceof InputError) {
    const { isUserError } = error // Inferred type: `true`
  }
}

Install the core package via npm. If you use any plugins, you must install them separately as well.

npm install modern-errors

Requirements & Compatibility:

• Node.js >= 18.18.0
• Works in browsers
• ES Module only: Must be loaded using import or import(). It does not support require().
• TypeScript: Must be configured to output ES modules, not CommonJS.

The modern-errors API is fully typed for TypeScript (version 4.7 or higher). Because the package is an ES module, you must configure your TypeScript project to output ES modules rather than CommonJS.

Refer to the TypeScript ESM guide for configuration details.

In modern-errors, errors that are not explicitly caught and wrapped in a known error class are considered unknown (often indicating a bug). You can normalize these unexpected exceptions using BaseError.normalize(error, UnknownError) to ensure they follow the library's structure, apply plugins, and have a valid class.

To ensure every error thrown from a module's main entry point is valid, wrap the top-level logic in a try/catch block and use normalize in the catch block.

export const UnknownError = BaseError.subclass('UnknownError')

try {
  return regExp.test(value)
} catch (error) {
  // Now an `UnknownError` instance
  throw BaseError.normalize(error, UnknownError)
}