npm package: @golemio/golemio-errors
Description: Library of Error classes of the Data Platform System
Author: Operator ICT, a.s.
Latest version: 0.0.2
Deprecated: this package has been deprecated

# Golemio Errors Library

Minimal package with custom Error class extending the native built-in JavaScript `Error` class, providing extra funcionality and more capabilities for error handling.

Trying to adhere to [Node.js best practices](https://github.com/goldbergyoni/nodebestpractices#2-error-handling-practices).

Developed by http://operatorict.cz


## Prerequisites

- node.js (https://nodejs.org)
- yarn (https://yarnpkg.com)
- TypeScript (https://www.typescriptlang.org/)

## Installation

Install Node

Install all npm modules using command:
```
yarn
```

## Compilation of typescript code

To compile typescript code into js one-time

```
yarn run build
```
or run this, to watch all changes
```
yarn run build-watch
```
from the application's root directory.


## Usage

First, in your project folder create file `.npmrc` with connection to OICT private npm registry and then in your project's `package.json` set dependency to Errors
```
npm install golemio-errors --save

or

yarn add golemio-errors --save
```

Then import module, e.g.
```
import { CustomError } from "golemio-errors";
```

Our CustomError has:

- whole stack trace of original `Error`
- extends (thus is the type of) `Error`
- extra info about origin class
- extra info about error code
- distinguishes between operational errors (application error, app knows how to handle it) and fatal errors (app should gracefully die)
- string message (== only thing the native Error has)


You can use CustomError class as you would a standard JavaScript Error, you will just get additional info and more capabilities:

```
const found = await this.model.findOne(id);
if (!found ) {
    throw new CustomError("Id `" + id + "` not found", true, "MyModelClass", 404);
} 
```

you can add the underlying Error to get the whole stack trace:
```
try {
    const q = this.model.find("nonsense");
    return await q.exec();
} catch (err) {
    throw new CustomError("Database error", true, "MyModelClass", 500, err);
}
```

and the result you will get:
```
"MyModelClass" [500] Database error (ObjectParameterError: Parameter "filter" to find() must be an object, got nonsense)
CustomError: Database error
    at MyModel.<anonymous> ({path}\src\core\models\MyModel.ts:65:19)
    at Generator.throw (<anonymous>)
    at rejected ({path}\src\core\models\MyModel.ts:5:65)
    at process._tickCallback (internal/process/next_tick.js:68:7)
```

if you call .toString() on the error object in the error handler (or if you use our ErrorHandler class).

You can import the error handler function:

```
import { handleError } from "golemio-errors";
```
The handle function provides a central point for error handling in your application. It logs the error, kills the application if it's unknown non-operational (programmer) error. Returns "API response ready" object if it's a known operational error with one of the standard HTTP codes.

You can use it:

```
try {
    await functionThatThrowsCustomError();      // Can throw our CustomError class
    await jsBuiltInFunction();                  // Can throw a native built-in JavaScript Error
} catch (err) {                                 // Catches everything
    handleError(err);                           // Handles everything
}
```

or for example in Express error handler route
```
// Error handler to catch all errors sent by routers (propagated through next(err))
this.express.use((err: any, req: Request, res: Response, next: NextFunction) => {
    handleError(err).then((error) => {
        if (error) {
            log.silly("Error caught by the router error handler.");
            res.status(error.error_status || 500).send(error);
        }
    });
});
```

and the result can be i.e.:
```
{ 
    error_message: "Not Found.", 
    error_status: 404 
}
```
or in development environment (NODE_ENV set to "development"):
```
{
    "error_message": "Not Found.",
    "error_status": 404,
    "stack_trace": "CustomError: Id `nonsense` not found\n    
    at MyModel.<anonymous> ({path}y\\dist\\core\\models\\MyModel.js:116:23)\n    
    at Generator.next (<anonymous>)\n
    at fulfilled ({path}\\dist\\core\\models\\MyModel.js:4:58)\n    
    at process._tickCallback (internal/process/next_tick.js:68:7)"
}
```

## Logging

Logging uses `Winston` for standard logging with levels and `debug` (https://www.npmjs.com/package/debug) for debugging.

All logs with `silly` and `debug` level are printed as standard log (if appropriate log level is set) using Winston as well as using `debug` module with `"golemio:errors"` settings.

You can set both `LOG_LEVEL` and `DEBUG` settings in ENV variables.

## Documentation

For generating documentation run `yarn run generate-docs`. TypeDoc source code documentation is located in `docs/typedoc`.

## Contribution guidelines

Please read `CONTRIBUTING.md`.

## Troubleshooting

Contact benak@operatorict.cz or vycpalek@operatorict.cz