https://github.com/johannschopplich/resultx
🤝 Minimalist, strongly-typed result pattern for TypeScript
https://github.com/johannschopplich/resultx
result-pattern result-type typescript
Last synced: 15 days ago
JSON representation
🤝 Minimalist, strongly-typed result pattern for TypeScript
- Host: GitHub
- URL: https://github.com/johannschopplich/resultx
- Owner: johannschopplich
- License: mit
- Created: 2023-05-22T05:52:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-02T19:20:09.000Z (8 months ago)
- Last Synced: 2025-05-07T12:48:40.917Z (5 months ago)
- Topics: result-pattern, result-type, typescript
- Language: TypeScript
- Homepage:
- Size: 336 KB
- Stars: 10
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# resultx
A lightweight and simple `Result` type for TypeScript, inspired by Rust's Result type.
## Description
`resultx` provides a `Result` type that represents either success (`Ok`) or failure (`Err`). It helps to handle errors in a more explicit and type-safe way, without relying on exceptions.
For error handling in synchronous code, `resultx` provides a `trySafe` function that wraps a function that might throw an error. For asynchronous code, `trySafe` can also be used with promises.
## Key Features
- 🎭 Simple and intuitive `Result` type, wrapping `Ok` and `Err` values
- 🚀 Supports both synchronous and asynchronous operations
- 🛡️ Type-safe error handling
- 🧰 Zero dependencies
- 📦 Tiny bundle size (half a kilobyte minified)
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [Examples](#examples)
## Installation
Add `resultx` to your dependencies by running one of the following commands, depending on your package manager:
```bash
pnpm add -D resultx
# Or with npm
npm install -D resultx
# Or with yarn
yarn add -D resultx
```
## Usage
```ts
import { err, ok, trySafe, unwrap } from 'resultx'
// Create `Ok` and `Err` results
const successResult = ok(42)
// ^? Ok
const failureResult = err('Something went wrong')
// ^? Err<"Something went wrong">
// Use `trySafe` for error handling
const result = trySafe(() => {
// Your code that might throw an error
return JSON.parse('{"foo":"bar"}')
})
// Either log the result or the error
if (result.ok) {
console.log('Parsed JSON:', result.value)
}
else {
console.error('Failed to parse JSON:', result.error)
}
// Or unwrap and destructure the result
const { value, error } = unwrap(result)
```
## API
### `Result`
The `Result` type represents either success (`Ok`) or failure (`Err`).
**Type Definition:**
```ts
type Result = Ok | Err
```
#### `Ok`
The `Ok` type wraps a successful value.
**Example:**
```ts
const result = new Ok(42)
```
**Type Definition:**
```ts
declare class Ok {
readonly value: T
readonly ok: true
constructor(value: T)
}
```
### `Err`
The `Err` type wraps an error value.
**Example:**
```ts
const result = new Err('Something went wrong')
```
**Type Definition:**
```ts
declare class Err {
readonly error: E
readonly ok: false
constructor(error: E)
}
```
### `ok`
Shorthand function to create an `Ok` result. Use it to wrap a successful value.
**Type Definition:**
```ts
function ok(value: T): Ok
```
### `err`
Shorthand function to create an `Err` result. Use it to wrap an error value.
**Type Definition:**
```ts
function err(err: E): Err
function err(err: E): Err
```
### `trySafe`
Wraps a function that might throw an error and returns a `Result` with the result of the function.
**Type Definition:**
```ts
function trySafe(fn: () => T): Result
function trySafe(promise: Promise): Promise>
```
### `unwrap`
Unwraps a `Result`, `Ok`, or `Err` value and returns the value or error in an object. If the result is an `Ok`, the object contains the value and an `undefined` error. If the result is an `Err`, the object contains an `undefined` value and the error.
**Example:**
```ts
const result = trySafe(() => JSON.parse('{"foo":"bar"}'))
const { value, error } = unwrap(result)
```
**Type Definition:**
```ts
function unwrap(result: Ok): { value: T, error: undefined }
function unwrap(result: Err): { value: undefined, error: E }
function unwrap(result: Result): { value: T, error: undefined } | { value: undefined, error: E }
```
## Examples
### Basic Usage
A common use case for `Result` is error handling in functions that might fail. Here's an example of a function that divides two numbers and returns a `Result`:
```ts
import { err, ok } from 'resultx'
function divide(a: number, b: number) {
if (b === 0) {
return err('Division by zero')
}
return ok(a / b)
}
const result = divide(10, 2)
if (result.ok) {
console.log('Result:', result.value)
}
else {
console.error('Error:', result.error)
}
```
### Error Handling with `trySafe`
The `trySafe` function is useful for error handling in synchronous code. It wraps a function that might throw an error and returns a `Result`:
```ts
import { trySafe } from 'resultx'
const result = trySafe(() => JSON.parse('{"foo":"bar"}'))
if (result.ok) {
console.log('Parsed JSON:', result.value)
}
else {
console.error('Failed to parse JSON:', result.error)
}
```
### Async Operations with `trySafe`
For asynchronous operations, `trySafe` can also be used with promises. Here's an example of fetching data from an API:
```ts
import { trySafe } from 'resultx'
async function fetchData() {
const result = await trySafe(fetch('https://api.example.com/data'))
if (result.ok) {
const data = await result.value.json()
console.log('Fetched data:', data)
}
else {
console.error('Failed to fetch data:', result.error)
}
}
fetchData()
```
## License
[MIT](./LICENSE) License © 2023-PRESENT [Johann Schopplich](https://github.com/johannschopplich)