https://github.com/aripalo/result
Typesafe error handling (inspired by Go) and data absence protection for TypeScript applications (NodeJS or Browser)
https://github.com/aripalo/result
Last synced: 6 months ago
JSON representation
Typesafe error handling (inspired by Go) and data absence protection for TypeScript applications (NodeJS or Browser)
- Host: GitHub
- URL: https://github.com/aripalo/result
- Owner: aripalo
- License: apache-2.0
- Created: 2024-02-07T18:16:18.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-07T19:46:33.000Z (over 1 year ago)
- Last Synced: 2025-02-14T05:15:22.038Z (8 months ago)
- Language: TypeScript
- Size: 10.7 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `@aripalo/result`
**Typesafe error handling (inspired by Go) & data absence protection for TypeScript apps** (NodeJS/Browser).
🚧 Should work, but all of this is still a bit "work-in-progress"!
## Getting started
### Install
```sh
npm i @aripalo/result
```
### Example "throwable"
Some irrelevant code for demonstration purposes:
```ts
async function randomErrorHelloWorld(): Promise {
if (Math.random() < 0.5) {
throw new Error("Random error occurred");
}
return "Hello World!";
}
```
### Usage
```ts
import { Result } from "@aripalo/result";
const [value, err] = await Result(randomErrorHelloWorld());
if (err) {
assert(value === null); // true
assert(err instanceof Error); // true
} else {
assert(typeof value === "string"); // true
assert(err === null); // true
}
```
## Purpose
> _“There are many like it, but this one is mine.”_
Writing asynchronous code with `async`/`await` looks simple, but once procedural code that depends on the output of previous async steps is being introduced with bit more complex error handling requirements, things start to become complex from control flow perspective.
**There are many great alternative solutions to this problem; This one just happens to be the pattern I personally prefer to use.**
1. Go-inspired, error as return value
2. Returned error is always an instance of `Error`
3. Return value (type `Maybe`) is a Tuple with either value or error present and the other always set to `null`:
```ts
type Maybe = [value: T, err: null] | [value: null, err: Error];
```
4. Data absence protection: By default, values that resolve to `undefined` or `null` will internally thrown an error, resulting into:
```ts
[value: null, err: Error]
```
5. Primarily aimed for `async` functions and Promise objects, but works with synchronous functions too: Anything that is _throwable_, i.e. "can throw/reject".
6. Works both in NodeJS and Browser environments
## Patterns
### Receive both
```ts
const [value, err] = await Result(randomErrorHelloWorld());
if (err) {
// handle err, for example return early
return;
}
// do something with the value
```
### Ignore value
If you're only interested in "did the operation succeed", without caring about the return value:
```ts
const [, err] = await Result(randomErrorHelloWorld());
if (err) {
// handle err
}
```
### Ignore err
When you don't really care if the operation fails, but if it succeeded do something with the return value:
```ts
const [value] = await Result(randomErrorHelloWorld());
if (value) {
// do something with value
}
```
### Disable data absence protection
If your _throwable_ returns/resolves without _meaningful_ data on success, you may specify `meaningful: false` to prevent the data absence protection:
```ts
const [value, err] = await Result(Promise.resolve(undefined), {
meaningful: false,
});
if (err) {
// handle err
} else {
assert(typeof value === "undefined"); // true
}
```