Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/olian04/simply-result
Simply typesafe Result and Option monads in typescript and javascript.
https://github.com/olian04/simply-result
fp functional-programming javascript monad monad-types monads option option-type result result-type typescript
Last synced: 9 days ago
JSON representation
Simply typesafe Result and Option monads in typescript and javascript.
- Host: GitHub
- URL: https://github.com/olian04/simply-result
- Owner: Olian04
- License: mit
- Created: 2023-08-15T09:15:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-22T17:00:52.000Z (9 months ago)
- Last Synced: 2024-10-03T10:05:16.047Z (about 1 month ago)
- Topics: fp, functional-programming, javascript, monad, monad-types, monads, option, option-type, result, result-type, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/simply-result
- Size: 165 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/simply-result)
[](https://github.com/Olian04/simply-result/actions/workflows/ci.yml)
[](https://codecov.io/gh/Olian04/simply-result)
[](https://www.npmjs.com/package/simply-result)
[](./LICENSE)
# simply-result
Simply result is a Result and Option monad library for typescript and javascript. Its more than [100 times faster than try-catch](#performance) with a total package size of ~700b minified and gzipped.
See also the sister library [simply-result-util](https://github.com/Olian04/simply-result-util) for useful monadic helper functions such as `Try`, `transpose`, and `flatten`.
```ts
import { Result, Ok } from 'simply-result';
const doSomeWork = (): Result => Ok(3);
const fraction = doSomeWork()
.mapErr(err => console.error(err))
.intoOption()
.filter(it => it !== 0)
.map(it => (1 / it).toPrecision(3))
.unwrapOr('0');
console.log(fraction); // '0.333'
```
## Installation
### NPM
[`npm i simply-result`](https://www.npmjs.com/package/simply-result)
```ts
import {
Result, Ok, Err,
Option, Some, None,
} from 'simply-result';
```
## Demo
[See `./demo`](./demo/)
## Type Docs
### Result
```ts
type Result =
| Ok
| Err
interface Ok {
isOk: true
isErr: false
ok: V
match(cases: {
Ok: (ok: V) => T
}): T
intoOption(): Some
intoErrOption(): None
map(fn: (ok: V) => T): Ok
mapErr(fn: unknown): Ok
andThen(fn: (ok: V) => T): T
elseThen(fn: unknown): Ok
unwrapOr(ok: unknown): V
unwrapElse(fn: unknown): V
toString(): string
}
interface Err {
isOk: false
isErr: true
err: E
match(cases: {
Err: (err: E) => T
}): T
intoOption(): None
intoErrOption(): Some
map(fn: unknown): Err
mapErr(fn: (err: E) => F): Err
andThen(fn: unknown): Err
elseThen(fn: (err: E) => T): T
unwrapOr(ok: T): T
unwrapElse(fn: () => T): T
toString(): string
}
function Ok(value: V): Ok
function Err(error: E): Err
```
### Option
```ts
type Option =
| Some
| None
interface Some {
isSome: true
isNone: false
some: V
match(cases: {
Some: (some: V) => T
}): T
intoResult(error: unknown): Ok
map(fn: (some: V) => T): Some
filter(fn: (some: V) => boolean): Option
andThen(fn: (some: V) => T): T
elseThen(fn: unknown): Some
unwrapOr(some: unknown): V
unwrapElse(fn: unknown): V
toString(): string
}
interface None {
isSome: false
isNone: true
match(cases: {
None: () => T
}): T
intoResult(error: E): Err
map(fn: unknown): None
filter(fn: unknown): None
andThen(fn: unknown): None
elseThen(fn: () => T): T
unwrapOr(some: T): T
unwrapElse(fn: () => T): T
toString(): string
}
function Some(value: V): Some
const None: None
```
## Performance
| | Code | Result |
|:---------:|:-------------------------------------------------------:|:-------------------------------------------------:|
| Result | `Err(new Error()).elseThen(err => { err.message })` | `123,901,767 ops/sec ±0.15% (100 runs sampled)` |
| Try Catch | `try { throw new Error() } catch (err) { err.message }` | `1,125,735 ops/sec ±0.29% (67 runs sampled)` |
| Baseline | `new Error().message` | `1,027,606,577 ops/sec ±0.10% (101 runs sampled)` |
All performance tests use the same `Error` object which is created before testing as to minimize the impact of creating an error object on the measurements.
Tests were ran on a `32gb MacBook M1 Pro` running `macOS 14.3`. The test code can be found [here](./demo/perf.ts).
```log
(1/5) baseline x 1,026,512,662 ops/sec ±0.13% (102 runs sampled)
(2/5) baseline x 1,025,374,916 ops/sec ±0.46% (94 runs sampled)
(3/5) baseline x 1,027,606,577 ops/sec ±0.10% (101 runs sampled)
(4/5) baseline x 1,027,408,614 ops/sec ±0.11% (100 runs sampled)
(5/5) baseline x 1,027,220,720 ops/sec ±0.15% (101 runs sampled)
(1/5) Result x 123,762,745 ops/sec ±0.21% (101 runs sampled)
(2/5) Result x 123,725,903 ops/sec ±0.20% (100 runs sampled)
(3/5) Result x 123,690,424 ops/sec ±0.21% (99 runs sampled)
(4/5) Result x 123,901,767 ops/sec ±0.15% (100 runs sampled)
(5/5) Result x 123,781,206 ops/sec ±0.25% (100 runs sampled)
(1/5) try catch x 1,108,408 ops/sec ±0.34% (59 runs sampled)
(2/5) try catch x 1,122,301 ops/sec ±0.37% (66 runs sampled)
(3/5) try catch x 1,124,218 ops/sec ±0.37% (67 runs sampled)
(4/5) try catch x 1,125,735 ops/sec ±0.29% (67 runs sampled)
(5/5) try catch x 1,116,800 ops/sec ±0.39% (67 runs sampled)
```