# @oats-ts/try

> This library wraps the result of a synchronous operation, expressing either a success or a failure.

Latest version **0.0.51** (published 2023-12-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @oats-ts/try
pnpm add @oats-ts/try
yarn add @oats-ts/try
bun add @oats-ts/try
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.51 |
| Published | 2023-12-17 |
| First published | 2021-12-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 27.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 22 |
| Author | Balázs Édes |
| Maintainers | bali182 |

## Links

- npm: https://www.npmjs.com/package/@oats-ts/try
- Repository: https://github.com/oats-ts/oats-ts
- Homepage: https://oats-ts.github.io/docs
- Issues: https://github.com/oats-ts/oats-ts/issues
- npm.io page: https://npm.io/package/@oats-ts/try

## Dependencies (1)

- [@oats-ts/validators](https://npm.io/package/@oats-ts/validators.md) 0.0.51

## Recent versions

- 0.0.51 (latest) — 2023-12-17
- 0.0.50 — 2023-12-10
- 0.0.49 — 2022-12-08
- 0.0.48 — 2022-12-02
- 0.0.47 — 2022-11-16
- 0.0.46 — 2022-11-13
- 0.0.45 — 2022-11-11
- 0.0.44 — 2022-11-09
- 0.0.43 — 2022-10-30
- 0.0.42 — 2022-10-13
- 0.0.41 — 2022-10-12
- 0.0.40 — 2022-10-10
- 0.0.39 — 2022-10-09
- 0.0.38 — 2022-10-04
- 0.0.37 — 2022-10-02
- … 29 more at https://npm.io/package/@oats-ts/try/versions

## README

# @oats-ts/try

This library wraps the result of a synchronous operation, expressing either a success or a failure.

## motivation

In typescript we have no built in way of conveying what errors might a function fail with. This is ok, if you are using errors as a "panic" mechanism, and you don't want to recover. But for libraries, where errors should be well defined, and users should be able to recover from them this is not suitable. The reason this library was created is to support typed errors for [oats](https://oats-ts.github.io/docs)

## basic usage

```ts
import { success, failure, isSuccess, Try } from '@oats-ts/try'

function divide(a: number, b: number): Try<number> {
  if (b === 0) {
    return failure([
      {
        message: 'cannot be 0',
        severity: 'error',
        path: 'b',
        type: 'division-by-zero',
      },
    ])
  }
  return success(a / b)
}

const result = divide(1, 2)

// isSuccess and isFailure are type guards, without type narrowing you can't access neither .data nor .issues
if (isSuccess(result)) {
  console.log('divide was successful', result.data)
} else {
  console.log('divide failed', result.issues)
}
```

## utilities

There are some common utility methods exposed that make it easier to work with `Try`s

### fromArray

Creates a `Try<T[]>` from `Try<T>[]`. Useful when have a list of tries as a result of `Array.map`, but you care about the correctness of all results.

```ts
import { fromArray } from '@oats-ts/try'

const numbers: number[] = getNumbersFromUser()

const dividedNumbers = fromArray(numbers.map((num) => divide(5, num)))

if (isSuccess(dividedNumbers)) {
  console.log('Here are the results:', dividedNumbers.data)
} else {
  console.log('Some of your inputs are wrong:', dividedNumbers.issues)
}
```

### fromRecord

Creates a `Try<Record<A, B>>` from `Record<A, Try<B>>`. Useful when you have an object, where each field is a computed value, and you care about the correctness of each.

```ts
import { fromRecord } from '@oats-ts/try'

const resultObject = {
  by5: divide(10, 5),
  by3: divide(10, 3),
  by1: divide(10, 1),
} as const

// result is of type Try<Record<'by5' | 'by3' | 'by1', number>>
const result = fromRecord(resultObject)
```

### zip

Wrapper on top of `fromArray`, but works with statically typed tuples

```ts
import { zip } from '@oats-ts/try'

const divisionResult = divide(5, 3)
const stringResult = success('')

// result is of type Try<[number, string]>
const result = zip(divisionResult, stringResult)
```

### fluent

The fluent method exposes some functional behaviour on the wrapped `Try`:

```ts
const result = fluent(divide(a, b))
  // .map runs performs the given transformation on .data if the Try is a success, otherise delegates the failure
  .map((result) => result - 1)
  // .map runs performs the given transformation on .data if the Try is a success, and carries on with the returned try
  .flatMap((result) => divide(5, result))
  // .get unwraps the Try, you have to provide a callback for both the success and the error case
  .get(
    (data) => data,
    (issues) => NaN,
  )
```

---
_Source: https://npm.io/package/@oats-ts/try · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._