Let's talk about phantom types in Swift

Preface

Ambiguous data is arguably one of the most common sources of bugs and issues in general applications. While Swift helps us avoid many sources of ambiguity through its strong type system and sophisticated compiler - as long as we can't guarantee at compile time that a certain data will always conform to our requirements, there is always a risk that we will end up in an ambiguous or unpredictable state.

This week, let’s look at a technique that lets us leverage Swift’s type system to perform more kinds of data validation at compile time — eliminating more potential sources of ambiguity and helping us maintain type safety throughout our codebase — by using phantom types.

Well defined, but still vague

As an example, let's say we're developing a text editor, and while it initially only supports plain text files - over time we also add support for editing HTML documents, as well as PDF previews.

In order to be able to reuse as much of our original document handling code as possible, we continue to use the same Document model as we started with - only now it has gained a Format property that tells us what kind of document we are dealing with:

 struct Document {
 enum Format {
 case text
 case html
 Case pdf
 }
 var format : Format
 var data : Data
 var modificationDate : Date
 var author : Author
 }

While it's certainly good to avoid code duplication, and enums are a good way to model the general case when we're dealing with different formats or variations of a model, the above setup actually ends up creating quite a bit of ambiguity.

For example, we might have some API that only makes sense when called with a document of a given format - like this function that opens a text editor, which assumes that any Document passed into it is a text document:

 func openTextEditor ( for document : Document ) {
 let text = String ( decoding : document .data , as : UTF8 .self )
 let editor = TextEditor ( text : text )
 ...
 }

While it’s not the end of the world if we accidentally pass an HTML document to the above function (HTML is just text after all), attempting to open a PDF in this manner will most likely result in something completely incomprehensible being rendered, our text editing functions won’t work, and our application may even end up crashing.

We keep running into the same problem when writing code for any other specific format, for example if we want to improve the user experience of editing HTML documents by implementing a parser and a specialized editor:

 func openHTMLEditor ( for document : Document ) {
 // Just like the function we used above for text editing,
 // This function assumes that it is always passed an HTML document.
 let parser = HTMLParser ()
 let html = parser.parse ( document .data )
 let editor = HTMLEditor ( html : html )
 ...
 }

An initial thought on how to solve the above problem might be to write a wrapper function that switches to the format of the passed document and then opens the correct editor for each case. However, while this works well for text and HTML documents, since PDF documents are not editable in our application - we will be forced to throw an error, trigger an assertion, or fail in some other way when encountering a PDF:

 func openEditor ( for document : Document ) {
 switch document .format {
 case .text :
 openTextEditor ( for : document )
 case.html :
 openHTMLEditor ( for : document )
 case .pdf :
 assertionFailure ( "Cannot edit PDF documents" )
 }
 }

The above situation isn't very nice, because it requires us as developers to always keep track of what type of file we're dealing with in any given code path, and any mistakes we might make can only be discovered at runtime - the compiler simply doesn't have enough information to do this kind of checking at compile time.

So, while our "Document" model might seem very elegant and complete at first glance, it turns out that it is not entirely the right solution for the situation at hand.

Looks like we need a deal!

One way to solve the above problem is to make Document a protocol, rather than a concrete type, and make all its properties (except format) requirements:

 protocol Document {
 var data : Data { get }
 var modificationDate : Date { get }
 var author : Author { get }
 }

With the above changes, we can now implement specialized types for each of our three document formats and have those types conform to our new document protocol - like this:

 struct TextDocument : Document {
 var data : Data
 var modificationDate : Date
 var author : Author
 }

The benefit of the above approach is that it allows us to implement both generic functionality that can operate on any Document, and specific APIs that only accept a certain type:

 // This function can save any file,
 // So it accepts anything that conforms to our new document protocol.
 func save ( _ document : Document ) {
 ...
 }
 // We can only pass text files to our function now,
 // Open a text editor.
 func openTextEditor ( for document : TextDocument ) {
 ...
 }

What we’ve done above is essentially moving checks that used to happen at runtime to be verified at compile time - since the compiler is now able to check that we’re always passing correctly formatted files to each of our APIs, this is a big improvement.

However, by making the above changes, we also lose the advantage of our original implementation - code reuse. Since we are now using a single protocol to represent all document formats, we will need to write completely duplicate model implementations for each of our three document types, as well as provide support for any additional formats we may add in the future.

Introducing Phantom Types

Wouldn’t it be nice if we could find a way to reuse the same Document model for all formats while still validating our format-specific code at compile time? It turns out that our previous line of code can actually give us a hint on how to achieve this:

 let text = String ( decoding : document .data , as : UTF8 .self )

When converting Data to a String, as we did above, we pass the encoding we want the string to be decoded into - in this case, UTF8 - by passing a reference to the type itself. This is really interesting. If we dig a little deeper, we'll see that the Swift standard library defines the UTF8 type we mentioned above as a caseless enumeration in another namespace-like enumeration called Unicode.

 enum Unicode {
 enum UTF8 {}
 ...
 }
 typealias UTF8 = Unicode .UTF8 

Note that if you look at the actual implementation of the UTF8 type, it does include a private case that exists only for backwards compatibility with Swift 3.

What we're looking at here is a technique known as phantom types - when types are used as tags, rather than being instantiated to represent values ​​or objects. In fact, since none of the above enums have any public cases, they can't even be instantiated!

Let's see if we can use the same technique to solve our Document dilemma. We'll start by reducing Document to a struct, only this time we'll remove its format property (and the associated enumeration) and instead make it a generic that covers any Format type - like this:

 struct Document < Format > {
 var data : Data
 var modificationDate : Date
 var author : Author
 }

Inspired by the standard library's Unicode enumeration and its various encodings, we'll define a similar enumeration - DocumentFormat - as a namespace for three caseless enumerations, one for each format:

 enum DocumentFormat {
 enum Text {}
 enum HTML {}
 enum PDF {}
 }

Note that there is no protocol involved here - any type can be used as a format, as with String and its various encodings, we will just use the documented Format type as a compile-time marker. This will allow us to write our format-specific API like this:

 func openTextEditor ( for document : Document < DocumentFormat .Text >) {
 ...
 }
 func openHTMLEditor ( for document : Document < DocumentFormat .HTML >) {
 ...
 }
 func openPreview ( for document : Document < DocumentFormat .PDF >) {
 ...
 }

Of course, we can still write generic code that doesn't require any specific format. For example, here we can turn the previous saveAPI into a completely generic function:

 func save < F >( _ document : Document < F >) {
 ...
 }

However, always typing Document to refer to a text document is rather tedious, so let's also define shorthands for each format using type aliases. This will give us nice, semantic names without any repetitive code:

 typealias TextDocument = Document < DocumentFormat .Text >
 typealias HTMLDocument = Document < DocumentFormat .HTML >
 typealias PDFDocument = Document < DocumentFormat .PDF >

Phantom types also really shine when it comes to format-specific extensions, which can now be done directly using Swift’s powerful generics system and generic type constraints. For example, we can extend all text documents with a method that generates an NSAttributedString:

 extension Document where Format == DocumentFormat .Text {
 func makeAttributedString ( withFont font : UIFont ) -> NSAttributedString {
 let string = String ( decoding : data , as : UTF8 .self )
 return NSAttributedString ( string : string , attributes : [
 .font : font
 ])
 }
 }

Since our phantom types are just normal types at the end of the day - we can also make them conform to protocols, and use those protocols as generic constraints. For example, we could make some of our DocumentFormat types conform to the Printable protocol, and then we could use those protocols as constraints in our printing code. There are tons of possibilities here.

A standard model

At first, phantom types may seem a bit "out of place" in Swift. However, while Swift does not provide first-class support for phantom types like more purely functional languages ​​​​(such as Haskell), this pattern can be found in many different places in the standard library and Apple's platform SDKs.

For example, Foundation's Measurement API uses phantom types to ensure type safety when passing various measurements—such as degrees, lengths, and weights:

 let meters = Measurement < UnitLength >( value : 5 , unit : .meters )
 let degrees = Measurement < UnitAngle >( value : 90 , unit : .degrees )

By using phantom types, the two measurements above cannot be mixed, because which unit each value is in is encoded into the value's type. This prevents us from accidentally passing a length to a function that accepts an angle, or vice versa - just like we prevented document formats from being mixed up earlier.

in conclusion

Using phantom types is a very powerful technique that allows us to leverage the type system to validate different variations of a particular value. While using phantom types generally makes the API more verbose, and does come with the complexity of generics - it allows us to rely less on runtime checks when dealing with different formats and variations, and let the compiler perform those checks.

Just like with generics in general, I think it's important to first carefully evaluate the situation at hand before deploying phantom types. Just like our initial Document model wasn't the right choice for the task at hand, despite its good structure, phantom types can make a simple setup more complicated if deployed in the wrong situation. As always, it comes down to choosing the right tool for the job.