bakutils-catcher
v3.6.1
Published
Utility library for handling errors elegantly with Decorators and Rust-like algebraic types.
Downloads
423
Maintainers
Readme
bakutils-catcher
This library is a lightweight, easy-to-use, with Decorators, to catch exceptions and errors in your code and Algebraic Data Types with Rust-like features with Result
and Option
.
For a better understanding of the Option
and Result
type features, i recommend that you read the following article Enhancing TypeScript: Implementing Robust Error Handling with Result and Option
Note: When using the decorators features, make sure that the tsconfig.json
file has the experimentalDecorators
and emitDecoratorMetadata
properties enabled and reflect-metadata library is installed/imported. Since this library is meant to have zero dependencies, it is not included in the package.
Installation
Please follow the standard npm package installation steps.
npm install bakutils-catcher
#or
yarn add bakutils-catcher
#or
pnpm add bakutils-catcher
Note: Make sure to include reflect-metadata as it's required for decorators but is not included as a dependency in this package.
Features
Algebraic Data Types
Result
The Result type can either be a Left representing a failed computation or a Right representing a successful computation.
Left: Represents a failed computation.
- .unwrap(): Returns the value of the Result if it is successful, otherwise throws an error.
- .unwrapOr(defaultValue): Returns the value of the Result if it is successful, otherwise returns the - provided default value.
- .unwrapOrElse(fn): Returns the value of the Result if it is successful, otherwise calls the - provided function with the error and returns its result.
- .isErr(): Returns true if the Result is an error, false otherwise.
- .isOk(): Returns true if the Result is successful, false otherwise.
Right: Represents a successful computation.
- .unwrap(): Returns the value of the Result.
- .unwrapOr(defaultValue): Returns the value of the Result.
- .unwrapOrElse(fn): Returns the value of the Result.
- .isErr(): Returns true if the Result is an error, false otherwise.
- .isOk(): Returns true if the Result is successful, false otherwise.
Option
The Option type can either be Some representing an existing value or None representing no value.
- Some: Represents an Option that contains a value.
- .unwrap(): Returns the value of the Option if it exists, otherwise throws an error.
- .unwrapOr(defaultValue): Returns the value of the Option if it exists, otherwise returns the - provided default value.
- .unwrapOrElse(fn): Returns the value of the Option if it exists, otherwise calls the provided - function and returns its result.
- .isSome(): Returns true if the Option contains a value, false otherwise.
- .isNone(): Returns true if the Option does not contain a value, false otherwise.
- None: Represents an Option that does not contain a value.
- .unwrap(): Throws an error because None does not contain a value.
- .unwrapOr(defaultValue): Returns the provided default value because None does not contain a value.
- .unwrapOrElse(fn): Calls the provided function and returns its result because None does not contain a value.
- .isSome(): Returns true if the Option contains a value, false otherwise.
- .isNone(): Returns true if the Option does not contain a value, false otherwise.
You can wrap any value with the Option
function (Not the type) on cases where you are not sure if the value is null
or undefined
.
import {Option, Some} from 'bakutils-catcher';
let unknownRunTimeValue = /*...*/;
//TypeScript will infer if you are using Option as a type or as a function.
const someValue = Option(unknownRunTimeValue);
const typedSomeValue: Option<number> = Some(unknownRunTimeValue);
Decorators
Catch
A TypeScript decorator that wraps a class method with error-handling logic. It catches errors of a specific type thrown within the decorated method.
Usage
class SomeThing {
@Catch(MyError, (err, context, ...args) => {
// handle error here
})
public myMethodWithoutTryCatch() {}
}
DefaultCatch
A TypeScript decorator that wraps a class method with error-handling logic. It catches all errors thrown within the decorated method.
Usage
class SomeThing {
@DefaultCatch((err, context, ...args) => {
// handle error here
})
public myMethodWithoutTryCatch() {}
}
Quick Start
Here's a quick example to get you started:
import { Ok, Err, Some, None, Catch, DefaultCatch } from 'bakutils-catcher';
// Using Result
const goodResult = Ok("Success");
const badResult = Err("Failure");
// Using Option
const someValue = Some(42);
const noValue = None;
// Using Catch Decorator
class MyClass {
@Catch(MyError, (err) => {
console.log("Caught a MyError:", err);
})
myMethod() {
throw new MyError("Oops!");
}
}
// Using DefaultCatch Decorator
class AnotherClass {
@DefaultCatch((err) => {
console.log("Caught an error:", err);
})
anotherMethod() {
throw new Error("Oops again!");
}
}
License This project is licensed under the MIT License.