Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nickfla1/resful
Type safe results for TypeScript
https://github.com/nickfla1/resful
nodejs results typescript
Last synced: 2 months ago
JSON representation
Type safe results for TypeScript
- Host: GitHub
- URL: https://github.com/nickfla1/resful
- Owner: nickfla1
- License: mit
- Created: 2023-11-03T23:36:29.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-04T18:33:20.000Z (6 months ago)
- Last Synced: 2024-10-10T11:38:13.308Z (3 months ago)
- Topics: nodejs, results, typescript
- Language: TypeScript
- Homepage:
- Size: 79.1 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# resful
Type safe result utilities for TypeScript.
## Who should use this library?
This library is intended for developers that want to void explicitly uses of `Error` and `throw` in their TypeScript applications.
If used in libraries iti is not advised to expose `Result` to the library public API. This library is thought for internal use only.
## How to use
### Install
```sh
yarn add resful
npm install resful
pnpm install resful
```
> NOTE: Not tested on Bun
### Basic usage
```ts
import { ok, err, isOk, type Result } from 'resful'
const myFunc = (): Result => {
if (Math.random() > 0.5) {
return err("bad odds")
}
return ok("good odds")
}
const res = myFunc()
if (isOk(res)) {
// nice stuff
}
```
## API
### `ok`
Creates an immutable (`Object.freeze`) `OkResult` object of the provided type.
```ts
import { ok } from 'resful'
interface User {
id: string
email: string
}
const res = ok({
id: '123-456',
email: '[email protected]'
})
```
### `err`
Creates an immutable (`Object.freeze`) `ErrResult` object of the provided type.
```ts
import { err } from 'resful'
const BAD_ERROR = 'error.bad' as const
const res = err(BAD_ERROR) // The type of the error is inferred
```
### `isOk` and `isErr`
Utilities asserting if a result is either an `OkResult` or an `ErrResult`.
```ts
import { isOk, isErr } from 'resful'
const res = /* ok(...) or err(...) */
if (isOk(res)) {
// `res.ok` is accessible, res is OkResult
}
if (isErr(res)) {
// `res.err` is accessible, res is ErrResult
}
```
### `unwrap`
Utility to unwrap the content of a result.
> NOTE: This utility will throw a `TypeError` if its input is an `ErrResult`
```ts
import { unwrap, ok } from 'resful'
const res = ok('foobar')
unwrap(res) === 'foobar' // true
```
### `unwrapOr`
Utility to unwrap the content of a result. Returning a compatible fallback value if it's an `ErrResult`.
```ts
import { unwrapOr, ok } from 'resful'
const res = ok('foobar')
unwrapOr(res, 'barbar') === 'foobar' // true
```
```ts
import { unwrapOr, err } from 'resful'
const res = err('foobar')
unwrapOr(res, 'barbar') === 'barbar' // true
```
### `map`
Utility to map the content of an `OkResult` into another type.
```ts
import { map, ok } from 'resful'
const res = ok('foobar')
map(res, (value) => value.toUpperCase()) // { data: 'FOOBAR' }
```
### `mapErr`
Utility to map the content of an `ErrResult` into another type.
```ts
import { mapErr, err } from 'resful'
const res = err('barbar')
mapErr(res, (value) => value.toUpperCase()) // { err: 'BARBAR' }
```
### `run`
Utility to wrap a function inside a safe-ish context. `UnwrapError`s thrown inside are catched and returned as `ErrResult`s.
> NOTE: This utility will _not_ handle unhandled non-`UnwrapError` thrown while executed.
```ts
import { run, ok, unwrap } from 'resful'
const res = run(() => {
unwrap(err('oh no'))
ok('yes')
})
```
Or async
```ts
const res = await run(async () => {
unwrap(await doStuff())
ok('yes')
})
```
### `safe`
Utility to wrap a function inside a safe context. All errors thrown inside are catched and returned as `ErrResult`s.
See [`run`](#run) examples.
### `box`
Utility to wrap a function reference inside a safe-ish context. Same rules as [`run`](#run) apply.
```ts
import { box, ok, unwrap } from 'resful'
function fn() {
unwrap(err('oh no'))
ok('yes')
})
const boxedFn = box(fn)
const res = boxedFn()
```
Or with arguments
```ts
async function fn(what: string) {
ok(`yes, ${what}`)
})
const boxedFn = box(fn)
const res = await boxedFn('sir')
```
### `safeBox`
Utility to wrap a function reference inside a safe context. Same rules as [`safe`](#safe) apply.
See [`box`](#box) examples.