option

README

option

Optional values that move absence checks from runtime to the type system.

// Before: four lines to safely extract a map value with a default
token, ok := headers["Authorization"]
if !ok {
    token = "none"
}

// After
token := option.Lookup(headers, "Authorization").Or("none")

Four lines become one.

What It Looks Like

// Environment with default
port := option.Getenv("PORT").Or("8080")

// Conditional pipeline
name := userOption.KeepIf(User.IsActive).ToString(User.Name).Or("unknown")

// Comma-ok extraction
if user, ok := userOption.Get(); ok {
    fmt.Println(user.Name)
}

// Side effect — fires only if ok
userOption.IfOk(User.Save)

// Before: three separate absence checks, then assemble
host := record.RawHost()
if host == "" {
    host = "localhost"
}
port := os.Getenv("PORT")
if port == "" {
    port = "8080"
}
name, ok := labels["name"]
if !ok {
    name = "default"
}
return Config{Host: host, Port: port, Name: name}

// After: every field resolves inline
return Config{
    Host: record.Host().Or("localhost"),
    Port: option.Getenv("PORT").Or("8080"),
    Name: option.Lookup(labels, "name").Or("default"),
}

// Tri-state boolean — option.Bool is Option[bool]
type ScanResult struct {
    IsConnected option.Bool  // true, false, or unknown
}
connected := result.IsConnected.OrFalse()  // unknown → false

// Nullable field — return option instead of zero value
func (r Record) Host() option.String {
    return option.NonZero(r.host)
}
// Caller decides how to handle absence
addr := record.Host().Or("localhost")

One Type for All of Go's "Maybe" Patterns

Go represents absence three different ways: *T (nil), zero values ("", 0), and comma-ok returns (map lookup, type assertion). All three let you skip the check and use the value directly — the failure shows up at runtime, not compile time.

Option[T] unifies them. Factory functions bridge each Go pattern into a single chainable type:

• NonNil(ptr) — pointer-based absence
• NonZero(count), NonEmpty(name) — zero-value absence
• Lookup(m, key), New(val, ok) — comma-ok absence
• Getenv("PORT") — environment variable absence

Once you have a Option[T], the same API works regardless of where the value came from: .Or("default"), .KeepIf(valid), .ToString(format), .Get().

Operations

Option[T] holds an optional value — ok or not-ok. Type aliases String, Int, Bool, etc. are shorthand for common types, with pre-declared not-ok values (NotOkString, NotOkInt, etc.). JSON serialization via MarshalJSON/UnmarshalJSON (ok → value, not-ok → null).

• Create: Of, New, NotOk, NonZero, NonEmpty, NonNil, Getenv, Lookup
• Create + Transform: NonZeroWith, NonEmptyWith, NonNilWith — check presence and transform in one call
• Extract: Get, IsOk, MustGet, Or, OrCall, OrZero, OrEmpty, OrFalse
• Transform: Convert, Map, ToString, ToInt, other To*, ToOpt
• Filter: KeepIf, RemoveIf
• Side effects: IfOk, IfNotOk, Lift

See pkg.go.dev for complete API documentation, the main README for installation, Nil Safety in Go for the full discussion, and the showcase for real-world rewrites.

Documentation

Overview

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

Index

• Variables
• func Lift[T any](fn func(T)) func(Option[T])
• type Any
• type Bool
• type Byte
• type Error
• type Int
• type Option
  • func Lookup[K comparable, V any](m map[K]V, key K) (_ Option[V])
  • func Map[T, R any](b Option[T], fn func(T) R) (_ Option[R])
  • func New[T any](t T, ok bool) (_ Option[T])
  • func NonEmptyWith[R any](s string, fn func(string) R) (_ Option[R])
  • func NonNil[T any](t *T) (_ Option[T])
  • func NonNilWith[T any, R any](t *T, fn func(T) R) (_ Option[R])
  • func NonZero[T comparable](t T) (_ Option[T])
  • func NonZeroWith[T comparable, R any](t T, fn func(T) R) (_ Option[R])
  • func NotOk[T any]() (_ Option[T])
  • func Of[T any](t T) Option[T]
  • func (b Option[T]) Convert(fn func(T) T) (_ Option[T])
  • func (b Option[T]) Get() (_ T, _ bool)
  • func (b Option[T]) IfNotOk(fn func())
  • func (b Option[T]) IfOk(fn func(T))
  • func (b Option[T]) IsOk() bool
  • func (b Option[T]) KeepIf(fn func(T) bool) (_ Option[T])
  • func (o Option[T]) MarshalJSON() ([]byte, error)
  • func (b Option[T]) MustGet() T
  • func (b Option[T]) Or(t T) T
  • func (b Option[T]) OrCall(fn func() T) (_ T)
  • func (b Option[T]) OrEmpty() (_ T)
  • func (b Option[T]) OrFalse() bool
  • func (b Option[T]) OrZero() (_ T)
  • func (b Option[T]) RemoveIf(fn func(T) bool) (_ Option[T])
  • func (b Option[T]) ToAny(fn func(T) any) (_ Option[any])
  • func (b Option[T]) ToBool(fn func(T) bool) (_ Option[bool])
  • func (b Option[T]) ToByte(fn func(T) byte) (_ Option[byte])
  • func (b Option[T]) ToError(fn func(T) error) (_ Option[error])
  • func (b Option[T]) ToInt(fn func(T) int) (_ Option[int])
  • func (b Option[T]) ToOpt() (_ *T)
  • func (b Option[T]) ToRune(fn func(T) rune) (_ Option[rune])
  • func (b Option[T]) ToString(fn func(T) string) (_ Option[string])
  • func (o *Option[T]) UnmarshalJSON(data []byte) error
• type Rune
• type String
  • func Getenv(key string) String
  • func NonEmpty(s string) (_ String)

Variables

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

Functions

func Lift

func Lift[T any](fn func(T)) func(Option[T])

Lift transforms a function operating on T into one operating on Option[T]. The lifted function executes only when the option is ok.

Types

type Any

type Any = Option[any]

type Bool

type Bool = Option[bool]

type Byte

type Byte = Option[byte]

type Error

type Error = Option[error]

type Int

type Int = Option[int]

type Option

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

Option represents an optional value of type T.

func Lookup

func Lookup[K comparable, V any](m map[K]V, key K) (_ Option[V])

Lookup returns an ok option of the value at key in m, or not-ok if the key is absent.

func Map

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

func New

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

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

func NonEmptyWith

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

NonEmptyWith returns an ok option of fn(s) provided that s is not empty, or not-ok otherwise. It is the string-specific variant of NonZeroWith.

func NonNil

func NonNil[T any](t *T) (_ Option[T])

NonNil 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 NonNilWith

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

NonNilWith returns an ok option of fn(*t) provided that t is not nil, or not-ok otherwise. It dereferences the pointer before passing to fn, matching NonNil's behavior.

func NonZero

func NonZero[T comparable](t T) (_ Option[T])

NonZero returns an ok option of t provided that t is not the zero value for T, or not-ok otherwise. Zero values include "" for strings, 0 for numbers, false for bools, etc.

func NonZeroWith

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

NonZeroWith returns an ok option of fn(t) provided that t is not the zero value for T, or not-ok otherwise. It combines NonZero and a transform in one call — check presence and transform in a single step.

func NotOk

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

func Of

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

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

func (Option[T]) Convert

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

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

func (Option[T]) Get

func (b Option[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 (Option[T]) IfNotOk

func (b Option[T]) IfNotOk(fn func())

IfNotOk calls fn if the option is not ok.

func (Option[T]) IfOk

func (b Option[T]) IfOk(fn func(T))

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

func (Option[T]) IsOk

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

IsOk returns true if the option is ok.

func (Option[T]) KeepIf

func (b Option[T]) KeepIf(fn func(T) bool) (_ Option[T])

KeepIf 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 RemoveIf method as well.

func (Option[T]) MarshalJSON

func (o Option[T]) MarshalJSON() ([]byte, error)

MarshalJSON serializes Option: Ok(v) → v, NotOk → null

func (Option[T]) MustGet

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

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

func (Option[T]) Or

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

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

func (Option[T]) OrCall

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

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

func (Option[T]) OrEmpty

func (b Option[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 (Option[T]) OrFalse

func (b Option[T]) OrFalse() bool

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

func (Option[T]) OrZero

func (b Option[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 (Option[T]) RemoveIf

func (b Option[T]) RemoveIf(fn func(T) bool) (_ Option[T])

RemoveIf 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 (Option[T]) ToAny

func (b Option[T]) ToAny(fn func(T) any) (_ Option[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 (Option[T]) ToBool

func (b Option[T]) ToBool(fn func(T) bool) (_ Option[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 (Option[T]) ToByte

func (b Option[T]) ToByte(fn func(T) byte) (_ Option[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 (Option[T]) ToError

func (b Option[T]) ToError(fn func(T) error) (_ Option[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 (Option[T]) ToInt

func (b Option[T]) ToInt(fn func(T) int) (_ Option[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 (Option[T]) ToOpt

func (b Option[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 (Option[T]) ToRune

func (b Option[T]) ToRune(fn func(T) rune) (_ Option[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 (Option[T]) ToString

func (b Option[T]) ToString(fn func(T) string) (_ Option[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.

func (*Option[T]) UnmarshalJSON

func (o *Option[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes Option: null → NotOk, value → Ok(value)

type Rune

type Rune = Option[rune]

type String

type String = Option[string]

func Getenv

func Getenv(key string) String

func NonEmpty

func NonEmpty(s string) (_ String)

NonEmpty returns an ok option of s provided that s is not empty, or not-ok otherwise. It is the string-specific variant of NonZero.