option

README

option: nil-safe optional values

Represent values that may be absent. Options enforce checking before use—nil panics become compile-time errors.

An option is either ok (has a value) or not-ok (absent).

host := config.GetHost().Or("localhost")  // default if absent

See pkg.go.dev for complete API documentation. For the full discussion of nil safety, see Nil Safety in Go. For function naming patterns, see Naming Functions for Higher-Order Functions.

Quick Start

import "github.com/binaryphile/fluentfp/option"

// Create options
okHello := option.Of("hello")           // ok
notOkString := option.NotOkString       // not-ok

// Extract with defaults
hello := okHello.Or("fallback")
fallback := notOkString.Or("fallback")

// Check and extract
if hello, ok := okHello.Get(); ok {
    // use hello
}

Types

Basic[T] holds an optional value—either "ok" (has value) or "not-ok" (absent).

Type aliases String, Int, Bool are shorthand for Basic[string], Basic[int], etc. See Type Aliases for the full list.

API Reference

Constructors

Function	Signature	Purpose	Example
Of	Of[T](T) Basic[T]	Create ok option	option.Of(user)
New	New[T](T, bool) Basic[T]	From value + ok flag	option.New(val, ok)
NotOk	NotOk[T]() Basic[T]	Create not-ok option	option.NotOk[User]()
IfNotZero	IfNotZero[T comparable](T) Basic[T]	Not-ok if zero	option.IfNotZero(name)
IfNotNil	IfNotNil[T](*T) Basic[T]	Not-ok if nil	option.IfNotNil(userPtr)
Getenv	Getenv(string) String	From env var	option.Getenv("PORT")

Pseudo-options: Go APIs sometimes use *T (nil = absent) or zero values (empty = absent) as pseudo-options. IfNotNil and IfNotZero convert these to formal options.

Extraction Methods

Method	Signature	Purpose	Example
.Get	.Get() (T, bool)	Comma-ok unwrap	user, ok := userOption.Get()
.IsOk	.IsOk() bool	Check if ok	if nameOption.IsOk()
.MustGet	.MustGet() T	Value or panic	user = userOption.MustGet()
.Or	.Or(T) T	Value or default	port = portOption.Or("8080")
.OrCall	.OrCall(func() T) T	Lazy default	port = portOption.OrCall(findPort)
.OrZero	.OrZero() T	Value or zero	name = nameOption.OrZero()
.OrEmpty	.OrEmpty() T	Alias for strings	name = nameOption.OrEmpty()
.OrFalse	.OrFalse() bool	For option.Bool	enabled = flagOption.OrFalse()
.ToOpt	.ToOpt() *T	Convert to pointer	ptr = userOption.ToOpt()

Filtering Methods

Method	Signature	Purpose	Example
.KeepOkIf	.KeepOkIf(func(T) bool) Basic[T]	Not-ok if false	active = userOption.KeepOkIf(User.IsActive)
.ToNotOkIf	.ToNotOkIf(func(T) bool) Basic[T]	Not-ok if true	valid = userOption.ToNotOkIf(User.IsExpired)

Mapping Methods

Method	Signature	Purpose	Example
.Convert	.Convert(func(T) T) Basic[T]	Transform, same type	normalized = userOption.Convert(User.Normalize)
.ToString	.ToString(func(T) string) String	Transform to string	name = userOption.ToString(User.Name)
.ToInt	.ToInt(func(T) int) Int	Transform to int	age = userOption.ToInt(User.Age)
Map	Map[T,R](Basic[T], func(T)R) Basic[R]	Transform to any type	role = option.Map(userOption, User.Role)

Other To[Type] methods: ToAny, ToBool, ToByte, ToError, ToRune

Side Effects

Method	Signature	Purpose	Example
.Call	.Call(func(T))	Execute if ok	userOption.Call(User.Save)

Type Aliases

Pre-defined types: String, Int, Bool, Error, Any, Byte, Rune

Pre-defined not-ok values: NotOkString, NotOkInt, NotOkBool, NotOkError, NotOkAny, NotOkByte, NotOkRune

Creating Options

// From known value
opt := option.Of("hello")

// Conditional creation
opt := option.New(value, ok)

// From comparable (not-ok if zero)
opt := option.IfNotZero(maybeEmpty)

// From pointer (not-ok if nil)
opt := option.IfNotNil(ptr)

// From environment
port := option.Getenv("PORT").Or("8080")

Using Options

// Get with comma-ok
if val, ok := opt.Get(); ok {
    // use val
}

// Get with default
val := opt.Or("default")
val := opt.OrCall(expensiveDefault)
val := opt.OrZero()

// Transform
length := opt.ToInt(func(s string) int { return len(s) })
upper := option.Map(opt, strings.ToUpper)

// Filter
nonEmpty := opt.KeepOkIf(func(s string) bool { return s != "" })

// Side effect
opt.Call(fmt.Println)

When NOT to Use option

• Go idiom (T, error) — Don't replace error returns with option
• Performance-critical paths — Option adds a bool field; profile first
• Simple nil checks — If if ptr != nil is clear, don't over-engineer
• When error context matters — Option loses why something is absent

Patterns

Tri-State Boolean

type ScanResult struct {
    IsConnected option.Bool  // true, false, or unknown
}

connected := result.IsConnected.OrFalse()  // unknown → false

Nullable Database Fields

func (r Record) GetHost() option.String {
    return option.IfNotZero(r.NullableHost.String)
}

Advanced: Domain Option Types

For domain-specific behavior (conditional lifecycle management, dependency injection), see the advanced option example.

See Also

For typed failure values instead of absent, see either.

Documentation

Overview

Package option provides types and functions to work with optional values.

Index

• Variables
• type Any
• type Basic
  • func IfNotNil[T any](t *T) (_ Basic[T])
  • func IfNotZero[T comparable](t T) (_ Basic[T])
  • func Map[T, R any](b Basic[T], fn func(T) R) (_ Basic[R])
  • func New[T any](t T, ok bool) (_ Basic[T])
  • func NotOk[T any]() (_ Basic[T])
  • func Of[T any](t T) Basic[T]
  • func (b Basic[T]) Call(fn func(T))
  • func (b Basic[T]) Convert(fn func(T) T) (_ Basic[T])
  • func (b Basic[T]) Get() (_ T, _ bool)
  • func (b Basic[T]) IsOk() bool
  • func (b Basic[T]) KeepOkIf(fn func(T) bool) (_ Basic[T])
  • func (b Basic[T]) MustGet() T
  • func (b Basic[T]) Or(t T) T
  • func (b Basic[T]) OrCall(fn func() T) (_ T)
  • func (b Basic[T]) OrEmpty() (_ T)
  • func (b Basic[T]) OrFalse() (_ T)
  • func (b Basic[T]) OrZero() (_ T)
  • func (b Basic[T]) ToAny(fn func(T) any) (_ Basic[any])
  • func (b Basic[T]) ToBool(fn func(T) bool) (_ Basic[bool])
  • func (b Basic[T]) ToByte(fn func(T) byte) (_ Basic[byte])
  • func (b Basic[T]) ToError(fn func(T) error) (_ Basic[error])
  • func (b Basic[T]) ToInt(fn func(T) int) (_ Basic[int])
  • func (b Basic[T]) ToNotOkIf(fn func(T) bool) (_ Basic[T])
  • func (b Basic[T]) ToOpt() (_ *T)
  • func (b Basic[T]) ToRune(fn func(T) rune) (_ Basic[rune])
  • func (b Basic[T]) ToString(fn func(T) string) (_ Basic[string])
• type Bool
• type Byte
• type Error
• type Int
• type Rune
• type String
  • func Getenv(key string) String

Variables

var (
	NotOkAny    = Basic[any]{}
	NotOkBool   = Basic[bool]{}
	NotOkByte   = Basic[byte]{}
	NotOkError  = Basic[error]{}
	NotOkInt    = Basic[int]{}
	NotOkRune   = Basic[rune]{}
	NotOkString = Basic[string]{}
)

Types

type Any

type Any = Basic[any]

type Basic

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

Basic represents an optional value of type T.

func IfNotNil

func IfNotNil[T any](t *T) (_ Basic[T])

IfNotNil returns an ok option of *what t points at* provided that t is not nil, or not-ok otherwise. It converts a pointer-based pseudo-option (where nil means absent) into a formal option.

func IfNotZero

func IfNotZero[T comparable](t T) (_ Basic[T])

IfNotZero returns an ok option of t provided that t is not the zero value for T, or not-ok otherwise.

func Map

func Map[T, R any](b Basic[T], fn func(T) R) (_ Basic[R])

func New

func New[T any](t T, ok bool) (_ Basic[T])

New returns an ok option of t provided that ok is true, or not-ok otherwise.

func NotOk

func NotOk[T any]() (_ Basic[T])

func Of

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

Of returns an ok option of t, independent of t's value.

func (Basic[T]) Call

func (b Basic[T]) Call(fn func(T))

Call applies fn to the option's value provided that the option is ok.

func (Basic[T]) Convert

func (b Basic[T]) Convert(fn func(T) T) (_ Basic[T])

Convert returns the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) Get

func (b Basic[T]) Get() (_ T, _ bool)

Get returns the option's value and a boolean indicating the option's status. It unpacks the option's fields into Go's comma-ok idiom, making it useful in the usual Go conditional constructs. When used in this manner, myVal doesn't stick around in the namespace when you're done with it:

if myVal, ok := o.Get; ok {
  do some stuff
}

func (Basic[T]) IsOk

func (b Basic[T]) IsOk() bool

IsOk returns true if the option is ok.

func (Basic[T]) KeepOkIf

func (b Basic[T]) KeepOkIf(fn func(T) bool) (_ Basic[T])

KeepOkIf returns b provided that applying fn to an ok option's value returns true, or the original option otherwise. It is the filter operation. Since Go doesn't offer a convenient lambda syntax for constructing the negation of a function's output, there is a ToNotOkIf method as well.

func (Basic[T]) MustGet

func (b Basic[T]) MustGet() T

MustGet returns the option's value or panics if the option is not ok.

func (Basic[T]) Or

func (b Basic[T]) Or(t T) T

Or returns the option's value provided that the option is ok, otherwise t.

func (Basic[T]) OrCall

func (b Basic[T]) OrCall(fn func() T) (_ T)

OrCall returns the option's value provided that it is ok, otherwise the result of calling fn.

func (Basic[T]) OrEmpty

func (b Basic[T]) OrEmpty() (_ T)

OrEmpty returns the option's value provided that it is ok, otherwise the zero value for T. It is a more readable alias for OrZero when T is string.

func (Basic[T]) OrFalse

func (b Basic[T]) OrFalse() (_ T)

OrFalse returns the option's value provided that it is ok, otherwise the zero value for T. It is a more readable alias for OrZero when T is bool.

func (Basic[T]) OrZero

func (b Basic[T]) OrZero() (_ T)

OrZero returns the option's value provided that it is ok, otherwise the zero value for T. See OrEmpty and OrFalse for more readable aliases of OrZero when T is string or bool.

func (Basic[T]) ToAny

func (b Basic[T]) ToAny(fn func(T) any) (_ Basic[any])

ToAny returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) ToBool

func (b Basic[T]) ToBool(fn func(T) bool) (_ Basic[bool])

ToBool returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) ToByte

func (b Basic[T]) ToByte(fn func(T) byte) (_ Basic[byte])

ToByte returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) ToError

func (b Basic[T]) ToError(fn func(T) error) (_ Basic[error])

ToError returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) ToInt

func (b Basic[T]) ToInt(fn func(T) int) (_ Basic[int])

ToInt returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) ToNotOkIf

func (b Basic[T]) ToNotOkIf(fn func(T) bool) (_ Basic[T])

ToNotOkIf returns a not-ok option provided that applying fn to an ok option's value returns true, or the original option otherwise. It is the filter operation with negation. Since Go doesn't offer a convenient lambda syntax for constructing the negation of a function's output, having negation built-in is both a convenience and keeps consuming code readable.

func (Basic[T]) ToOpt

func (b Basic[T]) ToOpt() (_ *T)

ToOpt returns a pointer-based pseudo-option of the pointed-at value provided that the option is ok, or not-ok otherwise. By convention, in consuming code, we suffix a pseudo-option's variable name with an "Opt" suffix to clarify the pointer's meaning and use, hence "ToOpt".

func (Basic[T]) ToRune

func (b Basic[T]) ToRune(fn func(T) rune) (_ Basic[rune])

ToRune returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

func (Basic[T]) ToString

func (b Basic[T]) ToString(fn func(T) string) (_ Basic[string])

ToString returns an option of the result of applying fn to the option's value provided that the option is ok, or not-ok otherwise.

type Bool

type Bool = Basic[bool]

type Byte

type Byte = Basic[byte]

type Error

type Error = Basic[error]

type Int

type Int = Basic[int]

type Rune

type Rune = Basic[rune]

type String

type String = Basic[string]

func Getenv

func Getenv(key string) String