Swift’s Codable API — which consists of the Encodable protocol for encoding, and Decodable for decoding — offers a powerful, built-in mechanism for converting native Swift types to and from a serialized format, such as JSON. Thanks to its integration with the Swift compiler, we often don’t have to do any additional work to enable one of our types to become Codable, such as this Movie type:

struct Movie: Identifiable, Codable {
    let id: UUID
    var title: String
    var releaseDate: Date
    var genre: Genre
    var directorName: String
}

Just by adding that Codable conformance (which is a type alias for both Encodable and Decodable), our above Movie type can now be serialized and deserialized automatically, as long as the data format (such as JSON) that we’re working with follows the same structure as our Swift type declaration.

However, sometimes we might be working with a type that requires some additional data that’s not present in the JSON (or whichever data format we’re decoding from) in order to be initialized. For example, the following User type includes a favorites property — which is a Favorites value that contains the user’s favorites, such as their favorite director and movie genre:

struct User: Identifiable {
    let id: UUID
    var name: String
    var membershipPoints: Int
    var favorites: Favorites
}

struct Favorites: Codable {
    var genre: Genre
    var directorName: String
    var movieIDs: [Movie.ID]
}

However, the JSON response that our app receives from the server when loading the data for a user doesn’t include the Favorites data, which instead need to be loaded from a separate server endpoint:

// User server response:
{
    "id": "7CBE0CC1-7779-42E9-AAF1-C4B145F3CAE9",
    "name": "John Appleseed",
    "membershipPoints": 192
}

// Favorites server response:
{
    "genre": "action",
    "directorName": "Christopher Nolan",
    "movieIDs": [
        "F028CAB5-74D7-4B86-8450-D0046C32DFA0",
        "D2657C95-1A35-446C-97D4-FAAA4783F2AA",
        "5159AF60-DF61-4A0C-A6BA-AE0E027E2BC2"
    ]
}

Now the question is, how do we make User conform to Codable (or more specifically, Decodable) without being able to decode the required Favorites data from the server’s JSON response?

One option would be to simply make the favorites property optional — but that would have several downsides. First, it would make our data model more fragile, as we could easily miss to populate that property when loading User values within various contexts (and the compiler wouldn’t be able to warn us about it). Second, and arguably more important, is that we’d constantly have to unwrap that optional favorites value every time we access it, leading to either extra boilerplate code (and potentially ambiguous states), or dangerous force unwrapping.

Another, more robust option would be to use a secondary, partial model when decoding our User data, which we would then combine with a Favorites value in order to form our final model — like this:

extension User {
    struct Partial: Decodable {
    let id: UUID
    var name: String
    var membershipPoints: Int
}
}

struct Networking {
    var session = URLSession.shared
    ...

    func loadUser(withID id: User.ID) async throws -> User {
        let favoritesURL = favoritesURLForUser(withID: id)
        let userURL = urlForUser(withID: id)

        // Load the user's favorites and the partial user data
        // that our server responds with:
        async let favorites = request(favoritesURL) as Favorites
        async let partialUser = request(userURL) as User.Partial

        // Form our final user model by combining the partial
        // model with the favorites that were loaded:
        return try await User(
            id: partialUser.id,
name: partialUser.name,
membershipPoints: partialUser.membershipPoints,
            favorites: favorites
        )
    }
    
    ...

    private func request<T: Decodable>(_ url: URL) async throws -> T {
        let (data, _) = try await session.data(from: url)
        return try JSONDecoder().decode(T.self, from: data)
    }
}

While the above works perfectly fine, it would be really nice to find a solution that doesn’t require us to duplicate all of our User model’s properties by declaring a separate, decoding-specific Partial model. Thankfully, the Swift Codable system* does actually include such a solution — the somewhat lesser known CodableWithConfiguration API.

* CodableWithConfiguration is not technically a direct part of Codable, which is defined within Swift’s standard library, but is instead an extension defined within Foundation. That doesn’t make much of a difference when targeting any of Apple’s platforms, though.

When a type conforms to either EncodableWithConfiguration or DecodableWithConfiguration, it requires an additional configuration value to be passed when either encoding or decoding it (and the compiler will enforce that requirement). That’s incredibly useful in situations such as when decoding our User type, since we can define that Favorites is the required DecodingConfiguration for our type — meaning that we can ensure that such a value will always be present during decoding, without having to declare any additional partial types.

So let’s go ahead and update our User type to conform to DecodableWithConfiguration, which does require a manual decoding implementation, unfortunately:

extension User: Encodable, DecodableWithConfiguration {
    enum CodingKeys: CodingKey {
        case id
        case name
        case membershipPoints
    }

    init(from decoder: Decoder, configuration: Favorites) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)

        id = try container.decode(UUID.self, forKey: .id)
        name = try container.decode(String.self, forKey: .name)
        membershipPoints = try container.decode(
            Int.self,
            forKey: .membershipPoints
        )
        favorites = configuration
    }
}

So we still have to write a bit of boilerplate in order to enable our new decoding setup, but the advantage is that we can now make our networking code a lot simpler — all that we need is another overload of our private request method, which works with types conforming to DecodableWithConfiguration, and we’ll now be able to leverage type inference to make our decoding call site a lot simpler:

struct Networking {
    ...

    func loadUser(withID id: User.ID) async throws -> User {
        let favoritesURL = favoritesURLForUser(withID: id)
        let userURL = urlForUser(withID: id)

        return try await request(userURL, with: request(favoritesURL))
    }
    
    ...

    private func request<T: Decodable>(_ url: URL) async throws -> T {
        ...
    }

    private func request<T: DecodableWithConfiguration>(
        _ url: URL,
        with config: T.DecodingConfiguration
    ) async throws -> T {
        let (data, _) = try await session.data(from: url)

        return try JSONDecoder().decode(
    T.self,
    from: data,
    configuration: config
)
    }
}

However, one thing that’s a bit puzzling about the Codable WithConfiguration API is that even though the protocol itself, as well as the KeyedCodingContainer methods that enable us to perform nested decoding of such types, are all available from iOS 15, the top-level configuration-compatible JSONDecoder API wasn’t added until iOS 17.

Thankfully, that’s something that we can quite easily work around if working on a project that needs to support iOS 16 and earlier — by introducing our own implementation of that API, which uses Codable’s userInfo mechanism to store the configuration of the value that we’re currently decoding:

extension JSONDecoder {
    // First, we define a wrapper type which we'll use to decode
    // values that require a configuration type:
    private struct ConfigurationDecodingWrapper<
        Wrapped: DecodableWithConfiguration
    >: Decodable {
        var wrapped: Wrapped

        init(from decoder: Decoder) throws {
            let configuration = decoder.userInfo[configurationUserInfoKey]

            wrapped = try Wrapped(
                from: decoder,
                configuration: configuration as! Wrapped.DecodingConfiguration
            )
        }
    }

    private static let configurationUserInfoKey = CodingUserInfoKey(
        rawValue: "configuration"
    )!

    // Then, we declare our own decode method (which omits the
    // type parameter in order to not conflict with the built-in
    // API), which will work on iOS 15 and above:
    func decode<T: DecodableWithConfiguration>(
        from data: Data,
        configuration: T.DecodingConfiguration
    ) throws -> T {
        let decoder = JSONDecoder()
        decoder.userInfo[Self.configurationUserInfoKey] = configuration

        let wrapper = try decoder.decode(
            ConfigurationDecodingWrapper<T>.self,
            from: data
        )

        return wrapper.wrapped
    }
}

CodableWithConfiguration is really quite useful when using Swift’s built-in serialization API to encode and decode types that require additional data in order to be initialized, without having to resort to modeling required data as optional, or having to define additional types that are only ever used for decoding purposes.

I hope that you found this article useful. Feel free to reach out via either either Mastodon or Bluesky if you have any questions or feedback.

Thanks for reading!

Swift by Sundell is brought to you by the Genius Scan SDK — Add a powerful document scanner to any mobile app, and turn scans into high-quality PDFs with one line of code. Try it today.

SwiftUI’s ViewBuilder type is a key part of the library’s overall API design, in that it’s what enables multiple view expressions to be declared within a given scope (such as a body property implementation, or a closure passed to containers such as HStack or VStack) without requiring any manual grouping or wrapping at each call site.

For example, within the following VStack, we can simply place each subview within the closure we pass to it, and ViewBuilder will take care of collecting those views and building them into the final content that then gets rendered within the stack:

VStack {
    Image(systemName: "star")
    Text("Hello, world!")
}

What’s interesting about ViewBuilder is that it’s completely possible to use SwiftUI for a significant amount of time before even discovering that it exists. After all, we don’t have to reference it explicitly in most situations, as SwiftUI’s various closures and protocols have already been annotated with the corresponding @ViewBuilder attribute out of the box.

For example, the View protocol that we use every time we want to define a custom view uses ViewBuilder implicitly, since the definition for the body property requirement looks like this:

@MainActor @preconcurrency public protocol View {
    associatedtype Body : View

    @ViewBuilder @MainActor @preconcurrency var body: Self.Body { get }
}

That’s what makes it possible to use things like control flow within our view body implementations, even when each branch within such a flow returns different types, and even when we don’t explicitly mark our property with @ViewBuilder ourselves:

struct RootView: View {
    @State private var user: User?

    var body: some View {
        if let user {
    HomeView(user: user)
} else {
    LoginView(user: $user)
}
    }
}

The way our views automatically get annotated with @ViewBuilder works the same way as why we don’t have to manually mark our views as @MainActor to run them on the main thread — our custom view types automatically inherit those attributes from the View protocol declaration.

But there are situations in which using ViewBuilder directly can be incredibly useful — so let’s go ahead and explore a few such examples, along with some tips and tricks that can be good to keep in mind when writing that kind of code.

Custom containers

Any property, function, or closure can be marked with the @ViewBuilder attribute, which opts that code into getting the same “DSL-like” capabilities as SwiftUI’s built-in APIs. For example, let’s say that we’re building a custom Container view, which renders a header on top of a content view, while also applying some default styling to those two components:

struct Container<Header: View, Content: View>: View {
    var header: Header
    var content: Content

    var body: some View {
        VStack(spacing: 0) {
            header
                .frame(maxWidth: .infinity)
                .padding()
                .foregroundStyle(.white)
                .background(Color.blue)

            ScrollView {
                content.padding()
            }
        }
    }
}

As our Container view is currently defined, we’re limited to using just a single view for both the header and content properties, and we’d pass them just like we’d pass any other Swift initializer values — for example like this:

Container(header: Text("Welcome"), content: ContentView())

Now, let’s go ahead and mark both header and content with the @ViewBuilder attribute, to see how that affects our view’s API:

struct Container<Header: View, Content: View>: View {
    @ViewBuilder var header: Header
    @ViewBuilder var content: Content

    var body: some View {
        ...
    }
}

What’s interesting is that, even though we haven’t redefined either of the above properties as being closures (they still both just store a single view value), their values must now be passed as closures when we initialize our Container view. ViewBuilder will then take any closure that we passed, and apply its view building logic to it, resulting in a single output view, which is then stored within each property.

What that means is that we’re now able to use the same SwiftUI syntax as when interacting with the library’s built-in APIs when defining either our header or content. Let’s use that new capability to update our RootView from before to use our new Container implementation, as we’re now able to use an if statement with separate view branches to declare our view’s content:

struct RootView: View {
    @State private var user: User?

    var body: some View {
        Container(header: {
            Text("Welcome")
        }, content: {
            if let user {
    HomeView(user: user)
} else {
    LoginView(user: $user)
}
        })
    }
}

Neat! Next, let’s take a look at how we might handle situations when we want to omit a specific component from a custom container view.

Making view builder properties optional

For example, let’s say that we want to make our Container view’s header optional. One way to get that done would be to write an extension on Container with a generic constraint on SwiftUI’s EmptyView type, which allows us to then pass that type’s initializer as a closure when calling our view’s member-wise initializer:

extension Container where Header == EmptyView {
    init(@ViewBuilder content: () -> Content) {
        self.init(header: EmptyView.init, content: content)
    }
}

Note that we have to use a closure for our content property above, rather than just a Content value. That’s because the automatic conversion from view builder closure to single view value that we utilized before only works for stored properties, not for function arguments. Our closure doesn’t need to be @escaping, though, since SwiftUI will still evaluate it directly and automatically convert it into a single view, just like when using our view’s member-wise initializer.

With the above in place, we could now update our RootView to no longer use a header, which in turn enables us to use trailing closure syntax to achieve a call site that looks exactly like when using SwiftUI’s built in containers (like HStack or VStack):

struct RootView: View {
    @State private var user: User?

    var body: some View {
        Container {
            if let user {
                HomeView(user: user)
            } else {
                LoginView(user: $user)
            }
        }
    }
}

While the above works great, there’s an alternative approach that we can take if we don’t want to define a constrained Container extension, but rather just use a custom initializer with default argument values instead.

What’s cool about using ViewBuilder is that, unlike when accepting separate view values directly, the compiler will automatically infer the concrete types for Header and Content if we use default arguments for their corresponding values.

So, if we specify EmptyView.init as the default value for our header property argument, then we can achieve the exact same result as when using the extension-based approach, while also giving us the option to keep adding more default values and convenience APIs in the future — all without having to define multiple extensions:

struct Container<Header: View, Content: View>: View {
    var header: Header
    var content: Content

    init(@ViewBuilder header: () -> Header = EmptyView.init,
         @ViewBuilder content: () -> Content) {
        self.header = header()
        self.content = content()
    }

    var body: some View {
        ...
    }
}

Note that we no longer need to add the @ViewBuilder attribute to our properties, since we now perform the closure-to-view conversion ourselves (by simply calling those closures within our view’s initializer).

An alternative approach would’ve been to instead store references to our closures within the header and content properties, and to then call those closures within our view’s body. Doing so wouldn’t make much of a difference in this particular case (besides requiring those closures to be @escaping, which most of SwiftUI’s own view builder closures aren’t), however, in some situations, taking that approach can significantly hurt performance — since we’ll end up re-evaluating those closures every time our view’s body gets re-evaluated. So, when possible, resolving each view builder closure up-front gives us the most predictable and consistent results.

Handling multiple view expressions

Just like when using SwiftUI’s built-in containers, it’s also now possible to place multiple view expressions within either our header or content closures. For example, if we bring back the header within our RootView, we might use this capability to add a NavigationLink below our welcome text — like this:

struct RootView: View {
    ...

    var body: some View {
        Container(header: {
            Text("Welcome")
            NavigationLink("Info") {
    InfoView()
}
        }, content: {
            ...
        })
    }
}

However, call sites like the one above might not always produce the result we’d expect, since when processed by ViewBuilder, multiple view expressions will essentially be treated the same way as if they were added to a SwiftUI Group — in that they’ll each be independently styled, sized, and positioned according to the current context.

So, in the above example, we’re not actually adding a combined header to our view, but rather two separate headers — each with its own layout within the enclosing VStack, and each with its own set of modifiers applied to it.

To resolve that, it might be a good idea to wrap both our header and content views within explicit containers, so that their layout will always be predictable, even when multiple view expressions are used at a specific call site:

struct Container<Header: View, Content: View>: View {
    ...

    var body: some View {
        VStack(spacing: 0) {
            VStack { header }
                .frame(maxWidth: .infinity)
                .padding()
                .foregroundStyle(.white)
                .background(Color.blue)

            ScrollView {
                VStack { content }
                    .padding()
            }
        }
    }
}

Whether to take the above approach (and enforce a specific layout within the container in question), or leave it up to each call site to define its own layout, will likely come down to a combination of personal/team preference and the specific container (and layout behaviors) that we’re implementing.

There are cases, though, where it’s arguably best to add an explicit container at the call site, in order to make our code more clear and easier to maintain. For example, here we’re using @ViewBuilder as a sort of code organization tool, in that we’re applying it to private functions that we’re using to build separate parts of our view — which in general is a really great way to structure increasingly complex SwiftUI view implementations, rather than allowing our body properties to grow too large in scope:

struct RootView: View {
    @State private var user: User?

    var body: some View {
        Container(header: header, content: content)
    }
}

private extension RootView {
    @ViewBuilder func header() -> some View {
        Text("Welcome")
        NavigationLink("Info") {
            InfoView()
        }
    }

    @ViewBuilder func content() -> some View {
        if let user {
            HomeView(user: user)
        } else {
            LoginView(user: $user)
        }
    }
}

However, while our above code is now very neatly organized, the semantics of our new header function are arguably a bit odd — since it doesn’t really return a header, but rather multiple view expressions that will be built into a header. It might be a nitpicky detail in the grand scheme of things, but aiming to write code to be as clear as possible does often really help when it comes to future maintainability.

A rule of thumb that can be good to follow is that a function or computed property should never return multiple root view expressions (since that gives us an implicit group, just like before). Instead, it would arguably be better if our header function didn’t actually use ViewBuilder, but rather just returned an explicit VStack which in turn contains our header view’s content. That way, it’ll become crystal clear how our header will be rendered, even if we end up changing how our Container view works in the future:

private extension RootView {
    func header() -> some View {
        VStack(spacing: 20) {
            Text("Welcome")
            NavigationLink("Info") {
                InfoView()
            }
        }
    }

    @ViewBuilder func content() -> some View {
        if let user {
            HomeView(user: user)
        } else {
            LoginView(user: $user)
        }
    }
}

We still want to keep using @ViewBuilder for our content function, though, since it returns just a single (albeit conditional) root view expression.

Swift by Sundell is brought to you by the Genius Scan SDK — Add a powerful document scanner to any mobile app, and turn scans into high-quality PDFs with one line of code. Try it today.

Conclusion

SwiftUI’s ViewBuilder is a really powerful tool, and the fact that we can opt our own code into using it gives us a lot of flexibility when it comes to how we want to structure and reuse our UI code. By adopting it within our own custom containers, we can really craft APIs that feel right at home alongside SwiftUI’s own features, which in turn should help us improve the consistency and clarity of the UI code that we write.

I hope you enjoyed this article. If you have any questions, comments, or feedback, then feel free to reach out via either Mastodon or Bluesky.

Thanks for reading!

Swift’s defer keyword allows us to delay the execution of a given block of code until the current scope is exited. While that might initially not seem that useful (after all, can’t we simply write that code at the end of the scope instead?), it turns out that when writing modern Swift code, we’re quite often dealing with multiple potential exit points within our functions and closures — especially when writing code that throws, or when utilizing async/await.

Let’s take a look at the following SearchService type’s loadItems method as an example. It uses a Database API that requires a connection to be opened before any operations can be performed, and that connection then needs to be properly closed and cleaned up before new database requests can be accepted:

actor SearchService {
    private let database: Database
    ...

    func loadItems(maching searchString: String) throws -> [Item] {
        let connection = database.connect()

        do {
            let items: [Item] = try connection.runQuery(.entries(
                matching: searchString
            ))

            connection.close()
            return items
        } catch {
            connection.close()
            throw error
        }
    }
}

Note how we need to explicitly specify the type for our items above, since the runQuery method is generic, as it can return an array of any kind of database-compatible entry type that we’re looking to retrieve.

Because our code has two separate branches (one for when our runQuery call succeeds, and one for when an error is thrown), we need to write separate calls to connection.close within each branch. That might initially not seem like a big deal, but just like most code duplication, it increases the chance that we’ll end up making a mistake, which could result in a quite major bug in this instance (as missing a close call would leave the database unable to accept additional requests).

One way to solve the above problem would be to ensure that our code only has a single branch of execution. In the case of the above loadItems method, that could be done by using the closure-based Result initializer included in the standard library, which converts a throwing closure into a result, which can then be unwrapped once we’ve closed our database connection — like this:

actor SearchService {
    private let database: Database
    ...

    func loadItems(maching searchString: String) throws -> [Item] {
        let connection = database.connect()

        let result = Result<[Item], Error> {
            try connection.runQuery(.entries(matching: searchString))
        }

        connection.close()
        return try result.get()
    }
}

While that’s certainly an improvement — let’s now take a look at how defer lets us solve the problem in an arguably much more elegant way, since it’ll let us define the closing of our database connection right next to where the connection is opened:

actor SearchService {
    private let database: Database
    ...

    func loadItems(maching searchString: String) throws -> [Item] {
        let connection = database.connect()
        defer { connection.close() }

        return try connection.runQuery(.entries(matching: searchString))
    }
}

Nice! Not only are the calls to connect and close now right next to each other (which arguably makes it easier to reason about those two calls as a pair), but because we can now directly return the result of our runQuery call, we no longer have to manually specify any type information — the compiler can now automatically infer the return type of that call for us.

Using defer does have somewhat of a downside, though, in that it sort of breaks the traditional control flow model that structured programming tends to follow — where instructions are always executed from top to bottom. Within our current loadItems implementation, for example, we now have three expressions:

• 1. Open the connection
• 2. Close the connection (deferred)
• 3. Run our query

But those expressions won’t be executed in the order 1, 2, 3, but rather in the order 1, 3, 2, which might initially seem like a quite strange way of structuring our code. So, using defer might end up being somewhat of an acquired taste, and a tool that should probably not be over-used, but rather just used when there’s some specific cleanup work that we want to ensure gets performed no matter how the current scope is exited.

Async contexts

The defer keyword is perhaps even more useful in the concurrent world of async/await, since one of the benefits of that way of writing async code is that it lets us “flatten” code that previously required nesting in the shape of closures or separate operations.

For example, within the following ItemListService, we once again have to work with separate code branches (and thus, nesting) in order to ensure that an isLoading bool is set back to false whenever a loading operation was completed:

actor ItemListService {
    private let networking: NetworkingService
    private var isLoading = false
    ...

    func loadItems(after lastItem: Item) async throws -> [Item] {
        guard !isLoading else { throw Error.alreadyLoading }
isLoading = true

        do {
            let request = requestForLoadingItems(after: lastItem)
            let response = try await networking.performRequest(request)
            let items: [Item] = try response.decoded()
            
            isLoading = false
            return items
        } catch {
            isLoading = false
            throw error
        }
    }
}

In this case, we can’t rely on the Result-based approach we took earlier to flatten our code into a single branch, since there’s no built-in way to convert an async closure into a Result (although that’s something we could add, using a custom extension). So this is a type of situation where defer really comes in handy, as it lets us ensure that our isLoading state is always assigned back to false whenever an operation either succeeded or failed:

actor ItemListService {
    private let networking: NetworkingService
    private var isLoading = false
    ...

    func loadItems(after lastItem: Item) async throws -> [Item] {
        guard !isLoading else { throw LoadingError.alreadyLoading }
        isLoading = true
        defer { isLoading = false }

        let request = requestForLoadingItems(after: lastItem)
        let response = try await networking.performRequest(request)
        return try response.decoded()
    }
}

The above type of approach can also be really useful when working with nested async tasks as well. For example, let’s say that we wanted to improve the above loadItems method so that it doesn’t throw an error if called while a loading operation is already underway. To do that, we could keep track of a dictionary of loading tasks (keyed by the ID of the lastItem for each task), and then use defer to ensure that a task is always removed from that dictionary when it was completed — like this:

actor ItemListService {
    private let networking: NetworkingService
    private var activeTasksForLastItemID = [Item.ID: Task<[Item], Error>]()
    ...

    func loadItems(after lastItem: Item) async throws -> [Item] {
        if let existingTask = activeTasksForLastItemID[lastItem.id] {
            return try await existingTask.value
        }

        let task = Task {
            defer { activeTasksForLastItemID[lastItem.id] = nil }

            let request = requestForLoadingItems(after: lastItem)
            let response = try await networking.performRequest(request)
            return try response.decoded() as [Item]
        }

        activeTasksForLastItemID[lastItem.id] = task
return try await task.value
    }
}

In general, the above technique is a neat way of preventing duplicate async actor requests, since actors only protect against simultaneous calls while they’re busy performing synchronous work. Once an actor has started an async task using await, it’s free to accept new calls while that async task is being performed. By using a nested Task combined with the defer keyword, we can ensure that such duplicate requests are properly reused and discarded once finished, all in a predictable manner.

Swift by Sundell is brought to you by the Genius Scan SDK — Add a powerful document scanner to any mobile app, and turn scans into high-quality PDFs with one line of code. Try it today.

Conclusion

Swift’s defer keyword might initially seem like a somewhat odd language tool, as it doesn’t strictly follow the top-to-bottom control flow order that structured programming tend to use. But when it comes to cleanup operations, state management, and other tasks that we want to ensure are run no matter how a given scope is exited, it can be a really great tool — especially when utilizing Swift concurrency and the language’s native error handling model.

If you’ve got questions, comments, or feedback, then feel free to reach out via either Mastodon or Bluesky.

Thanks for reading!

These days, most applications need to work with URLs in some form. Perhaps they’re used to make network calls, to read and write files, or to perform various kinds of database operations. In Swift, URLs are by convention (and through the design of Apple’s frameworks) represented using the dedicated URL type, rather than just using plain strings, which ensures that we’re actually working with valid, properly formatted URLs.

However, that also means that anytime that we have a string that we wish to treat as a URL, we have to perform a conversion that returns an optional — such as in this case:

guard let url = URL(string: "https://swiftbysundell.com") else {
    // Hmmm... now what?
    return print("Invalid URL")
}

For URLs such as the one above, which are constructed using static string literals, using a conversion that can fail does arguably feel a bit unnecessary. After all, there’s no runtime variance involved here, so there’s really no significant risk that the above kind of conversion will result in nil, unless we’ve made a typo within our code.

So, when working with such static URLs, it’s very common to simply use force unwrapping to turn the resulting optional URL into a non-optional one:

let url = URL(string: "https://swiftbysundell.com")!

However, having to do the above kind of force unwrapping manually every time we want to construct a URL is not quite ideal — so let’s see if we can improve things. First, let’s extend URL with an initializer that accepts a StaticString (which are Swift string literals without any kind of interpolation or dynamic components), within which we can perform the required unwrapping, but this time we’ll use a custom fatalError message in case the conversion to a URL failed:

extension URL {
    init(staticString: StaticString) {
        guard let url = Self(string: "\(staticString)") else {
            fatalError("Invalid static URL string: \(staticString)")
        }

        self = url
    }
}

Using a custom fatalError call in situations when we have to force unwrap a value is in general a good practice, since that lets us provide additional context that can be incredibly useful if we ever need to debug a crash caused by a nil value.

With the above in place, we can now easily convert any static string within our code base into a URL, without having to deal with optionals at every single call site:

let url = URL(staticString: "https://swiftbysundell.com")

Nice! Up until Swift 5.9, the above approach was more or less the best simple way to work with inline, static URLs in a non-optional manner (without requiring any external tools, such as code generation). However, Swift 5.9 introduced a new feature that can be incredibly useful in situations like this — macros.

It’s macro time!

Let’s see if we can write a Swift macro that’ll let us not just convert, but also validate static URL strings at compile time. We’ll start by jumping over to the command line, where we’ll run the following command to create a new macro-based Swift package:

swift package init --type macro --name StaticURL

One thing that’s neat about macro packages, is that they come pre-filled with most of the boilerplate that we’ll need to define and vend our macro to any other targets that wish to use it — and it just so happens that the stringify macro that’s added as an example is the exact same type of macro that we’re looking to add — a freestanding expression macro.

So let’s go ahead and simply rename the definition of stringify to staticURL, and change its input and output types to match the URL extension we created earlier:

import Foundation

@freestanding(expression)
public macro staticURL(_ value: StaticString) -> URL = #externalMacro(
    module: "StaticURLMacros",
    type: "StaticURLMacro"
)

Next, let’s rename the StringifyMacro implementation to StaticURLMacro (matching the above definition’s type argument), and replace its previous expansion code with some logic that first ensures that the passed argument is indeed a string literal (although the Swift type system should already have verified that for us), and then extracts the string and attempts to construct a URL using it.

If all checks pass, then we generate the same kind of force-unwrapping URL construction code that we manually used to write, which will be the output of our macro. Here’s what all of that looks like:

public struct StaticURLMacro: ExpressionMacro {
    public static func expansion(
        of node: some FreestandingMacroExpansionSyntax,
        in context: some MacroExpansionContext
    ) throws -> ExprSyntax {
        // Verify that a string literal was passed, and extract
        // the first segment. We can be sure that only one
        // segment exists, since we're only accepting static
        // strings (which cannot have any dynamic components):
        guard let argument = node.arguments.first?.expression,
              let literal = argument.as(StringLiteralExprSyntax.self),
              case .stringSegment(let segment) = literal.segments.first
        else {
            throw StaticURLMacroError.notAStringLiteral
        }
        
        // Verify that the passed string is indeed a valid URL:
        guard URL(string: segment.content.text) != nil else {
            throw StaticURLMacroError.invalidURL
        }

        // Generate the code required to construct a URL value
        // for the passed string at runtime:
        return "Foundation.URL(string: \(argument))!"
    }
}

Note how we prefix the URL type with its parent module (Foundation) above. That’s to avoid conflicts if our macro is used within a context that has declared its own URL type. Applying such prefixes isn’t typically necessary when writing code manually, but is a good practice when writing macros, since we don’t know up-front exactly where our macros will end up being used.

With our macro implementation done, all that remains is to define the StaticURLMacroError type that’s used above, and to update our CompilerPlugin to provide the correct macro type:

enum StaticURLMacroError: String, Error, CustomStringConvertible {
    case notAStringLiteral = "Argument is not a string literal"
    case invalidURL = "Argument is not a valid URL"

    public var description: String { rawValue }
}

@main struct StaticURLPlugin: CompilerPlugin {
    let providingMacros: [Macro.Type] = [StaticURLMacro.self]
}

With all those pieces in place, if we integrate our new StaticURL macro package within an application, then we can now easily define static, 100% compile-time validated URLs wherever we’d like:

let url = #staticURL("https://swiftbysundell.com")

Neat! It could definitely be argued that using a macro isn’t really necessary for a use case like this, given that our earlier StaticString-based extension approach worked just fine (apart from the danger of typos). Like in many cases when working with Swift, this is essentially a trade-off between increased complexity and compile-time safety, and whether or not the additional complexity of a macro will be worth it will likely vary from project to project.

Dynamic components

So far, we’ve been working with URLs that are known at compile time, but what about ones that have to be constructed at runtime? For example, here we’re using string interpolation to define a URL that’ll be used to load User data from a given web API endpoint:

actor NetworkingService {
    private static let baseURL = "https://api.myapp.com"
    ...

    func loadUser(withID id: User.ID) async throws -> User {
        guard let url = URL(
            string: "\(Self.baseURL)/users/\(id)?refresh=true"
        ) else {
            throw NetworkingError.invalidURL
        }

        ...
    }
}

Here we’re facing a very similar problem as when working with static URLs — when reading the above code, we can see that there’s no way that the performed URL conversion will ever result in nil, given that our baseURL and /users/ strings are both static, and if we assume that User.ID values are always URL-safe.

So would it be possible to convince the compiler that a nil result can never occur, even when working with dynamic URL components? An initial idea might be to use Foundation’s dedicated URLComponents builder — which offers a structured way to construct dynamic URLs.

While that approach does have some key advantages over using string interpolation (since we’re now assigning values to explicit parts of the URL we’re building, rather than just working with a loosely formed string) — it’s significantly more verbose in comparison, while still not getting rid of having to unwrap our URL as an optional:

actor NetworkingService {
    private static let baseURLComponents = {
        var components = URLComponents()
        components.scheme = "https"
        components.host = "api.myapp.com"
        return components
    }()
    
    ...

    func loadUser(withID id: User.ID) async throws -> User {
        var urlComponents = Self.baseURLComponents
        urlComponents.path = "/users/\(id)"
        urlComponents.queryItems = [
            URLQueryItem(name: "refresh", value: "true")
        ]

        guard let url = urlComponents.url else {
            throw NetworkingError.invalidURL
        }

        ...
    }
}

Thankfully, it turns out that there’s a much simpler suite of APIs for dynamic URL construction that were introduced in iOS 16 (and the other 2022 Apple operating system versions) that — when combined with our static URL handling code from before — lets us both completely get rid of optionals, and gives us a really nice syntax for constructing our API call URL.

If we declare our base URL as a static URL value (rather than a string, or a URLComponents value), then we can simply call different overloads of the appending API on that value to construct our dynamic URL in a completely optional-free manner — like this:

actor NetworkingService {
    private static let baseURL = #staticURL("https://api.myapp.com")
    ...

    func loadUser(withID id: User.ID) async throws -> User {
        let url = Self.baseURL
            .appending(components: "users", id)
            .appending(queryItems: [
                URLQueryItem(name: "refresh", value: "true")
            ])
            
        ...
    }
}

Very nice! And the good news is that we’re not limited to just using the above kind of solution when constructing URLs used to perform network calls — we can also use the same suite of APIs when working with file system URLs that we’d previously resolve using FileManager, such as in this example:

private extension NetworkingService {
    func cacheResponseOnDisk(_ response: Response) throws {
        guard let cacheFolderURL = FileManager.default.urls(
            for: .cachesDirectory,
            in: .userDomainMask
        ).first else {
            throw NetworkingError.failedToResolveCacheFolder
        }

        ...
    }
}

If we now convert the above code to use the new URL construction APIs, then we’ll end up with a another non-optional solution, just as when constructing our web API URL:

private extension NetworkingService {
    func cacheResponseOnDisk(_ response: Response) throws {
        let cacheURL = URL
            .cachesDirectory
            .appending(component: response.cacheID)

        ...
    }
}

URL now also contains a number of other static properties that can be used to reference common folders on Apple’s platforms, such as the home and temporary directories — all of which hold a predictable, non-optional value:

URL.homeDirectory
URL.documentsDirectory
URL.desktopDirectory
URL.temporaryDirectory

So, as long as we’re targeting the equivalent of iOS 16 or above within a given project, then we’re now able to quite easily construct both web and file system URLs, even when they contain dynamic paths and components, such as query items.

Swift by Sundell is brought to you by the Genius Scan SDK — Add a powerful document scanner to any mobile app, and turn scans into high-quality PDFs with one line of code. Try it today.

Conclusion

Using Foundation’s modern URL construction APIs to be able to avoid optionals when creating URL values doesn’t just simplify our code, it also reduces the risk of bugs and crashes, and further lets us work with URLs in more structured ways — by replacing things like string interpolation with dedicated APIs for appending path components and query items.

I hope you’ve enjoyed reading this first Swift by Sundell article in over two years, and that you’ll find it useful when working on your Swift projects. If you have any questions, feedback, or comments, then feel free to reach out via either Mastodon or Bluesky.

Thanks for reading — and hey, it’s good to be back!