berrserk

Lightweight TypeScript library for type-safe errors-as-values

---

Installation

npm add berrserk
# or
yarn add berrserk
# or
pnpm add berrserk

Or whatever package manager you're currently using.

Highlights

• Handle errors as values rather than exceptions
• Support for both synchronous and asynchronous functions
• Type-safe return values with proper TypeScript definitions
• Zero dependencies
• It's also very cool

Usage

Basic Usage

import { withError } from 'berrserk'

// Synchronous example
const result = withError(() => {
  // This might throw an error
  return JSON.parse('{"valid": "json"}')
})

result.error
  ? console.error('Error parsing:', result.error.message)
  : console.log('Parsed data:', result.data)

// Asynchronous example
const fetchData = async () => {
  const result = await withError(async () => {
    const response = await fetch('https://api.example.com/data')
    return response.json()
  })

  if (result.error) {
    console.error('API Error:', result.error)
    return null
  }

  return result.data
}

Type Definitions

type Either<TResult, TError = Error> = Success<TResult> | Failure<TError>

type Success<TResult> = {
  data: TResult
  error?: undefined
}

type Failure<TError = Error> = {
  data?: undefined
  error: TError
}

API Reference

withError()

Executes a callback function and handles any errors that may be thrown, returning a structured result object.

function withError<TResult>(
  callback: () => TResult | Promise<TResult>
): Either<TResult> | Promise<Either<TResult>>

Parameters

• callback: A function that returns a value or a promise. If this function throws or rejects, the error will be caught and wrapped in the return value.

Returns

• For synchronous functions: Either<TResult, Error>
• For asynchronous functions: Promise<Either<TResult, Error>>

Examples

Form Validation

import { withError } from 'berrserk'

const validateForm = (formData) => {
  return withError(() => {
    if (!formData.email) {
      throw new Error('Email is required')
    }
    if (!formData.password) {
      throw new Error('Password is required')
    }
    return { valid: true }
  })
}

const result = validateForm({ email: '[e-mail]' })
if (result.error) {
  displayError(result.error.message) // "Password is required"
}

API Requests

import { withError } from 'berrserk'

const getUserData = async (userId) => {
  const result = await withError(async () => {
    const response = await fetch(`/api/users/${userId}`)
    if (!response.ok) {
      throw new Error(`HTTP error: ${response.status}`)
    }
    return response.json()
  })

  return result
}

// Usage
const userResult = await getUserData(123)
userResult.error ? showError(userResult.error) : renderUser(userResult.data)

Benefits Over Traditional Try/Catch

• Enforces error handling at compile time with TypeScript
• Makes error paths explicit in your code
• Eliminates the possibility of unhandled exceptions
• Seamlessly works with both synchronous and asynchronous code
• Provides consistent error handling patterns across your codebase

Local Development

Setting up the project for local development is straightforward:

1. Clone the repository

   git clone https://github.com/ntwigs/berrserk.git
   cd berrserk

2. Install development dependencies

   pnpm i

3. Available scripts:

   # Watch mode during development
   pnpm dev
   
   # Build the library
   pnpm build
   
   # Run tests
   pnpm test
   
   # Format code
   pnpm format
   
   # Check formatting
   pnpm format:check
   
   # Lint code
   pnpm lint

The project uses rslib for building and vitest for testing.

If you encounter any issues during setup, development or usage, please file an issue.

---

Created with an unhealthy amount of hatred towards error-throwing.