youch-core

Error parser to parse an error instance into a collection of frames

[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] [![license-image]][license-url]

Introduction

The youch-core package contains the Error parser used by youch to pretty print Errors on the Web and the terminal.

It is a low-level package and you will only use it if you want to create your own Error printer while re-using the core Error parsing logic.

Installation

Install the package from the npm registry as follows.

npm i @poppinss/dumper

yarn add @poppinss/dumper

pnpm add @poppinss/dumper

Usage

You may parse an error using the ErrorParser.parse method. The parse method accepts the erorr object and returns back a Promise with ParsedError.

import { ErrorParser } from 'youch-core'

/**
 * Error object to parse
 */
const error = new Error('Something went wrong')

/**
 * Create parser instance and parse the error
 */
const parser = new ErrorParser()
const parsedError = await parser.parse(error)

The parsedError.frames property is an array of stack frames with the filename, line number and the source code snippet for the given frame in the stack.

parsedError.frames.forEach((frame) => {
  console.log(`${frame.type}: ${frame.fileName}:${frame.lineNumber}`)
})

Using a custom source code loader

The ErrorParser reads the source code of files within the stack trace using the Node.js fs module. However, you can override this default and provide a custom source loader using the parser.defineSourceLoader method.

[!NOTE] The defineSourceLoader method is called for every frame within the stack traces. Therefore, you must perform the necessary checks before attempting to read the source code of a file. For example, you must not attempt to read the source code for fileNames pointing to native code.

const parser = new ErrorParser()

parser.defineSourceLoader(async (stackFrame) => {
  if (stackFrame.type !== 'native') {
    stackFrame.source = await someFunctionToGetFileSource(stackFrame.fileName)
  }
})

Contributing

One of the primary goals of Poppinss is to have a vibrant community of users and contributors who believes in the principles of the framework.

We encourage you to read the contribution guide before contributing to the framework.

Code of Conduct

In order to ensure that the Poppinss community is welcoming to all, please review and abide by the Code of Conduct.

License

The youch-core package is open-sourced software licensed under the MIT license.

[gh-workflow-url]: https://github.com/poppinss/youch-core/actions/workflows/checks.yml 'Github action'

[npm-url]: https://npmjs.org/package/youch-core 'npm'

[license-url]: LICENSE.md 'license'