Forem: Ivan Goremykin

Create, Push, and Present Any View Controller in 1 LOC using Metaprogramming

Ivan Goremykin — Sun, 18 Jun 2023 17:39:11 +0000

TL;DR

We make view controller instantiation more type-safe by eliminating string IDs and use metaprogramming to generate functions that let you create, push, and present any view controller in 1 LOC, so you can save ~15 LOC whenever you want to perform push or present. It works both with storyboard-based view controllers and code-only ones. The generated code is autocomplete-friendly. Here is the full source code example.

Foreword

Although SwiftUI is gaining popularity, the traditional UIKit workflow will remain with us for some time. I'd like to share our approach to managing boilerplate code for UIViewController instantiation and navigation.

Motivation

Storyboards are great when you need to design the appearance of your screen. They are not so great when it comes to writing code required for view controller instantiation or setting up transitions via segue mechanism, especially when you need to

change the existing screen sequence,
implement dynamic screen sequence,
instantiate an array of view controllers.

Here is the vanilla approach to dealing with view controller instantiation, setting up its parameters, and pushing onto the navigation stack:

func preCreateMyViewController()
{
    // Create using a string identifier "MyStoryboard"
    let storyboard = UIStoryboard(name: "MyStoryboard", bundle: nil)

    // Create using a string identifier "MyViewController"
    self.myViewController = storyboard.instantiateViewController(withIdentifier: "MyViewController") as! MyViewController

    // Set parameters known at instantiation time
    self.myViewController.param0 = "I may be paranoid, but not an android."
    self.myViewController.param1 = 42
}

func pushMyViewController()
{
    // Push pre-created view controller onto navigation stack
    navigationController?.pushViewController(self.myViewController, animated: true)
}

override func prepare(for segue: UIStoryboardSegue, sender: Any?)
{
    if let myViewController = segue.destination as? MyViewController
    {
        // Set parameters known at prepare-for-segue time
        myViewController.param2 = .white
    }
}

There are several problems with this approach.

Strings as identifiers

Since both storyboard and view controller are accessed by string IDs ("MyStoryboard" and "MyViewController"), you can simply misspell them and get no compile-time error at all. For example, you could change the storyboard’s file name and forget to change corresponding string IDs in every call of UIStoryboard(name: "MyStoryboard", bundle: nil), and no compile-time error will occur.

Non-atomic instantiation

By non-atomic, I mean that a view controller is not instantiated by a single function call. In order to have a fully functional view controller you’ll have to do these steps:

Instantiate view controller from storyboard,
Setup parameters that are known at instantiation time,
Setup parameters that are known at prepare-for-segue time.

Hence the full setup process is spread across several files, that leads us to a plethora of problems:

you might forget to do any of these steps and still get no compilation error,
you might copy and paste only 2 of the 3 required steps and still get no compilation error,
making any changes (e.g., adding to the view controller a new parameter known at prepare-for-segue time) has to be done in every prepare(for:sender:) implementation, and if you forget — you know what? You don’t get a compilation error! All these situations will silently leave you with a half-initialized view controller, which is a splendid thing to discover at runtime.

Lots of boilerplate and code duplication

It costs us ~15 LOC for view controller instantiation, preparing for a segue, and pushing a view controller onto the navigation stack. It’s just annoying to repeat those 15 lines in any other place that leads to your view controller. It should be only 1 LOC.

Solution

Over the years we have shifted to the “design in a storyboard, compose in code” approach. We do not use segues for transitioning between screens, hence we do not pass parameters between screens in prepare(for:sender:). Instead, we do our design in a storyboard and instantiate, compose, and route the screens in code.

Another important aspect of our programming approach is to move as much of runtime errors to compile-time as possible, so we could get closer to the holy grail of the “if no errors at build time, then no errors at runtime” paradigm.

There are many possible types of errors that might occur at runtime. There are not so many mechanics to detect and prevent those runtime errors at the build time. There is one tool at our disposal that flawlessly works at the build time — the type system. Hence we try to express our runtime problems as compile-time type problems in order to prevent runtime errors by getting compile-time errors. Let the compiler help you.

We will modify our vanilla example in 5 easy steps:

Eliminate String Identifiers
Make Instantiation Atomic
Create 1 LOC Navigation
Eliminate Boilerplate with Metaprogramming
Add Resource Consistency Tests using Metaprogramming

Eliminate String Identifiers

Let’s get rid of those string identifiers. Instead of

let storyboard = UIStoryboard(name: "MyStoryboard", bundle: nil)
let myViewController = storyboard.instantiateViewController(withIdentifier: "MyViewController") as! MyViewController

… we will write

let myViewController = UIViewController.instantiate(.myStoryboard, MyViewController.self)

We assume that view controller’s Storyboard ID is equal to its type name.
UIViewController.instantiate is a utility function. It creates a view controller and casts it to the specified type, hence the client doesn’t have to write cast herself.

extension UIViewController
{
    static func instantiate<ViewController: UIViewController>(_ storyboardName: UIStoryboard.Name,
                                                              _ viewControllerType: ViewController.Type) -> ViewController
    {
        let storyboard = UIStoryboard(name: storyboardName.rawValue, bundle: nil)
        return storyboard.instantiateViewController(withIdentifier: String(describing: ViewController.self)) as! ViewController
    }
}

UIStoryboard.Name is a project-specific enum:

extension UIStoryboard
{
    enum Name: String
    {
        case main
        case myStoryboard
        case yourStoryboard
    }
}

If you misspell the storyboard name when calling UIViewController.instantiate, then it just won’t compile. If you type the wrong view controller type name, then it just won’t compile. Type system to the rescue!

This approach is not persistent to changes of a storyboard file name or changes of a view controller type name. In order to guarantee correct naming at runtime, we generate resource consistency tests. We will cover this later in the corresponding section.

Make Instantiation Atomic

Since we want our view controllers to be instantiated by a single function call we completely drop segues, and instead of this:

let myViewController = UIViewController.instantiate(.myStoryboard, MyViewController.self)

// Set parameters known at instantiation time
self.myViewController.param0 = "I may be paranoid, but not an android."
self.myViewController.param1 = 42

override func prepare(for segue: UIStoryboardSegue, sender: Any?)
{
    if let myViewController = segue.destination as? MyViewController
    {
        // Set parameters known at prepare-for-segue time
        myViewController.param2 = .white
    }
}

… we write

let myViewController = createMyViewController("I may be paranoid, but not an android.", 42, .white)

For each view controller, there is a createMyViewController function that takes all parameters required for the view controller to be 100% initialized and operational.

We oblige all our view controllers to implement an initialize function that takes all parameters required for this view controller:

class MyViewController: UIViewController
{
    // MARK:- Parameters
    var param0: String!
    var param1: Int!
    var param2: UIColor!

    // MARK:- Initialization
    func initialize(param0: String, param1: Int, param2: UIColor)
    {
        self.param0 = param0
        self.param1 = param1
        self.param2 = param2
    }
}

Hence the createMyViewController function will look like this:

func createMyViewController(_ param0: String, _ param1: Int, _ param2: UIColor) -> MyViewController
{
    let myViewController = UIViewController.instantiate(.myStoryboard, MyViewController.self)

    myViewController.initialize(param0: param0, param1: param1, param2: param2)

    return myViewController
}

The initialize should only be called once and only by a create function.

The initialize is written by hand, but createMyViewController is generated by a metaprogramming template. We will discuss code generation later.

Now we have an atomic instantiation of our view controller provided by createMyViewController functions. These functions are safer for copy-pasting since you can’t copy half of a function call and deal with a half-initialized view controller as a result.

If you forget to pass some parameters to createMyViewController function, then the compiler will be happy to let you know. Once again, type system to the rescue!

Create 1 LOC Navigation

Now that we have createMyViewController, we want to push or present our view controller. In many cases we create a view controller only to pass it to the navigation controller:

let myViewController = createMyViewController("I may be paranoid, but not an android.", 42, .white)
navigationController.pushViewController(myViewController, animated: animated)

It would be much nicer if we could just write:

navigationController.pushMyViewController("I may be paranoid, but not an android.", 42, .white, animated)

For each view controller, we have pushMyViewController and presentMyViewController, which are generated by a metaprogramming template that will be discussed later in the corresponding section.

Don’t Pollute the Global Namespace

If you work on a moderate-size project, then you are probably going to have 50+ screens. That means that you will have 50+ create, 50+ push, and 50+ present functions generated for you. Since we don’t want to pollute the global namespace with these functions, we need a place to store all these functions. Where do we put them?

A hint might be found in the essay Learnable Programming by Bret Victor, where he writes:

Strangely, I don’t actually know of any APIs that are intentionally designed with autocomplete in mind.

We are going to fix that. This is how our create functions will look like:

UIViewController.create.myViewController(param0, param1, param2)
UIViewController.create.yourViewController(param0, param1)

The implementation is trivial:

extension UIViewController
{
    static let create = UIViewControllerCreate()

    class UIViewControllerCreate
    {
        func myViewController(param0, param1, param2) -> MyViewController { … }
        func yourViewController(param0, param1) -> YourViewController { … }
    }
}

Same for navigation, we will write our push and present functions just like this:

navigationController.push.myViewController(param0, param1, param2, animated)
yourViewController.present.myViewController(param0, param1, param2, animated)

This implementation is a bit different since we want our functions to be called on an instance of UINavigationController (in case of push) and on an instance of UIViewController (in case of present):

extension UINavigationController
{
    var push: UINavigationControllerPush
    {
         return UIViewControllerFactory(self)
    }

    class UINavigationControllerPush
    {
        weak var navigationController: UINavigationController?

        init(_ navigationController: UINavigationController)
        {
            self.navigationController = navigationController
        }

        func myViewController(_ param0: String, _ param1: Int, _ param2: UIColor, _ animated: Bool) { … }
        func yourViewController(_ param0: String, _ param1: Double, _ animated: Bool) { … }
    }
}

We have just added a single extension property to UINavigationController class and 2 extension properties to UIViewController. Each of those extension properties has 50+ functions.

Eliminate Boilerplate with Metaprogramming

Now that we have designed our APIs we can generate the code. For each view controller in our project, we are going to generate 3 functions: create, push, and present. We are going to generate code with Sourcery — a tool developed by Krzysztof Zabłocki.

Despite the recent announcement of Swift Macros, the development workflow built on Sourcery has proven to be efficient, and we've only just begun discussions about transitioning to Swift Macros.

Sourcery operates as follows: you provide a template file, Sourcery parses your source code, and then generates code based on your template and the parsed source code. Sourcery can be used as a standalone executable or embedded right into the Xcode building process as a Run Script phase. It automatically regenerates code on any changes in your template file or in the project source files.

We write our templates in Swift. Sourcery’s API is way richer than Swift’s native reflection. You can iterate over types presented in your project, filter them, and access all their functions, variable names, template arguments and so on. This is how you iterate over all view controllers that have an initialize method:

types.classes
    .filter { $0.inheritedTypes.contains("UIViewController") && $0.hasMethod(named: "initialize") }
    .map { $0.name }
    .sorted(by: <)
    .forEach { print($0) }

The functions to be generated — create, push, and present, — have almost the same signature as initialize, the only difference is the animated parameter in the latter two:

// Handwritten
myViewController.initialize(param0, param1, param2)

// Generated
UIViewController.create.myViewController(param0, param1, param2)
navigationController.push.myViewController(param0, param1, param2, animated)
yourViewController.present.myViewController(param0, param1, param2, animated)

In our Sourcery template, we iterate over all view controllers, look at their initialize methods, and replicate the same signature in create, push, and present and add an animated parameter at the end of push and present. If a view controller doesn’t need parameters to be set and hence doesn’t have an initialize method, then its create function will not have parameters, and push and present will get only the animated parameter.

There is one more thing to be considered regarding the create function. We need to know UIStoryboard.Name for those view controllers that are instantiated from a storyboard. We make all such view controllers conform to StoryboardInstantiatable protocol:

protocol StoryboardInstantiatable: UIViewController
{
    static var storyboardName: UIStoryboard.Name { get }
}

We could use Sourcery annotations to specify the UIStoryboard.Name, but it wouldn’t work with the Xcode refactoring tool when we need to rename those UIStoryboard.Name cases.

This is how MyViewController conforms to StoryboardInstantiatable protocol:

extension MyViewController: StoryboardInstantiatable
{
    static var storyboardName: UIStoryboard.Name { return .myStoryboard }
}

It is extremely valuable when you want to add a new parameter to the initialize function and those changes are instantly reflected in create, push, and present, since Sourcery automatically regenerates them after every change of initialize. No need to manually forward a new parameter to 3 functions!

Add Resource Consistency Tests using Metaprogramming

Now that we have dropped string identifiers, the instantiation of a storyboard-based view controller looks like this:

let myViewController = UIViewController.instantiate(.myStoryboard, MyViewController.self)

If a storyboard file name or a view controller type name is changed, then the compile-time error will not occur. If we can’t catch errors at compile-time, then we catch them at test time. Once again Sourcery comes to the rescue. In order to guarantee the correct naming of all related resources (storyboard file names, view controllers’ storyboard IDs), we generate resource consistency tests.

There are 2 groups of these tests: storyboard tests and view controller tests.

Storyboard tests are intended to check whether every case from UIStoryboard.Name enum successfully loads a storyboard by its rawValue. Here is an example of such a test for one case:

class StoryboardNameTests: XCTestCase
{
    func testStoryboardA()
    {
        XCTAssertNotNil(getPath(for: .storyboardA))
    }

    private func getPath(for storyboardName: UIStoryboard.Name) -> String?
    {
        return Bundle.main.path(forResource: storyboardName.fileName, ofType: "storyboardc")
    }
}

View controller tests are intended to check whether every view controller that conforms to StoryboardInstantiatable protocol can be instantiated from its storyboard (their type names must equal their Storyboard IDs). Here is an example of such a test:

class InstantiateUIViewControllerTests: XCTestCase
{
    func testMyViewController()
    {
        XCTAssertTrue(canBeInstantiated(MyViewController.self))
    }

    private func canBeInstantiated<ViewController: StoryboardInstantiatable>(_ viewControllerType: ViewController.Type) -> Bool
    {
        return UIViewController.instantiate(storyBoardName:   ViewController.storyboardName.fileName,
                                            viewControllerId: String(describing: ViewController.self)) is ViewController
    }
}

It is important to say that there is an elegant solution to the resource consistency problem that we haven’t adapted yet. Instead of testing raw values of UIStoryboard.Name cases, we could just generate the UIStoryboard.Name enum. Please refer to SwiftGen for the details.

Discussion

In order to eliminate error-prone and boilerplate code, we have developed a type-safe solution using metaprogramming. We don’t pollute the global namespace and design our API with autocomplete in mind. In every place where you want to push a view controller, instead of 15 LOC now you can write only 1:

navigationController.pushMyViewController("I may be paranoid, but not an android.", 42, .white, animated)

The less code, the more opportunities for new pattern discovery and further improvements.

For the sake of simplicity, we have been working with vanilla UINavigationController. The presented metaprogramming approach can be adapted to more sophisticated navigation architectures, such as coordinators, and other forms of user interactions.

We prefer functional programming over object-oriented, that’s why UIViewController multilevel inheritance is not supported in our templates.

One of the drawbacks of our approach is that initialize is not a private method. If we want to have our view controller in one file and all generated code in another, then we can’t make the initialize function private since createMyViewController must access initialize. At the same time, Sourcery supports inlining generated code right into the source files instead of separate files, but we just don’t even want to look at this boilerplate while programming our view controllers. Therefore, there is a tacit convention: “don’t manually call an initialize method”; luckily, our programmers are intelligent enough to follow it.

The full example Xcode project with a typical project structure including all discussed Sourcery templates can be found here.

Acknowledgments

I would like to thank Dmitry Cherednikov and Vyacheslav Shakaev for their constructive criticism and valuable comments on the draft version of this text. I would also like to thank Michael Goremykin for his contribution to the templates’ source code.

Adding Codable Conformance to Union with Metaprogramming

Ivan Goremykin — Thu, 02 Feb 2023 11:39:24 +0000

TL;DR

We add Codable conformance to a set of enums — Union2, Union3, etc. by representing each UnionX in KeyedEncodingContainer as a “value” and a “type”. The choice of coding scheme is team-specific and configurable via Sourcery template arguments. The code is generated using a Sourcery template written in Swift. All the source code, including a Swift playground, Sourcery templates, configuration files, and scripts, is available on GitHub. You can also run the code on Repl.it.

Preface

In the article Adding Union to Swift with Metaprogramming we have generated a set of enums — Union2, Union3, etc. that act like a disjoint set. For every UnionX, we also provide a selection of helper methods: conformance to the standard Swift protocols, higher-order functions, etc. Adding Encodable and Decodable conformance to UnionX is a significant topic on its own, which is why it’s covered in a separate article.

Motivation

The essence of many mobile applications is manipulating lists of elements. Sometimes, we need to encode and decode lists where elements are not of the same type.

Encoding a type that conforms to Encodable is trivial. However, decoding it is not — since we don’t know which type to decode beforehand. In the following example, we have an array with 2 objects: the first one is of type Album, and the second one is of type Artist:

[
    {
        "id": "808a0004-df02-4cf6-b5fb-caec1c155420",
        "name": "Tilt",
        "release-date": "1995-05-08",
        "artistId": "dff5a5ad-6185-47ab-ae42-c72045bfa38a"
    },
    {
        "id": "2c51f969-f145-4a65-b9bc-3ed4c0840b0d",
        "name": "Mark Hollis",
        "biography": "Mark David Hollis was an English musician, the main vocalist and songwriter of the band Talk Talk."
    }
]

If we want to decode this array, how do we know which object should be decoded as Album and which — as Artist?

What other developers do

Brute force

To decode an array of non-homogeneous values, some implementations use a brute-force approach:

they try to decode the object as TypeA
if they fail, they try to decode it as TypeB
and so on until they either succeed or run out of types to decode

Not only this approach has obvious performance implications, but there is no guarantee that a set of type’s CodingKeys can act as a composite key, i.e. uniquely identify the type. For instance, if TypeA has a subset of TypeB’s keys, we can mistakenly decode JSON object that represents TypeB as TypeA:

struct Type A {
   let id: UUID
   let name: String
}

struct Type B {
   let id: UUID
   let name: String
   let expiredOn: Date
}

This JSON object can be decoded both as TypeA and as TypeB.

{
   “id”: “7a910713-dcbd-4f6e-a739-2adb3d445cdb”,
   “name”: “Trial Subscription”,
   “expiredOn”: “2012-12-21”,
}

Protocol Buffers

ProtocolBuffers’ OneOf message addresses the case of having a message with many fields where at most one field will be set at the same time.

message SampleMessage {
  oneof sample_oneof {
    string name = 4;
    SubMessage sub_message = 9;
  }
}

It supports fields of any type, except map fields and repeated fields. This concept lacks the disadvantages of brute force and will underlie our approach.

What we’re going to do

We’re going to represent UnionX using 2 coding keys:

“value” that contains the encoded object carried by UnionX
“type” that uniquely identifies the wrapped type

We will implement a Sourcery template for adding Codable conformance to UnionX, where X is the size of the enum. X is going to be an argument of the Sourcery template.

We will go through various aspects of it using Union2 as an example.

Coding Scheme

A modified version of the previous example with an array of non-homogeneous values will look like this:

[
    {
        "type": "album",
        "value": {
            "id": "808a0004-df02-4cf6-b5fb-caec1c155420",
            "name": "Tilt",
            "release-date": "1995-05-08",
            "artistId": "dff5a5ad-6185-47ab-ae42-c72045bfa38a"
        },
    {
        "type": "artist",
        "value": {
            "id": "2c51f969-f145-4a65-b9bc-3ed4c0840b0d",
            "name": "Mark Hollis",
            "biography": "Mark David Hollis was an English musician, the main vocalist and songwriter of the band Talk Talk."
        }
    }
]

Each UnionX object will be represented in JSON as follows:

{
    "<Type ID Key>": "<Type ID Value>",
    "<Value Key>": Value
}

The choice of Type ID Key, Type ID Value, and Value Key depends on each particular development team. The following factors should be taken into consideration:
1. The choice of names of Type ID Key and Value Key attributes

in this example it’s “type” and “value”
it could be “type_id” and “wrapped” or something else

2. The choice of Type ID Value

it can be human-readable — String (“album”, “artist”, etc.)
or not human-readable — UUID, Int, etc.
each has its pros and cons

3. The UnionX coding scheme should be the same across the whole project

if your team has a couple of endpoints that return a non-homogeneous array of JSON objects, they all should follow the same scheme
the JSON scheme is highly likely to be shared by multiple platforms (iOS, Android, Web), so there should be an agreement between all the stakeholders

Because the choice of Type ID Key, Type ID Value, and Value Key is team-specific, our Sourcery template is going to accept following arguments:

Type ID Key — e.g. “type”, “id”, “type_id”
Type ID Value — e.g. “String”, “UUID”, “Int”
Value Key — e.g. “value”, “wrapped”

Codable

Now that we have agreed on the coding scheme, let’s take a look at Swift code for encoding and decoding unions.

First, let’s define the type of Type ID (e.g. “String”, “UUID”, “Int”) — UnionTypeID:

typealias UnionTypeID = String // 'String' comes from the Sourcery template arguments

This is how we generate this line of code in our meta-code.

Next, we want to get Type ID Value (e.g. “album”, “artist”) from all types wrapped by UnionX. E.g. if there is Union2<Album, Artist>, we want both Album and Artist to provide Type ID Value. This requirement will come in the form of protocol:

protocol UnionIdentifiable {
    static var unionTypeID: UnionTypeID { get }
}

Both Album and Artist are going to conform to UnionIdentifiable:

extension Artist: UnionIdentifiable {
    static let unionTypeID: UnionTypeID = "artist"
}

extension Album: UnionIdentifiable {
    static let unionTypeID: UnionTypeID = "album"
}

We’re not using Swift’s Identifiable because it identifies instances, not types, and also because it has associatedtype requirements, i.e. it will not work if Artist returns ID of type String and Album returns ID of type UUID.

We will also need a CodingKey for adding Encodable and Decodable conformance to UnionX. For every UnionX object, we will need to encode 2 attributes — Type ID Key and Value Key; hence we define 2 coding keys:

struct UnionCodingKey: CodingKey {
    var stringValue: String
    init?(stringValue: String) { self.stringValue = stringValue }

    var intValue: Int? { return nil }
    init?(intValue: Int) { return nil }

    static let unionTypeID = UnionCodingKey(stringValue: "type")! // "type" comes from the Sourcery template arguments
    static let wrappedValue = UnionCodingKey(stringValue: "value")! // "value" comes from the Sourcery template arguments
}

The respective metaprogramming code can be found here. Note that UnionTypeID, UnionIdentifiable, and UnionCodingKey will be shared across Union2, Union3, etc.

Encoding

Now that we have a coding key, let’s encode our Union:

extension Union2: Encodable where Item0: Encodable & UnionIdentifiable, Item1: Encodable & UnionIdentifiable {
    func encode(to encoder: Encoder) throws {
        var unionContainer = encoder.container(keyedBy: UnionCodingKey.self)

        try unionContainer.encode(unionTypeID, forKey: .unionTypeID)
        try unionContainer.encode(innerEncodable, forKey: .wrappedValue)
    }

    private var unionTypeID: UnionTypeID {
        switch self {
        case .item0:
            return Item0.unionTypeID

        case .item1:
            return Item1.unionTypeID
        }
    }

    private var innerEncodable: Encodable {
        switch self {
        case .item0(let item0):
            return item0

        case .item1(let item1):
            return item1
        }
    }
}

The corresponding metaprogramming code can be found here.

A few notes about the generated code above:

if we want to make our UnionX conform to Encodable, we will need all of its wrapped types to conform not only to Encodable, but also to our UnionIdentifiable
to follow the single-responsibility principle and make our encode(to:) easy to read, we generated 2 computed properties — unionTypeID and innerEncodable
both of them should be not accessed outside of the extension and hence are marked private

Decoding

Decoding UnionX will look like this:

extension Union2: Decodable where Item0: Decodable & UnionIdentifiable, Item1: Decodable & UnionIdentifiable {
    func init(from decoder: Decoder) throws {
        let unionContainer = try decoder.container(keyedBy: UnionCodingKey.self)

        let unionTypeID = try unionContainer.decode(UnionTypeID.self, forKey: .unionTypeID)

        switch unionTypeID {
        case Item0.unionTypeID:
            self = .item0(try unionContainer.decode(Item0.self, forKey: .wrappedValue))

        case Item1.unionTypeID:
            self = .item1(try unionContainer.decode(Item1.self, forKey: .wrappedValue))

        default:
            throw UnionDecodingError.unknownUnionTypeID(unionTypeID)
        }
    }
}

The respective metaprogramming code can be found here.

A few notes about the generated code above:

if we want to make our UnionX conform to Decodable, we will need all of its wrapped types to conform not only to Decodable, but also to our UnionIdentifiable
in case we fail to match unionTypeID with any known type ID, we will throw UnionDecodingError:

enum UnionDecodingError: Error {
    case unknownUnionTypeID(UnionTypeID)
}

UnionDecodingError is shared across Union2, Union3, etc.

End-to-end example

Now that we have all the code, we can take a look at how it’s going to be used:

// Encoding
let sample: [U2<Album, Artist>] = [
    .init(Album.sample0),
    .init(Album.sample1),
    .init(Album.sample2),
    .init(Artist.sample0),
    .init(Artist.sample1)
]

let encoder = JSONEncoder()

let encodedSample = try encoder.encode(sample)

// Decoding
let decoder = JSONDecoder()

let decodedSample = try decoder.decode(
    [U2<Album, Artist>].self,
    from: encodedSample
)

print(sample == decodedSample) // true

Discussion

We have written meta code for adding Codable conformance to a set of UnionX types.

You can check both meta-code and generated code

on GitHub, where it is available as a Swift playground and a set of scripts and configuration files for running Sourcery
or on Repl.it, where you can run the whole thing in a browser

An interesting implication of this approach is that it is possible to encode UnionX and then decode it as UnionX+1:

let arrayOfU2: [U2<Album, Playlist>] = try decoder.decode(
    [U2<Album, Playlist>].self,
    from: encodedSample
)

let arrayOfU3 = try decoder.decode(
    [U3<Album, Playlist, Artist>].self,
    from: encodedSample
)

arrayOfU2.compactMap0() == arrayOfU3.compactMap0() // Compare two arrays [Album]
arrayOfU2.compactMap1() == arrayOfU3.compactMap1() // Compare two arrays [Artist]

… which makes our solution open for extension.

Acknowledgments

I would like to thank Vyacheslav Shakaev for his constructive criticism and valuable comments on the draft version of this text.

Adding Union to Swift with Metaprogramming

Ivan Goremykin — Thu, 02 Feb 2023 11:39:01 +0000

TL;DR

We generate a set of enums — Union2, Union3, etc. — that act like a disjoint set. For every UnionX, we also provide a selection of helper methods: conformance to the standard Swift protocols, higher-order functions, etc. The code is generated using a Sourcery template written in Swift. All the source code, including a Swift playground, Sourcery templates, configuration files, and scripts, is available on GitHub. You can also run the code on Repl.it.

Motivation

The essence of many mobile applications is manipulating lists of elements. Sometimes, we need to process lists where elements are not of the same type. Unfortunately, Swift doesn’t provide an out-of-the-box type-safe solution that doesn’t require developers to write boilerplate code.

For example, if we are developing a music streaming app, we might want to display a list of all items that the User has previously viewed: [AlbumA, AlbumB, ArtistA, PlaylistA, ArtistB]. In that case, we will need to store objects of Album, Artist, and Playlist types in the same array.

An obvious type-safe solution would be introducing an enum with associated values:

enum RecentlyViewedItem {
   case album(Album)
   case artist(Artist)
   case playlist(Playlist)
}

Next time we want to display a list of all downloaded items — which are only albums and playlists. In that case, we will have to introduce another enum, consisting of only 2 elements:

enum DownloadedItem {
   case album(Album)
   case playlist(Playlist)
}

It seems that introducing a new type that only carries one of the other possible types is a bit excessive. It would be great to avoid introducing new types and to have a generic approach that preserves type safety, i.e., we don’t want something like [AnyObject] to carry objects of different types.

What Swift already has

When we need to glue together a bunch of unrelated types without introducing a new type, we use a tuple. It works like the AND operator for multiple types: (TypeA, TypeB) represents TypeA AND TypeB. A tuple is one of the common algebraic data type classes.

However, if we want to unite multiple types together but have only one of them being instantiated — TypeA XOR TypeB — Swift doesn’t provide us with any means for doing that. This scenario represents another typical algebraic data types class — a disjoint union.

One can say that a tuple works like an anonymous data structure. Our goal is to do with enums what tuple does to structs.

What other languages have

There are a couple of languages that feature first-class support of disjoint unions. In these languages, an expression representing TypeA XOR TypeB can be called a union, a tagged union, etc.

For instance, TypeScript’s type system allows building new types out of existing ones using a large variety of operators, including unions:

function printId(id: number | string) {
  console.log("Your ID is: " + id);
}

printId(101);
printId("202");

Scala provides first-class support of union types:

case class Username(name: String)
case class Password(hash: Hash)

def help(id: Username | Password) =
  val user = id match
    case Username(name) => lookupName(name)
    case Password(hash) => lookupPassword(hash)
  …

Bosque’s type system also supports unions. Like in previous examples, the TypeA | TypeB notation specifies a type that may be either TypeA or TypeB. Side note: Bosque is quite an interesting language to study on its own, be sure to check it out.

Previous work

The Swift community came up with a couple of implementations of Either — a generic enum that carries one of 2 types associated with it (here, here, and here). There has been a discussion about adding Either to the Standard Library. Still, it seems we’re not going to have it in the foreseeable future because adding disjunctions (logical XORs) in type constraints is a commonly rejected evolution proposal. Funny enough, Apple has an internal implementation of Either in their standard library, but they are not sharing it with us ¯\_(ツ)_/¯

Anyway, Either is a handy data structure, and many teams have adopted it in their codebase. However, it limits the number of types to 2 and often lacks some useful helper functions.

What we’re going to do

We’re going to introduce a set of enums Union2, Union3, etc. and add a bunch of helper methods that cover Swift standard protocols, data transformations, and some other popular use cases. To avoid writing these UnionX types by hand, we will generate them using metaprogramming.

Metaprogramming in Swift

The most popular tool for generating code in Swift is Sourcery — a tool developed by Krzysztof Zabłocki. It works like this: you provide a template file, Sourcery parses your source code and generates code based on your template and the parsed source code. Sourcery can be used as a standalone executable or embedded right into the Xcode building process as a Run Script phase. It automatically regenerates code on any changes in your template file or in the project source files.

Generating Unions

We’re going to implement a Sourcery template for generating enum UnionX, where X is the size of the enum. X is going to be an argument of the Sourcery template. We will go through various aspects of UnionX using Union2 as an example.

Type Definition

We’re going to start with defining a type. This is how our Unions are going to look like:

enum Union2<Item0, Item1> {
    case item0(Item0)
    case item1(Item1)
}

The meta code for generating a definition of UnionX can be found here.

Initializers

We want to be able to initialize our Unions simply by providing a value for one of the wrapped values:

let unionFromArtist: Union2<Artist, Album> = .init(Artist.sample())
let unionFromAlbum: Union2<Artist, Album> = .init(Album.sample())

The initializers themselves are going to look like this:

extension Union2 {
    init(_ item0: Item0) {
        self = .item0(item0)
    }

    init(_ item1: Item1) {
        self = .item1(item1)
    }
}

Here is the meta code for generating an initializer.

Getters

Now that we can define and instantiate our union we want to access its wrapped values:

let unionFromArtist: Union2<Artist, Album> = .init(Artist.sample())

let artist = unionFromArtist.item0 // Artist(…)
let album = unionFromArtist.item1 // nil

The getters themselves look unsurprisingly boring:

extension Union2 {
    var item0: Item0? {
        if case let .item0(item0) = self {
            return item0
        }

        return nil
    }

    var item1: Item1? {
        if case let .item1(item1) = self {
            return item1
        }

        return nil
    }
}

It’s great that we didn’t have to write them manually, thanks to the respective meta code. Note that we omit type names in the if-case-let expressions to improve readability.

Setters

If you have a stateful variable, you will need to mutate it. Since we can’t overload the assignment operator in Swift, we will introduce a bunch of setter methods:

var selectedItem: Union2<Artist, Album> = …
selectedItem.set(artist)
selectedItem.set(album)

The setters themselves look like this:

extension Union2 {
    mutating func set(_ item0: Item0) {
        self = .init(item0)
    }

    mutating func set(_ item1: Item1) {
        self = .init(item1)
    }
}

Note that in the setters’ code we’re using initializers that we have generated in the previous step. The corresponding meta code is here.

Transforming a Union

The nature of many data operations is a transformation of its wrapped values. Like many of Swift’s native types, our Unions will have a map and a flatMap higher-order functions.

map returns a new UnionX, mapping its wrapped value using the given transformation:

extension Union2 {
    func map0<Transformed0>(_ transform: (Item0) throws -> Transformed0) rethrows -> Union2<Transformed0, Item1> {
        switch self {
        case .item0(let item0):
            return .init(try transform(item0))

        case .item1(let item1):
            return .init(item1)
        }
    }

    func map1<Transformed1>(_ transform: (Item1) throws -> Transformed1) rethrows -> Union2<Item0, Transformed1> {
        switch self {
        case .item0(let item0):
            return .init(item0)

        case .item1(let item1):
            return .init(try transform(item1))
        }
    }
}

flatMap returns a new UnionX, mapping its wrapped value using the given transformation and unwrapping the produced result:

func flatMap0<Transformed0>(_ transform: (Item0) throws -> Union2<Transformed0, Item1>) rethrows -> Union2<Transformed0, Item1> {
    switch self {
    case .item0(let item0):
        return try transform(item0)

    case .item1(let item1):
        return .init(item1)
    }
}

func flatMap1<Transformed1>(_ transform: (Item1) throws -> Union2<Item0, Transformed1>) rethrows -> Union2<Item0, Transformed1> {
    switch self {
    case .item0(let item0):
        return .init(item0)

    case .item1(let item1):
        return try transform(item1)
    }
}

Note that we’re trying to stay close to Apple’s naming and signatures when defining our higher-order functions. The respective meta code can be found here and here.

Transforming a sequence of Unions

In case we have a sequence of Unions, we might want to leave only those of a particular type:

let unions: [Union2<Artist, Album>] = […]

let artists: [Artist] = unions.compactMap0()
let albums: [Album] = unions.compactMap1()

To achieve that, we will define an extension for Sequence where we add a set of functions similar to compactMap(_:) — compactMap0, compactMap1, etc.

Due to the limitations of Swift’s generics, we can’t simply define an extension for Sequence where Element == UnionX because UnionX carries wrapped types. We can overcome this limitation by taking three steps:

1. Introduce a protocol:

protocol Union2Protocol {
    associatedtype Item0
    associatedtype Item1

    var item0: Item0? { get }
    var item1: Item1? { get }
}

2. Make an extension for Sequence:

extension Sequence where Element: Union2Protocol {
    func compactMap0() -> [Element.Item0] {
        return compactMap { $0.item0 }
    }

    func compactMap1() -> [Element.Item1] {
        return compactMap { $0.item1 }
    }
}

3. Auto-conform UnionX to UnionXProtocol:

extension Union2: Union2Protocol {}

Note that we are again using getters that we have previously generated to make the code of compactMapX more compact. You can find the respective meta code here.

Conforming to standard Swift protocols

There is a set of the standard Swift protocols that we use daily, including Basic Behaviors (Equatable, Hashable, etc.), Error, Codable, and others. It would be great if our UnionX conformed to each of these protocols in case all of its wrapped types also conform to it.

Equatable

Swift compiler can automatically generate conformance to Equatable, if all associated types also conform to Equatable. So we will just generate a line like this:

extension Union2: Equatable where Item0: Equatable, Item1: Equatable {}

It would be convenient if we could compare a union directly with a value of one of its wrapped types. That is particularly useful when writing asserts in a Unit-test:

var actuallySelected: Union2<Artist, Album> = …
let expectedToBeSelected: Album = …

XCTAssertEqual(actuallySelected, expectedToBeSelected)

To achieve this, we will need to generate a set of equality functions:

extension Union2: Equatable where Item0: Equatable, Item1: Equatable {
    static func ==(_ union: Self, _ item0: Item0) -> Bool {
        return union.item0 == item0
    }

    static func ==(_ union: Self, _ item1: Item1) -> Bool {
        return union.item1 == item1
    }

    static func ==(_ item0: Item0, _ union: Self) -> Bool {
        return union.item0 == item0
    }

    static func ==(_ item1: Item1, _ union: Self) -> Bool {
        return union.item1 == item1
    }
}

Note that we’re using Self instead of Union2<Item0, Item1>. That will improve readability, especially for Union8<Item0, Item1, Item2, Item3, Item4, Item5, Item6, Item7> and alike. Also, we are again using the code that we had generated in the previous step — getters union.item0 and union.item1. This helps us reduce the number of LOC and improve readability. Here is the meta code for this extension.

Hashable

This one is simple because Swift compiler can automatically generate conformance to Hashable if all of enum’s associated types also conform to Hashable:

extension Union2: Hashable where Item0: Hashable, Item1: Hashable {
}

Here’s how this line has been generated using metaprogramming.

Sendable

For those using concurrency features available in Swift 5.7, it will be convenient if UnionX conforms to Sendable if all of its wrapped types also conform to Sendable. The code looks largely unremarkable:

extension Union2: Sendable where Item0: Sendable, Item1: Sendable {   
}

You can find the relevant meta code here.

String representation

Adding conformance to CustomStringConvertable and DebugCustomStringConvertable is shockingly trivial:

extension Union2: CustomStringConvertible {
    var description: String {
        switch self {
        case .item0(let item0):
            return "Union2.item0(\(item0))"

        case .item1(let item1):
            return "Union2.item1(\(item1))"
        }
    }
}

extension Union2: CustomDebugStringConvertible {
    var debugDescription: String {
        switch self {
        case .item0(let item0):
            return "Union2.item0(\(item0))"

        case .item1(let item1):
            return "Union2.item1(\(item1))"
        }
    }
}

We use the same textual representation in both cases, which can be easily altered in the respective meta code.

Error

We can make the UnionX conform to Error if all wrapped types of UnionX also conform to Error. Error protocol defines a computed property localizedDescription. Since every type associated with Union conforms to Error, each of them provides localizedDescription. To make our code neater, we will first define a computed property that returns the inner error and then use it to implement localizedDescription:

extension Union2: Error where Item0: Error, Item1: Error {
    var innerError: Error {
        switch self {
        case .item0(let item0):
            return item0

        case .item1(let item1):
            return item1
        }
    }

    var localizedDescription: String {
        return innerError.localizedDescription
    }
}

We will also leave innerError accessible to UnionX's clients since this property is useful on its own. The respective meta code can be found here.

CaseIterable

The CaseIterable protocol defines a type that provides a collection of all possible values. In case all of UnionX’s wrapped types conform to CaseIterable we can make UnionX conform to CaseIterable as well. This is useful when writing Unit-tests.

Consider an example where we have a DataProvider that can return either NetworkError or StorageError:

protocol DataProviderProtocol{
    func downloadFile(
        fileDescriptor: FileDescriptor,
        completion: @escaping (Result<FileMetadata, DataProvideError>) -> Void
    )
}

typealias DataProvideError = Union2<NetworkError, StorageError>

enum NetworkError: Error, Equatable, CaseIterable {
   case noInternetConnection
   case authenticationFailed
   case decodingFailed
}

enum StorageError: Error, Equatable, CaseIterable {
   case diskFull
   case fileAlreadyExists
}

… and there is another system that we want to test, that depends on DataProvider:

final class AudioProvider: AudioProviderProtocol {
    init(
        dataProvider: DataProviderProtocol,
        userPlanProvider: UserPlanProviderProtocol
    ) { … }

    func downloadAudioFile(
        audioFileDescriptor: AudioFileDescriptor,
        completion: @escaping (Result<AudioFileMetadata, AudioProviderError>) -> Void
    ) { … }
}

enum AudioProviderError: Error, Equatable {
    case userNotEligibleForAudioDownloads
    case userNotEligibleForAudioDownloadsOfQuality(AudioQuality)
    case dataProvider(DataProvideError)
}

We can write a Unit-test that asserts that if there is an error returned by a sub-system (DataProvider), the system under test (AudioProvider) will return a correct error:

func test_systemReturnsExpectedError_ifErrorInDataProvider() {
    let dataProviderMock = DataProviderMock()
    let userPlanProviderMock = UserPlanProviderMock()

    let sut = AudioProvider(
        dataProvider: dataProviderMock,
        userPlanProvider: userPlanProviderMock
    )

    for dataProvideError in DataProvideError.allCases {
        dataProviderMock.downloadFileMockFunc.returns(.failure(dataProvideError))

        var actualResult: Result<AudioFileMetadata, AudioProviderError>?
        sut.downloadAudioFile(
            audioFileDescriptor: .sample(),
            completion: { actualResult = $0 }
        )

        XCTAssertEqual(
            actualResult,
            .failure(.dataProvider(dataProvideError))
        )
    }
}

Since we can’t have stored generic static properties in generic types, UnionX’s allCases is going to be a computed property:

extension Union2: CaseIterable where Item0: CaseIterable, Item1: CaseIterable {
    static var allCases: [Self] {
        return Item0.allCases.map { .init($0) } + Item1.allCases.map { .init($0) }
    }
}

Note that we’re using initializers that we have previously generated for UnionX. Also, DataProvideError, which is Union2, conforms to Error because both of its wrapped types do it, — thanks to the code that we have generated before. The meta code for providing conformance to CaseIterable can be found here.

Codable

This one is not straightforward. Coding a wrapped type that conforms to Encodable is trivial. However, decoding encoded data into UnionX is not since we don’t know which type to decode in advance. Making UnionX conform to Decodable and Encodable is a massive topic on its own. For that reason, it has been covered in a separate article.

Final touches

Our set of unions is ready to be used, but let’s add some final polishing.

We can make our client code more compact if we use a shortened name for every UnionX: Union2 → U2, Union3 → U3, etc. For every UnionX, we will generate a type alias UX:

typealias U2 = Union2

To simplify navigation in the generated code, we add // MARK: comments for every section that we described above, for every UnionX.

We also provide control over the access level of the generated code. It’s up to your team to decide whether you want your UnionX and its extensions to be public or internal. You can see how the access level parameter is defined and used in the meta code.

The Sourcery template that generates UnionX can be found here. It accepts the following Sourcery arguments:

max Union size to be generated,
access level of generated code.

The Sourcery configuration file is available here.

Discussion

We have written meta code for generating a set of UnionX types.

You can check both meta-code and generated code

on GitHub, where it is available as a Swift playground and a set of scripts and configuration files for running Sourcery
or on Repl.it, where you can run the whole thing in a browser

I chose 9 as the maximum size of a UnionX to be generated. Why 9? Because that was the number of members of the Fellowship of The Ring. So, in the end, we did it for Frodo.

More things to consider

We have generated some code, but we didn’t take any measures to prevent misusing it.

For instance, it is possible to write and compile code where all or some wrapped types are the same: U2<TypeA, TypeA>. It’s a valid type from the compiler’s perspective but not from a logic perspective. Ideally, the compiler should generate a compile-time warning for such cases. Unfortunately, we don’t have static assertions in Swift, though there is a proposal that, as of the moment this article is being written, is “awaiting implementation”.

There is an option to add run-time asserts for every UnionX's initializer, function, and computed property:

init(_ item0: Item0) {
    assert(Item0.self != Item1.self)
    self = .item0(item0)
}

init(_ item1: Item1) {
    assert(Item0.self != Item1.self)
    self = .item1(item1)
}

… which will probably bring more clutter than value. We will leave it as an exercise for the reader.

Another thing that we need to keep in mind is that U2<TypeA, TypeB> and U2<TypeB, TypeA> are different types from the compiler’s perspective but are identical from the logic perspective since they both represent the same intention. Ideally, the client should be able to seamlessly work with any permutation of wrapped types carried by a UnionX. So that it will be possible to compare types U2<TypeA, TypeB> and U2<TypeB, TypeA> directly, store them in the same strictly typed array, etc. To keep our reader occupied, we’ll leave generating permutations as another exercise.

How about writing U2<TypeA, Void>? Sure, why not. As we know, Swift’s Void is just an empty tuple, so it’s another expression valid from a compiler point of view, but not from the underlying logic of a union. U2<TypeA, Void> is just TypeA?, so the compiler should probably generate warnings for such cases.

Type U2<TypeA, TypeA?> can be represented as an optional type TypeA?. The type U2<TypeA?, TypeB?> can be simplified as U2<TypeA, TypeB>?. Another set of compiler warnings for these cases would be nice.

And what about nesting unions, e.g. U2<TypeA, U2<TypeB, TypeC>>? There are plenty of cases where nested unions can be flattened:

U2<TypeA, U2<TypeB, TypeC>> → U3<TypeA, TypeB, TypeC>
U2<TypeA, U2<TypeA, TypeB>> → U2<TypeA, TypeB>
U2<U2<TypeA, TypeB>, U2<TypeB, TypeC>> → U3<TypeA, TypeB, TypeC>
etc.

Taking care of permutations, optionals, and nesting simultaneously is quite challenging, which probably explains why we don’t have first-class disjoints in Swift.

Writing metaprogramming code in Swift

Guidelines

Make generated code readable by reducing LOC
- use Self instead of Union5<T0, T1, T2, T3, T4>
- completely skip type where possible, e.g. in if case let .item0(item0) = self expressions
Reuse generated code inside other parts of your generated code
- e.g. we use generated accessors in Equatable operators and compactMapX
Apply the same rules to generated code that are considered good practice for hand-written code
- stay close to Apple’s naming and signature
- follow Apple’s API Design Guidelines, etc.

Metaprogramming pipeline

we have written our meta-programming code using a set of internal utilities for generating enums, functions, etc.
we used Sourcery only for rendering the final result into a generated .swift-file
the generated code features minimum formatting: we hardcoded the indentation to be 4 spaces and use Egyptian brackets everywhere
the idea is to separate code generation from code formatting
if you want your code to be formatted with a specific set of rules in mind, you can forward the generated code to a formatting utility, e.g. swift-format

Acknowledgments

I would like to thank Vyacheslav Shakaev for his constructive criticism and valuable comments on the draft version of this text and Nadezhda Zhubreva for making an editorial illustration for the article U3<🦊, 🦉, 🦌>.