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: '[email protected]' })
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.