must

README

must

Turn assumed preconditions into enforced invariants. Panics when violated.

Use must when failure indicates a programmer error or misconfiguration — not for recoverable runtime conditions.

// Before: you're assuming this won't fail — but silently
_ = os.Setenv("PATH", newPath)

// After: same assumption, now enforced
err := os.Setenv("PATH", newPath)
must.BeNil(err)

must.BeNil replaces the three-line if err != nil { panic(err) } block with one line. must.Get goes further — four lines (declare, call, check, panic) become one.

What It Looks Like

// Initialization — errors here mean a bug or misconfiguration, not a runtime condition
re := must.Get(regexp.Compile(pattern))
port := must.Get(strconv.Atoi(os.Getenv("PORT")))

// Required environment
home := must.NonEmptyEnv("HOME")

// Pipeline adapter — wraps func(T)(R, error) into func(T) R
mustAtoi := must.Of(strconv.Atoi)
n := mustAtoi("42")  // 42, or panics if not a valid integer

Making Assumptions Visible

Every _ = fn() is a hidden assumption — you're expecting the error won't happen. If it does, the program continues with no indication of what went wrong.

must makes the assumption explicit. If it's wrong, you find out immediately.

Don't recover from must panics and continue normal execution. An invariant violation means the program is in a state you didn't anticipate — recovering and continuing from that state is how silent corruption happens. Top-level recovery for logging, crash reporting, or test assertions is fine. If you're tempted to recover and continue, the operation isn't an invariant — use (T, error) returns and handle the error explicitly.

Convention: For error-only returns, keep the err assignment — it reads like Go:

err := os.MkdirAll(dataDir, 0o755)
must.BeNil(err)

Use must.Get when you need the value: re := must.Get(regexp.Compile(pattern)). Prefix must.Of-wrapped variables with must to signal panic behavior: mustAtoi := must.Of(strconv.Atoi).

Operations

• Get(T, error) T — extract value or panic with the error
• Get2(T, T2, error) (T, T2) — two-value variant
• BeNil(error) — panic with the error if non-nil
• NonEmptyEnv(key) string — env var or panic if unset or empty (wraps ErrEnvUnset / ErrEnvEmpty)
• Of(func(T)(R, error)) func(T) R — wrap for higher-order use (panics immediately if fn is nil, wraps ErrNilFunction)

See pkg.go.dev for complete API documentation, the main README for installation, and rslt for typed error handling without panics.

Documentation

Overview

Package must provides panic-on-error helpers for enforcing invariants.

Use must for startup-time configuration, code generation, tests, and programmer-error invariants — cases where failure means a bug or misconfiguration, not a recoverable runtime condition.

Do not use must for user input, expected I/O failures, or exported library APIs unless panic semantics are explicitly part of the contract.

BeNil, Get, Get2, and Of panic with the original error value, preserving error chains for errors.Is/errors.As after recovery. NonEmptyEnv panics with a descriptive error wrapping ErrEnvUnset or ErrEnvEmpty for machine-checkable classification after recovery.

Of panics immediately if given a nil function, wrapping ErrNilFunction.

Index

• Variables
• func BeNil(err error)
• func Get[T any](t T, err error) T
• func Get2[T, T2 any](t T, t2 T2, err error) (T, T2)
• func NonEmptyEnv(key string) string
• func Of[T, R any](fn func(T) (R, error)) func(T) R

Variables

var ErrEnvEmpty = errors.New("environment variable empty")

ErrEnvEmpty indicates the environment variable is set but empty.

var ErrEnvUnset = errors.New("environment variable unset")

ErrEnvUnset indicates the environment variable is not set.

var ErrNilFunction = errors.New("nil function")

ErrNilFunction indicates a nil function was passed where one is required.

Functions

func BeNil

func BeNil(err error)

BeNil panics if err is not nil.

func Get

func Get[T any](t T, err error) T

Get returns the value of a (value, error) pair of arguments unless error is non-nil. In that case, it panics.

func Get2

func Get2[T, T2 any](t T, t2 T2, err error) (T, T2)

Get2 returns the value of a (value, value, error) set of arguments unless error is non-nil. In that case, it panics.

func NonEmptyEnv

func NonEmptyEnv(key string) string

NonEmptyEnv returns the value of the environment variable named by key. It panics if the variable is unset or empty. The panic value wraps ErrEnvUnset or ErrEnvEmpty for errors.Is matching.

func Of

func Of[T, R any](fn func(T) (R, error)) func(T) R

Of returns the "must" version of fn. fn must be a single-argument function. Panics immediately if fn is nil, wrapping ErrNilFunction.