---

---

Install

1npm install @visulima/error

1yarn add @visulima/error

1pnpm add @visulima/error

Usage

Extend the VisulimaError

1import { VisulimaError } from "@visulima/error";
2
3class MyError extends VisulimaError {
4    constructor(message: string) {
5        super({
6            name: "MyError",
7            message,
8        });
9    }
10}
11
12throw new MyError("My error message");
13
14// or
15
16const error = new MyError("My error message");
17
18error.hint = "My error hint";
19
20throw error;

Get all causes in a error

1import { getErrorCauses } from "@visulima/error";
2
3const error = new Error("My error message");
4const error2 = new Error("Nested Error");
5
6error.cause = error2;
7
8// The getErrorCauses function will return an array of all causes in the error in the order they occurred.
9const causes = getErrorCauses(error);
10
11console.log(causes);
12
13// [
14//     {
15//         message: "My error message",
16//         name: "Error",
17//         stack: "Error: My error message\n    at Object.<anonymous> (/visulima/packages/error/src/index.ts:2:16)",
18//     },
19//     {
20//         message: "Nested Error",
21//         name: "Error",
22//         stack: "Error: Nested Error\n    at Object.<anonymous> (/visulima/packages/error/src/index.ts:3:16)",
23//     },
24// ];

Pretty Code Frame

Display a pretty code frame with the error location.

Note: Tabs can be used in the source code, codeFrame transforms them to spaces based on the tabWidth option. The default tabWidth is 4, to disable the transformation, set tabWidth to false.

1import { codeFrame } from "@visulima/error";
2
3const source = "const x = 10;\nconst error = x.y;\n";
4const loc = { column: 16, line: 2 };
5
6const frame = codeFrame(source, { start: loc });
7
8console.log(frame);
9//   1 | const x = 10;
10// > 2 | const error = x.y;
11//     |                ^

API

source

Type: string

The source code to frame.

location

Type: object

The location of the error.

location.start

Type: object

The location of the start of the frame.

location.start.line

Type: number

The line number of the error.

location.start.column

Type: number

The column number of the error.

location.end

Type: object

The location of the end of the frame.

location.end.line

Type: number

The line number of the error.

location.end.column

Type: number

The column number of the error.

options

Type: object

options.linesAbove

Type: number

Default: 2

The number of lines to show above the error.

options.linesBelow

Type: number

Default: 3

The number of lines to show below the error.

options.tabWidth

Type: number | false

Default: 4

Stacktrace

Browser older than 6 years are not supported.

Currently supported browsers/platforms:

• Firefox
• Chrome
• Webkit / Safari
• Edge
• Node / Node V8
• Opera (Chromium based)

1import { parseStacktrace } from "@visulima/error";
2
3const error = new Error("My error message");
4
5const stack = parseStacktrace(error);
6
7console.log(stack);
8
9// [
10//     {
11//         column: 16,
12//         file: "file:///Users/danielbannert/Projects/visulima/packages/error/src/index.ts",
13//         line: 2,
14//         methodName: "Object.<anonymous>",
15//         raw: "    at Object.<anonymous> (/visulima/packages/error/src/index.ts:2:16)",
16//         type: undefined, // optional property, can be undefined, "eval", "native", or "internal"
17//         evalOrigin: undefined, // optional property only available if the stacktrace contains eval
18//     },
19//     ...and so on
20// ];

API

error

Type: Error

The error to parse.

options

Type: object

options.filter

Type: Function

A function to filter the stack frames.

options.frameLimit

Type: number

The maximum number of frames to parse.

serialize an error object

• Ensures errors are safe to serialize with JSON
• Can be used as error.toJSON()
• Deep serialization, including transforming
• Custom serialization (e.g. YAML or process.send())
• Keeps both native (TypeError, etc.) and custom error classes
• Preserves errors' additional properties
• Can keep constructor's arguments
• Works recursively with error.cause and AggregateError
• Buffer properties are replaced with [object Buffer]
• Circular references are handled.
• If the input object has a .toJSON() method, then it's called instead of serializing the object's properties.
• It's up to .toJSON() implementation to handle circular references and enumerability of the properties.

1import { serializeError } from "@visulima/error";
2
3const error = new TypeError("example");
4const errorObject = serializeError(error);
5// Plain object: { name: 'TypeError', message: 'example', stack: '...' }
6
7const errorString = JSON.stringify(errorObject);
8const newErrorObject = JSON.parse(errorString);

renderError - pretty print an error

1import { renderError } from "@visulima/error";
2
3const error = new Error("This is an error message");
4
5console.log(renderError(error));
6
7// Error: This is an error message
8//
9// at <unknown> file:///home/visulima/visulima/examples/error/node/render-error.js:5
10//   1 | import { renderError } from "@visulima/error";
11//   2 |
12//   3 | const error = new Error("This is an error message");
13//   4 |
14// ❯ 5 | console.log(renderError(new Error("This is an error message")));
15//     |                         ^
16//   6 |
17//
18// at ModuleJob.run node:internal/modules/esm/module_job:195
19// at async ModuleLoader.import node:internal/modules/esm/loader:336
20// at async loadESM node:internal/process/esm_loader:34
21// at async handleMainPromise node:internal/modules/run_main:106

colorized output

Use the @visulima/colorize, chalk or some other package to colorize the output.

API

error

Type: AggregateError | Error | VisulimaError
The error to render.

options

Type: object

options.color

Type: object
The color options.

options.cwd

Type: string

The current working directory.

options.displayShortPath

Type: boolean
Default: false

Display the short path.

options.framesMaxLimit

Type: number
Default: Number.Infinity

The maximum number of frames to display.

options.hideErrorCauseCodeView

Type: boolean
Default: false

Hide the error cause code view.

options.hideErrorCodeView

Type: boolean
Default: false

Hide the error code view.

options.hideErrorTitle

Type: boolean
Default: false

Hide the error title.

options.hideMessage

Type: boolean
Default: false

Hide the error message.

captureRawStackTrace

Capture a raw stack trace.

1import { captureRawStackTrace } from "@visulima/error";
2
3const stack = captureRawStackTrace();
4
5console.log(stack);

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• Daniel Bannert
• All Contributors

About

Related Projects

• baseerr: merge another error with additional properties.
• callsites: get callsites from the V8 stack trace API.
• explain-error: wrap an error with additional explanation.
• error-wrapper: merges the stack of another error to its own.
• errwischt/stacktrace-parser
• trace: create super long stack traces.
• clarify: remove node related stack trace noise.
• piotr-szewczyk/stacktrace-parser-node
• pretty-error: make the call stacks clear.
• node-pretty-exceptions - Pretty and more helpful uncaught exceptions, automatically
• youch-terminal - Display youch error message on terminal
• ono: allow different types of error to be thrown.
• stacktracejs/error-stack-parser
• marvinhagemeister/errorstacks Tiny library to parse error stack traces
• getsentry/sentry-javascript
• serialize-error - Serialize/deserialize an error into a plain object
• baseerr: merge another error with additional properties.
• callsite-record - Create fancy log entries for errors and function call sites

License

The visulima error is open-sourced software licensed under the [MIT][license-url]

[typescript-url]: https://www.typescriptlang.org/ "TypeScript" "typescript" [license-image]: https://img.shields.io/npm/l/@visulima/error?color=blueviolet&style=for-the-badge [license-url]: LICENSE.md "license" [npm-image]: https://img.shields.io/npm/v/@visulima/error/latest.svg?style=for-the-badge&logo=npm [npm-url]: https://www.npmjs.com/package/@visulima/error/v/latest "npm"