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: NonZeroMap, NonEmptyMap, NonNilMap — check presence and map 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, and Nil Safety in Go for the full discussion.

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 NonEmptyMap[R any](s string, fn func(string) R) (_ Option[R])
  • func NonNil[T any](t *T) (_ Option[T])
  • func NonNilMap[T any, R any](t *T, fn func(T) R) (_ Option[R])
  • func NonZero[T comparable](t T) (_ Option[T])
  • func NonZeroMap[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 NonEmptyMap

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

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

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 NonNilMap

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

NonNilMap 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 NonZeroMap

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

NonZeroMap 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 Map 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.