Err

Err

Value-based error handling inspired by Go’s explicit error returns.

Err replaces thrown exceptions with immutable error values that carry context (codes, metadata, timestamps) and compose via wrapping and aggregation. Because every Err is a plain value, errors flow through the type system — no try/catch needed.

Key concepts:

Immutability — every mutating method (wrap, withCode, add) returns a new instance. metadata is copied on construction and frozen, so neither the caller’s original object nor a cast can write into it. The copy and freeze are shallow: values nested inside metadata remain the caller’s to mutate.
Hierarchical codes — colon-separated segments (AUTH:TOKEN:EXPIRED) enable prefix matching.
Cause chains — wrap() links errors into a chain queryable via root, chain(), and unwrap().
Aggregation — add() / addAll() collect multiple independent errors under one parent.

See

err.examples.test.ts for usage patterns

Classes

Defined in: types/err.ts:38

A value-based error type that supports wrapping, aggregation, and serialization.

All instances are immutable - methods return new instances rather than mutating. metadata is copied and frozen on construction (shallowly - nested values are not).

Properties

code?

readonly optional code: string

Defined in: types/err.ts:55

Error code for programmatic handling

isErr

readonly isErr: true

Defined in: types/err.ts:49

Discriminator property for type narrowing. Always true for Err instances.

kind

readonly kind: "Err" = "Err"

Defined in: types/err.ts:43

Discriminator property for type narrowing. Always “Err” for Err instances.

message

readonly message: string

Defined in: types/err.ts:52

Human-readable error message

metadata?

readonly optional metadata: Record<string, unknown>

Defined in: types/err.ts:58

Additional contextual data. Frozen; nested values are not.

timestamp

readonly timestamp: string

Defined in: types/err.ts:65

Timestamp when the error was created (ISO 8601 string).

Stored as string for easy serialization and comparison.

Accessors

errors

Get Signature

get errors(): readonly Err []

Defined in: types/err.ts:535

Direct child errors (for aggregates).

Returns

readonly Err []

isAggregate

Get Signature

get isAggregate(): boolean

Defined in: types/err.ts:528

Whether this error is an aggregate containing multiple errors.

Returns

boolean

root

Get Signature

get root(): Err

Defined in: types/err.ts:542

The root/original error in a wrapped error chain.

Returns

Err

stack

Get Signature

get stack(): string | undefined

Defined in: types/err.ts:923

Get the captured stack trace.

For errors created from native Errors, this is the original stack. For errors created via Err.from(string), this is the stack at creation. For wrapped errors, use .root.stack to get the original location.

Returns

string | undefined

Stack trace string or undefined

Methods

add()

add(error): Err

Defined in: types/err.ts:498

Add an error to this aggregate.

Parameters

error

Error to add (Err, Error, or string)

string | Err | Error

Returns

Err

New Err instance with the error added

addAll()

addAll(errors): Err

Defined in: types/err.ts:517

Add multiple errors to this aggregate at once.

Parameters

errors

(string | Err | Error)[]

Array of errors to add

Returns

Err

New Err instance with all errors added

chain()

chain(): Err []

Defined in: types/err.ts:560

Get the full chain of wrapped errors from root to current.

Returns

Err []

Array of Err instances in causal order

filter()

filter(predicate): Err []

Defined in: types/err.ts:648

Find all errors matching a predicate.

Parameters

predicate

(e) => boolean

Function to test each error

Returns

Err []

Array of all matching Err instances

find()

find(predicate): Err | undefined

Defined in: types/err.ts:628

Find the first error matching a predicate.

Parameters

predicate

(e) => boolean

Function to test each error

Returns

Err | undefined

The first matching Err or undefined

flatten()

flatten(): Err []

Defined in: types/err.ts:575

Flatten all errors into a single array.

Returns

Err []

Flattened array of all individual errors

getMetadata()

Call Signature

getMetadata<T>(key): T | undefined

Defined in: types/err.ts:436

Get metadata value for a given key.

Type Parameters

T

T = unknown

The expected type of the metadata value

Parameters

key

string

The metadata key to retrieve

Returns

T | undefined

The metadata value or default, cast to type T

Call Signature

getMetadata<T>(key, defaultValue): T

Defined in: types/err.ts:437

Get metadata value for a given key.

Type Parameters

T

T = unknown

The expected type of the metadata value

Parameters

key

string

The metadata key to retrieve

defaultValue

T

Optional default value if key is missing

Returns

T

The metadata value or default, cast to type T

hasCode()

Call Signature

hasCode(): boolean

Defined in: types/err.ts:593

Check if this error or any error in its chain/aggregate has a specific code, or — when called with no argument — whether any code is present in the tree.

Returns

boolean

true if the code is found (or any code exists, when called with no argument)

Call Signature

hasCode(code): boolean

Defined in: types/err.ts:594

Check if this error or any error in its chain/aggregate has a specific code, or — when called with no argument — whether any code is present in the tree.

Parameters

code

string

The error code to search for. Omit to check for the presence of any code.

Returns

boolean

true if the code is found (or any code exists, when called with no argument)

hasCodePrefix()

hasCodePrefix(prefix, boundary?): boolean

Defined in: types/err.ts:607

Check if this error or any error in its chain/aggregate has a code matching the given prefix.

Parameters

prefix

string

The code prefix to search for

boundary?

string = ":"

Separator character/string between code segments (default: “:”)

Returns

boolean

true if a matching code is found anywhere in the error tree

hasMetadata()

hasMetadata(key, options?): boolean

Defined in: types/err.ts:410

Check if metadata exists for a given key.

Parameters

key

string

The metadata key to check

options?

Optional configuration

keyCheck?

boolean

If true, only checks key existence (default: false)

Returns

boolean

true if metadata exists according to the selected mode

omitMetadata()

omitMetadata(key): Err

Defined in: types/err.ts:456

Create a new Err instance with specified metadata keys removed.

Parameters

key

Single key or array of keys to remove

string | string[]

Returns

Err

New Err instance with keys omitted

toError()

toError(): Error

Defined in: types/err.ts:898

Convert to a native Error for interop with throw-based APIs.

Returns

Error

Native Error instance

toJSON()

toJSON(options?): ErrJSON

Defined in: types/err.ts:672

Convert to a JSON-serializable object.

Parameters

options?

ErrJSONOptions = {}

Control what fields are included

Returns

ErrJSON

Plain object representation

See

fromJSON for deserializing an Err from JSON

toString()

toString(options?): string

Defined in: types/err.ts:820

Convert to a formatted string for logging/display.

Parameters

options?

ToStringOptions

Formatting options (optional)

Returns

string

Formatted error string

unwrap()

unwrap(): Err | undefined

Defined in: types/err.ts:551

Get the directly wrapped error (one level up).

Returns

Err | undefined

The wrapped Err or undefined

withCode()

withCode(code): Err

Defined in: types/err.ts:370

Create a new Err with a different or added error code.

Parameters

code

string

The error code to set

Returns

Err

New Err instance with the specified code

withMetadata()

withMetadata(metadata): Err

Defined in: types/err.ts:387

Create a new Err with additional metadata.

Parameters

metadata

Record<string, unknown>

Key-value pairs to add to metadata

Returns

Err

New Err instance with merged metadata

wrap()

wrap(message, options?): Err

Defined in: types/err.ts:355

Wrap this error with additional context.

Parameters

message

string

Context message explaining what operation failed

options?

ErrOptions

Optional code and metadata for the wrapper

Returns

Err

New Err instance with this error as cause

from()

Call Signature

static from(message, code?): Err

Defined in: types/err.ts:129

Create an Err from a string message with optional code.

Parameters

message

string

Error message

code?

string

Optional error code

Returns

Err

New Err instance

Call Signature

static from(message, options): Err

Defined in: types/err.ts:138

Create an Err from a string message with full options.

Parameters

message

string

Error message

options

ErrOptions

Code and metadata options

Returns

Err

New Err instance

Call Signature

static from(error, options?): Err

Defined in: types/err.ts:149

Create an Err from a native Error.

Preserves the original error’s stack trace, cause chain, and name.

Parameters

error

Error

Native Error instance

options?

ErrOptions

Optional overrides for message, code, and metadata

Returns

Err

New Err instance

Call Signature

static from(error, options?): Err

Defined in: types/err.ts:158

Create an Err from another Err instance (clone with optional overrides).

Parameters

error

Err

Existing Err instance

options?

ErrOptions

Optional overrides

Returns

Err

New Err instance with merged properties

Call Signature

static from(error, options?): Err

Defined in: types/err.ts:167

Create an Err from an unknown value (safe for catch blocks).

Parameters

error

unknown

Any value

options?

ErrOptions

Optional code and metadata

Returns

Err

New Err instance

fromJSON()

static fromJSON(json): Err

Defined in: types/err.ts:257

Deserialize an Err from JSON representation.

Parameters

json

unknown

JSON object matching ErrJSON structure

Returns

Err

Reconstructed Err instance

Throws

Error if json is invalid or missing required fields

See

toJSON for serializing an Err to JSON

isErr()

static isErr(value): value is Err

Defined in: types/err.ts:340

Type guard to check if a value is an Err instance.

Nominal since v0.7.0: a plain object carrying kind: "Err" or isErr: true is data, not an error. Reconstruct one with Err.from(value).

Parameters

value

unknown

Any value to check

Returns

value is Err

true if value is an Err instance

Interfaces

ErrJSON

Defined in: types/err.types.ts:28

Wire shape of a serialized Err for cross-boundary transport. Reconstruct via Err.fromJSON().

Properties

cause?

optional cause: ErrJSON

Defined in: types/err.types.ts:36

code?

optional code: string

Defined in: types/err.types.ts:32

errors

errors: ErrJSON []

Defined in: types/err.types.ts:37

isErr?

optional isErr: boolean

Defined in: types/err.types.ts:31

kind?

optional kind: "Err"

Defined in: types/err.types.ts:30

message

message: string

Defined in: types/err.types.ts:29

metadata?

optional metadata: Record<string, unknown>

Defined in: types/err.types.ts:33

stack?

optional stack: string

Defined in: types/err.types.ts:35

timestamp

timestamp: string

Defined in: types/err.types.ts:34

ErrJSONOptions

Defined in: types/err.types.ts:44

Controls which fields ErrJSON includes. Omit sensitive fields at public API boundaries.

Properties

metadata?

optional metadata: boolean

Defined in: types/err.types.ts:48

Include metadata.

Default

true

stack?

optional stack: boolean

Defined in: types/err.types.ts:46

Include stack trace.

Default

true

ErrOptions

Defined in: types/err.types.ts:13

Options for creating or modifying an Err instance.

Properties

code?

optional code: string

Defined in: types/err.types.ts:15

Error code for programmatic handling

message?

optional message: string

Defined in: types/err.types.ts:17

Human-readable error message

metadata?

optional metadata: Record<string, unknown>

Defined in: types/err.types.ts:19

Additional contextual data attached to this error level only

ToStringOptions

Defined in: types/err.types.ts:56

Controls Err.toString() output for logging and debugging.

Properties

date?

optional date: boolean

Defined in: types/err.types.ts:60

ISO 8601 timestamp prefix.

Default

false

indent?

optional indent: string

Defined in: types/err.types.ts:66

Indentation per nesting level.

Default

"  "

maxDepth?

optional maxDepth: number

Defined in: types/err.types.ts:64

Max cause chain depth before truncation.

Default

undefined (unlimited)

metadata?

optional metadata: boolean

Defined in: types/err.types.ts:62

Inline metadata object.

Default

false

stack?

optional stack: number | boolean

Defined in: types/err.types.ts:58

true = full stack, number = top N frames.

Default

undefined

Type Aliases

ErrCode

ErrCode = string

Defined in: types/err.types.ts:8

Uppercase snake_case identifier for programmatic error handling. Supports hierarchical codes for prefix matching: ‘AUTH:TOKEN:EXPIRED’.

See

Err.hasCode for prefix-based matching behavior

flow Test helpers