Dysfunctional options pattern in Go

Ever since Rob Pike published the text on the functional options pattern¹, there’s been no shortage of blogs, talks, or comments on how it improves or obfuscates configuration ergonomics.

While the necessity of such a pattern is quite evident in a language that lacks default arguments in functions, more often than not, it needlessly complicates things. The situation gets worse if you have to maintain a public API where multiple configurations are controlled in this manner.

However, the pattern solves a valid problem and definitely has its place. Otherwise, it wouldn’t have been picked up by pretty much every other library²³.

If you have no idea what I’m talking about, you might want to give my previous write-up on configuring options⁴ a read.

Functional options pattern

As a recap, here’s how the functional options pattern works. Let’s say, you need to allow the users of your API to configure something. You can expose a struct from your package that’ll be passed to some other function to tune its behavior. For example:

package src

type Config struct {
    // Required
    Foo, Bar string

    // Optional
    Fizz, Bazz int
}

func Do(config *Config) {
    // Do something with the config values
}

Then the Config struct will be imported, initialized, and passed to the Do function by your API users:

package main

import ".../src"

func main() {
    // Initialize the config and pass it to the Do function
    config := &src.Config{
        Foo: "hello",
        Bar: "world",
        Fizz: 0,
        Bazz: 42,
    }

    // Call Do with the initialized Config struct
    src.Do(config)
}

This is one way of doing that, but it’s generally discouraged since it requires you to expose the internals of your API to the users. So instead, a library usually exposes a factory function that’ll do the struct initialization while keeping the struct and fields private. For instance:

package src

type config struct { // Notice that the struct and fields are now private
    // Required
    foo, bar string

    // Optional
    fizz, bazz int
}

// Public factory function
func NewConfig(foo, bar string, fizz, bazz int) config {
    return config{foo, bar, fizz, bazz}
}

func Do(c *config){}

The API consumers will now use NewConfig to produce a configuration and then pass the struct instance to the Do function as follows:

package main

import ".../src"

func main() {
    // Initialize the config with the NewConfig factory
    c := &src.NewConfig("hello", "world", 0, 42)

    // Call Do with the initialized Config struct
    src.Do(c)
}

This approach is better as it keeps the internal machinery hidden from users. However, it doesn’t allow for setting default values for some configuration attributes; all must be set explicitly. What if your users want to override the values of multiple attributes? This leads your configuration struct to be overloaded with options, making the NewConfig function demands numerous positional arguments.

This setup isn’t user-friendly, as it forces API users to explicitly pass all these options to the NewConfig factory. Ideally, you’d initialize config with some default values, offering users a chance to override them. But, Go doesn’t support default values for function arguments, which compels us to be creative and come up with different workarounds. Functional options pattern is one of them.

Here’s how you can build your API to leverage the pattern:

package src

type config struct {
    // Required
    foo, bar string

    // Optional
    fizz, bazz int
}

type option func(*config)

// The value of each optional configuration attribute can be overridden with
// an associated function
func WithFizz(fizz int) option {
    return func(c *config) {
        c.fizz = fizz
    }
}

func WithBazz(bazz int) option {
    return func(c *config) {
        c.bazz = bazz
    }
}

func NewConfig(foo, bar string, opts ...option) config {
    // First fill in the options with default values
    c := config{foo, bar, 10, 100}

    // Now allow users to override the optional configuration attributes
    for _, opt := range opts {
        opt(&c)
    }
    return c
}

func Do(c *config) {}

Then you’d use it as follows:

package main

import ".../src"

func main() {
    c := &src.NewConfig("hello", "world", src.WithFizz(1), src.WithBazz(2))
    src.Do(c)
}

Functional options pattern relies on functions that modify the configuration struct’s state. These modifier functions, or option functions, are defined to accept a pointer to the configuration struct *config and then directly alter its fields. This direct manipulation is possible because the option functions are closures, which means they capture and modify the variables from their enclosing scope, in this case, the config instance.

In the NewConfig factory, the variadic parameter opts ...option allows for an arbitrary number of option functions to be passed. Here, opts represents the optional configurations that the users can override if they want to.

The NewConfig function iterates over this slice of option functions, invoking each one with the &c argument, which is a pointer to the newly created config instance. The config instance is created with default values, and the users can use the With* functions to override them.

Curse of indirection

That’s a fair bit of indirection just to allow API users to configure some options. I don’t know about you, but multi-layered higher-order functions hurt my brain. It’s quite slow as well.

All this complexity could have been avoided if Go allowed default arguments in functions. Your configuration factory could simply grab the default values from the keyword arguments and pass them to the underlying struct. The idea that supporting default arguments in functions would lead to a parameter explosion seems unfounded, especially when the alternative requires gymnastics like the functional option pattern.

Also, the multiple layers of indirection hinder API discoverability. Trying to discover modifier functions by hovering your cursor over the factory function’s return value in the IDE won’t be very helpful, as these functions are defined at the package level.

So, if you need to configure multiple structs in this manner, the explosion of their respective package-level modifiers make it even harder for the user to know which function they’ll need to use to update a certain configuration attribute.

Recently, I’ve spontaneously stumbled upon a fluent-style API to manage configurations that don’t require so many layers of indirection and lets you expose optional configuration attributes. Let’s call it dysfunctional options pattern.

Dysfunctional options pattern

The idea is quite similar to how the API with functional options pattern is constructed. Here’s the complete implementation:

package src

type config struct {
    // Required
    foo, bar string

    // Optional
    fizz, bazz int
}

// Each optional configuration attribute will have its own public method
func (c *config) WithFizz(fizz int) *config {
    c.fizz = fizz
    return c
}

func (c *config) WithBazz(bazz int) *config {
    c.bazz = bazz
    return c
}

// This only accepts the required options as params
func NewConfig(foo, bar string) *config {
    // First fill in the options with default values
    return &config{foo, bar, 10, 100}
}

func Do(c *config) {}

You’d use the API as follows:

package main

import ".../src"

func main() {
    // Initialize the struct with only the required options and then chain
    // the option methods to update the optional configuration attributes
    c := src.NewConfig("hello", "world").WithFizz(0).WithBazz(42)
    src.Do(c)
}

Similar to the previous pattern, we have modifiers here too. However, instead of being higher order functions, the modifiers are methods on config and return a pointer to the struct.

The NewConfig factory function instantiates the config struct with some default values and returns the struct pointer like the modifiers. This enables us to chain the WithFizz and WithBazz modifiers on the returned value of NewConfig and update the values of the optional configuration attributes.

Apart from simplicity and the lack of magic, you can hover over the return type of the factory and immediately know about the supported modifier methods.

I did a rudimentary benchmark⁵ of the two approaches and was surprised that the second one was roughly ~76x faster on Go 1.22!

Here’s an example⁶ of the pattern in the wild.

P.S. This is indeed a lightweight spin on what OO languages call the builder pattern. However, I didn’t call it that because there’s no mandatory .Build() method to be called at the end of the method chain.

Functional options pattern#

Curse of indirection#

Dysfunctional options pattern#

Recent posts

Functional options pattern

Curse of indirection

Dysfunctional options pattern