@twreporter/errors

This package provides the helpers for handling errors in the The Reporter website.

Inspired by package errors for Go language and the related article by Dave Cheney.

• @twreporter/errors
  • Use
    • errors.helpers.wrap
    • errors.helpers.unwrap
    • errors.helpers.cause
    • errors.helpers.printAll
    • errors.helpers.printOne
    • errors.helpers.annotateAxiosError
    • errors.AnnotatingError
      • public properties
  • Development
    • Dev
    • Build
    • Publish

Reference:

• JavaScript Errors and Stack Traces in Depth
• V8 Stack trace API
• Don’t just check errors, handle them gracefully

Use

errors.helpers.wrap

Annotate the error with name, message and payload. It will return a new error that is an instance of errors.AnnotatingError.

See source code and JSDoc for all parameters

Example:

import errors from '@twreporter/errors'

function doSomething() {
  try {
    const someArguments = {
      /* ... */
    }
    invokeSomethingWithError(...someArguments)
  } catch (error) {
    console.error(
      errors.helpers.wrap(
        error,
        'ErrorType',
        'failed to invoke something',
        { args: someArguments },
        invokeSomethingWithError
      )
    )
  }
}

errors.helpers.unwrap

It will return the previous error in the chain that the input error belongs to.

If there is no pointer of previous error saved in the input error, it will return null.

It works like the Unwrap method of errors in Go@^1.13.

See source code and JSDoc for all parameters

Example:

import errors from '@twreporter/errors'

function doSomething() {
  try {
    const someArguments = {
      /* ... */
    }
    invokeSomethingWithError(...someArguments)
  } catch (error) {
    /* list all error.name in errors chain */
    let _error = error
    const chain = []
    while (_error) {
      chain.push(_error)
      _error = errors.helpers.unwrap(_error)
    }
    /* ... handle the chain */
  }
}

errors.helpers.cause

It will return the earliest error in the chain that the input error belongs to.

See source code and JSDoc for all parameters

import errors from '@twreporter/errors'

function nestedFailedTask() {
  throw new Error('nested failure')
}

function invokeSomething() {
  const someArguments = { bar: 'bar' }
  try {
    nestedFailedTask()
  } catch (error) {
    throw errors.helpers.wrap(
      error,
      'ErrorType',
      'failed to invoke nested task',
      { args: someArguments }
    )
  }
}

function doSomething() {
  const someArguments = { foo: 'foo' }
  try {
    invokeSomething(someArguments)
  } catch (error) {
    const annotatingError = errors.helpers.wrap(
      error,
      'ErrorType',
      'failed to invoke something',
      { args: someArguments }
    )
    errors.helpers.cause(annotatingError) === 'nested failure' /* true */
  }
}

log out:

ErrorType: failed to invoke something
    at doSomething (/test.js:12:44)
  payload {"args":{"foo":"foo"}}

errors.helpers.printAll

See source code and JSDoc for all parameters

import errors from '@twreporter/errors'

function nestedFailedTask() {
  throw new Error('nested failure')
}

function invokeSomething() {
  const someArguments = { bar: 'bar' }
  try {
    nestedFailedTask()
  } catch (error) {
    throw errors.helpers.wrap(
      error,
      'ErrorType',
      'failed to invoke nested task',
      { args: someArguments }
    )
  }
}

function doSomething() {
  const someArguments = { foo: 'foo' }
  try {
    invokeSomething(someArguments)
  } catch (error) {
    const annotatingError = errors.helpers.wrap(
      error,
      'ErrorType',
      'failed to invoke something',
      { args: someArguments }
    )
    const message = errors.helpers.printAll(annotatingError, {
      withStack: true,
      withPayload: true,
    })
    console.error(message)
  }
}

doSomething()

log out:

Error: nested failure
 at nestedFailedTask (/test.js:4:9)
ErrorType: failed to invoke nested task
 at invokeSomething (/test.js:12:26)
 > payload {"args":{"bar":"bar"}}
ErrorType: failed to invoke something
 at doSomething (/test.js:21:44)
 > payload {"args":{"foo":"foo"}}

errors.helpers.printOne

See source code and JSDoc for all parameters

import errors from '@twreporter/errors'

function invokeSomethingWithError() {
  throw new Error('nested error')
}

function doSomething() {
  const someArguments = { foo: 'foo' }
  try {
    invokeSomethingWithError(someArguments)
  } catch (error) {
    const annotatingError = errors.helpers.wrap(
      error,
      'ErrorType',
      'failed to invoke something',
      { args: someArguments }
    )
    const message = errors.helpers.printOne(annotatingError, {
      withStack: true,
      withPayload: true,
    })
    console.error(message)
  }
}

doSomething()

log out:

ErrorType: failed to invoke something
 at doSomething (/test.js:12:44)
 > payload {"args":{"foo":"foo"}}

errors.helpers.annotateAxiosError

See source code and JSDoc for all parameters

import errors from '@twreporter/errors'
import axios from 'axios'

async function doSomething() {
  try {
    const someArguments = {
      /* ... */
    }
    await axios.get(someArguments)
  } catch (axiosError) {
    throw errors.helpers.annotateAxiosError(axiosError)
  }
}

errors.AnnotatingError

public properties

• name {string} the name of this error
• message {string} the message of this error
• payload {Object} the context information for better debugging
• stack {string} the stack trace from where the error be constructed. it contains the name and message of the error in the V8 engine

See source code and JSDoc for all parameters

Development

Dev

make dev

Build

make build

Publish

make publish