Builder as a monoid by Mark Seemann
Builder, particularly Fluent Builder, is one of the more useful design patterns. Here's why.
This article is part of a series of articles about design patterns and their universal abstraction counterparts.
The Builder design pattern is an occasionally useful pattern, but mostly in its Fluent Builder variation. I've already described that Builder, Fluent Builder, and Immutable Fluent Builder are isomorphic. The Immutable Fluent Builder variation is a set of pure functions, so among the three variations, it best fits the set of universal abstractions that I've so far discussed in this article series.
Design Patterns describes 23 patterns. Some of these are more useful than others. I first read the book in 2003, and while I initially used many of the patterns, after some years I settled into a routine where I'd reach for the same handful of patterns and ignore the rest.
What makes some design patterns more universally useful than others? There's probably components of both subjectivity and chance, but I also believe that there's some correlation to universal abstractions. I consider abstractions universal when they are derived from universal truths (i.e. mathematics) instead of language features or 'just' experience. That's what the overall article series is about. In this article, you'll learn how the Builder pattern is an instance of a universal abstraction. Hopefully, this goes a long way towards explaining why it seems to be so universally useful.
Builder API, isolated #
I'll start with the HttpRequestMessageBuilder from the article about Builder isomorphisms, particularly its Immutable Fluent Builder incarnation. Start by isolating those methods that manipulate the Builder. These are the functions that had void return types in the original Builder incarnation. Imagine, for example, that you extract an interface of only those methods. What would such an interface look like?
public interface IHttpRequestMessageBuilder { HttpRequestMessageBuilder AddJsonBody(object jsonBody); HttpRequestMessageBuilder WithMethod(HttpMethod newMethod); }
Keep in mind that on all instance methods, the instance itself can be viewed as 'argument 0'. In that light, each of these methods take two arguments: a Builder and the formal argument (jsonBody and newMethod, respectively). Each method returns a Builder. I've already described how this is equivalent to an endomorphism. An endomorphism is a function that returns the same type of output as its input, and it forms a monoid.
This can be difficult to see, so I'll make it explicit. The code that follows only exists to illustrate the point. In no way do I endorse that you write code in this way.
Explicit endomorphism #
You can define a formal interface for an endomorphism:
public interface IEndomorphism<T> { T Run(T x); }
Notice that it's completely generic. The Run method takes a value of the generic type T and returns a value of the type T. The identity of the monoid, you may recall, is the eponymously named identity function which returns its input without modification. You can also define the monoidal combination of two endomorphisms:
public class AppendEndomorphism<T> : IEndomorphism<T> { private readonly IEndomorphism<T> morphism1; private readonly IEndomorphism<T> morphism2; public AppendEndomorphism(IEndomorphism<T> morphism1, IEndomorphism<T> morphism2) { this.morphism1 = morphism1; this.morphism2 = morphism2; } public T Run(T x) { return morphism2.Run(morphism1.Run(x)); } }
This implementation of IEndomorphism<T> composes two other IEndomorphism<T> objects. When its Run method is called, it first calls Run on morphism1 and then uses the return value of that method call (still a T object) as input for Run on morphism2.
If you need to combine more than two endomorphisms then that's also possible, because monoids accumulate.
Explicit endomorphism to change HTTP method #
You can adapt the WithMethod method to the IEndomorphism<HttpRequestMessageBuilder> interface:
public class ChangeMethodEndomorphism : IEndomorphism<HttpRequestMessageBuilder> { private readonly HttpMethod newMethod; public ChangeMethodEndomorphism(HttpMethod newMethod) { this.newMethod = newMethod; } public HttpRequestMessageBuilder Run(HttpRequestMessageBuilder x) { if (x is null) throw new ArgumentNullException(nameof(x)); return x.WithMethod(newMethod); } }
In itself, this is simple code, but it does turn things on their head. The newMethod argument is now a class field (and constructor argument), while the HttpRequestMessageBuilder has been turned into a method argument. Keep in mind that I'm not doing this because I endorse this style of API design; I do it to demonstrate how the Immutable Fluent Builder pattern is an endomorphism.
Since ChangeMethodEndomorphism is an Adapter between IEndomorphism<HttpRequestMessageBuilder> and the WithMethod method, I hope that this is becoming apparent. I'll show one more Adapter.
Explicit endomorphism to add a JSON body #
In the example code, there's one more method that modifies an HttpRequestMessageBuilder object, and that's the AddJsonBody method. You can also create an Adapter over that method:
public class AddJsonBodyEndomorphism : IEndomorphism<HttpRequestMessageBuilder> { private readonly object jsonBody; public AddJsonBodyEndomorphism(object jsonBody) { this.jsonBody = jsonBody; } public HttpRequestMessageBuilder Run(HttpRequestMessageBuilder x) { if (x is null) throw new ArgumentNullException(nameof(x)); return x.AddJsonBody(jsonBody); } }
While the AddJsonBody method itself is more complicated than WithMethod, the Adapter is strikingly similar.
Running an explicit endomorphism #
You can use the IEndomorphism<T> API to compose a pipeline of operations that will, for example, make an HttpRequestMessageBuilder build an HTTP POST request with a JSON body:
IEndomorphism<HttpRequestMessageBuilder> morphism = new AppendEndomorphism<HttpRequestMessageBuilder>( new ChangeMethodEndomorphism(HttpMethod.Post), new AddJsonBodyEndomorphism(new { id = Guid.NewGuid(), date = "2020-03-22 19:30:00", name = "Ælfgifu", email = "ælfgifu@example.net", quantity = 1 }));
You can then Run the endomorphism over a new HttpRequestMessageBuilder object to produce an HTTP request:
HttpRequestMessage msg = morphism.Run(new HttpRequestMessageBuilder(url)).Build();
The msg object represents an HTTP POST request with the supplied JSON body.
Once again, I stress that the purpose of this little exercise is only to demonstrate how an Immutable Fluent Builder is an endomorphism, which is a monoid.
Test Data Builder endomorphism #
You can give Test Data Builders the same treatment, again only to demonstrate that the reason they compose so well is because they're monoids. I'll use an immutable variation of the AddressBuilder from this article.
For example, to modify a city, you can introduce an endomorphism like this:
public class CityEndomorphism : IEndomorphism<AddressBuilder> { private readonly string city; public CityEndomorphism(string city) { this.city = city; } public AddressBuilder Run(AddressBuilder x) { return x.WithCity(city); } }
You can use it to create an address in Paris like this:
IEndomorphism<AddressBuilder> morphism = new CityEndomorphism("Paris"); Address address = morphism.Run(new AddressBuilder()).Build();
The address is fully populated with Street, PostCode, and so on, but apart from City, you know none of the values.
Sweet spot #
Let's return to the question from the introduction to the article. What makes some design patterns useful? I don't think that there's a single answer to that question, but I find it intriguing that so many of the useful patterns turn out to be equivalent to universal abstractions. The Builder pattern is a monoid. From a programming perspective, the most useful characteristic of semigroups and monoids is that they enable you to treat many objects as one object. Monoids compose.
Of the three Builder variations, the Immutable Fluent Builder is the most useful. It's also the variation that most clearly corresponds to the endomorphism monoid. Viewing it as an endomorphism reveals its strengths. When or where is a Builder most useful?
Don't be mislead by Design Patterns, which states the intent of the Builder pattern like this:
This may still be the case, but I don't find that this is the primary advantage offered by the pattern. We've learned much about the utility of each design pattern since 1994, so I don't blame the Gang of Four for not seeing this. I do think, however, that it's important to emphasise that the benefit you can derive from a pattern may differ from the original motivation."Separate the construction of a complex object from its representation so that the same construction process can create different representations."
An endomorphism represents a modification of a value. You need a value to get started, and you get a modified value (of the same type) as output.
Sometimes, all you need is the initial object.
And sometimes, you need to compose several changes.
To me, this makes the sweet spot for the pattern clear. Use an (Immutable) Fluent Builder when you have a basic object that's useful in itself, but where you want to give client code the option to make changes to the defaults.
Sometimes, the initial object has self-contained default values. Test Data Builders are good examples of that:
public AddressBuilder() { this.street = ""; this.city = ""; this.postCode = new PostCodeBuilder().Build(); }
The AddressBuilder constructor fully initialises the object. You can use its WithNoPostcode, WithStreet, etcetera methods to make changes to it, but you can also use it as is.
In other cases, client code must initialise the object to be built. The HttpRequestMessageBuilder is an example of that:
public HttpRequestMessageBuilder(string url) : this(new Uri(url)) { } public HttpRequestMessageBuilder(Uri url) : this(url, HttpMethod.Get, null) { } private HttpRequestMessageBuilder(Uri url, HttpMethod method, object? jsonBody) { this.url = url; Method = method; this.jsonBody = jsonBody; }
While there's more than one constructor overload, client code must supply a url in one form or other. That's the precondition of this class. Given a valid url, though, an HttpRequestMessageBuilder object can be useful without further modification, but you can also modify it by calling its methods.
You often see the Builder pattern used for configuration APIs. The ASP.NET Core IApplicationBuilder is a prominent example of the Fluent Builder pattern. The NServiceBus endpoint configuration API, on the other hand, is based on the classic Builder pattern. It makes sense to use an endomorphic design for framework configuration. Framework designers want to make it as easy to get started with their framework as possible. For this reason, it's important to provide a useful default configuration, so that you can get started with as little ceremony as possible. On the other hand, a framework must be flexible. You need a way to tweak the configuration to support your particular needs. The Builder pattern supports both scenarios.
Other examples include Test Data Builders, as well as specialised Builders such as UriBuilder and SqlConnectionStringBuilder.
It's also worth noting that F# copy-and-update expressions are endomorphisms. That's the reason that when you have immutable records, you need no Test Data Builders.
Summary #
The Builder pattern comes in (at least) three variations: the Gang-of-Four Builder pattern, Fluent Builder, and Immutable Fluent Builder. All are isomorphic to each other, and are equivalent to the endomorphism monoid.
Viewing Builders as endomorphisms may mostly be an academic exercise, but I think it highlights the sweet spot for the pattern. It's particularly useful when you wish to expose an API that offers simple defaults, while at the same time enabling client code to make changes to those defaults. When those changes involve several steps (as e.g. AddJsonBody) you can view each modifier method as a Facade.
Next: Visitor as a sum type.
