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.
Reach for must at initialization boundaries — package-level vars (must.Get(template.New("page").Parse(html))), test fixtures (must.Get(os.CreateTemp(...))), CLI setup (must.BeNil(os.MkdirAll(...))). The pattern: if failure here means a programmer error or broken environment, not a runtime condition the user can fix, it's a must call. If you're writing _ = fn() or if err != nil { panic(err) }, that's must in disguise.
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.From(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.From-wrapped variables with must to signal panic behavior: mustAtoi := must.From(strconv.Atoi).
Operations
Get(T, error) T— extract value or panic with the errorGet2(T, T2, error) (T, T2)— two-value variantBeNil(error)— panic with the error if non-nilNonEmptyEnv(key) string— env var or panic if unset or empty (wrapsErrEnvUnset/ErrEnvEmpty)Of(func(T)(R, error)) func(T) R— wrap for higher-order use (panics immediately if fn is nil, wrapsErrNilFunction)
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, and Get2 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.
From panics immediately if given a nil function, wrapping ErrNilFunction.
For recoverable error handling instead of panics, see [rslt.Result].
Index ¶
Examples ¶
Constants ¶
This section is empty.
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. The panic value is err itself, preserving error chains for errors.Is/errors.As after recovery.
func From ¶ added in v0.60.0
From returns the "must" version of fn. fn must be a single-argument function. Panics immediately if fn is nil, wrapping ErrNilFunction.
Example ¶
package main
import (
"fmt"
"strconv"
"github.com/binaryphile/fluentfp/must"
"github.com/binaryphile/fluentfp/slice"
)
func main() {
// mustAtoi wraps strconv.Atoi to panic on parse error.
mustAtoi := must.From(strconv.Atoi)
nums := slice.From([]string{"1", "2", "3"}).ToInt(mustAtoi)
fmt.Println(nums)
}
Output: [1 2 3]
func Get ¶
Get returns the value of a (value, error) pair, or panics if error is non-nil. The panic value is the original error, preserving error chains for errors.Is/errors.As after recovery.
func Get2 ¶
Get2 returns the values of a (value, value, error) triple, or panics if error is non-nil. The panic value is the original error, preserving error chains for errors.Is/errors.As after recovery.
func NonEmptyEnv ¶ added in v0.41.0
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.
Types ¶
This section is empty.
Source Files