Functional Options

The functional options pattern lets a constructor stay backward compatible while accepting an open-ended set of optional settings. Callers pass only what differs from the defaults; new options never break old call sites.

Core Rules

1. Reach for functional options at 3+ optional parameters or whenever the API will grow.
2. The `options` struct is unexported. Only the package owns its shape.
3. The `Option` interface has an unexported `apply` method. No external package can forge an option.
4. Defaults go inside the constructor, before options are applied.
5. Required parameters stay positional; only the optional ones go through ...Option.
6. Prefer the interface form over closures — it composes better with testing, debugging, and fmt.Stringer.

When to Use What

Read references/options-vs-struct.md when choosing between options and a plain config struct, or designing a hybrid.

The Canonical Pattern

package db

import "go.uber.org/zap"

// options is the package's private bag of settings.
type options struct {
    cache  bool
    logger *zap.Logger
}

// Option configures Open.
type Option interface {
    apply(*options)
}

// --- cacheOption -----------------------------------------------------------

type cacheOption bool

func (c cacheOption) apply(o *options) { o.cache = bool(c) }

// WithCache enables or disables the in-memory cache.
func WithCache(enabled bool) Option { return cacheOption(enabled) }

// --- loggerOption ----------------------------------------------------------

type loggerOption struct{ log *zap.Logger }

func (l loggerOption) apply(o *options) { o.logger = l.log }

// WithLogger sets the logger used by the connection.
func WithLogger(log *zap.Logger) Option { return loggerOption{log: log} }

// --- constructor -----------------------------------------------------------

// Open dials addr using the given options.
func Open(addr string, opts ...Option) (*Connection, error) {
    o := options{
        cache:  true,
        logger: zap.NewNop(),
    }
    for _, opt := range opts {
        opt.apply(&o)
    }
    // ... build the connection from o
    return &Connection{}, nil
}

Caller Experience

db.Open(addr)
db.Open(addr, db.WithLogger(log))
db.Open(addr, db.WithCache(false), db.WithLogger(log))

Compare to the alternative where all defaults must be repeated:

db.Open(addr, db.DefaultCache, zap.NewNop()) // tedious

Why an Interface, Not a Closure?

// The closure variant — discouraged
type Option func(*options)

The interface form wins on:

1. Testability — option values can be compared in tests.
2. Debuggability — option types can implement fmt.Stringer.
3. Documentation — godoc lists each option type explicitly.
4. Extensibility — options can implement additional interfaces (e.g., Validate()).

Closures are shorter to write; they pay for that shortness in introspection.

Defaults

Set defaults before applying options. A constructor that ignores its defaults is a bug magnet:

o := options{
    cache:  true,
    logger: zap.NewNop(),
}
for _, opt := range opts {
    opt.apply(&o)
}

If a default needs computation (a temp dir, a process-wide ID), build it once during the constructor — not at package init.

Quick Reference

// 1. Unexported settings bag
type options struct { ... }

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

// 3. One option type per setting
type widgetOption Widget
func (w widgetOption) apply(o *options) { o.widget = Widget(w) }
func WithWidget(w Widget) Option         { return widgetOption(w) }

// 4. Constructor: defaults, then apply
func New(required string, opts ...Option) (*Thing, error) {
    o := options{ /* defaults */ }
    for _, opt := range opts { opt.apply(&o) }
    return build(required, o)
}

Anti-Patterns

Verification Checklist

• [ ] options is unexported
• [ ] Option interface has an unexported apply(*options) method
• [ ] Each setting has a With* constructor returning Option
• [ ] Constructor sets defaults first, then applies options
• [ ] Required parameters are not hidden behind ...Option
• [ ] No exported Apply or Option func(*options) slipped in
• [ ] Doc comments explain each With* and its default

References

• references/options-vs-struct.md — when to prefer a config struct, and how to combine the two