optional

README

optional

Package optional is a generic implementation of functional options for type-safe, friendly constructor APIs.

[!IMPORTANT] Despite the name, this is not a Some/None/Maybe/Option monad. It implements the functional-options pattern — composable values that configure a *T via Apply(*T) — for building friendly constructor APIs. If you came looking for an optional/nullable value type, this is not that.

Install

go get github.com/gomatic/go-optional

Requires Go 1.26+.

Usage

An Option[T] is anything that can Apply(*T). Define option types for your struct and apply them with New or NewWithDefault.

type Thing struct{ name string }

type Name string

func (n Name) Apply(t *Thing) { optional.Must(t).name = string(n) }

thing := optional.New[Thing](Name("example"))
withDefault := optional.NewWithDefault(Thing{name: "default"}, Name("override"))

Configuration maps

Configuration is a string-keyed map with typed keys, decodable into a struct via mapstructure.

const port optional.ConfigurationKey[int] = "port"

type Config struct {
    Port int `mapstructure:"port"`
}

cfg, err := optional.Decode[Config](optional.NewConfiguration(port.Opt(8080)))

API

Symbol	Description
Option[T]	Interface for a value that applies fields to a *T
New[T]	Build a T from options
NewWithDefault[T]	Build a T from a default plus options
Must[T]	Return a non-nil *T, guarding against nil
Map[K, V] / Pair[K, V]	Generic option-applied map and its key/value option
Configuration / ConfigurationKey[T] / Opt[T]	String-keyed config map, typed keys, and options
NewConfiguration / Decode[T] / KV / Enabled	Build, decode, and construct configuration options

License

See LICENSE.

Documentation

Overview

Package optional is a generic take on [functional options](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis).

Index

• func Decode[T any](in Configuration) (*T, error)
• func Must[T any](t *T) *T
• func New[T any](opts ...Option[T]) T
• func NewWithDefault[T any](def T, opts ...Option[T]) T
• type Configuration
  • func NewConfiguration(opts ...Option[Configuration]) Configuration
• type ConfigurationKey
  • func (o ConfigurationKey[T]) Opt(v T) Opt[T]
• type Error
  • func (e Error) Error() string
• type Map
• type Opt
  • func Enabled(o ConfigurationKey[bool]) Opt[bool]
  • func KV[T any](k string, v T) Opt[T]
  • func (c Opt[T]) Apply(t *Configuration)
• type Option
• type Pair
  • func (c Pair[K, V]) Apply(t *Map[K, V])

Functions

func Decode

func Decode[T any](in Configuration) (*T, error)

Decode turns the Configuration map into a struct for you.

func Must

func Must[T any](t *T) *T

Must keeps you safe from a nil panic: hand it a nil t and you get a new *T back (so using it inside an Apply just does nothing), otherwise you get t untouched. If you'd actually rather have the panic, skip Must and let the usual nil panic happen.

func New

func New[T any](opts ...Option[T]) T

New returns a T that's been initialized with all the options you handed it.

func NewWithDefault

func NewWithDefault[T any](def T, opts ...Option[T]) T

NewWithDefault returns a T that starts from a default T and then has all the options applied on top.

Types

type Configuration

type Configuration Map[string, any]

Configuration is a nice general-purpose configurable map.

func NewConfiguration

func NewConfiguration(opts ...Option[Configuration]) Configuration

NewConfiguration whips up a Configuration from whatever options you pass in.

type ConfigurationKey

type ConfigurationKey[T any] string

ConfigurationKey is a typed key for a value living in a Configuration.

func (ConfigurationKey[T]) Opt

func (o ConfigurationKey[T]) Opt(v T) Opt[T]

Opt builds an Opt for this key, wrapping up the value you give it.

type Error

type Error string

Error is the constant error type for the optional package; every error the package emits is a const of this type so callers can match it with errors.Is.

const ErrDecode Error = "optional: decode configuration"

ErrDecode reports that a Configuration could not be decoded into the target struct; it wraps the underlying mapstructure failure.

func (Error) Error

func (e Error) Error() string

Error satisfies the error interface, returning the sentinel's text.

type Map

type Map[K comparable, V any] map[K]V

Map is an even more general configurable map than a Configuration is.

type Opt

type Opt[T any] Pair[string, T]

Opt is a single Configuration option, ready to apply.

func Enabled

func Enabled(o ConfigurationKey[bool]) Opt[bool]

Enabled builds a bool Opt for this key and flips it on (true).

func KV

func KV[T any](k string, v T) Opt[T]

KV is a quick little helper for spinning up an Opt option.

func (Opt[T]) Apply

func (c Opt[T]) Apply(t *Configuration)

Apply is how Opt satisfies the Option interface.

type Option

type Option[T any] interface {
	Apply(*T)
}

Option is the interface for any type T that knows how to apply its field values to a *T through its Apply method.

type Pair

type Pair[K comparable, V any] struct {
	Key   K
	Value V
}

Pair is a single Map option, ready to apply.

func (Pair[K, V]) Apply

func (c Pair[K, V]) Apply(t *Map[K, V])

Apply is how Pair satisfies the Option interface.