typescript.md

TypeScript

The API is fully typed for TypeScript users (>= 4.7).

Error properties and methods

Error classes' and instances' props, aggregate errors and custom methods/properties are typed.

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

Plugins

Plugin methods, properties and options are typed.

import ModernError from 'modern-errors'

// This plugin adds a `BaseError.httpResponse(error)` method
import modernErrorsHttp from 'modern-errors-http'

const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsHttp],
})

const error = new BaseError('Wrong user name', {
  http: { title: false }, // Type error: `title` must be a string
})
const httpResponse = BaseError.httpResponse(error) // Inferred type: response object

Narrowing

When catching exceptions, their type can be narrowed using instanceof.

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`
  }
}

Type inference

Types are automatically inferred: no explicit type declaration is needed. typeof, ReturnType, etc. can be used to retrieve the type of a variable or method.

const printErrorClass = function (
  ErrorClass: ReturnType<typeof BaseError.subclass>,
) {
  // ...
}

const InputError = BaseError.subclass('InputError')
printErrorClass(InputError)

Wide types

The following types are exported: ErrorInstance, ErrorClass, ClassOptions, InstanceOptions, MethodOptions, Plugin and Info.

Those types are wide: they do not include any information about specific props, aggregate errors nor custom methods/properties. However, they can include specific plugins' methods, properties and options by passing those as a generic parameter, such as ErrorClass<[typeof plugin]>.

They should only be used to type unknown error instances and classes, when no variable nor type inference is available. For example, they can be useful when creating plugins.