Lovely Error

Minimal, powerful, and highly customizable error parser and manager for JavaScript! 🚀

[!WARNING] Not stable yet!

Features

• Parser: Parsing error message and stack to meaningful objects.
• Exception Filter: This feature inspired by Java to handle different exceptions separately.
• Logger: Hmm! Not actually a logger, but it will pass the final neat string to your preferred logger.

Engines Compatibility

• V8 (NodeJS, Deno, Chromium, ...)
• Chakra (Edge)
• JavaScriptCore (Bun, Safari)
• SpiderMonkey (Firefox)

How to Use

Installation

1npm install lovely-error

1yarn add lovely-error

1pnpm add lovely-error

Constructor

To instantiate LovelyError you can pass two parameters. (your error instance [required], options to customize behavior [optional])

1try {
2  throw new Error('Something went wrong!');
3} catch (error) {
4  const lovelyError = new LovelyError(error, { includePackageTrace: true });
5}

Options

• includePackageTrace: Include traces that have been ended up in your package, or lib folders.
• includeProjectTrace: Include traces that is related to your project source code.
• includeInternalTrace: Include runtime internal traces.
• provideSupplementaryTrace: Some packages limited their errors trace, and as a result we won't have the error trace in our source code! This feature provides a supplementary trace next to the original trace that points where LovelyError instantiated to help you debug better!
• packagePathSignatures: In some environments you may have your packages in custom folders, so you can introduce them to lovely error recognize them as your lib folders.
• traceLimit: Will limit traces that would be parsed (not those that would be provided).

1type LovelyStackOptions = {
2  includePackageTrace?: boolean; // default: false
3  includeProjectTrace?: boolean; // default: true
4  includeInternalTrace?: boolean; // default: false
5  provideSupplementaryTrace?: boolean; // default: true
6  packagePathSignatures?: string[]; // default: []
7  traceLimit?: number; // default: 10
8};

This package has only three methods that can be accessed by instance or statically.

LovelyError.stack

This function simply return the parsed error.

1catch (error) {
2  // by instance
3  const lovelyError = new LovelyError(error, { includePackageTrace: true });
4  const stack = lovelyError.stack();
5
6  // by static function
7  const stack = LovelyError.stack(error, { includePackageTrace: true });
8}

The returned stack will have an structure like this:

1type LovelyTraceElement = {
2  method: {
3    name: string;
4    alias?: string;
5    parent?: string;
6  };
7  filePath: string;
8  line: string;
9  column: string;
10};
11
12type LovelyStack = {
13  exception: string;
14  message: string;
15  trace?: LovelyTraceElement[];
16  packageTrace?: LovelyTraceElement[];
17  projectTrace?: LovelyTraceElement[];
18  internalTrace?: LovelyTraceElement[];
19  stringTrace?: string;
20};

LovelyError.catch

This function will help you to handle your errors separately by their exception. (inspired by Java)

1catch (error) {
2  // by instance
3  const lovelyError = new LovelyError(error);
4
5  lovelyError.catch('IOException', (stack: LovelyStack) => {
6    console.log(`I just care about ${stack.exception}`);
7    console.log(`message: ${stack.message}`);
8  });
9
10  // by static function (not recommended for more than one)
11  LovelyError.catch(error, LovelyError.NO_EXCEPTION, (stack: LovelyStack) => {
12    console.log('Default error instance! Hmm...');
13  });
14}

LovelyError.log

Log provided stack in a neat way with your preferred logger (default: console.log), by this powerful and highly customizable function. Let me show what I mean by highly customizable. This is our base code without any configuration:

1class ConnectionException extends Error {
2  name = ConnectionException.name;
3
4  constructor(message) {
5    super(message);
6  }
7}
8
9const app = express();
10
11app.get('/', function rootHandler(req, res) {
12  try {
13    throw new ConnectionException('Failed to connect to target server!');
14  } catch (error) {
15    new LovelyError(error, {
16      includeInternalTrace: true,
17      includePackageTrace: true,
18    }).log();
19
20    res.send();
21  }
22});
23
24app.listen(3000);

Output: You see there is actually not much difference between this log and simply console.log(error);, but the power is you can change this to a completely different thing!

Options

• logger: A logger function.
• colorize: Add ANSI color codes to log string (turn it off if you are storing logs).
• verbose: Will include full filePath, and if you set it to false you will see a summarized filePath.
• colorPalette: Color scheme for each part of the log.

1type LovelyLogOptions = {
2  logger?: LoggerFunction | null; // default: console.log
3  colorize?: boolean; // default: true
4  verbose?: boolean; // default: true
5  colorPalette?: LogColorPalette;
6};

Color Palette Object

1export type ColorObject = { foreground: number; background?: number };
2
3export type LogColorPalette = {
4  exception?: ColorObject;
5  message?: ColorObject;
6  treeArrow?: ColorObject;
7  packageTrace?: ColorObject;
8  projectTrace?: ColorObject;
9  internalTrace?: ColorObject;
10};

Default Object:

1{
2  exception: {
3      foreground: ConsoleColor.TEXT_BLACK,
4      background: ConsoleColor.BACKGROUND_RED,
5  },
6  message: {
7      foreground: ConsoleColor.TEXT_RED,
8  },
9  treeArrow: {
10      foreground: ConsoleColor.TEXT_YELLOW,
11  },
12  packageTrace: {
13      foreground: ConsoleColor.TEXT_GRAY,
14  },
15  projectTrace: {
16      foreground: ConsoleColor.TEXT_WHITE,
17  },
18  internalTrace: {
19      foreground: ConsoleColor.TEXT_GRAY,
20  },
21},

[!NOTE] When you're filling log options, your missed properties will filled by this default object

Built-in Color Palette Templates

We provided some regular built-in palette templates to save your time!

Here is our template class that you can use:

1class ColorPaletteTemplate {
2  static ERROR_PALETTE = {
3    exception: {
4      foreground: ConsoleColor.TEXT_BLACK,
5      background: ConsoleColor.BACKGROUND_RED,
6    },
7    message: {
8      foreground: ConsoleColor.TEXT_RED,
9    },
10    treeArrow: {
11      foreground: ConsoleColor.TEXT_RED,
12    },
13  };
14  static WARNING_PALETTE = {
15    exception: {
16      foreground: ConsoleColor.TEXT_BLACK,
17      background: ConsoleColor.BACKGROUND_YELLOW,
18    },
19    message: {
20      foreground: ConsoleColor.TEXT_YELLOW,
21    },
22    treeArrow: {
23      foreground: ConsoleColor.TEXT_YELLOW,
24    },
25  };
26  static INFO_PALETTE = {
27    exception: {
28      foreground: ConsoleColor.TEXT_BLACK,
29      background: ConsoleColor.BACKGROUND_CYAN,
30    },
31    message: {
32      foreground: ConsoleColor.TEXT_CYAN,
33    },
34    treeArrow: {
35      foreground: ConsoleColor.TEXT_CYAN,
36    },
37  };
38  static DEBUG_PALETTE = {
39    exception: {
40      foreground: ConsoleColor.TEXT_WHITE,
41      background: ConsoleColor.BACKGROUND_MAGENTA,
42    },
43    message: {
44      foreground: ConsoleColor.TEXT_MAGENTA,
45    },
46    treeArrow: {
47      foreground: ConsoleColor.TEXT_MAGENTA,
48    },
49  };
50}

Final Example

Let's see another and more customized log to feel the difference:

1app.get('/', function rootHandler(req, res) {
2  try {
3    throw new ConnectionException('Failed to connect to target server!');
4  } catch (error) {
5    const lovelyError = new LovelyError(error, {
6      includeInternalTrace: true,
7      includePackageTrace: true,
8    });
9
10    // using template
11    lovelyError.log({
12      verbose: false,
13      colorPalette: ColorPaletteTemplate.INFO_PALETTE,
14    });
15
16    // using custom object
17    lovelyError.log({
18      verbose: false,
19      colorPalette: {
20        exception: {
21          background: ConsoleColor.BACKGROUND_GREEN,
22        },
23        message: {
24          foreground: ConsoleColor.TEXT_GREEN,
25        },
26        projectTrace: {
27          foreground: ConsoleColor.TEXT_GREEN,
28        },
29        packageTrace: {
30          foreground: ConsoleColor.TEXT_BLUE,
31        },
32      },
33    });
34
35    res.send();
36  }
37});

Output:

Don't know about you! But I like this more than simple console.log

Contribution

We didn't define any rule, and code of conduct yet, let's see how this package will grow first!
We invite everyone that interested to this project. Just open an issue or fork this repository and make a PR!

License

1MIT License
2
3Copyright (c) 2024 xvyashar
4
5Permission is hereby granted, free of charge, to any person obtaining a copy
6of this software and associated documentation files (the "Software"), to deal
7in the Software without restriction, including without limitation the rights
8to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9copies of the Software, and to permit persons to whom the Software is
10furnished to do so, subject to the following conditions:
11
12The above copyright notice and this permission notice shall be included in all
13copies or substantial portions of the Software.
14
15THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21SOFTWARE.