https://github.com/astoilkov/settle-it
Deal with code that can throw
https://github.com/astoilkov/settle-it
error-handling errors try-catch
Last synced: 9 months ago
JSON representation
Deal with code that can throw
- Host: GitHub
- URL: https://github.com/astoilkov/settle-it
- Owner: astoilkov
- License: mit
- Created: 2022-07-03T14:13:36.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-11-08T13:10:31.000Z (about 2 years ago)
- Last Synced: 2025-04-14T02:07:42.237Z (9 months ago)
- Topics: error-handling, errors, try-catch
- Language: TypeScript
- Homepage:
- Size: 32.2 KB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# `settle-it`
> Deal with code that can throw.
[](https://bundlephobia.com/result?p=settle-it)
[](https://github.com/astoilkov/settle-it/actions/workflows/main.yml)
## Install
```bash
npm install settle-it
```
## Why
Most commonly I use `try/catch`, but in some cases it's great:
- if you prefer a one-liner
- when you want to ignore the error
- to avoid nesting `try/catch` statements
- when you [prefer const](https://eslint.org/docs/latest/rules/prefer-const), `try`/`catch` statements get in the way because you need to use `let` if you need the variable outside of the `try`/`catch` scope:
```ts
let todos;
try {
todos = JSON.parse(localStorage.getItem('todos'))
} catch {}
return todos.filter(todo => todo.done)
```
Also:
- `err` is always an `Error` object — great for TypeScript & unexpected cases when someone `throw 'error'`
- Supports a `fallback` value.
- `fallback` can be a function that accepts the `Error` — great for working with it
## Examples
Safely parse JSON & specify the type (one-liner):
```ts
import settle from 'settle-it'
const [parsed] = settle(() => JSON.parse(value))
// parsed is State | undefined
```
Prefer `const`:
```ts
const isOnline = settle(async () => {
const response = await fetch('https://status.com/check')
const json = response.json()
return json.isOnline
}, false)
```
Safely fetch & on error, send to error tracking service (one-liner):
```ts
import settle from 'settle-it'
const [response] = await settle(fetch('https://todos.com/get'), sendToErrorTrackingService)
// response is Response | undefined
```
Safely read a file & fallback to empty string (one-liner):
```ts
import { readFile } from 'node:fs/promises'
const [content] = await settle(readFile(path), '')
// content is string
```
Avoid nesting `try/catch` statements:
```ts
const user = settle(() => JSON.parse(json), () => showDialog('failed to parse'))
const contents = settle(fetch(`http://example.com/${user.id}`), () => showDialog('failed to fetch'))
// to show different errors to the user you need to nest try/catch statements
```
## API
I usually prefer [source code](./index.ts) or examples ↑.
```ts
settle(
value: Promise | (() => T) | (() => Promise),
fallback: F | ((err: Error) => F | void)
): [T, undefined] | [F, Error]
```
- **First parameter** accepts either sync/async function or a Promise.
- **Returns** `[value, undefined]` if no error was thrown while executing the function.
- **Returns** `[fallback, Error]` is an error was thrown.