errs

Simple error creation, boundaries, and formatting utilities for modern Node.js applications.

Features

- Simple Error Creation - Create errors with custom properties in one line
- Error Boundaries - Collect errors without immediate throwing
- Type Guards - Runtime type checking for errors with TypeScript support
- Result Pattern - Rust-style tryCatch for exception-free error handling
- Multi-Format Output - Format errors for terminal, JSON, or HTML
- Native Cause Chains - Built-in support for ES2022 Error.cause
- Error Type Registration - Register and reuse custom error types
- Zero Dependencies - No runtime dependencies

Installation

``sh
npm install errs
`

Quick Start

`js
import errs from 'errs'

// Create errors with custom properties
const err = errs.create({
message: 'User not found',
status: 404,
code: 'USER_NOT_FOUND'
})

// Collect multiple errors without throwing
const boundary = errs.boundary()
boundary.add(new Error('Validation failed'))
boundary.add(new Error('Invalid email'))
if (boundary.hasErrors()) {
boundary.throwIfErrors()
}

// Format errors for different outputs
console.log(errs.format(err, { format: 'terminal' }))
`

API Reference

$3

#### errs.create(opts)

Creates a new error with custom properties.

`js
// From a string
const err = errs.create('Something went wrong')

// From an object
const err = errs.create({
message: 'Database connection failed',
status: 500,
code: 'DB_ERROR'
})

// From an array (joined with spaces)
const err = errs.create(['Invalid', 'request', 'parameters'])

// From a function
const err = errs.create(() => ({
message: 'Dynamic error',
timestamp: Date.now()
}))
`

#### errs.create(type, opts)

Creates an error of a registered type.

`js
class ValidationError extends Error {
name = 'ValidationError'
}

errs.register('validation', ValidationError)

const err = errs.create('validation', {
message: 'Invalid input',
field: 'email'
})
`

$3

#### errs.merge(error, opts)

Merges an existing error with new properties and sets native cause chain.

`js
try {
await fetchData()
} catch (original) {
throw errs.merge(original, {
message: 'Failed to load user data',
userId: 123
})
// merged.cause === original
}
`

$3

#### errs.boundary(options)

Creates an ErrorBoundary for collecting errors without immediate throwing.

`js
const boundary = errs.boundary({
maxErrors: 100, // Maximum errors to collect (default: 1000)
captureStack: true // Capture creation point (default: true)
})

// Collect errors
try {
validateEmail(data.email)
} catch (e) {
boundary.add(e)
}

try {
validateAge(data.age)
} catch (e) {
boundary.add(e)
}

// Check and throw if errors exist
if (boundary.hasErrors()) {
console.log(Collected ${boundary.count} errors)
boundary.throwIfErrors('Validation failed')
}

// Or get as AggregateError
const aggregate = boundary.toAggregateError()

// Clear and reuse
boundary.clear()
`

#### ErrorBoundary Methods

- add(error) - Add an error to the boundary
- hasErrors() - Check if any errors collected
- count - Get number of errors
- errors - Get copy of all errors
- toAggregateError(message) - Convert to AggregateError
- throwIfErrors(message) - Throw if errors exist
- clear() - Remove all errors
- trap(fn) - Execute sync function, trap errors to boundary
- trapAsync(fn) - Execute async function, trap errors to boundary

#### boundary.trap(fn) / boundary.trapAsync(fn)

Execute functions and automatically collect errors without throwing.

`js
const boundary = errs.boundary()

// Sync operations
const result = boundary.trap(() => JSON.parse(userInput))
if (result.ok) {
console.log('Parsed:', result.value)
} else {
console.log('Parse failed, error collected')
}

// Async operations
const fetched = await boundary.trapAsync(() => fetch(url))
if (fetched.ok) {
const data = await fetched.value.json()
}

// Process multiple and handle all errors at once
items.forEach(item => boundary.trap(() => processItem(item)))
boundary.throwIfErrors('Batch processing failed')
`

$3

#### errs.isErrorType(error, ErrorClass)

Type guard that checks if an error is an instance of a specific class.

`js
try {
await fetchData()
} catch (err) {
if (errs.isErrorType(err, TypeError)) {
// TypeScript knows err is TypeError here
console.log('Type error occurred')
}
}
`

#### errs.isRegisteredType(error, typeName)

Check if an error matches a registered type name.

`js
errs.register('validation', ValidationError)

if (errs.isRegisteredType(err, 'validation')) {
// Handle validation error
}
`

#### errs.assertErrorType(error, ErrorClass, message?)

Assert error is a specific type, throws TypeError if not.

`js
function handleHttpError(err) {
// Throws TypeError if err is not HttpError
const httpErr = errs.assertErrorType(err, HttpError)
return httpErr.status // TypeScript knows this is HttpError
}
`

$3

#### errs.tryCatch(fn)

Wraps a sync function to return a Result instead of throwing.

`js
const result = errs.tryCatch(() => JSON.parse(input))
if (result.ok) {
console.log(result.value)
} else {
console.log('Parse error:', result.error.message)
}
`

#### errs.tryCatchAsync(fn)

Wraps an async function to return a Result instead of throwing.

`js
const result = await errs.tryCatchAsync(() => fetch(url))
if (result.ok) {
const data = await result.value.json()
} else {
console.log('Fetch failed:', result.error.message)
}
`

$3

#### errs.parallel(promises, options)

Run multiple promises and collect all errors.

`js
const { results, boundary } = await errs.parallel([
fetchUser(1),
fetchUser(2),
fetchUser(3)
])

// Get successful values
const users = results
.filter(r => r.status === 'fulfilled')
.map(r => r.value)

// Check for errors
if (boundary.hasErrors()) {
console.error(${boundary.count} requests failed)
}
`

$3

#### errs.format(error, options)

Format errors for different output targets.

`js
// Terminal output with colors
console.log(errs.format(error, { format: 'terminal', colors: true }))

// JSON for logging
logger.error(errs.format(error, { format: 'json', indent: 2 }))

// HTML for error pages
res.send(errs.format(error, { format: 'html' }))
`

Terminal Output:

`
╭─ TypeError: Cannot read property 'x' of undefined
│
│ at processUser (src/users.js:42:15)
│ at async main (src/index.js:10:3)
│
├─ Caused by: NetworkError: Connection refused
│
│ at fetch (src/api.js:23:9)
│
╰─ 2 errors in chain
`

$3

#### errs.handle(error, callback, stream)

Unified error handling for callbacks and EventEmitters.

`js
// With callback
errs.handle(err, (e) => console.error(e))

// With EventEmitter
errs.handle(err, emitter)

// With both
errs.handle(err, callback, emitter)

// Returns emitter if no callback
const emitter = errs.handle(err)
emitter.on('error', handleError)
`

$3

#### errs.register(type, ErrorClass)

Register a custom error type.

`js
class HttpError extends Error {
name = 'HttpError'
constructor(message, status) {
super(message)
this.status = status
}
}

errs.register('http', HttpError)

// Use registered type
const err = errs.create('http', {
message: 'Not found',
status: 404
})
`

#### errs.unregister(type)

Unregister an error type.

`js
errs.unregister('http')
`

$3

#### errs.toJSON(error)

Convert error to JSON-serializable object.

`js
const err = new Error('Test error')
err.code = 'TEST_CODE'

const json = errs.toJSON(err)
// { message: 'Test error', stack: '...', code: 'TEST_CODE' }
`

Named Exports

All functions are available as named exports:

`js
import {
create,
boundary,
format,
parallel,
isErrorType,
isRegisteredType,
assertErrorType,
tryCatch,
tryCatchAsync
} from 'errs'

const err = create('Error message')
const bound = boundary()
const result = tryCatch(() => JSON.parse(data))
`

Subpath Exports

Import specific modules directly:

`js
import { ErrorBoundary } from 'errs/boundary'
import { format } from 'errs/format'
`

Use Cases

$3

`js
const boundary = errs.boundary()

if (!email.includes('@')) {
boundary.add(new Error('Invalid email'))
}
if (password.length < 8) {
boundary.add(new Error('Password too short'))
}

boundary.throwIfErrors('Validation failed')
`

$3

`js
const boundary = errs.boundary()

for (const item of items) {
try {
await processItem(item)
} catch (err) {
boundary.add(err)
}
}

if (boundary.hasErrors()) {
console.error(${boundary.count} items failed)
await logErrors(boundary.errors)
}
`

$3

`js
app.use((err, req, res, next) => {
res.status(err.status || 500).send(
errs.format(err, { format: 'json' })
)
})
``

Requirements

- Node.js >= 20.0.0

Migration from v0.x

See MIGRATION.md for detailed migration guide.

License

MIT

Contributors

- Charlie Robbins
- Nuno Job