JSPM – @visulima/error@5.0.4

Package Exports

@visulima/error
@visulima/error/code-frame
@visulima/error/error
@visulima/error/package.json
@visulima/error/solution
@visulima/error/solution/ai
@visulima/error/solution/ai/prompt
@visulima/error/stacktrace

Readme

Visulima error

Error with more than just a message, stacktrace parsing and sourcemap loading.

[][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]

^{Daniel Bannert's open source work is supported by the community on GitHub Sponsors}

Install

npm install @visulima/error

yarn add @visulima/error

pnpm add @visulima/error

Optional: AI integration

If you want to generate AI-powered solution hints, install these optional peer dependencies in your app:

# pnpm
pnpm add ai

# npm
npm i ai

# yarn
yarn add ai

Usage

Extend the VisulimaError

import { VisulimaError } from "@visulima/error";

class MyError extends VisulimaError {
    constructor(message: string) {
        super({
            name: "MyError",
            message,
        });
    }
}

throw new MyError("My error message");

// or

const error = new MyError("My error message");

error.hint = "My error hint";

throw error;

Get all causes in a error

import { getErrorCauses } from "@visulima/error";

const error = new Error("My error message");
const error2 = new Error("Nested Error");

error.cause = error2;

// The getErrorCauses function will return an array of all causes in the error in the order they occurred.
const causes = getErrorCauses(error);

console.log(causes);

// [
//     {
//         message: "My error message",
//         name: "Error",
//         stack: "Error: My error message\n    at Object.<anonymous> (/visulima/packages/error/src/index.ts:2:16)",
//     },
//     {
//         message: "Nested Error",
//         name: "Error",
//         stack: "Error: Nested Error\n    at Object.<anonymous> (/visulima/packages/error/src/index.ts:3:16)",
//     },
// ];

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.

import { codeFrame } from "@visulima/error";

const source = "const x = 10;\nconst error = x.y;\n";
const loc = { column: 16, line: 2 };

const frame = codeFrame(source, { start: loc });

console.log(frame);
//   1 | const x = 10;
// > 2 | const error = x.y;
//     |                ^

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)

import { parseStacktrace } from "@visulima/error";

const error = new Error("My error message");

const stack = parseStacktrace(error);

console.log(stack);

// [
//     {
//         column: 16,
//         file: "file:///Users/danielbannert/Projects/visulima/packages/error/src/index.ts",
//         line: 2,
//         methodName: "Object.<anonymous>",
//         raw: "    at Object.<anonymous> (/visulima/packages/error/src/index.ts:2:16)",
//         type: undefined, // optional property, can be undefined, "eval", "native", or "internal"
//         evalOrigin: undefined, // optional property only available if the stacktrace contains eval
//     },
//     ...and so on
// ];

Format stacktrace to a string

Turn parsed frames into a printable stack string (Node-style), optionally with a header line.

import { parseStacktrace, stringifyStackFrames, formatStackFrameLine } from "@visulima/error";

const error = new Error("Boom");

const frames = parseStacktrace(error);

// Full stack as a single string with a header ("Error: Boom")
const stackText = stringifyStackFrames(frames, {
    header: { name: error.name, message: error.message },
});
console.log(stackText);

// Format a single frame line (e.g., for custom rendering)
const firstLine = formatStackFrameLine(frames[0]);

API

stringifyStackFrames(frames, options?)
- frames: Trace[] — parsed frames from parseStacktrace
- options.header: { name?: string; message?: string } — optional first-line header
formatStackFrameLine(frame)
- frame: Trace
- returns a single formatted line like " at myMethod (/path/file.ts:10:5)"

Solutions (finders)

Generate helpful hints to fix an error. Two finders ship out of the box:

Rule-based finder: provides best-effort fixes for common errors (ESM/CJS mix, missing default export, DNS issues, hydration mismatch, etc.)
Error-hint finder: reads error.hint you attach to an Error or VisulimaError

Both return a Solution ({ header?: string; body: string }) or undefined.

import { codeFrame } from "@visulima/error";
import { ruleBasedFinder, errorHintFinder } from "@visulima/error";

const error = new Error("Cannot read properties of undefined (reading 'x')");

const source = "const o = undefined\nconsole.log(o.x)\n";
const snippet = codeFrame(source, { start: { line: 2, column: 13 } });

const fileCtx = {
    file: "/path/to/file.ts",
    line: 2,
    language: "ts",
    snippet,
};

// 1) Rule-based finder
const ruleHint = await ruleBasedFinder.handle(error, fileCtx);
if (ruleHint) {
    console.log(ruleHint.header);
    console.log(ruleHint.body);
}

// 2) Error-hint finder (reads error.hint)
const custom = new Error("failed") as Error & { hint?: unknown };
custom.hint = ["Check the environment variables.", "Ensure the service is reachable."];
const hintHint = await errorHintFinder.handle(custom, { file: "", line: 0 });

AI solution helper (optional)

You can build an AI prompt with rich context and render the LLM result into a nice HTML snippet.

import { aiPrompt, aiSolutionResponse } from "@visulima/error/solution/ai";
// or
// import aiPrompt from "@visulima/error/solution/ai/prompt";

const prompt = aiPrompt({
    applicationType: undefined,
    error,
    file: fileCtx,
});

// Send `prompt` to your LLM of choice.
// When you receive the model's text output, format it for display:
const html = aiSolutionResponse(modelText);

You may also use a convenience finder that calls an AI provider for you (requires optional peer dep ai):

import { aiFinder } from "@visulima/error/solution/ai";
import { createOpenAI } from "@ai-sdk/openai";

const client = createOpenAI(apiKey ? { apiKey } : undefined);

const findAI = aiFinder(client(modelId), {
    temperature: 0,
});

const aiHint = await findAI.handle(error, fileCtx);

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.

import { serializeError } from "@visulima/error";

const error = new TypeError("example");
const errorObject = serializeError(error);
// Plain object: { name: 'TypeError', message: 'example', stack: '...' }

const errorString = JSON.stringify(errorObject);
const newErrorObject = JSON.parse(errorString);

`deserialize` an error object

Deserialize a previously serialized error back to an Error instance.

Automatically detects error-like objects
Reconstructs proper Error instances with correct constructors
Handles custom error classes registered with addKnownErrorConstructor
Supports AggregateError deserialization
Preserves error properties and cause chains
Wraps non-error-like objects in NonError

import { serializeError, deserializeError } from "@visulima/error";

const error = new TypeError("example");
const serialized = serializeError(error);

// Deserialize back to Error instance
const deserialized = deserializeError(serialized);

console.log(deserialized instanceof TypeError); // true
console.log(deserialized.message); // "example"

Registering Custom Error Constructors

import { addKnownErrorConstructor, deserializeError } from "@visulima/error";

class CustomError extends Error {
    constructor(message: string, code: number) {
        super(message);
        this.name = "CustomError";
        this.code = code;
    }
}

// Register the custom error constructor
addKnownErrorConstructor(CustomError);

// Now it can be deserialized properly
const serialized = { name: "CustomError", message: "test", code: 42 };
const deserialized = deserializeError(serialized);

console.log(deserialized instanceof CustomError); // true
console.log(deserialized.code); // 42

NonError for Non-Error Objects

When deserializing objects that don't look like errors, they're wrapped in a NonError:

import { deserializeError, NonError } from "@visulima/error";

const deserialized = deserializeError({ foo: "bar" });

console.log(deserialized instanceof NonError); // true
console.log(deserialized.message); // '{"foo":"bar"}'

renderError - pretty print an error

import { renderError } from "@visulima/error";

const error = new Error("This is an error message");

console.log(renderError(error));

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

colorized output

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

colorized output

API

error

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

options

Type: object

options.color

Type: object
The color options.