value

README

value

Conditional value selection without branching.

// Before: five lines to assign one value
var color string
if critical {
    color = warn
} else {
    color = calm
}

// After
color := value.Of(warn).When(critical).Or(calm)

Five lines become one.

What It Looks Like

Struct Returns

Go struct literals let you build and return a value in one statement — value.Of keeps it that way when fields are conditional:

// Before: pre-compute each field, then assemble
var level string
if overdue {
    level = "critical"
} else {
    level = "info"
}
var icon string
if overdue {
    icon = "!"
} else {
    icon = "✓"
}
return Alert{Message: msg, Level: level, Icon: icon}

// After: every field resolves inline
return Alert{
    Message: msg,
    Level:   value.Of("critical").When(overdue).Or("info"),
    Icon:    value.Of("!").When(overdue).Or("✓"),
}

Defaults with Validation

timeout := value.Of(requested).When(requested > 0).Or(defaultTimeout)

Lazy Evaluation

// expensiveDefault is only called when the cache misses
result := value.LazyOf(expensiveDefault).When(!cache.Hit()).Or(cache.Value())

LazyOf wraps a func() T and only evaluates it if the condition is true. Use it when the conditional value is expensive to compute.

First Non-Zero

// Config merge: use override if set, otherwise keep default
result.Region = value.FirstNonZero(override.Region, defaults.Region)

// Multi-level fallback
host := value.FirstNonZero(envHost, configHost, "localhost")

FirstNonZero returns the first non-zero value from its arguments, or zero if all are zero. It requires comparable (same constraint as slice.Compact). Use it when the condition is "non-zero" and you don't need the option intermediary.

FirstNonEmpty is the string-specific variant — reads naturally for string config merges:

region := value.FirstNonEmpty(override.Region, defaults.Region)

FirstNonNil dereferences the first non-nil pointer, or returns zero if all are nil:

timeout := value.FirstNonNil(override.Timeout, defaults.Timeout)

Composition

.Or() isn't part of value — it comes from option.Option[T]. The chain works because .When() returns an option:

value.Of(v)  →  Cond[T]
  .When(c)   →  option.Option[T]    // Ok(v) if true, NotOk if false
  .Or(fb)    →  T                  // resolve with fallback

value creates the condition. option resolves it. The packages compose.

When to Use value vs option

	value	option
Intent	Select between values	Handle a potentially absent value
Trigger	Explicit condition or zero-value check	Value's own existence/validity
Pattern	A or B (condition) / first non-zero	A or nothing

// value: both alternatives are known
color := value.Of(warn).When(critical).Or(calm)

// option: the value might not exist
port := option.Getenv("PORT").Or("8080")

Operations

Cond[T] holds a value pending a condition check. LazyCond[T] holds a function for deferred computation.

• Of(T) Cond[T] — wrap a value
• Cond[T].When(bool) option.Option[T] — ok if true, not-ok if false
• LazyOf(func() T) LazyCond[T] — wrap a function (lazy)
• LazyCond[T].When(bool) option.Option[T] — evaluate only if true
• FirstNonZero[T comparable](vals ...T) T — first non-zero value
• FirstNonEmpty(vals ...string) string — first non-empty string (string-specific variant of FirstNonZero)
• FirstNonNil[T any](ptrs ...*T) T — first non-nil pointer, dereferenced (zero if all nil)

See pkg.go.dev for complete API documentation, the main README for installation, option for absent values without conditions, and the showcase for real-world rewrites.

Documentation

Overview

Package value provides value-first conditional selection. Use this for selecting a value with a fallback, not for executing branches of logic.

Index

• Variables
• func FirstNonEmpty(vals ...string) string
• func FirstNonNil[T any](ptrs ...*T) (_ T)
• func FirstNonZero[T comparable](vals ...T) (_ T)
• func NonEmptyWith[R any](s string, fn func(string) R) option.Option[R]
• func NonNil[T any](t *T) option.Option[T]
• func NonNilWith[T any, R any](t *T, fn func(T) R) option.Option[R]
• func NonZero[T comparable](t T) option.Option[T]
• func NonZeroWith[T comparable, R any](t T, fn func(T) R) option.Option[R]
• type Cond
  • func Of[T any](t T) Cond[T]
  • func (c Cond[T]) When(ok bool) option.Option[T]
• type LazyCond
  • func LazyOf[T any](fn func() T) LazyCond[T]
  • func (c LazyCond[T]) When(ok bool) option.Option[T]

Variables

var NonEmpty = option.NonEmpty

NonEmpty returns an ok option if s is not empty, or not-ok otherwise.

Functions

func FirstNonEmpty

func FirstNonEmpty(vals ...string) string

FirstNonEmpty returns the first non-empty string, or empty if all are empty. It is the string-specific variant of FirstNonZero.

func FirstNonNil

func FirstNonNil[T any](ptrs ...*T) (_ T)

FirstNonNil returns the dereferenced value of the first non-nil pointer, or zero if all are nil.

func FirstNonZero

func FirstNonZero[T comparable](vals ...T) (_ T)

FirstNonZero returns the first non-zero value, or zero if all are zero.

func NonEmptyWith

func NonEmptyWith[R any](s string, fn func(string) R) option.Option[R]

NonEmptyWith returns an ok option of fn(s) if s is not empty, or not-ok otherwise.

func NonNil

func NonNil[T any](t *T) option.Option[T]

NonNil returns an ok option of *t if t is not nil, or not-ok otherwise.

func NonNilWith

func NonNilWith[T any, R any](t *T, fn func(T) R) option.Option[R]

NonNilWith returns an ok option of fn(*t) if t is not nil, or not-ok otherwise.

func NonZero

func NonZero[T comparable](t T) option.Option[T]

NonZero returns an ok option if t is not the zero value, or not-ok otherwise.

func NonZeroWith

func NonZeroWith[T comparable, R any](t T, fn func(T) R) option.Option[R]

NonZeroWith returns an ok option of fn(t) if t is not the zero value, or not-ok otherwise.

Types

type Cond

type Cond[T any] struct {
	// contains filtered or unexported fields
}

Cond holds a value pending a condition check.

func Of

func Of[T any](t T) Cond[T]

Of wraps a value for conditional selection.

func (Cond[T]) When

func (c Cond[T]) When(ok bool) option.Option[T]

When returns an option: Ok(value) if condition true, NotOk if false.

type LazyCond

type LazyCond[T any] struct {
	// contains filtered or unexported fields
}

LazyCond holds a function for deferred value computation.

func LazyOf

func LazyOf[T any](fn func() T) LazyCond[T]

LazyOf wraps a function for lazy conditional selection. The function is only called if the condition is true.

func (LazyCond[T]) When

func (c LazyCond[T]) When(ok bool) option.Option[T]

When evaluates fn only if condition true, returns option.