Functional Options Pattern Skill

Functional Options Pattern

Functional options is a pattern where you declare an opaque Option type that records information in an internal struct. The constructor accepts a variadic number of these options and applies them to configure the result.

Resource Routing

references/OPTIONS-VS-STRUCTS.md - Read when choosing between config structs and functional options, implementing the full interface-based option pattern, or evaluating hybrid constructor APIs.

When to Use

Use functional options when:

3+ optional arguments on constructors or public APIs
Extensible APIs that may gain new options over time
Clean caller experience is important (no need to pass defaults)

The Pattern

Core Components

Unexported options struct - holds all configuration
Exported Option interface - with unexported apply method
Option types - implement the interface
With* constructors - create options

Option Interface

type Option interface {
    apply(*options)
}

The unexported apply method ensures only options from this package can be used.

Comparison: Functional Options vs Config Struct

| Aspect | Functional Options | Config Struct | |--------|-------------------|---------------| | Extensibility | Add new With* functions | Add new fields (may break) | | Defaults | Built into constructor | Zero values or separate defaults | | Caller experience | Only specify what differs | Must construct entire struct | | Testability | Options are comparable | Struct comparison | | Complexity | More boilerplate | Simpler setup |

Prefer Config Struct when: Fewer than 3 options, options rarely change, all options usually specified together, or internal APIs only.

Why Not Closures?

The interface approach is preferred over closure-only options because:

Testability - Options can be compared in tests and mocks
Debuggability - Options can implement fmt.Stringer
Flexibility - Options can implement additional interfaces
Visibility - Option types are visible in documentation

Quick Reference

// 1. Unexported options struct with defaults
type options struct {
    field1 Type1
    field2 Type2
}

// 2. Exported Option interface, unexported method
type Option interface {
    apply(*options)
}

// 3. Option type + apply + With* constructor
type field1Option Type1

func (o field1Option) apply(opts *options) { opts.field1 = Type1(o) }
func WithField1(v Type1) Option            { return field1Option(v) }

// 4. Constructor applies options over defaults
func New(required string, opts ...Option) (*Thing, error) {
    o := options{field1: defaultField1, field2: defaultField2}
    for _, opt := range opts {
        opt.apply(&o)
    }
    // ...
}

Checklist

[ ] options struct is unexported
[ ] Option interface has unexported apply method
[ ] Each option has a With* constructor
[ ] Defaults are set before applying options
[ ] Required parameters are separate from ...Option

Related Skills

Interface design: See go-interfaces when designing the Option interface or choosing between interface and closure approaches
Naming conventions: See go-naming when naming With* constructors, option types, or the unexported options struct
Function design: See go-functions when organizing constructors within a file or formatting variadic signatures
Documentation: See go-documentation when documenting Option types, With* functions, or constructor behavior

External Resources

Self-referential functions and the design of options - Rob Pike
Functional options for friendly APIs - Dave Cheney

Agent Skills: Functional Options Pattern

Install this agent skill to your local

Skill Files