option

package
v0.27.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2026 License: MIT Imports: 2 Imported by: 0

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.KeepOkIf(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 Basic[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.IfNotZero(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.

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

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

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

Operations

Basic[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, IfNotZero, IfNotEmpty, IfNotNil, Getenv, Lookup
  • Extract: Get, IsOk, MustGet, Or, OrCall, OrZero, OrEmpty, OrFalse
  • Transform: Convert, Map, ToString, ToInt, other To*, ToOpt
  • Filter: KeepOkIf, ToNotOkIf
  • Side effects: IfOk, IfNotOk, Lift

For domain-specific option types with conditional method dispatch, see the advanced option example.

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

Constants

This section is empty.

Variables

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

Functions

func Lift added in v0.15.0 

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

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

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 added in v0.10.0 

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 added in v0.7.0 

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. Zero values include "" for strings, 0 for numbers, false for bools, etc.

func Lookup added in v0.23.0 

func Lookup[K comparable, V any](m map[K]V, key K) (_ Basic[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 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]) Convert added in v0.9.0 

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]) IfNotOk added in v0.23.0 

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

IfNotOk calls fn if the option is not ok.

func (Basic[T]) IfOk added in v0.23.0 

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

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

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]) MarshalJSON added in v0.14.0 

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

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

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() 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 (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.

func (*Basic[T]) UnmarshalJSON added in v0.14.0 

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

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

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

func IfNotEmpty added in v0.12.0 

func IfNotEmpty(s string) (_ String)

IfNotEmpty returns an ok option of s provided that s is not empty, or not-ok otherwise. It is a readable alias for IfNotZero when the type is string.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.