Gatsby Starter Blog RSS Feed

Libraries with resources optimized for build time and application size

Tue, 27 Jun 2023 00:00:00 GMT

When you have a large code base more often than not you end up with your code broken down into multiple frameworks. But when it comes to resources often they are kept together in the main app bundle. While this works for the single app target it may present some challenges when testing your code, especially using snapshot tests, or affect the application size when you have additional targets like app extensions.

When you have a framework that implements your design system components, like we do at Wise, it's only logical to keep the common resources for these components - fonts, colors, icons, illustrations etc. - in that framework. In addition to the design system framework we have many other frameworks with feature code some of which require some feature specific resources.

Our current setup configures our frameworks to be built as static libraries. Since static libraries can't contain any resources we also have companion bundle targets for those frameworks that require resources. Their purpose is to package resources of the framework in a *.bundle that is then copied as a resource to the main app target. This allows us to achieve higher number of frameworks without negatively affecting the app start up time as if we were to use dynamic libraries instead.

If you are curios to dive deeper into static vs dynamic libraries topic here is a nice article - Static vs Dynamic Frameworks on iOS — a discussion with ChatGPT. And make sure to watch "Meet mergeable libraries" WWDC'23 video and its related videos.

This setup works but comes with its own costs. Every clean build requires rebuilding the frameworks and the bundles. And building some of the bundles can take quite a lot of time if they contain large assets catalogs. To build a bundle with asset catalogs Xcode uses actool that compresses .xcassets into a single Assets.car file. In our case our catalogs grew so big that compiling them took around 50 seconds. That's a large performance hit for something that does not really change regularly so does not have to be rebuilt on every clean build. Later we will also see that this setup can negatively affect the application size.

To address this issue instead of rebuilding resource bundle every time we can extract resources and code to access them (we use SwiftGen for that) into a separate target that we will build once and consume as a binary in our other targets. Further we will call this target WiseAtoms.

This can be achieved in two ways:

using static library and prebuilt resources bundle
using binary dynamic library with resources included

We will explore both of these approaches and their pros and cons.

Static library with resouces bundle

This is the setup that is identical to how we have all our frameworks setup at Wise so requires minimum changes to our project configuration. All we have to do is to create and use a new WiseAtoms framework in a few simple steps.

First we extract our resources and code to access them into two new targets (we use xcodegen to manage our project so this is a trivial task) - WiseAtoms.bundle and WiseAtoms.framework. WiseAtoms.framework will contain a static library with code to access the resources and WiseAtoms.bundle will contain those resources in the assets catalog.

Then we create a dummy app target that would depend on the WiseAtoms.framework and WiseAtoms.bundle and write a script that uses xcodebuild to archive this app. This will compile our assets catalog and create a bundle for us.

xcodebuild archive \
     -workspace Wise.xcworkspace \
     -scheme WiseAtomsDummyApp \
     -destination "generic/platform=iOS" \
     -archivePath "build/WiseAtoms"

We only need to archive for iOS since this will work both on device and simulator - if we build for iOS simulator then we will get an error when trying to distribute the app with this bundle to the AppStore: ERROR: Asset validation failed (90542) Invalid CFBundleSupportedPlatforms value. The CFBundleSupportedPlatforms key in the Info.plist file in “Payload/Wise.app/WiseAtoms.bundle” bundle contains an invalid value, [iPhoneSimulator].

Then we copy the WiseAtoms.bundle from the built app archive to our repository:

cp -R \
    build/WiseAtoms.xcarchive/Products/Applications/WiseAtomsDummyApp.app/WiseAtoms.bundle Wise/ \
    WiseAtoms

This could be configured in Xcode with Aggregate Target but since we are only going to run this on CI the script is enough.

Next we add the WiseAtoms.bundle to our design system framework Copy Resources build phase. By including the WiseAtoms.bundle into our design system framework's bundle we are avoiding copying it to every app target separately which makes our project setup a bit simpler. With xcodegen we are doing that simply by adding a path to the bundle in the sources section of the target configuration. If we do that in dependencies section then xcodegen will instead create a dependency between our framework and the bundle target and will build the bundle and compile the assets catalog, which is what we are trying to avoid.

Since our bundle now is inside another bundle we need to adjust the code that refers to this bundle accordingly - by appending WiseAtoms.bundle to the path of the design system framework's bundle: Bundle(url: Bundle.main.bundleURL.appendingPathComponent("WiseAtoms.bundle")).

Next we link WiseAtoms.framework to the design system framework and import it using @_exported import WiseAtoms. This will make code from WiseAtoms available everywhere where we already import our design system framework so we don't need to change any code.

And finally we add WiseAtoms.framework to the app target with Do Not Embed configuration since this is a static framework.

With that we have a separate WiseAtoms.framework and prebuilt WiseAtoms.bundle that won't be rebuilt every time.

Now let's see how we can achieve the same goal using a dynamic library with resources packaged in XCFramework.

XCFramework with dynamic library and resources

Dynamic libraries unlike static libraries can contain resources that would be accessible for the library code at runtime. This means that we don't need a separate target for the bundle, but we need a few extra steps to buildand use this library.

We start again by creating a separate WiseAtoms framework target, but this time we add our resources directly to it. Then following Apple's guide on creating multiplatform XCFramework we configure its build settings:

BUILD_LIBRARY_FOR_DISTRIBUTION: true
SKIP_INSTALL: false

What this guide does not mention are two important settings to make this approach work. First is MACH_O_TYPE that defines a type of binary the framework will compile and how it will be linked to other binaries. We need to set it to mh_dylib to create a dynamic library. This is the default type set for the framework targets when creating them in Xcode, so if you are using Xcode to create a framework you don't need to change it. But since our setup is using xcodegen and we instead default to static libraries we have to explicitly change this setting for WiseAtoms.framework.

The second important setting is SWIFT_SERIALIZE_DEBUGGING_OPTIONS. It's not a part of predefined build settings in Xcode so it has to be added as User Defined setting, and it is only briefly mentioned in "Debug Swift debugging with LLDB" WWDC'22 video. This needs to be set to false or the compiler will record machine specific paths to the debug symbols which will break any debugging on any other machine other than the one it was built on (and even on this machine it will break if you clean DerivedData).

So the whole list of build settings looks like that:

BUILD_LIBRARY_FOR_DISTRIBUTION: true
SKIP_INSTALL: false
MACH_O_TYPE: mh_dylib
SWIFT_SERIALIZE_DEBUGGING_OPTIONS: false

Next following the Apple's guide further we create a script to archive our framework for device and simulator and package both binaries in a single XCFramework:

BUILD_PATH="$(pwd -P)/build/WiseAtoms"
TARGET_PATH="$(pwd -P)/Wise/WiseAtoms/build"
IOS_ARCHIVE_PATH="${BUILD_PATH}/WiseAtoms-iOS.xcarchive"
SIMULATOR_ARCHIVE_PATH="${BUILD_PATH}/WiseAtoms-iOS_Simulator.xcarchive"
PROJECT_NAME="WiseAtoms"

xodebuild archive \
     -workspace Wise.xcworkspace \
     -scheme WiseAtoms \
     -destination "generic/platform=iOS" \
     -archivePath "${IOS_ARCHIVE_PATH}"

xcodebuild archive 
     -workspace Wise.xcworkspace \
     -scheme WiseAtoms \
     -destination "generic/platform=iOS Simulator" \
     -archivePath "${SIMULATOR_ARCHIVE_PATH}"

xcodebuild -create-xcframework \
     -archive "${IOS_ARCHIVE_PATH}" -framework "${PROJECT_NAME}.framework" \
     -archive "${SIMULATOR_ARCHIVE_PATH}" -framework "${PROJECT_NAME}.framework" \
     -output "${TARGET_PATH}/${PROJECT_NAME}.xcframework"

Then after running this script successfully we link WiseAtoms.xcframework to our design system framework and add it to our app target with Embed and Sign configuration so that it is copied to the app bundle and resigned for AppStore distribution.

Lastly we add @_exported import WiseAtoms in the design system framework. And we are done. Almost. There is one more consideration to make. And it relates to the app extensions.

At Wise we have a companion Currency Converter app that has a widget extension. Both the app and the extension use our design system framework. With static library and separate resource bundle it means the extension target need to link to the design system framework and copy its bundle as well to access some of the design system resources. And although the extension only needs a subset of these resources we have to copy the whole bundle. This makes the whole app much larger both when user downloads it and when it is installed on the user's device. While this can be optimised by splitting resources bundle further into smaller bundles, having a different slimmed down version of the bundle for the extension target or adjusting the code to locate the bundle in a different way when the code is run by the extension - this all means a more complicated project configuration.

When we have a dynamic library the resources are packaged together with a binary in a framework so they don't need to be copied to the app target. But we need to make sure that the extension target can load the library at runtime. For that the first thing to do that comes to mind is to embed the WiseAtoms.xcframework in the extension target. While this will work on the simulator it is not valid for AppStore distribution - doing that will result in the validation error: ERROR: Asset validation failed (90685) CFBundleIdentifier Collision. There is more than one bundle with the CFBundleIdentifier value 'com.transferwise.WiseAtoms' under the iOS application 'CurrencyConverter.app'. This is because both the app target and the extension target embed the same WiseAtoms framework.

To avoid this error instead of embedding WiseAtoms.xcframework into the app extension we will link to it with Do Not Embed configuration and we will adjust LD_RUNPATH_SEARCH_PATHS build setting of the extension target to point to the Frameworks directory of the main app target. Since the extension binary is located inside the app bundle at the PlugIns/CurrencyConverterWidget.appex we need to add '@loader_path/../../Frameworks' to the search paths. With this when the widget runs it will load the WiseAtoms.framework from the app's frameworks.

This allowed us to cut the application size more than two times which is expected since we don't have two separate copies of resource bundles.

Although dynamic library setup is different from the default approach we use in our project, the application size improvement makes this approach more attractive - we will only pay a small price of loading the library at the application start up time. We probably could achieve the same result with a static library and a bundle if we can figure out how to locate the bundle from of the app from the app extension but we haven't explored that. We also don't need a separate bundle and dummy app target to build the bundle so our project configuration becomes a bit simpler too. And with Swift Package Manager we can even turn this into a standalone package hosted outside of our monorepo. This won't be possible with a static library and resource bundle because SPM does not support bundle targets.

Decoding nested values with property wrappers

Thu, 13 Feb 2020 00:00:00 GMT

Property wrappers is one of the recent Swift proposals that have been welcomed probably the most by the community. To be fair though they don't bring anything relly revolutionary to the way we write code. For instance in the context of decoding we could use wrapper types from day one. The main difference that property wrappers make (let's forget about their projected value feature) in this context and which makes using them much more attractive is ability to refer to a wrapped value as it was not wrapped. But that makes all the difference. So let's see how property wrappers can be used to solve one decoding edge case as an example - decoding deeply nested values.

The problem

It's common that when decoding some type we want to get access to some value deep down the chain of nested objects. The most trivial approach to do that would be to declare all the intermediate types and properties so that compiler can generate all the code for us. But we, developers, are lazy and don't like to write boilerplate code that we won't use otherwise. Also this approach means that we would need to access these nested values through a long chain of properties, or we would need to write even more boilerplate to incapsulate that.

Wouldn't be nice if we could decode nested values without all these intermediate types and properties baggage? It turns out we can do that and it is pretty easy to do without even fighting the standard library (almost).

Decoding a single nested value

Let's say we have a JSON of the following format:

{
    "id": "1",
    "user": {
        "details": {
            "address": "Apple St."
        }
    }
}

And we want to decode it into the following struct:

struct Contact: Decodable {
    let id: String
    let address: String
}

Out of the box compiler won't generate the code that would be able to decode such JSON in this struct as it does not know about intermediate "user" and "details" keys. Without declaring all the intermediate data structures we would need to implement decoding manually like this:

enum CodingKeys: String, CodingKey {
    case id
    case user
    case details
    case address
}
    
init(from decoder: Decoder) throws {
    let values = try decoder.container(keyedBy: CodingKeys.self)
    
    self.id = try values.decode(String.self, forKey: .id)
    self.address = try values
        .nestedContainer(keyedBy: CodingKeys.self, forKey: .user)
        .nestedContainer(keyedBy: CodingKeys.self, forKey: .details)
        .decode(String.self, forKey: .address)
}

As you see we not only have to implement all the decoding code but also define all the coding keys ourselves. It's not a hard thing to do but can be a lot of typing. Ideally we don't want to implement decoding and to define all the coding keys manually.

To start let's highlight what's missing for the compiler to generate this code for us. First thing that is missing is intermediate coding keys. Compiler generates coding keys based on the stored properties of our type, so in our case it will generate id and address keys, but details and user keys will be missing.

Next thing that is missing is a link between the address property and its key path in the JSON structure. Compiler does not know that to extract address value it needs to go through user and details objects first. If we will be able to provide this link to the compiler somehow then we will be able to remove our custom decoding constructor and just rely on compiler generated code.

So what we need to do now is to somehow abstract this code:

self.address = try values
    .nestedContainer(keyedBy: CodingKeys.self, forKey: .user)
    .nestedContainer(keyedBy: CodingKeys.self, forKey: .details)
    .decode(String.self, forKey: .address)

To do that we need to know the order of the keys and their values. In this case the order is .user, .details, .address. Then we need to know the type of the property we are decoding, which is a String.

When compiler generates decoding code for us it generates calls to the methods of KeyedDecodingContainer which all look like func decode<T>(_: T.Type, forKey key: Key) throws -> T. To decode address property compiler will generate a call to decode(String.self, forKey: .address). So there seem to be no direct way for us to inject the missing keys. And here comes the wrapper.

To hold the intermediate keys that compiler needs to use to generate code we can define a special wrapper type, let's call it NestedDecodable:

struct NestedDecodable<T: Decodable>: Decodable {
    let wrappedValue: T
    let keys: [CodingKey]
}

Now we can declare our address property as wrapped in this type:

let address = NestedDecodable<String>(
    keys: [
        CodingKeys.user, 
        CodingKeys.details, 
        CodingKeys.address
    ]
)

This though won't work as this property will be initialised even before invoking a decoder and we don't have wrapped value to pass to it. So instead we can only declare its type as wrapped into NestedDecodable:

let address = NestedDecodable<String>

But now we don't have a way to specify the keys... We will make it right later but for now let's leave it as it is and move on to the decoding container.

With the code we have so far compiler will generate the code that will try to decode address with decode(NestedDecodable<String>.self, forKey: .address). As NestedDecodable and it's wrapped value are as well decodable types then compiler will generate decoding initialiser for it as well, which will try to decode its wrapped value and coding keys. But both of these properties are not present in the JSON so we can't rely on compiler generated code as it is now.

Instead we can define a specialised decoding function on KeyedDecodingContainer that would decode values of this type with an extension:

extension KeyedDecodingContainer {
    func decode<T>(_: NestedDecodable<T>.Type, forKey key: Key) throws -> NestedDecodable<T> {
        ...
    }
}

Here we would want to decode the value and return it wrapped into the NestedDecodable.

extension KeyedDecodingContainer {
    func decode<T>(_: NestedDecodable<T>.Type, forKey key: Key) throws -> NestedDecodable<T> {
        let wrappedValue = ...
        return NestedDecodable(wrappedValue: wrappedValue)
    }
}

For that we would need to adjust a constructor of NestedDecodable to accept wrapped value:

struct NestedDecodable<T>: Decodable {
    let wrappedValue: T
    init(wrappedValue: T) {
        self.wrappedValue = wrappedValue
    }
}

But now we don't really have a place where to store the nested keys values. As a matter of fact we don't really need them to be stored in NestedDecodable any more as we would need to use them before we even create an instance of NestedDecodable. But without this instance the only thing we have is the type NestedDecodable<T>.Type.

How can we get the list of nested keys when we have only information about types? Remember that coding keys are enums (technically it's not a requirement). How knowing an enum type can we get a list of enum values? Sounds familiar? Right, it's CaseIterable:

enum CodingKeys: String, CodingKey, CaseIterable {
    case id
    case user
    case details
    case address
}

CodingKeys.allCases == [.id, .user, .details, .address]

Almost what we need, except we have all the keys here, but when decoding address we need only user, details and address. Also we need to have these keys exactly in this order as this is the order we would need to go through the JSON. We still need to have id key for id property, so let's define a separate type for address keys:

struct Contact {
    ....
    
    enum CodingKeys: String, CodingKey {
        case id
    }
    
    enum AddressCodingKeys: String, CodingKey, CaseIterable {
        case user, details, address
    }
}

AddressCodingKeys.allCases == [.user, .details, .address]

Great! Now we need to make our NestedDecodable type aware about these extra coding keys type, which we can do by adding another generic parameter to it:

struct NestedDecodable<T, Keys: CodingKey & CaseIterable>: Decodable {
    ...
}

struct Contact: Decodable {
    let id: String
    let address: NestedDecodable<String, AddressCodingKeys>
    
    enum CodingKeys: String, CodingKey {
        case id
    }
    
    enum AddressCodingKeys: String, CodingKey, CaseIterable {
        case user, details, address
    }
}

With that we need to update the signature of our KeyedDecodingContainer extension and we can finally access nested coding keys:

extension KeyedDecodingContainer {
    func decode<T, NestedKeys>(_: NestedDecodable<T, NestedKeys>.Type, forKey key: Key) throws -> NestedDecodable<T, NestedKeys> {
        let keys = NestedKeys.allCases
        let wrappedValue = ...
        return NestedDecodable(wrappedValue: wrappedValue)
    }
}

Now we have everything to start to decode our values. First we would need to get hold of the nested container for user key, then its nested container for details key and finally we would be able to decode the address value. As this is a generic method we don't really know how many nested keys we will have and what will be their actual values, so our method should be generic enough to be able to decode any value with any number of nested keys. For that we will simply iterate over the list of keys and get a nested container for each of the key until we rich the last one which we will use to finally decode the value:

var container: KeydDecodingContainer<NestedKeys>
NestedKeys.allCases.dropLast().forEach { key in
    container = try container.nestedContainer(keyedBy: NestedKeys.self, forKey: key)
}
let wrappedValue = try container.decode(T.self, forKey: NestedKeys.lastCase!)
return NestedDecodable(wrappedValue: wrappedValue)

Unfortunatelly this won't work because when we get the nested container for the first key we don't have a container instance initialised to call nestedContainer on. We only have self which is a container itself, but it has a different type KeyedDecodingContainer<Key> as Key and NestedKeys are different types. So if we will try to use self as initial value var container: KeyedDecodingContainer<NestedKeys> = self the types will mismatch. But as soon as we have a first nested container we will always have KeyedDecodingContainer<NestedKeys> down the way. Seems like we need to handle the first key separately. So let's do that:

var container = try self.nestedContainer(keyedBy: NestedKeys.self, forKey: NestedKeys.allCases.first!)
NestedKeys.allCases.dropFirst().dropLast().forEach { key in
    container = try container.nestedContainer(keyedBy: NestedKeys.self, forKey: key)
}
let wrappedValue = try container.decode(String.self, forKey: NestedKeys.lastCase!)
return NestedDecodable(wrappedValue: wrappedValue)

This still won't compile though - to call self.nestedContainer we need to pass it a key value that is of container's key type, in this case it's Key (at runtime it will be Contact.CodingKeys), but NestedKeys.allCases.first is a NestedKey...

There is also another problem that right now we only have an id key defined in the Contact.CodingKeys. So compiler will complain that a key for address property is missing. Let's add it then.

enum CodingKeys: String, CodingKey {
    case id
    case address
}

Now compiler will call our extension decode method with the address key and we can use it instead of the NestedKeys.allCases.first to get the first nested container. But we need to make sure we set the raw value of this key to the actual root key, which is "user" in our case. With that we won't need user key in Contact.AddressCodingKeys any more:

enum CodingKeys: String, CodingKey {
    case id
    case address = "user"
}

enum AddressCodingKeys: String, CodingKey, CaseIterable {
    case details, address
}

extension KeyedDecodingContainer {
    func decode<T, NestedKeys>(_: NestedDecodable<T, NestedKeys>.Type, forKey key: Key) throws -> NestedDecodable<T, NestedKeys> {
        var container = try self.nestedContainer(keyedBy: NestedKeys.self, forKey: key)
        NestedKeys.allCases.dropLast().forEach { key in
            container = try container.nestedContainer(keyedBy: NestedKeys.self, forKey: key)
        }
        let wrappedValue = try container.decode(String.self, forKey: NestedKeys.lastCase!)
        return NestedDecodable(wrappedValue: wrappedValue)
    }
}

This will finally compile and actually work in runtime! It looks a bit weird that we have two address keys but one of them is actually a "user" key, but that's the way to make compiler happy.

Let's sum up all the code we have right now to see that it's actually not that much:

struct Contact: Decodable {
    let id: String
    let address: NestedDecodable<String, AddressCodingKeys>
    
    enum CodingKeys: String, CodingKey {
        case id
        case address = "user"
    }
    
    enum AddressCodingKeys: String, CodingKey, CaseIterable {
        case details, address
    }
}

struct NestedDecodable<T, Keys: CodingKey & CaseIterable>: Decodable {
    let wrappedValue: T
    init(wrappedValue: T) {
        self.wrappedValue = wrappedValue
    }
}

extension KeyedDecodingContainer {
    func decode<T, NestedKeys>(_: NestedDecodable<T, NestedKeys>.Type, forKey key: Key) throws -> NestedDecodable<T, NestedKeys> {
        guard NestedKeys.allCases.isEmpty == false else { throw ... }
        
        var container = try self.nestedContainer(keyedBy: NestedKeys.self, forKey: key)
        NestedKeys.allCases.dropLast().forEach { key in
            container = try container.nestedContainer(keyedBy: NestedKeys.self, forKey: key)
        }
        let wrappedValue = try container.decode(String.self, forKey: NestedKeys.lastCase!)
        return NestedDecodable(wrappedValue: wrappedValue)
    }
}

extension CaseIterable {
    static var lastCase: Self? {
        guard allCases.isEmpty == false else { return nil }
        let lastIndex = allCases.index(allCases.endIndex, offsetBy: -1)
        return allCases[lastIndex]
    }
}

Now we can decode our Contact type and access its address. The only drawback is that address property is not a String any more but a NestedDecodable<String, Contact.AddressCodingKeys>. We still can access the actual string quite easily with address.wrappedValue, but we now would need to do that everywhere, which is nasty.

By now you already noticed thought that our NestedDecodable type perfectly matches property wrapper requirements, which is a wrappedValue property and init(wrappedValue:) initialiser. So we can go on and annotate it without changing anything else:

@propertyWrapper
struct NestedDecodable<T, Keys: CodingKey & CaseIterable>: Decodable {
    let wrappedValue: T
    init(wrappedValue: T) {
        self.wrappedValue = wrappedValue
    }
}

Now we can change how we declare our address property and with that we can access it directly as a string without even knowing that it was wrapped in the first place:

struct Contact: Decodable {
    let id: String
    @NestedDecodable<String, AddressCodingKeys>
    let address: String
    
    enum CodingKeys: String, CodingKey {
        case id
        case address = "user"
    }
    
    enum AddressCodingKeys: String, CodingKey, CaseIterable {
        case details, address
    }
}

let contact = try JSONDecoder().decode(Contact.self, from: jsonData)
contact.address == "Apple St."

And that's the main "magic" of property wrappers.

Decoding multiple nested value

Now when we can decode a single nested value we can declare as many NestedDecodable properties as we want, we can even completely get rid of any nested types in our data models and make them all flat (in real life you wouldn't do that of course). Let's try to add another nested property, let's say a name. Our JSON will look like this:

{
    "id": "1",
    "user": {
        "details": {
            "address": "Apple St."
            "name": "Jhon Appleseed"
        }
    }
}

We will need to add a new property "annotated" with NestedDecodable wrapper and coding keys for it:

struct Contact: Decodable {
    let id: String
    @NestedDecodable<String, AddressCodingKeys>
    let address: String
    @NestedDecodable<String, NameCodingKeys>
    let name: String
    
    enum CodingKeys: String, CodingKey {
        case id
        case address = "user"
        case name = "user"
    }
    
    enum AddressCodingKeys: String, CodingKey, CaseIterable {
        case details, address
    }
    
    enum NameCodingKeys: String, CodingKey, CaseIterable {
        case details, name
    }
}

This looks fine but unfortunately does not work as different enum cases can't have the same raw values... So to be able to decode nested values with the same root we need a different way to define their common root key. The only feasible way to do that is to define it separately in each nested keys enum:

enum CodingKeys: String, CodingKey {
    case id
}
    
enum AddressCodingKeys: String, CodingKey, CaseIterable {
    case user, details, address
}
    
enum NameCodingKeys: String, CodingKey, CaseIterable {
    case user, details, name
}

With that we again have a problem that CodingKeys does not define all the keys for all the properties in the Contact type. But now as we don't need to change their raw values we can leave it to compiler to generate these keys for us and remove CodingKeys type completely and only leave nested keys enums. But this means that we can't use compiler generated keys for address and name when decoding these properties, as their raw values won't be "user" any more. We need to use user keys from AddressCodingKeys and NameCodingKeys respectively. But we can't use these keys as they are not Contact.CodingKeys...

Sounds like we are in a dead end. Notice though that all our keys are enums based on String raw values. So using the raw value "user" we can create either CodingKeys.user key, or NameCodingKeys.user or AddressCodingKeys.user. So what we need to restore our decoding code is to take the first key in NestedKeys, get its string value and use it to create a Key value. If the raw values of these enum cases match, then this convertion will work perfectly (and if does not - we throw):

let rootKey = Key(stringValue: NestedKeys.allCases.first!.stringValue)

With that we can fix our decoding method:

extension KeyedDecodingContainer {
    func decode<T, NestedKeys>(_: NestedDecodable<T, NestedKeys>.Type, forKey key: Key) throws -> NestedDecodable<T, NestedKeys> {
        guard NestedKeys.allCases.isEmpty == false else { throw ... }
        
        let wrappedValue = try containerForNestedKey().decode(T.self, forKey: NestedKeys.lastCase!)
        return NestedDecodable(wrappedValue: wrappedValue)
    }
    
    private func containerForNestedKey<K: CodingKey & CaseIterable>() throws -> KeyedDecodingContainer<K> {
        guard let rootKey = Key(stringValue: K.allCases.first!.stringValue) else { throw ... }
        
        var container = try self.nestedContainer(keyedBy: K.self, forKey: rootKey)
        if K.allCases.count > 1 {
            try K.allCases.dropFirst().dropLast().forEach { (key) in
                container = try container.nestedContainer(keyedBy: K.self, forKey: key)
            }
        }
        return container
    }
}

That's fine, it compiles now. But we still have one last issue - we still don't have a CodingKeys.user key. If we try to define it manually compiler will complain that there is no Contact.user property. If we don't do that then compiler won't generate this key for us, so our trick with converting keys from one type to another won't work at runtime. So we have nothing to do but to declare a user property to let compiler generate a user key for us:

struct Contact: Decodable {
    let id: String
    @NestedDecodable<String, AddressCodingKeys>
    let address: String
    @NestedDecodable<String, NameCodingKeys>
    let name: String
    
    private let user: ...
}

But what should be its type? We don't actually want to decode anything into this property and we definetely don't want to specify it's full type which is [String: [String: String]]. We could do that but it will break whole decoding as soon as we start to have nested values of any other types - its type will become [String: [String: Any]] for which compiler won't be able to generate decoding code at all.

So as we don't want to have any value in this user property can we declare it just as Void? We could but Void is not Decodable and we can't extend it to conform to any protocol. But what we can do is to define our own Void. In the end it's just a struct with no members.

struct Unit: Decodable {
    init() {}
    init(from decoder: Decoder) {}
}

struct Contact: Decodable {
    let id: String
    @NestedDecodable<String, AddressCodingKeys>
    let address: String
    @NestedDecodable<String, NameCodingKeys>
    let name: String
    
    private let user: Unit
}

(We could name this type something like RootKeyPlaceholder to make its purpose more clear in this context, but Unit is a good general type that can be used for other purposes as well)

And now we are really done. Complier will generate a user key for us, will automatically decode "nothing" into it and we then will be able to convert our key types and have multiple properties nested under the same root key.

Let's recap and see the final version of the code:

struct Contact: Decodable {
    let id: String
    @NestedDecodable<String, AddressCodingKeys>
    let address: String
    @NestedDecodable<String, NameCodingKeys>
    let name: String
    
    private let user: Unit
    
    enum AddressCodingKeys: String, CodingKey, CaseIterable {
        case user, details, address
    }
    
    enum NameCodingKeys: String, CodingKey, CaseIterable {
        case user, details, name
    }
}

struct NestedDecodable<T, Keys: CodingKey & CaseIterable>: Decodable {
    let wrappedValue: T
    init(wrappedValue: T) {
        self.wrappedValue = wrappedValue
    }
}

extension KeyedDecodingContainer {
    func decode<T, NestedKeys>(_: NestedDecodable<T, NestedKeys>.Type, forKey key: Key) throws -> NestedDecodable<T, NestedKeys> {
        guard NestedKeys.allCases.isEmpty == false else { throw ... }
        
        let wrappedValue = try containerForNestedKey().decode(T.self, forKey: NestedKeys.lastCase!)
        return NestedDecodable(wrappedValue: wrappedValue)
    }
    
    private func containerForNestedKey<K: CodingKey & CaseIterable>() throws -> KeyedDecodingContainer<K> {
        guard let rootKey = Key(stringValue: K.allCases.first!.stringValue) else { throw ... }
        
        var container = try self.nestedContainer(keyedBy: K.self, forKey: rootKey)
        if K.allCases.count > 1 {
            try K.allCases.dropFirst().dropLast().forEach { (key) in
                container = try container.nestedContainer(keyedBy: K.self, forKey: key)
            }
        }
        return container
    }
}

extension CaseIterable {
    static var lastCase: Self? {
        guard allCases.isEmpty == false else { return nil }
        let lastIndex = allCases.index(allCases.endIndex, offsetBy: -1)
        return allCases[lastIndex]
    }
}

struct Unit: Decodable {
    init() {}
    init(from decoder: Decoder) {}
}

Conclusion

Note that if we have just one nested property per root key we still can use the first version of the code. On the other hand we then will need to define all our keys manually just to provide few custom values, so if there are a lot of properties and just a few nested properties it might be easier to use the second approach. Then we will only need to add Unit properties for our root keys. Unfortunately it's not a completely safe solution as we can still make a typo in the name of this property and even in cases for nested keys and it will be possible to catch this only at runtime. But on the other hand Codable is inherently unsafe as we still can have a mismatch between JSON keys and properties names. So this seems like an acceptable nuance.

As an excercise you can now try to implement Encodable and Codable for encoding nested values. Or you can go and see the full code that supports both encoding and decoding here.

git rebase vs. git rebase --onto

Sun, 10 Nov 2019 00:00:00 GMT

Recently we were discussing in our team how to approach having fixes for bugs discovered during release both in release and the trunk branch to ensure we don't have to deal with large merges and possible conflicts in the release branch when we are done with a release and immediately benefit from those fixes on the trunk while we keep working on it. We figured there are two pretty-much similar options: either we cherry-pick commits from trunk to release branch or we cherry-pick from release branch to trunk. As our trunk and release branches are configured as protected on GitHub, we can't just cherry-pick fixes and push them to the target branch. We would need to create a new branch based on the head of the target branch (or reset branch with a fix to reuse it), cherry-pick required commits to it and only then push and create a PR. This works but cherry-picking more than a few commits one by one (or even using range of commits) seems like an extra and error-prone work. Instead we could rebase. That's when I've learned about git rebase --onto from Michael Brown. Let's see how it is different from more commonly used git rebase.

Let's say we have a following git tree:

$ git log --graph --oneline --all --pretty=format:'%s%d'
*   Merge branch 'fix' into release (release)
|\  
| * E (HEAD -> fix)
|/  
* D
* C
| * F (master)
|/  
* B
* A

Here we have a master branch where we continue development while we are at the same time working on a release and we have a fix branch with a fix (commit E) that we already merged into release branch.

Now we want to bring this fix from commit E from release to master. If we try git rebase master from fix branch we will have the following result:

$ git rebase master
First, rewinding head to replay your work on top of it...
Applying: C
Applying: D
Applying: E
$ git log --graph --oneline --all --pretty=format:'%s%d'
* E (HEAD -> fix)
* D
* C
* F (master)
| *   Merge branch 'fix' into release (release)
| |\  
| | * E
| |/  
| * D
| * C
|/  
* B
* A

As we see rebase took all the commits in the fix branch that are not present in master and replayed them on master though we only wanted to have a single commit E.

Now when we instead do git rebase --onto master HEAD~ we get what we want:

$ git rebase --onto master HEAD~
First, rewinding head to replay your work on top of it...
Applying: E
$ git log --graph --oneline --all --pretty=format:'%s%d'
* E (HEAD -> fix)
* F (master)
| *   Merge branch 'fix' into release (release)
| |\  
| | * E
| |/  
| * D
| * C
|/  
* B
* A

We can see that the difference between git rebase and git rebase --onto is that the former changes the base of a whole branch, meaning that it will find at what point current branch diverged from the target branch and will replay all the commits from this point on the new target branch, when the later changes the base of a commit by replacing its old base with a new base. In our case, as we want just a single commit from the fix branch we need to change the base of this commit, which is HEAD~ with a new base, which is master.

Another option would be to use interactive rebase and manually remove commits that we don't need, but similarly to cherry-picking this can be a lot of error-prone work if our release branch contains a lot of other commits.

That's it. Next time you rebase, remember that rebase --onto can be a better option. And if you want to learn about a few more complicated use cases read this article.

Making Slack, CircleCI and Fastlane work together

Sat, 08 Jun 2019 14:00:48 GMT

Nowadays Slack, some kind of CI and often Fastlane are default tools in a toolset of iOS developers. These tools serve their own purposes well, but wouldn't they do it better when they all work together? In this tutorial, I'll describe how to connect Slack with CircleCI and Fastlane. I'll be using CircleCI as an example but it's pretty much the same with any modern CI solution. As a bonus, we will do that in Swift using Vapor 3.0. So this tutorial can be as well an introduction to Swift on the server with Vapor framework.

Running Fastlane on CI

I touched in depth the details of configuring CircleCI in a dynamic way so that you can reuse as much configuration as you can without repeating common steps in each job, so I won't go into details here and will just highlight the main ideas.

While CircleCI support for triggering workflows with API calls is still very limited we will use a build job. As it's not run as a part of a workflow we will need to define a job that would run all the required steps like checkout, bundle_install, etc. To be able to reuse those steps in other jobs we will define them using YAML aliases (I described this approach here, if you already using CircleCI 2.1 you probably won't need this):

references:
    - &fastlane
            run:
                name: Fastlane
                command: |
                    if [[$CIRCLE_JOB == fastlane]] ; then
                        if [[-n "${FASTLANE}"]]; then
                eval "bundle exec fastlane ${FASTLANE} ${OPTIONS}"
            fi

    - &all_steps
            steps:
                - checkout
                - *brew
                - *restore_gems_cache
                - *bundle_install
                - *save_gems_cache
                - *restore_cocoapods_cache
                - *pod_install
                - *save_cocoapods_cache
                - *fastlane
                - *store_fastlane_output

jobs:
    fastlane:
        <<: *container_config
        <<: *all_steps

Alias fastlane defines a step that checks for environment variable CIRCLE_JOB to check if this step is running within a job that was triggered with an API call (it will be the first job defined in the jobs list). Then we check if FASTLANE and OPTIONS environment variables are defined and use them in a call to fastlane.

CircleCI service

To trigger such job and run a specific lane on CircleCI we need to make a request to the CircleCI API. For that, we create a service type responsible for interacting with CircleCI API.

struct CircleCIService: Service {
    private let baseURL = URL(string: "https://circleci.com")!
    private let headers: HTTPHeaders = [
        "Content-Type": "application/json",
        "Accept": "application/json"
    ]

    let token: String
    let project: String
}

Conforming to Service protocol defined in Vapor is not required and in fact, it does not have any requirements, but doing so will allow us to register this type in Vapors DI container which can become handy at some point later.

To work with CircleCI API we'll need a token that you can create on its dashboard and a project name.

To trigger a job that would run a specific lane we need to make CircleCI aware of this lane name and its options. This is done by sending build_parameters property in the API request body. This key expects strings key-value pairs which will be made accessible to CircleCI as environment variables.

{
    "build_parameters: {
        "FASTLANE": "test",
        "OPTIONS": "branch:master"
    }
}

If the API call successfully triggered a job the response will contain a build_url parameter with a link to the job's dashboard and a branch on which it is running. To work with these parameters we create request and response types:

extension CircleCIService {
    struct BuildRequest: Content {
        let buildParameters: [String: String]

        enum CodingKeys: String, CodingKey {
            case buildParameters = "build_parameters"
        }
    }

    public struct BuildResponse: Content {
        public let branch: String
        public let buildURL: String

        enum CodingKeys: String, CodingKey {
            case branch
            case buildURL = "build_url"
        }
    }
}

Using Content protocol defined in Vapor is not strictly necessary here - Codable will work just fine, but it makes it slightly easier to encode/decode data in the Vapor environment.

Now we can actually implement the API call:

extension CircleCIService {
    public func run(
        parameters: [String: String],
        branch: String,
        on request: Request
    ) throws -> Future<BuildResponse> {
        let url = URL(
            string: "/api/v1.1/project/github/\(project)/tree/\(branch)?circle-token=\(token)",
            relativeTo: baseURL
        )!
        let request = BuildRequest(buildParameters: parameters)
        return try request.client().post(url, headers: headers) {
            try $0.content.encode(request)
        }
    }
}

Slack service

To communicate with Slack we will use slash commands. To implement them we need first to create a Slack app and register a slash command in it. To invoke it we will need to send a Slack message that would like like /fastlane test branch:master, where fastlane is the name of the command (slash commands are always prefixed with /) and the rest is the text of the command that our Vapor app will parse to extract the name of the lane (in this case test) and its options (in this case branch:master).

When it's done we need to implement the endpoint in our Vapor app that will be called by Slack when someone triggers this slash command. The request made by Slack to this endpoint will contain some metadata in its body that contains the text of the command itself and some additional data, like the channel name where the command was invoked, the security token and response URL (more details about this later).

struct SlackCommandMetadata: Content {
    let token: String
    let channelName: String
    let text: String
    let responseURL: String

    enum CodingKeys: String, CodingKey {
        case token
        case channelName = "channel_name"
        case text
        case responseURL = "response_url"
    }
}

After the request is sent to our app by Slack it will expect the response. It should contain a text and flag that would instruct Slack to make the response visible either only to the user who invoked the slash command (that's called "ephemeral" response) or to everyone in the channel where the command was invoked.

struct SlackResponse: Content {
    let text: String
    let visibility: Visibility

    enum Visibility: String, Content {
        case user = "ephemeral"
        case channel = "in_channel"
    }

    enum CodingKeys: String, CodingKey {
        case text
        case visibility = "response_type"
    }
}

This response can be sent to Slack right after the command was processed as a response to the incoming HTTP request or later using responseURL. This is helpful because Slack has a 3 seconds timeout for slash commands responses. We could just send some generic response right away, i.e. Ok, will trigger CircleCI job now, but it will be more useful if this response would contain a URL to the triggered job. Sometimes CircleCI takes a bit longer to trigger the job and we'll need to wait for it to return the response with a job URL so we will do that by sending this data to the responseURL when a request to CircleCI API returns it.

extension Future where T == SlackResponse {
    func replyLater(
        withImmediateResponse immediateResponse: SlackResponse,
        responseURL: String,
        on request: Request
    ) -> Future<SlackResponse> {
        _ = self
            .mapIfError { SlackResponse($0.localizedDescription) }
            .flatMap { response in
                try request.client()
                    .post(responseURL) {
                        try $0.content.encode(response)
                    }
        }

        return request.eventLoop.future(immediateResponse)
    }
}

Now to be able to handle a slash command in our app we need to describe it in code. For that we will introduce a SlackCommand type responsible for parsing the incoming request, triggering CircleCI service and sending results back to Slack, and SlackService responsible for handling a command on a high level:

struct SlackCommand {
    let name: String
    let help: String
    let run: (SlackCommandMetadata, Request) throws -> Future<SlackResponse>
}

struct SlackService {
    let token: String

    func handle(command: SlackCommand, on request: Request) throws -> Future<Response> {
        return try request.content
            .decode(SlackCommandMetadata.self)
            .flatMap { [token] metadata in
                guard metadata.token == token else {
                    throw Error.invalidToken
                }
                
                if metadata.text == "help" {
                    return request.future(SlackResponse(command.help))
                } else {
                    return try command.run(metadata, request)
                }
            }
            .mapIfError { SlackResponse($0.localizedDescription) }
            .encode(for: request)
    }
}
        
extension SlackService {
    enum Error: Swift.Error {
        case invalidToken
        case missingParameter(key: String)
        case invalidParameter(key: String, value: String, expected: String)
    }
}

First SlackService extracts the command metadata from the incoming request and verifies its token (Slack docs say that it's a deprecated way of verifying requests made by Slack but its fine for our purposes for now). Then if the request was to show the command usage instructions (i.e. /fastlane help) we return these instructions in the response. Otherwise, we trigger the command using its run closure.

Now we have everything ready to implement the actual command:

extension SlackCommand {
    static let fastlane = { (ci: CircleCIService) in
        SlackCommand(
            name: "fastlane",
            help: "Invokes specified lane on specified branch...",
            run: { metadata, request in
                try runLane(
                    metadata: metadata,
                    ci: ci,
                    on: request
                )
        })
    }

    private static func runLane(
        metadata: SlackCommandMetadata,
        ci: CircleCIService,
        on request: Request
    ) throws -> Future<SlackResponse> {
        let components = metadata.text.components(separatedBy: " ")
        let lane = components[0]
        let options = components.dropFirst().joined(separator: " ")
        let branch = components.dropFirst()
            .first { $0.hasPrefix("branch:") }?
            .dropFirst("branch:".count)
        let parameters = ["FASTLANE": lane, "OPTIONS": options]

        return try ci
            .run(
                parameters: parameters,
                branch: branch ?? "master",
                on: request
            )
            .map { (response: CircleCIService.BuildResponse) in
                SlackResponse("""
                    🚀 Triggered `\(lane)` on the `\(response.branch)` branch.
                    \(response.buildURL)
                    """,
                    visibility: .channel
                )
            }
            .replyLater(
                withImmediateResponse: SlackResponse("👍"),
                responseURL: metadata.responseURL,
                on: request
            )
    }
}

Our command first performs some trivial string parsing to extract a lane name, its options, and a branch name and then uses that in a call to CircleCI service. When this call completes we convert its response to the Slack message that contains the job URL and we send it back to the Slack as a delayed response.

To connect all these pieces together we now need to register a route in our Vapor app in the routes.swift file :

public func routes(
    router: Router,
    slack: SlackService,
    commands: [SlackCommand]
) throws {
    commands.forEach { command in
        router.post(command.name) { req -> Future<Response> in
            do {
                return try slack.handle(command: command, on: req)
            } catch {
                return try SlackResponse(error.localizedDescription)
                    .encode(for: req)
            }
        }
    }
}

and configure Slack and CircleCI services in the configure.swift file:

public func configure(_ config: inout Config, _ env: inout Environment, _ services: inout Services) throws {
    let slack = SlackService(
        token: Environment.get("SLACK_TOKEN")
    )

    let ci = CircleCIService(
        token: Environment.get("CIRCLECI_TOKEN")!,
        project: Environment.get("CIRCLECI_PROJECT")!
    )

    let router = EngineRouter.default()
    try routes(
        router: router, 
        slack: slack, 
        commands: [
            .fastlane(ci)
        ]
    )
    services.register(router, as: Router.self)
    ...
}

And we are done! If you want to test the app you need to set environment variables in the Xcode scheme and just run the app. It will run it on the localhost and you'll be able to send requests to it (I use Insomnia for that). Then deploy the app to the platform of your choice (we use Heroku for that), update the slash command with the actual URL of your app and enjoy!

Conclusion

In Babylon iOS team we use this integration dozen of times daily and it proved to be very useful. So we decided to share it with the community and to opensource our app! We call it Stevenson - the original app, written with Vapor 2.0, was called Steve - and you can find it on our GitHub. It contains the code for our app itself and a reusable framework that you can use in your own apps. If you use or built yourself similar Slack apps in your team we'll be happy to hear from you about how you use them!

Swift 5 string interpolation

Wed, 06 Feb 2019 19:30:00 GMT

Strings are everywhere. We all use strings everyday. In Swift String is a very powerful type. One of the features it had available since the beginning is the string interpolation. With it we can embed any Swift expression inside the string literal instead of concatenating strings manually.

let name = "iOS Astronauts"
"Hello, \(name)" // "Hello, iOS Astronauts"
"Hello, \(name.count)" // "Hello, 14"
"Hello, \({ name })" // "Hello, (Function)"
"Hello, \(Optional.some(name))" // "Hello, Optional("Ilya")"
"Hello, \(MyStruct())" // "Hello, MyStruct()"

But you'll say, we all already know that and there is nothing really exciting about that. But today let's see how string interpolation works exactly.

For that standard library defines a protocol ExpressibleByStringInterpolation. This type was deprecated in Swift 3 so its details are now even stripped out of generated interface of standard library that you'll see in the Xcode, but we can find a cached version on swiftdoc.org¹. There you'll see that there are two constructors required by this protocol.

protocol ExpressibleByStringInterpolation {

    init(stringInterpolation strings: Self...)
    
    init<T>(stringInterpolationSegment expr: T)

}

We can also find there some details about how these constructors are being invoked.

String interpolation is a multiple-step initialization process. When you use string interpolation, the following steps occur:

1. The string literal is broken into pieces. Each segment of the string literal before , between , and after any included expressions, along with the individual expressions themselves, are passed to the init(stringInterpolationSegment:) initializer.

2. The results of those calls are passed to the init(stringInterpolation:) initializer in the order in which they appear in the string literal.

So essentially string interpolation is just a syntactic sugar that at compile type converts expression like this:

"hello \(name)!"

into a call like this²:

String(stringInterpolation:
    String(stringInterpolationSegment: "hello "),
    String(stringInterpolationSegment: name),
    String(stringInterpolationSegment: "!")
)

If we go through this generated code step by step then we see that first a string will be created with hello string, then another string will be created with a name value, and then another with ! and only then all these strings will be passed as an array into the final constructor to create a final string.

What now?

Cool. But what now? Well, knowing that we can now make our own types conform to this procotol.

Let's imagine we have a blog and we want to write our blog posts in Swift. Of course its not possible straight away as Swift is not a markup language and modern browsers down't understand it. But what if we convert our Swift code into the format that they can understand? For example Markdown or HTML?

That we can do. What we want to achieve is to be able to write something like this:

let blogPost: Markup = "..."

let markdow = Markdown(blogPost)

let html = HTML(blogPost)

Let's see how we can use string interpolation for that.

Demo 1 (playground)

So as you can see it's possible to use string interpolation for that but current design has few limitations (more details in the Swift Evolution proposal²):

Doesn't allow extra parameters
Accepts any type of values
Lost segment semantics
Memory overhead

Also the best variant of our implementation that we could achieve is not perfect as well.

We have to use free functions for each type of element to avoid specifying the type name.
Function calls add extra brackets which only increase noise.
Free functions pollute global namespace.

But at the same time our implementation is already pretty powerful. We could even workaround some design limitation using free functions to be able to use parameters with interpolation.

Over time people came up with interesting and more useful applications of that, for example for localization ³, which was possible even in Swift 2.

let color = "blue"
let num = 42

let localized: LocalizableString = 
    "Colorless \(color) ideas sleep furiously."
// format = NSLocalizedString("Colorless %@ ideas sleep furiously.", comment: "")
// String(format: format, arguments: ["blue"])


let localized: LocalizableString = 
    "\(num.formatted("%05d")) colorless green ideas sleep furiously.")
// format = NSLocalizedString("%05d colorless green ideas sleep furiously.", comment: "")
// String(format: format, arguments: [42])

Swift 5

As we saw earlier ExpressibleByStringInterpolation was deprecated in Swift 3 with a promiss to be redesigned in Swift 4. And finally this redesign happened in Swift 5. So let's see what have changed.

The basic concept is still the same, but the form has changed a bit. Now instead of aggregating interpolation segments in the type itself we need to use an associated type that should implement new StringInterpolationProtocol. The value of this type will be passsed into the new constructor init(stringInterpolation:) instead of array of individual segments. ²

public protocol ExpressibleByStringInterpolation : ExpressibleByStringLiteral {

    associatedtype StringInterpolation : StringInterpolationProtocol = DefaultStringInterpolation where Self.StringLiteralType == Self.StringInterpolation.StringLiteralType

    init(stringInterpolation: Self.StringInterpolation)
}

This associated type needs to implement a new constructor init(literalCapacity: Int, interpolationCount: Int) that accepts the combined size of all literal segments and the number of interpolation segments. Then it needs to implement the new func appendLiteral(_: StringLiteralType) method that will be called with each string literal segment.And then we can define our own func appendInterpolation(...) methods for any other type of segment we want to support. ²

public protocol StringInterpolationProtocol {
    associatedtype StringLiteralType : _ExpressibleByBuiltinStringLiteral

    init(literalCapacity: Int, interpolationCount: Int)

    mutating func appendLiteral(_ literal: Self.StringLiteralType)

    mutating func appendInterpolation(...)
}

These appendInterpolation methods can have any signature, they can accept any number of arguments, labeled or not, they can even throw and use generics, but they shouldn't return any value, or at least should be annotated with @discardableResult (on practice this is not enforced if there is any other appendInterpolation method that satisfies requirements) and they don't support trailing closures. There must be at least one appendInterpolation method satisfying these requirements.

func appendInterpolation(_ literal: String) { ... }

func appendInterpolation(
    number: NSNumber, 
    formatter: NSNumberFormatter
) { ... }

func appendInterpolation<T: Encodable>(
    js: T, 
    encoder: JSONEncoder = JSONEncoder()
) throws { ... }

At compile time interpolation will be restricted to these methods only, which allows to restrict types of values that can be interpolated instead of allowing any types of values as in the current design.

We now also have a much better compiler support that will fail to compile if you use wrong types or wrong parameter names, though code completion does not quite work yet.

"\(js: [String: String](), encoder: JSONEncoder())" ✅

"\(js: [String: Any](), encoder: JSONEncoder())" 🛑

"\(js: [String: String](), encode: JSONEncoder())" 🛑

The code generated by the compiler changed a bit as well, so instead of code like this:

String(stringInterpolation:
    String(stringInterpolationSegment: "hello "),
    String(stringInterpolationSegment: name),
    String(stringInterpolationSegment: "!")
)

it will generate something that looks more like this^[2:4]:

String(stringInterpolation: {
    var temp = String.StringInterpolation(literalCapacity: 7, interpolationCount: 1)
    temp.appendLiteral("hello ")
    temp.appendInterpolation(name)
    temp.appendLiteral("!")
    return temp
}())

If we go through the process step by step again then we see that first the insteance of the associated interpolation type will be created, then the first literal segment will be appended to it, then the first interpolated value with the name value will be appended, then the last literal segment will be appened and finally the value of interpolation type will be passed into the constructor.

Lets see now how our implementation will change with Swift 5.

Demo 2 (playground)

So with this new design we can simplify things we could do before, for example boolean expressions: ⁴

// old
"Cheese Sandwich \(isStarred ? "(*)" : "")"

// new
"Cheese Sandwich \(if: isStarred, "(*)")"

Or can even create our own DSLs, like for string formatting²⁵:

"The price is $\(cost, format: "%.2f")"

"\(42, radix: .binary)"

or attributed strings⁶:

"Hello, \("iOS Astronauts", .color(.red))"

or such special cases as GitHub Msarkdown: ⁷

"See \(issue: 123)"

We can even go a bit further and implemt our own template DSL: ⁸

let hello: Template = """
    \(if: greeting, 
        then: "Hello", 
        else: "Goodbye"
    ) \(for: names, do: { name, loop in 
        "\(loop.index + 1). \(name)"
    })
    """

Or a more type-safe version of string format: ⁸

let hello: StringFormatter<(String, Date)> = "Hello, \(.string). Today is \(.date)."

render(hello, "iOS Astronauts", Date()) ✅
render(hello, Date(), "iOS Astronauts") 🛑

Some of these things will surely make it into the standard library and many 3rd party implementations will popup on GitHub and I hope now you are excited as me about this small but great Swift feature and new opportunities it offers.

One more thing

There is also one small but very useful improvement in Swift 5 not directly related to string interpolation, but one that makes it even easier to use. Now you can use # to tell Swift that quotes and back slashes in your string are actually literals. With that when you want to use string interpolation you need to add the same number of # . With this you no longer need to use \ to escape characters, which is a big deal when dealing for example with regular expressions ⁹

// old
print("<a href=\"\(url)\" title=\"Apple Developer\">")

// new
print(#"<a href="\#(url)" title="Apple Developer">"#)

Implementing features with ReactiveFeedback

Wed, 07 Nov 2018 13:40:24 GMT

Some time ago there was an explosion of articles and talks in the iOS community about "unidirectional flow" architectures, inspired by Redux library from JavaScript. The dust has settled since then but as a result of this storm, we now have ReSwift and other implementations of this approach. Reactive programming adepts didn't stay away for long and came up with RxFeedback. At Babylon, we use ReactiveCocoa so we've built ReactiveFeedback. In this article, you'll see how we use it to build the whole features in our app, not just increment counters so there will be a lot of code (you can see the whole code in this gist).

One of the differences from what you will see in most of the tutorials about this approach is that we don't have a global application state. We simply don't need it as we build our app from a set of microfeatures, from a bootstrapping state when the user starts the app to the implementation of each and every application flow. Every feature has a clear "entry point" for the rest of the code to interact with it and has it's own state isolated from the rest of the app.

To demonstrate our approach we will build an interface that allows users to make a list of pharmacies where they prefer their medications to be delivered. This is a real feauture that I was working on recently. Here is how the final result will look like:

On the screen we are going to implement user will see an empty state placeholder when there are no previously saved pharmacies, will be able to add pharmacies from the map screen, delete previously added pharmacies and finally select a pharmacy for delivery, which will dismiss this screen.

As Redux in its essence is just a state machine we start with defining states and possible transitions between them. Apart from states and transitions, we will define "actions" - events that trigger state transitions, and "signals" - events sent out by the state machine to perform side effects i.e. presenting another screen.

We start with loading state, of course. In case of loading data, in this case, the list of pharmacies previously saved by the user, succeeds we go to loaded state, or otherwise in loading failed state from where we can go back to loading state using retry action.

From loaded state using add pharmacy action we go to searching state. During this transition, we send show map signal to display map user interface. When the user closes the map without selecting any pharmacy we go back to loaded state. When the user selects a pharmacy on the map we go to adding state. If adding pharmacy succeeds we go to loaded state with this pharmacy added, otherwise we go to failed state which immediately sends show error signal and goes back to loaded state.

Similarly to this when user deletes pharmacy we go to deleting state and if deleting succeeds we go to loaded state with this pharmacy deleted from the list, otherwise to failed state, send show error signal and go back to loaded state keeping this pharmacy in the list.

Finally, when the user selects pharmacy from the list we can either exit the flow and return selected pharmacy to the caller through dismissing state and dismiss signal, or we can display directions to the selected pharmacy which will send show map signal and then go to showing directions state. When the user closes the map we go back to loaded state.

Here is the final diagram. It looks a bit complicated but when you break it down into pieces like we just did it becomes pretty simple to understand.

Now let's implement it!

We start with bootstrapping feature using Xcode templates that we've created. This saves us from writing some boilerplate code and ensures that each implementation follows the same structure and naming conventions. Programming is a creative process but this creativity should be controlled in large teams.

Using the template we end up with few files each containing one type - builder, flow controller, view model, and renderer. Each of them serves its own single purpose. This break down is similar to what you might have seen in VIPER or other patterns. Let's go through these types one by one.

Builder

The builder is a main entry point to the feature. It defines and implements an external interface for the rest of the code to interact with the feature, i.e. here func make() -> UIViewController. There might be several of such entry points depending on a use case. Implementation of this interface takes care of creating and wiring together all other components - flow controller, view model, and renderer. The output is typically a view controller. As you can see nothing except view controller leaves the builder. This way we achieve a high level of isolation of the feature making it a black box for the rest of the code - nothing but what we pass as input parameters to make function (it's empty now but we will fill it soon) can affect the feature.

protocol PharmaciesListChildBuilders {}

struct PharmaciesListBuilder: PharmaciesListChildBuilders {
    init() {}

    func make() -> UIViewController {
        let viewModel = PharmaciesListViewModel()
        
        let viewController = BabylonBoxViewController(
            viewModel: viewModel,
            renderer: PharmaciesListRenderer.self,
            rendererConfig: PharmaciesListRenderer.Config()
        )
        
        let flowController = PharmaciesListFlowController(
            modal: viewController.modalFlow,
            builders: self
        )

        viewModel.routes
            .observe(on: UIScheduler())
            .observeValues(flowController.handle)

        return viewController
    }
}

Flow controller

You are probably familiar with this concept already. You might have heard about "coordinators" and "routers". The flow controller is a similar concept. Its responsibility is to implement navigation. For navigation, we use a concept of "flows" throughout our app. It serves us as an abstraction of different presentation styles, mostly modal and navigation, used to present view controllers. Method func handle(_: PharmaciesListViewModel.Route) implements the navigation logic and is an observer of the view model's routes signal. In this method, the flow controller decides what and how to present depending on the route value it receives from a view model.

final class PharmaciesListFlowController {
    private let presenting: Flow
    private let modal: Flow
    private let builders: PharmaciesListChildBuilders

    init(presenting: Flow,
            modal: Flow,
            builders: PharmaciesListChildBuilders) {
        self.presenting = presenting
        self.modal = modal
        self.builders = builders
    }

    func handle(_ route: PharmaciesListViewModel.Route) {
        switch route {

        }
    }
}

Renderer

As the name implies this type renders UI. It does it using Bento, our declarative UI framework. The way it works is similar to React. Instead of working with views directly we define a virtual representation of user interface as a tree-like structure. Similar to React this representation is a function of the state. When a new tree is created as a result of the state change the difference between the old and the new tree is calculated and the user interface is updated accordingly. As our app contains a lot of forms the main focus of Bento is table and collection views. In fact, even screens that don't look like forms, i.e. empty state screen that you could see on the video, are implemented using this approach. Almost every screen in our app is either table or collection view powered by Bento (or its predecessor).

typealias Sink<Action> = (Action) -> Void

struct PharmaciesListRenderer: BoxRenderer {
    private let config: Config
    private let observer: Sink<PharmaciesListViewModel.Action>
    
    struct Config {}

    init(observer: @escaping Sink<PharmaciesListViewModel.Action>, 
            config: Config) {
        self.config = config
        self.observer = observer
    }

    func render(state: PharmaciesListViewModel.State) -> Screen<SectionId, NodeId> {
        return Screen(box: .empty)
    }

}

extension PharmaciesListRenderer {
    
    enum SectionId: Hashable {
        case first
    }

    enum NodeId: Hashable {
        case first
    }
}

View model

This is a central piece of the puzzle that implements all the business logic and controls the state. You can imagine that it's a rather complex type so let's look at its pieces one by one. The main building blocks of every view model are state property, reducer function and routes signal. The state represents the state of our system, reducer is a function that based on the current state and incoming event produces a new state. And the routes is the signal observed by the flow controller so that it can perform navigation.

final class PharmaciesListViewModel: BoxViewModel {

    let state: Property<State>
    let routes: Signal<Route, NoError>

    private let (actions, actionsObserver) = Signal<Action, NoError>.pipe()

    init() {
        state = Property(
            initial: .initial,
            reduce: PharmaciesListViewModel.reduce,
            feedbacks: [
                PharmaciesListViewModel
                    .userActions(actions: actions)
            ]
        )
        
        routes = .empty
    }

    func send(action: PharmaciesListViewModel.Action) {
        actionsObserver.send(value: action)
    }

    private static func reduce(_ state: State, _ event: Event) -> State {
        switch event {
        default:
            return state
        }
    }

}

Now, remember the state diagram we designed in the beginning? The "state" from this diagram is, obviously, state property of a view model, routes is a "signal", i.e. "show map" or "dismiss", and reducer function is what implements transitions between states.

Let's look closer at the state property. As you can see it's not a regular ReactiveSwift Property. Apart from the initial value, it has a reduce and feedbacks parameters.

state = Property(
    initial: .initial,
    reduce: PharmaciesListViewModel.reduce,
    feedbacks: [
        PharmaciesListViewModel
            .userActions(actions: actions)
    ]
)

Under the hood ReactiveFeedback framework will create a state machine like system which will use reduce function to produce new states when new events occur, and feedbacks to perform side-effects on state changes which can result in new events and further state changes. This way it defines a "feedback loop" - every time the state changes (including when it is created with its initial value) the system will go through all the feedbacks, some of them will trigger side effects, i.e. an asynchronous network call, as a result of this side effect an event can be emitted which then will be passed to the reducer along with the current state and the reducer will either produce a new state or return the current state (effectively discarding the event) and the loop will start over. As a result of every state change, the state property current value will be updated. Now note that it's a Property, not a MutableProperty. This means that this property value can't be changed from outside. The only way to change it is through feedbacks and events. This way we make sure that nothing but the state machine itself can affect its state.

This may sound familiar to you if you like me had to study control theory as it uses the concept of feedbacks extensively. I was not very attentive student back in my university days so it took me some time to realize that similarity.

Now let's look at the feedback. We have only one for now and it's pretty simple. All that it does is transforms events caused by user interactions with UI into state machine events.

extension PharmaciesListViewModel {

    func send(action: PharmaciesListViewModel.Action) {
        actionsObserver.send(value: action)
    }

    fileprivate static func userActions(
        actions: Signal<Action, NoError>
    ) -> Feedback<State, Event> {
        return Feedback { scheduler, state -> Signal<Event, NoError> in
            return actions.map(Event.ui).observe(on: scheduler)
        }
    }

}

The func send(action:) function is passed to the renderer as observer parameter (it has a Sink typealias which is actually just a typealias of (Action) -> Void so it matches the signature of this function). The renderer then binds this observer with UIControl.Events of controls that it renders. Action type here represents a subset of state machine events that can be triggered by the user. For example, when the user taps a button it will produce the Event.ui(Action.buttonTapped) event.

The rest of the view model code created by the template contains definitions of State, Action, Event and Route types.

extension PharmaciesListViewModel {
    
    enum State {
        case initial
    }

    enum Event {
        case ui(Action)
    }

    enum Action {}

    enum Route {}

}

Let's start filling them in.

State

Here is how the states that we defined earlier can be represented.

indirect enum State: Equatable {
    case loading
    case loadingFailed(CoreError)
    case loaded([PharmacyDTO], CoreError?)
    case searching([PharmacyDTO])
    case showingDirections([PharmacyDTO], Place)
    case adding([PharmacyDTO], PharmacyDTO)
    case deleting([PharmacyDTO], Int)
    case dismissing(State, PharmacyDTO?)
}

All the states that are possible after the content is loaded contain the list of pharmacies. This is done so that we can pass it from one state to another when performing transitions. Sometimes we extract this kind of common associated values in a separate type Context, but here we have only this piece of data to carry on, so we don't really need it, though we could define it just as typealias Context = [PharmacyDTO].

You can see that we don't have a failed case that we had on the state diagram. Instead, we combine it with loaded state by adding optional error as its second associated value. This way we model two states using one enum case - optionality of error property allows using one case for two distinctive states, with and without error.

The last interesting detail here is the dismissing state. It has an optional PharmacyDTO which will contain a pharmacy user selected for delivery (the "output" of the feature) or nil if the user dismisses the screen without selecting anything, and state which is the state in which the screen was dismissed - it can be loading, loaded or loadingFailed, because in all these states we show a "Cancel" button that the user can press. Now, remember that we treat UI as a function of the state. Every time the state changes the renderer will be invoked to produce a new UI based on a new state. Then it will be invoked for the dismissing state and will need to return something. But when the screen is dismissing we don't want anything on it to change, so we need to create exactly the same UI tree that we returned for the previous state. So we bundle it within dismissing state to be able to render it.

Events and Actions

State transitions happen on events. Some events can happen due to side effects like network calls, and some can happen due to user interactions with UI elements. To make the distinction clearer we separate UI events into Actions type and use a single Event case for all of them, case ui(Action). We also allow a different behavior of the feature - in some flows we want to show directions to the selected pharmacy and in others we just return selected pharmacy. For that, we use Action.Selection enum.

enum Event: Equatable {
    case ui(Action)
    case loaded([PharmacyDTO])
    case failed(CoreError)
    case mapResponse(Place?)
    case added(PharmacyDTO)
    case deleted
}

enum Action: Equatable {
    case addPharmacy
    case deletePharmacy(Int)
    case select(Int, Selection)
    case retry
    case cancel

    enum Selection: Equatable {
        case dismiss
        case showDirections
    }
}

Reducer

Reducer is the central part of any view model. It is a function that defines all state transitions and considering a number of states and transitions we have you can guess it's pretty complex. To simplify it we will break it into pieces, handling events for each state in a separate function. This will leave us with pretty boilerplate implementation:

static func reduce(_ state: State, _ event: Event) -> State {
    switch state {
    case .loading:
        return reduceLoading(state: state, event: event)
    case let .loadingFailed(error):
        return reduceLoadingFailed(state: state, event: event, error: error)
    case let .loaded(pharmacies, error):
        return reduceLoaded(state: state, event: event, pharmacies: pharmacies, error: error)
    case let .adding(pharmacies, pharmacy):
        return reduceAdding(state: state, event: event, pharmacies: pharmacies, pharmacy: pharmacy)
    case let .deleting(pharmacies, index):
        return reduceDeleting(state: state, event: event, pharmacies: pharmacies, index: index)
    case let .searching(pharmacies):
        return reduceSearching(state: state, event: event, pharmacies: pharmacies)
    case let .showingDirections(pharmacies, place):
        return reduceShowingDirections(state: state, event: event, pharmacies: pharmacies, place: place)
    case .dismissing:
        return state
    }
}

The main logic is now broken down into small pieces that are much easier to digest. When loading we need to handle loading failure, success and cancelation events. All other events we ignore by returning the current state:

static func reduceLoading(state: State, event: Event) -> State {
    switch event {
    case let .failed(error):
            return .loadingFailed(error)
    case let .loaded(pharmacies):
            return .loaded(pharmacies, nil)
    case .ui(.cancel):
            return .dismissing(state, nil)
    default:
        return state
    }
}

When loading failed we only care about retry event and cancelation:

static func reduceLoadingFailed(
    state: State, 
    event: Event, 
    error: CoreError
) -> State {
    switch event {
    case .ui(.retry):
            return .loading
    case .ui(.cancel):
            return .dismissing(state, nil)
    default:
        return state
    }
}

Loaded state reducer is a bit more complex as it has more possible transitions, but in the end, it's also pretty straight-forward. When a pharmacy is selected we also need to check an action assoicated with selection to either show the map or dismiss the screen.

static func reduceLoaded(
    state: State, 
    event: Event, 
    pharmacies: [PharmacyDTO], 
    error: CoreError?
) -> State {
    switch event {
    case let .loaded(pharmacies):
        return .loaded(pharmacies, nil)
    case .ui(.addPharmacy):
        return .searching(pharmacies)
    case let .ui(.deletePharmacy(pharmacy)):
        return .deleting(pharmacies, pharmacy)
    case let .ui(.select(index, action)):
        switch action {
        case .dismiss:
            return .dismissing(state, pharmacies[index])
            case .showDirections:
            if let place = pharmacies[index].toPlace() {
                return .showingDirections(pharmacies, place)
            } else {
                return .loaded(pharmacies, nil)
            }
        }
        case .ui(.cancel):
        return .dismissing(state, nil)
    default: 
        return state
    }
}

adding and deleting states reducers are pretty similar and straight-forward as well. When a pharmacy is added we add it to the pharmacies list and return to loaded state. When a pharmacy is deleted we remove it from the pharmacies list and return to loaded state. In case of an error, we return loaded state with an error value.

static func reduceAdding(
    state: State, 
    event: Event, 
    pharmacies: [PharmacyDTO], 
    pharmacy: PharmacyDTO
) -> State {
    switch event {
    case let .didAdd(pharmacy):
        return .loaded(pharmacies + [pharmacy], nil)
    case let .didFail(error):
        return .loaded(pharmacies, error)
    default:
        return state
    }
}

static func reduceDeleting(
    state: State, 
    event: Event, 
    pharmacies: [PharmacyDTO], 
    index: Int
) -> State {
    switch event {
    case .didDelete:
        var pharmacies = pharmacies
        pharmacies.remove(at: index)
        return .loaded(pharmacies, nil)
    case let .didFail(error):
        return .loaded(pharmacies, error)
    default:
        return state
    }
}

When the user searches for a pharmacy on a map we only need to handle the event of selecting a place on the map. To avoid adding the same pharmacy multiple times we check if it is already on the list to decide if we should add it or ignore it.

static func reduceSearching(
    state: State, 
    event: Event, 
    pharmacies: [PharmacyDTO]
) -> State {
    switch event {
    case let .didSelectPlace(response):
        if case let .selected(place) = response,
            !pharmacies.contains(where: { 
                $0.reference == place.reference 
            }) {
            return .adding(pharmacies, PharmacyDTO(place))
        } else {
            return .loaded(pharmacies, nil)
        }
    default:
        return state
    }
}

Finally, when the map is presented to show directions to the pharmacy we are not actually interested in handling any specific events because the map, in this case, does not provide any return value, so we simply can return .loaded state on didLoad event that as you will see soon happens right after state changes to showingDirections. Alternatively, we could produce an Event when the map is dismissed and hande it here so that our system stays in the showingDirections state while the map is presented.

static func reduceShowingDirections(
    state: State, 
    event: Event, 
    pharmacies: [PharmacyDTO], 
    place: Place
) -> State {
    switch event {
    case let .didLoad(pharmacies):
        return .loaded(pharmacies, nil)
    default:
        return state
    }
}

Feedbacks

Now lets finally look at the most interesting yet simple part of the view model - feedbacks. You already saw one feedback that effectively maps UI actions into state changes. The rest of the feedbacks are handling all other events unrelated to UI interactions, mostly network calls responses. Typically each feedback has an effect only in a particular state. It is not something that is enforced by the ReactiveFeedback so on one event multiple feedbacks can be invoked and can result in multiple side-effects being triggered.

Let's start with a loading feedback. All that it does is starting a network call to fetch a list of saved pharmacies and map its result into Event.

static func whenLoading(
    businessController: PharmaciesBusinessControllerProtocol
) -> Feedback<State, Event> {
    return Feedback { state -> SignalProducer<Event, NoError> in
        guard case .loading = state else { return .empty }

        return businessController.fetch()
            .map(Event.didLoad)
            .replaceError(Event.didFail)
    }
}

Similarly feedbacks for adding and deleting pharmacy trigger network calls and map their results into Event.

static func whenAdding(
    businessController: PharmaciesBusinessControllerProtocol
) -> Feedback<State, Event> {
    return Feedback { state -> SignalProducer<Event, NoError> in
        guard case let .adding(_, pharmacy) = state,
            let reference = pharmacy.reference else { return .empty }

        return businessController.add(pharmacy: AddPharmacyRequest(reference: reference))
            .map(Event.didAdd)
            .replaceError(Event.didFail)
    }
}

static func whenDeleting(
    businessController: PharmaciesBusinessControllerProtocol
) -> Feedback<State, Event> {
    return Feedback { state -> SignalProducer<Event, NoError> in
        guard case let .deleting(pharmacies, index) = state else { return .empty }

        return businessController.delete(pharmacy: pharmacies[index])
            .map { _ in Event.didDelete }
            .replaceError(Event.didFail)
    }
}

When showing directions or when an error happens (i.e. network request fails) we only need to present a map or an alert with an error message. This only involves navigation logic and if you remember for that we use the routes signal. This way these feedbacks only need to restore the system to the loaded state what they can do by producing .didLoad event.

static func whenFailed() -> Feedback<State, Event> {
    return Feedback { state -> SignalProducer<Event, NoError> in
        guard case let .loaded(pharmacies, _?) = state else { return .empty }

        return .value(.didLoad(pharmacies))
    }
}

static func whenShowingDirections() -> Feedback<State, Event> {
    return Feedback { state -> SignalProducer<Event, NoError> in
        guard case let .showingDirections(pharmacies, _) = state else { return .empty }

        return .value(.didLoad(pharmacies))
    }
}

Routes

The last piece of the view model is routes signal. It is observed by the flow controller to perform navigation when a new route is sent by the view model and effectively serves as an entry point into other features.

routes = state.signal.skipRepeats().filterMap { state in
    switch state {
    case let .loaded(_, error?):
        return .showAlert(.make(error: error))
    case .searching:
        return .showMap(mapResponsesObserver.send(value:))
    case let .showingDirections(_, place):
        return .showDirections(place)
    case let .dismissing(_, selectedPharmacy):
        return .dismiss {
            selectedPharmacy.map { pharmacySelectionObserver?.send(value: $0) }
        }
    default:
        return nil
    }
}

As you can see routes signal is directly derived from state property. We could also derive it from actions signal. In this case, we wouldn't need some states and corresponding feedbacks like showingDirections and instead will observe action select(index, .showDirections). But this breaks the property of our system that the state is the single source of truth of everything happening in it. Also having these "transient" states helps to have a more complete picture of the system.

With this we can now implement the flow controller that all fits into one function:

func handle(_ route: PharmaciesViewModel.Route) {
    switch route {
    case let .showMap(response):
        BabylonNavigationController { [presenting = self.modal] _, modal in
            builders.makeMap(response: response, modal: modal, presenting: presenting)
        } |> modal.present
    case let .showDirections(place):
        builders.makeDirectionsMap(for: place, modal: modal, presenting: presenting)
            |> presenting.present
    case let .showAlert(error):
        UIAlertController.make(error: error)
            |> modal.present
    case let .dismiss(completion):
        completion
            |> presenting.dismiss
    }
}

Rendering

To wrap up let's see a high-level implementation of the renderer. It is a very simple, and pure, function that based on state value returns UI tree to be rendered by Bento framework. In most of the states, we are rendering a list of pharmacies. In the .loading or .loadingFailed states or when no pharmacies are saved we are rendering screen in an "empty" state, which can render a spinner or a placeholder with an icon and an action button to reload the list or add the first pharmacy.

func render(state: PharmaciesViewModel.State) -> Screen<SectionId, RowId> {
    switch state {
    case .loading:
        return render(emptyState: .loading)
    case .loadingFailed:
        return render(emptyState: .error)
    case let .loaded(pharmacies, _), 
            let .searching(pharmacies), 
            let .showingDirections(pharmacies, _):
        if pharmacies.isEmpty {
            return render(emptyState: .empty)
        } else {
            return render(pharmacies: pharmacies)
        }
    case let .adding(pharmacies, pharamacy):
        return render(pharmacies: pharmacies + [pharamacy])
    case .deleting(var pharmacies, let index):
        pharmacies.remove(at: index)
        return render(pharmacies: pharmacies)
    case let .dismissing(state, _):
        return render(state: state)
    }
}

I will not go into more implementation details as it deserves a separate post, but if you are curious you can look at the Bento example or final gist.

Wrap up

Now you should have a picture of architecture we use to develop features. You can draw some lines between it and the VIPER in how we break responsibilities between types. One of the benefits of such separation is that extracting navigation and rendering logic from a view model allows us to separate it from UIKit related side-effects which makes it easier to unit test. Separating rendering logic also allows us to test it easily (using FBSnapshotTest) without caring about mocking network calls performed by the view model.

Using ReactiveFeedback to model the state machine which is the main driver of the view model helps us to control its side-effects which is also easy to test either by testing reducer function directly or by testing view model as a black box asserting how the state changes when events happen. It also bridges the Redux approach with the reactive programming that is in the heart of our development culture.

By continuously applying this pattern across the app, with the help of Xcode templates, we make it easier for us to understand parts of it we didn't work on before or start a development of a new feature, even though some implementation details may differ. This is crucial to ensure maintainability of the code base that is actively worked on by more than 10 people at the same time, no matter what pattern you choose for that.

iOS UI Automation Tests at Babylon

Mon, 08 Oct 2018 09:00:00 GMT

This article is based on the talk I gave at iOS Astronauts meetup that was held on 03.10.2018 at Babylon. You can check out this talk and other videos as well as join the meetup group here.

Probably every iOS developer nowadays knows what UI tests are and how to write them. Sometimes we don't even have to write them ourselves because Xcode can do that for us. Of course, the result is far from ideal and probably you don't want to keep it as it is in your tests, but point is that it's not hard to write a code that will tap a button on a screen.

What's hard is the issues you start to face when you write more and more of such tests.

In this post, I'll be highlighting some of the issues we face with UI tests at Babylon. Mainly they are related to:

unexpected tests failures
tests performance
the complexity of some scenarios

Content stability

One of the main reasons for our UI tests suite failures is a frequent change of content that we don't control (of course after our own changes to the codebase). The best example of that is our chatbot. It works the way that you can ask our chatbot any question and in return, it asks you to answer some more questions so that it can give you better results. Some of these questions will expect you to choose an answer from a set of provided options or give a free-form answer. Depending on your answer chatbot may ask a different question next time. These flows are defined by the backend AI service and are absolutely opaque for the app - with rare exception we don't know what is the difference between one or another option. And from time to time these flows change and for example instead of answer option that says "OK" we receive "SURE". And UI tests start to fail because they can't find a button they expect.

In some cases, we could probably use unique identifiers of the answer options as accessibility identifiers. And it would work for such simple cases where semantics doesn't change. But as we don't control these flows we have no knowledge about the nature of these changes and we might as well receive completely new elements that we know nothing about. Or the flow might change and instead of asking question A and then question B the chatbot will first ask question B, or even C and only then question A. That makes testing these flows on the client side particularly unstable.

External system actions required

Another issue is that some of the user scenarios in our app require not just user interaction but also GP interaction in a system we call "GP Portal". For example, when a user books an appointment with a GP it will only start when GP initiates it and the app receives a call. The same with completing an appointment. It actually does not complete automatically when you or GP hang up. After that GP may have to do few things on the GP Portal and only when they are ready they complete the appointment. That's like your Uber driver completes the ride. Only then the app receives a push notification for example that you have a prescription or asking you to rate the appointment. So as you can imagine these scenarios are pretty cumbersome to test manually as well as hard to automate.

Network stability

Another very common reason for tests to fail is the network stability. It's not just about how good is a Wi-Fi signal in the room with your test devices, it's about everything that can happen when you are doing network calls, 500 responses, timeouts, connection drops and so on. And when your tests are running in the cloud, like ours, you have even less control of that.
Sometime people go extreme and build racks for test devices with their own WiFi signals and then have to add electromagnetic enclosures to isolate them to avoid networking issues.

Performance

This brings us to another issue which is related to the performance of tests. Not just a device or simulator performance that also might vary and be unpredictable, but also the need to perform extra steps to reach a point of interest in the app. For example, every test needs to start from registering a new user because we want our tests to be isolated from each other. Then all tests related to appointments flows need to schedule an appointment, add a payment method, confirm payment and so on. This leads to a lot of tests going through the same steps over and over again.

And then we face a dilemma - either we can group such scenarios together and have fewer tests but make them larger by asserting more expectations in each test which will make each test longer to run but will speed up whole test suite, or we could make tests smaller, more focused but run the whole tests suite for a much longer time because of more repeated steps.

How do we solve that?

Now when we know the problems let's look at their solutions that we try to apply. Some of these things we are already doing, some of them we plan to do in a near future, some are still just ideas.

Basically, our strategy is built around an approach that can be summarised as "control the world". By the world, in this case, we mean everything outside the app, which is the network, and everything inside the app, which is the app initial state (the runtime state is already controlled by the test)

What does it mean to control the network? It means that our test instead of some backend services have full control over what data our application receives when it makes network calls.

How can we do that? This is a very trivial thing to do in unit tests, there are few well-known ways of doing that, from using dependency injection and network mocks, to using custom URL protocols to serve stubbed data. It's simple because unit tests and the code they test are running in the same process, so they can access the same network stack, modify it or completely replace it.

But when we are running UI test we have two processes running in parallel - application process and test runner process - with two separate network stacks. That makes it a bit trickier to affect the network stack of the app from the test runner process.

There are few ways to achieve that though. One is from the inside of the application process, and another is from the inside of the test runner process.

Control the world from the inside of the app

When we are doing that from the inside of the app we do it the same way as in unit tests, either by injecting mock network stack or using custom URL protocol to serve stubbed data. The most common is to use a URL protocol. The idea is that the URL protocol allows you to intercept all network requests and pass back stubbed data. There are several open-source libraries that make this very straightforward but when it comes to using them with UI tests there are few issues.

First, you need to integrate some test related code into the app code. The problem is not that you have to do that, most likely you'll need to do that anyway for one or another reason. The problem is in the amount of that code and how well it is isolated from the rest of the app and what it will allow you to do. And even if it is isolated - it's still in the different target than tests.

Next, you will have to somehow instruct the app what stubs to use. This is usually done via launch arguments as it is the only way that we have in UI tests to alter the app behavior. This approach is not very flexible when it comes to passing through something more than a few strings or JSON objects, but it might be enough just to pass the name of the test that is currently running so that the app can pick up the correct network stubs stored in a bundle.

let body = [ "user": "Kyle" ]
stub(uri("/{user}/{repository}"), json(body))

straightforward ✅
integrates into application code ❌
not very flexible ❌

Control the world from the inside the test runner

Another way of controlling the network is from inside the test process. For that instead of making requests to a backend service, the app makes requests to a local web server that is running on the localhost and is controlled by the test code. The test then decides what to do with the request - return some stabbed data, redirect it to the real service or maybe return an error. Possibilities are basically endless and can satisfy all the needs that you can possibly imagine, unlike the previous approach where it's harder to synchronize between the app and the test. You can use it to simply log all network requests and responses to attach them to tests results to improve debugging experience. Or you can use these logs as snapshots and run your tests against these snapshots instead of the real network. Or you can even implement a mock backend and never talk to the real services.

This approach also requires some integration in the app, but most likely you already have everything that you need for that. There is more work to be done on the test target side though, but its much better isolated from the app. That's another benefit of this approach - most of the code will be in the tests target, inlined into your tests so you will not need to jump between code in the app and tests.

override func setUp() {
  server.start()
  server.router.notFoundResponse = InterceptResponse()
}

override func tearDown() {
  server.stop()
}

harder to setup ❌
integrates into the test runner ✅
very flexible ✅

Local server setup - in the app

So what we need to do to make our tests work with the local web server? First of all our app needs to be able to switch to a localhost. If your app supports switching between backend environments like develop, staging, production then you simply need to add one more environment for localhost. If not - you need to implement that but it's pretty trivial and anyway is a good thing to have.

In our case, it required a little bit more work because our app uses multiple backend services which are located on different hosts, so we can't just replace one host with a localhost, we have to somehow keep the original host of the request. We do that by putting it in the first path component of the request. Then in the test, we can extract it and make a real request to this host if we need.

public static func local(_ env: Environment, host: String) -> Environment {
  return Environment(
    name: "localhost",
    endpoints: Environment.Endpoints(
      app1BaseURL: URL(string: "http://\(host)/\(env.endpoints.app1BaseURL.host!)")!,
                             // http://localhost:8080/dev.api1.com
      app2BaseURL: URL(string: "http://\(host)/\(env.endpoints.app2BaseURL.host!)")!,
                             // http://localhost:8080/dev.api2.com
      webAppURL: env.endpoints.webAppURL
    )
  )
}

Second, and the last, if you use TSL you will need to enable local networking for the app, which is done by adding a single key in Info.plist file.

if [ "${CONFIGURATION}" == "Debug" ]; then
    /usr/libexec/PlistBuddy -c "Set NSAppTransportSecurity:NSAllowsLocalNetworking YES" "${TARGET_BUILD_DIR}/${INFOPLIST_PATH}"
fi

Local server setup - in the test

On the test runner side, you need to do a bit more. First of all, you need a web server implementation of course. But that's not something you'll have to write yourself, there are open-source solutions that have been available for a while, like GCDWebServer, swifter, Kitura, or if you want you can implement your own based on SwiftNIO.

What implementation you use does not really matter, some of them are easier to set up than others (for example I couldn't go through Kitura HelloWorld tutorial) but they basically work the same way. We currently use a small web framework called Ambassador that works pretty well even though it is relatively unknown and gives us everything we need for testing purposes and nothing extra that we don't need.

class MockServer {
  func start() {}
  func stop() {}
  func setupRoutes() {}
  func startRecording(testName: String) {}
}

class MyTest: XCTestCase {
  override func setUp() {
    server.start()
    if runsAgainstMockServer {
      // local server mocks backend
      server.setupRoutes()
    } else server.config.recordingMode != nil {
      // "snapshot" tests
      server.startRecording(testName: testName)
    } else {
      // local server as a proxy
      server.router.notFoundResponse = InterceptResponse()
    }
  }
  
  override func tearDown() {
    server.stop()
  }
}

Next, you need to intercept the requests from the app using this web server. The web frameworks already provide all functionality for that, usually through the concept known as "router". Basically, this router holds a mapping between URL patterns and functions to handle them. In any web framework, it can be done by registering a handler for all incoming requests. This handler when invoked parses the request and then we can decide what to do with it. For example, we can redirect this request to the real server using URLSession, get the response and then send it back to the app.

import EnvoyAmbassador
import Embassy

struct InterceptResponse: WebApp {
  func app(
    _ environ: [String: Any],
    startResponse: @escaping StartResponse,
    sendBody: @escaping SendBody 
  ) {
    let env = RequestEnvironment(environ)
    let request = env.request
    session.dataTask(with: request) { data, response, error in
      self.complete(env, request, response, data, startResponse, sendBody)
    }.resume()
  }
}

Local server edge cases

Before we continue to how we use the local web server in our tests, there are some interesting edge cases that we faced when using this approach.

First is running parallel tests in simulators on the same machine. When you are starting a local web server it needs to listen to a specific port, i.e. 8080. But if this port is already taken by another instance of a web server that is running on the same machine and was started from another test, you can't use the same port. For that, we simply pick up the next port until we find one that is free.

Next edge case is that our backend sometimes returns us absolute URLs to some resources instead of relative URLs. In this case, we have to override such URLs to point them to localhost so that when the app access them we can intercept them too. But we have to be careful about that, for example, we can receive an URL that contains another URL in its query parameter. So when we were simply replacing all http:// with http://localhost we were also changing those URLs. And then we ended up with URLs in query parameters like http://localhost:8080/www.nhs.co.uk/ instead of just http://www.nhs.co.uk which real backend services can't understand. We solved that by replacing URLs pointing only to our hosts and ignore all other hosts.

This resulted in another issue - when we change the content of the response, its size changes and so we also have to change corresponding HTTP headers of response, so that application network stack is not confused and can properly read all response data.

There might be others that we just haven't faced yet, but so far they were easy to solve and flexibility that local server provides outweighs them.

Local web server use cases

Now let's talk about how we are using the local web server in our tests. We do it in all different ways that this approach allows.

In the simplest case, we redirect all requests to the real services and simply log requests and responses. This already gives us a useful insight into why the test may misbehave, is it because request failed or it returned some data we didn't expect. And we don't have to switch between app and test logs, everything now is in one place.

We also use these logs as recordings, or snapshots, so that we can replay tests later without reaching real services. This is very similar to snapshot tests that you may write for your UI components. Each test can be run either in record or replay mode. In record mode, our web server redirects all requests to real backend services and writes responses in a file. In replay mode, it reads from these files.

And in some rare scenarios, we use the web server to completely mock the backend.

Network session recording

Let's talk a bit more about network session recording. When a local web server receives a request from the app it makes a similar request but to the real web server. It does it using plain URLSession. Because of that, we can record all network interactions easily by injecting into our web server a mock URL session that handles all recording and replaying logic.

There are again several open source solutions for that, like DVR, but we are using one that is called Vinyl and was actually developed by our team members. In practice, it worked much better than DVR and is much easier to use.

func startRecording(testName: String) {
  // detect recording mode
  let recordingMode: RecordingMode
  if case .record? = config.recordingMode {
    recordingMode = .missingVinyl(recordingPath: recordingPath)
  } else {
    recordingMode = .none
  }
  // configure matching strategy
  let matchingStrategy = MatchingStrategy.requestAttributes(
    types: [.method, .url, .query, .body],
    playTracksUniquely: false
  )
  // create URLSession mock
  recordingSession = Turntable(
    vinylName: vinylName(forTest: testName), 
    turntableConfiguration: TurntableConfiguration(
      matchingStrategy: matchingStrategy,
      recordingMode: recordingMode
  ))
  router.notFoundResponse = InterceptResponse(session: recordingSession!)
}

Recording network session is pretty straightforward but when it comes to replaying them there are two interesting problems we have to solve.

First one is random test input. Each of our tests starts with registering a new user. For that, we use randomly generated emails. And there are several other places where we generate random data, i.e. symptoms when booking an appointment. This random data then will be submitted in a body of a network request.

Now when we replay these network requests we need a way to match previously recorded requests with new incoming requests. If we match them only by URLs we are risking to match wrong requests in the case when there are similar requests with different bodies. So we match everything - HTTP method, URL, query parameters and body data. But then when we replay the test and it uses a different random input than what was used in recording we will not find a match because its body will be different from what was recorded before.

To solve that we simply store all random strings that test generates in a file next to network logs and then in replay mode read from it. This way when we replay test we use exactly the same input that was used when this test was recorded.

let matchingStrategy = MatchingStrategy.requestAttributes(
  types: [.method, .url, .query, .body],
  playTracksUniquely: false
)

func generateRandomString(length: Int, key: String?) -> String {
  if server.config.recordingMode != nil, let key = key {
      return randomStringFromFile(length: length, key: key)
  } else {
      return randomString(length: length)
  }
}

Another problem is similar to random input data - it's a current date. For example when user books an appointment our backend returns us available time slots. Then before submitting a book appointment request, we are checking if a selected time slot is actually in the future.

Now imagine that we replay this scenario against network recording made yesterday. All time slots will be in the past so the date check will fail and we will treat all of the time slots as expired. To solve that we need our app to use a custom date factory instead of default Date constructor that in tests returns the current date as a date of recording.

extension Date {
  static func now() -> Date {
    #if targetEnvironment(simulator)
    return Date(fromLaunchArguments: CommandLine.arguments)
    #else
    return Date()
    #end
  }
}

Mocking backend

The last use case for the local web server that we use is to completely mock the backend. This is useful for scenarios that we can't test only using the app and which require some actions on GP portal, i.e. prescriptions flow. For that, we need to have a prescription created on a backend. But instead, we can mock the endpoint to get prescriptions and return stubbed prescription. Or the scenario of registering with Facebook. For that, you need to have a test facebook user. But you can use it only once to register on a real server. We could create new test users in each test via Facebook API but this is very slow and we are introducing another point of failure that we can't control. Instead we use a single test user that we use to log in with Facebook in a browser and then we use a mock implementation of registration endpoint that we configure based on the test scenario - it can either return successful response or return an error so that we can make sure that the app reacts correctly on all responses.

The main problem with this approach is that you need to mock everything. As soon as you mocked one endpoint, i.e. that returns fake authorization token or fake prescription, you can't make any requests using this data to the real backend because it will not know anything about this fake data. You don't have to reimplement all backend logic though, instead, you can just configure it to be in a specific state, i.e. have an upcoming appointment for the user or have a completed appointment with a prescription. So the logic that you need to implement boils down to doing CRUD operations on collections of data using queries based on incoming requests. And this can be implemented in a pretty neat way.

func setUp() {
  server.router["patients/", .number()] = server.get(\.patients, by: \.id)
}

func test() {
  server.patient = PatientDTO.mock()
}

Another thing you'll need to implement is Encodable on your data models. In the app, most of your data models need to implement only Decodable, but to send them to the app from a mock server you need to decode them. If your models are simple or use tools like Sourcery you can get this boilerplate for free either relying on compiler generated implementations or code generated by Sourcery. Otherwise, you need to write this boilerplate code.

So as you can see it requires more work (that can be trivial though) for each test comparing with snapshot tests. For that reason, we will most likely use snapshots approach going forward and only use mocking when there is no other option.

mock everything ❌
boilerplate code to write ❌
total control ✅

Network and content stability? ✅

Snapshots approach comes with another benefit that is that it solves network and content stability issues. It does not matter how you implement snapshot tests, using the local web server or from inside the app - you will not depend on the real network anymore, so this can potentially make your tests less flaky and even a bit faster. Tomorrow when running tests your app will receive the same data as yesterday so you can be sure that if the test fails it's because of the app, not network or content changes. And when content really changes and you want to update your snapshots you just need to run the tests in record mode (making them work with the changed content so that they pass of course) and your snapshots will be updated without you ever touching snapshot files manually.

Tests performance

Now let's move on to the last problem - tests performance. Specifically repeating the same steps in different tests. Every time a user tries to access clinical records in the app we may ask them for their password. It is similar to how AppStore app asks you for your password or a fingerprint from time to time when you make a purchase. So we have to handle this in a lot of tests and spend quite some time on these otherwise useless steps.

To solve that we introduce shortcuts in the app which are only present when the app is built for the simulator. They work pretty much as feature toggles, just private and only available for our tests. We also use launch arguments to override some user defaults that we use in the app, for example, to check if we already showed onboarding screens or a screen that asks a user to enable push notifications.

This not only makes tests faster to run but also easier to write because we don't risk to forget to handle some alert or a popup after some step when they are disabled. Sometimes, like in push notifications tests, we do the opposite - we override defaults so that we force notifications screen to appear so that we make sure we enable notifications if this was never done on this device (i.e. after resetting simulators content).

We also use this approach to make the app to use memory storage instead of the keychain to store authentication token. This way we don't have to care about clearing any data from previous tests as each test will start with a completely fresh state.

Another case of performing repeated steps is when several tests need to perform the same steps to reach a particular state, for example, register a new user or book an appointment. This is probably the main factor that affects our tests performance right now. To solve that we are currently doing API calls to the backend from the test and then pass the data that we received to the app.

For example, when we need to register a new user at the beginning of the test we don't go through all registration steps every time. Instead, we make an API call to register a user with particular data and then we enter credentials we used for that on the login screen. We can even further speed it up by passing authorization token to the app via launch arguments so that it starts already in a logged in state, instead of going through the login screen. The same we can do with booking an appointment and other user actions, like adding a family member or a new payment method.

We are currently working on splitting our code base into SDKs and we plan to use these SDKs in our UI tests so that we also don't have to duplicate networking code in automation tests and authentication will be probably the first thing we will use it for.

We could even use API calls from tests to interact with GP portal instead of using mocked backend. This though will require us to first implement those APIs (which are designed first of all for a web app, not for tests), handle authentication and so on. But we then can use snapshots the same way as for calls made by our app. That's something we may switch to in future instead of using mock backend.

BDD-style tests

Finally, let's see now how our typical UI test looks like. Here is an example.

import XCTest
import XCTest_Gherkin

class MockServerTestExample: BaseFeature {

  override func setUp() {
    self.server.config.recordingMode = .replay
    super.setUp()
  }

  func testExample() {
    And("I tap the Get Started button")

    When("I enter my details")
    And("I accept terms and conditions")
    And("I tap on Lets go button")
    And("I accept privacy policy")

    Then("I see the home screen")
  }
}

As you can see it uses a mock server in replay mode and it's written in BDD style with clear given-when-then sections. It's also written in plain English which highly improves its readability. You can actually write it in any other language because these expressions are just plain strings. But at the same time, it is an absolutely valid Swift code.

This way each test is not just a set of some obscure Swift methods calls, it's a specification that is easy to understand for any member of your team, be it QA, developer or product owner. It also makes tests a better documentation of your product requirements, how it should behave.

To write tests like that we use a framework XCTest-Gherkin that gives us this simple and neat given-when-then DSL. "Gherkin" is a "Cucumber" in German and it's the name of this DSL. And Cucumber is one of the test tools that use this DSL. Calabash is another example of such a tool. Cucumber actually has its own Objective-C implementation of Gherkin parser, and there are few other open source libraries for iOS like Cucumberish.

Of course, by itself this test will not do anything. It will compile and run but it will fail on the first line because the Gherkin framework does not know what to do on this step. First, we need to implement the steps. Internally the Gherkin framework has a mapping between step expressions, which are just regular expressions, and their implementations, passed in as closures. Then when the step is invoked in tests using for example Given method, the string passed as a parameter to this method is matched with all available steps expressions and first matched step is invoked.

func defineSteps() {
  step("I launch the app") {
    XCUIApplication().launchIfNeeded()
  }
  
  step("I see the home screen") {
    XCTAssertTrue(TabBarMenu().isScreenDisplayed())
    XCTAssertTrue(TabBarMenu().isSelected(tabBarItem: .home))
    XCTAssertTrue(HomeScreen().isScreenDisplayed())
  }
}

To implement steps we use plain XCTest APIs with some helpers and a Page Object pattern. This allows us to make steps implementation highly readable too and makes our tests code very structured (you can argue if its a good structure but they are definitely structured). For each screen, we have a dedicated Page Object with the main goal to abstract interactions with XCUIElements and to hide implementations details. Each page object has a dedicated Steps Definer with implementations of steps related to this screen. These steps are used by tests which are grouped in Features, fancy name to call subclasses of XCTestCase.

class HomeScreen: BaseScreen {
  fileprivate enum Views {
    static let root = "homeRootView"
  }
  
  func isScreenDisplayed() -> Bool {
    let rootView = app.otherElements[Views.root]
    return tryWaitFor(element: rootView, withState: .exists)
  }
}

class HomeScreenStepsDefiner: BaseSteps {
  step("I see the home screen") {
    XCTAssertTrue(HomeScreen().isScreenDisplayed())
  }
}

class HomeScreenFeature: BaseFeature {
  func test_view_default_home_screen() {}
  func test_start_chat_from_home_screen() {}
}

Another nice feature of XCTest-Gherkin is that it automatically wraps steps into XCTActivity that can be seen in the test activity log. Each step starts a new activity which has the same name as step expression. This way the activity log looks exactly as our tests. And then we use XCTestHTMLReport to generate HTML reports which look exactly like activity logs in Xcode.

XCTest-Gherkin allows us to write very readable tests, but unfortunately, Xcode is not a great IDE to write such tests. There is no code completion for steps expression because they are just plain strings and there is no way to navigate from the test to the step implementation. Thankfully there are much better text editors like VSCode. It has a nice Gherkin plugin that works well with steps implemented basically with any BDD framework in any language, even with XCTest-Gherkin.

In VSCode you will not write a Swift test that you can run in Xcode, instead, it will be a feature file written in vanilla Gherkin language. Then you can write a simple test case in XCTest-Gherkin that will parse this feature file, convert it to native test cases and run them.

Unfortunately, you will not have a good debugging experience in this case as you will not be able to set breakpoints in test cases. VSCode has a plugin to compile Swift code but debugging tests is an issue that is still not solved.

For this, we can theoretically develop a code generator that will convert vanilla Gherkin feature files to XCTestCases which we can run and debug in Xcode. This way we can have the best of two worlds: nice editing experience of VSCode, debugging with Xcode and sharing feature files across teams. And as VSCode can compile your Swift code you will only need to switch to Xcode for debugging.

Alternatively one can develop a similar plugin for VSCode that will understand not just vanilla Gherkin but XCTest-Gherkin syntax. Then we wouldn't need to write feature files and generate Swift code from them.

This is not something that we use though, at least right now, because tools are not there yet so we have to live with the limitations of Xcode.

Wrap up

Now you know how local web server, snapshot tests and mock backend help us to solve some issues with UI tests. We are in the process of applying these approaches and currently have only few tests using snapshots and mocked backend but we already see how it enables us easily automate scenarious that we had to test manually before. If it proves to work well on a long run we will probably even opensource some of this code. And hopefully soon thanks to these techniques the only reason for our tests to fail will be developers being lazy to update them.

https://techcrunch.com/2016/07/13/facebook-lifts-the-veil-on-its-mobile-device-lab">https://techcrunch.com/2016/07/13/facebook-lifts-the-veil-on-its-mobile-device-lab ↩
C. Montgomery Burns' Handbook of World Domination By Matt Groening.↩

Parameterized jobs in CircleCI

Tue, 07 Aug 2018 18:41:12 GMT

The title is a lie - there is no such thing as parameterized jobs (at the time of writing, but seems it’s going to be improved in 2.1) when we are talking about CircleCI 2.0 workflows, which are (almost) awesome by the way. But with some tricks, we can achieve something close to that.

Here is the problem. Let's say we have a bunch of jobs which are exactly the same except what build or test command they invoke in the end. They all need to perform the same sequence of actions:

checkout code
install dependencies (different Homebrew packages, Ruby gems, CocoaPods and/or Carthage dependencies)
cache all of that so that future jobs don't spend more time than needed downloading everything all over again
run some build or test command, i.e. execute some lane or rake task
save artifacts and test results

That's a lot of boilerplate. How do we avoid repeating it and yet have different jobs for different tasks?

CircleCI 2.0 offers different ways to simplify such configuration, which are very well described in its documentation: we can use cache to store dependencies based on lock-file checksums, and we can use workflows to break all these steps into separate jobs and use workspaces to share data between them.

Unfortunately, I found that using workspaces adds significant overhead to the total time of the workflow (it was about 8 minutes in my case, which is pretty close to 50% of total workflow time without workspaces). If we extract checkout and dependencies installation steps into a separate job then we'll need to persist into the workspace all the content in the working directory. And yes, it will also persist whole .git folder. This adds several minutes to archive and then unarchive in the next job. Additionally, we might need to store Derived Data to use build-for-testing and test-without-building features of xcodebuild to pass it between build and test jobs. This adds time again. So even though now we have a nice pipeline where we first checkout, then build, then execute tests in parallel, such workflow can become much longer to run. And it does not give apparent performance improvements compared with a workflow that simply performs all the same steps for each of the jobs in parallel.

For that reason, I had to opt out using workspaces and had to repeat all of the steps in each job...

regression_test_bupa:
    <<: *container_config

    steps:
        - checkout
        - *lfs
        - *brew
        - *restore_gems_cache
        - *bundle_install
        - *save_gems_cache
        - *restore_cocoapods_cache
        - *pod_install
        - *save_cocoapods_cache
        - *restore_carthage_cache

        - run:
            name: Fastlane
            no_output_timeout: 60m
            command: bundle exec fastlane regression_test_bupa

        - *store_fastlane_output
        - *store_scan_results
        - *store_snapshot_diffs

There is a YAML feature that I use here to avoid even more repetitions - aliases. This way I extract configurations common for each job:

- &container_config
    macos:
        xcode: "9.4.1"
    working_directory: /Users/distiller/project
    shell: /bin/bash --login -eo pipefail
    environment:
        LC_ALL: en_US.UTF-8
        LANG: en_US.UTF-8
        SCAN_DEVICE: iPhone 5s
        FL_OUTPUT_DIR: output
        FASTLANE_XCODEBUILD_SETTINGS_RETRIES: 10

or individual steps, i.e. installing CocoaPods:

- &cocoapods_cache_key
    2-pods-{{ checksum "Podfile.lock" }}

- &restore_cocoapods_cache
    restore_cache:
        key: *cocoapods_cache_key

- &pod_install
    run:
        name: Pod Install
        command: |
            bundle exec pod --version
            diff Podfile.lock Pods/Manifest.lock || curl https://cocoapods-specs.circleci.com/fetch-cocoapods-repo-from-s3.sh | bash -s cf
            bundle exec pod install

- &save_cocoapods_cache
    save_cache:
        key: *cocoapods_cache_key
        paths:
            - Pods
            - ~/.cocoapods/repos

But YAML aliases don't support arrays, so can't be used to reuse steps definition between jobs.

It was fine in the beginning but when I started to move other jobs from Jenkins to CircleCI, config file grew immensely. Turns out that I already knew the solution for that, just didn't see it. There is the answer to that problem here but it does not go into details. So here we go.

As I mentioned before YAML aliases support only key-value pairs, not collections. So then we can extract steps key-value pair into an alias that we can then include in each job.

- &fastlane
    run:
        name: Fastlane
        no_output_timeout: 60m
        command: bundle exec fastlane ???

- &base_steps
    steps:
        - checkout
        - *lfs
        - *brew
        - *restore_gems_cache
        - *bundle_install
        - *save_gems_cache
        - *restore_cocoapods_cache
        - *pod_install
        - *save_cocoapods_cache
        - *restore_carthage_cache

        - *fastlane

        - *store_fastlane_output
        - *store_scan_results
        - *store_snapshot_diffs

But that does not allow us to override individual steps, like fastlane step here, so that we can perform different build or test commands in different jobs. We can only override all steps or none of them.

But we can use environment variables as parameters for these commands. Using Fastlane (or Rakefile, or Makefile) simplifies that a lot because we only need to set an environment variable with a name of a lane or rake task. And we might not even need it because we can use job name already exposed as environment variable out of the box.

- &fastlane
    run:
        name: Fastlane
        no_output_timeout: 60m
        command: bundle exec fastlane ${LANE:-$CIRCLE_JOB}

To be able to override/add environment variables we also need to extract environment key-value pair into an alias:

- &env_defaults
    LC_ALL: en_US.UTF-8
    LANG: en_US.UTF-8
    SCAN_DEVICE: iPhone 5s
    FL_OUTPUT_DIR: output
    FASTLANE_XCODEBUILD_SETTINGS_RETRIES: 10

- &container_config
    macos:
        xcode: "9.4.1"
    working_directory: /Users/distiller/project
    shell: /bin/bash --login -eo pipefail
    environment:
        <<: *env_defaults

And now to define a "parametrized" job we need just a few lines:

jobs:
    build_bupa_for_distribution:
        <<: *container_config
        <<: *base_steps

    test_bupa:
        <<: *container_config
        <<: *base_steps

    regression_test_bupa:
        <<: *container_config
        environment:
            <<: *env_defaults
            SCAN_DEVICE: iPhone 8 Plus (11.4)
        <<: *base_steps

Each of these jobs will perform exactly the same steps before invoking specific lane, defined by the name of the job and using default environment variables. If needed we can override lane name setting LANE environment variable. And for UI tests we can also override the type of simulator device to run them on (I couldn't make it work with SCAN_DEVICES though).

As a result, config file became around 2 times smaller - from initial 700 lines it went to just 370.

This way we can parametrize any number of steps, or even skip some steps (out of the box workflows only can skip whole jobs, not individual steps, and only based on a branch or a tag name). And extracting steps into Fast/Rake/Make-file will not only make this task simpler but will also help to keep config file clean.

Codable in practice

Sat, 05 May 2018 23:38:46 GMT

One of the first tasks I got in my new team was to convert entire code base from in-house JSON encoding/decoding solution (in fact two of them) to Swift native Codable protocols. What may sound like an easy task, on practice means a lot of work taking into account inconsistencies in API. That lead to the situation when apart from really simple data structures holding just few properties of primitive types, everything required custom decoding or encoding. Here are few of the use cases that I encountered and their possible solutions. In the end I will talk a bit about my experience using Sourcery to solve these issues.

Single or few keys differ from its property name.

When it is not a problem at all when you are dealing with small types, this requires a lot of manual typing when you have dozen of properties, because one "bad" key will require you to define all the other keys as well. Trivial example of that is id property. In the code it may be named identifier, but in most APIs it is id. One way to solve that would be of course to rename all identifiers's to id's, but that will lead to a lot of unnecessary changes in entire codebase (even if automated with refactoring tools) and may go against team coding style and lint rules. With Swift 4.1 this can be solved with custom key decoding/encoding strategies, but it can be costly performance wise, as noted in the docs (though I personally haven't made any performance tests). Also it may happen that single key decoding strategy will not cover all your cases.

Another common problem with coding keys is when APIs uses snake case notation while client code uses camel case. This seems to me as a pretty standard case, so that with Swift 4.1 it is one of the built in keys decoding/encoding strategies (apart from default one). While covering most of the cases this strategy will not cover all of them though. One trivial example of that is acronyms. To decode key like base_url you'll need to name corresponding property as baseUrl, when baseURL is more canonical. In case if you want to keep property name as baseURL you will need to define a custom key for it, which will bring you the the previous problem. Another issue may be in minor differences in encoding compound words, like post_code vs postcode, first_name vs firstname and so on. People also make mistakes quite often and as a result you can be stuck with using keys with typos and other inconsistencies in API which most of the time is easier to work around on clients than on backend.

So even if you are using key strategies, you may still need to define your coding keys, even though now not all of them will need to have a raw value, but apparently this still does not work very well.

Another less common but still possible case is when you deal at the same time with different APIs which use different keys strategies. Using standard library's approach will make you to handle these APIs differently to be able to set different strategies on decoders that they use, which can require you make more changes to your network layer implementation.

Single or few properties require custom decoding/encoding.

In case you only need to transform some keys and all is fine with your data types, i.e. numbers always come as numbers and not as strings, having custom CodingKeys may be just enough for you. But if you have at least one property that you have to decode or encode manually you will have to do that for all the properties. And even if all is fine with your keys and you only need custom decoding, you will have to define all the keys too as complier will not let you to use decoder with keys type which is not defined anywhere¹. Meaning that automatic synthesis of Codable implementation is useless in this case and you can end up with twice as much code to write as number of properties in your type.

The best way to make it still work is to introduce intermediate wrapper types which will handle this custom decoding/decoding implementations. This though can cause unexpected changes across your code base and can make working with your models harder when you need to access these wrapped values. To mitigate the negative effect of this your can introduce computed properties which will take care of unwrapping, but you'll need a different name for such properties, so the problem of unneeded changes does not go away. You can instead change the name of a wrapper property, i.e. prefix it with underscore, and use a custom key strategy which will drop it for all the keys.

Ignoring malformed data

It might be the case that some of the data will come in a format that you don't expect and can not decode, i.e. date format changed without API version change, or you are dealing with user generated data that was not validated. In case this data is a part of a bigger data graph you probably don't want to fail decoding of the whole graph just because something went wrong with one of its portions, but instead disable some corresponding feature of the app. This may be controlled by the API not returning such data so you will not need to decode corresponding keys (but most likely API will not care about validating data for a client). In this case you can just make your property optional or use decodeIfPresent if you have to do decoding manually. The problem with this is that if at some point you will receive malformed data, decoding will still fail, because as you can see from Decodable constructor signature init(from:) throws it is not failable and only can throw errors, which will be then re-thrown by decodeIfPresent. So if key is present, decoder will still attempt to decode what ever data is stored by this key. Instead of optionals and decodeIfPresent we have to use either custom decoding methods which will silence errors:

extension KeyedDecodingContainer {
    public func decodeSafely<T: Decodable>(_ type: T.Type, forKey key: KeyedDecodingContainer.Key) -> T? {
        guard let decoded = try? decode(T.self, forKey: key) else { return nil }
        return decoded
    }

    public func decodeSafelyIfPresent<T: Decodable>(_ type: T.Type, forKey key: KeyedDecodingContainer.Key) -> T? {
        guard let decoded = try? decodeIfPresent(T.self, forKey: key) else { return nil }
        return decoded
    }
}

or introduce a wrapper type that will do the same in its implementation of Decodable constructor:

struct FailableDecodable<T: Swift.Decodable>: Swift.Decodable {
    let value: T?

    init(from decoder: Swift.Decoder) throws {
        let container = try decoder.singleValueContainer()
        self.value = try? container.decode(T.self)
    }
}

The benefit of using wrapper type is that it can be then used as a property type by itself to allow decoding code to be synthesised by compiler and can be used as a type of collection elements, like arrays, as discussed further.

Prune arrays

Malformed data discussed previously can come in as an array. In this case you might want to just filter out those items which can not be decoded and keep the rest. Again standard decoding methods will not work here as decoding [T].self type will fail if any of items can not be decoded to T, as well as [T?].self - even though Optional is Decodable its implementation rethrows the error if its value can't be decoded. In this case you can again use FailableDecodable wrapper or extend decoder with custom decoding methods:

items = try values.decode([FailableDecodable<Item>].self, forKey: .items).flatMap({ $0.value })

items = try values.decodeIfPresent([FailableDecodable<Item>].self, forKey: .items).flatMap({ $0.value })

Not empty arrays and strings

In constrast to pruning arrays you might want to ensure that array contains at least one item, or string to be not empty. This type of validation could be performed on a backend side but usually it's not the case. So you will have to deal with it on a client. Another wrapper that ensures that wrapped collection (including String) is not empty can be useful in this case (you can implement more sophisticated version of it). Again you can use this wrapper directly or introduce custom decoding methods (you might then need them on both KeyedDecodingContainer and UnkeyedDecodingContainer).

struct NotEmptyDecodable<T: Swift.Decodable & Collection>: Swift.Decodable {
    var value: T

    init(from decoder: Decoder) throws {
        let values = try decoder.singleValueContainer()
        let value = try values.decode(T.self)
        guard !value.isEmpty else {
            throw decoder.dataCorrupted("Unexpected empty \(T.self)")
        }
        self.value = value
    }

}

Deep nesting

It is not unusual to have data that you are interested in buried deep inside data structure. This can be just one key, i.e. when you want to decode or encode array of some items by items key, or it can be a complex key path like errors.base.0. To access it this way you can replicate data structure by defining all intermediate types and keys. But if you will never use them for anything else it seems like too much of an effort just to make automatic synthesis work, especially if you have to do that in several places. You probably don't want to bloat your data models with bunch of "lists" and other dummy types which do not have any other practical application (though sometimes it can be a useful abstraction and a really good and fast way to solve this issue). Instead you can perform decoding using something similar to key path access using yet another smart wrapper.

First we will need a custom key type:

public struct AnyCodingKey: Swift.CodingKey, ExpressibleByStringLiteral, ExpressibleByIntegerLiteral {
    public var intValue: Int?
    public var stringValue: String

    public init?(intValue: Int) {
        self.intValue = intValue
        self.stringValue = "\(intValue)"
    }

    public init?(stringValue: String) {
        self.stringValue = stringValue
        self.intValue = Int(stringValue)
    }

    public init(stringLiteral value: String) {
        self.init(stringValue: value)!
    }

    public init(integerLiteral value: Int) {
        self.init(intValue: value)!
    }

}

This key can be constructed with any string to access property by key or integer to access item in array by index (most of the time you will probably need just first or last item, so recognising first and last in the key path can be handy too). Next we need a method that will take care of decoding by key path:

struct NestedKeyDecodable<T: Swift.Decodable>: Swift.Decodable {
    let value: T
    
    init(from decoder: Swift.Decoder) throws {
        guard let nestedKey = decoder.userInfo[AnyCodingKey.key] as? AnyCodingKey,
                !nestedKey.stringValue.isEmpty else {
            fatalError("No key is stored in decoder's user info")
        }
        let keydContainer = try? decoder.container(keyedBy: AnyCodingKey.self)
        let unkeyedContainer = try? decoder.unkeyedContainer()
        self.value = try _decodeNested(
            key: nestedKey,              
            keyedContainer: keydContainer,
            unkeyedContainer: unkeyedContainer
        )
    }
}

The main bit of implementation is _decodeNested function. What it does is it breaks key path into keys using . as a separator and loops through key path items trying to get either nested keyed container for string items (accessing nested object) or nested unkeyed container for integer items (accessing array element). On the last key path item it tries to decode value from the latest nested container it had reached.

func _decodeNested<T: Swift.Decodable>(
    key: AnyCodingKey,
    keyedContainer: KeyedDecodingContainer<AnyCodingKey>?,
    unkeyedContainer: UnkeyedDecodingContainer?
) throws -> T {
    var keyPath = key.stringValue.components(separatedBy: ".")
    var key = AnyCodingKey(stringValue: keyPath.removeFirst())!
    var keyedContainer = keyedContainer
    var unkeyedContainer = unkeyedContainer

    if let index = key.intValue {
        try unkeyedContainer?.advance(to: index)
    }

    while !keyPath.isEmpty {
        let nextKey = AnyCodingKey(stringValue: keyPath.removeFirst())!
        if let index = nextKey.intValue {
            unkeyedContainer = try keyedContainer?.nestedUnkeyedContainer(forKey: key, at: index)
                ?? unkeyedContainer?.nestedUnkeyedContainer(at: index)
            keyedContainer = nil
        } else {
            keyedContainer = try keyedContainer?.nestedContainer(keyedBy: AnyCodingKey.self, forKey: key)
                ?? unkeyedContainer?.nestedContainer(keyedBy: AnyCodingKey.self)
            unkeyedContainer = nil
        }
        key = nextKey
    }

    if let c = keyedContainer {
        return try c.decode(T.self, forKey: key)
    } else if var c = unkeyedContainer {
        return try c.decode(T.self)
    } else {
        fatalError("Should never happen")
    }
}

Flat data structure

Opposite to the nested data is situation when you have different data types encoded in the same JSON object. For example it can be a patient data with their address encoded on the same level as its name and other personal details instead of being a separate object stored by its own key. In your data model you can prefer to represent it as a single property of Address type, especially if another endpoint returns you this type on its own and you want to reuse it. To do that call Decodable constructor of this type and pass it the same decoder used to decode the containing type. The same applies to encoding.

struct Person: Decodable {
    let name: String
    let address: Address

    enum CodingKeys: String, CodingKey { ... }

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        name = try container.decode(String.self, forKey: .name)
        address = try Address(from: decoder)
    }
}

Mapping from one type to another

It's very usual when you need to convert Strings to Double, or String to some enum value. JSONDecoder.nonConformingFloatDecodingStrategy only takes care of converting "exceptional" float values, like infinity or NaN and does not provide extension mechanism like custom keys strategy, so will not help here. It can be solved with a computed property, but it might be better to perform mapping during decoding so that decoding fails if mapping fails, instead of returning optional in the computed property. I.e. if you need to map String to Double you may use custom decoding methods, like func decode(_ type: String.Type, forKey key: Key) -> Double, or generic wrappers, i.e. StringNumber<T> which will implement Decodable only if T is of Double or Int type (thanks to conditional conformance!).

Different date formats

In ideal world API is consistent in representing dates as well as other types. In this ideal world it either uses ISO format or timestamps, so that you can use one of the decoding strategies provided by standard library, or at least uses some consistent format, so that you can define your own strategy based on DateFormatter. But in real world you can have an endpoint that, lets say, returns appointment details with the date and time of appointment and patient personal data with its birthday which only have date and does not have time. One decoding strategy will not be able to handle this. You may come up with a smart custom strategy that takes in Decoder and returns Date depending on the key being decoded (Decoder does not keep track of the type being decoded, it only tracks keys), but it does not sound like a good solution to me. One alternative is to decode each date property as a string value first and then use what ever date formatter you need in each particular case. Another is to introducing generic type that will be parametrised over formatter type:

struct FormattedDate<F: DateFormatter>: Decodable {
    let date: Date

    init(from decoder: Decoder) throws {
        let values = try decoder.singleValueContainer()
        let dateString = try values.decode(String.self)
        let dateFormatter = F.sharedInstance // 🤷‍♂️
        guard let date = dateFormatter.date(from: dateString) else {
            throw DecodingError.dataCorrupted("Invalid date format")
        }
        self.date = date
    }
}

This though will require to define date formatters as subclasses of DateFormatter (you can model it in another way but you will still need them to be distinct types), while it's more common to define them as plane DataFormatters created with different date formats and stored as a static instances in some namespace.

Dictionaries and arrays of arbitrary types

Not always data have a well defined scheme that you can control, sometimes you need to decode or encode [Any] or [String: Any] types. These types can not be decoded or encoded automatically as Any is not "codable" (even worse in Swift 4 code that does that will compile but will crash at runtime). These types can be decoded/encoded using a wrapper that will internally check decodable or encodable value against each possible type and decode/encode it accordingly (also taking care of null values with decodeNil(forKey:) method). Its implementation is trivial and consists of quite a few if/else statements, so I'll leave it out as an exercise.

Optional values as required

By default optional values will be decoded using decodeIfPresent method and will not be encoded if the value is nil. It might be not what you want as it can mask errors on API side (when it does not return key that you are expecting) or API can require you to send all the values in a payload even if they are null. At the same time you might need to use optional property because you need to create an instance of a type manually and in this case don't have values for these properties. A good example of such properties (for decoding case) can be unique id's generated by the API. The only feasible option here is to implement coding methods manually for type with such properties.

Default values

Another case that standard library does not take care of is default values. When you can't decode, let's say, Int value, 0 can be a valid default for it. You probably wouldn't want to deal with optionality in every place where you use this property, so you either will need to implement coding methods manually, falling back to default value, or make this property optional and use another computed property that will fall back to default value. If you need to encode default value too, computed property will not work as only stored properties are encoded by default so you will still need to implement encoding manually.

Memberwise initialiser

This issue is not related to problems with decoding particular data types but instead is a limitation of Swift as a language. When you implement Decodable on a struct and define its init(from decoder: Decoder) method in its body, Swift will not generate memberwise initialiser for such struct. This is mostly a problem for unit tests when you need to create fake values. To avoid this issue define init(from decoder: Decoder) in an extension of your struct.

These issues are most of which I had to tackle, but there are also other interesting use cases which I luckily didn't have to deal with, like decoding subclasses, inherited classes, heterogeneous arrays and there are some more very useful tips on this topic, some of which I used during development.

If we look at the outlined solutions they all more or less fall into three domains:

implementing decoding/encoding manually and dealing with issues one by one
extending decoding/encoding containers with custom methods
define wrapper types and use type system to make Codable implementation synthesised by compiler

The first option is the most straight forward but can require you to write or copy-paste a lot of code.
The second option will still require manual implementation of decoding/encoding protocols but will give you reusable methods which will save you some time.
With the third option instead of reusable methods you will have types and will be able to make code synthesised for you in more cases, but it may require you to make more unneeded changes in your code base and make it harder to work with your types. It also has another positive effect - it makes a data scheme to be encoded in your types, which I think is better than using decoding strategies provided by standard library. It can be a good idea though to have separate types for those data schemes and for data models and setup bridging between them so that data models are agnostic about API details. But that leads to more boilerplate code to write.

Sourcery

But there is also another option - let Sourcery to generate boilerplate Codable code instead of compiler. There are few benefits of using Sourcery here comparing with other options:

it is much more flexible than what standard library has to offer right now, you can implement absolutely custom template which will handle your specific cases in the way which suits best to you
it saves you from writing much more boilerplate code than standard library can do right now. It can let you to define only custom coding keys and generate the rest of the keys for you, and it can let you to define custom decoding methods only for some properties and generate code for the rest of the properties
you don't need to pollute your code with various wrapper types which only purpose is to satisfy compiler
Sourcery will update generated code whenever you change your source code so you will never forget to decode or encode new property
you can remove Sourcery at any point and you will have all the code in place already

There are drawbacks of course too:

learning curve as you need to understand Sourcery specifics and its limitations
you may need to develop and maintain your own template or extend existing one, so you'll need to be comfortable with options that Sourcery provides for developing templates (Stencil, Swift or EJS)
if you are working in the team you need to make sure that you are not the only one who understand what Sourcery is. Otherwise you will end up with it being removed as soon as you leave the team (the story of my life) or it will be harder to adopt it
template code is still a code and it can have bugs and can (will) become a legacy. Also do not overuse annotations - they make templates more flexible, but, in my experience, are hard to understand for newcomers

Conclusion

Codable as a feature was by now well accepted by community and made life of Swift developers much easier, but it still does not solve all the issues we have to deal with in real-life projects. There are multiple ways how you can solve them by writing your code in a specific ways. And tools like Sourcery which will help you to write even less code.

This will not be the case if you let compiler to generate implementation for one of Decodable or Encodable protocols when you are conforming to Codable. But if you provide manually implementation for both of them or when you conform only to one of them and provide manual implementation for it - compiler will not generate CodingKeys type for you.↩

URL parser in functional style. Part 2.

Tue, 07 Nov 2017 19:56:44 GMT

In previous part we started to write base components of URL parser. Time to extend it and add some additional functionality, like conditional, optional and wildcard patterns.

Conditional pattern

This pattern should parse either one pattern or another. This kind of parameter type can be expressed with Either<A, B> type defined as a simple generic enum with two cases.

enum Either<A, B> {
    case left(A), right(B)
}

Using this type we can compose parser and printer. Parser will try to parse left pattern first and return matched value wrapped in Either.left, otherwise it will parse right pattern and return matched value wrapped in Either.right. Printer will pattern match this value and will print left or right pattern.

func parseEither<L, R, S>(_ lhs: RoutePattern<L, S>, _ rhs: RoutePattern<R, S>) -> Parser<Either<L, R>> {
    return {
        lhs.parse($0).map({ ($0.rest, Either.left($0.match)) })
            ?? rhs.parse($0).map({ ($0.rest, Either.right($0.match)) })
    }
}

func printEither<L, R, S>(_ lhs: RoutePattern<L, S>, _ rhs: RoutePattern<R, S>) -> Printer<Either<L, R>> {
    return {
        switch $0 {
        case let .left(a): return lhs.print(a)
        case let .right(b): return rhs.print(b)
        }
    }
}

func templateOr<A, B, S>(_ lhs: RoutePattern<A, S>, _ rhs: RoutePattern<B, S>) -> String {
    return "(\(lhs.template)|\(rhs.template))"
}

With that we can now define operator for this kind of composition.

extension RoutePattern {

    static func |<B>(lhs: RoutePattern, rhs: RoutePattern<B, S>) -> RoutePattern<Either<A, B>, S> {
        return .init(parse: parseEither(lhs, rhs), print: printEither(lhs, rhs), template: templateOr(lhs, rhs))
    }

}

For Void types we need again to handle composition separately, but we only need to handle one case when Void is on both sides. In case if Void is on one side we will have Either<Void, A> or Either<A, Void> type in which we can not easily get rid of Void.

func parseAny<A, S>(_ lhs: RoutePattern<A, S>, _ rhs: RoutePattern<A, S>) -> Parser<A> {
    return { lhs.parse($0) ?? rhs.parse($0) }
}

func printAny<A, S>(_ lhs: RoutePattern<A, S>, _ rhs: RoutePattern<A, S>) -> Printer<A> {
    return { lhs.print($0) ?? rhs.print($0) }
}

extension RoutePattern where A == Void, S == Path {
    
    static func |(lhs: RoutePattern, rhs: RoutePattern) -> RoutePattern {
        return .init(parse: parseAny(lhs, rhs), print: printAny(lhs, rhs), template: templateOr(lhs, rhs))
    }
    
}

With that we can define more complex patterns like this:

let profileRoute = lit("users") /> (string >/> lit("profile") | lit("me"))

let url = URL(string: "appscheme://users/username/profile")!

let parsed = profileRoute.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), .left("username"))

let url = URL(string: "appscheme://users/me")!

let parsed = profileRoute.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), .right(()))

let printed = profileRoute.print(.left("username"))
// printed = (path: ["users", "username", "profile"], query: [:])

let printed = profileRoute.print(.right(()))
// printed = (path: ["users", "me"], query: [:])

let template = profileRoute.template
// template = "users/(:string/profile|me)"

In this case we define pattern for Either<String, Void>, but for this kind of cases it might be better to use optional pattern.

Optional pattern

This pattern should succeed parsing and printing even if it actually failed. For that type of pattern parameter should be A?. We will create this pattern with a simple function that will wrap another patter with parameter type A.

func maybe<A, S>(_ route: RoutePattern<A, S>) -> RoutePattern<A?, S> {
    return .init(parse: { url in
        guard let result = route.parse(url) else { return (url, nil) }
        return (result.rest, result.match)
    }, print: {
        return $0.flatMap(route.print)
    }, template: "(\(route.template))")
}

Note that in parser we can not just return result, as its type will be (RouteComponents, A) but we need to return (RouteComponents, A?), so we have to deconstruct and construct tuple again.

Void parameter type again requires special attention. It does not make much sense to have pattern with Void? parameter type, we can just keep Void.

func maybe(_ route: RoutePattern<Void, Path>) -> RoutePattern<Void, Path> {
    return .init(parse: { route.parse($0) ?? ($0, ()) }, print: route.print, template: "(\(route.template))")
}

With that we can define patterns composition:

infix operator /? : MultiplicationPrecedence

extension RoutePattern where S == Path {
    
    static func /?(lhs: RoutePattern, rhs: RoutePattern<Void, S>) -> RoutePattern {
        let rhs = maybe(rhs)
        return .init(parse: parseLeft(lhs, rhs), print: printLeft(lhs, rhs), template: templateAnd(lhs, rhs))
    }
    
    static func /?(lhs: RoutePattern<Void, S>, rhs: RoutePattern) -> RoutePattern<A?, S> {
        let rhs = maybe(rhs)
        return .init(parse: parseRight(lhs, rhs), print: printRight(lhs, rhs), template: templateAnd(lhs, rhs))
    }
    
    static func /?<B>(lhs: RoutePattern, rhs: RoutePattern<B, S>) -> RoutePattern<(A, B?), S> {
        let rhs = maybe(rhs)
        return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
    }

}

With this operator we hide wrapping of right pattern in a maybe function and make its usage more natural. Similar operators we can define for query patterns:

infix operator .?? : MultiplicationPrecedence
infix operator &? : MultiplicationPrecedence

extension RoutePattern where S == Query {
    
    public static func .??(lhs: RoutePattern<Void, Path>, rhs: RoutePattern) -> RoutePattern<A?, Query> {
        let rhs = maybe(rhs)
        return .init(parse: parseRight(lhs, rhs), print: printRight(lhs, rhs), template: templateAnd(lhs, rhs))
    }
    
    public static func .??<B>(lhs: RoutePattern<B, Path>, rhs: RoutePattern) -> RoutePattern<(B, A?), Query> {
        let rhs = maybe(rhs)
        return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
    }

    public static func &?<B>(lhs: RoutePattern, rhs: RoutePattern<B, Query>) -> RoutePattern<(A, B?), Query> {
        let rhs = maybe(rhs)
        return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
    }

}

Wildcard pattern

This pattern will be the most complicated. First we need to introduce two more state of a pattern: one that marks that subsequent pattern is required - AnyStart and one that marks that pattern ends with any path - AnyEnd.

protocol AnyPattern {}
enum AnyStart: AnyPattern, OpenPatternState {}
enum AnyEnd: AnyPattern, ClosedPathPatternState {}

Lets start with Wildcard pattern used in the end of the path.

public let any: RoutePattern<Void, AnyEnd> = {
    return .init(parse: { route in
        guard route.path.first != nil else { return nil }
        return (([], route.query), ())
    }, print: { _ in
        return (["*"], [:])
    }, template: "*")
}()

Type of the pattern is RoutePattern<Void, AnyEnd> because we are not going to extract any parameters from it and we should not allow any other path patterns after it, so it's status should be "closed" but different from Path.
To parse it we just check if there are any paths left. If there is none we fail (wildcard pattern requires at least one more path component), otherwise we drop all the components left in the path and only keep query.

We can now define composition for route with wildcard pattern, nothing special here:

extension RoutePattern where S == Path {

    // string /> any
    static func />(lhs: RoutePattern<Void, Path>, rhs: RoutePattern<A, AnyEnd>) -> RoutePattern<A, AnyEnd> {
        return .init(parse: parseRight(lhs, rhs), print: printRight(lhs, rhs), template: templateAnd(lhs, rhs))
    }
    
    // param >/> any
    static func >/>(lhs: RoutePattern<A, Path>, rhs: RoutePattern<Void, AnyEnd>) -> RoutePattern<A, AnyEnd> {
        return .init(parse: parseLeft(lhs, rhs), print: printLeft(lhs, rhs), template: templateAnd(lhs, rhs))
    }
}

In the case when wildcard used before other pattern we will define a function that accepts next pattern. As wildcard means that there can be any kind of path components before next pattern we will simply try to match next pattern until it succeeds. If it fails we will drop path component and try again until it matches or we reach the end of the path.

func any<A>(_ next: RoutePattern<A, Path>) -> RoutePattern<A, AnyStart> {
    return .init(parse: { route in
        // there should be at least one path component before `next`, so we drop it from the beginning
        for index in route.path.dropFirst().indices {
            // try match the rest of pattern with the rest of path
            let rest = route.path.suffix(from: index)
            if let nextResult = next.parse((Array(rest), route.query)) {
                return nextResult
            }
        }
        return nil
    }, print: {
        guard let nextResult = next.print($0) else { return nil }
        return (["*"] + nextResult.path, [:])
    }, template: "*/\(next.template)")
}

First we define composition when wildcard is used at start of path as it's the simplest case:

extension RoutePattern where S == Path {

    // any /> something
    static func />(lhs: @escaping (RoutePattern) -> RoutePattern<A, AnyStart>, rhs: RoutePattern) -> RoutePattern {
        let route = lhs(rhs)
        return .init(parse: route.parse, print: route.print, template: route.template)
    }

}

This pattern accepts any pattern as first parameter and right pattern. Note that though lhs parameter type is a closure it has the same signature as func any<A>(_ next: RoutePattern<A, Path>) -> RoutePattern<A, AnyStart>, so it means that we can pass any function to it. Then we pass right pattern to this function so that we get a pattern that will match it. But as it has AnyStart state but we need tor return pattern with Path state we construct a new pattern.

Now we can define patterns with wildcard pattern at start and end of path:

let anyStart = any /> lit("users")
let anyEnd = lit("users") /> any

let url = URL(string: "appscheme://something/users")!

let parsed = anyStart.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), ())

let url = URL(string: "appscheme://users/something")!

let parsed = anyEnd.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), ())

let printed = anyStart.print(())
// printed = (path: ["*", "users"], query: [:])

let printed = anyEnd.print(())
// printed = (path: ["users", "*"], query: [:])

let template = anyStart.template
// template = "*/users"

let template = anyEnd.template
// template = "users/*"

For the most complicated case when wildcard is used in the middle of the path we will need a small helper that will be able to "consume" the subsequent pattern to produce a new pattern:

struct AwaitingPattern<LeftType, RightType, ResultType> {
    let consume: (RoutePattern<RightType, Path>) -> RoutePattern<ResultType, Path>
}

For composition we need to define two operators:

extension RoutePattern where S == Path {

    // param >/> any (>/> param)
    static func >/><B>(lhs: RoutePattern<A, Path>, rhs: @escaping (RoutePattern<B, Path>) -> RoutePattern<B, AnyStart>) -> AwaitingPattern<A, B, (A, B)> {
        return .init {
            let rhs = rhs($0)
            return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
        }
    }
    
    // (param >/> any) >/> param
    static func >/><B>(lhs: AwaitingPattern<A, B, (A, B)>, rhs: RoutePattern<B, Path>) -> RoutePattern<(A, B), Path> {
        return lhs.consume(rhs)
    }

}

First function accepts left pattern with parameter of type A and any function that expects next pattern with parameter type B. This function returns AwaitingPattern. It has left type of A, right type of B and the result type of (A, B) as it will be actual pattern result after all the components are concatenated.

Second function accepts AwaitingPattern that we got from first function and a pattern with parameter type B. As a result it produces composed pattern of type (A, B). This way we actually concatenate three patterns, one of the left side, wildcard itself, and one on the right side.

let anyMiddle: RoutePattern<(Int, String), Path> = int >/> any >/> string

We have to handle Void types separately again, for both cases - Void on the left and Void on the right:

extension RoutePattern where S == Path {

    // string /> any (/> param)
    static func />(lhs: RoutePattern<Void, Path>, rhs: @escaping (RoutePattern<A, Path>) -> RoutePattern<A, AnyStart>) -> AwaitingPattern<Void, A, A> {
        return .init {
            let rhs = rhs($0)
            return .init(parse: parseRight(lhs, rhs), print: printRight(lhs, rhs), template: templateAnd(lhs, rhs))
        }
    }
    
    // (string />) any /> param
    static func />(lhs: AwaitingPattern<Void, A, A>, rhs: RoutePattern<A, Path>) -> RoutePattern {
        return lhs.consume(rhs)
    }

    // param >/> any (>/> string)
    static func >/>(lhs: RoutePattern, rhs: @escaping (RoutePattern<Void, Path>) -> RoutePattern<Void, AnyStart>) -> AwaitingPattern<A, Void, A> {
        return .init {
            let rhs = rhs($0)
            return .init(parse: parseLeft(lhs, rhs), print: printLeft(lhs, rhs), template: templateAnd(lhs, rhs))
        }
    }
    
    // (param >/>) any >/> string
    static func >/>(lhs: AwaitingPattern<A, Void, A>, rhs: RoutePattern<Void, Path>) -> RoutePattern<A, Path> {
        return lhs.consume(rhs)
    }

}

In case we have Void on the left the resulting type of pattern parameter will be type of right pattern. In case we have Void on the right - it will be type of left pattern. Implementations are trivial in both cases, we just need to get types right.

Router

The last component of the puzzle is a router, object that holds mapping between routes and patterns and uses it match URLs or print URLs for routes. To hold this map we could use array or dictionary, but instead we will reuse RoutePattern and its composition. When first pattern will be registered for some route we will store a reference to it. When new pattern is added we will compose it with current pattern in a way similar to how we composed pattern for Either. This is similar to how you can replace loop with recursion.

class Router<U: Route> {
    private var route: RoutePattern<U, Path>?

    private func add(_ route: RoutePattern<U, Path>) -> Router {
        self.route = self.route.map({ oldValue in
            .init(parse: { oldValue.parse($0) ?? route.parse($0) },
                    print: { oldValue.print($0) ?? route.print($0) },
                    template: "\(oldValue.template)\n\(route.template)")
        }) ?? route
        return self
    }

}

One important thing to note here is generic type of Router. It should conform to special protocol Route:

protocol Route: Equatable {
    func deconstruct<A>(_ constructor: ((A) -> Self)) -> A?
}

It requires only one function that accepts some generic "constructor" that converts generic type A to Self and returns this generic parameter back. You'll see why it's needed and hot it is used in a minute.

So we have now RoutePattern<U, Path> that we can use for matching. U here stands for the type of the route (or intent) that we defined in the beginning of first part:

enum Route {
    case showMyProfile
    case showProfile(userId: String)
    case follow(userId: String)
    case retweet(tweetId: Int)
    case showUserTweet(userId: String, tweetId: Int)
}

Let's define some possible patterns for these routes:

let showMyProfile: RoutePattern<Void, Path> = lit("users") /> lit("me")
let showProfile: RoutePattern<String, Path> = lit("users") /> string >/> lit("profile") 
let follow: RoutePattern<String, Path> = lit("users") /> string >/> lit("follow")
let retweet: RoutePattern<Int, Query> = lit(retweet) .? int("tweetId")
let showUserTweet: RoutePattern<(String, Int), Path> = lit("users") /> string >/> lit("tweets") >/> int

As you can see generic types of these patterns do not match type U which our router expects. So how do we actually register them?

For that we need to "map" patterns over their parameter type. But this should be a special kind of map, that can do transformation on both directions. We need that to be able to map tuple of associated values to enum case and convert enum case back to tuple of its associated values. We do that using already familiar apply and unapply functions.

extension RoutePattern {

    func map<B, S>(_ apply: @escaping (A) -> B?, _ unapply: @escaping (B) -> A?) -> RoutePattern<B, S> {
        return .init(parse: {
            guard let result = self.parse($0), let value = apply(result.match) else { return nil }
            return (result.rest, value)
        }, print: {
            guard let value = unapply($0) else { return nil }
            return self.print(value)
        }, template: template)
    }

}

So to map pattern of type A to pattern of type B we need functions that can convert A to B and B to A. Their result types are optional as we allow this transformations to fail so that we can fail parsing or printing.

Let's now use this function to register a simplest pattern:

extension Router {

    @discardableResult
    func add<S: ClosedPatternState>(_ intent: U, route: RoutePattern<Void, S>) -> Router {
        return add(route.map({ intent }, { $0 == intent ? () : nil }))
    }

}

Here we are using map to create a new pattern that will convert Void to U, for which we just need to return value of U that we got as input parameter. For printing we need to check that parameter sent to print, U is equal to intent that we are registering this pattern for.

Here is how we use it:

let router = Router<Routes>()
router.add(Routes.showMyProfile, route: lit("users") /> lit("me"))

let url = URL(string: "appscheme://users/me")!

let parsed = router.route.parse(url.components)
// parsed = Routes.showMyProfile

let printed = router.route.print(Routes.showMyProfile)
// printed = (path: ["users", "me"], query: [:])

Let's now try to register route with one parameter:

extension Router {

    @discardableResult
    func add<A, S: ClosedPatternState>(_ intent: @escaping ((A)) -> U, route: RoutePattern<A, S>) -> Router {
        return add(route.map({ intent($0) }, { ??? }))
    }

}

The input parameter of this function is a function that accepts parameter A and returns U. For that we can use enum cases constructor. I.e. Routes.showProfile has type of (String) -> Routes, Routes.showUserTweet has type of (String, Int) -> Routes. So to map A to U we just need to pass A to this constructor to get U.

But how do we get A from value of U. Essentially it will mean that we need to extract associated values from value of enum. In Swift we usually do that with if case let:

if case let .showProfile(userId) = value { ... }

But we can't use this inside unapply closure, because we don't know to what case to match the value, we only get it's constructor. We can't write something like if case intent = value, it just does not make sense. So how do we solve that? That's where our deconstruct function comes in. It accepts (A) -> Self as parameter. That's exactly the signature of our input intent parameter, so the only thing we can do is to pass it in. As a result we will get A?, that's exactly what we need to return from unapply function, so everything matches!

extension Router {

    @discardableResult
    func add<A, S: ClosedPatternState>(_ intent: @escaping ((A)) -> U, route: RoutePattern<A, S>) -> Router {
        return add(route.map({ intent($0) }, { $0.deconstruct(intent) }))
    }

}

Now let's see how we can implement this function:

extension Routes: Route {

    func deconstruct<A>(_ constructor: ((A) -> Routes)) -> A? {
        switch self {
            ???
        }
    }
}

The point of this method is to extract associated values from enum value in case it matches the constructor. So first we extract values from each case:

switch self {
    case let .showProfile(values): ...
    case let .follow(values): ...
    case let .retweet(values): ...
    case let .showUserTweet(values): ...
    default: ...
}

What we can do now with these extracted associated values. We can try to simply return them, but we can't as their type does not match generic parameter A.

switch self {
    case let .showProfile(values): return values // error: Cannot convert return expression of type 'String' to return type 'A?'
    ...
}

To solve that we should use less known feature of pattern matching - matching by type:

switch self {
    case let .showProfile(values as A): return values
    case let .follow(values as A): return values
    case let .retweet(values as A): return values
    case let .showUserTweet(values as A): return values
    default: nil
}

This way we only match cases if type of A matches type of case associated values. Otherwise we sink to default case which returns nil.

Now everything compiles, but let's think what will happen if we just return associated values like we do now. Let's assume that we registered route showProfile(userId: String) in our router:

router.add(Routes.showProfile, route: lit("users") /> string >/> lit("profile"))

Let's now try to print url for it.

router.route.print(Routes.showProfile(userId: "username"))

This will result in call Routes.showProfile(userId: "username").deconstruct(Routes.showProfile) which will return "username", as expected. But what if instead we pass in value of Routes.follow("username")?

router.route.print(Routes.follow("username"))

In this case it will call Routes.follow("username").deconstruct(Routes.showProfile). And as the only thing that we are doing is pattern matching we will again return "username", though we should return nil instead as this route was never registered. It means that we need to do something more than just pattern matching - we need to check if the value created by constructor passed to deconstruct is actually the same value on which this method was called. In case they don't match we should return nil as printing should fail, in case they match we return extracted associated value.

switch self {
    case let .showProfile(values as A) where self == constructor(values): return values
    case let .follow(values as A) where self == constructor(values): return values
    case let .retweet(values as A) where self == constructor(values): return values
    case let .showUserTweet(values as A) where self == constructor(values): return values
    default: nil
}

Note: as you can see we only define this method on the cases with associated values, because for cases without associated values we need A to be Void, but there is no way to express it in Swift, and we will just use == operator in this case.

Now we not only make sure that type of associated values match A, but also that enum value created by constructor matches the value that we called deconstruct method on. Which means that we will only get associated values if we pass in to print the same enum value that we passed in to add method:

router.add(Routes.showProfile, route: lit("users") /> string >/> lit("profile"))

let printed = router.route.print(Routes.showProfile(userId: "username"))
// printed = (path: ["users", "username", "profile"], query: [:])

router.add(Routes.follow, route: lit("users") /> string >/> lit("follow"))

let printed = router.route.print(Routes.follow(userId: "username"))
// printed = (path: ["users", "username", "follow"], query: [:])

Cool! Almost there!

Now let's see how do we register route with two parameters:

extension Router {

    @discardableResult
    func add<A, B, S: ClosedPatternState>(_ intent: @escaping ((A, B)) -> U, route: RoutePattern<(A, B), S>) -> Router {
        return add(route.map({ intent($0) }, { $0.deconstruct(intent) }))
    }

}

Exactly the same, except our parameter type is now (A, B). What about three parameters?

extension Router {

    public func add<A, B, C, S: ClosedPatternState>(_ intent: @escaping ((A, B, C)) -> U, route: RoutePattern<((A, B), C), S>) -> Router {
        return add(route.map({ intent($0) }, { $0.deconstruct(intent) }))
    }

}

This will not compile as we have a mismatch between type of enum constructor input values (A, B, C) and type of pattern parameter ((A, B), C). To solve that we need to define functions which will convert these types from one to another:

func flatten<A, B, C>(_ t: ((A, B), C)) -> (A, B, C) {
    return (t.0.0, t.0.1, t.1)
}

func parenthesize<A, B, C>(_ t: (A, B, C)) -> ((A, B), C) {
    return ((t.0, t.1), t.2)
}

flatten method gets "grouped" tuple value and flattens it to a plane tuple. parenthesize do the opposite, it takes "flat" tuple and groups it's element in tuples of two elements. Now we can use these functions to make compiler happy:

extension Router {

    @discardableResult
    func add<A, B, C, S: ClosedPatternState>(_ intent: @escaping ((A, B, C)) -> U, route: RoutePattern<((A, B), C), S>) -> Router {
        return add(route.map({ intent(flatten($0)) }, { $0.deconstruct(intent).map(parenthesize) }))
    }

}

Now we just need to define these methods for 4, 5 and 6 parameters (that should be enough for most cases). And we are done.

Phew! That was a lot of code! A lot of small functions! But it's very satisfying that it works in the end! Let's summarise what we have now.

Conclusion

The main question: is this implementation better than imperative? As always there are some profits and some drawbacks.

Pros:

parsing became way much simpler, especially when it comes to implementing complex patterns like wildcard. It's built with very small functions which are easy to understand and test, and their composition
it's much more type-safe, parameters can be extracted into associated values automatically (almost) instead of aggregating them in weakly typed dictionary where all values are strings and we need to manually convert their types and pass them in enum case constructor
we got printing almost for free

Cons:

we had to use few custom operators instead of one standard (/). I already mentioned a reason for that in the first part - using one operator will produce too many overloads of it and Swift will not be able to compile such expressions. Even with two custom operators compilation sometimes takes more time comparing with if we would use third, >/ operator. Hopefully this will be possible to solve with conditional protocol conformance
as you saw we need to write some boilerplate to get things together for printing URLs. If we don't need printing we can remove it, which will make implementation much easier: we only will need apply functions and we will not need print functions at all
parsing is now based on recursion which can be a bit hard to wrap your head around at first. It can also come with some performance and memory overhead as we are composing functions, but I didn't perform any measurements yet

In the end I'm personally not sure about how much I'm satisfied with results. The main disadvantage for me is use of several custom operators. It's very satisfactory though that I managed to understand how to do it and learned few things along the way about composition and phantom types. Thanks to Brandon Williams again for sharing his code and making this learning opportunity possible!

You can find all the code on github.

URL parser in functional style. Part 1.

Tue, 07 Nov 2017 19:56:35 GMT

When I published one of my previous posts about deeplinks and then decided to turn it into a framework it turned out that Brandon Williams was working on a similar thing for his Point-Free project, but related to parsing http requests for web framework. As parsing URLs is a subset of this problem I decided to go through his implementation and apply the same technique to rewrite parser that I have written in imperative way (and probably not in the best way) in a functional style. Just to see where it goes and as exercise in a functional programming. So here is the path I went through.

Problem

Let's first describe a problem. We want to write a URL parser that will give us a type-safe way to define deeplink "routes" in our app (in my previous post I call them "intents", but I will be using "routes" here). There are few design goals for that:

each route should be defined by enum case that should correspond to some "route pattern". For example we can have our routes defined like this:

enum Routes {
    case showMyProfile
    case showProfile(userId: String)
    case follow(userId: String)
    case retweet(tweetId: Int)
    case showUserTweet(userId: String, tweetId: Int)
}

route can have typed parameters extracted from path components or from query. For routes defined above we can imaging following patterns:

/users/me
/users/:string/profile
/users/:string/follow
/retweet?tweetId=:int
/users/:string/tweets/:int

Here :string or :int stands for parameter of String or Int type. As you can see they can be defined as part of the path or query. When several parameters are defined they should strictly match types and order of associated values in the route case. This way complier will only allow us to associate routes with patterns when their parameter types match.

route can have special patterns like * for matching any path components in the start/end/middle of the path, () for optional parameters, conditional pattern this|that that matches either left or right option
it should be possible to "print" url for specific route based on the pattern it was previously associated with. This way we can not only handle deeplinks but build our entire app navigation based on URLs and perform navigation witch a call to open(url:):

let route = Routes.showUserTweet(userId: "username", tweetId: 123)
let url = router.url(for: route)
// url = "appscheme://users/username/tweets/123"
router.open(url: url)

The ground

To start up we need to define our basic building blocks. This part I find one of the most difficult in functional programming. The basic units are so small but mean so much for a final result that it is very important, but sometimes difficult, to find a proper abstraction. Our abstractions will be the following:

url (or route) components, consisting of array of paths and dictionary of query items.

typealias RouteComponents = (path: [String], query: [String: String])

parser, which is a function that takes in route components and returns the rest of them that it didn't process, along with matched value that it extracted from processed components. If parsing fails it should return nil.

typealias Parser<A> = (RouteComponents) -> (rest: RouteComponents, match: A)?

printer, that based on the input for parameter value returns route components where parameter placeholder (/:string or ?key=:string) is replaced with its value (/abc or ?key=abc). If printing fails it should return nil.

typealias Printer<A> = (A) -> RouteComponents?

route pattern, which contains of parser, printer and a template string:

struct RoutePattern<A, S: PatternState> {
    let parse: Parser<A>
    let print: Printer<A>
    let template: String
}

It has two generic parameters, A for type of parameter and S for state of pattern. This state we will model based on phantom types which we will use to define operations only possible on patterns in specific states.

protocol PatternState {}
protocol ClosedPatternState: PatternState {} // pattern is complete
protocol OpenPatternState: PatternState {} // pattern requires subsequent pattern to become closed

protocol ClosedPathPatternState: ClosedPatternState {}
enum Path: ClosedPathPatternState {} // pattern only has path components
enum Query: ClosedPatternState {} // pattern has path and query components

Here you can see that we not only define that pattern can be in Path or Query state, but also it can be closed or opened. Later we will use opened state to implement * pattern that is used in the start or middle of the pattern.

Path patterns

With these abstractions we can start building our patterns! There can be two types of path patterns:

string path component (or "literal"), i.e. /users
path parameter, i.e. :string

Let's start with a simplest literal pattern.

func lit(_ str: String) -> RoutePattern<Void, Path> {
    return .init(parse: { route in
        guard route.path.first == str else { return nil }
        return ((Array(route.path.dropFirst()), route.query), ())
    }, print: { _ in
        return ([str], [:])
    }, template: str)
}

To parse this pattern we should check if the first path component matches the literal and if it does we should return the rest of components, otherwise we should fail parsing by returning nil. No parameter value will be captured, so pattern parameter type will be Void. Literals can be only used in path, so the state of the pattern will be Path. To print the url we should just put a literal value in a path components. And the template for this pattern is just a literal itself.

With this we can already define pattern that will consist of single path component:

let login = lit("login")
let url = URL(string: "appscheme://login")!

let parsed = login.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), ())

let printed = login.print(())
// printed = (path: ["login"], query: [:])

let template = myProfile.template
// template = "login"

Pretty cool and simple, but not very useful. So let's move on to path parameter pattern.

func pathParam<A>(_ apply: @escaping (String) -> A?, _ unapply: @escaping (A) -> String?) -> RoutePattern<A, Path> {
    return .init(parse: { route in
        guard let pathComponent = route.path.first, let parsed = apply(pathComponent) else { return nil }
        return ((Array(route.path.dropFirst()), route.query), parsed)
    }, print: { a in
        guard let string = unapply(a) else { return nil }
        return ([string], [:])
    }, template: pathParamTemplate(A.self))
}

func pathParamTemplate<A>(_ type: A.Type) -> String {
    return ":\(typeKey(type))"
}

This one is a bit more complicated. For that pattern to be parsed a path component, which is of String type, should be successfully transformed to type A, which can be Int, Double or String. For that transformation we pass in apply function. If this transformation fails or there is no path components left we fail parsing, otherwise we drop first path component and return parsed value for matched result. For printing we need to do a backward transformation, from value of type A to String. For that we use unapply function. For template string we use a simple helper that converts type to it's string representation, i.e. String to :string, Int to :int.

To simplify working with path parameters we will introduce helper functions for each type of parameter which will build up in a small DSL:

let string = pathParam(String.init, String.init)

let int = pathParam(Int.init, String.init)

let double = pathParam(Double.init, String.init)

Here we provide constructors from standard library to perform transformations between type of parameter and String. With that we can define a simple route with a single path parameter.

let url = URL(string: "appscheme://123")!

let parsed = int.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), 123)

let printed = int.print(123)
// printed = (path: ["123"], query: [:])

let template = int.template
// template = ":int"

Again cool and simple, but still not very useful.

Patterns composition

To make this really useful and before we continue with query patterns we need to define a way to combine different patterns so that we can build bigger patterns.

For that we will use function composition. Route patterns essentially are just boxes of pure parser and printer functions, so they can be easily composed together. Let's look at how we can compose parsers.

func parseBoth<L, R, LS, RS>(_ lhs: RoutePattern<L, LS>, _ rhs: RoutePattern<R, RS>) -> Parser<(L, R)> {
    return { route in
        guard let lhsResult = lhs.parse(route) else { return nil }
        guard let rhsResult = rhs.parse(lhsResult.rest) else { return nil }
        return (rhsResult.rest, (lhsResult.match, rhsResult.match))
    }
}

Here we define a function that accepts two route patterns of any parameter type (and of any state) and returns a new parser that parses both of those patterns' values in a tuple. For that we first parse route components using left pattern, then if it succeeds we get the rest of path components and parse them with a right pattern. If it also succeeds we return the rest of path components and match result of both left and right patterns.

Printer composition is done pretty much the same way:

func printBoth<L, R, LS, RS>(_ lhs: RoutePattern<L, LS>, _ rhs: RoutePattern<R, RS>) -> Printer<(L, R)> {
    return {
        guard let lhs = lhs.print($0.0), let rhs = rhs.print($0.1) else { return nil }
        return (lhs.path + rhs.path, lhs.query.merging(rhs.query, uniquingKeysWith: { $1 }))
    }
}

We again get two patterns and first use left pattern to print route components using left tuple value, then we use right pattern to print route components using right tuple value. If both succeed we merge the results.

Template composition is a bit different, as template is not a function but just a String, but it is even simpler:

func templateAnd<A, B>(_ lhs: RoutePattern<A, Path>, _ rhs: RoutePattern<B, Path>) -> String {
    return "\(lhs.template)/\(rhs.template)"
}

We just get templates of both patterns and concatenate them with /. Another difference here is that this function can only be applied to patterns in Path state, because of different separators for path components (/) and for query components (? or &). This is one of examples of phantom types usage.

With all that we now can define a function that will "concatenate" two patterns. For that we will introduce a custom operator, so that writing it will feel more natural.

infix operator >/> : MultiplicationPrecedence

extension RoutePattern where S == Path {
    static func >/><B>(lhs: RoutePattern, rhs: RoutePattern<B, S>) -> RoutePattern<(A, B), S> {
        return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
    }
}

Again we use phantom type here to constrain this operation to patterns only in Path state. Implementation is trivial, we use functions that we defined before to compose parsers, printers and templates and construct a new pattern with them. What we get with this is pretty cool though. Now we can combine two patterns into one which will internally parse or print both of them and will only succeed in parsing or printing of both of them succeed. We already can build patterns for 4 of 5 routes that we defined in the beginning.

let profileRoute = lit("users") >/> string >/> lit("profile")
let url = URL(string: "appscheme://users/username/profile")

let parsed = int.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), (((), "username"), ()))

let printed = int.print((((), "username"), ()))
// printed = (path: ["users", "username", "profile"], query: [:])

let template = int.template
// template = "users/:string/profile"

Pretty cool! Though you can spot a nasty issue here. Every time when we compose two patterns with parameter types A and B we will end up with a new pattern with parameter type (A, B). If we now compose it with another pattern with parameter type C we will get pattern with type ((A, B), C). And so on. So parsing in this example will give us a value of ((Void, String), Void). But then we need to use this value somehow to create a case of route, as this should be the result of our "pattern matching". For this example it is showProfile(userId: String). You can see that type of pattern parameter and type of route associated values do not match. We can of course redefine our route as showProfile(((Void, String), Void)) but this is just ugly and unusable. How we can solve that?

With another custom operator! Well, to be fair, operators here are just helpers to provide more natural way of composing patterns, the solution for the problem is again in function composition.

When parsing literal patterns we are not very interested in Void matching result. It is just placeholder for generic type parameter. So let's drop it! To do that we need to handle three cases: when we have Void type on the left, on the right and on both sides. Here is our parsers composition for these cases:

func parseLeft<L, LS, RS>(_ lhs: RoutePattern<L, LS>, _ rhs: RoutePattern<Void, RS>) -> Parser<L> {
    return { route in
        guard let result = parseBoth(lhs, rhs)(route) else { return nil }
        return (result.rest, result.match.0)
    }
}

func parseRight<R, LS, RS>(_ lhs: RoutePattern<Void, LS>, _ rhs: RoutePattern<R, RS>) -> Parser<R> {
    return { route in
        guard let result = parseBoth(lhs, rhs)(route) else { return nil }
        return (result.rest, result.match.1)
    }
}

parseLeft function parses both left and right parser, but only returns matched value of left pattern. parseRight does the same but returns matched value of right pattern. In case we have patterns with Void parameter type on both sides we can use either of these functions because it does not matter if we return Void from left or right pattern.

Printers composition will be a bit different:

func printLeft<L, LS, RS>(_ lhs: RoutePattern<L, LS>, _ rhs: RoutePattern<Void, RS>) -> Printer<L> {
    return { printBoth(lhs, rhs)(($0, ())) }
}

func printRight<R, LS, RS>(_ lhs: RoutePattern<Void, LS>, _ rhs: RoutePattern<R, RS>) -> Printer<R> {
    return { printBoth(lhs, rhs)(((), $0)) }
}

Again we pass in left and right pattern, but we want a printer that will print both of them, but will only need left or right value as input. As we need values for both patterns to pass to printBoth printer we just create Void value inline.

We don't need to change anything in templates composition as it works already who we need it to work, so let's now define pattern composition:

infix operator /> : MultiplicationPrecedence

extension RoutePattern where S == Path {

    static func />(lhs: RoutePattern<Void, S>, rhs: RoutePattern) -> RoutePattern {
        return .init(parse: parseRight(lhs, rhs), print: printRight(lhs, rhs), template: templateAnd(lhs, rhs))
    }

    static func >/>(lhs: RoutePattern, rhs: RoutePattern<Void, S>) -> RoutePattern {
        return .init(parse: parseLeft(lhs, rhs), print: printLeft(lhs, rhs), template: templateAnd(lhs, rhs))
    }

}

We introduce new operator /> that will be used to drop left side parameter value and will be only applicable when left pattern has Void parameter type. It will return pattern with only right parameter type, we achieve that by using parseRight and printRight functions.

For the case when pattern with Void parameter type is on the right side we reuse >/> operator, using parseLeft and printLeft functions.

Note: I decided to reuse >/> operator here for two reasons. One is that it's better if you make user to use less custom operators. Second is that it should be easy to remember that left > in this operator means that left parameter type will be preserved in contrast to /> operator. I could define >/ operator but it will make users think about what operator to use where. With /> and >/> you end up with /> only used before you introduce parameter pattern, after it you'll always use >/>. I also can't use just >/> or /> always as I will have too many overloads of it, which will make expressions to complex for Swift compiler.

Let's now see what we can do with that.

let profileRoute = lit("users") /> string >/> lit("profile")
let url = URL(string: "appscheme://users/username/profile")

let parsed = profileRoute.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), "username")

let printed = profileRoute.print("username")
// printed = (path: ["users", "username", "profile"], query: [:])

let template = profileRoute.template
// template = "users/:string/profile"

Now our profileRoute will have type RoutePattern<String, Path> and we will only get single matched value from parse and need to provide only single value to print function. The same applies when we have only literal patterns:

let myProfile = lit("users") /> lit("me")
let url = URL(string: "appscheme://users/me")

let parsed = myProfile.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), ())

let printed = myProfile.print(())
// printed = (path: ["users", "me"], query: [:])

let template = myProfile.template
// template = "users/me"

Here pattern type will be RoutePattern<Void, Path> instead of RoutePattern<(Void, Void), Path> if we would use >/> operator.

Query patterns

Now lets move on to query patterns. In queries we can only have parameter patterns, but the difference is that they are named and come in as a dictionary with their names as keys.

func queryParam<A>(_ key: String, _ apply: @escaping (String) -> A?, _ unapply: @escaping (A) -> String?) -> RoutePattern<A, Query> {
    return .init(parse: { route in
        guard let queryValue = route.query[key], let parsed = apply(queryValue) else { return nil }
        return (route, parsed)
    }, print: { a in
        guard let value = unapply(a) else { return nil }
        return ([], [key: value])
    }, template: queryParamTemplate(A.self, key: key))
}

func queryParamTemplate<A>(_ type: A.Type, key: String) -> String {
    return "\(key)=:\(typeKey(type))"
}

This is pretty much the same as parsing path parameters except that we are passing in the key for parameter name. We also don't necessary have to drop query components when they are parsed as we should allow any other query components in the url besides those defined in pattern. Another difference is that result of this function is a pattern in a Query state.

To make it easier to use this function we can define few helper methods for each of query parameter types, similar to what we did for path pattern:

func int(_ key: String) -> RoutePattern<Int, Query> { return queryParam(key, Int.init, String.init) }

func double(_ key: String) -> RoutePattern<Double, Query> { return queryParam(key, Double.init, String.init) }

func bool(_ key: String) -> RoutePattern<Bool, Query> { return queryParam(key, Bool.fromString, Bool.toString) }

func string(_ key: String) -> RoutePattern<String, Query> { return queryParam(key, String.init, String.init) }

Now we can define pattern composition:

infix operator .? : MultiplicationPrecedence

extension RoutePattern where S == Query {

    static func .?(lhs: RoutePattern<Void, Path>, rhs: RoutePattern) -> RoutePattern {
        return .init(parse: parseRight(lhs, rhs), print: printRight(lhs, rhs), template: templateAnd(lhs, rhs))
    }
    
    static func .?<B>(lhs: RoutePattern<B, Path>, rhs: RoutePattern) -> RoutePattern<(B, A), Query> {
        return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
    }

    static func &<B>(lhs: RoutePattern, rhs: RoutePattern<B, Query>) -> RoutePattern<(A, B), Query> {
        return .init(parse: parseBoth(lhs, rhs), print: printBoth(lhs, rhs), template: templateAnd(lhs, rhs))
    }

}

func templateAnd<A, B, S: ClosedPathPatternState>(_ lhs: RoutePattern<A, S>, _ rhs: RoutePattern<B, Query>) -> String {
    return "\(lhs.template)?\(rhs.template)"
}

func templateAnd<A, B>(_ lhs: RoutePattern<A, Query>, _ rhs: RoutePattern<B, Query>) -> String {
    return "\(lhs.template)&\(rhs.template)"
}

Similarly to what we did to drop Void parameter type in path patterns we define a function that will drop Void parameter of the left path pattern and will only return value of right query pattern. We also define two new variants of templateAnd function that uses proper separators between path and query.

Now we can build patterns not only with path components but also with query:

let retweetRoute = lit("retweet) .? int("tweetId")
let url = URL(string: "appscheme://retweet?tweetId=123")!

let parsed = retweetRoute.parse(url.routeComponents)
// parsed = ((path: [], query: [:]), 123)

let printed = retweetRoute.print(123)
// printed = (path: ["retweet"], query: ["tweetId": 123])

let template = retweetRoute.template
// template = "retweet?tweetId=:int"

Conclusion

I think this should be enough for the first part. We already achieved a lot. We can construct simple and more complicated patterns made of few smaller patterns, both with path and query parameters, and we solved the issue with unneeded Void types.

If that's not too much code for you already, see you in the second part.
You can find all the code on github.

Swift 4 tricky filters

Tue, 26 Sep 2017 07:46:10 GMT

This is a short story of a regression in Swift 4 that I've recently had to deal with. It can seem as a simple problem, but I think it's a good example of unexpected regression caused by a positive change in a language standard library.

First - a bit of a context. In my current project we extensively use Eureka framework to build forms. Most of the time values in our forms are selected from a list of options. For this purpose Eureka has a special type of section - SelectableSectionType. There is also a base class Section that represents a collection of rows. To make working with rows and sections easier this type implements protocols that allow us to work with it as with a collection of rows, like if it was a plain array. One of these protocols is RangeReplaceableCollection which simplifies inserting and removing rows from the section. I would not describe here all the machinery behind it but I will show some parts of this implementation to showcase the issue.

Any Section that implements SelectableSectionType handles rows selection that can be setup with multiple or single selection option. In case of a single selection implementation goes through all the rows of this section and clears the value of the row that was selected previously, which removes selection indicator from its cell, and sets the value of the row for the new selection (selected row is determined by non-nil value). For that it is using combination of filter and forEach methods:

extension SelectableSectionType where Self: Section {

    func prepare(selectableRows rows: [BaseRow]) {
        for row in rows {
            ...
            row.onCellSelection { [weak self] cell, row in
                guard let s = self, !row.isDisabled else { return }
                switch s.selectionType {
                case .multipleSelection: ...
                case let .singleSelection(enableDeselection):
                    // clear baseValue for all rows except selected
                    s.filter { $0.baseValue != nil && $0 != row }.forEach {
                        $0.baseValue = nil
                        $0.updateCell()
                    }
                    // update value of selected row
                }
            }
        }
    }
}

This code works fine with Swift 3, but with Swift 4 selection started to behave "weird": as soon as you select new option it was not possible to select previous option any more.

Debugging this issue lead to discovery that after option was deselected and then selected again row.onCellSelection closure was still called, as expected, but guard expression was not passing any more, specifically because self was nil. As in this context self is a reference to Section it would mean that the section was at some point deallocated. row.section which should contain a reference to the section where row was added to, was also nil at this point. But as other rows were behaving correctly it could only mean that they were referencing different sections, and one of them was at some point deallocated.

And indeed adding deinit method to Section and adding a breakpoint there clearly demonstrated that some instance of section was being deallocated. What was still surprising is that deinit was called even before row.onCellSelection closure completed. Instead it was called right after forEach returned.

My first guess was to blame some bug related to ARC, but it turned out to be related to SE-0174. According to this proposal a new version of filter method was added to RangeReplaceableCollection which is returning Self instead of [Self.Element] as defined in Swift 3. This method has a default implementation:

extension RangeReplaceableCollection {

    public func filter(
        _ isIncluded: (Element) throws -> Bool
    ) rethrows -> Self {
        return try Self(self.lazy.filter(isIncluded))
    }

}

extension RangeReplaceableCollection {

    public init<S : Sequence>(_ elements: S)
        where S.Element == Element {
        self.init()
        append(contentsOf: elements)
    }

}

RangeReplaceableCollection already requires init initialiser on implementing type which made this implementation possible.

And indeed init and append methods of Section were called in this case. As you can see it was resulting in updating row.section property. At the same time using KVO it was calling prepare(selectableRows:) when row was added to the section, which resulted in overriding onCellSelection for this row.

extension Section: RangeReplaceableCollection {
    public func append<S: Sequence>(contentsOf newElements: S) where S.Iterator.Element == BaseRow {
        kvoWrapper.rows.addObjects(from: newElements.map { $0 }) // triggers KVO invocation
        ...
        for row in newElements {
            row.wasAddedTo(section: self)
        }
    }
}

extension BaseRow {
    final func wasAddedTo(section: Section) {
        self.section = section
        ...
    }
}

And as the section reference in row is weak and a new section was just created by filter method, this instance was deallocated as soon as code was escaping the only context that has a strong reference to it, which is a subsequent forEach call.

The fix for this issue is much simpler then debugging it. One of the option is to stop using filter:

s.forEach {
    guard $0.baseValue != nil && $0 != row else { return }
    $0.baseValue = nil
    $0.updateCell()
}

Another option is to explicitly specify return type of filter method so that Swift 3 variant is used:

s.filter { $0.baseValue != nil && $0 != row } as [BaseRow]

Both of these options will result in array of rows being created instead of new Section which will not lead to all of its side effects, in this case unneeded. Luckily none of the rest of Eureka's code was affected as in other places where filter was used its return type was already explicitly set to array.

This was a tricky issue and a fun hunt! I hope this write-up will help me and you to avoid such bugs in future. And as always thanks to Joe Groff for being so helpful and responsive on Twitter.

Deep links with no brainer

Wed, 06 Sep 2017 20:16:00 GMT

Very often in my practice deep links were something that no one cares much, they work somehow and its fine. Or there are just few of them and its really not hard to maintain. But working for a long time on one product that targets several very different markets reveals all the importance of deep links in a long run. There are always requests from marketing teams to support new kind of deep link for a new marketing campaign, to open some new screen in the app from push notification, or with some specific parameters, when existing deep link can't be reused for what ever reason and you have to create yet another one for the same action. In the modern app there are also all kinds of different sources of urls that should act like a deep link to your app - universal links, push notifications, shortcut items etc.

Unless your app's navigation is architectured entirely around URLs, when you basically get deep links handling for free, it can very fast become a nightmare to maintain. Bad deep links implementations can suffer from different severe issues, sometimes few of them at the same time:

it is usually heavily stringly typed
warm and cold state handling is fragile and unpredictable, sometimes everything works, sometime - fails miserably
its hard to debug, requires to step through each line of code
impossible to see what deep links are handled on the screen just by glancing at code
no tracking, no error reporting, no logging
no tests
something breaks almost with each release and is discovered much later

In this post I'll describe an approach for deep links handling that I've just recently came up with trying to address all aforementioned issues. The main design goals of this approach are:

reliability, deep links should not break, or at least should break less
readability, it should be clear how deep links are handeled
testability, it should be easier to unit test deep links
tracking, it should be easier to track deep link handling, both during debuggin and in production

Probably most obvious solution would be just to present final screens modally from what ever place in the app, or to push it on top of the current navigation stack. If that would be the case there wouldn't be this post in the first place. You still would need to handle different states of view hierarchy but things will become much easier comparing to the case when opening deep link should involve navigation to intermediate screens, like if user would navigate to them themselves. So keep in mind that it's the case.

Solution involves several action points. First, deep links should be described in a type safe manner, avoiding stringly typing as much as possible. This can be achieved by using enums or structs. Next, state of deep link handling should be stored in memory and this information should be descriptive. Again enums come for the rescue. It should be possible to track this state for error and successful scenarious. Deep links routes registration should be clear from side effects, like opening modal screens or switching tabs, to make it easier to unit test. Finally handling deep links from a cold and warm start should be done in a predictable way by always starting it from a single point and then sinking deep link through the application's screens graph.

Strongly typed deep links

Each deep link is represented with an url and an intent that is modelled by enum with associated values. You should aim to have as little deep links variations as possible and having too many cases in the enum will help you to assert that. This intent cases describe actions which should be performed as a result of deep link handling, usually opening some screen in the app.

struct DeepLink {
    let url: URL
    let intent: Intent
    
    enum Intent {
        case showRecipe(recipeId: String)
        case editMenu(subscriptionId: String, weekOrMenuId: Either<Int, String>)
        case showSubscription(subscriptionId: String, week: Int)
        ...
    }
    
}

add(routes: [
    "subscription/:subscriptionId/swap/:menuId",
    "subscription/:subscriptionId/:weekId/edit"
    ]) { params -> DeepLink.Intent? in
        ...
}

Alternatively deep link can be described with a protocol and multiple structs (or classes if you want) implementing this protocol. When handeled, instead of switching over intent we will switch over type of deep link, which is basically the same.

protocol DeepLink {
    var url: URL { get }
    static var routes: [String] { get }
    static var authorized: Bool { get }
    
    init?(url: URL, dictionary: [String: String])
}

struct MealSwapDeepLink: DeepLink {

    static let routes: [String] = [
        "subscription/:subscriptionId/swap/:menuId",
        "subscription/:subscriptionId/:weekId/edit"
    ]
    
    static let requiresAuthorization = true

    let url: URL
    let subscriptionId: String
    let menuOrWeekId: Either<Int, String>
    
    init?(url: URL, dictionary: [String: String]) {
        ...
    }
    
}

Using protocol approach can give more flexibility (Swift enums are relatively rigid and limited), isolate unrelated deep links from each other in separate files, what can be considered as a drawback though. But it also comes with drawbacks like possible types explosion and more boilerplate to write.
Enum approach on the other hand looks cleaner and requires less boilerplate. Also if you already use libraries like JLRoutes it will require less changes to the code structure.
They both suffer from violation of Open-Closed Principle, but it feels like trying to solve this will unnecessary complicate the implementation.

The rest of code examples will be based on enums approach.

State of deep link handling

Deep link handling state can be also represented as enum. Having a custom type for that will give you more control over it.

enum DeepLinkHandling: CustomStringConvertible {

    // deeplink successfully handled
    case opened(DeepLink)

    // deeplink was rejected because it can't be handeled, with optional log message
    case rejected(DeepLink, String?)

    // deeplink handling delayed because more data is needed
    case delayed(DeepLink, Bool)

    // deeplink was passed through to some other handler
    case passedThrough(to: DeepLinkHandler, DeepLink)
    
    var description: String {
        switch self {
        case .opened(let deeplink):
            return "Opened deeplink \(deeplink)"
        case .rejected(let deeplink, let reason):
            return "Rejected deeplink \(deeplink) for reason : \(reason ?? "unknown")"
        case .delayed(let deeplink, _):
            return "Delayed deeplink \(deeplink)"
        case .passedThrough(let handler, let deeplink):
            return "Passed through deeplink \(deeplink) to \(type(of: handler))"
        }
    }
}

With such type you can describe each state of deep link handling that you can be interested in (you might need some more cases depending on the architecture of your app, but you got the idea), and will be able to associate with it any information usefull for tracking or logging.

Deep link handler

DeepLinkHandler protocol describes set of requirements for view controller (typically) to implement in order to take part in deep link handling process. It requires just one stored property and one method to implement.

protocol DeepLinkHandler: class {
    // stores the current state of deeplink handling
    var deeplinkHandling: DeepLinkHandling? { get set }
    // attempts to handle deeplink and returns next state
    func open(deeplink: DeepLink, animated: Bool) -> DeepLinkHandling
}

When implementing this protocol you will only care about these requirements, logic to handle state changes will be implemented in a default implementations in extension of this protocol. open(deeplink:animated:) method also is not intended to be called manually from your code - again it will be called from default implementation of the protocol.

extension DeepLinkHandler {
    
    // Attempts to handle deeplink and updates its state, 
    // should be always called instead of method that returns state
    func open(deeplink: DeepLink, animated: Bool) {
        let result = open(deeplink: deeplink, animated: animated)
        log.debug(result)
        // you can track rejected or opened deeplinks here too
        deeplinkHandling = result
        
        if case let .passedThrough(handler, deeplink) = result {
            handler.open(deeplink: deeplink, animated: animated) as Void
        }
    }
    
    // Call to complete deeplink handling if it was delayed
    func complete(deeplinkHandling: DeepLinkHandling?) {
        if case let .delayed(deeplink, animated)? = deeplinkHandling {
            open(deeplink: deeplink, animated: animated) as Void
            if case .delayed? = self.deeplinkHandling { return }
        }
    }
}

Simplest implementation of this protocol will just return opened or rejected states.

extension RecipeFlowController: DeepLinkHandler {

    func open(deeplink: DeepLink, animated: Bool) -> DeepLinkHandling {
        switch deeplink {
        case .showRecipe(let recipeId):
            showRecipe(withId: recipeId)
            return .opened(deeplink)
        default:
            // none of other deeplinks can be handled by this controller
            // we can also do assertionFailure here
            // because it's most likely programmer's error:
            // either deeplink handling is missing
            // or wrong screen was asked to handle deeplink
            return .rejected(deeplink, nil)
        }
    }

}

More complicated implementation with delayed handling and several screens involved in deep link handling:

extension MyMenuNavigationController: DeepLinkHandler {

    func open(deeplink: DeepLink, animated: Bool) -> DeepLinkHandling {
        // if view is not loaded yet we should probably wait for it
        guard isViewLoaded else { .delayed(deeplink, animated) }
            
        switch deeplink.intent {
        case 
            .editMenu(let subscriptionId, _),
            .showSubscriptions(let subscriptionId):

            guard subscriptions != nil else {
                // wait until subscriptions are loaded somewhere else or trigger loading here
                return .delayed(deeplink, animated)
            }

            if let subscription = subscriptionWithId(subscriptionId) {
                return showSubscription(subscriptionId, toOpen: deeplink, animated: animated)
            } else {
                // we can return specific error to improve logging and tracking of errors
                return .rejected(deeplink, .noSuchSubscription(subscriptionId))
            }
        default:
            return .rejected(deeplink, nil)
        }
    }
    
    func viewDidLoad() {
        super.viewDidLoad()
        ...
        complete(deeplinkHandling: deepLinkHandling)
    }
    
    func showSubscription(subscriptionId: String, toOpen deeplink: DeepLink, animated: Bool) -> DeepLinkHandling {
        let subscriptionViewController = showSubscription(subscriptionId, animated: animated)
        // pass deeplink further to next screen
        return .passedThrough(to: subscriptionViewController, deeplink)
    }
    
    func loadData() {
        dataProvider.loadSubscriptions() { [weak self] subscriptions, error in
            // at some point when we want to retry any delayed deeplink
            self?.complete(deeplinkHandling: self!.deeplinkHandling)
        }
    }

}

extension SubscriptionViewController: DeepLinkHandler {
    
    func open(deeplink: DeepLink, animated: Bool) -> DeepLinkHandling {
        switch deeplink.intent {
        case .showSubscription(_, let week):
            // navigate to requested view and do nothing
            return switchToWeekOrMenuId(.init(week), toOpen: deeplink, animated: animated, completion: {
                .opened(deeplink)
            })
        case .editMenu(_, let weekOrMenuId):
            // go to requested week and proceed to meal swap
            return switchToWeekOrMenuId(weekOrMenuId, toOpen: deeplink, animated: animated, completion: { [weak self] in
                if self?.canEditMenu == true {
                    self?.showEditMenu(toOpen: deeplink, animated: animated)
                    return .opened(deeplink)
                } else {
                    return .rejected(deeplink, .cantEditMenu)
                }
            })
        default:
            return .rejected(deeplink, nil)
        }
    }
    
    func switchToWeekOrMenuId(_ weekOrMenuId: Either<Int, String>, toOpen deeplink: DeepLink, animated: Bool, completion: () -> DeepLinkHandling) -> DeepLinkHandling {
        switch weekOrMenuId {
        case .left(let week):
            if self.week != week {
                switchToWeek(week)
                return .delayed(deeplink, animated)
            } else {
                return completion()
            }
        case .right(let: menuId):
            if menu.id != menuId {
                getMenuWeekByMenuId(menuId) { [weak self] week in
                    self?.switchToWeek(week)
                    //or we can transform link to one with week and try to open it
                }
                return .delayed(deeplink, animated)
            } else {
                return completion()
            }
        }
    }
    
    func switchedToWeek(_ week: Int) {
        // called somewhere later when we navigated to requested week
        complete(deeplinkHandling: deeplinkHandling)
    }
    
}

With this implementation it is more clear what deep links are handled on the screen, because they will be clearly stated in switch, and even how the state transitioning happens. Descriptive names for these states and additional console logs also improve debugging experience. Assertions that might be used here will help to catch bugs faster during development.

Deep links registration

Deep link routes registration should be clear of side effects (calling deep link handler to handle matched deep link) which can be performed implicitly by router (object that is responsible for keeping track of registered deep links routes and match them with incoming deep links, invoking registered handler closure as a side effect, consider mentioned JLRoutes as example). It makes testing deep links parsing much simpler.

class HFRoutes: JLRoutes {

    override init() {
        add(route: "recipe/:recipeId") { params in
            return .recipe(params["recipeId"] as! String)
        }

        addAuthorized(routes: [
                "subscription/:subscriptionId/swap/:menuId",
                "subscription/:subscriptionId/:weekId/edit"
            ]) { params in

            guard let subscriptionId = params["subscriptionId"] as? String else { return nil }

            if let menuId = params["menuId"] as? String {
                return .editMenu(subscriptionId, .init(menuId))
            } else if let weekId = params["weekId"] as? String, let week = Int(string: weekId) {
                return .editMenu(subscriptionId, .init(week))
            } else {
                return nil
            }
        }
    }

}

This can be also done in a more type safe manner without using strings for parameters names. This will help to avoid typos when defining pattern and parsing its parameters.

enum DeepLinkPathComponent: String {
    case recipeId
    case subscriptionId
    case menuId
    case weekId
}

// some custom operators to build url patterns using strings and components
// private to not pollute the scope of the rest of the app

private func /(lhs: String, rhs: String) -> String {
    return "\(lhs)/\(rhs)"
}

private func /(lhs: String, rhs: DeepLinkPathComponent) -> String {
    return "\(lhs)/:\(rhs.rawValue)"
}

private func /(lhs: DeepLinkPathComponent, rhs: String) -> String {
    return ":\(lhs.rawValue)/\(rhs)"
}

extension HFRoutes {
    
    private func parse(params: [String: Any]) -> [DeepLinkPathComponent: String] {
        var _params: [DeepLinkPathComponent: String] = [:]
        for (key, value) in params {
            guard let component = DeepLinkPathComponent(rawValue: key) else { continue }
            _params[component] = String(describing: value)
        }
        return _params
    }
    
    func add(routes: [String], handler: ([DeepLinkPathComponent: String]) -> DeepLink.Intent?) {
        add(routes: routes) { params in 
            return handler(parse(params: params)) != nil
        }
    }

}

add(route: "recipes" / .recipeId) { params in 
    if let recipeId = params[.recipeId] {
        return .recipe(recipeId)
    } else {
        return nil
    }
}

addAuthorized(routes: [
    "subscription" / .subscriptionId / "swap" / .menuId,
    "subscription" / .subscriptionId / .weekId / "edit"
]) { params in
    
    if let subscriptionId = params[.subscriptionId], let menuId = params[.menuId] {
        return .editMenu(subscriptionId: subscriptionId, menuIdOrWeekId: .init(menuId))
    }
    if let subscriptionId = params[.subscriptionId], let weekId = params[.weekId], let week = Int(string: weekId) {
        return .editMenu(subscriptionId: subscriptionId, menuIdOrWeekId: .init(week))
    }
    return nil
}

String path components can also be extracted to the enum but this will not give as much as in case of parameters which are most likely used repeatedly across different patterns.

Cold and warm start

To make deep link handling predictable no matter in what state the app is, handling deep link should always start from the same point - root handler. This root handler can be an app delegate (and mock in unit tests). To always start deep link handling with app delegate it should be stored as a week reference in a router:

class HFRoutes {

    weak private(set) var rootDeepLinkHandler: DeepLinkHandler?
    
    init(rootDeepLinkHandler: DeepLinkHandler?) {
        self.rootDeepLinkHandler = rootDeepLinkHandler
        super.init()
        registerRoutes()
    }

    func add(routes: [String], handler: ([DeepLinkPathComponent: String]) -> DeepLink.Intent?) {
        add(routes: routes) { params in 
            guard let intent = handler(parse(params: params)) else { return false }
            let url = URL(string: params[kJLRouteURLKey] as! String)!
            let deeplink = DeepLink(url: url, intent: intent)
            rootDeeplinkHandler?.open(deeplink: deeplink, animated: true) as Void?
            return true
        }
    }
    
}

In case of cold start it's usual that the app needs to perform some launch routine, i.e. restore previously stored user session. During this routine you can present some LaunchViewController as a root view controller of the key window. In this case app delegate can handle deep links itself, delaying all of them until launch routine is finished. When launch is done app delegate completes its deep link handling and passes it through to newly installed root view controller (HomeViewController).

extension AppDelegate: DeepLinkHandler {

    lazy private(set) var router: HFRoutes! = HFRoutes(rootDeepLinkHandler: self)

    func open(deeplink: DeepLink, animated: Bool) -> DeepLinkHandling {
        switch deeplink.intent {
        case .registerForPushNotifications:
            // deeplinks which do not require any UI changes
            // can be handled by app delegate itself
            registerForPushNotifications()
        default:
            // all other deeplinks handling involves UI changes
            if let deeplinkHandler = keyWindow?.rootViewController as? DeepLinkHandler {
                return .passedThrough(to: deeplinkHandler, deeplink, animated))
            } else {
                return .delayed(deeplink, animated)
            }
        }
    }
    
    // can be called from LaunchViewController via delegate or trigerred with a notification
    func applicationDidFinishLaunchingRoutine(...) {
        ...
        self.complete(deeplinkHandling: deeplinkHandling)
    }

}

In case of "warm" start HomeViewController will be already a root view controller, so app delegate will delegate deep link handling to it right away. HomeViewController can i.e. switch to correct tab and will pass deep link further.

extension HomeViewController: DeepLinkHandler {

    func open(deeplink: DeepLink, animated: Bool) -> DeepLinkHandling? {
        switch deeplink.intent {
        case .showRecipe:
            return selectTab(.explore, toOpen: deeplink, animated: animated)
        case .editMenu, .showSubscription:
            return selectTab(.mymenu, toOpen: deeplink, animated: animated)
        }
    }
    
    func selectTab(_ tab: HomeTab, toOpen deeplink: DeepLink, animated: Bool) -> DeepLinkHandling {
        selectTab(tab, animated: animated)
        guard let deeplinkHandler = selectedViewController as? DeepLinkHandler else { return .rejected(deeplink, nil) }
        return .passedThrough(to: deeplinkHandler, deeplink, animated)
    }
}

This way the flow of deep link handling will be always predictable and application state (cold or warm start) related logic will be concentrated in one place in the app delegate.

Next steps

We can make one step further in the direction of removing side effects from the methods that handles deep links. By adding additional associated value of closure type to some DeppLinkHandling cases we can postpone a bit execution of the side effect required to handle a deep link and make open(deeplink:animated) -> DeepLinkHandling even more free of side effects. Side effect will be performed by default implementation of open(deeplink:animated) method. In unit tests we don't care about this method, unless we want to validate side effect itself, and to test logic in open(deeplink:animated) -> DeepLinkHandling becomes even simpler.

enum DeepLinkHandling {
    case opened(DeepLink, ((Bool) -> Void)?)
    case rejected(DeepLink, Error?)
    case delayed(DeepLink, Bool, ((Bool) -> Void)?)
    case passedThrough(DeepLink, ((Bool) -> DeepLinkHandler)?)
}

extension DeepLinkHandler {

    func open(deeplink: DeepLink, animated: Bool) {
        let result = open(deeplink: deeplink, animated: animated)
        log.debug(result)
        // you can track rejected or opened deeplinks here too
        deeplinkHandling = result
        
        switch result {
        case let .opened(_, sideEffect?):
            sideEffect(animated)
        case let .delayed(_, _, sideEffect?):
            sideEffect(animated)
        case let .passedThrough(deeplink, sideEffect?):
            if let handler = sideEffect(animated) {
                handler.open(deeplink: deeplink, animated: animated) as Void
            }
        default: break
        }
    }

}

Bonus

Additionaly you can use Sourcery to code generate all the boilerplate. It can be also used to generate README file with supported links or html page to use for manual testing.

enum Intent {
    // sourcery: deeplink_route = recipe/:recipeId
    // sourcery: deeplink_route = account/recipe/:recipeId
    case showRecipe(recipeId: String)
    
    // sourcery: deeplink_route = subscription/:subscriptionId/swap/:menuId
    // sourcery: deeplink_authorized
    case editMenu(subscriptionId: String, menuId: String)
    
    // sourcery: deeplink_route = subscription/:subscriptionId/:week/edit
    // sourcery: deeplink_authorized
    case editMenuForWeek(subscriptionId: String, week: Int)
}

// auto-generated code

add(routes: [
    "recipe/:recipeId",
    "account/recipe/:recipeId"
    ]) { params in
    guard let recipeId = params["recipeId"] as? String else { return nil }
    return .showRecipe(recipeId: recipeId)
}

addAuthorized(routes: [
    "subscription/:subscriptionId/swap/:menuId"
]) { params in 
    guard let subscroptionId = params["subscriptionId"] as? String else { return nil }
    guard let menuId = params["menuId"] as? String else { return nil }
    return .editMenu(subscritionId: subscriptionId, menuId: menuId)
}

addAuthorized(routes: [
    "subscription/:subscriptionId/:week/edit"
]) { params in 
    guard let subscriptionId = params["subscriptionId"] as? String else { return nil }
    guard let week = (params["week"] as? String).map(Int.init(string:)) else { return nil }
    return . editMenuForWeek(subscritionId: subscriptionId, week: week)
}

Conclusion

With all this deep links code should become no brainer. It can be also a first step for implementing navigation in your app entirely based on the URLs, where open(deeplink:animated) method will become the main entry point of each controller. This will not only give you deep links support out of the box, but will also force you to isolate controllers from each other, minimising data flow between them.

Tell me what you think in the comments!

Swift enums with associated values defaults

Fri, 24 Mar 2017 10:01:21 GMT

In Swift enums are much more powerful than we got used to in other languages. One of the features that makes them more interesting to use is associated values - values that each instance of enum case can carry along with it. We can not have stored properties in the enum, so associated values is basically the only way to store additional data with enum value. Creating an enum value with associated value has a similar semantics as a method call. The difference is - we can not define defaults for parameters which represent associated values.

Here is a real-life example. I was implementing a custom popover presentation for which I have a relative position, view to present popover from and an inset from it along with several other parameters. First I had all of these properties defined as a separate method parameters:

public class PopoverPresentationController {
    public init(presentedViewController: UIViewController,
                presenting presentingViewController: UIViewController?,
                position: PopoverPosition = .center,
                inset: CGFloat = 8,
                fromView: UIView? = nil,
                passThrough: Bool = false,
                dimBackground: Bool = false,
                onTouchOut: (() -> Void)? = nil) {
    ...
    }
}

First there were just few constructor parameters, but soon their number grow. It was time to refactor. Usual way to solve constructor over-injection is to refactor set of parameters into a new abstraction. It comes to mind pretty fast that position, inset and fromView all describe popover position. I already had a Position enum defined like this:

public enum Position {
    case bottom
    case top
    case center
}

so I decided to add the rest of the properties to its associated values:

public enum Position {
    case bottom(fromView: UIView?, inset: CGFloat)
    case top(fromView: UIView?, inset: CGFloat)
    case center(fromView: UIView?)
}

What I liked about that solution is that I could solve the issue that inset actually does not matter for center position, and with enum and associated values I can avoid meaningless parameters.

What I didn't like though was the fact that I loose the ability to use default values. So after this refactoring the code became cluttered with those defaults pretty fast:

showPopoverMessage(message, position: .bottom(fromView: nil, inset: 8))

So I started to wonder if there is a way to workaround Swift limitation of not being able to specify defaults for associated values. In the end I found few ways to do that.

Enum with static factory methods

The first solution that comes to mind is to define static factory methods with default parameters:

public enum PopoverPosition {
    case bottom(fromView: UIView?, inset: CGFloat)
    case top(fromView: UIView?, inset: CGFloat)
    case center(fromView: UIView?)

    public static func bottom(fromView: UIView? = nil, inset: CGFloat = 8) -> PopoverPosition {
        return PopoverPosition.bottom(fromView: fromView, inset: inset)
    }
}

Unfortunately this will not compile - compiler treats static method as redeclaration of enum case (even if different argument labels are used). There are two options here: either to change methods names, i.e. using an external name of first parameter as a method name prefix:

public enum PopoverPosition {
    case bottom(fromView: UIView?, inset: CGFloat)
    ...
    public static func bottomFrom(_ fromView: UIView? = nil, inset: CGFloat = 8) -> PopoverPosition {
        return PopoverPosition.bottom(fromView: fromView, inset: inset)
    }
}

or to rename enum cases, i.e. capitalising them:

public enum PopoverPosition {
    case Bottom(fromView: UIView?, inset: CGFloat)
    ...
    public static func bottom(fromView: UIView? = nil, inset: CGFloat = 8) -> PopoverPosition {
        return PopoverPosition.Bottom(fromView: fromView, inset: inset)
    }
}

The main downside of this approach is the need to use different names for methods and cases.

Using struct instead of enum

Another pretty obvious option is to switch from enum to struct.

public struct PopoverPosition {
    
    public enum Position {
        case bottom
        case top
        case center
    }
    
    public let position: Position
    public let fromView: UIView?
    public let inset: CGFloat
    
    private init(position: Position, fromView: UIView?, inset: CGFloat) {
        self.position = position
        self.fromView = fromView
        self.inset = inset
    }
    
    public static func bottom(fromView: UIView? = nil, inset: CGFloat = 8) -> PopoverPosition {
        return PopoverPosition(position: .bottom, fromView: fromView, inset: inset)
    }
}

This is a bit more to type but it solves the issue. With private initialiser we can limit ways to construct the value to only factory methods which makes it closer to enum cases with associated values. The downside is that now we have two types instead of one (struct and enum) and we can not use PopoverPosition value in a switch, we have to use its position property.

Using enum with a builder

Trying to stick with enum I came up with another option - using an inner builder type to scope factory methods and avoid compiler complaining about redeclarations:

public enum Position {
    case bottom(fromView: UIView?, inset: CGFloat)
    case top(fromView: UIView?, inset: CGFloat)
    case center(fromView: UIView?)
    
    public enum Builder {
        public static func bottom(fromView: UIView? = nil, inset: CGFloat = 8) -> Position {
            return Position.bottom(fromView: fromView, inset: inset)
        }
        ...
    }
    
    public static var make: Position.Builder.Type {
        return Position.Builder.self
    }
}

With this now I have a way to construct enum value with default associated values like this:

let position = Position.Builder.bottom()

Instead of using Builder directly, which looks a bit clumsy we can use a make method defined in enum:

public enum Position {
    public static var make: Position.Builder.Type {
        return Position.Builder.self
    }
}

let position = Position.make.bottom()

Conclusion

After all I ended up using a struct instead of enum. Again I end up with preferring something else to enum, which I consider a code smell in general. There is definitely a place for enums in Swift code, and I do use them from time to time, but most of the time they are not the best option.

Update

Thanks to Olivier for pointing me to the proposal that is supposed to fix the issue that caused this post in the first place by normalising associated values representations, which will result in allowing defaults for associated values.

Xcode Source Editor Extension superpowered with SourceKitten

Sun, 19 Feb 2017 20:23:16 GMT

With Xcode 8 Apple finally provided developers with first party API to develop plugin-like Xcode extensions, at the same time closing all the doors for in-process plugins. At this moment unfortunately we are provided with a very limited tools. We can only manipulate the content of currently selected file, have no (official) access to any project metadata and other sources. There are also no first-party tools for code analysis, so we have to parse the code manually. Luckily thanks to OSS community we have such projects as SourceKitten that fills this gap and gives us some foundation to build cool stuff on top of it. Usually though it's used as a framework as part of other tools, usually command line tools that are supposed to be run from a build step of your project, not in source editor extension. Is it even possible to use SourceKitten in Xcode extension? Let's try.

We go and create an Xcode source editor extension, link it with SourceKittenFramework and its dependencies, write some boilerplate implementation of extension command that uses one of SourceKitten APIs, like Structure. We run our extension and... we see in the console: xcrun: error: cannot be used within an App Sandbox.

Under the hood SourceKitten uses XPC service to communicate with SourceKit process, the same what Xcode does. It basically invokes xcrun command with different flags and parameters. And as that error message says this command can not be used within an App Sandbox. Xcode source editor extension though should be sandboxed.

Luckily on MacOS we can run non-sandboxed apps unless we want to distribute them via App Store. In non-sandboxed app we can use SourceKitten without any problems.

But if we try to turn off sandboxing for source editor extension it will simply not show up in Editor menu. So how can we run SourceKitten from non-sandboxed environment while being in a sandboxed environment of extension? The answer is - XPC service. XPC services everywhere! Instead of using SourceKitten directly we will access it through XPC service that will be not sandboxed and so can use SourceKitten.

As our source editor extension is just an app extension it requires some MacOS app that will contain it. Extension in its turn will serve as a container for XPC service. The app itself can be as dumb as possible, it does not need to do anything, though it can be used as a settings interface for extension. The main actors will be an extension and it's accompanying XPC service.

Creating simple XPC service

So let's go through this setup step by step. First let's try to create a simple XPC service that our app can communicate with.

I will not go into details of XPC service implementation, you can find everything you need to know in docs.

Create a Cocoa Application and XPC Service target using Xcode templates. XPC Service template already contains everything that we need - it has a service protocol and its implementation that contains a simple function to uppercase input string, and comments on how to call the service from the app. Unfortunately there is no Swift version of this template, so we will need to rewrite it in Swift manually. Here is the code you should end up with.

// SourceKittenEditorExtensionService.xpc
// SourceKittenEditorExtensionServiceProtocol.swift

@objc protocol SourceKittenEditorExtensionServiceProtocol {
    func uppercase(_ string: String, withReply: (String)->())
}

// SourceKittenEditorExtensionService.xpc
// SourceKittenEditorExtensionService.swift
import Foundation

@objc class SourceKittenEditorExtensionService: NSObject, SourceKittenEditorExtensionServiceProtocol {
    
    func uppercase(_ string: String, withReply: (String) -> ()) {
        withReply(string.uppercased())
    }

}

// SourceKittenEditorExtensionService.xpc
// main.swift
import Foundation

class ServiceDelegate : NSObject, NSXPCListenerDelegate {
    func listener(_ listener: NSXPCListener, shouldAcceptNewConnection newConnection: NSXPCConnection) -> Bool {
        newConnection.exportedInterface = NSXPCInterface(with: SourceKittenEditorExtensionServiceProtocol.self)
        let exportedObject = SourceKittenEditorExtensionService()
        newConnection.exportedObject = exportedObject
        newConnection.resume()
        return true
    }
}

// Create the listener and resume it:
let delegate = ServiceDelegate()
let listener = NSXPCListener.service()
listener.delegate = delegate;
listener.resume()

// SourceKittenEditorExtensionApp.app
// AppDelegate.swift
import Cocoa

@NSApplicationMain
class AppDelegate: NSObject, NSApplicationDelegate {

    @IBOutlet weak var window: NSWindow!

    lazy var connection: NSXPCConnection = {
        let connection = NSXPCConnection(serviceName: "my.company.SourceKittenEditorExtensionService")
        connection.remoteObjectInterface = NSXPCInterface(with: SourceKittenEditorExtensionServiceProtocol.self)
        connection.resume()
        return connection
    }()

    func applicationDidFinishLaunching(_ aNotification: Notification) {
        let handler: (Error) -> () = { error in
            print("remote proxy error: \(error)")
        }
        let service = connection.remoteObjectProxyWithErrorHandler(handler) as! SourceKittenEditorExtensionServiceProtocol
        service.uppercase("lowercase") { (uppercased) in
            print(uppercased)
        }
    }

}

Now we need to enable Code Signing and App Sandboxing for both targets. As said before we will not use sandboxing for XPC Service to use SourceKitten, but at this point as we don't use SourceKitten yet you will see that everything still works and we get uppercased string!

Using SourceKitten in XPC service

Now let's try to use SourceKitten in our XPC service. Let's replace the method that we have in our service with another method to get a structure of source code.

// SourceKittenEditorExtensionService.xpc
// SourceKittenEditorExtensionServiceProtocol.swift

@objc protocol SourceKittenEditorExtensionServiceProtocol {
    func structure(_ string: String, withReply: ([String: AnyObject])->())
}


// SourceKittenEditorExtensionService.xpc
// SourceKittenEditorExtensionService.swift
import SourceKittenFramework

@objc class SourceKittenEditorExtensionService: NSObject, SourceKittenEditorExtensionServiceProtocol {
    
    func structure(_ string: String, withReply: ([String: AnyObject]) -> ()) {
        let file = File(contents: string)
        let structure = Structure(file: file)
        withReply(structure.dictionary as [String: AnyObject])
    }

}

// SourceKittenEditorExtensionApp.app
// AppDelegate.swift
import Cocoa

@NSApplicationMain
class AppDelegate: NSObject, NSApplicationDelegate {
    
    @IBOutlet weak var window: NSWindow!
    
    lazy var connection: NSXPCConnection = {
        let connection = NSXPCConnection(serviceName: "my.company.SourceKittenEditorExtensionService")
        connection.remoteObjectInterface = NSXPCInterface(with: SourceKittenEditorExtensionServiceProtocol.self)
        connection.resume()
        return connection
    }()
    
    func applicationDidFinishLaunching(_ aNotification: Notification) {
        let handler: (Error) -> () = { error in
            print("remote proxy error: \(error)")
        }
        let service = connection.remoteObjectProxyWithErrorHandler(handler) as! SourceKittenEditorExtensionServiceProtocol
        service.structure("struct Foo {}") { (structure) in
            print(structure)
        }
    }
    
}

Now we need to add SourceKittenFramework and its dependencies to Embedded Binaries of the app and link them with XPC Service target. To make them available for XPC Service at runtime we also need to add runpath @executable_path/../../../../Frameworks in XPC Service build settings.

If we run the app now we will see the error message xcrun: error: cannot be used within an App Sandbox. Go on and turn off sandboxing for XPC Service target (you need to delete entitlements file and clear Code Signing Entitlements build setting first). If you run the app again you will see that it works and you will see parsed code structure!

["key.diagnostic_stage": source.diagnostic.stage.swift.parse, "key.substructure": <__NSSingleObjectArrayI 0x7f8805f11b50>(
{
    "key.accessibility" = "source.lang.swift.accessibility.internal";
    "key.bodylength" = 0;
    "key.bodyoffset" = 12;
    "key.kind" = "source.lang.swift.decl.struct";
    "key.length" = 13;
    "key.name" = Foo;
    "key.namelength" = 3;
    "key.nameoffset" = 7;
    "key.offset" = 0;
}
)
, "key.offset": 0, "key.length": 13]

Xcode source editor extension

Now when we have XCP Service for SourceKitten let's use it in source editor extension instead of the app.

Go on and add Xcode Source Editor Extension target from Xcode template. Move the code to communicate with the service from the app to extension command code. Here is the code of extension that you should end up with. As you can see it's exactly the same as code that calls XPC Service from the app and service code does not change at all.

// SourceKittenEditorExtension.appex
// SourceEditorExtension.swift
import Foundation
import XcodeKit

class SourceEditorExtension: NSObject, XCSourceEditorExtension {
    
    func extensionDidFinishLaunching() {
        // If your extension needs to do any work at launch, implement this optional method.
        print("extension launched")
    }
    
    /*
    var commandDefinitions: [[XCSourceEditorCommandDefinitionKey: Any]] {
        // If your extension needs to return a collection of command definitions that differs from those in its Info.plist, implement this optional property getter.
        return []
    }
    */
    
}

// SourceKittenEditorExtension.appex
// SourceEditorCommand.swift

import Foundation
import XcodeKit

class SourceEditorCommand: NSObject, XCSourceEditorCommand {
    
    lazy var connection: NSXPCConnection = {
        let connection = NSXPCConnection(serviceName: "my.company.SourceKittenEditorExtensionService")
        connection.remoteObjectInterface = NSXPCInterface(with: SourceKittenEditorExtensionServiceProtocol.self)
        connection.resume()
        return connection
    }()

    deinit {
        connection.invalidate()
    }

    func perform(with invocation: XCSourceEditorCommandInvocation, completionHandler: @escaping (Error?) -> Void) -> Void {
        let handler: (Error) -> () = { error in
            print("remote proxy error: \(error)")
        }
        let service = connection.remoteObjectProxyWithErrorHandler(handler) as! SourceKittenEditorExtensionServiceProtocol
        service.structure(invocation.buffer.completeBuffer) { (structure) in
            print(structure)
            completionHandler(nil)
        }
    }
    
}

Now remove the XPC Service from the app embedded binaries and add a Copy Files build phase in extension target to copy XPC Service to XPC Services directory. Add XPC Service target as a Target Dependency for extension target. As now XPC Service is embedded in the extension which is in turn is embedded in the app we need to adjust its runpath to @executable_path/../../../../../../../Frameworks.

Now when you run the extension (if you have a good day it will show up in Editor menu) and select its menu item you will see it's working like a charm!

If something does not work as expected when you run the app or extension (extension menu does not show up, app fails to connect to service or fails to locate its binary), start from the beginning... My experience shows that it's easier and faster than trying to find the issue. If extension does not do anything (you don't see any output in the console) stop and run it again, for me it works only every second time.

Now we have SourceKitten superpowers in our source editor extension and with it we can do much more than before as we now have (almost complete) information about source code structure and we don't need to parse source code manually, it's much simpler to parse JSON that we now have.

You can get all the source code of this extension here.

Thanks to Norio Nomura for sharing his implementation of extension that uses SourceKitten in his repo. I used it as a reference. https://github.com/norio-nomura/LinuxSupportForXcode/

Extending native code with JavaScriptCore

Wed, 08 Feb 2017 19:01:00 GMT

This week there were a lot of articles around the web about React Native and its place in a current iOS dev ecosystem. I was also playing with JavaScript lately, but in somewhat different context - JavaScriptCore. JavaScriptCore is a really great way to make your apps extensible by your users. There are some cool live examples of awesome tools leveraging it.

As developers we are in a better position than our users as most of the time we can extend and patch our tools to our needs using native code. But our users can not. For example if you are building an app that uses some template engine, for example for Swift it can be Stencil, users of your tool will most likely need to extend template language as it can be very limited. With JavaScriptCore you can give them that power.

As every technology JavaScriptCore has its pros and cons. On one side it's fairly straightforward to implement, it's possible to completely separate implementation into a separate module and it provides a lot of possibilities to your users. On the other side it requires developers to write some boilerplate to support it (more you want to separate your native code from JavaScriptCore code more boilerplate you will need) and it's not designed for performance sensitive tasks (JavaScript code always runs synchronously, but you can have several contexts running in a separate threads, like CoreData contexts, just don't cross borders).

There is a good documentation and there are bunch of articles talking describing basics of JavaScriptCore which are really very simple so I will not repeat them here. If you want you can see all the implementation details in this repo. Instead I'd like to provide some tips that I've discovered while digging into it.

Modularity

For interoperability with your native code JavaScriptCore requires conformance to a protocol that defines all methods and properties that you want to access from JavaScript. It must inherit JSExport protocol and must be marked with @objc which inherently means that only subclasses of NSObject can implement it. But you don't need to sacrifice your swifty design choices in favour of supporting JavaScriptCore. Using adapter classes is a straightforward solution which gives enough flexibility for the price of writing some boilerplate. You can even define them in a separate module (framework) keeping your core module free of any references to JavaScriptCore.

Exceptions

Catch all JavaScript exceptions and rethrow them as native errors. Basically that's the only way to debug JavaScript code. Rethrowing JavaScript exceptions as native errors will help you to integrate it with native code and provide users feedback in case something is wrong in their JavaScript code. It's very easy to do with a simple helper method:

struct JSException: Error, CustomStringConvertible {
    let exception: JSValue
    var description: String {
        return "\(exception)"
    }
    init(_ exception: JSValue) {
        self.exception = exception
    }
}

@discardableResult
func inJSContext(_ jsContext: JSContext, _ block: () -> JSValue?) throws -> JSValue? {
    let result = block()
    if let exception = jsContext.exception {
        throw JSException(exception)
    } else {
        return result
    }
}

try inJSContext(jsContext) { jsContext.evaluateScript(code) }

You can also get all of the console logs with this trick (source in Objective-C):

let consoleLog: @convention(block) (String)->() = { s in print(s) }
let console = jscontext.objectForKeyedSubscript("console")
console?.setObject(unsafeBitCast(consoleLog, to: AnyObject.self), forKeyedSubscript: "log" as NSString)

Result

It's not possible (as far as I can tell) to use methods which throws even though they are bridged to Objective-C from Swift. Changing method to non-throwing and using try! could be one of your options, but there are other solutions - you can provide a function as a parameter and pass it an error (see the next tip), or you can use Result-like wrapper type (especially if you are already using Result in your native code).

You can also use a simple decorator function that rethrows native error as JavaScript error:

func bridgingError<T>(_ expression: () throws -> T) -> T? {
    do {
        return try expression()
    } catch {
        JSContext.current().evaluateScript("throw \"\(error)\"")
        return nil
    }
}

func wrapperMethodCalledFromJavaScript() -> Any? {
    return bridgingError { try wrapped.nativeMethodThatThrows() }
}

This way you can effectively rethrow native errors through JavaScript back to native code that invoked it or handle them in JavaScript code itself.

Closure parameters

You can not export methods with closure parameters. Instead of closure type use JSValue and call(withArguments:) when in native code you need to call a JavaScript function passed as a parameter. This way you can for example implement alternative API for handling errors (on JavaScript side you can pass {} if you don't need error handling)

func wrapperMethodCalledFromJavaScript(_ onError: JSValue) -> Any? {
    do {
        return try wrapped.nativeMethodThatThrows()
    } catch {
        onError.call(withArguments: [error])
        return nil
    }
}

wrapperMethodCalledFromJavaScript(function(error) { ... })

Constructors

To be able to construct your exported native types in JavaScript you can define a static factory method in a protocol. Swift initialisers are not automatically exported by JavaScriptCore. To use them you can do some trick - cast your initializer to @convention(block) closure and register it in a JavaScript context with a type name as a key:

class JSVariable: NSObject, JSExportableVariable {
    init(_ variable: String) { ... }
}

let newVariable: @convention(block) (String) -> JSVariable = JSVariable.init
jsContext.setObject(unsafeBitCast(newVariable, to: AnyObject.self), forKeyedSubscript: "Variable" as NSString)

var variable = new Variable("name")

With that you will not be able to access static methods of this type, but it may be still better than defining unneeded factory methods.

Key-Value coding

If you try to access property that is not present in the object you will get a nice undefined result of you script without any info what actually went wrong. In Cocoa in contrast to that we have Key-Value Coding which let us not only define valueForKey but also valueForUndefinedKey. Those methods are not available in JavaScript context (unless you define them in export protocol of course) and even if they would they will be not that convenient to use comparing with dot notation. There is a way to combine two approaches - using Proxy. It let's you define i.e. getter or setter decorators which will be called every time you try to access any property on a proxy object. This is what we use in Sourcery to catch some runtime errors in JavaScript templates.

let valueForKey: @convention(block) (NSObject, String) -> Any? = { target, key in
    return target.value(forKey: key)
}
jsContext.setObject(valueForKey, forKeyedSubscript: "valueForKey" as NSString)
jsContext.setObject(myObject, forKeyedSubscript: "myObject" as NSString)
jsContext.evaluateScript("myObject = new Proxy(myObject, { get: valueForKey })")

This way we replace original object with Proxy that wraps it and every time any property will be accessed on this proxy the valueForKey block will be called where we can redirect to NSObject's value(forKey:) or do what ever else.

Playgrounds

In a playground define types that you want to export in a separate source file, not directly in a playground page. Only this way they will be exported.

That's it for now. Are you using JavaScriptCore and have some more tips to share? Do that in the comments!

Going back to the roots

Thu, 02 Feb 2017 09:58:19 GMT

As Roy Marmelstein said in his recent presentation at dotSwift - we love to be excited. Can not agree more. When we read a blog post that describes the concept or architectural pattern that is somewhat new for us and feels exciting we tend to accept it as something good. We can go really far away this rote and sometimes we don't notice that we already have all the tools to solve the problems they address. For iOS developers this tool is a framework that we inevitably use every day - UIKit.

That's what I was thinking about in the breaks at dotSwift. It started to bug me after I watched yet another presentation about coordinators the night before. Not saying that this is a misleading concept (it's really not) let's think how can we do the same using what UIKit had for ages.

All of that can be also applied to VIPER and all of it's derivatives as its Interactor and Router are doing the same job as Coordinator.

The idea behind coordinators is very clear. They are there to manage application flow. You have a root (or app) coordinator that has references to child coordinators for each of the user stories. Then each of the child coordinators completely manages flow in their story and can transition to other stories (via its parent) or start new "child" stories. They let you make your view controllers highly maintainable: you can change their order in the user story, you can change the way how they are presented, you can easily extract them and reuse in completely different environment. In other words you can easier change the flow. In theory the only thing that will change when flow changes, if properly implemented, is coordinator.

That's all good, but its usually suggested to use PONSO objects as coordinators. And here is the obvious alternative that UIKit gives us that is for some reason ignored - subclassing view controllers. I used to also ignore it and advocate for PONSO objects instead because what can be easier than dealing with PONSO, right? But starting to think about it I didn't find any critical arguments against it.

Subclassing standard UIKit controllers

There is probably no application in the AppStore that does not use UITabBarController or UINavigationController. If you find yourself thinking about implementing your own version of it - stop and think again. Then think once more. If you still what to go for it you might have some specific reasons, but most of the time you will be completely covered by using these controllers. Even if you use them as-is you are able to customise their behaviour, i.e. transition animation.

There are always exceptions. Don't even think about using UIPageViewController if you want to keep your crash free rate high without trying to fix every hole in it. Can't say much about UISplitViewController as I never used it, but I suspect it's more likely that you will need to adjust it and then it may not play nice with you. In case of UINavigationController and UITabBarController I've never had to change their default behaviour.

UINavigationController documentation says: "You generally use this class as-is but you may also subclass to customize the class behavior." UITabBarController documentation says: "This class is generally used as-is but may be subclassed in iOS 6 and later." We subclass UIViewController without even questioning, so there is nothing that stops you from subclassing UINavigationController or UITabBarController and use them as your coordinators. It's exactly what they are designed for. They are not just dummy view controllers. They literally manage their child view controllers flow in their own way. The same if you use you custom container - it can be a coordinator for its child view controllers.

If you need custom actions, need to store and update some global state, pass data between view controllers you can use view controller subclass the same way as you would use PONSO coordinator. With one difference - you will not need another abstraction. Less abstractions - less things to wrap your (and your colleagues) head around.

If you are concerned about testability - there are no show-stopper issues in unit testing UINavigationController or UITabBarController, they are just view controllers, so you unit test them the same way. All that buzzing about "view controllers are not testable" is just an excuse for not testing them (that I myself use too often with no real reason, just because I don't like to write tests that much) because they are usually monolithic. Of course Massive-View-Controller is hard to test. But any God Object is hard to test, it's true not just for view controllers. Thin view controller does not mean dumb view controller.

If you are concerned with tight coupling your view controller with navigation or tab bar controller then just don't couple them too much! There is no much difference here in using PONSO or view controller subclass. Don't rely on your view controller being in navigation stack or being presented modally, as this can change and this is not a view controllers responsibility. The only benefit of using PONSO here is that you can make it's interface not exposing anything related to concrete implementation of navigation, i.e. if it uses UINavigationController internally or something else. With subclass due to inheritance client will be able to access all UINavigationController methods. But the thing is that it's their problem if they use it the way that they tightly couples with such implementation details. They could use protocol that does not leak any implementation details instead of concrete class. With subclass they just have more options (and more ways to screw up), choosing PONSO instead just constrains its client so they can not "abuse" it in some ways, but I would not say that this should be a reason to prefer it. That's simply the question of client using dependency injection correctly or not.

If you are concerned with subclassing because you don't want to inherit unneeded behaviour or you don't want your code to break with the next iOS update then it's just too late - you have to use UIKit and most likely you already use it's containers. Then it does not matter either you use UINavigationController as-is and PONSO coordinator or you use UINavigationController subclass itself as coordinator. It's even better this way as you can override unneeded behaviour.

The only thing you need to successfully implement application flow is to remember that your view controllers should be agnostic to it. Screen A should not ask whoever (router, interactor, storyboard, it's navigation controller or tab bar controller) to present screen B, either modally or with a push, screen A should not pass data to screen B, screen A should not care if it's presented modally, pushed in navigation stack or presented in a pop over. If you do that you are coupling your controllers with your current flow. It will make harder to use them separately from each other or change that behaviour. Instead you should delegate all of that to someone else. It may be a PONSO coordinator, but the same way it can be view controller's parent - navigation, tab bar controller or you custom container. You just should not leak their implementation details.

Of course there are cases when it's not necessary. If you have a screen for creating a calendar event and screen to set its time you most likely will always use them together in one way. Then it's not a problem to couple them together. You still can avoid too much coupling using abstractions instead of concrete types. But you don't have to use coordinator of any form in this case.

Responder chain

The powerful technology that you probably almost never use explicitly. But if you use it you will see that you don't have to define all the IBActions in the view controller or a view that contains controls that trigger those actions and then pass them to a delegate or call some block. You can put them right in there in the controller that should handle this action. If this action requires some flow transition it most likely belongs to coordinator. If you are using view controller based container instead of PONSO coordinator responder chain will be there to help you to wire things together. Just define IBAction right in your container and link it with First Responder in Interface Builder. If you would use PONSO coordinator you will not be able to do that as it's not easy to insert PONSO in responder chain and you will end up with doing some extra work: you will need to define IBAction in view controller and use it to call a method on coordinator which will also most likely involve using delegate protocol, or you will need to set target and action in code. That's all just unnecessary boilerplate that no one likes to write.

Unwind segues

This is another UIKit feature that, as far as I can tell from my experience, is not widely adopted. I myself used it twice or so and just as an experiment. The same as responder chain (it actually is built on top of responder chain) it let's you to define actions, but for leaving screen, and it let's you to define these actions in the view controller that needs to handle the result of the job performed by user (or your app) on dismissed screen, or in a container that plays the role of coordinator. Unwind segue will also automatically dismiss view controller, so you don't have to pop or dismiss it manually. Another improvement they can bring is that you can get rid of endless delegate methods or completion blocks. You can even use custom segues for unwinding and trigger them manually.

Note: from what I've tried it looks like if you put an action for unwind segue in navigation controller subclass it will become its destination and dismissed view controller will not be popped automatically. The dismissed view controller will still receive prepare for segue callback, so if you delegate this method to its coordinator (navigation controller in this case) you will be able to handle that action there and will not need to dismiss controller manually, UIKit will handle it.

There is a valid concern regarding using responder chain and unwind segues. They are (mostly) managed by UIKit and we don't have (you have some control of unwind segues) a lot of ways to control it. So you of course need to understand how these techniques work, but still you can face some unexpected behaviour when they don't work nice with what you need to do (see my previous note). Using PONSO controller you have more control over it, but it comes with a cost of writing some boilerplate and introducing a new level of abstraction. So I would say this is the only thing that you should have in mind when deciding to use these techniques. The point is that you have options, what is always good.

One more tip

Use code generators like R.swift or SwiftGen to generate code for working with segues, storyboards and view controllers in a type-safe manner. They don't just provide strongly typed APIs instead of UIKit's stringily typed, they will save you from leaving potential bugs and crashes when you change your flows, as they will prevent your code from compiling until you fix all the issues caused by flow changes.

Conclusion

In the end as you can see using coordinators does not necessary mean introducing new abstractions, it can be simply using standard UIKit components in a better way. Nothing said here is a rule set in stone though, except maybe using code generators (that you should really do even if you are not using coordinators). This is more like a set of advices that I'm myself going to try out and will follow up if I find something that does not work out well. If you know something that I might miss - please do share your thoughts in the comments.

Adaptive text styles

Thu, 19 Jan 2017 21:00:00 GMT

Textual content is the essential part of any app and text handling in iOS has been improving through last years. Starting with iOS 7 we have dynamic types and text styles, then in iOS 8 we got self sizing cells that help a lot when you want to adopt dynamic type. With trait collections we also expanded the ways how we can adapt text to different environments. And Apple was constantly extending those APIs exposing new font styles, font wights and so on.

There is one "but" here. I don't have official statistics and will be glad to be wrong, but I think most of the apps in the AppStore do not care about adapting text, or they simply use system font hoping that it will play nice, or handle it in a custom way via in app setting.

There are few reason why that can happen (again, I will be glad to be wrong that this is even the case) that I can think of. One of them is that it requires a lot of boilerplate to write. You need to listen to specific notification, you need to reference your labels and other views with outlets and update them when this notification arrives. More than that you will most likely need to adjust your layout, at least to handle multi line labels better than just trimming tail. The same with updating text on trait collection changes. You need to implement traitCollectionDidChange(_:) in every view or view controller and update all labels again. That's really tons of boilerplate that no one wants to deal with.

Another reason can be that out of the box these features work well with system font only and either require more code to work with custom fonts or simply don't work at all (like text styles).

Speaking of updating to trait collection changes things are a bit better here as it's very easy to set it up in Interface Builder without writing a single line of code. Simply add a variant for the font property. It works perfectly with any custom font and it will be automatically updated on trait collection change.

But if you want to use custom font, respond to trait collection changes and adopt dynamic type you still will need to write lots (less than if there was no trait collections support in Interface Builder, but still a lot) of boilerplate.

And even though setting up fonts in a storyboard looks like a feasible solution in fact it does not scale. Imagine that your designer decides to change a font. Or to change the size of each subtitle label from 14pt to 13pt. Depending on how much text you display in your app it can be either very trivial task or a real nightmare.

There is also UIAppearance that is very easy to use to setup global application appearance, but it does not work well when it comes to defining arbitrary styles of custom views. You can vary appearance properties for different trait collections, but you will need to use subclasses to set up their appearance, or if you want to avoid subclassing you can vary it based on containing types, what will again force you to subclass (and a lot). Also not every property of every view can be set with appearance proxy and you can not even extend it in Swift. So looks like this is not an option either.

What do we want are two simple things:

automatically update text fonts when trait collection or content size category changes without writing any boilerplate code
easily maintain a set of text styles
avoid subclassing standard UIKit components

Can we do something with that?

Let's start from the very beginning. Before you start to implement anything you get the designs from your UI/UX team. If you are lucky enough these designs will come along with a very handy thing - a style guide. If it's not the case, please reach out to your design team right now and ask if they can provide it. Most likely they can and already have it, you just never asked. If you are supper lucky this style guide will be consistent across all the designs and will contain a finite number of colors and text styles to use in the app. By text style here I mean combination of font name, size, weight and traits. It can also contain other attributes, like line height and letter spacing, but let's concentrate on basic properties.

With this style guide at hand you can easily transform it to code that can look something like this:

func bodyTextStyle(_ traitCollection: UITraitCollection) -> UIFont? {
  if case .compact = traitCollection.horizontalSizeClass {
    return UIFont(name: "Comic Sans", size: 20)
  } else {
    return UIFont(name: "Comic Sans", size: 24)
  }
}

As you can see we already think about using different size for different size class. And that's what your designer should think about too.

Note: it's a very good idea to define font styles in a format that is readable both for designer and developer and then using a code generator like Sourcery transform it into code. At least you can use R.swift or SwiftGen to generate code to access your font resources.

When you are done with specifying your font style functions you will notice the obvious thing - they all have a same signature. Seems like a good candidate for a typealias:

public typealias TextStyle = (UITraitCollection) -> UIFont?

Let's move on and think about views. What do we want is to be able to apply some font style to a view that displays text and to update it automatically. For update we might need a function like func updateStyle(). This function should be called when trait collection or content size category changes. But how do we do that?

Each UIView conforms to UITraitEnvironment protocol that defines a property var traitCollection: UITraitCollection { get } and a method func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?). So it looks like we should call our updateStyle from traitCollectionDidChange. But to do that we will need to create a subclass and override this method. Or we will need to implement this method on a view controller and call updateStyle on each view manually. But this is what we started from and what we want to get rid of.

To avoid subclassing we can try to observer traitCollection via KVO, but we will realize pretty soon that it's not KVO compliant. Sigh.

There is a interesting solution that I came up with, inspired by this post. There author uses child view controllers to separate some tasks from a parent view controller which require to receive all UIKit callbacks instead of its parent. If he can solve that applying composition to view controllers can we solve our problem with composition of views? Sure!

Instead of responding to trait collection change in the view itself we can add an invisible subview that will respond to them. These changes are propagated by UIKit from view to all of its subviews no matter if they are actually rendered or not. So the only thing that we need to do is to create a subclass of UIView, override traitCollectionDidChange method and add the instance of this view as a subview in a view that we want to update.

class StyleProxyView: UIView {
    
  override public func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
    superview?.updateStyle()
  }
    
}

Looks good (you will see why I called it StyleProxyView later) but we can do it a bit more type safe with generics:

class StyleProxyView<S: UIView>: UIView {
    
  weak var instance: S? { return superview as? S }
    
  override public func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
    instance?.updateStyle()
  }
    
}

This way we will be able to add StyleProxyView<UILabel> only to UILabel.
But most likely we will not need to change the style of any view, as plain UIView does not render any text. We will need it for UILabel, UIButton and some other views. So instead of constraining StyleProxyView to any UIView let's constrain it with a protocol. Let's call it something... stylish:

protocol Stylish {
  func updateStyle()
}

class StyleProxyView<S: Stylish>: UIView {
    
  var instance: S? { return superview as? S }
    
  override public func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
    instance?.updateStyle()
  }
    
}

To update style we need a way to set it up first. Looking back at UIAppearance we can use a similar interface:

label.style.font = bodyTextStyle

Instead of setting property on a label (which is just UILabel) we set this property through a proxy object. And then we can use it to update label itself:

extension UILabel: Stylish {
  func updateStyle() {
    font = style.font(traitCollection) ?? font
    invalidateIntrinsicContentSize()
  }
}

But what is this proxy? Is it StyleProxyView that we defined before? Not exactly. You see, the StyleProxyView is still a UIView, so if we make style a StyleProxyView we will be able to do things like label.style.frame = ... which does not make any sense. Instead it will be a plain NSObject (on why we need an NSObject later) object:

public class StyleProxy<S: Stylish>: NSObject {
  fileprivate override init() { }
}

We will still use a StyleProxyView to access style property:

class StyleProxyView<S: Stylish>: UIView {
  var style: StyleProxy<S> = StyleProxy()
  ...
}

And now the missing part:

extension Stylish where Self: UIView {
    
  private(set) var style: StyleProxy<Self> {
    get {
      if let proxy = subviews.first(where: { $0 is StyleProxyView<Self> }) as? StyleProxyView<Self> {
        return proxy.style
      }
        
      let proxy = StyleProxyView<Self>()
      addSubview(proxy)
      return proxy.style
    }
    set {
      guard let proxy = subviews.first(where: { $0 is StyleProxyView<Self> }) as? StyleProxyView<Self> else { return }
      proxy.style = newValue
      updateStyle()
    }
  }

}

First time when we access style property we are adding a StyleProxyView as a subview. On next calls we will reuse that instance. Then we return its style property. Setter does not even require any explanation.

Here we defined style property as var style: StyleProxy<Self>, so when we use it on UIView instance it will be StyleProxy<UIView> (we will need to extend UIView with Stylish implementation for that), but if we use it on UILabel instance it will be StyleProxy<UILabel>.

Note: if you try to use StyleProxy<Self> in a Stylish protocol like this: func updateStyle(style: StyleProxy<Self>) it will not work because compiler will give you an error when you will try to implement it i.e. on UILabel: "Protocol 'Stylish' requirement 'updateStyle(style:)' cannot be satisfied by a non-final class ('UILabel') because it uses 'Self' in a non-parameter, non-result type position". But in extension it will work. Though StyleProxyView will be not able to access it any more. Sigh. Sometimes I doubt that Swift is a right name for the language.

Now when we can access style with label.style we can move on and add actual style properties to it. Here our generic constraints will start to help us as we are going to extend StyleProxy type for different types of its generic parameter S:

private var _textStyleKey: Void?

public extension StyleProxy where S: UILabel {
    
  var font: TextStyle? {
    get {
      //swifty wrapper for objc_getAssociatedObject
      return associatedValue(forKey: &_textStyleKey)
    }
    set {
      //swifty wrapper for objc_setAssociatedObject
      retain(newValue, forKey: &_textStyleKey)
    }
  }
    
}

Here for any StyleProxy with UILabel constraint we are adding textStyle property storing it as associated object (that's why we used NSObject as a base class for it) as we can not have stored variables in extensions, but we still have access to Objective-C runtime and can leverage it.

Now we can finally use it in updateStyle:

extension UILabel: Stylish {
  func updateStyle() {
    font = style.font(traitCollection) ?? font
  }
}

That's it. Now when you will do label.style.textStyle = boldTextStyle it will add a style proxy view that will respond to trait collection changes by calling updateStyle method defined on UILabel where you will update its font. You write it once and use it everywhere.

This post can seem to be long but describe implementation takes less than 100 lines. And it's straight forward to implement the same for UIButton or any other view with text. Simply create StyleProxy extension for this type with properties that you want to set and use them in updateStyle method of this type. It's also trivial to add observing for UIContentSizeCategoryDidChangeNotification. You can even extend text style to use NSAttributedString attributes, though this will require some additional work for ensuring its predictable behavior with attributes set through i.e. attributedText property of UILabel.

The profit of this implementation is that now you don't need to care about updating labels in traitCollectionDidChange of their superview, they will update themselves using text style that you set on them. At the same time you still can use static fonts with font property. You will be able to easily adjust fonts of all your labels or adding new style simply doing that in one place instead of doing that in every storyboard or xib. And we've built a structured collection of text styles that can be used independently from style proxies.

What do you think? Does it look like a feasible solution or it does not worth it? How do you manage text styles in your app?

Inout variables with side effects

Thu, 15 Dec 2016 13:12:17 GMT

Every app has some kind of caching. Let's say our caching strategy is very simple:

check if data is in the memory cache and return it
if not - make a network call and cache the result when it's done

For that you can write code that will probably look something like this:

if let cached = store.menuPreferences {
    dispatch_async(dispatch_get_main_queue()) {
        completion(preferences: cached, error: nil)
    }
} else {
    repository.getMenuPreferences({ (preferences, error) in
        if let preferences = preferences {
            self.store.setMenuPreferences(preferences)
        }
        completion(preferences: preferences, error: error)
    })
}

Pretty simple and straight forward. But what if you need to add caching for another piece of data? And another, and another and so on and on. Having to repeat this check-cache-or-make-request dance is just boring. So let's improve it and extract common logic to a method.

func serveCached<T>(inout cached: T?, @noescape updateCache: ((T?, ErrorType?)->())->(), completion: (T?, ErrorType?)->()) {
    if let cached = cached {
        dispatch_async(dispatch_get_main_queue()) {
            completion(cached, nil)
        }
    } else {
        updateCache({ response, error in
            if let response = response {
                cached = response
            }
            completion(response, error)
        })
    }
}

var preferences: MenuPreferences? {
    get { return self.store.menuPreferences }
    set { self.store.setMenuPreferences(newValue ?? []) }

serveCached(&preferences, updateCache: repository.getMenuPreferences, completion: completion)

What we are doing here is that we are trying to use inout variable to wrap access to the storage. We do that by defining custom accessors for it. Yes, right on the local variable! (willSet and didSet will work exactly the same way). This way we will have a side effect on assignment. Then we pass it to the method, read from it and later assign new value to it.

Looks cool! Except that it will not work. To be more precise it will work only if inout variable is not captured by the code block that escapes. So if what you do in updateCache is synchronous then it will work. But most likely it will be asynchronous and in this case the closure passed to updateCache will need to escape. Here is the proposal for Swift 3 that explains what happens here and says:

... an inout parameter is captured as a shadow copy that is written back to the argument when the callee returns. This allows inout parameters to be captured and mutated with the expected semantics when the closure is called while the inout parameter is active... But this leads to unintuitive results when the closure escapes, since the shadow copy is persisted independently of the original argument.

But no worries! There is nothing here that can not be fixed with a simple boxing. Instead of passing inout variable to the method we will pass it a variable that boxes accessors instead:

final class Variable<T> {

    let get: () -> T?
    let set: (T?) -> ()
    
    init(get value: () -> T?, set: (T?) -> ()) {
        self.get = value
        self.set = set
    }
}

With this simple class we need to make some trivial changes in serveCached method and the calling part stays almost the same:

let preferences = Variable(
    get: { self.store.menuPreferences },
    set: { self.store.setMenuPreferences(newValue ?? []) }
)

serveCached(preferences, updateCache: repository.getMenuPreferences, completion: completion)

Conclusion

In Swift it's very common that such simple box classes become very helpful. In my current project besides this one and a trivial Box class we also use such boxes as NSCodingBox and Cached which save us from writing a lot of boilerplate. And the fact that in Swift we can use setters and observers for local variables just the same way as for properties also allows for some neat code improvements.

Objective-C headers in Swift framework & custom build configurations

Sat, 29 Oct 2016 13:45:54 GMT

It's already 2 years of Swift and its interoperability with Objective-C as well. When app extensions were released we've got a way to share our code across targets using frameworks. I used to build lots of frameworks since then, sometimes I even worked full-time just on frameworks. But as I had written almost none of Objective-C in around a year now and I've never dived deep enough in Swift and Objective-C interoperability in frameworks here is the lesson I had to learn hard this time.

Setup

Lets say you've decided to make a framework that combines all UIKit related extensions used in your app. I would say that it's a good idea because next you can include your 3rd party UI dependencies in that framework as a source code. That can improve your app launch time as it will need to load less frameworks on startup.

Let's say you are using UIAppearance and need to support iOS 8. Then most likely you will need to use static func appearanceWhenContainedInInstancesOfClasses(containerTypes: [AnyObject.Type]) -> Self method. But it is only available in Swift for iOS 9. To make this method available in Swift for iOS 8 you need to use some Objective-C wrapper method.

UIAppearance+Swift.h

NS_ASSUME_NONNULL_BEGIN
@interface UIView (UIAppearance_Swift)

+ (instancetype)appearanceWhenContainedWithin:(Class<UIAppearanceContainer>)container;

@end
NS_ASSUME_NONNULL_END

UIAppearance+Swift.m

@implementation UIView (UIAppearance_Swift)

+ (instancetype)appearanceWhenContainedWithin:(Class<UIAppearanceContainer>)container
{
    return [self appearanceWhenContainedIn: container, nil];
}

@end

So far so good, but how do you expose this to the Swift code in the framework itself and to the application code that links to this framework?

In the app target you use bridging headers to expose Objective-C code for Swift code in the same target. But framework targets do not support bridging headers. Frameworks have so called umbrella headers. Here is an example:

#import <UIKit/UIKit.h>

//! Project version number for UIKitExtensions.
FOUNDATION_EXPORT double UIKitExtensionsVersionNumber;

//! Project version string for UIKitExtensions.
FOUNDATION_EXPORT const unsigned char UIKitExtensionsVersionString[];

// In this header, you should import all the public headers of your framework using statements like #import <UIKitExtensions/PublicHeader.h>

See this comment? It might seem that that's what we need. And even official interoperability guide suggests so. So we import our header, just like this comment says:

// In this header, you should import all the public headers of your framework using statements like #import <UIKitExtensions/PublicHeader.h>

#import <UIKitExtensions/UIAppearance+Swift.h>

Not forgetting of course to make this header public, because by default headers are added to project scope.

If you do so your framework will compile perfectly fine, other Swift code in the framework will have access to Objective-C code defined in imported header because compiler will generate appropriate Swift code.

import Foundation
import UIKit
import UIKitExtensions

extension UIView {
    public class func appearanceWhenContainedWithin(container: AnyObject.Type) -> Self
}

But don't completely trust it. This will work for most cases but not for all.

The problem

As the project grows up we always come to the situations when default Debug and Release configurations are not enough. We start to add something like Debug Production and Debug Staging and maybe more. That's when things become trickier.

Also when dealing with frameworks you can setup your project in different ways. Here is an article that describes one of such setups. I don't use exactly the same, but a similar approach. I have a separate project for all the frameworks. Then I have a simple build script that copies framework from build products directory to Frameworks directory. Then I add this directory in "Frameworks search paths" and embed the framework in the app.

So based on that let's say we have our framework target defined in a separate project and instead of Debug configuration we have Debug Production.

If you build the app for Debug Production configuration and you have enabled option "Find Implicit Dependencies" in build schema (it's enabled by default) Xcode will first try to build framework for this configuration. But as there is no such configuration in framework project it will fallback to default, which turns out to be Release:

But the app target will be built normally for Debug Production configuration:

That all will create build products at different paths, and apparently cause the error:

In fact it will be even worse because it will fail to compile only from clean state. If you build an app target again after failure without cleaning derived data folder it will compile. It's very easy not to notice that when you are building locally and then you will only see these errors on a build machine where typically build is done from clean state.

That's all will make you (me) wonder what a hell is going on, trying to look at performed build steps, blaming parallelize building, blaming custom configurations and Xcode, blaming Apple and the whole universe for making your life so miserable.

The solution

Turns out there are several ways to solve the issue.

First option is not to use a separate project for the framework target and include it in the app target's project. That will make both the app and the framework targets to share configurations, build products will be placed at the same path and there will be no linking errors. This approach though can make Xcode slower because it will need to index all source files, both from the app and from the framework.

If you still need to use a separate project for the framework you have two options left.

One is not to use custom build configurations or to create the same build configurations in framework project. The actual build settings does not matter, just configurations should be named the same. That's clearly not the best solution because you simply may not need these configurations for the framework. Or you may need to use completely different configurations there. Then it will probably not work at all. But that's one of the easiest way to make your app to build. And think if you can to replace build settings with environment variables and arguments.

The last option is to use custom module map and import Objective-C headers there instead of umbrella header. That will make them available from Swift code both in the framework and in the target that links to that framework. And it's very easy to do. You can find the default module map generated by Xcode inside the framework. It will look like this:

framework module UIKitExtensions {
    umbrella header "UIKitExtensions.h"

    export *
    module * { export * }
}

module UIKitExtensions.Swift {
    header "UIKitExtensions-Swift.h"
}

UIKitExtensions.Swift module will be always generated by Xcode so we don't need to include it in our custom module map. All we need to do is to import Objective-C header in UIKitExtension module (don't forget to remove it from umbrella header):

framework module UIKitExtensions {
    umbrella header "UIKitExtensions.h"
    header "UIAppearance+Swift.h"

    export *
    module * { export * }
}

Then set the path to module map file in Build Settings fo the framework:

With that when you try to build your target from clean state there will be no error any more.

Though this solution works I'm not entirely sure that it's a correct use of module maps. Here is a good starting guide on that matter.

And here is a demo project that demonstrates the original issue and solves it with custom module map. Please feel free to correct any of my statements and prove that I'm doing something wrong here and the problem is in some other build settings, project setup or something else. Or that there is a much better solution to this problem.

Frameworks, Keychain, NSCoding and Swift

Fri, 30 Sep 2016 08:30:00 GMT

One of the strategies that we use at HelloFresh to reduce compile time, improve code reuse and overall codebase health is breaking our code into frameworks. We've started with two core layers - domain and network. We broke these layers into four different frameworks: domain, generic API client, implementation of API client based on Alamofire and endpoints containing collections of requests that we can make to our API. Simply breaking these layers into frameworks already gave us a lot - it was easier to concentrate on particular parts of the code, define seams between them, cover them with tests and finally replace horrible legacy code that already started to bite us in the ass as we were moving forward with new features. And after few weeks when we started to work on the app extension we were able to reuse those frameworks.

While we were continuing to write tests we also had to extract some shared tests functionality into a separate framework, containing some custom asserts and helper methods. Some of them were depending on types defined in the domain framework. That created situation that we could not use those helpers in domain framework tests, because it would create a circular reference. At the same time we noticed that we need to reuse some other parts of our codebase, in particular date formatters which were used both in the UI and in the API layer. We could put them in the domain framework (and that is what we did at first), but we did't feel that this code really belongs to that layer. So we decided to create foundation framework and extract everything except actual domain models from domain framework - JSON serialization helpers, custom calendar and bunch of other very basic stuff. At the same time I decided to merge all API related frameworks into one, following package principles.

In new setup we again had four frameworks, but arranged differently: foundation, test, domain and api framework. And that is when I faced an unexpected problem. It was reading from the Keychain.

The problem is that we're storing in the Keychain some of the data which type was defined in a framework that we get rid of (endpoints). More than that as it was a Swift struct that can not be stored in the Keychain as it requires NSCoding compliance we wrapped it in a box type, that moved from one framework (domain) to another (foundation). After introducing new frameworks setup everything was compiling fine, but at runtime we got a crash trying to read that data from the Keychain. The reason is that when we store data in the Keychain (and not only then) its type will have a "mangled" name: _TtGC16HelloFreshDomain11NSCodingBoxV19HelloFreshEndpoints11XXXXXX_ (where XXXXXX is a name of a Swift struct that we are storing in the Keychain). As you can see it contains not only type names, but also module names (and looks like both of them are prefixed by their characters count). After moving to the new frameworks setup all of these modules names changed and runtime type that we were trying to read from the Keychain was not matching the type of stored data anymore. And that causes a crash.

Foundation provides two different ways to fix that problem. The first one is to implement NSKeyedUnarchiverDelegate protocol method func unarchiver(_ unarchiver: NSKeyedUnarchiver, cannotDecodeObjectOfClassName name: String, originalClasses classNames: [String]) -> AnyClass?. It will be called if data can not be decoded, for instance because of types mismatch. If we return some class unarchiver will try to decode data using this type.
We could not use this method as a library that we use for keychain access uses static NSKeyedUnarchiver methods, so there is nothing to attach a delegate to.

Luckily there is a second way. Before reading data from the Keychain you can call class func setClass(_ cls: Swift.AnyClass?, forClassName codedName: String)of NSKeyedUnarchiver and set the new type to use for decoding data stored as another type. The end result will be the same as using a delegate.

For sure it is not Swift-only problem but "mangled" Swift types' runtime names makes it a bit harder, because you can not really know that name before you see it in a crash report. You can get it programmatically using NSStringFromClass(SwiftType.self), but it's not likely you will do it before you actually face a type mismatch issue, when it is already a bit late as most likely you already removed old types. And that leaves you with horrible hardcoded string names.

P.S. I hope after that I will not have nightmares where Chris Latner or Joe Groff are calling me by my Swift runtime full name.

Xcode & cross-platform frameworks

Thu, 18 Aug 2016 01:47:37 GMT

Recently I came across an article by Max Howell describing how he had setup PromiseKit project to use just a single target instead of a separate target for each platform. As I have a side-project framework I'm working on I was interested to try this setup. Here is what I've found out.

In general there is nothing special in the setup and it works both in Xcode 7 and Xcode 8.

First you need to specify that the framework target supports all the platforms, not forgetting about simulators. If you already have separate framework targets, like I had, you can notice that, for instance tvOS target supports appletvos and appletvsimulator (just try to change tvOS in Supported Platforms build setting to Others... and you will see the list). So we just need to combine all these values in one single target. At the end you will have the following list of platforms:

SUPPORTED_PLATFORMS = "macosx iphoneos iphonesimulator appletvos appletvsimulator watchos watchsimulator"

Next you need to set deployment target for each of these platforms in Deployment section of build settings.

The next step is to make sure that in TARGETED_DEVICE_FAMILY setting in User-Defined build settings you have listed all of supported platforms where 1,2 - iOS, 3 - tvOS, 4 - watchOS. So if you support all four platforms you need to set it to 1,2,3,4.

Then you in run destinations list you will see all different devices grouped by platforms:

Now you will be able to build your framework for different platforms simply by selecting corresponding device as a destination.

Test targets

Test targets are a bit different. The same way you can use a single test target for all supported platforms. But there is a difference between test bundle layout on macOS and other platforms. For tests to be able to locate your framework and load it at runtime we need to provide different Runpath Search Paths for macOS target:

LD_RUNPATH_SEARCH_PATHS = "@executable_path/Frameworks @loader_path/Frameworks";
"LD_RUNPATH_SEARCH_PATHS[sdk=macosx*]" = "@executable_path/../Frameworks @loader_path/../Frameworks";

Then you will be able to run your tests on different platforms using just one target (if you are not that lucky just like me you will need to clean your project and restart Xcode several times before it will really work).

Tip: To manage build settings both for your main target and test target it will make sense to define supported platforms on a project level and then inherit this setting on a target level.

Dependency management

If you are working on an open-source framework then probably you support Carthage and Cocoapods (if you don't support one of them you really should). These tools perfectly support this kind of project setup without need to change anything. I haven't checked Swift Package Manager yet but looks like it is a default setup for Xcode projects that it generates, so I guess it will be supported out of the box.

Gotchas

There are few gotchas that I have found along the way. First happens when your cross-platform framework depends on another framework and you manage this dependency with Carthage. To sole it you need to modify Framework Search Paths build setting to point to specific Carthage subfolder (don't forget about simulators):

"FRAMEWORK_SEARCH_PATHS[sdk=appletvos*]" = "$(SRCROOT)/Carthage/Build/tvOS";
"FRAMEWORK_SEARCH_PATHS[sdk=appletvsimulator*]" = "$(SRCROOT)/Carthage/Build/tvOS";
"FRAMEWORK_SEARCH_PATHS[sdk=iphoneos*]" = "$(SRCROOT)/Carthage/Build/iOS";
"FRAMEWORK_SEARCH_PATHS[sdk=iphonesimulator*]" = "$(SRCROOT)/Carthage/Build/iOS";
"FRAMEWORK_SEARCH_PATHS[sdk=macosx*]" = "$(SRCROOT)/Carthage/Build/Mac";

Then you will need to modify copy frameworks build step in your test target. You can copy required frameworks manually or use Carthage's copy-framework tool.

When using copy-framework we must provide input files (paths to frameworks to copy) using Input Files list. But that in fact will be equivalent to defining SCRIPT_INPUT_FILE_COUNT and SCRIPT_INPUT_FILE_n environment variables. So here is a script I wrote for that:

for path in $FRAMEWORK_SEARCH_PATHS
do
    if [-d "${path}/Dip.framework"] && [[$path == *"Carthage"*]]; then
        export SCRIPT_INPUT_FILE_COUNT=1
        export SCRIPT_INPUT_FILE_0="${path}/Dip.framework"
        /usr/local/bin/carthage copy-frameworks
        break
    fi
done

Here I search for the dependency framework in $FRAMEWORK_SEARCH_PATHS located in a Carthage build folder and then define environment variables required for copy-frameworks

The next problem happens if your target contains arbitrary resource files (for instance Interface Builder files) that differ from platform to platform. It will also require a Run Script build phase. In Dip-UI I have to test how framework integrates with storyboards. Thus I need to use storyboards in test target. But not only storyboards are implemented by different classes on iOS and macOS (UIStoryboard and NSStoryboard), but they also require different storyboard files. Storyboards have to be not just copied as other resources, but also compiled. There is no way to make Xcode compile storyboards conditionally depending on a platform other than doing it with a script. Here is a script I ended up with:

ibtool --compilation-directory "${TARGET_TEMP_DIR}" "${SRCROOT}/DipUITests/${STORYBOARD_NAME_PREFIX}Storyboard.storyboard"
ibtool --link "${TARGET_BUILD_DIR}/${UNLOCALIZED_RESOURCES_FOLDER_PATH}" "${TARGET_TEMP_DIR}/${STORYBOARD_NAME_PREFIX}Storyboard.storyboardc"

There are two steps - compiling storyboard and linking, which copies compiled storyboard to resources folder.
To come up with correct commands I simply inspected Xcode logs when it was building platform-specific test targets and removed unneeded command line arguments. It works for me as I use very simple storyboards but you may need to provide some additional parameters.

Notes:

1. STORYBOARD_\_NAME__PREFIX defines different prefix for storyboard files for different platforms.

2. You will probably need to go to storyboards and check if your view controllers have correct Module in Identity Inspector.

Surprisingly when I had separate framework targets for tvOS and iOS I could use the same iOS storyboard both in iOS test target and in tvOS test target. This didn't work when I switched to a single framework target. So I also had to create a new storyboard specifically for tvOS.

The last issue I faced happens if you have your framework as a separate target defined in the same project and if you have few targets built for different platforms that depends on that framework. The most obvious example is iOS app and its extensions. The problem is that in this case Xcode does not automatically build the framework for all required targets. Again there is nothing that can not be solved with a custom build script. Just add xcodebuild command to the builds steps of your extensions. Alternatively I would recommend using moving frameworks to the separate project and link your main targets with prebuilt binaries (or just use Carthage).

These issues make the setup a bit tricky but I believe that for 98% of project it will be not a case at all.

Conclusion

With single-target project maintaining cross-platform frameworks becomes a breeze and I definitely encourage you to spend thirty minutes to adopt this setup in your project right now. Chances are very small that you will need to handle some tricky situation but most likely you will be able to solve it with few simple scripts.

Douglas-Peucker algorithm

Sat, 13 Aug 2016 22:49:39 GMT

This post is a part of the series about shapes recognition. This post is also available as a part of a playground.

When drawing by hand, especially in a slow manner, we will get a lot of touch points and the resulting curve will contain lots of close points. Also we can not draw ideally, so resulting curve can contain artifacts like hooklet at the end of the curve, closed shapes can not be ideally closed. These artifacts are insignificant for recognizing a shape and only complicate calculations. To eliminate deviation from "ideal" curve there are different preprocessing algorithms that we can apply before proceeding to the next steps of shape recognition.

Douglas-Peucker algorithm

When implementing smooth freehand drawing we were making our curve more complex by transforming line segments to Bezier curves. Now we will do opposite procedure - we will simplify our curve by removing insignificant points. Douglas-Peucker algorithm is one of the tools to solve that problem.

The purpose of the algorithm is, given a curve composed of line segments, to find a similar curve with fewer points. The algorithm defines 'dissimilar' based on the maximum distance between the original curve and the simplified curve (i.e., the Hausdorff distance between the curves). The simplified curve consists of a subset of the points that defined the original curve.¹

The input of the algorithm is a curve represented by an ordered set of points (P1,...,Pn) and the threshold ℇ > 0. The output is the curve represented by the subset of the input set of points.

On the first step of the algorithm we search for the farthest point (Pz) from the line segment between the start and the end points (P1 and Pn). If that point is closer than the threshold (ℇ) all the points between P1 and Pn are discarded. Otherwise the Pz is included in the resulting set. Then we repeat the same step recursively with the right and the left parts of the curve (from P1 to Pz and from Pz to Pn). Then we merge the results of processing the left and the right parts. Algorithm repeats until all the points are handled.

Simplifying a piecewise linear curve with the Douglas–Peucker algorithm.²

First let's write a helper function that will find the farthest point.

For brevity I don't include functions that are used to calculate the distance between the point and the line segment. They are pretty trivial geometric calculations and you can find them in the source files for this playground.

    typealias FarthestPoint = (index: Int, point: CGPoint!, distance: CGFloat)
    
    func farthestPoint(points: [CGPoint]) -> FarthestPoint? {
    var farthest: FarthestPoint?
    
    //if there are less then two points in the set return nil
    guard points.count >= 3 else { return farthest }
    
    let (p1, pn) = (points.first!, points.last!)
    
    //find the farthest point from the line segment between the start and the end points
    for i in 1..<(points.count - 1) {
        let distance = points[i].distance(to: (p1, pn))
        if distance > (farthest?.distance ?? -CGFloat.max) {
            farthest = (i, points[i], distance)
        }
    }
    return farthest
    }

With that function it is trivial to implement the algorithm.

     func douglasPeucker(points: [CGPoint], tolerance: CGFloat) -> [CGPoint] {
        //if the farthest point can not be found include all points from the input set
        guard let farthest = farthestPoint(points) else { 
            return points 
        }
        //if the farthest point is closer than a threshold only include the start and the end points of the input set
        guard farthest.distance > tolerance else { 
            return [points.first!, points.last!]
        }
     
        //Otherwise recursively apply the algorithm to the left and to the right parts of the set
        let left = douglasPeucker(Array(points[0...farthest.index]), tolerance: tolerance)
        let right = douglasPeucker(Array(points[farthest.index..<points.count]), tolerance: tolerance)
     
        //Now merge left and right parts removing duplicated point
        return Array([Array(left.dropLast()), right].flatten())
     }

Let's see how this algorithm works on a sample set of points.
First here is the input path built by connecting each sample point with line segments:

Here is the resulting path with threshold value of 5. You can play with it and see how higher values will discard more points.

Here you can see how each step of the algorithm performs. The farthest point on the each step is marked with a square. Points discarded on a previous step are drawn with a cross.

The algorithm can be implemented without recursion but I will leave it for you as an exercise.

Hint: Usually recursion can be replaced by using stacks.

Freehand drawing

Sun, 31 Jul 2016 16:53:01 GMT

This post is a part of the series about shapes recognition. This post is also available as a part of a playground.

Naive implementation of rendering user's freehand drawing is strait forward. We need to listen to touch events from view and construct the path appending lines to each subsequent point.

public class LineDrawing: Drawing {
    public var canvas: DrawableView?
    public var path = UIBezierPath()
    
    public init() {}

    public func touchesBegan(at point: CGPoint) {
        path.removeAllPoints()
        path.moveToPoint(point)
    }

    public func touchesMoved(to point: CGPoint) {
        path.addLineToPoint(point)
    }

    public func touchesEnded(at point: CGPoint) {
        path.addLineToPoint(point)
    }

    public func touchesCancelled(at point: CGPoint) {
        path.removeAllPoints()
    }
}

But usually such naive approach does not provide acceptable results. Strokes looks ridgid and angular.

Luckily it's not very hard to improve our drawing strategy by utilizing Bezier curves. Intead of appending line segments we can append curve segments. We need four points to draw Bezier curve - start point, end point and two control points. So we need to accumulate touch points in array up to four, append curve segment and flush points array.

public class CurveDrawing: Drawing {
    public var canvas: DrawableView?
    public let path = UIBezierPath()
    var controlPoints: [CGPoint] = []

    public init() {}

    public func touchesBegan(at point: CGPoint) {
        controlPoints = [point]
        path.removeAllPoints()
        path.moveToPoint(point)
    }

    public func touchesMoved(to point: CGPoint) {
        guard controlPoints.count == 3 else {
            controlPoints.append(point)
            return
        }
        path.addCurveToPoint(
            point,
            controlPoint1: controlPoints[1],
            controlPoint2: controlPoints[2]
        )
        controlPoints = [point]
    }

    public func touchesEnded(at point: CGPoint) {
        if controlPoints.count > 1 {
            for _ in controlPoints.count..<4 {
                touchesMoved(to: point)
            }
        }
        controlPoints = []
    }

    public func touchesCancelled(at point: CGPoint) {
        path.removeAllPoints()
    }
}

When touchs end we can loose some points at the end of the curve. To avoid that we repeat the last recorded point until we have enouth points to draw the last segment. Dependeing on how many points are missing it can result in a line or curve segment.

Looks better but still not ideal. As you can see there are obtuse angles at the points where two curves connects. We can avoid that by shifting this point to the median of second control point of the first curve and the first control point of the next curve.

Instead of accumulating four control points we will take one more and use it as a first control point of the second curve. Then we calculate new end point for the first curve and create a curve itself. At the end we flush control points array and store there shifted end point (it will be start point if the next curve) and the first control point of the next curve that we already have.

public class SmoothDrawing: Drawing {
    //The rest of the code is the same as in CurveDrawing
    
    public func touchesMoved(to point: CGPoint) {
        guard controlPoints.count == 5 else {
            controlPoints.append(point)
            return 
        }
        let endPoint = CGPoint(
            x: (controlPoints[2].x + point.x)/2,
            y: (controlPoints[2].y + point.y)/2
        )
        path.addCurveToPoint(
            endPoint,
            controlPoint1: controlPoints[1],
            controlPoint2: controlPoints[2]
        )
        controlPoints = [endPoint, point]
    }
    
    public func touchesEnded(at point: CGPoint) {
        if controlPoints.count > 1 {
            for _ in controlPoints.count..<5 {
                touchesMoved(to: point)
            }
        }
        controlPoints = []
    }
}

Lastly in iOS 9 we have access to coalescing touches (when touch moves we can get more touch points between previous and current touch location), touches prediction and precies touch location. They can be used to achieve even more accurate result. If we have access to coalesced touches we can simply process them one by one as we normally do for other touches. Touch prediction can be used to complete smoothed path in a more intellegent way. Also we can access other touch parameters such as force (to control the path thikness) or stylus orientation. Play with it if you have access to supported devices and check out WWDC session on that topic.

Dependency Injection (DI) in Swift

Sat, 28 May 2016 18:24:56 GMT

This post is a script of the talk that I've made on UIKonf'16. That was a first time for me to present on such a big conference and honestly I'm not even close to a public speaker so you may enjoy just reading it more. Anyway here is the video. And slides are here.

For many of us Swift opened up a world of functional programming. But it is still much more object oriented language than functional. And our main tools - Cocoa frameworks - are object oriented. So probably we ourselves will still keep writing object oriented code. The problem with that is that it is actually hard to write well designed object oriented code.

There are bunch of different design principles, like SOLID, KISS, DRY and others (YAGNI, RAP, CQS), and even more design patterns. Just the fact that there are so many different principles and patterns means, at least for me, that good object oriented design is hard, if ever possible.

Dependency Injection is itself not a part of SOLID principles that I have just mentioned. But it strongly relates to all of them. Unfortunately the concept of Dependency Injection is surrounded with many misconceptions.

Wikipedia gives us very complex definition:

"In software engineering, dependency injection is a software design pattern that implements inversion of control for resolving dependencies." - Wikipedia

And few more sentences... In contrast some developers say that dependency injection is just passing in an instance variable.

"Dependency injection is really just passing in an instance variable." - James Shore

Others think that it is some kind of voodoo magic that requires to use complicated and slow frameworks, or that it is only relevant for testing and just makes code harder to understand. I would say that all of these are misconceptions about Dependency Injection.

I will try to make it more clear, as far as I can, and show what I've learned about Dependency Injection. I will try to show how we can do Dependency Injection. And more than that how we should not do it.

Why Dependency Injection?

To start let's see what problems Dependency Injection tries to solve in the first place.

In programming we always have to deal with abstractions of different kinds and levels. They are just everywhere. Interfaces, methods, closures and even concrete types and variables names - they are all abstractions.

For a good code design it's very important to use proper abstractions because they make our code loosely coupled. That means that different componenets of our code can be replaced with alternative implementations without affecting other components. When our code is loosely coupled it becomes easier to test, easier to extend, easier to reuse, easier to develop in parallel. That all makes it easier to maintain.

Loosely coupled code is the main goal of Dependency Injection. It enables us to write loosely coupled code. And thus it makes testing, extending and reusing code much easier.

Very often Dependency Injection is discussed only in context of Unit Testing. And indeed it improves testability a lot, especially in Swift. But the real picture is much wider. If our final goal is not just unit testing some classes but loose coupling and making our code maintainable then we will need to make a bit more effort than just passing instance varibales.

Though it is true that in its essence Dependency Injection is about passing instance variables or better to say passing dependencies to their consumers. This is the first step and as each first step it is the most important one. But that is only one part of a story. There are also a second and even a third step. And these steps make the difference between just passing variables and Dependency Injection.

Dependency Injection Patterns

So let's start with the first step. There are few patterns how we can pass dependencies to their consumers:

Custructor Injection
Property Injection
Method Injection
Ambient context

Let's see how they look like using examples from Cocoa frameworks.

Constructor injection

Here is an example of constructor injection from CoreData:

class NSPersistentStore : NSObject {

    init(
        persistentStoreCoordinator root: NSPersistentStoreCoordinator?, 
        configurationName name: String?, 
        URL url: NSURL, 
        options: [NSObject: AnyObject]?
    )
        
    var persistentStoreCoordinator: NSPersistentStoreCoordinator? { get }
    
}

Here the instance of persistent store coordinator is passed in constructor of NSPersistentStore along with some other parameters. Then reference to coordinator is stored and can not be changed in runtime.

With constructor injection we pass dependencies as cunstructor arguments and store them in readonly properties.

Though there are not so many examples of constructor injection in Cocoa frameworks, it is the prefered way to inject dependencies. Because it's the easiest one to implement, it ensures that dependencies will be always present and that they will not change at runtime what makes it much safer.

But there are cases when constructor injection is not possible or does not fit well. In these cases we should use property injection.

Property injection

This pattern is all over the place in any iOS application. For example delegate pattern is often implemented using property injection.

extension UIViewController {

    weak public var transitioningDelegate: UIViewControllerTransitioningDelegate?
            
}

Here for example view controller exposes writable property for transitioning delegate that we can change at any moment if we want to override the dafault behavior.

With property injection consumer gets its dependency through writable property that also has some default value.

Local & foreign defaults

Property injection should be used when there is a good local default for dependency. "Local" means that it is defined in the same module. nil is also a perfect local default, it just makes dependency optional.

When implementation comes from a separate module it is foreign. Then we should not use it as a default value. And we should not use property injection for such dependency. Instead we should use constructor injection.

Imagine that default implementation of transitioning delegate is defined not in UIKit, but in some other framework. Then we will always need to link to this framework even if we never use this API. UIKit becomes tightly coupled with that framework. And it drags along this unneded dependency. The same can happen with our own code and that will make it harder to reuse.

Comparing with constructor injection property injection is maybe easier to understand and it makes our API to look more flexible. But at the same time it can be harder to implement and can make our code more fragile.

First of all we need to have some default implementation in place or handle optional value in a proper way which can lead to cluttering code with unwrapping optionals. Secondly, we can not define our property as immutable. So if we don't want to allow to change it once it was set we will need to ensure that at runtime instead of compile time. Also we may need to synchronise access to it to prevent threading issues. For these reasons if we can use constructor injection we should prefer it to property injection.

Method injection

Next pattern, method injection, is as simple as passing argument to a method. For example here is NSCoding protocol:

public protocol NSCoding {

    public func encodeWithCoder(aCoder: NSCoder)
    
}

Each time the method is called different instance and even implementation of NSCoder can be passed as an argument.

With method injection dependency is passed as a parameter to a method.

Method injection is usually used when dependency can vary with each method call or when dependency is temporal and it is not required to keep reference to it outside of a method scope.

Ambient context

The last pattern - ambient context - is hard to find in Cocoa. Probably NSURLCache is the most close example.

public class NSURLCache : NSObject {

    public class func setSharedURLCache(cache: NSURLCache)
    
    public class func sharedURLCache() -> NSURLCache
    
}

Here for example we can set any subclass of NSURLCache as a shared instance and then access it with static getter. And this is its main difference from singleton which is not writable.

Ambient context is implemented using static method or static writable property with some default value.

This pattern should be used only for truly universal dependencies that represent some cross-cutting concerns such as logging, analitycs, accessing time and dates, etc.

Ambient context has its own advantages. It makes dependency always accessible and does not pollute API. It fits well in case of cross-cutting concerns. But in other case it does not justify its disadvantages. It makes dependency implicit and it represents a global mutable state which is maybe not what you want.

So if the dependency is not truly universal first we should consider using other DI patterns.

Separation of concerns

As you may notice all these patterns are very simple and they share one common principle - separation of concerns. We remove several responsibilities from the consumer of dependency: what concrete implementation to use, how to configure it and how to manage its lifetime. This lets us easily substitute dependency in different context or in tests, change its lifetime strategy, for instance use shared or separate instances, or to change the way how the dependency is constructed. All without changing its consumers. That makes concumers decoupled with their dependencies, making them easier to reuse, extend, develop and test.

The obvious side effect of these patterns is that now every user of our code needs to provide its depnendecies. But how do they get them? If they create them directly then they become tigthly coupled with those dependencies. So we just move the problem to another place. This problem brings us to much less dicussed DI pattern called Composition Root.

Composition root

Composition Root is a place where components from different layers of the application are wired together. The main point of having composition root is to separate configuration logic from the rest of our code, do it in a well defined place in a common manner. Having a piece of code which single responsobility is to configure other components. Creating dependencies and injecting them in constructors or properties should be done only in the Composition Root.

^[1]

Ideally there should be one Composition Root in the application and it should be close to application entry point. Like on this diagram. But it does not have to be implemented with a single method or a class. It can contain as many classes and methods as needed until they stay together at the same layer of components.

Here is for example implementation of Composition Root from VIPER example application.^[2]

class AppDependencies {
    init() {
        configureDependencies()
    }
    
    func configureDependencies() {
        // Root Level Classes
        let coreDataStore = CoreDataStore()
        let clock = DeviceClock()
        let rootWireframe = RootWireframe()
        
        // List Module Classes
        let listPresenter = ListPresenter()
        let listDataManager = ListDataManager()
        let listInteractor = ListInteractor(dataManager: listDataManager, clock: clock)
        ...    
        listInteractor.output = listPresenter
        listPresenter.listInteractor = listInteractor
        listPresenter.listWireframe = listWireframe
        listWireframe.addWireframe = addWireframe
        ...
    }
}

Here we have some root classes, root wireframe that only manages window root view controller and some separate components for some list of todo items, like presenter, interactor, wireframe. Then we just wire them all together. And it is all implemented in one class. And the only place where we use this class is the app delegate:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?
    
    let appDependencies = AppDependencies()

    func application(
        application: UIApplication, 
        didFinishLaunchingWithOptions launchOptions: [NSObject : AnyObject]?) -> Bool {
        
        appDependencies.installRootViewControllerIntoWindow(window!)
        
        return true
    }
}

Here we first create dependencies class which will configure all of the components and wire them together. Then we just call a method that sets root view controller in a window.

So the entire objects graph will be created here with a single call and the only objects which will be created later in runtime are view controllers and views.

Unfortunatelly Composition Root is usually not discussed in articles or talks about DI. But it is probably one of the most important parts of Dependency Injection. If we manage to do that we have already come a long way.

The biggest challange of properly implementing DI is getting all classes with dependencies moved to Composition Root. - Mark Seeman

Anti-patterns

But as it often happens while we are trying to properly implement some patterns we can easily end up with anti-patterns. So, now let's move on to the dark side and see what are the common DI anti-patterns.

Control freak

The first one is control freak. That is simply when we don't use DI at all. When consumer of dependency controls how and when the dependency is created. It happens every time when consumer gets a dependency directly or indirectly using constructor anywhere outside Composition Root. For example in its own constructor or just when it needs it.

class RecipesService {

    let repository: RecipesRepository
    
    init() {
        self.repository = CoreDataRecipesRepository()
    }
}

But does that mean that we are not allowed to use constructors at all? Of course not. It depends on what kind of dependency we construct.

Stable & volatile dependencies

There are two kinds of them - stable and volatile. When it comes to stable dependencies we should not worry about constructing them directly inside their consumer. But we should avoid doing that for volatile dependencies.

What is a volatile dependency? Any dependency that requires some specific environment setup, like database or network access. Dependencies that implement nondeterministic behaviour are volatile, for example if they use random numbers, depend on time or implement cryptography. When we expect dependency to be replaced or it is simply not ready yet because it is developed in parallel - it is also volatile.

The symptom of volatile dependencies is that they disable some of loose coupling benefits. If dependency does not let us test, extend, reuse or develop our code in parallel - it should be considered as volatile. Otherwise it is a stable dependency.

So first of all we need to understand if the dependency is volatile or stable and inject it with Dependency Injection patterns when it is volatile.

Bastard injection

The next anti-pattern is called Bastard injection. That happens when we have constructor that lets us provide dependencies for tests and another constructor with default implementations used in production. In Swift we can do that easily with default arguments like in the following example.

class RecipesService {

    let repository: RecipesRepository
    
    init(repository: RecipesRepository = CoreDataRecipesRepository()) {
        self.repository = repository
    }
}

From one point this pattern improves testability. The problem of this anti-pattern is in using as a default a foreign default - defined in other module. That makes our code testable, but tightly coupled with another module. If default implementation is local the impact of this anti-pattern is much smaller. Maybe it will be better to refactor it to property injection instead. But when default implementation is foreign we should use constructor injection and do not provide default value for this argument. Instead we should provide it in the Composition Root. This way we don't loose any flexibility but avoid tight coupling with another module.

Service locator

The last anti-pattern I will talk about is a Service Locator. Service Locator is a common name for some service that we can query for different objects that were previously registered in it. It is the most tricky anti-pattern because it can make us feel that everything is absolutely fine. Many developers do not even consider it as an anti-pattern at all. But Service Locator is in fact oposite to Dependency injection.

Let's look at an example:

let locator = ServiceLocator.sharedInstance

locator.register( { CoreDataRecipesRepository() }, 
                    forType: RecipesRepository.self)

class RecipesService {

    let repository: RecipesRepository
    
    init() {
        let locator = ServiceLocator.sharedInstance
        self.repository = locator.resolve(RecipesRepository.self)
    }
}

In this example we have some service that we can access using static property. Then for the type of our dependency we register a factory that produces some concrete instance. Then we ask this service for our dependency when we need it instead of using constructor or property injection.

It seems like Service Locator provides all the benefits of Dependency Injection. It improves extensibility and testability because we can register another implementation of dependency without changing its consumer. It separates configuration from usage and also enables parallel development.

But it has few major drawbacks. It makes dependencies implicit instead of explicit what hides real class complexity. To be able to use this class we now need to know its internal details. We don't see its dependencies and will find out about them only at runtime or by inspecting its implementation or documentation. Also with service locator our code becomes tightly coupled with it. That completely breaks reusability and makes code less maintainable.

For these reasons I tend to think that Service Locator is an anti-pattern. Instead of using it we should define dependencies explicitly, use DI patterns to inject them and use Composition Root to wire them together.

So lets sum up what we have discussed by that point. We discussed that Dependency Injection is used to enable loose coupling what makes our code easier to maintain. We discussed different DI patterns among which constructor injection should be a prefered choise. We discussed what are local and foreign dependencies and what are stable and volatile dependencies. Also we discussed what are common DI anti-patterns that we should avoid.

At this point using DI patterns we've made our dependencies explicit and moved all the configurations in the Composition Root which is already a huge step forward to our goal - loose coupling.

But our code is not yet lossely coupled. The next big step for that is to model dependencies with abstractions. Lets remember one of the SOLID principles.

Dependency Inversion Principle (DIP)

Dependency Inversion Principle says that high-level code should not depend on lower-level code, they both should depend on abstractions and abstractions should not depend on details. The point is that the class and its dependency should be on the same level of abstraction. If we have some service it should not depend on concrete API repository or data base repository because they belong to lower level layer.

For example we should not depend on API repository implemented with Alamofire or data base repository implemented with CoreData or Realm. Because this will make our code tightly coupled with specific implementation. Instead we should depend on a higher level abstraction. Both service and repository should depend on that abstraction. So the direction of dependency between higher and lower levels is inverted.

And we should follow this principle to have loosly coupled code. Dependency Injection is not just patterns that we discussed before. It requires both patterns and Dependency Inversion Principle to be applied at the same time. Without that we will not get all the benefits of loose coupling.

DI = DI patterns + DIP

It is commonnly said that loose coupling is achieved by programming against interfaces and not to implementations.

Program to an interface, not an implementation (Design Patterns: Elements of Reusable Object-Oriented Software)

But Dependency Inversion Principle says that it is not about interfaces, but about abstractions. Loose coupling does not mean interfaces or protocols everywhere. Because not always interfaces are good and reusable abstractions.

Program to an ~~interface~~ abstraction

Interface (or a protocol) is just a language construct that we can use to model abstraction. It is a way how our code communicates with it. But it does not make any guarnatee for a good and reusable abstraction which is a key to loose coupling.

Base class can be sometimes as good abstraction as a protocol. Of course most of the time we probably will use protocols to model abstractions. But be careful with introducing protocols everywhere. It can be unneeded level of inderection. And in Swift protocols migth bite sometimes.

Interfaces are not abstractions - Mark Seeman ^[3]

When you pass a dependency in constructor, or using property or method injection - you should pass it as an abstraction (again, not nececerely using protocol). The same if you use ambinet context. It is not just some shared static instance - it should be an abstraction.

So Dependency Injection and Loose Coupling is achieved not just with Dependency Injection Patterns but also with Dependency Inversion Principle and modeling dependencies with abstractions.

Inversion of Control & DI Containers

But there is also one more step that we can make using another design principle. This principle is called Inversion of Control. It is often seen as a defining characteristic of frameworks.

When we use libraries the flow is "normal" and we call library from our code. But in case of frameworks it is inverted - framework calls our code using different callback methods.

And we can apply this principle for managing dependencies using special frameworks. Usually these frameworks are called Dependency Injection Containers.

There are bunch of different containers available. In fact most of you have used one DI container probably without even knowing that. It is Interface Builder. In Interface Builder we can drag-n-drop any NSObject and reference to it using @IBOutlet through interface or a base class. The same with view controllers. We can think of storyboards and xibs as factories for view controllers. Interface Builder is an example of XML configuration style. It is of course not a full featured DI container and it is not its primary goal but still it can be used for that.

If you go to CocoaPods and search for "dependency injection" you will find a lot of different open source DI containers. Maybe even too many of them. But you will notice that only few of them succeeded and became relatively popular. Let's shortly look at two of them - one that comes from Objective-C world and one from Swift. Typhoon and Dip.

Typhoon

http://typhoonframework.org

First one, Typhoon, is probably the most popular DI container among Cocoa developers. It has relatively simple and well documented API with lots of powerfull features. It is well maintained and supported and still continues to improve.

In terms of API Typhoon building blocks are objects called assemblies. Here is an example of such assembly interface. It looks like a simple factory.

public class APIClientAssembly: TyphoonAssembly {
    
    public dynamic func apiClient() -> AnyObject { 
        ... 
    }
    
    public dynamic func session() -> AnyObject { 
        ... 
    }
    
    public dynamic func logger() -> AnyObject { 
        ... 
    }
    
}

But in implementation instead of returning a concrete instance of some type like from factory method we return a TyphoonDefinition that describes how that instance should be created when it is requested. What initialiser should be used and with what perameters, what properties should be injected.

public dynamic func apiClient() -> AnyObject {
    return TyphoonDefinition.withClass(APIClientImp.self) { definition in
        
        definition.useInitializer(#selector(APIClientImp.init(session:))) {
            initializer in
            
            initializer.injectParameterWith(self.session())
        }
        
        definition.injectProperty("logger", with: self.logger())
    }
}

Here we define that APIClient will be created with init(session:) constructor and that it's session argument will be provided by the same assembly. Also we define that logger property will be injected with a logger instance also provided by the same assembly.

We can also define different scopes or lifetime strategies for components. For example with Singleton scope Typhoon will create only one instance of logger.

public dynamic func session() -> AnyObject {
    return TyphoonDefinition.withClass(NSURLSession.self) { definition in
        definition.useInitializer(#selector(NSURLSession.sharedSession))
    }
}
    
public dynamic func logger() -> AnyObject {
    return TyphoonDefinition.withClass(ConsoleLogger.self) { definition in
        definition.scope = .Singleton
    }
}

To get an instance of some type from assembly we first activate it and then just call its interface method. When activated assembly methods will return not TyphoonDefinitions but instances, created based on the rules that we provided.

let assembly = APIClientAssembly().activate()

let apiClient = assembly.apiClient() as! APIClient

To make this work Typhoon uses Objective-C runtime a lot. And in Swift applications using Objective-C runtime looks just not right. We still can use Typhoon in Swift as well as in Objective-C. But there are some problems we will face with:

Requires to subclass NSObject and define protocols with @objc
Methods called during injection should be dynamic
requires type casting
not all features work in Swift
too wordy API for Swift

Typhoon team recently announced that they started to work on pure Swift implementation, and I can't wait to see what they will come up with. But for now I would not use Typhoon in its current state in a pure Swift code base. Especially when there are already few native solutions.

Dip

https://github.com/AliSoftware/Dip

And Dip is one of them. It works only in Swift and it does not require Objective-C runtime at all. In fact it even does not have any references to Foundation, so we can use it on any platform where we can use Swift. It is also type-safe and implementation is not that complicated comparing with Typhoon.

In terms of API it takes approach that is more traditional for DI containers on other platforms and follows "register-resolve" pattern.

Here is the same example that we used for Typhoon.

let container = DependencyContainer()

container.register { 
    try APIClientImp(session: container.resolve()) as APIClient 
}
.resolveDependencies { container, client in
    client.logger = try container.resolve()
}

container.register { NSURLSession.sharedSession() as NetworkSession }
container.register(.Singleton) { ConsoleLogger() as Logger }

First we register APIClientImp as implementation of APIClient protocol. Container will also resolve contructor argument and when instance is created will set logger property. For session parameter container will use shared url session and for logger it will create a singleton instance.

Then when we need to get the instance of APIClient we simply call resolve method of the container:

let apiClient = try! container.resolve() as APIClient

You may notice that the API is almost the same as we saw in Service Locator. But it is not about API or implementation, it is about how we use it. If you don't want to use container as a Service Locator remember that you should call it only in the Composition Root.

Dip also provides some cool features like auto-wiring. For example we can define logger property to be automatically injected. Container will first create the instance of APIClient and then will use its mirror to find logger property and inject the real instance in it.

class APIClientImp: APIClient {

    private let _logger = Injected<Logger>()
    
    var logger: Logger? { return _logger.value }
    
}

Then when we register APIClient using its constructor instead of calling resolve to get a NetworkSession argument we just say that we want to use a first argument passed to the factory closure. Then container will infer its type and resolve it for us.

class APIClientImp: APIClient {
    init(session: NetworkSession) { ... }
}

container.register { APIClientImp(session: $0) as APIClient }

And that can simplify configuration a lot.

If we compare base features of Typhoon and Dip we will notice that they share most of them. It may seem surprising that almost the same features are possible in Swift even though it does not have powerfull runtime features like in Objective-C. But generics and type inference are in fact enougth for that.

										Typhoon                Dip 
										
Constructor, property, method injection     ✔︎                  ✔︎
Lifecycle management                        ✔︎                  ✔︎
Circular dependencies                       ✔︎                  ✔︎
Runtime arguments                           ✔︎                  ✔︎
Named definitions                            ✔︎                  ✔︎
Storyboards integration                     ✔︎                  ✔︎
------------------------------------------------------------------------

Auto-wiring                                 ✔︎                  ✔︎
Thread safety                               ✘                  ✔︎
Interception                                ✔         ︎         ✘
Infrastructure                              ✔︎                  ✘

You may ask why do I need to use Typhoon or Dip or any other DI container when I can do the same by my own. There are few reasons I can suggest. They provide easy integration with storyboards, manage components lifecycle for you that can be tricky some times, they can simplify some configurations, Typhoon also provides easy interception using NSProxy and some other additional features.

But remember that DI containers are optional and Dependency Injection is not the same as using DI container.

DI ≠ DI Container

In a new project we may start with it if we want, but in a legacy code base we should first refactor it using Dependency Injection Patterns, Composition Root and Dependency Inversion Principle and then see if DI container is needed or not (in most cases answer will be "no").

If you have complex configurations and you find yourself implementing something like DI container to simplify them or you need some additional features that it provides then probably you will benefit from using already existing implementation. But if you are ok with your own factories - its great and keep using them. Don't use DI container just for the sake of using it.

The same is true for DI itself. Be rational about where to apply it and what parts of your system you need to decouple. Don't try to solve problems that you don't have yet. Maybe you will never have them or the way that you solved them now will not fit when you really face them. At the end DI is just a means to an end, like any other pattern or technology that we use. It is not a goal itself.

In the end I want to mention some usefull resources where you can find more about DI and some related topics.

Mixing optional binding and boolean expressions

Thu, 28 Apr 2016 21:11:07 GMT

There were few times already when I used this little-known feature of Swift in real code and it improved (in my opinion) readability a lot and much better described the intention of the code.

Here is the original code from the real app:

if let cutoffDate = menu?.cutoffDate where menu?.mealSwapEnabledForProduct == true {
  ...
} else {
  ...
}

Very trivial piece of code. But it contains one problem - it communicate wrong intention. When optional binding comes first and is followed by where it may seem that we make decision based on the value in this optional and the boolean expression is secondary. But in fact decision here should be made based on the boolean expression.

We can make it much better because we don't have to have where always at the end of if statement:

if menu?.mealSwapEnabledForProduct == true,
  let cutoffDate = menu?.cutoffDate {
  ...
} else {
  ...
}

I think this way the code communicates our logic and intention much better.

In Swift we can combine optional binding with where and boolean expressions. But after we started optional binding block we can have only where at the end of it, or another optional binding block with its own where. So boolean expression can not appear after optional binding.

Here is the full grammar of if statement:

if-statement → if condition-clause code-block else-clause(opt)
else-clause → else code-block else if-statement

condition-clause → expression
condition-clause → expression, condition-list
condition-clause → condition-list
condition-clause → availability-condition, expression
condition-list → condition | condition, condition-list
condition → availability-condition | case-condition | optional-binding-condition
case-condition → case pattern initializer where-clause(opt)
optional-binding-condition → optional-binding-head optional-binding-continuation-list(opt) where-clauseopt
optional-binding-head → let pattern initializer | var pattern initializer
optional-binding-continuation-list → optional-binding-continuation | optional-binding-continuation, optional-binding-continuation-list
optional-binding-continuation → pattern initializer | optional-binding-head

So this grammar says that condition can start with expression (boolean) or availability condition, followed by condition list, which can contain another availability condition or case condition or optional binding. And as you can see condition list can contain several other condition lists.

For example this is a valid if statement:

if
  #available(watchOS 2, *), 
  booleanExpr1 && booleanExpr2, 
  #available(iOS 9, *), 
  let value11 = value1 where value11 > 0,
  case let .Some(value1) = value1 where value1 > 0,
  #available(OSX 10, *), 
  case let .Some(value2) = value2 where value2 < 0,
  let value22 = value2 where value22 < 0 {

~= vs Range.contains(_:)

Thu, 14 Apr 2016 22:50:00 GMT

Today I was working on simple validators that we use for forms (backed by awesome Eureka) and had to implement validator that validates string length. So I did it like this:

struct StringValidator: Validator {
    typealias ValueType = String
    
    let stringRange: Range<Int>
    init(stringRange: Range<Int> = 1..<Int.max) {
        self.stringRange = stringRange
    }
    
    func validate(value: String?) -> Bool {
        guard let value = value?.stringByTrimmingCharactersInSet(.whitespaceAndNewlineCharacterSet()) else {
            return true
        }
        return stringRange.contains(value.characters.count)
    }
}

The idea is simple. Form field can have a validator with default range (1..<Int.max) that will validate any not empty string, but it can also setup validator with specific range that will define minimum and maximum string length. Using isEmpty on string is not an option because it makes a special case and for that I will need to define a separate validator like NonEmptyStringValidator what looks unnecessary.

Then I wrote some tests. And noticed that when I pass an empty string as a value and expect that it will fail validation test never completes. First I thought that there is some issues when I combine several validators together. But the reason is much simpler. Range is a SequenceType. And SequenceType provides default implementation for contains(_:) method that simply iterates through all sequence members. Probably Range does not override it so it is iterated from 1 to Int.max and each index is compared with 0. For me it looks strange because I don't see any problem with providing specific implementation of that method that will only check bounds. It will not break the contract of SequenceType. It does not look like Range can contain indexes in random order or can be discontinuous. But for whatever reason we don't have it in stdlib.

I definitely didn't want to compare range startIndex and endIndex manually. So my first attempt to fix this was moving to NSRange:

return NSLocationInRange(value.characters.count, NSRange(stringRange))

It works and only checks for range bounds. But that does not look nice either.

After some time I found much better solution (I think it dawned on me at the moment when I switched to Safari tab with "Match me if you can" article):

return stringRange ~= value.characters.count

Works perfectly and looks much better than any other solution. Though I had to put a comment describing what it does because ~= is so rarely used by itself.

Also I found out that there are HalfOpenInterval and ClosedInterval that are returned from ... or ..< operators for Comparable generic argument. But for ForwardIndexType (which Int is) these operators return Range. Intervals are not collections or sequences and don't have aforementioned issue.

On package managers

Tue, 29 Mar 2016 19:16:28 GMT

I definitely agree with those who say that you should not depend on code from external source (meaning where and how it is hosted). You should check in any code or binaries, used by your project to your own repo. But in fact it is not enough.

Speaking specifically about iOS/OS X development if you are using CocoaPods or Carthage and work in a team you will end up, ironically, with managing versions of your package manager. The main problem of these tools is that you need them to be installed on the machine to build your project. When you work in a team that becomes even more complicated, because you must have the same versions of package manager to be installed for all team members.

The rule of one click

I will not argue about pros and cons of CocoaPods and Carthage comparing with manual setup and is it hard or not to manage them. I had to much bad experience with both of them in the past and don't completely trust neither of them. What does not mean they had not improved since then. In fact we are using Carthage in my current team and I was the one who was insisting on using it instead of CocoaPods. But I still have few life stories when it looked like these tools were not helping at all.

Anyway the main issue is still there. And it breaks the rule that I read, if I'm not mistaken, in "Clean code" by Robert C. Martin.

The rule is simple:

You should be able to build your project without installing anything but your IDE and with just one click.

We used to follow this rule. But then we decided that we need to simplify the process. And it was broken since then. And it became more and more complicated instead.
Therefore I hope SPM will finally make it possible to follow this rule again.

Another thing is that actually package manager can be meaningless in your case.

Do your dependencies depend on something else? Most likely not. And everything that you read about developing iOS/OS X frameworks/libraries will encourage that. So you most likely don't need complex dependencies graph resolution.

How often do you update your dependencies? Once a week? Once a month? Maybe one or two dependencies yes, but that is better for you to use more stable dependencies, not that are in active development. In fact you must have strong reasons to update your dependencies - obviously each update can not only fix bugs and add new features, but also introduce regression. And it is not always possible to investigate all changes made. So if frequent updates is not a usual thing it is maybe easier to do them manually.

For now the best option, as I can see it, if you want to take some advantage of using package manager is to use Carthage to checkout source code, check it in your repo (or use your own forks) but use Xcode to build it by adding these dependencies as subprojects or in a common workspace. If you still prefer to use Carthage to build frameworks I would also check in all build artifacts, so that you are sure that every developer will have the same binary version (you will still need to make sure you use the same version of Carthage at some point).

Creating a simple OS X app

Thu, 24 Mar 2016 09:42:58 GMT

OS X developers are kind of rare developer species. I don't know about you but among my fellow developers there is only one who is doing OS X. I'm not sure if Swift's popularity will (or already does) change something, most likely we will have more Swift backend developers instead.

Anyhow. Recently I came up with an idea of a simple app that can help me and my colleagues in our daily work. At HelloFresh when it comes to dates everything becomes very special. We don't use gregorian calendar week - instead our week starts on Saturday and ends on Friday. Though we still use ISO8601 standard. First I was surprised to know that in this standard the year of the week is defined by the year of that's week Thursday. My next surprise was that it is perfectly handled by NSCalendar.

So the idea for the app was obvious - to have a visual calendar that will provide correct week information. So that we always know what week is it now. A simple status bar app with popper calendar feels like a perfect solution. So here is what I learned building it (I didn't read any Apple's documentation, 'cause wanted to make it in one evening and used only stackoverflow).

First I found an open source calendar implementation (I could not use NSDatePicker 'cause was going to tweak it a bit) - MLCalendarView. There were not so many options to choose from, comparing with iOS - only two...

The rest I had to do was to create a status bar item. First I went to MainMenu.xib created by standard Cocoa App template and deleted menu and window from there - I will not need them anyway.

Then I created my status item:

lazy var statusItem: NSStatusItem = {
    let statusItem = NSStatusBar.systemStatusBar().statusItemWithLength(NSVariableStatusItemLength)
    statusItem.button?.target = self
    statusItem.button?.action = #selector(AppDelegate.showContextMenu(_:))
    let options: NSEventMask = [.LeftMouseUpMask, .RightMouseUpMask]
    statusItem.button?.sendActionOn(Int(options.rawValue))
    return statusItem
}()

At a glance - nothing special here. But note how target-action pattern is implemented. Instead of associating some selector with single type of event, like in iOS, we need to provide a bit-mask (options set) for events and the same selector will be called for any event from this set. Left-clicks will work even if you set up only target and action. But if you want to handle other types of interactions you need to provide some events mask.

On right-click I want to show a single-item menu with only one option to close the app. Here is a menu for that:

lazy var statusMenu: NSMenu = {
    let rightClickMenu = NSMenu()
    rightClickMenu.addItem(NSMenuItem(title: "Close", action: #selector(AppDelegate.closeApp), keyEquivalent: ""))
    return rightClickMenu
}()

On left-click I want to show a popover from the status bar item. Here is how you create a popover in OS X:

lazy var popover: NSPopover! = {
    let popover = NSPopover()
    popover.contentViewController = self.calendar
    popover.appearance = NSAppearance(named: NSAppearanceNameAqua)
    popover.animates = true
    popover.behavior = .Transient
    return popover
}()

Nothing special except weird NSAppearanceNameAqua. Without that colors in popover are "a bit" different.

Then to actually show popover or context menu on right/left-click here is a handler method:

func showContextMenu(sender: NSStatusBarButton) {
    switch NSApp.currentEvent!.type {
    case .RightMouseUp:
            statusItem.popUpStatusItemMenu(statusMenu)
    default:
        popover.showRelativeToRect(sender.bounds, ofView: sender, preferredEdge: NSRectEdge.MaxY)
    }
}

Another difference in UI events handling on OS X. Action handlers can not receive event as a second parameter. Instead we ask NSApp for current event (last received event). Then I simply switch over type of event and either show a menu or a popover.

And that is it! The rest was setting up and tweaking calendar. Here is the result - https://github.com/ilyapuchka/HFWeekApp

I don't know if there is any plan for Cocoa in Apple. But without it we can end up in the world where each desktop app is an Electron app...

Intermediate action segues

Sun, 27 Dec 2015 19:54:38 GMT

TL;DR - You can play with source code and example project here.

Storyboards segues are very cool. They are very easy yet powerful. They help to incapsulate presentation logic and move it out from view controllers. And adaptive segues are state of the art. There is only one thing (almost) left if view controller - managing segue performance using those two commonly used methods:

func shouldPerformSegueWithIdentifier(identifier: String, sender: AnyObject?) -> Bool
func prepareForSegue(segue: UIStoryboardSegue, sender: AnyObject?)

And those methods are the place where we usually screw up everything with our custom logic based on tons of if or switch statements. Then we introduce different routers, coordinators and God knows what else (though they are all nice and interesting concepts), forgetting that we can just subclass a segue and do it not only to pass data around.

There is very common use case. You want to present some view only if user has been authorized in your application. If not then you what to show login form. Or register form with subsequent Terms of Use that user has to agree to in order to use your service. It is already a whole storyboard to be displayed in between.

You can do that with several ifs if you have it in one place. But what if you have few places in your app where you need to authorize user before doing something?

Lets see how we can do that with custom segue. I will call this segue an IntermediateActionSegue.

Here are our design goals:

segue should know nothing about current application context and application (view controllers) should know as little as possible about their presentation context (for instance that they were presented as intermediate controllers)
segue should support different kinds of presentation style like modal, fullscreen, popover and custom
segue should be adaptive
there should be a way to present single view controller or a storyboard as intermediate action
segue API should look like UIKit API, meaning that client code should be able to change presentation using delegate callbacks

Actually implementation of such segue is straight forward. All we need to do is to ask some delegate, custom object (that can be your lovely router, coordinator or what ever else) or simply segue's sourceViewController, to provide us with intermediate view controller, that we need to present instead of destinationViewController, and with its presentation style. For that we will use a protocol:

public protocol IntermediateActionPresentationDelegate: class {
    
    func intermediateViewControllerForSegue(segue: UIStoryboardSegue) -> UIViewController?
    
    func intermediateViewControllerPresentationStyleForSegue(segue: UIStoryboardSegue) -> IntermediateActionSeguePresentationStyle
    
    func willPresentIntermediateViewController(segue: UIStoryboardSegue, intermediateViewController: UIViewController)

    func intermediateViewControllerCompleted(intermediateViewController: UIViewController, success: Bool, completionData: AnyObject?) -> Bool

}

When that intermediate view controller completes its task we let the segue that presented it to know about that and depending on the result, success or failure, segue will complete itself dismissing intermediate view controllers and presenting destinationViewController or abort. For that we need to keep a reference to segue in a view controller. We can use associated object to add this property to any view controller in extension:

extension UIViewController {

    private struct AssociatedKeys {
        static var segueKey = 0
    }
    
    public private(set) final var intermediateActionSegue: IntermediateActionSegue? {
        get {
            return objc_getAssociatedObject(self, &AssociatedKeys.segueKey) as? IntermediateActionSegue ?? storyboard?.intermediateActionSegue
        }
        set {
            objc_setAssociatedObject(self, &AssociatedKeys.segueKey, newValue, objc_AssociationPolicy.OBJC_ASSOCIATION_RETAIN_NONATOMIC)
        }
    }

}

Note that if we want to present intermediate storyboards we kind of loose control of the flow while we are on that storyboard. For instance we can not pass reference to segue that caused this storyboard to appear between view controllers of that storyboard. Technically we can but it will break our first design goal. So we additionally store reference to segue in storyboard when we present "initial" intermediate view controller again using associated object and extension.

The only difficulty is to handle different presentations that could happen along the way. But there are usually only two alternative variants - either intermediate controllers are presented modally or in navigation controller.

Conclusion

Of course that is neither an ideal nor the only one possible solution, there is still a room for improvements here. Using this kind of segue you will still sometimes need to switch on segues identifiers or something else to setup presentation logic or check conditions to display intermediate view controllers. But at least you will have few options here. You can use either extension of view controller or separate delegate object to define presentation and business rules. Or you can easily subclass this segue.

What I think is good is that now you can easily use any view controller or even storyboard as intermediate and they don't know almost nothing (except calling completion method on a segues) about how they are used. Your view controllers will communicate with intermediate controllers by well defined interface, separate from handling all other segues. When you move handling those segues in extension or separate object, that will make your view controller a bit cleaner.

You can play with source code and example project here.

Properties of types conforming to protocols in Swift

Fri, 25 Dec 2015 12:21:20 GMT

In Objective-C it's very natural to have a property of type that also conforms to one or few protocols. In Swift that becomes tedious cause you can not simply combine types and protocols.

You can use generics:

class MyClass<T: MyOtherType where T: MyProtocol> {
  var property: T
}

But you will notice soon that this approach has more drawbacks then advantages. First if you need to have another such property it will become a mess. Second is that you can not use this type in Interface Builder anymore, as well as you can not see it from Objective-C environment. Third is that interface always looks more complex if there are generics.

The other way could be to define a protocol that adds some traits of class that you want to extend. Let's say you want to have a UIView property that also conforms to Animatable protocol and you want to access it's animatable trait and view trait. But you don't need to access all of the UIView properties, let's say you need only frame for now. Then you can simply add this property to protocol that extends Animatable protocol, or use protocols composition:

protocol Animatable {
  func startAnimating()
  func stopAnimating()
}

protocol AnimatableView: Animatable {
  var frame: CGRect { get }
}

class ViewController: UIViewController {
  var view: AnimatableView
}

You probably already noticed some problems here too. Every time you will need to access new property of UIView you will need to add it to AnimatableView property. Also you can not pass view property as argument to methods that accept UIView. You can of course force cast it to UIView but pony will be hurt then.

There is much cleaner yet easy solution:

protocol Animatable {
  func startAnimating()
  func stopAnimating()
}

protocol AnyView {
  var view: UIView { get }
}

protocol AnimatableView: AnyView, Animatable {}
//or using protocols composition
typealias AnimatableView = protocol<AnyView, Animatable>

extension UIView: AnyView {
  var view: UIView { return self }
}

Instead of having protocol that exposes some properties of UIView we expose the whole UIView type via property and access it when we need to work with instance as with UIView.

This approach has all advantages of previous one - you can easily access your property by its different traits. But it does not have any of drawbacks of previous solutions. You don't ever need to add any property from UIView class to your protocols if you want to access it. You can use the property in methods that accept UIView simply by passing in its view property. And of course you don't loose Objective-C interoperability and Interface Builder support.

There are different examples of such approach. For instance Alamofire uses URLRequestConvertible protocol:

public protocol URLRequestConvertible {
  var URLRequest: NSMutableURLRequest { get }
}
extension NSURLRequest: URLRequestConvertible {
  public var URLRequest: NSMutableURLRequest { get }
}

Personally I would not use Convertible name for such protocols cause it doest not mean the same as Convertible protocols in Swift standard library where usually they mean that you can create an instance of protocol type from some other type. For instance you can create StringLiteralConvertible instance from String. Or you can create instance of ArrayLiteralConvertible from array literal. But you can not get array literal back from ArrayLiteralConvertible. So it is conversion only in one direction - from external type to self type. But here we need conversion in other direction - from self type to external type.

There are though CustromStringConvertible and ConstomDebugStringConvertible that look more like URLRequestConvertible from Alamofire. But for me they are kind of special and I think I liked original Printable name more.

Personally I would prefer to use names like AnyView or AnyURLRequest or even ViewRepresentable or URLRequestRepresentable. The former is shorter when the latter I think better describes the direction of conversion that happens.

Dependency injection with Dip

Thu, 24 Dec 2015 19:20:38 GMT

Note (15.04.16): This post is updated to reflect some of the latest changes in Dip.

In some of my previous posts I wrote about using dependency injection with Typhoon framework and described some internals of analogous pure-Swift framework called Dip. Here I want to illustrate how Dip can be used in a real project using the same example that I used before. Also this post will contain a sneak peak of some upcoming extensions of Dip (probably they will be released as separate projects). You can check out source code here. Note that it uses my fork of Dip and features described here are not yet released as part of project or any extension.

Dip assemblies

Note: this feature is implemented only in my fork here.

Fundamental components of Typhoon are TyphoonDefinition and TyphoonAssembly. In Dip we have DefinitionOf<T, F>, Assembly and AssemblyDefinitionOf<T, U>. As you could guess assemblies in Dip serve the same goal as in Typhoon - to encapsulate components' factories registration in standalone classes instead of making all registrations in one place. Also they create some kind of hierarchy of assembly classes. In Swift they can not be the same as TyphoonAssembly in terms of that they can not resolve components by themselves. That is still done by container. Assemblies only hold definitions that should be registered in container when assembly is activated in that container. So they are effectively just an alternative syntax for registering components in container. The same you can do with standard Dip syntax.

So how Dip assemblies look like? Here is the same UIComponents assembly I had when I used Typhoon, now written with Dip:

class UIComponents: Assembly {
    
    let authViewController = AssemblyDefinitionOf(tag: "ViewController") { (_, _: Void) in ViewController() }
        .resolveDependencies { (c, vc) -> () in
            vc.animationsFactory = try c.resolve() as AnimationsFactory
    }
    
    let authFormBehaviour = AssemblyDefinitionOf() { (c, _: Void) in
        AuthFormBehaviourImp(apiClient: try c.resolve()) as AuthFormBehaviour
    }
    
    let animationFactory = AssemblyDefinitionOf() { (c, _: Void) in
        c as AnimationsFactory
    }

    let shakeAnimaton = AssemblyDefinitionOf() { (_, view: UIView) in
        ShakeAnimationImp(view: view) as ShakeAnimation
    }
    
    //Collaborating assemblies
    
    let networkComponents = NetworkComponents()

}

AssemblyDefinitionOf<T, U> is a generic type where generic parameter T is a type of component to register and U is type of arguments accepted by factory. It is initialized with optional tag and factory that accepts container and runtime arguments. This factory is stored by assembly definition to create component definition when assembly is activated in container. When that happens using activate(inContainer: DependencyContainer) method of assembly or when container is created with its init(assemblies:configure:) initializer, assembly will iterate over all of its stored properties of type AssemblyDefinitionOf, will create DefinitionOf<T, U throws -> T> from them and will register these definitions in container. So when assembly is activated in some container this container will have all of assembly's definitions registered. You can activate/deactivate assemblies in different containers, there is no relationship between assembly and container.

Notice that there is also a stored property in UIComponents assembly that holds a reference to instance of another assembly - NetworkComponents. In Typhoon it is called "collaborating assembly". When assembly is activated it will also iterate over such properties and activate those assemblies in the same container. Let's look how this NetworkComponents assembly looks like:

class NetworkComponents: Assembly {
    
    let apiClient = AssemblyDefinitionOf() { (_, _: Void) in
        APIClient(baseURL: NSURL(string: "http://localhost:2368")!) as GhostApiClient
    }
    
}

Say no to boxing pure-Swift types to make them visible to Objective-C runtime to use them with Typhoon!

Using assemblies with collaborating assemblies you can register all your definitions with just one line like this:

let container = DependencyContainer(assemblies: [UIComponents()])

Looks neat, don't you think? This will not only activate all definitions from UIComponents assemblies but also from any of its collaborating assemblies. So that in definitions of one assembly you can use container to resolve definitions provided by another assembly. In this particular example we resolve apiClient dependency of view controller's form behavior using definition that comes from another assembly - NetworkComponents.

So you can see that assemblies are really just an alternative syntax to register definitions. It is arguably better, definitely more wordy and complex comparing to standard syntax. For that reasons this feature will be not a part of Dip project, but will be probably released as a separate library. But it makes a nice parallel with Typhoon assemblies so if you ever used Typhoon you may like it.

Storyboards integration

Note: this feature is released as a separate extension - Dip-UI

So we have defined all the dependencies used by our view controller using assemblies, but how we inject them? There are two ways. You can create view controller in code and inject its dependencies manually, for example using constructor injection. You should not pass Dip container in constructor though, cause it will make dependencies of view controller implicit and that is bad. At least use a protocol that abstracts out the fact that passed instance is as DependencyContainer. The other way is to register definition for view controller type in Dip and resolve it using container. But if you use storyboard it will create instance of view controller for you. Then you need to use property injection and here is when storyboards integration and auto-injections come in to play.

There are few things you need to do to use storyboards integration:

you need to set a container to be used by storyboards
in Interface Builder you need to set a dipTag property on the instance where you want to inject dependencies in
you need to make your view controller conform to StoryboardInstantiatable protocol

To set a container to be used by storyboards there is a static property container added to UIStoryboard class. You can set it to your main container or any other container in app delegate. This container should have definitions for types where you want to inject dependencies in. In my case it is ViewController type. So I will just register view controller as usual using its init() initializer - at runtime this factory will be not called anyway because storyboard will already create the instance and container will just pick it up. You can still add resolveDependencies block to define how to resolve dependencies of that type. This block will be called when storyboard creates an instance. You can see the example of such definition in UIComponents assembly:

let authViewController = AssemblyDefinitionOf(tag: "ViewController") { (_, _: Void) in ViewController() }
    .resolveDependencies { (c, vc) -> () in
        vc.animationsFactory = try c.resolve() as AnimationsFactory
}

Note: you don't need to use assemblies to use storyboard integration.

When you set dipTag on the instance in Interface Builder its setter will be called in runtime right after the moment the instance was created. And that is the point when Dip can resolve dependencies of that instance. This tag value will be used to lookup appropriate definition in container. Lookup will fallback to definition for the instance type registered for nil tag, so you don't even need to bother about tag value that you use in Interface Builder when you register definitions in container, you can register them without tags. But you can use different tags to have different definitions for the same type. For example if you use several instances of the same view controller but they require different dependencies you can have two definitions for that view controller type with different resolveDependencies block and different tags.

If Dip was able to find definition for the instance type then it will call its resolveDependencies block. After that it will auto-inject dependencies in this instance. It is the same logic used by resolve method of container.

So you can see that there are two ways you can resolve dependencies for instances created by storyboards. First is using resolveDependencies block. The second is using auto-injection feature. I already described in previous post how this feature works. All you need to do is to wrap your property type with Injected or InjectedWeak wrapper (or your own box type) and register definitions for that type.

The example project uses both of these ways. The manual way, using resolveDependencies block, is used to inject animationsFactory property of ViewController:

class UIComponents: Assembly {

    let authViewController = AssemblyDefinitionOf(tag: "ViewController") { (_, _: Void) in ViewController() }
        .resolveDependencies { (c, vc) -> () in
            vc.animationsFactory = try c.resolve() as AnimationsFactory
    }

    let animationFactory = AssemblyDefinitionOf() { (c, _: Void) in
        c as AnimationsFactory
    }

}

extension DependencyContainer: AnimationsFactory {
    func shakeAnimation(view: UIView) -> ShakeAnimation {
        return try! self.resolve(withArguments: view) as ShakeAnimation
    }
}

protocol AnimationsFactory {
    func shakeAnimation(view: UIView) -> ShakeAnimation
}

Note that the container itself is registered as instance of AnimationsFactory property cause it implements this protocol. The same way you can use a separate class to implement factory protocol but this way is also appropriate (though you can argue that then container violates single responsibility principle).

Auto-injection way is used to inject formBehaviour property of ViewController. Here is how it is defined:

class ViewController: UIViewController {

    private let _formBehaviour = Injected<AuthFormBehaviour>()
    
    var formBehaviour: AuthFormBehaviour? {
        return _formBehaviour.value
    }

}

class UIComponents: Assembly {

    let authFormBehaviour = AssemblyDefinitionOf() { (c, _: Void) in
        AuthFormBehaviourImp(apiClient: try c.resolve()) as AuthFormBehaviour
    }

}

Now I will have all the dependencies of ViewController injected at runtime and I've never called resolve or any other method on container myself. I don't even have a reference to container anywhere except app delegate and assemblies!

The only thing left to do is to wire up all the components in view controller. It does not depend on using Dip or any other form of DI - we already have all the dependencies, we just need to connect them among each other.

Note: Basically it may/should be also done during resolving objects graph, but here we need to deal with root view, that can be not loaded yet. Here it would not be an issue.

It is very straightforward and can be done in viewDidLoad method:

override func viewDidLoad() {
    super.viewDidLoad()
        
    formBehaviour?.onLoggedIn = {[unowned self] in self.handleLogin($0, performedRequest: $1)}
        
    formBehaviour?.userNameInput = authView.userNameInput
    formBehaviour?.userNameInput.delegate = formBehaviour
        
    formBehaviour?.passwordInput = authView.passwordInput
    formBehaviour?.passwordInput.delegate = formBehaviour
        
    authView.loginButton.addTarget(formBehaviour, action: "submitForm", forControlEvents: .TouchUpInside)
        authView.cancelButton.addTarget(formBehaviour, action: "cancelForm", forControlEvents: .TouchUpInside)

    authView.userNameInput.shakeAnimation = animationsFactory?.shakeAnimation(authView.userNameInput)
    authView.passwordInput.shakeAnimation = animationsFactory?.shakeAnimation(authView.passwordInput)
}

The last thing to mention is that how easy you can create container and make it usable by storyboards. The only thing you need is to define it as a stored property of your app delegate like this:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?
    let container = DependencyContainer(assemblies: [UIComponents()]) { c in
        DependencyContainer.uiContainer = c
    }
}

That's basically it. You can see that with auto-injection feature and storyboards integration it's very easy to resolve dependencies no matter where the instance comes from - storyboard or code. And assemblies let you break your definitions in groups of related components.

Of course any convenience comes at a price - you can say that setting container as a static property of UIStoryboard class will make it a service locator, or that assemblies syntax is not that good (you need to specify arguments type and can not reference assembly itself inside factory or resolveDependencies block). And probably you will be right. But that's a thing about such frameworks. They make some task more convenient or automated by adding some cost either in architecture or performance. So it is always a tradeoff between convenience and that additional costs.

In overall I'm very excited about Dip and its upcoming features. You can check out its roadmap here). I can't wait to use it not only in my side project but also in my main work project too.

IoC container in Swift. Circular dependencies and auto-injection

Wed, 11 Nov 2015 18:24:56 GMT

Note (15.04.16): This post is updated to reflect some of the latest changes in Dip.

In my previous post I wrote about Dip, lightweight IoC written in Swift. Here I would like to describe how some other of it's features were implemented. They are not yet available in original repo, but you can check them out in my fork.

Circular dependencies

Let's say we have a server-client model where client has reference to server and server has backward weak reference to it's client. First problem is that we can not have two objects that have reference to each other to be created with constructors like this:

class ClientImp: Client {
    var server: Server
    init(server: Server) { self.server = server }
}
class ServerImp: Server {
    var client: Client
    init(client: Client) { self.client = client }
}
container.register { ServerImp(client: container.resolve()) as Server }
container.register { ClientImp(server: container.resolve()) as Client }

If we try this we will end up in infinite recursion - we will not be able to finish creating instance of server or client and will enter another resolve which will enter another resolve and so forth.

Another problem is that we need to reuse already resolved instances somehow, otherwise we will have infinite recursion again trying to create new instances every time. For that we can simply store resolved instances in a dictionary by the same keys used to get factories to create them. We can abstract that to private class that will also detect when this pool of instances should be drained.

class ResolvedInstances {
    var resolvedInstances = [DefinitionKey: Any]()
    private var depth: Int = 0

    func resolve<T>(@noescape block: () -> T) -> T {
        depth = depth + 1
        
        defer {
            depth = depth - 1
            if depth == 0 {
                resolvedInstances.removeAll()
            }
        }

        let resolved = block()
        return resolved
    }    
}

As you can see when depth of recursion will reach zero (when code returns from outermost resolve call) cache will be cleared. Until then we can get instances from cache and reuse them.

To handle recursion we need to separate creation of object and resolving its dependency for at least one of circular dependencies. Either of Client and Server can still use constructor injection, but another (or both) should use property injection. Here where DefinitionOf class comes back on stage.

func resolveDependencies(block: (DependencyContainer, T) -> ()) -> DefinitionOf<T, F> {
    guard resolveDependenciesBlock == nil else {
        fatalError("You can not change resolveDependencies block after it was set.")
    }
    self.resolveDependenciesBlock = block
    return self
}

var scope: ComponentScope
var factory: F

Here we add few properties to this class - resolveDependenciesBlock and scope. First is a block that will be called by container after factory of this definition is called and just before resolve returns. Scope will define how exactly instances resolved by that definition will be reused - not reused at all, stored as singleton or reused during one call to resolve. The last one is the one that should be used to register circular dependencies. As I mentioned before not reusing instances will cause infinite recursion again. resolvedInstance property will be used only to store singleton instances.

With all that we can finally resolve circular dependencies:

func resolve<T, F>(tag tag: Tag? = nil, builder: F -> T) -> T {
    let key = DefinitionKey(protocolType: T.self, factoryType: F.self, associatedTag: tag)
    guard let definition = self.definitions[key] as? DefinitionOf<T, F> else {
        fatalError("No definition registered with \(key)")
    }

    let usingKey: DefinitionKey? = definition.scope == .ObjectGraph ? key : nil
    return _resolve(usingKey, definition: definition, builder: builder)
}

func _resolve<T, F>(key: DefinitionKey?, definition: DefinitionOf<T, F>, builder: F -> T) -> T {
    return resolvedInstances.resolve {

        if let previouslyResolved: T = resolvedInstances.previouslyResolved(key) {
            return previouslyResolved
        } else {
            let resolvedInstance = builder(definition.factory)
    
            if let previouslyResolved: T = resolvedInstances.previouslyResolved(key) {
                return previouslyResolved
            }
    
            resolvedInstances.storeResolvedInstance(resolvedInstance, forKey: key)
            definition.resolveDependenciesBlock?(self, resolvedInstance)
            return resolvedInstance
        }
    }
}

extension ResolvedInstances {
    func storeResolvedInstance<T>(instance: T, forKey key: DefinitionKey?) {
        self.resolvedInstances[key] = instance
    }
    
    func previouslyResolved<T>(key: DefinitionKey?) -> T? {
        return self.resolvedInstances[key] as? T
    }
}

Here we first check if we need to reuse instances at all. If we need then we use the same definition key to check if there is anything cached. If it's there we return it, otherwise we call builder. After builder is called we first should cache result and then call resolveDependenciesBlock block of definition if there is any. Interesting trick here is that after builder returns we check for instance to reuse again. That's because builder will call factory, that may call another resolve that may produce the same instance that we were trying to resolve originally. So when we return from builder and there is already cached instance we just return it instead of instance that was created by call to builder. Otherwise our circular dependency will be broken - we will have to clients and server, referenced by client will reference to another instance of Client.

Auto injection

We can have situation when we already have an instance of some type (for example created by Storyboard) and we want to fill it's dependencies. Currently we can do it like this:

class ServiceImp: Service {
    var logger: Logger
    var collaboratingService: AnotherService
}

let service = ServiceImp()
service.logger = container.resolve() as Logger
service.collaboratingService = container.resolve() as AnotherService

Or if we get Service instance also from the container can we have all of it's dependencies resolved without adding resolveDependencies, so that instead of this:

container.register { AnotherServiceImp() as AnotherService }
container.register { ServiceImp() as Service }.resolveDependencies { container, service in
    service.logger = container.resolve() as Logger
    service.collaboratingService = container.resolve() as AnotherService
}
let service = container.resolve() as Service

we would do just this:

container.register { AnotherServiceImp() as AnotherService }
container.register { ServiceImp() as Service }

let service = container.resolve() as Service

The last case has much more cleaner syntax. Can we do that?

The idea is simple - using reflection we can get Mirror of the object that will contain all its properties and their values. To be able to change those values we will wrap them in simple class wrappers. This way value will be not copied in the mirror, but will reference the same object. If we will change its wrapped value we will change it not only for mirror, but in real instance too.

final class Injected<T> {
    var _value: T?
    init(value: T?) {
        self._value = value
    }

    var value: T? {
        get {
            return _value as? T
        }
    }
}

Here I define some private protocol just to be able to detect that property is wrapped. And provide very simple generic wrapper that conforms to this protocol. Now I can use it to define property for my dependency:

class ClientImp: Client {
    var server: Injected<Server>
}

container.register { ClientImp() as Client }
container.register { ServerImp() as Server }

let client = container.resolve() as Client

Here I faced the first problem - I need some initial value for server property or I need a constructor, or this property should be defined os optional. Using constructor will mean calling resolve on container manually. Optional will not work either cause nil value can not be checked for type with is operator, it will always return false. So I will not be able to detect that property is wrapped.

The solution is to use instance of Injected<T> that wraps nil value as initial value of property:

final class Injected<T>: _Injected {
    ...
    init() { }
}

class ClientImp: Client {
    var server = Injected<Server>()
}

So good so far. In resolve method before it returns I can call another method that will perform reflection and resolve dependencies of the instance:

class DependencyContainer {
    
    func _resolve<T, F>(key: DefinitionKey?, definition: DefinitionOf<T>, builder: F->T) -> T {
        ...
        definition.resolveDependenciesBlock?(resolvedInstance)
        autoInjectProperties(resolvedInstance)
        return resolvedInstance
    }
    
    func autoInjectProperties(instance: Any) {
        for child in Mirror(reflecting: instance).children {
            ...
        }
    }
}

And here I faced few other problems. First was that I have definition that can resolve only unwrapped type and I can not construct wrapped type in runtime. And another one - how to deal with weak values for circular dependencies. If we use Injected wrapper for circular dependencies we will have retina cycle, cause it holds strong reference to wrapped value.

I could try to work around first problem registering another definition for wrapped type like this:

container.register { ServerImp() as Server }
container.register { Injected(ServerImp()) as Injected<Server> }

But that's just code duplication. And I don't want clients to care about wrapper, I want it to be used only to define properties.

Instead we can ask wrapper to resolve its value. Inside wrapper we know wrapped type at compile time, so we will be able to call container.resolve(). We just need to pass in a container.

To do that we can introduce protocol:

protocol AutoInjectedPropertyBox: class {
    func resolve(container: DependencyContainer)
}

extension Injected: AutoInjectedPropertyBox {
    public func resolve(container: DependencyContainer) {
        let resolved = container.resolve(tag: tag) as T
        value = resolved
    }
}

Now it's trivial to resolve it:

func autoInjectProperties(instance: Any) {
    for child in Mirror(reflecting: instance).children {
        if let injectedPropertyBox = child.value as? AutoInjectedPropertyBox {
            injectedPropertyBox.resolve(self)
        }
    }
}

For weak properties I use the same approach. I introduce another wrapper InjectedWeak that reference wrapped value with weak property:

final class InjectedWeak<T> {
    var _value: AnyObject?
    
    init() {}

    var value: T? {
        get {
            return _value as? T
        }
    }
}

extension InjectedWeak: AutoInjectedPropertyBox {
    func resolve(container: DependencyContainer) {
        let resolved = container.resolve(tag: tag) as T
        if !(resolved is AnyObject) {
            fatalError("\(T.self) can not be casted to AnyObject. InjectedWeak wrapper should be used to wrap only classes.")
        }
        value = resolved
    }
}

And that's it! Now the only thing that you need is to use types wrapped in Injected for you properties and Dip will resolve them for you! You can even make them private and for clients of you classes provided computed property that will unwrap private property. Yes, that sounds like an overhead, but I think it's appropriate for such feature.

I really hope that these two features will make Dip even more useful than it is now.

IoC container in Swift

Sun, 08 Nov 2015 19:45:22 GMT

Note (15.04.16): This post is updated to reflect some of the latest changes in Dip.

In my previous post I talked about dependency injection framework for Objective-C called Typhoon. It's very easy to start to use it, yet it's very powerful (maybe even too much cause there are so much stuff you can do with it). When I first time saw it it was not love at first sight. I though: "Pfff, I don't need all these crazy swizzling and other runtime magic, I can inject everything manually". But actually I didn't and there were lot's of lazy properties and singletons all over my code. Actually I didn't thought about design too much. At the point when we met again I was a bit more experienced and thanks to some of my colleagues started to value clean code and design much more. That helped me to understand the value of this framework and IoC in general. Some people think that it only makes code even more complicated. Yes, if you look at its sample project, fully backed by Typhoon, where they inject everything even app delegate, I will agree that it is probably too much. But believe me, it's still much batter than what you can have without it - giant "directories" of objects holding references literally to every other component of the system and passed to all of them so that they can talk to each other breaking communications patterns of you system in all possible ways, or objects with initializers with ten or more arguments, or tests that mock everything just to create sut (system under test) object or all of this together (based on my personal experience). Introducing IoC is definitely not the first thing you should think of trying to improve your design but such things as Typhoon make your code (at least when you deal with dependencies) much more structured, you simply know where all the things are defined and you no more need to think where something comes from, how it is created or how I replace it with fake implementation in test. You just look at your definitions and see it. And it's really very easy to reed, you don't even need to know how it works to understand what it does. I shared it with my colleagues, showed them how it works and encouraged to use it. And now after about six months when I'm already not in that team any more they not just build all of their applications with it, but also are part of Typhoon core contributors and share their experience with others.

But I'm here not to advocate Typhoon. It's the end of 2015 and there is Swift. Such things as Typhoon rely a lot on Objective-C runtime thus making it hard to use with pure Swift (meaning without @objc and dynamic). And it's just too wordy for Swift. You can use it, but I don't encourage you. You can try to use Objective-C for it what will be probably a better idea but then you will need to deal with languages interoperability.

So is there a way to do the same (well there are just too much stuff there in Typhoon so I mean only core IoC container functionality) in Swift way or are we doomed to stick to Objective-C?

Good news - there is such way. And actually it's pretty easy and elegant. Take a look at Dip project. It's rather basic for now but there is a huge space for improvements. I'm very excited about it and started to contribute to it recently so there are few cool features coming up, like circular dependencies and automatic property injection - they are already available in my fork.

Here is how it looks like. I will use very basic examples not to disturb you with unneeded details.

Let's say you have some protocol with different implementations:

protocol Service() {...}
class ServiceImp: Service {...}
class FakeService: Service {...}

In production code you can use real implementation:

container.register { ServiceImp() as Service }
let service = container.resolve() as Service // -> ServiceImp

And in your tests you use another implementation:

container.register { FakeService() as Service }
let service = container.resolve() as Service // -> FakeService

So the only difference is what implementations you register in runtime. You source code does not change because it does not care about concrete implementations, it only needs reference to container.

Do you fill it?

container.register { ServiceImp() as Service }
container.resolve() as Service

Remove dots, curly and round brackets:

container register ServiceImp as Service 
container resolve as Service

It's simple and beautiful. As you might guess already the first line registers factory (closure or method) to create instances of Service protocol and the second line creates this instance.

Everything else can be built on top of that. Need runtime arguments? Easy:

container.register { url, port in ServiceImp(url, port: port) as Service }
let service = container.resolve(url, 80) as Service

Circular dependencies? Well, not so easy but possible:

protocol Server: class {
    var client: Client? { get set }
}

class ServerImp: Server {
    weak var client: Client?
    init() {}
}

protocol Client: class {
    var server: Server { get }
}

class ClientImp: Client {
    var server: Server
    init(server: Server) {
        self.server = server
    }
}

container.register(.ObjectGraph) {
    ClientImp(server: container.resolve()) as Client }

container.register(.ObjectGraph) { ServerImp() as Server }
    .resolveDependencies { container, server in
        server.client = container.resolve() as Client
}

let client = container.resolve() as Client // -> ClientImp
let server = client.server // -> ServerImp

That was a bit complex but can be improved with auto-injection:

protocol Service {
    var client: Client {get}
}

protocol Client: class {
    var service: Service {get}
}

class ServiceImp: Service {
    var _client = InjectedWeak<Client>()

    var client: Client {
        return _client.value!
    }
}

class ClientImp: Client {
    var _service = Injected<Service>()
    
    var service: Service {
        return _service.value!
    }
}

container.register(.ObjectGraph) { ServiceImp() as Service }
container.register(.ObjectGraph) { ClientImp() as Client }

let client = container.resolve() as Client // -> ClientImp
let service = client.service // -> ServerImp

Small wrappers and computed properties for convenience and we are back to simple syntax.

How it works

So what's the magic? The fundamental blocks of Dip are generics. They play very nice here and let to use very clean and Swifty syntax. Let's look at register method first. I will use simpler and slightly modified original implementation to demonstrate basic idea.

func register<T>(tag tag: Tag? = nil, factory: ()->T) -> DefinitionOf<T> {
    let key = Key(protocolType: T.self, associatedTag: tag)
    dependencies[key] = factory
}

var dependencies = [Key : ()->Any]()

struct Key : Hashable, Equatable {
    var protocolType: Any.Type
    var associatedTag: Tag?
    
    var hashValue: Int {
        return "\(protocolType)-\(associatedTag)".hashValue
    }
}

func ==(lhs: Key, rhs: Key) -> Bool {
    return lhs.protocolType == rhs.protocolType && lhs.associatedTag == rhs.associatedTag
}

Here we simply store passed in factory by key that is created with generic type and tag (tags don't matter here but I will use them later in auto-injection). To resolve we create the same key, get the factory and call it:

func resolve<T>(tag: Tag? = nil) -> T {
    let key = Key(protocolType: T.self, associatedTag: tag)
    guard let factory = self.dependencies[key] else {
        fatalError("No instance factory registered with \(key)") 
    }
    return factory(tag) as! T
}

The magic is how generics and as operator work here together. If you don't use as:

container.register { ServiceImp() }

then T.self == ServiceImp. But if you use it:

container.register { ServiceImp() as Service }

then T.self == Service! With as you upcast concrete class ServiceImp to protocol Service and method now does not know that you pass it ServiceImp, it only knows that it is Service, so type T will be Service. Now if we use the same trick with as in resolve it will create the same key and find exactly the same factory that we registered for that type. When we store factories we store them as methods that return Any type, but generic type in register and resolve together with key based on it make sure that instance that is returned by factory has the same type (or is its derivative) as type T so downcast from Any to T is absolutely safe. And that's all the "magic". Now it can be improved to allow other features.

Runtime arguments

For example what if we need to provide some runtime arguments to our factories when we resolve types? A bit more of generics and it's possible. First we need to distinguish factories that accept different runtime arguments. For that we add type of factory to the lookup key:

struct DefinitionKey : Hashable, Equatable {
    var protocolType: Any.Type
    var factoryType: Any.Type
    var associatedTag: DependencyContainer.Tag?
    
    var hashValue: Int {
        return "\(protocolType)-\(factoryType)-\(associatedTag)".hashValue
    }
}

func ==(lhs: DefinitionKey, rhs: DefinitionKey) -> Bool {
    return lhs.protocolType == rhs.protocolType && lhs.factoryType == rhs.factoryType && lhs.associatedTag == rhs.associatedTag
}

To have more flexibility container will store not just factories, but definitions, generic class that for now will only hold reference to factory which now will be of type Any - we don't care here what it is (and we just don't know), we only need to store it.

protocol Definition {}

final class DefinitionOf<T>: Definition {
    let factory: Any
    let scope: ComponentScope

    init(factory: Any, scope: ComponentScope) {
        self.factory = factory
        self.scope = scope
    }
}

In register method to get access to type of passed in factory we will use generic again:

func register<T>(tag tag: Tag? = nil, scope: ComponentScope = .Prototype, factory: () -> T) -> DefinitionOf<T> {
    return register(tag: tag, factory: factory, scope: .Prototype)
}

func registerFactory<T, F>(tag tag: Tag? = nil, scope: ComponentScope, factory: F, scope: ComponentScope) -> DefinitionOf<T> {
    let key = DefinitionKey(protocolType: T.self, factoryType: F.self, associatedTag: tag)
    let definition = DefinitionOf<T, F>(factory: factory, scope: scope)
    dependencies[key] = definition
    return definition
}

We added another register method that does not care about actual type of factory, it can be anything (in practice it will be different kinds of closures), it only needs to use this type to create a key. Now we can use this second register method in method that registers factory with one runtime argument:

func register<T, Arg1>(tag tag: Tag? = nil, scope: ComponentScope = .Prototype, factory: (Arg1) -> T) -> DefinitionOf<T> {
    return register(tag: tag, factory: factory, scope: scope)
}

Here we use generic again, this time for type of runtime argument. In this method type F will be Arg1 -> T. Let's remember that.

That was one part of the problem, we can now register factory with one runtime argument or with no arguments, but how we resolve it? And if we have two different factories whit argument and with no argument registered for the same type how we choose between them? Here generics help us again.

func resolve<T>(tag tag: Tag? = nil) -> T {
    return _resolve(tag: tag) { (factory: () -> T) in factory() }
}

func _resolve<T, F>(tag tag: Tag? = nil, builder: F -> T) -> T {
    let key = DefinitionKey(protocolType: T.self, factoryType: F.self, associatedTag: tag)
    guard let definition = self.dependencies[key] as? DefinitionOf<T> else {
        fatalError()
    }
    return builder(definition.factory as! F)
}

The same way we introduced register method with generic type F for factory we add resolve method with type F that stands for the same type. But instead of passing actual factory to this method we pass it a builder closure that accepts factory and returns instance that it creates, which is of type T. To build a key we use factory type F, get stored definition and pass factory that it holds to builder closure. Generic type F and key based on it make sure that type of factory stored in definition is actually F, so downcast is safe. The keys is also based on type of T, so we a sure that F is a closure that returns T. But where we get builder from? We make it ourselves in the outer resolve method - in this case it's a closure that accepts factory and returns it's value. The same way we can add resolve method that accepts runtime argument and pass it to factory:

func resolve<T, Arg1>(tag tag: Tag? = nil, withArguments: Arg1) -> T {
    return resolve(tag: tag) { (factory: (Arg1) -> T) in factory(arg1) }
}

Here we know that factory that we want to use should accept one argument, so we set it's type to Arg1 -> T. Builder type will be Arg1 -> T -> T and F will be Arg1 -> T. That's exactly the same type that we used in register, of course if Arg1 used here and Arg1 used there are the same. So the key built with this type F will give us factory that accepts argument of type Arg1.

Now we can add methods for as many arguments as we want. Use of generic type F for factory type lets us capture factory signature that contains all of its arguments and return type. So for the same type we can register different factories that accepts different types of parameters. Which factory will be used depends on what parameters we pass to resolve and - what is also important - in what order.

Conclusion

I wanted to describe how I implemented circular dependencies and auto-injection but this post becomes too long already so I will leave it for the next time. Even without these features Dip is rather useful, can cover a lot of cases and can help in tests and loose coupling. Yet it's very simple. Probably what I like most about it is that how as operator works. It will be very easy to build new functionality on top of what we have now, providing features for UI components and Storyboards like Typhoon does but preserving it's swiftness and simplicity. When that will be done I hope there will be no more need for Typhoon in Swift code.

View controller thinning. Dependency injection with Typhoon.

Tue, 27 Oct 2015 11:56:27 GMT

In my previous post I described how you can break business and presentation logic in small PONSO's to achieve better separation of concerns and think view controller. To wire up dependencies, particularly those PONSO instances with view elements and actions I heavily used Interface Builder. In this post I will show how you can do the same using IoC-container instead of Interface Builder. As example of such IoC container implementation I will use Typhoon framework. To checkout the full code you can use this repo.

First lets start with defining what IoC-container ("Inversion-Of-Control-Container") is. I will not dive deep in theory of Inversion Of Control principle, you better read about that somewhere else. IoC-container serves to simplify and automate the process of defining and resolving dependencies between software system components. Basically what IoC-container does is that it provides some API to register components and to resolve them later. Sometimes it can even resolve them for you so you don't even need to call any method to create an instance of your component. Imagine that you have component that depends on lot's of other components:

let apiClient = ApiClient(hostProvider: ApiHostProvider(), requestFactory: ApiRequestFactory(), requestSerializer: ApiRequestSerializer(), responseSerializer: ApiResponseSerializer(), cookiesStorage: CookiesStorage(), logger: ApiLogger())

With IoC-container you can use something like this:

let apiClient: ApiClient = networkComponents.resolve()

You can easily use Dependency Injection pattern without any containers in relatively small systems but when number of components in your system grows so the number of dependencies grows and at some point you will end up with a lot of code that just wires things together. This setup logic can be scattered over you code. Instead you should aim to concentrate setup in one point. Basically it would be the earliest entry point of you program. Speaking of iOS app you can think of your app delegate. This is not perfect solution though. In large system you will have app delegate bloated with setup of different components. Also sometimes it's not possible or not efficient to define all dependencies at startup. You may need to decide what components to use at runtime depending on the state of your system or user input. This is when IoC-container will be very handy.

So let's look at Typhoon, so far the best IoC-container for Cocoa.

Typhoon

The way you use it is that you define assemblies that provide definitions for your system components. Definitions define the type of component they describe and how it will be created at runtime - what initializer will be used, what properties will be injected during resolution process and what methods will be called. You can think of assemblies as classes that provide factory methods for your components. But instead of manually creating components that factory methods return definitions for this components that Typhoon use later to create real components. What makes Typhoon even better is that you can seamlessly integrate it step by step in your application. You don't have to make you system Typhoon-centric and strongly depend on it. Also it works great with storyboards so it's very easy to start inject things. In runtime Typhoon will detect types of view controllers and inject their dependencies if you provide appropriate definitions.

Let's go back to our project and see how Typhoon can be used in practice. My view controller with login form have few dependencies, currently injected with Interface Builder. So I need to provide definition to instruct Typhoon what it should inject in this controller. To do that I define subclass of TyphoonAssembly and provide definition for ViewController class:

class UIComponents: TyphoonAssembly {
    dynamic func authViewController() -> AnyObject {
        return TyphoonDefinition.withClass(ViewController.self) { def in
            def.injectProperty("nibName", with: "AuthView")
        }
    }
}

Here I create method that returns TyphoonDefinition for ViewController class. From now on every time Typhoon stumble on ViewController in storyboard it will use this definition to setup this controller. Here setup is very simple, I just say that Typhoon should inject property nibName and set its value to AuthView. This way view controller will be loaded with root view from xib with this name. No I don't need to override this property in view controller.

Next I will add definition for form behavior:

dynamic func authViewController() -> AnyObject {
    return TyphoonDefinition.withClass(ViewController.self) { def in
        ...
        def.injectProperty("formBehaviour")
    }
}

dynamic func authFormBehaviour() -> AnyObject {
    return TyphoonDefinition.withClass(AuthFormBehaviour.self) {def in
        def.useInitializer("initWithAPIClient:") { method in
            ...
        }
    }
}

Here I say that to create form behavior instance I want Typhoon to use its initWithAPIClient: initializer. I will get back to that definition in a minute to explain details.

Next I can define animations:

dynamic func shakeAnimaton(view: UIView) -> AnyObject {
    return TyphoonDefinition.withClass(ShakeAnimationImp.self) { def in
        def.injectProperty("view", with: view)
    }
}

Here I use another feature of Typhoon - runtime arguments. When animation object will be created its view property will be set to the view passed to this definition as argument.

But wait, view controller does not have references to animation objects, instead input fields, subviews of its root view store them. So how I can set them? I don't have access to view controller or its view in definition, there is simply no object created yet when we define definition. The way it can be solved is that Typhoon can call arbitrary methods (injection callbacks) on created object before returning it. The drawback of this method is that I will have to access view property in this method what will load view earlier. Usually it's not a problem cause in most cases view is loaded shortly after view controller is created. But if it does not work well than you can inject assembly itself to view controller and access its definition to resolve animations in viewDidLoad.

dynamic func authViewController() -> AnyObject {
    return TyphoonDefinition.withClass(ViewController.self) { def in
        ...
        def.performAfterInjections("typhoonDidInject:") { method in
            method.injectParameterWith(self)
        }
    }
}

extension ViewController {

    func typhoonDidInject(uiComponents: UIComponents) {
        authView.userNameInput.shakeAnimation = uiComponents.shakeAnimaton(authView.userNameInput) as! ShakeAnimationImp
        authView.passwordInput.shakeAnimation = uiComponents.shakeAnimaton(authView.passwordInput) as! ShakeAnimationImp
    }
}

Here I define that as a last step of resolve process Typhoon should call typhoonDidInject: method of view controller with assembly as it's argument. Using this assembly I can access shakeAnimtion definition and resolve it.

In the same method I can finish wiring by connecting form behavior input fields to auth view subviews and adding actions to buttons:

func typhoonDidInject(uiComponents: UIComponents) {
    formBehaviour?.userNameInput = authView.userNameInput
    formBehaviour?.passwordInput = authView.passwordInput
    authView.loginButton.addTarget(formBehaviour, action: "submitForm", forControlEvents: .TouchUpInside)
    authView.cancelButton.addTarget(formBehaviour, action: "cancelForm", forControlEvents: .TouchUpInside)
    
    ...
}

Now it's time to go back to definition of network components.
First of all I want to separate UI components assembly from network components assembly. But then to inject api client to form behavior I will need to somehow reference to network components assembly in UI components assembly so that I can do something like this:

def.useInitializer("initWithAPIClient:") { method in
    method.injectParameterWith(self.networkComponents.apiClient())
}

For that there is a mechanism in Typhoon called collaborating assemblies. To use it I can define a property of another assembly on UI components assembly.

private(set) var networkComponents: NetworkComponents!

When Typhoon will initialize UI components assembly it will inspect its properties and search for those that are subclasses of TyphoonAssembly. When it finds one it will search for assembly that it can inject in this property. So now I need to define assembly for network components:

class NetworkComponents: TyphoonAssembly {
    
    dynamic func apiClient() -> AnyObject {
        return TyphoonDefinition.withClass(APIClientBox.self) { (def: TyphoonDefinition!) in
            def.useInitializer("init:") { (initializer: TyphoonMethod!) in
                initializer.injectParameterWith(NetworkComponents.apiClientInstance)
            }
        }
    }
    
    private static let apiClientInstance: APIClient = {
        let host = "http://localhost:2368"
        let client = APIClient(baseURL: NSURL(string: host)!)
        return client
    }()
    
}

Now my two assemblies will be connected and UI components assembly will be able to use definitions from network components assembly in it's own definitions.

The other interesting thing here is that Typhoon can not inject Swift-native classes. So I wrap APIClient in simple PONSO wrapper and inject it instead.

public class APIClientBox: NSObject {
    let unboxed: APIClient
    dynamic init(_ boxed: AnyObject) {
        unboxed = boxed as! APIClient
    }
}

The last thing left to do is to tell Typhoon what assemblies it should activate at startup. There are different ways to provide initial assemblies - manual, using plist and using app delegate.
To do it with app delegate I just need to implement initialAssemblies() method and return classes of assemblies that should be activated. Then Typhoon will activate them at the earliest point. After activation assembly will no longer return definitions from its methods, instead it will return resolved instances.

extension AppDelegate {
    func initialAssemblies() -> [AnyClass] {
        return [NetworkComponents.self, UIComponents.self]
    }
}

Conclusion

Typhoon is very powerful framework for DI. You can build very complex systems with complex graphs of dependencies and they all will be described using uniform and easy to read API. But Typhoon was originally designed for Objective-C and uses it's runtime features heavily. Thanks to languages interoperability it still works in Swift with some restrictions and requirements. In some cases I think it's even better to use Objective-C to define assemblies. For native Swift code it's rather easy to create basic IoC but supporting all of the features available in Objective-C looks impossible.
Comparing with Interface Builder Typhoon requires more code of course, but it provides well defined point of setup, separated from the rest of the system, it provides uniform API to describe dependencies and it's just easier to follow code than expecting connections in Interface Builder. But no matter what approach you prefer I hope by this moment you share the with me understanding of actually very simple fact that proper dependency management, SRP and other principles are very important.

View controller thinning. Behaviors and Interface Builder.

Sat, 10 Oct 2015 15:13:18 GMT

In previous post I showed how you can move some presentation logic from view controller to view. Now view controller is responsible only for business logic, in this case making login request and handling its result. But now you would say: "You just moved presentation logic from controller to view. Now you have Massive View!" And you will be right. Though view is a perfect place for presentation logic that leads to that view should know everything about its subviews and it will probably change when we change something in its subviews. So in this post I will show how to make view a little bit less aware of its subviews details and how to isolate business logic from everything else. You can follow commits history in this repo.

Behaviors

And this brings us to the concept of behaviors. What makes difference between values and objects is that values are inert but objects behave. They do something and change when you tell them. If what your object does is just some calculations than it's probably better to be a value. If your value needs to perform some action apart from manipulation with its data than it's probably better to be an object. But does the behavior need to be defined in object itself? It is now. AuthView now defines how its subviews should behave when user taps on them or when the user input is invalid. In most cases it will be fine and acceptable. But if because of that your view becomes to complex then it's probably time to refactor and to let the behaviors a green light.

First I will define what are those behaviours in case of AuthView. The most obvious one is highlighting behavior. When user taps on a button or when it changes input context from one text field to another these views change there background color. Cool, what's next? When user press login button and his input is invalid text fields should "shake". That's also a behavior - in response to user input I add some animation to views. The last behavior is form behavior. It defines what should happen when on for example pressing "Return" button on keyboard, should user move from one field to another or it will just hide the keyboard, in what order this move should happen, on what button the form is submitted or discarded.

Highlight behavior

For this behavior I need to provide few things - background color for normal state, background color for highlighted state, setter for background color and setter for highlighted state. UITextField and UIButton already has properties like background color and highlighted. What's missing is ability to set background colors for different highlight state. First I will define protocol BackgroundHighlightableView that will provide interface required for this behavior.

protocol BackgroundHighlightableView: class {
    var backgroundColor: UIColor? {get set}
    var backgroundColorForHighlightedState: UIColor? {get}
    var backgroundColorForNormalState: UIColor? {get}
    
    var highlighted: Bool {get set}
    func setHighlighted(highlighted: Bool, animated: Bool)
    func backgroundColor(highlighted: Bool) -> UIColor?
}

Here I define only getters for backgroundColorForHighlightedState and backgroundColorForNormalState cause I'm not gonna use this protocol to change this properties, but in concrete implementation I will provide those setters.

Next I will define extension for this protocol when it's applied to UIView (it make less sense to apply it on anything else but we can not restrict protocol to be applied on specific types) that will provide default implementation of protocol's methods.

extension BackgroundHighlightableView where Self: UIView {
    
    func setHighlighted(highlighted: Bool, animated: Bool) {
        let view = self as UIView
        guard backgroundColorForHighlightedState != nil &&
            view.backgroundColor != nil else {
                return
        }
        changeAnimated(true, options: [.BeginFromCurrentState]) {
            view.backgroundColor = self.backgroundColor(highlighted)
        }
    }
    
    func backgroundColor(highlighted: Bool) -> UIColor? {
        return highlighted ? backgroundColorForHighlightedState : backgroundColorForNormalState
    }
    
}

Note that I had to use let view = self as UIView (or I could use let view = self as BackgroundHighlightableView). I need it cause protocol and UIView both define backgroundColor property and for Swift referencing it with self will be ambiguous.

Now I can use this protocol to create subclass of UIButton that will conform to it.

class HighlightableButton: UIButton, BackgroundHighlightableView {
    
    @IBInspectable
    var backgroundColorForHighlightedState: UIColor?
    
    var backgroundColorForNormalState: UIColor?
    
    override var backgroundColor: UIColor? {
        didSet {
            backgroundColorForNormalState = backgroundColorForNormalState ?? backgroundColor
        }
    }
    
    override var highlighted: Bool {
        willSet {
            setHighlighted(newValue, animated: true)
        }
    }
    
}

For text filed I already have a subclass - FormTextField, so I can extend it and add conformance to BackgroundHighlightableView:

extension FormTextField: BackgroundHighlightableView {
    
    var backgroundColorForHighlightedState: UIColor? {
        get {
            return self.theme.highlightedBackgroundColor
        }
    }
    
    var backgroundColorForNormalState: UIColor? {
        get {
            return self.theme.backgroundColor
        }
    }
    
    override var highlighted: Bool {
        willSet {
            setHighlighted(newValue, animated: true)
        }
    }
    
    override func resignFirstResponder() -> Bool {
        let resignedFirstResponder = super.resignFirstResponder()
        highlighted = !resignedFirstResponder
        return resignedFirstResponder
    }
    
    override func becomeFirstResponder() -> Bool {
        let becameFirstResponder = super.becomeFirstResponder()
        highlighted = becameFirstResponder
        return becameFirstResponder
    }

}

You can see the difference. In HighlightableButton I used IBInspectable property to set backgroundColorForHighlightedState. Here I use theme to provide background colors for different states.

Animations

To define animation I need its duration, view to apply it on and method to apply it.

@objc
protocol Animation {
    var duration: Double {get}
    var view: UIView? {get}
}

extension Animation {
    func play() {
        fatalError("Concrete instances of Animation protocol should provide implementation of this method.")
    }
}

Here I mark Animation protocol as @objc so that later I can use concrete implementation of this protocol as IBOutlet. If I would use it only in code it's not required. But since I mark the whole protocol with @objc each method will be implicitly marked with @objc. Then I will not be able to define default implementation for play() method in protocol extension (what I will do in a minute), because it's not supported yet. That's why I removed play() method from protocol declaration to its extension and defined implementation with assertion. I will override it anyway.

Next I will define more concrete protocol that will describe "shake" animation.

@objc
protocol ShakeAnimation: Animation {
    var maxOffset: Double {get set}
    var keyPath: String {get set}
}

extension ShakeAnimation {
    func play() {
        guard let view = view else { return }
        
        let animation = CAKeyframeAnimation(keyPath: keyPath)
        animation.values = [0, maxOffset, -0.8 * maxOffset, 0.4 * maxOffset, 0]
        animation.keyTimes = [0, (1 / 6.0), (3 / 6.0), (5 / 6.0), 1]
        animation.duration = duration ?? view.implicitAnimationDuration
        animation.additive = true
        view.layer.addAnimation(animation, forKey: "shake")
    }
}

It's again marked with @objc to be used in Interface Builder. Here I define a keyPath that will be animated. I don't care if it is "position.x" or "position.y" or even "transform.rotation.z", I let clients of this protocol to define that. And I provide default implementation of "shake" animation which is pretty straight forward.

Now I need concrete implementation of ShakeAnimation protocol. I already have default implementation of play() function, so I need only to define properties and their default values.

class ShakeAnimationImp: NSObject, ShakeAnimation {
    
    @IBInspectable
    var duration: Double = 0.2
    
    @IBInspectable
    var maxOffset: Double = 10
    
    @IBInspectable
    var keyPath: String = "position.x"
    
    @IBOutlet
    weak var view: UIView?
    
}

Now I need to hook it up with view. To do that I will use Interface Builder. I need just to drag two objects of ShakeAnimationImp in AuthView xib and connect their view outlets with each of text fields. In FormTextField itself I need to have reference to animation object to call its play() method when I need to, so I will just add outlet for that property and will connect it with animation objects. I will add invalidInput property to FormTextField to incapsulate this behavior in view itself.

@IBOutlet
var shakeAnimation: ShakeAnimation?

var invalidInput: Bool = false {
    didSet {
        rightViewMode = invalidInput ? .Always : .Never
        if invalidInput {
            shakeAnimation?.play()
        }
    }
}

Now view controller only needs to call authView.userNameInput.invalidInput = true|false to trigger animation and show/hide invalid input indicator.

Form behavior

The last behavior that I will add is form behavior. Each form should have fields, optional current field, method to move user input focus to the next field and methods to submit form or to cancel.

protocol FormBehaviour {
    var formFields: [UIView]! {get}
    func goToNextFormField() -> UIView?
    func currentFormField() -> UIView?
    func submitForm()
    func cancelForm()
}

Note that formFields is defined as explicitly unwrapped optional property and not a function because I want to use it in Interface Builder again and want be able to use IBOutlet collection for this property. If I would use method like formField() -> [UIView] to use this protocol with InterfaceBuilder I would need to define property with some other name (Swift will not let you define property and at the same type function with no arguments, the same return type as property type and the same name as property) and return its value in this method.

It's very likely that each form will have the same logic for moving from one field to another, so here I can use protocol extension again and define default implementation, shared among all kinds of forms. Property for current field can be also implemented in this extension cause only the field which is a first responder can be current.

extension FormBehavior {
    
    func currentFormField() -> UIView? {
        for field in formFields where field.isFirstResponder() {
            return field
        }
        return nil
    }
    
    func goToNextFormField() -> UIView? {
        guard let
            formFields = self.formFields,
            currentField = currentFormField(),
            currentFieldIndex = formFields.indexOf(currentField)
            where
            formFields.count > 1
            else {
                return nil
        }
        
        var nextFormField: UIView! = nil
        var nextIndex = currentFieldIndex
        repeat {
            nextIndex = (nextIndex + 1) % formFields.count
            nextFormField = formFields[nextIndex]
        } while nextFormField.canBecomeFirstResponder() == false && nextIndex != currentFieldIndex
        if nextIndex != currentFieldIndex {
            nextFormField.becomeFirstResponder()
        }
        return nextFormField
    }
    
}

Next I need to define behavior specific to user login form. Here I have two options - to define this behavior as protocol and conform to it in view controller or to define a separate object that conforms to FormBehavior and use composition in view controller by referencing this object in property. First one is very tempting but that will lead me away from initial goal - to remove stuff from view controller. Also it will be harder to test this behavior cause it will require view controller (I still tried that way and you can check out code for this path in this branch). So the latter path looks preferable. It will let me later to test this behavior independently from view controller and I will be able to use Interface Builder to inject it in view controller.

class AuthFormBehaviour: NSObject, FormBehaviour {
    
    var apiClient: APIClient = APIClient(baseURL: NSURL(string: "http://localhost")!)
    
    @IBOutlet
    var userNameInput: UITextField! {
        didSet {
            userNameInput.delegate = self
        }
    }
    
    @IBOutlet
    var passwordInput: UITextField! {
        didSet {
            passwordInput.delegate = self
        }
    }
    
    @IBOutlet
    var formFields: [UIView]!
    
    @IBAction
    func submitForm() {
        guard let
            username = userNameInput.text,
            password = passwordInput.text else {
                return
        }
        userNameInput.endEditing(true)
        passwordInput.endEditing(true)
        login(username, password: password)
    }
    
    var onCancel: (()->())?
    
    @IBAction
    func cancelForm() {
        onCancel?()
    }
    
    var onLoggedIn: ((error: NSError?, performedRequest: Bool) -> ())?

    func login(username: String, password: String) {
        apiClient.login(username, password: password) { [weak self] (error, performedRequest) -> () in
            self?.onLoggedIn?(error: error, performedRequest: performedRequest)
        }
    }
    
}

extension AuthFormBehaviour: UITextFieldDelegate {
    
    func textFieldShouldReturn(textField: UITextField) -> Bool {
        if textField == formFields.last {
            submitForm()
        }
        else {
            goToNextFormField()
        }
        return true
    }
}

Everything is very straight forward here. I define that when form is submitted login request is performed and when it finishes I call onLoggedIn handler.

Now I can add this object in AuthView xib, connect its outlets and actions. Only thing that I need to add in view controller is a property to hold this behavior and set up its onLoggedIn handler.

@IBOutlet
var formBehavior: AuthFormBehavior! {
    didSet {
        formBehavior?.onLoggedIn = {[unowned self] in self.handleLogin($0, performedRequest: $1)}
    }
}

Clean up

The code looks much more cleaner already. To clean up view controller completely I will refactor error handling.
The only thing that view controller should do when login completes is to display error message if there was error and say to input fields that they have invalid input. It should not inspect error for that. Instead I can provide extension of NSError with methods that will determine what kind of error I have.

extension NSError {
    
    var underlyingError: NSError? {
        return userInfo[NSUnderlyingErrorKey] as? NSError
    }
    
    var userReadableMessage: String? {
        return userInfo[NSLocalizedDescriptionKey] as? String ?? NSLocalizedString("Something went wrong.", comment: "")
    }
    
    var alertMessage: String? {
        return userReadableMessage
    }
    
    func isInvalidUserNameError() -> Bool {
        return domain == NetworkErrorDomain && underlyingError?.code == NetworkErrorCode.InvalidUserName.rawValue
    }
    
    func isInvalidPasswordError() -> Bool {
        return domain == NetworkErrorDomain && underlyingError?.code == NetworkErrorCode.InvalidPassword.rawValue
    }
}

extension UIViewController {
    
    func displayError(error: NSError) {
        let alert = UIAlertController(title: NSLocalizedString("Error", comment: ""), message: error.alertMessage, preferredStyle: UIAlertControllerStyle.Alert)
        alert.addAction(UIAlertAction(title: NSLocalizedString("Close", comment: ""), style: UIAlertActionStyle.Cancel, handler: nil))
        presentViewController(alert, animated: true, completion: nil)
    }
    
}

Here I also define extension for UIViewController with method to display basic alert.

Conclusion

As you can see the original code changed a lot by this point. You could say that now there is much more code to support (and test). Yes, but as for me this code makes more sense, it's easy to follow though it's modular, it's testable, and what's more important, business logic is separated from everything else. I also heavily used Interface Builder to connect different components with each other. I could achieve the same result with code (and in next post I will show how) what has some advantages but with option to use Interface Builder, like it or not, we have more flexibility in how we implement things.

View themes

Sat, 03 Oct 2015 15:23:35 GMT

In my previous post you could see that I've used ColorTheme and ThemedView protocol to easily customize view appearance. Though that solution works I was not satisfied with it from very beginning. Here I try to find another solution.

What I really didn't like about my that solution was a check of tag type (if let tag = tag as? FormTextField.ThemeColorTag). Usually I try to avoid any kind of type checking. But here I have nothing to do but to check the type of tag.

The problem is that I tried to define some base protocol for color them. That led to the fact that any theme can be applied to any view. What will make more sense is that if I can have different kinds of themes for different kinds of views so that let's say UITextField can not be styled with theme for UIButton. Also it would be nice to extend UIKit views with default behavior of applying theme.

I could try solve that by adding type alias to ColorTheme to define type of tags that it can accept. But that would led to adding generic constraints to any subclass of UIView that should use theme (which will mean that I can't use them with outlets) and will also prevent to apply themes to standard UIKit components.

In the app I have custom UITextField subclass. So I need to define theme for UITextField. I want to be able to use different kind's of themes and I want them to be value types (cause at the end it's just a data structure that contains color values). I need a protocol for that.

protocol TextFieldTheme {
    var textColor: UIColor {get}
    var placeholderColor: UIColor {get}
    var tintColor: UIColor {get}
    var leftViewTintColor: UIColor {get}
    var rightViewTintColor: UIColor {get}
    var backgroundColor: UIColor {get}
}

Here I define protocol that defines methods to access color values specific for UITextField. For UIButton and other views there will be another set of functions.

Now this protocol can be extended to provide default values for each of color. This way when I will define concrete theme I will not need to define properties for values that are not different from default.

extension TextFieldTheme {
    var textColor: UIColor {
        return UIColor.blackColor()
    }
    var placeholderColor: UIColor {
        return UIColor.lightTextColor()
    }
    var tintColor: UIColor {
        return UIColor(red: 0, green: 100.0/255.0, blue: 220.0/255.0, alpha: 1)
    }
    var leftViewTintColor: UIColor {
        return UIColor(red: 0, green: 122.0/255.0, blue: 1, alpha: 1)
    }
    var rightViewTintColor: UIColor {
        return UIColor(red: 0, green: 122.0/255.0, blue: 1, alpha: 1)
    }
    var backgroundColor: UIColor {
        return UIColor.whiteColor()
    }
}

Here I use colors that are close to system default values.

In a subclass of UITextField, FormTextField I have custom right accessory view. To define it's style I need to extend TextFieldTheme protocol and add additional property. Also I want FormTextField to change it's background color whet it is highlighted. For that I can define separate protocol that will define background color for highlighted state.

protocol HighlightedBackgroundTheme {
    var highlightedBackgroundColor: UIColor {get}
}

protocol FormTextFieldTheme: TextFieldTheme, HighlightedBackgroundTheme {
    var invalidIndicatorColor: UIColor {get}
}

extension FormTextFieldTheme {
    var highlightedBackgroundColor: UIColor {
        return backgroundColor
    }

    var invalidIndicatorColor: UIColor {
        return UIColor(red: 220.0/255.0, green: 0, blue: 0, alpha: 1)
    }
}

Now I have everything to create concrete theme.

struct FormTextFieldDefaultTheme: FormTextFieldTheme {}

struct FormTextFieldCustomTheme: FormTextFieldTheme {
    
    var textColor: UIColor {
        return UIColor.whiteColor()
    }
    var placeholderColor: UIColor {
        return UIColor.lightTextColor()
    }
    var tintColor: UIColor {
        return UIColor.whiteColor()
    }
    var leftViewTintColor: UIColor {
        return placeholderColor
    }
    var rightViewTintColor: UIColor {
        return placeholderColor
    }
    var backgroundColor: UIColor {
        return UIColor(red: 103.0/255.0, green: 103.0/255.0, blue: 103.0/255.0, alpha: 1)
    }
    
    var highlightedBackgroundColor: UIColor {
        return UIColor(red: 145.0/255.0, green: 145.0/255.0, blue: 145.0/255.0, alpha: 1)
    }
    
}

Here I define default theme that inherits all it's values from protocol extension. And custom theme that overrides default values.

Now how can I use those themes? First I can extend UITextField and add method that will apply theme on it.

extension UITextField {
    func updateAppearance(theme: TextFieldTheme) {
        tintColor = theme.tintColor
        textColor = theme.textColor
        backgroundColor = theme.backgroundColor
        leftView?.tintColor = theme.leftViewTintColor
        rightView?.tintColor = theme.rightViewTintColor
        attributedPlaceholder = attributedPlaceholder(theme)
    }
    
    func attributedPlaceholder(theme: TextFieldTheme) -> NSAttributedString? {
        if let placeholder = placeholder {
            return NSAttributedString(string: placeholder, attributes: [
                NSForegroundColorAttributeName: theme.placeholderColor
                ])
        }
        return nil
    }
}

Now I can apply TextFieldTheme to any kind of UITextField including FormTextField. I can reuse that and in FormTextField I can add method that will apply FormTextFieldTheme.

var theme: FormTextFieldTheme = FormTextFieldDefaultTheme() {
    didSet {
        updateAppearance()
    }
}

func updateAppearance() {
    updateAppearance(theme)
}

func updateAppearance(theme: FormTextFieldTheme) {
    super.updateAppearance(theme)
    backgroundColor = highlighted ?
        theme.highlightedBackgroundColor :
        theme.backgroundColor
    (rightView as? InvalidInputIndicator)?.backgroundColor = theme.invalidIndicatorColor
}

Here I also define stored property for theme and shorthand method that will apply current theme.

I should note that FormTextField has now two different methods: updateAppearance(_: TextFieldTheme) and updateAppearance(_: FormTextFieldTheme). The latter does not override the former cause they have different types and also even if we try to override it Swift does not support overriding declarations from extensions. I could solve that by not adding updateAppearance(_: FormTextFieldTheme) but setting right accessory view background color and highlighted background color right in UITextField extension. But then I will need first to check if passed in theme actually conforms to HighlightedBackgroundTheme or FormTextFieldTheme. That's bad because we will need to change this extension every time we add any new theme and it will potentially lead to lots of if statements.

Having two different methods on the other hand makes sense if you think about it. Definition of TextFieldTheme provides clear information about what colors it can change. FormTextFieldTheme in its turn tells us that it can change all the properties that TextFieldTheme can change but also properties specific for FormTextField. So when you call updateAppearance(_: TextFieldTheme) it makes sense that it will change only those colors that are defined by TextFieldTheme. And when you call updateAppearance(_: FormTextFieldTheme) you know that it can change also colors specific for FormTextField.

More than that Swift don't even let us override updateAppearance(_: TextFieldTheme) with updateAppearance(_: FormTextFieldTheme), instead it forces us to have two distinct methods. And that's great because overriding method defined in superclass with method that requires more specific input is violation of Liskov substitution principle. It breaks a contract defined by superclass cause subclass asks more from it's clients than superclass. It's easy to misunderstand what 'more' means when it comes to inheritance. You may think that asking for superclass as argument is 'more' than asking for concrete subclass cause more objects can be passed in where superclass is expected. But in fact it's absolutely another way round cause asking for superclass is asking for less specific instance, where asking for subclass is asking for more specific instance. Here Swift behavior is different from Objective-C. Objective-C would easily let us break the contract cause types of parameters are not the part of method signature.

That's it. Now I have notion of themes without any type checking and with ability to apply theme not only to my custom views, but also to standard UIKit components. In real life application I will probably extend this solution with notion of Color Palette. The thing is that in real life when you work with designer it's very useful when you have defined finite set of colors (palette), marked by numbers (like color1, color2 etc) or some names, and when that colors are used consistently across whole application. This way designer does not need to specify exact colors on each view design but can just put references to color palette. At the same time developer can specify all colors in definition of palette and reference them in each theme. It will help you to remove duplication of hardcoded color values in your themes.

View controller thinning

Sat, 26 Sep 2015 17:51:00 GMT

"Massive view controller" is one of the most favorite topic for iOS developers when they talk about architecture. A lot have been said on this topic already, even more will be said in future cause unfortunately there is no silver bullet and view controller still stay massive in many projects. Recently Andy Matuschak presented here and there a live coding session on this topic. So you can see it's a well know and still actual problem.

The real problem is that there are a lot of responsibility in UIViewController already defined in UIKit. So why to add even more? We should try to minimize view controller responsibility as much as any other class in our application. Apple have made view controller the hart of each iOS application so we should respect them and treat them with the same care as our model, network or persistence layer. But instead we centralize all our code in view controllers.

Recently I've started to work on my new home project and from the beginning I've tried few techniques that I wanted to try for a long time. I think they can be useful in any other project. Not as a step-by-step recipe to solve all possible problems, but as concepts that you can apply to solve your particular case.

A lot of code is involved in this topic so I decided to break it in few parts. In this post I will show how you can refactor messy view controller and make it thinner so that it will follow Single Responsibility principle more. In next post I will show how you can make a next step forward to SRP with concept of behaviors and how Interface Builder lets us decrease lines of code even more if we use it not just to create layouts but as a dependency injection tool. After that I will take the same problem of dependency injection and will show how to solve it with Typhoon framework. You can follow the history of changes here on GitHub.

We will build very simple single view application which will display authorization form and let user to login on arbitrary service. To make things more interesting it will involve some animations and custom UI. We won't need to make any real network requests but for demonstration I'll use SwiftNetworking - framework that I described in one of my previous posts.

Specification

Application should display two input fields - for email and password - and two buttons - to login and to restoring password. If login fails the alert with error message should be displayed. If login or password are invalid then corresponding input fields should be marked with red dot at their right side and should be animated with "shake" animation. When user selects input field its background color should change to slightly lighter color with animation. When user deselects input filed its background color should animate back to initial color. Same effect should be applied to login button when user touches it or removes his finger from it. It should look something like this:

Initial state

As initial state we will take massive view controller that manages everything - views, control actions, animations and business logic.
The whole code is too long to paste it here, so here are links on GitHub - ViewController.swift, FormTextField.swift.

You can see that view controller does so much stuff that it is very hard to understand what it actually does. The only thing that it does not manages are some text input metrics. And this is only because of the API that UITextField provides.

Helpers

We will start with extracting some parts of code in small helpers. To setup icons of text fields we use hardcoded file names. With Swift 2 we can instead define simple extension of UIImage that will use enum with String raw value instead of String file name to create image.

extension UIImage {
    enum AssetIdentifier: String {
        case InputEmailIcon
        case InputPasswordIcon
    }
    convenience init!(_ assetIdentifier: AssetIdentifier) {
        self.init(named: assetIdentifier.rawValue)
    }
}

Swift 2 will automatically assign raw values to enum cases with String raw value type if they are not provided explicitly. So only thing that you should care about is that enum cases should match assets identifiers. If you want you can even generate such enum on build time using some script. This way you will never mistype image names in your code and you will have code completion.

Next we can make corner radius IBInspectable property so that we don't need to set it in code and don't need to access it through layer property.

extension UIView {
    @IBInspectable
    var cornerRadius: CGFloat {
        get {
            return layer.cornerRadius
        }
        set {
            clipsToBounds = newValue != 0
            layer.cornerRadius = newValue
        }
    }
}

Now any subclass of UIView will have field to set it's corner radius in Interface Builder.

Currently we setup text field's icon tint color manually in code and separately for each text field's. It would be cool if we can set it using UIAppearance. The problem is that for that we need to set tint color for UIImageView only if it is contained in UITextField using +(instancetype)appearanceWhenContainedIn:(Class <UIAppearanceContainer>)ContainerClass, .... This API is available from Objective-C but is not available from Swift in iOS 8 (it's available for Swift only in iOS 9 with + (instancetype)appearanceWhenContainedInInstancesOfClasses:(NSArray<Class <UIAppearanceContainer>> *)containerTypes). To solve that we can define Objective-C category that will accept only one class instead of variadic parameter.

@import UIKit;

@interface UIView (Appearance)

+ (instancetype)gh_appearanceWhenContainedIn:(Class<UIAppearanceContainer>)containerClass;

@end

@implementation UIView (Appearance)

+ (instancetype)gh_appearanceWhenContainedIn:(Class<UIAppearanceContainer>)containerClass {
    return [self appearanceWhenContainedIn:containerClass, nil];
}

@end

You can notice that in our application we have few animations with the same duration. It would be cool if we can add implicit animation duration for each view. That will make animations consistent through the whole application. Also you will see how easy it is to add custom UIAppearance properties.

@import UIKit;

@interface UIView (Appearance)
...
@property (nonatomic) NSTimeInterval implicitAnimationDuration UI_APPEARANCE_SELECTOR;

@end

@import ObjectiveC.runtime;

@implementation UIView (Appearance)
...
- (void)setImplicitAnimationDuration:(NSTimeInterval)implicitAnimationDuration
{
    objc_setAssociatedObject(self, @selector(implicitAnimationDuration), @(implicitAnimationDuration), OBJC_ASSOCIATION_RETAIN_NONATOMIC);
}

- (NSTimeInterval)implicitAnimationDuration
{
    return [objc_getAssociatedObject(self, @selector(implicitAnimationDuration)) ?: @(0.25) doubleValue];
}

@end

Here we use Objective-C runtime to define animation duration value using UIView category. To make it accessible through UIAppearance proxy object of UIView we only need to annotate it with UI_APPEARANCE_SELECTOR ¹.

With Swift animations can be simplified even more. Default animationWithDiration method is provided with different set of parameters but if you let's say want to specify animation options you will need to provide all other parameters like delay and completion handler. With Swift we can make it better by adding default values for arguments.

extension UIView {
    class func animateWithDuration(duration: NSTimeInterval = 0, delay: NSTimeInterval = 0, options: UIViewAnimationOptions = [], animations: () -> Void) {
        animateWithDuration(duration, delay: delay, options: options, animations: animations, completion: nil)
    }

    func changeAnimated(animated: Bool, delay: NSTimeInterval = 0, options: UIViewAnimationOptions = [], changes: () -> Void, completion: ((Bool) -> Void)? = nil) {
        UIView.animateWithDuration(animated ? implicitAnimationDuration : 0, delay: delay, options: options, animations: changes, completion: completion)
    }
}

Here we define method that instead of animation duration accepts Bool value and creates animation with implicit duration if it is true or with zero duration if it is false (which means that changes will be not animated at all). Also we define method that accepts animation block as trailing closure ignoring completion block.

Themes

Next thing that we can extract from view controller is setting up views appearance. First we should not hardcode UIColor values in different places in our code, all colors used in application should be specified in one place. This place can be called view theme. View theme should incapsulate all colors used by particular view. View should be able to access this colors using some tags.

protocol ColorTag {}

protocol ColorTheme {
    func colorForTag(tag: ColorTag) -> UIColor
    func mainColor() -> UIColor
}

extension ColorTheme {
    func mainColor() -> UIColor {
        return UIColor.whiteColor()
    }
}

protocol ThemedView: class {
    var theme: ColorTheme {get set}
    func updateAppearance()
}

Here we first define protocol for ColorTag. It's empty protocol cause we will use it only to annotate other types that will play role of tags (i.e. enums can be used as tags). Then we define ColorTheme protocol that has method to access color by tag and main color property. This main color will be used as default color.
With that we can define color theme for FormTextField.

extension FormTextField {
    enum ThemeColorTag: ColorTag {
        case TintColor
        case TextColor
        case PlaceholderColor
        case LeftViewTintColor
        case RightViewTintColor
        case BackgroundColor
        case HighlightedBackgroundColor
        case InvalidIndicatorColor
    }
}

struct FormTextFieldDefaultTheme: ColorTheme {
    func colorForTag(tag: ColorTag) -> UIColor {
        if let tag = tag as? FormTextField.ThemeColorTag {
            switch tag {
            case .TextColor:
                return UIColor.whiteColor()
            case .PlaceholderColor:
                return UIColor.lightTextColor()
            case .LeftViewTintColor, .RightViewTintColor:
                return UIColor.lightTextColor()
            case .BackgroundColor:
                return UIColor(red: 103.0/255.0, green: 103.0/255.0, blue: 103.0/255.0, alpha: 1)
            case .HighlightedBackgroundColor:
                return UIColor(red: 145.0/255.0, green: 145.0/255.0, blue: 145.0/255.0, alpha: 1)
            case .InvalidIndicatorColor:
                return UIColor(red: 220.0/255.0, green: 0, blue: 0, alpha: 1)
            default: return mainColor
            }
        }
        else {
            return mainColor
        }
    }
}

Using this theme we can make FormTextFiled to conform to ThemedView protocol.

extension ThemedView where Self: FormTextField {
    func attributedPlaceholder() -> NSAttributedString? {
        if let placeholder = placeholder {
            return NSAttributedString(string: placeholder, attributes: [NSForegroundColorAttributeName: theme.colorForTag(ThemeColorTag.PlaceholderColor)])
        }
        return nil
    }   
}

class FormTextField: UITextField, ThemedView {
    override init(frame: CGRect) {
        super.init(frame: frame)
        initialized()
    }
    
    required init?(coder aDecoder: NSCoder) {
        super.init(coder: aDecoder)
        initialized()
    }
    
    func initialized() {
        rightView = InvalidInputIndicator(textField: self)
        updateAppearance()
    }

    var theme: ColorTheme = FormTextFieldDefaultTheme() {
        didSet {
            updateAppearance()
        }
    }

    func updateAppearance() {
        tintColor = theme.colorForTag(ThemeColorTag.TintColor)
        textColor = theme.colorForTag(ThemeColorTag.TextColor)
        
        backgroundColor = highlighted ?
            theme.colorForTag(ThemeColorTag.HighlightedBackgroundColor) :
            theme.colorForTag(ThemeColorTag.BackgroundColor)
        
        attributedPlaceholder = attributedPlaceholder(theme)
        leftView?.tintColor = theme.colorForTag(ThemeColorTag.LeftViewTintColor)
        rightView?.tintColor = theme.colorForTag(ThemeColorTag.RightViewTintColor)
        (rightView as? InvalidInputIndicator)?.backgroundColor = theme.colorForTag(ThemeColorTag.InvalidIndicatorColor)
    }
    ...
}

class InvalidInputIndicator: UIView {
    init(textField: FormTextField) {
        super.init(frame: CGRectMake(0, 0, CGRectGetHeight(textField.bounds)/5, CGRectGetHeight(textField.bounds)/5))
        self.layer.cornerRadius = CGRectGetHeight(self.bounds) / 2
    }
    
    required init?(coder aDecoder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }
}

Now in view controller we only need to setup text fields' icons. As we load view from storyboard we can do it not in viewDidLoad but in observers of outlets for this views. When user will select or deselect text field we don't need to set it's background color manually. We can just set it's highlighted property and call updateAppearance() method.

class ViewController: UIViewController, UITextFieldDelegate {
    @IBOutlet
    var userNameInput: FormTextField! {
        didSet {
            userNameInput.leftView = UIImageView(image: UIImage(.InputEmailIcon))
            userNameInput.leftViewMode = UITextFieldViewMode.Always
            userNameInput.updateAppearance()
        }
    }

    @IBOutlet
    var passwordInput: FormTextField! {
        didSet {
            passwordInput.leftView = UIImageView(image: UIImage(.InputPasswordIcon))
            passwordInput.leftViewMode = UITextFieldViewMode.Always
            passwordInput.updateAppearance()
        }
    }
    ...
    func textFieldDidBeginEditing(textField: UITextField) {
        view.changeAnimated(true, options: [.BeginFromCurrentState]) {
            textField.highlighted = true
            (textField as? ThemedView)?.updateAppearance()
        }
    }

    func textFieldDidEndEditing(textField: UITextField) {
        view.changeAnimated(true, options: [.BeginFromCurrentState]) {
            textField.highlighted = false
            (textField as? ThemedView)?.updateAppearance()
        }
    }
    ...
}

The same way we can define theme for login button and change it's background color by calling updateAppearance() when it's highlighted state changes. But I will leave if for now as it is and in the next post will show how you can solve this case differently.

####Root view

Currently we have our layout defined in a storyboard. Though it can be the easiest way for small applications I think that for large projects it's better to use separate xib files for each view to define layout and to use storyboards only to define workflow. Though you can say that workflow is tightly coupled with layout (and you will be probably right) I still think that it's nice to separate them. I worked on one project with bunch of screens where almost every view and all transitions were defined in one storyboard. It was a mess. To clean it up I broke it into smaller storyboards (here you can read how, but iOS 9 introduces storyboards references so it should be easier now to achieve the same result). This made my life a bit easier but I still had a huge table view controller in one storyboard with ten or more cell prototypes and segues attached to them or to their subviews. It was very hard to manage. Some of my colleagues prefer not to use Interface Builder at all, but I think it is just another extreme.

We will not only move layout to separate xib file but we also will create UIView subclass for the root view. Then we can move all the code that manages subviews (text fields and buttons) there. The thing is that we easily create subclasses for our UI components like table view controllers, buttons, text fields. But almost never I've seen anyone creating subclass for root view and making it to manage it's subviews and their presentation logic instead of it's view controller. View controller should not know about any internals of it's root view, like it's subviews, their constraints or animations. View controller should only manage it's lifecycle and act as mediator between different components of business logic and presentation logic. View in turn should provide interface to change it or ask it for it's state.

To use xib file and storyboard at the same time you need few things. Fist delete root view from view controller in storyboard and override it's 'nibName' property:

class ViewController: UIViewController {
    ...
    override var nibName: String? {
        return "AuthView"
    }
    ...
}

Then in AuthView.xib you need to set File's Owner to ViewController and connect root view with it's view outlet. This way when system will load storyboard it will use AuthView.xib to load root view and will set it's root view element as view property of view controller.

Now we can move all outlets, text view delegate callbacks and buttons actions to AuthView:

class AuthView: UIView, UITextFieldDelegate {
    override init(frame: CGRect) {
        super.init(frame: frame)
        self.addEndEditingTapRecognizer()
    }
    
    required init?(coder aDecoder: NSCoder) {
        super.init(coder: aDecoder)
        self.addEndEditingTapRecognizer()
    }
    
    private lazy var endEditingTapRecognizer: UITapGestureRecognizer! = UITapGestureRecognizer(target: self, action: "endEditing")
    
    private func addEndEditingTapRecognizer() {
        self.addGestureRecognizer(endEditingTapRecognizer)
    }

    @objc func endEditing() {
        endEditing(true)
    }
    
    @IBOutlet
    var userNameInput: FormTextField! {
        didSet {
            userNameInput.leftView = UIImageView(image: UIImage(.InputEmailIcon))
            userNameInput.leftViewMode = UITextFieldViewMode.Always
            userNameInput.updateAppearance()
        }
    }
    
    @IBOutlet
    var passwordInput: FormTextField! {
        didSet {
            passwordInput.leftView = UIImageView(image: UIImage(.InputPasswordIcon))
            passwordInput.leftViewMode = UITextFieldViewMode.Always
            passwordInput.updateAppearance()
        }
    }

    @IBOutlet
    var loginButton: UIButton!

    @IBAction
    func loginButtonTapped(sender: UIButton) {
        endEditing()
        
        UIView.animateWithDuration(0.25, delay: 0, options: [UIViewAnimationOptions.BeginFromCurrentState], animations: { () -> Void in
            self.loginButton.backgroundColor = UIColor(red: 0, green: 122.0/255.0, blue: 255.0/255.0, alpha: 1)
            }, completion: nil)
    }

    @IBAction
    func loginButtonTouchBegin(sender: UIButton) {
        UIView.animateWithDuration(0.25, delay: 0, options: [UIViewAnimationOptions.BeginFromCurrentState], animations: { () -> Void in
            self.loginButton.backgroundColor = UIColor(red: 21.0/255.0, green: 160.0/255.0, blue: 255.0/255.0, alpha: 1)
            }, completion: nil)
    }
    
    @IBAction
    func forgottenPasswordTapped() {
        endEditing()
    }

    func textFieldDidBeginEditing(textField: UITextField) {
        self.changeAnimated(true, options: [.BeginFromCurrentState]) {
            textField.highlighted = true
            (textField as? ThemedView)?.updateAppearance()
        }
    }
    
    func textFieldDidEndEditing(textField: UITextField) {
        self.changeAnimated(true, options: [.BeginFromCurrentState]) {
            textField.highlighted = false
            (textField as? ThemedView)?.updateAppearance()
        }
    }
    
    func textFieldShouldReturn(textField: UITextField) -> Bool {
        if textField == userNameInput {
            passwordInput.becomeFirstResponder()
        }
        else {
            endEditing()
            onLoginButtonTapped?(nil)
        }
        return true
    }

    var shakeAnimation: CAKeyframeAnimation = {
        let animation = CAKeyframeAnimation(keyPath: "position.x")
        animation.values = [0, 10, -8, 4, 0]
        animation.keyTimes = [0, (1 / 6.0), (3 / 6.0), (5 / 6.0), 1]
        animation.duration = 0.2
        animation.additive = true
        return animation
    }()

    func markUserNameAsInvalid(invalid: Bool) {
        markTextField(userNameInput, asInvalid: invalid)
    }
    
    func markPasswordAsInvalid(invalid: Bool) {
        markTextField(passwordInput, asInvalid: invalid)
    }
    
    private func markTextField(textField: UITextField, asInvalid invalid: Bool) {
        if invalid {
            textField.rightViewMode = .Always
            textField.layer.addAnimation(shakeAnimation, forKey: "shake")
        }
        else {
            textField.rightViewMode = .Never
        }
    }
}

Notice that we also moved animations in view itself. View controller will call provided methods to mark input fields as invalid but it will be view how will decide how to present it to user.

Now view controller does not care about presentation logic of it's root view, it's subviews (we can even make them private if we want) and their animations. But also now there is no way for it to know that button was tapped. At the same time we should not add business logic (performing user login) to view. We can solve this simply by defining closure property on AuthView that it will call when we need to perform action on login button. View controller will set this closure to call it's login method. It is similar to what we've used to do in Objective-C with delegate pattern but it's simpler cause we don't need additional protocol for that. The same way we could add closure to respond to "Forgotten password" button but I will skip this.

class AuthView: UIView, UITextFieldDelegate {
    ...
    var onLoginButtonTapped: ((username: String, password: String) -> Void)?
    
    @IBAction
    func loginButtonTapped(sender: UIButton) {
        endEditing()
        
        UIView.animateWithDuration(0.25, delay: 0, options: [UIViewAnimationOptions.BeginFromCurrentState], animations: { () -> Void in
            self.loginButton.backgroundColor = UIColor(red: 0, green: 122.0/255.0, blue: 255.0/255.0, alpha: 1)
            }, completion: nil)

        onLoginButtonTapped?(username: userNameInput.text!, password: passwordInput.text!)
    }

    func textFieldShouldReturn(textField: UITextField) -> Bool {
        if textField == userNameInput {
            passwordInput.becomeFirstResponder()
        }
        else {
            endEditing()
            onLoginButtonTapped?(username: userNameInput.text!, password: passwordInput.text!)
        }
        return true
    }
}

class ViewController: UIViewController {
    ...
    var authView: AuthView! {
        return view as! AuthView
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        authView.onLoginButtonTapped = login
    }
    
    func login(username:String, password: String) {
        apiClient.login(username, password: password, completion: onLoggedIn)
    }
    ...
}

Have you noticed how many stuff already we have moved away from view controller? Now it manages only some of view setup and business logic. Most of presentation logic have moved to view itself. And I'm sure this is the right place for it. Even if you have complex view with lot's of stuff that should change on different events coming from different parts of your app, like for example constraints, they should not be changed or accessed by view controller directly. There should be API for that provided by UIView subclass. It is commonly said that view controllers are hard to test cause of their complex lifecycle. Views have much more simple lifecycle so they are better candidates for testing and handling presentation logic. Stay tuned and check out next parts of this series.

Unfortunately it looks like you can't use UI_APPEARANCE_SELECTOR together with IBInspectable which will be ignored for properties marked with UI_APPEARANCE_SELECTOR. That means that you can setup views properties either with UIAppearance proxy or with Interface Builder, not with both at the same time.↩︎

Path to Carthage. Real-life experience.

Mon, 21 Sep 2015 12:22:57 GMT

When it comes to dependency management in Cocoa world you have three options:

Cocoapods
Carthage
Don's use dependency management

First one, Cocoapods, have been around for quiet a long time already and is default tool for most of developers. It was designed from the beginning not just as dependency management tool, but as ecosystem for third party open-source components. It is easy to use in most cases. But it can be very painful to manage especially when it comes to customization and your lack of Ruby experience. Once I had few very hard days trying to make it work for my own project dealing with Specs and Podfiles. The other thing I personally don't like about Cocoapods is that it adds to much stuff in your project and it always requires few steps to remove this stuff completely. Also for some time (when I needed it most) Cocoapods lack support for frameworks. At the same time Cocoapods play nice when you need to work with local dependencies. After all after all my experience with Cocoapods I can say I dislike it and prefer not to use it.

In my current team we don't use Cocoapods (though our second team use it actively). Main reason for that was that we are not using any third party components - we do networking, core data and all other stuff by our own means. Recently we came to the decision to break our code base in smaller isolated components. The idea behind that was to decouple things better and to decrease time to run tests (we have more than 3500 tests and not all of them are running at light speed). For sure we needed dependency management tool for that and keeping in mind the fact that we support only iOS 8 we decided to try Carthage.

Carthage

Carthage somehow is similar to Cocoapods. You define your dependencies in similar manner using Cartfile. The differences with Cocoapods are huge though. Carthage don't integrate anything in your project. It only does what dependency management tool should do - resolve and manage dependencies. By resolving dependencies I mean building and going through graph of dependencies, detect version conflicts. By managing dependencies I mean checking out source code from VCS and preparing it to be used in project. Carthage does that by building frameworks (though you can skip this step). When dependencies are resolved you get Cartfile.resolved file with list of commits that were checked out for each of the dependencies and artifacts like checked out source code and frameworks binaries. Then you simple link your target to this frameworks. Or you can add source code as sub-project. Though there are few additional steps you may need to go through to make it work they are very simple. Much simpler, I can say, than adding build hooks to Podfile. And you don't need any specs to describe your project to make it available for Carhtage. You only need shared scheme that builds framework. If there is no target to build than carthage will only check-out source code. This way you can distribute Xcode configs or Protocol Buffers specs, not only frameworks.

But nothing good comes without cost. There are few gotchas in Carthage that we came across while splitting our code base by separate frameworks.

It builds everything

When you run carthage update or carthage bootstrap it will build every dependency even if they were not changed. That makes updating rather slow. For now there is no way (that I would know) you can specify that you want to update only specific dependency. Also before 9.0 release there was a bug with wrong build order when you have sub-dependencies. Basically they were resolved in wrong order - framework that depends on another framework was built before framework it depends on. Though you could solve it simply by changing lines order in Cartfile.resolve (it looks like Carthage builds frameworks in exact order in which they appear in this file) it becomes very annoying when your have relatively large dependency graph and you have to update frequently. Another way to solve it is to provide --no-build option and add your dependencies as sub-projects so that Xcode will build them itself.

Development

Carthage lets you checkout dependencies as submodules which can be handy when you are actively changing things. But that brings with it all the headache of submodules. Again you can not use only one dependency as submodule - it's all or nothing.

Using binaries

There is another feature in Carthage when you can upload binary to your GitHub release and Carthage will download it without building and checking out source code. This can save a lot of time when updating. But you should keep in mind that if you link against binaries (either that Carthage built for you or downloaded from GitHub) it will be harder to debug and change their code. Again you can not specify for what dependencies you want to download binaries and for what you want Carthage to build them. You can only disable this function completely with --no-use-binaries option.

Project settings

Be careful with your project settings. Even if Xcode can build your target and carthage build --no-skip-current does not fail it still may not work when you use it as a dependency. First of all you should be careful about code signing - frameworks should be code signed and it should match your main target signing. Also you need to be careful with settings like DYLIB_INSTALL_NAME_BASE (it should be @rpath) and LD_RUNPATH_SEARCH_PATHS (it should be @executable_path/Frameworks @loader_path/Frameworks, maybe you will also need to add @executable_path/../Frameworks @loader_path/../Frameworks). In one of the projects DYLIB_INSTALL_NAME_BASE was wrong for some reason and it took me some time to figure out the problem. If you own any of dependencies that you use and it contains Swift code then do not set EMBEDDED_CONTENT_CONTAINS_SWIFT to YES in it's project. Do it only in your main project. Otherwise xcodebuild (used by Carthage to build frameworks) will copy Swift libraries to Frameworks subfolder of your framework. I didn't understand this setting at first and got problems later trying to archive application.

Build machines

We spent quite some time making Carthage to work on our build machines. The problem was that it could not access GitHub by SSH. The same problem also occurred few times on my colleagues' local machines (probably as a result of some bug). The way we solved it on build machine was to put GitHub token in Key Chain. Locally you probably will need to checkout one of the dependencies manually with SSH. Another thing you should be aware of is that on build machine you should use carthage bootstrap, not update and you should commit your Cartfile.resolve file. This way you will have exactly the same versions of dependencies that you used locally when you build on build machine.

Contribution

Carthage is an open-source project written in Swift. So anyone interested can make it better. But the entry level for contributing is very high - it's build with ReactiveCocoa and the fact that it is in Swift does not make it easier. That was very sad when I faced some bugs and could not do anything but commenting in GiHub issues. Very subjective but still an issue for me.

Conclusion

Though we spent some time fighting with bugs (which are looks like fixed by 9.0 release) and finding the right strategy for us to use Carthage our experience with it is rather good and we will continue to use it. There is one lesson that I've personally learnt. If you actively change your dependencies' code then don't link to binaries directly, instead include their source code as sub-project. When its code base becomes stable start using binaries attached to GitHub releases (if you use GitHub at all) to speed up bootstrap on your build machines. We have about 8 dependencies in our project and it saves us few minutes on each build.

Networking in Swift

Thu, 10 Sep 2015 19:10:13 GMT

Recently I've updated my post on how you can implement lightweight networking in Objective-C. Now it's time to look at the same problem from perspective of Swift. If you want to check out code right away you can do it on Github.

As AFNetowrking is the default tool of choice for most of Objective-C developers, Alamofire became such in Swift community. But it's always useful to practice and find your own solutions. So let's look how we can do networking by ourselves and what we can achieve there using powerful Swift features like generics, structs and enums.

Endpoints

When you make HTTP request you reach some endpoint or resource on the remote server. This endpoint describes HTPP method you can use to access it, path of the resource, query parameters. We can minimally describe endpoint using protocol:

public protocol Endpoint {
    var path: String {get}
    var method: HTTPMethod {get}
}

There are limited number of endpoints that any API can provide. Enum will be the best way to implement Endpoint protocol. Let's say you have some blog platform API that provides endpoints for posts. Your endpoints enum can look like this:

public enum PostsEndpoint: Endpoint {
    
    case GetPosts
    case GetPost(Post.Id)
    case AddPost
    case UpdatePost(Post.Id)
    case DeletePost(Post.Id)
    
    public var path: String {
        switch self {
        case .GetPosts: return "posts/"
        case .GetPost(let id): return "posts/\(id)/"
        case .AddPost: return "posts/"
        case .UpdatePost(let id): return "posts/\(id)/"
        case .DeletePost(let id): return "posts/\(id)/"
        }
    }
    
    public var method: HTTPMethod {
        switch self {
        case .GetPosts, .GetPost: return .GET
        case .AddPost: return .POST
        case .UpdatePost: return .PUT
        case .DeletePost: return .DELETE
        }
    }
}

HTTP methods and headers

HTTP method can be also easily described by enum:

public enum HTTPMethod: String {
    case GET = "GET"
    case POST = "POST"
    case PUT = "PUT"
    case DELETE = "DELETE"
}

Different APIs can have different custom HTTP headers. Still we can define them as enum providing some standard values and ability to set custom header with arbitrary key and value.

public typealias MIMEType = String

public enum HTTPHeader {
    
    case ContentDisposition(String)
    case Accept([MIMEType])
    case ContentType(MIMEType)
    case Authorization(AccessToken)
    case Custom(String, String)
    
    var key: String {
        switch self {
        case .ContentDisposition:
            return "Content-Disposition"
        case .Accept:
            return "Accept"
        case .ContentType:
            return "Content-Type"
        case .Authorization:
            return "Authorization"
        case .Custom(let key, _):
            return key
        }
    }
    
    var requestHeaderValue: String {
        switch self {
        case .ContentDisposition(let disposition):
            return disposition
        case .Accept(let types):
            return ", ".join(types)
        case .ContentType(let type):
            return type
        case .Authorization(let token):
            return token.requestHeaderValue
        case .Custom(_, let value):
            return value
        }
    }
    
    func setRequestHeader(request: NSMutableURLRequest) {
        request.setValue(requestHeaderValue, forHTTPHeaderField: key)
    }
}

Requests and responses

Before we move to describing requests and responses we need to define some helper protocols that will help us to construct requests with arbitrary data and deserialize response data.

public protocol APIRequestDataEncodable {
    func encodeForAPIRequestData() throws -> NSData
}

public protocol APIResponseDecodable {
    init?(apiResponseData: NSData) throws
}

First protocol APIRequestDataEncodable defines function that will be used to convert arbitrary object to NSData for request body. APIResponseDecodable defines failable initializer to initialize object using response data.

Now using all these abstractions we can describe HTTP request. All we need to describe request is it's endpoint, base url (let's say you have production and development environments of your API with different domains), headers and query. Each request have different type of data that we expect in response. To abstract it we will use generic ResultType. Also request can be created with some input object. In this case this input object should conform to APIRequestDataEncodable so that we can encode it to body data without knowing any of its details. Finally we can define basic interface of request so that we can i.e. put them in array¹ or access its basic properties without caring about its generic type of result.

public protocol APIRequestType {
    
    var body: NSData? {get}
    var endpoint: Endpoint {get}
    var baseURL: NSURL {get}
    var headers: [HTTPHeader] {get}
    var query: [String: String] {get}
    
}

public struct APIRequestFor<ResultType: APIResponseDecodable>: APIRequestType {
    
    public let body: NSData?
    public let endpoint: Endpoint
    public let baseURL: NSURL
    public let headers: [HTTPHeader]
    public let query: [String: String]

    public init(endpoint: Endpoint, baseURL: NSURL, query: [String: String] = [:], headers: [HTTPHeader] = []) {
        self.endpoint = endpoint
        self.baseURL = baseURL
        self.query = query
        self.headers = headers
        self.body = nil
    }

    public init(endpoint: Endpoint, baseURL: NSURL, input: APIRequestDataEncodable, query: [String: String] = [:], headers: [HTTPHeader] = []) throws {
        self.endpoint = endpoint
        self.baseURL = baseURL
        self.query = query
        self.headers = headers
        self.body = try input.encodeForAPIRequestData()
    }
}

Response object is even simpler. Basically it should incapsulate HTTP response, it's data, error, original request and content type. We also can constrain it with generic type of its data so that APIRequestFor can be used only with APIResponseOf with the same generic result type.

public protocol APIResponse {
    
    var httpResponse: NSHTTPURLResponse? {get}
    var data: NSData? {get}
    var error: ErrorType? {get}
    var originalRequest: NSURLRequest? {get}
    var contentType: MIMEType? {get}
    
}

public struct APIResponseOf<ResultType: APIResponseDecodable>: APIResponse {
    
    public let httpResponse: NSHTTPURLResponse?
    public let data: NSData?
    public let originalRequest: NSURLRequest?
    internal(set) public var error: ErrorType?
    internal(set) public var result: ResultType?
    
    init(request: NSURLRequest? = nil, data: NSData? = nil, httpResponse: NSURLResponse? = nil, error: ErrorType? = nil) {
        self.originalRequest = request
        self.httpResponse = httpResponse as? NSHTTPURLResponse
        self.data = data
        self.error = error
        self.result = nil
    }
}

Serialization and deserialization

Now let's define some additional classes that will serialize requests and deserialize responses.

First thing we need is to process request. Request processor will take APIRequestType as input and will produce NSMutableURLRequest.

public protocol APIRequestProcessing {
    func processRequest(request: APIRequestType) throws -> NSMutableURLRequest
}

public class DefaultAPIRequestProcessing: APIRequestProcessing {

    public var defaultHeaders: [HTTPHeader]
    
    public init(defaultHeaders: [HTTPHeader] = []) {
        self.defaultHeaders = defaultHeaders
    }
    
    public func processRequest(request: APIRequestType) throws -> NSMutableURLRequest {
        let components = NSURLComponents(string: request.endpoint.path)!
        components.queryItems = NSURLQueryItem.queryItems(request.query)
        guard let url = components.URLRelativeToURL(request.baseURL) else {
            throw NSError(code: .BadRequest)
        }
        
        let httpRequest = NSMutableURLRequest(URL: url)
        httpRequest.HTTPMethod = request.endpoint.method.rawValue
        httpRequest.HTTPBody = request.body
        for header in defaultHeaders + request.headers {
            header.setRequestHeader(httpRequest)
        }
        return httpRequest
    }

}

Note that input argument is not APIRequestFor but APIRequestType. While building HTTP request we don't care about type of the result, but if we would use APIRequestFor we would have to make processing method generic as well.

To process response data we need another class that will return complete APIResponseOf based on partial response built from data provided by NSURLSession callbacks.

public protocol APIResponseProcessing {
    func processResponse<ResultType>(var response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) -> APIResponseOf<ResultType>
}

public class DefaultAPIResponseProcessing: APIResponseProcessing {

    public func processResponse<ResultType>(var response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) -> APIResponseOf<ResultType> {
        do {
            try validate(response, request: request)
            response.result = try decode(response, request: request)
        }
        catch {
            response.error = error
        }
        return response
    }
    
    final private func validate<ResultType>(response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) throws {
        try validateError(response, request: request)
        try validateHTTPResponse(response, request: request)
        try validateStatusCode(response, request: request)
        try validateContentType(response, request: request)
    }
    
    final private func validateError<ResultType>(response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) throws {
        if let error = response.error {
            throw error
        }
    }
    
    final private func validateHTTPResponse<ResultType>(response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) throws {
        if response.httpResponse == nil {
            throw NSError(code: .InvalidResponse)
        }
    }
    
    final private func validateStatusCode<ResultType>(response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) throws {
        if let error = NSError.backendError(response.httpResponse!.statusCode, data: response.data) {
            throw error
        }
    }
    
    final private func validateContentType<ResultType>(response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) throws {
        if let contentType = response.contentType {
            for case let .Accept(acceptable) in request.headers {
                if !acceptable.contains(contentType) {
                    throw NSError(code: .InvalidResponse)
                }
            }
        }
    }
    
    final private func decode<ResultType>(response: APIResponseOf<ResultType>, request: APIRequestFor<ResultType>) throws -> ResultType? {
        if let data = response.data {
            return try ResultType(apiResponseData: data)
        }
        return nil
    }

}

    public init() {}
    
}

Here we first validate partial response on errors, status code and content type and then try to create ResultType instance from response data using it's failable initializer. Note that here we need to use generic methods 'cause we need to provide result type for APIResponseOf somehow.

Client

Last thing we need is "API client", the object that provides API to make requests. In simplest case it can be a minimal wrapper of NSURLSession.

public class APIClient {
    public let baseURL: NSURL
    private let session: NSURLSession

    let requestProcessing: APIRequestProcessing
    let responseProcessing: APIResponseProcessing

    public init(baseURL: NSURL, session: NSURLSession, requestProcessing: APIRequestProcessing = DefaultAPIRequestProcessing(), responseProcessing: APIResponseProcessing = DefaultAPIResponseProcessing()) {
        self.baseURL = baseURL
        self.session = session
        self.requestProcessing = requestProcessing
        self.responseProcessing = responseProcessing
    }

    public func request<ResultType>(request: APIRequestFor<ResultType>, completion: APIResponseOf<ResultType> -> Void) -> NSURLSessionTask? {
        var task: NSURLSessionTask?
        do {
            let httpRequest = try self.requestProcessing.processRequest(request)
            task = self.session.dataTaskWithRequest(httpRequest, completionHandler: { (data, response, error) -> Void in
                self.completeRequest(task!.request, data: data, response: response, error: error, completionHandler: completion)
            })
            task.resume()
        }
        catch {
            cancelRequestWithError(error, completionHandler: completion)
        }
        return task
    }

    private func completeRequest(request: NSURLRequest!, data: NSData!, response: NSURLResponse, error: NSError!, completionHandler: APIResponseOf<ResultType> -> Void) {

        var apiResponse = APIResponseOf<ResultType>(request: task!.originalRequest, data: data, httpResponse: response, error: error)
        apiResponse = self.responseProcessing.processResponse(apiResponse, request: request)
        dispatch_async(dispatch_get_main_queue()) {
            completionHandler(apiResponse)
        }
    }

    private func cancelRequestWithError(error: ErrorType?) {
        let response = APIResponseOf<ResultType>(request: nil, data: nil, httpResponse: nil, error: error, completionHandler: APIResponseOf<ResultType> -> Void)
        dispatch_async(dispatch_get_main_queue()) {
            completionHandler(apiResponse)
        }
    }
}

Here APIClient tries to build HTTP request from APIRequestFor and creates NSURLSessionTask from it. In it's completion handler it process response data to instance of APIResponseOf and pass it to caller. If HTTP request fails to build caller will receive a callback with response that will contain error thrown on creating request.

To use this client you can extend it providing methods to access particular resources. For example to request posts you can create following method:

protocol PostsAPI {
    func posts(completion: APIResponseOf<Posts> -> Void) -> NSURLSessionTask?
}

extension APIClient: PostsAPI {

    public func posts(completion: APIResponseOf<Posts> -> Void) -> NSURLSessionTask? {
        let apiRequest = APIRequestFor<Posts>(endpoint: PostsEndpoint.GetPosts, baseURL: baseURL)
        return request(apiRequest, completion: completion)
    }
}

Conclusion

In this post I showed one of the ways how you can create your own network layer using Swift and it's features like generics, protocols, structs and enums. With generics there is actually no way for client to mess up with types of response data. And by separating requests and response processing to separate objects we provide clients of our code chance to change this behavior adding some additional logic.
Of course in real life you should think twice before you decide to implement such thing as network layer yourself or use existing frameworks like Alamofire. My advice is to take advantage of open source community work and use reliable and popular frameworks in your production code. But you must understand how they work, investigate their source code. It should not be black box for you and you can even learn from it. Implementing same functionality by yourself will help you to understand how they work and probably why they were build this way and possibly how they can be improved.

You can check out source code for this posts (with some improvements for tasks management and request signing) on Github.

The problem is that you can not put generic types in Swift collections, cause there are also generic and require all items to have the same type defined at compile time. For instance APIRequestFor<Posts> and APIRequestFor<Users> are different types, though they both are APIRequestFor instances. You can not define Array<APIRequestFor> cause APIRequestFor requires it's ResultType, and you can not use Array<APIRequestFor<AnyObject>> or Array<APIRequestFor<Any>>. But you can use Array<APIRequestType>, though you will lose information about ResultType of each request. ↩︎

Lightweight networking in Objective-C

Sat, 15 Aug 2015 19:18:00 GMT

AFNetworking is the most popular networking library for iOS. Chances are high that it's the first pod you add to your Podfile. It's used as a standalone network layer and as a part of some other frameworks, like RestKit. For me it has earned it's popularity for few reasons. It's well maintained, what is very important for open source project (thought it still has long living issues). And it has well thought architecture and interface, so it is easy to use and extend to your needs.

When we perform a request using AFNetworking we can receive serialized JSON object, either dictionary or array. And we can work with it right away. But we can do better. It's much better to work not with dictionaries and arrays but our own business objects. RestKit does this job but I find it's interface quiet complex (besides that it still uses 1.x version of AFNetworking and adds it's own bugs) and never used and never will use it in my projects. So let's see how we can improve our networking code ourselves with very little effort and without using AFNetworking at all. You can download full project on GitHub.

When we make a request it has some well known signature, like it's method, set of parameters and path. As a response to the request we expect some defined type of data. Let's create helper classes which will encapsulate requests and responses.

Here is our request:

typedef NS_ENUM(NSUInteger, HTTPMethod){
GET, POST, PUT, DELETE, HEAD
};

@protocol APIResponse;

@protocol APIRequest <NSObject>

- (HTTPMethod)method;
- (NSURL *)baseURL;
- (NSString *)path;
- (NSDictionary *)parameters;
- (NSDictionary *)headers;
- (Class<APIResponse>)responseClass;

@end

@protocol APIResponse <NSObject>

- (NSURLSessionDataTask *)task;
- (NSURLResponse *)response;
- (NSError *)error;
- (id)responseObject;
- (id)processedResponseObject;

- (instancetype)initWithTask:(NSURLSessionDataTask *)task
                response:(NSHTTPURLResponse *)response
            responseObject:(id)responseObject
                    error:(NSError *)error;

- (id)processResponseObject:(NSError **)error;

@end

We can add now some basic implementation of these protocols, i.e. to represent request for data in JSON format:

@interface SimpleAPIRequest : NSObject <APIRequest>

@end

@interface JSONAPIRequest : SimpleAPIRequest

@end

@interface SimpleAPIRequest()

@property (nonatomic) HTTPMethod method;
@property (nonatomic, copy) NSString *path;
@property (nonatomic, copy) NSDictionary *parameters;
@property (nonatomic, copy) NSDictionary *headers;
@property (nonatomic) Class<APIResponse> responseClass;

@end

@implementation SimpleAPIRequest

- (instancetype)init
{
    self = [super init];
    if (self) {
        self.responseClass = [SimpleAPIResponse class];
    }
    return self;
}

@end

@implementation JSONAPIRequest

- (instancetype)init
{
    self = [super init];
    if (self) {
        self.responseClass = [JSONAPIResponse class];
        self.headers = @{@"Accept": @"application/json", @"Content-type": @"application/json"};
    }
    return self;
}

@end

@interface SimpleAPIResponse: NSObject <APIResponse>

@end

@interface JSONAPIResponse : SimpleAPIResponse

@end

@interface SimpleAPIResponse ()

@property (nonatomic, copy) NSURLSessionDataTask *task;
@property (nonatomic, copy) NSHTTPURLResponse *response;
@property (nonatomic, copy) NSError *error;
@property (nonatomic, strong) id responseObject;
@property (nonatomic, strong) id processedResponseObject;

@end

@implementation SimpleAPIResponse

- (instancetype)initWithTask:(NSURLSessionDataTask *)task response:(NSHTTPURLResponse *)response responseObject:(id)responseObject error:(NSError *)error;
{
    self = [super init];
    if (self) {
        self.task = task;
        self.response = response;
        self.error = error;
        self.responseObject = responseObject;
        
        if (!error) {
            NSError *serializationError;
            self.processedResponseObject = [self processResponseObject:&serializationError];
            if (serializationError) {
                self.error = serializationError;
            }
        }
    }
    return self;
}

- (id)processResponseObject:(NSError *__autoreleasing *)error
{
    return self.responseObject;
}

@end

@implementation JSONAPIResponse

- (id)processResponseObject:(NSError *__autoreleasing *)error
{
    if ([self.responseObject isKindOfClass:[NSData class]]) {
        NSError *serializationError;
        id processedResponseObject = [NSJSONSerialization JSONObjectWithData:self.responseObject options:0 error:&serializationError];
        if (error) *error = serializationError;
        return processedResponseObject;
    }
    else {
        return nil;
    }
}

@end

To make requests we need some object. It will make request using NSURLSessionTask. Let's define it's protocol.

typedef void(^APIClientCompletionBlock)(id<APIResponse> response);

@protocol APIClient <NSObject>

- (NSURLSessionDataTask *)dataTaskWithAPIRequest:(id<APIRequest>)request
                                        completion:(APIClientCompletionBlock)completion;

@end

Foundation already has class that can create NSURLSessionTask - NSURLSession. So let's extend it and implement APIClient protocol in it's category:

@interface NSURLSession(APIClient) <APIClient>

@end

@implementation NSURLSession(APIClient)

- (NSURLSessionDataTask *)dataTaskWithAPIRequest:(id<APIRequest>)request
                                        completion:(APIClientCompletionBlock)completion;
{
    NSURL *requestUrl = [NSURL urlWithString:request.path baseURL:request.baseURL parameters:request.parameters];
    NSURLRequest *httpRequest = [NSURLRequest requestWithMethod:request.method url:requestUrl headers:request.headers];
    __block NSURLSessionDataTask *task;
    task = [self dataTaskWithRequest:httpRequest completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        
        Class responseClass = [request responseClass];
        id<APIResponse> apiResponse = [[responseClass alloc] initWithTask:task response:(NSHTTPURLResponse *)response responseObject:data error:error];
        
        dispatch_async(dispatch_get_main_queue(), ^{
            if (completion) { completion(apiResponse); }
        });
    }];

    [task resume];
    return task;
}

@end

This implementation is very generic. In callbacks we can receive instance of APIResponse protocol or some specific class that request instance returns from +responseClass method. By methods that provide specific type of response we can give clients of our code some type safety.

Now lets look how we can use that. Lets say we have some API that returns GitHub users. Lets define users request and response:

@interface GitHubJSONRequest : JSONAPIRequest

@end

@implementation GitHubJSONRequest

- (NSURL *)baseURL
{
    return [NSURL URLWithString:@"https://api.github.com"];
}

@end


@interface UsersRequest : GitHubJSONAPIRequest

@end

@implementation UsersRequest

- (HTTPMethod)method
{
    return GET;
}

- (NSString *)path
{
    return @"users";
}

- (Class)responseClass
{
    return [UsersResponse class];
}

@end


@interface UsersResponse : JSONAPIResponse

@property (nonatomic, strong, readonly) NSArray *users;

@end

@implementation UsersResponse

- (BOOL)processResponseObject:(NSError **)error;
{
    NSError *__error;
    id processedResponseObject = [super processResponseObject:&__error];
    if (__error || ![processedResponseObject isKindOfClass:[NSArray class]]) {
        if (error) *error = __error;
        return nil;
    }
    else {
        return [User withArray:processedResponseObject];
    }
}

- (NSArray *)users
{
    return self.processedResponseObject;
}

@end

Defining shorthand methods to access processed response objects (like - (NSArray *)users) will give our clients a straight way to access data they need and provide information about type of this data so they will not need to guess the type and cast it.

What about api client? We don't need to subclass it, we can use it's category to add behavior that we need:

typedef void(^UsersResponseBlock)(UsersResponse *response);

@protocol GitHubClient <APIClient>

- (NSURLSessionDataTask *)getUsers:(UsersResponseBlock)completion;

@end

@interface APIClient (GitHub) <GitHubClient>

@end

@implementation APIClient (GitHub)

- (NSURLSessionDataTask *)getUsers:(UsersResponseBlock)completion;
{
    UsersRequest *request = [[UsersRequest alloc] init];
    NSURLSessionDataTask *task = [self dataTaskWithAPIRequest:request completion:completion];
    [task resume];
    return task;
}

@end

First we create a request. Then we call the method of APIClient that actually perform request.
Adding -getUsers:... method will make a client of our code to be sure about what kind of response it will get - without any typecasting at all.

And that's all.

Conclusion

Let's look what we have achieved using this approach:

All of our requests and responses are encapsulated in small classes that are easy to read and test. When our api changes we will change only request or response class and will not need to change our api client or any other object.
Mapping to business objects is made at the moment when response object is created and it's done in generic way. All we need is to override template method in response class. It is also easy to test.
Type safety. Clients of our code should explicitly define relationships between requests and responses. Our code then guarantees that it will provide client with the right objects. Of course it's not real type safety comparing with Swift but at least we will have proper code completion and will get rid of typecasts.
We didn't use AFNetworking at all. So you can see how easy it is to manage networking yourself. AFNetworking of course provides much more functionality, but using described approach you can extend not just NSURLSession, but also AFHTTPSessionManager and make it more convenient to use.

Testing Sync Engine

Thu, 30 Jul 2015 15:48:14 GMT

Here is a small presentation that I've made about two weeks ago for our Wire team that provides some overview of Sync Engine testing (by Sync Engine we call our in-house framework that does all networking and data base management). It covers main problems we have to solve and what we still have to do and how we plan to do it. If you want dive deep in code and know i.e. how we deal with Core Data in our tests - checkout this great article for objc.io by Daniel Eggert.

Swift 2. Part 1.

Sun, 28 Jun 2015 11:49:34 GMT

This year I was lucky enougth to go to WWDC as part of Wire team. For me the most exciting stuff Apple introduced this year was Swift 2. I went almost to every session about programming languages, ignoring watchOS sessions and games completely. Though the main inspiration I've got from WWDC was to learn game development using Apple tools, like new GameKit. But that's not the point of this post.

After comming back from WWDC we had a tech talk at Wire and talked with our colleagues about the conference. I've presented about Swift and Objective-C and here is what I've talked about. Some topics are too big to inculed them in one post, so I've decided to break it in several parts.

Protocol extensions

In Swift 2 we can now extend not only structs, enums and classes, but also protocols. That gives us opportunity to provide default implementation of some method to all those types that conform to this protocol.

extension CollectionType {
    func myMap<U>(f: Self.Generator.Element -> U) -> [U] {
        var result: [U] = []
        for item in self {
            result.append(f(item))
        }
        return result
    }
}

[1, 2, 3, 4].myMap({ $0 * 2 })

Methods in protocol extensions can be, but not necessarily, defined in protocol itself. You can also override methods from protocol extensions in your conforming type and it will take precedence over "default" implementation of protocol extension.

protocol Letter {
    func print() -> String
}

extension Letter {
    func print() -> String {
        return "?"
    }
}

class A: Letter {
    func print() -> String {
        return "A"
    }
}

class Б: Letter {
}

A().print() //returns 'A'
Б().print() //returns '?'

Swift 2 makes protocol extensions even more powerfull than other types of extensions. You can provide constraints on the extensions, i.e. constraint on protocol associated type. Only those types that satisfy constraints will have extendend behaviour. This will work in parallel with unconstraind extensions. This way types that confrom to protocol and satisfy extension constraints will have both behaviours - from constrained and unconstrained extensions. All other confirming types will have behaviour only from unconstrained extension. This can be used pretty much the same way as function generic constraints in Swift 1.x.

extension SequenceType where Generator.Element: Equatable {
    func all(equalTo: Generator.Element) -> Bool {
        return !self.contains { $0 != equalTo }
    }
}

extension SequenceType {
    func all(criteria: Generator.Element -> Bool) -> Bool {
        return !self.contains { !criteria($0) }
    }
}

//Bool type conforms to Equatable,
//so you can use constrained extension:
[true, false, true].all(true)

//Or unconstrained:
[true, false, true].all {$0 == true}

struct User {
    let name: String
}

let users: [User] = [User(name: "Ilya"), User(name: "Marco")]

// User type does not conform to Equatable,
// so you can use only unconstrained extension:
users.all {$0.name == "Ilya"}

func ==(user1: User, user2: User) -> Bool {
    return user1.name == user2.name
}

extension User: Equatable {}

//Now when User type conforms to Equatable
//we can use constrained extension on User too:
users.all(User(name: "Ilya"))

Protocol extensions can also solve problem of optional methods in protocols. Remember that to be able to have optional method in Swift protocol you have to mark it with @objc attribute, which is not always what you really want. Instead you could separate your protocol in two parts and use optional variable of one of these protocols. This is also can be not ideal variant. With protocol extensions you can extend your protocol and provide default implementation for optional method. This way your types do not have to implement this method in order to conform to protocol, but they will be able to override it on demand. The drawback here is that you can not represent protocol extensions in Objective-C, so you can not extend Objective-C protocols.

As one of results of introducing this feature number of global functions in Swift standard library was reduced. Such functions as filter, map, readuce are defined in SequenceType and CollectionType extensions.

Protocol extensions and rich Swift type system open up a world of 'protocol oriented programming', as Apple calls it, for Cocoa developers (which is, as for me, nothing new). Swift 2 even more makes you to think about your type system. It is the language where difference between good and bad code is in good and bad type system.

Error handling

Next big new thing in Swift 2 is error handling. Though we had NSException for quite a long time in Objective-C developers still use them very rarely, usually for unrecoverable errors, pretty much as assertions. Instead we use NSError as in-out parameter to report our calling code about errors in called method. There is even a code convention around that pattern - if you accept error in-out parameter as last parameter of your method it should return Bool that will mean success or failure. We used the same pattern in Swift 1.x. Even more - in Swift 1.x you could not throw and catch exceptions at all. With Swift 2 things have changed and now we have something semantically similar to exceptions:

enum MyError: ErrorType {
    case SomeError
}

func methodThatThrows() throws -> Void {
    throw MyError.SomeError
}

do {
    try methodThatThrows()
}
catch {
    print(error)
}

As you can see we have new ErrorType protocol. To mark that your method can return error you add throws keyword in it's definition. You throw error with throw keyword. To call method that can throw error you must annotate it with try keyword. You can call it with try in new do-catch block. You can have as much catch block as you need and you can use them almos like switch cases, what means you can use pattern matching.

Note that adding throws to function declaration effectively creates new type of function. Function that throws is different than function that does not throw, so you can not exchange them (you can exchange them the other way round). You can not pass function that throws as parameter to function that accepts another function that can not throw. Function that can not throw is like a subtype of function that can throw. According to Liskov substitution principle. You can replace subtype by it's base type but you can not replace base type by it's subtype.

Also there is least known rethrows keyword.

func doSomeRethrow(f: () throws ->()) rethrows -> ()

You use it when you accept function that throws as argument for you function. If you pass something that can throw than your function will also throw. If you pass something that can not throw, complier will notice that and will presume that your function can not throw eigther. When you mark you function with rethrows you say to compiler that only way you can throw error is if something that you pass as parameter throws. When you mark you function with throws you tell compiler that you can throw mo matter if something you passed as argument throws or not.

Another difference between throws and rethrows is that latter does not create another type of function, it acts more like compiler attribute.

There is another situation when you can rethrow error. If inside your function you call some other function that throws you don't have to handle errors right there, you just call this function with try and if it throws your function will automatically throw the same error.

func anotherMethodThatThrows() throws -> Void {
    try methodThatThrows()
}

do {
    try anotherMethodThatThrows()
}
catch {
    print(error) //will print the same MyError.SomeError
}

The same happens when you use do-catch but your catches are not exhaustive. Error handling is checked at compile time, but you can not specify what types of errors you throw. Compiler though will try to infer that. And if it see that you don't catch all possible errors than you have to mark your function with throws and you will throw all errors that you don't catch.

The same way as optionals has implicitly unwrapped optionals marked with !, you can use try with !:

try! anotherMethodThatThrows()

This will wrap function in runtime assertion that no error should be thrown. If error is actually thrown you will get runtime error. You should use this only in situations when you are sure no error could be thrown at runtime, the same how you should use implicitly unwrapped optionals when you are sure there always will be some value.

In times of Swift 1.x we tend to use Result type. And we could expect that Apple will go the same way as commonity and will make use of Result a standard. But they went another way. Still there is a good use of Result. As mentioned earlier you can not use throwing functions as parameter to other functions that accept function as parameter. Result type can help here.

Let's say you have a simple function like this:

func doSome<T, R>(value: T, body: T -> R) -> R {
    return body(value)
}

doSome("result", body: print)

And you have a throwing print function:

func printOrThrow(t: String) throws -> Void {
    if t.rangeOfString("throw")?.startIndex == nil {
        print(t+"!")
    } else {
        throw MyError.SomeError
    }
}

doSome("result", body: printOrThrow) //Will not work

You can not use printOrThrow where function that does not throw is expected.
Ok then, we can create doSomeThatThrows function that can accept function that can throw and throw if this function throws:

func doSomeThatThrows<T, R>(value: T, body: T throws -> R) throws -> R {
    return try doSome(value, body: { (t) -> R in
        try body(t)
    })
}

But that will not compile 'cause our body closure that we pass to doSome function inside doSomeThatThrows will throw if body throws. That makes this closure type not T -> R but T throws -> R which is not accepted by doSome function.

Here is how we can solve this:

enum Result<T> {
    case Success(T)
    case Failure(ErrorType)
}

extension Result {
    func value() throws -> T {
        switch self {
        case .Success(let value): return value
        case .Failure(let err): throw err
        }
    }
    
    init(@noescape f: () throws -> T) {
        do { self = .Success(try f()) }
        catch { self = .Failure(error) }
    }
}

func doSomeThatThrows<T, R>(value: T, body: T throws -> R) throws -> R {
    return try doSome(value) { (t) -> Result<R> in
        Result {try body(t)}
    }.value()
}

Here we define familiar Result. We extend it to have initializer that accepts throwing function. If this function does not throw, we create .Success result. But if it throws we catch the error and create .Failure result. Using value() throws -> T function we can unwrap result if it is .Success or throw underlying error if it is .Failure. Using this Result type we can pass doSome function a closure that will return not R type but Result<R>. Now doSome itself returns Result<R>, so try to unwrap it's value and return result. So when value will be called it will either return unwrapped value or throw error which was thrown by body closure. Now we can easily use doSomeThatThrows like this:

do {
    try doSomeThatThrows("result", body: printOrThrow)
}
catch {
    print(error)
}

The other case where error handling does not play well is asynchronous code. Say you have some asynchronous function that accepts callback closure as parameter:

func doAsync<T>(value: T, callback: (T) -> Void) {
    dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0)) { () -> Void in
        callback(value)
    }
}

You can not pass function that throws as a callback here. So you create another function:

func doAsyncThatThrows<T>(value: T, callback: (T) throws -> Void) {
    doAsync(value, callback: { t in
        try callback(t)
    })
}

This will not compile cause closure you try to pass to doAsync throws. And of course you can not make this function throw 'cause you can throw only when callback is called but you will already return from this function.
The only thing you can do here is to handle errors right away:

func doAsyncThatThrows<T>(value: T, callback: (T) throws -> Void) {
    doAsync(value, callback: { t in
        do {
            try callback(t)
        } catch {
            print(error)
        }
    })
}

To make things more flexible you can extend this method to accept optional failure closure like this:

func doThis(callback: () throws -> Void, ifThrows failure:(ErrorType) -> Void) {
    do { try callback() }
    catch { failure(error) }
}

func doAsyncThatThrows<T>(value: T, callback: (T) throws -> Void, ifThrows failure: ((ErrorType) -> Void)? = nil) {
    doAsync(value, callback: { t in
        doThis({ try callback(t) }) { failure?($0) }
    })
}

doAsyncThatThrows("result", callback: printOrThrow)
doAsyncThatThrows("throw", callback: printOrThrow){print($0)}

Last two things to say about errors are how Objective-C APIs are mapped to new error handling and how you can create your own errors. If in Objective-C you have a method that accepts NSError in-out parameter this method is exposed to Swift 2 as method that throws and has one less parameter. And NSError conforms to ErrorType.

As you saw previously you can create your own errors using enum that conforms to ErrorType. This protocol is defined as empty (if fact it's empty only publically) so you don't have to do anything to confrom to it. You can also throw NSError. But you can also use structs and classes as errors. For that you need to implement some, for some reason private, properties.

struct Error: ErrorType {
    // Required by ErrorType, but private
    var _domain: String {return "com.wire"}
    var _code: Int {return 0}
    
    // Custom fields
    var reason: String
    var source: String
    
    init(_ reason: String,
        source: String = __FUNCTION__ ,
        file: String = __FILE__ ,
        line: Int = __LINE__ ) {
            self.reason = reason
            self.source = "Thrown in \(source) (File: \(file) Line: \(line))"
    }
}

Used resources:

Swift interesting features

Sun, 19 Apr 2015 12:05:41 GMT

or What Swift Language Guide do not tell you.

This post contains the list of interesting features of Swift that I find while using it. To make it more interactive I've put it in a playground that you can checkout here. The list is intended to be updated in future. If you have something you want to share, pull requests are welcome.

Contents:

Var in for-in loop
Property observers for local variables
~= operator
Curried functions
Subscript with more than one parameter (by AirspeedVelocity)

Var in for-in loop

If you have an array of reference type objects you can mutate them in a loop just by adding var before loop variable. This will work only for reference types as value types are copied on assignment and so the items in array will be not modified. If you have value types though you will be able to modify loop variable inside the loop. It will work pretty much like mutable function arguments.

    // Value type
    var valuesArray = [1, 2, 3]
    for (var valueItem) in valuesArray {
        ++valueItem // 2, 3, 4
    }
    valuesArray // 1, 2, 3
    
    // Reference type
    class Box {
        var value: Int
        init(_ value:Int) {
            self.value = value
        }
    }
    
    var objectsArray = [Box(1), Box(2), Box(3)]
    for (var item) in objectsArray {
        ++item.value // 2, 3, 4
    }
    objectsArray // 2, 3, 4

####Property observers for local variables

This does not work in plyagrounds but give it a try in a real project and you will see "Will set 1" and "Did set 1":

    func method() {
        
        var some: Int = 0 {
            willSet {
                print("Will set \(newValue)")
            }
            didSet {
                print("Did set \(some)")
            }
        }
        some = 1
    }
    
    method()

`~=` operator

This is an expression matching operator. This is what switch statement uses for pattern matching. Outside switch you can use it i.e to find out if Range contains value.

    let some = 1
    if 0...5 ~= some {
        print("\(some) is between 0 and 5")
    }

You can even override this operator like any other to crate some crazy things. For more information check out docs.

    typealias Age = UInt
    
    enum Gender {
        case Male
        case Female
    }
    
    class Person {
        
        var name: String
        var age: Age
        var gender: Gender
        
        init(_ name: String, age: Age, gender: Gender) {
            self.name = name
            self.age = age
            self.gender = gender
        }
    
    }
    
    func ==(lhs: Person, rhs: Person) -> Bool {
        return lhs.name == rhs.name && lhs.age == rhs.age && lhs.gender == rhs.gender
    }
    
    let Ilya = Person("Ilya", age: 28, gender: .Male)
    let Marina = Person("Marina", age: 27, gender: .Female)
    let me = Ilya
    
    func ~=(pattern: Person, value: Person) -> Bool {
        return pattern == value
    }
    
    switch me {
    case Ilya:
        print("Hi, man!")
    case Marina:
        print("Hi, gorgeous!")
    default: break
    }
    
    func ~=(pattern:Range<Age>, value: Person) -> Bool {
        return pattern ~= value.age
    }
    
    switch me {
    case 0...18:
        print("You are too young for that")
    case 18..<UInt.max:
        print("Do what ever you want")
    default: break
    }

Unfortunatelly complier will not let you to match your class against tuple or enum, which would be cool. But you can still use ~= directly if you define it with tuple or enum as a pattern to match. To make it better swap right and left hand statements. This can be fun but I don't see very good usecases for that.

    func ~=(pattern: Person, value: Gender) -> Bool {
        return pattern.gender == value
    }
    
    switch me {
    case _ where me ~= .Male:
        print("Hi, man!")
    case _ where me ~= .Female:
        print("Hi, gorgeous!")
    default: break
    }

####Curried functions

Instance methods in Swift are actually curried functions. You can store it in variable and apply to different instances. Checkout this post by Ole Begemann for one of use cases for that feature.

    extension Person {
        
        func growOlder(years: Age) {
            self.age += years
        }
        
    }
    
    let growOlder = Person.growOlder
    growOlder(Ilya)(5)
    growOlder(Marina)(5)

####Subscript with multiple parameters (by AirspeedVelocity)

Did you know that you can provide more than one parameter to subscript? Also ++ will not just change returned value but will also write it back to that subscript. It's possible because subscript parameters are inout.

    extension Dictionary {
        subscript(key: Key, or or: Value) -> Value {
            get {
                return self[key] ?? or
            }
            set {
                self[key] = newValue
            }
        }
    }
    
    var dict = ["a": 1]
    dict["a"]?++ // 1
    dict // ["a": 2]
    
    dict["b"]?++ // nil
    dict // ["a": 2]
    
    dict["c", or: 3]++ // 3
    dict // ["c": 4, "a": 2]

Custom UITextView in Swift

Sat, 04 Apr 2015 14:30:00 GMT

In this article I want to describe how I developed custom UITextView component in Swift using TextKit, Playgrounds and IBDesignable and IBInspectable directives. You can check out source code on github.

In this component we will add "read more" behaviour to text view. It will have two modes - full mode and trimmed mode. In full mode it will behave like standard UITextView. In trimmed mode it will trim text to some maximum numbers of lines and trim text with a string (like "Read more"). When user taps on "Read more" the component will switch from trimmed mode to full mode.

Creating playgroud

As I said earlier we will develop this component directly in Swift Playgroud. In Playgrouds we can render any view in Assistant Editor with help of XCPlayground module and it's XCPShowView function. To make it work we need to open playground's File Inspector (⌥-⌘-1). In File Inspector in Playground Settings we should check "Run in Full Simulator". Now hide File Inspector (⌥-⌘-0) and open Assistant Editor (⌥-⌘-⏎).

Recently I wrote a small overview about using this feature of playgrounds.

Creating main view

To display something in Assistant Editor we will create a main view. Let's define a function that will create and return this view.

func createView() -> UIView {
    let view = UIView(frame: UIScreen.mainScreen().bounds)
    view.backgroundColor = UIColor.greenColor()
    return view
}

Now we can display this view in Assistant Editor:

import UIKit
import XCPlayground

func createView() -> UIView {
...
}

XCPShowView("view", createView())

Here is what you should see:

Component's interface

As mentioned earlier we want our component to have maximum number of lines in trimmed mode and a string to trim text. Also we will add a flag to turn trimming on and off. So let's define some basic interface for our component:

class ReadMoreTextView: UITextView {

    var maximumNumberOfLines: Int = 0
    var trimText: NSString?
    var shouldTrim: Bool = false

}

Changing any of these properties should cause our text view to update it's layout so we need to add property observers for them:

var maximumNumberOfLines: Int = 0 {
    didSet { setNeedsLayout() }
}

var trimText: NSString? {
    didSet { setNeedsLayout() }
}

var shouldTrim: Bool = false {
    didSet { setNeedsLayout() }
}

func needsTrim() -> Bool {
    return shouldTrim && trimText != nil
}

override func layoutSubviews() {
    super.layoutSubviews()
    needsTrim() ? updateText() : resetText()
}

func updateText() {
    //update text view
}

func resetText() {
    //reset text view
}

Adding component to main view

To continue we need to see how our text view is rendered so we need to add it to our main view that is displayed in Assistant Editor. We can modify createView function to accept text view as it's argument and to add it on screen:

func createView(textView: TextView) -> UIView {

    let view = UIView(frame: UIScreen.mainScreen().bounds)
    view.backgroundColor = UIColor.greenColor()
    view.addSubview(textView)
    let metrics = ["padding": 20]

    view.addConstraints(NSLayoutConstraint
        .constraintsWithVisualFormat("V:|-padding-[textView]-padding-|", options: nil,
            metrics: metrics,
            views: ["textView": textView]))

    view.addConstraints(NSLayoutConstraint
    .constraintsWithVisualFormat("H:|-padding-[textView]-padding-|", options: nil,
        metrics: metrics,
        views: ["textView": textView]))

    return view
}

let textView = ReadMoreTextView()

textView.text = "Lorem ipsum dolor sit er elit lamet, consectetaur cillium adipisicing pecu, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Nam liber te conscient to factor tum poen legum odioque civiuda."

textView.maximumNumberOfLines = 3
textView.shouldTrim = true
textView.trimText = "Read more"

XCPShowView("view", createView(textView))

Extending TextKit

To trim text we need first find the range of text that fits to maximumNumberOfLines. To do so we will use TextKit. UITextView already uses it to render it's text on screen and has built in components like text container, text storage and layout manager. I will not go through details of TextKit, for more details on TextKit check out objc.io or documentation.

In NSLayoutManager's extention we will define two simple helper functions: first to find characters range that fits in text container and second to find bounding rectangle of characters range:

extension NSLayoutManager {

    func characterRangeThatFits(textContainer: NSTextContainer) -> NSRange {
        var rangeThatFits = self.glyphRangeForTextContainer(textContainer)
        rangeThatFits = self.characterRangeForGlyphRange(rangeThatFits, actualGlyphRange: nil)
        return rangeThatFits
    }

    func boundingRectForCharacterRange(range: NSRange, inTextContainer textContainer: NSTextContainer) -> CGRect {
        let glyphRange = self.glyphRangeForCharacterRange(range, actualCharacterRange: nil)
        let boundingRect = self.boundingRectForGlyphRange(glyphRange, inTextContainer: textContainer)
        return boundingRect
    }
}

Trimming text

Before updating text and trimming it we need to make sure that we can restore text view to it's full state when text should not be trimmed. For that we will store text and attributed text in private properties:

private var originalText: String!

override var text: String! {
    didSet {
        originalText = text
        originalAttributedText = nil
        if needsTrim() { updateText() }
    }
}

private var originalAttributedText: NSAttributedString!

override var attributedText: NSAttributedString! {
    didSet {
        originalAttributedText = attributedText
        originalText = nil
        if needsTrim() { updateText() }
    }
}

When we does not need to trim text we reset text view to full mode and restore it's text:

func resetText() {
    textContainer.maximumNumberOfLines = 0
    if originalText != nil {
        textStorage.replaceCharactersInRange(NSMakeRange(0, countElements(text!)), withString: originalText)
    }
    else if originalAttributedText != nil {
        textStorage.replaceCharactersInRange(NSMakeRange(0, countElements(text!)), withAttributedString: originalAttributedText)
    }
}

Next we add function to find range of text to replace with "Read more":

private func rangeToReplaceWithTrimText() -> NSRange {
    let emptyRange = NSMakeRange(NSNotFound, 0)

    var rangeToReplace = layoutManager.characterRangeThatFits(textContainer)
    if NSMaxRange(rangeToReplace) == originalTextLength() {
        rangeToReplace = emptyRange
    }
    else {
        rangeToReplace.location = NSMaxRange(rangeToReplace) - trimText!.length - 4
        if rangeToReplace.location < 0 {
            rangeToReplace = emptyRange
        }
        else {
            rangeToReplace.length = textStorage.length - rangeToReplace.location
        }
    }
    return rangeToReplace
}

private var _originalTextLength: Int {
    get {
        if originalText != nil {
            return countElements(originalText!)
        }
        else if originalAttributedText != nil {
            return originalAttributedText!.length
        }
        return 0
    }
}

Here we increase range by 4 to be able to add "... " as a prefix for trim text later. If we don't need to trim text eigther if we have too small text or too big maximumNumberOfLines then we return empty range.

Finally let's add code that will trim text:

func updateText() {
    textContainer.maximumNumberOfLines = maximumNumberOfLines
    layoutManager.invalidateLayoutForCharacterRange(layoutManager.characterRangeThatFits(textContainer), actualCharacterRange: nil)
    textContainer.size = CGSizeMake(bounds.size.width, CGFloat.max)

    var range = rangeToReplaceWithTrimText()
    if range.location != NSNotFound {
        textStorage.replaceCharactersInRange(range, withString: "... ".stringByAppendingString(trimText!))
    }
    invalidateIntrinsicContentSize()
}

First we set maximum number of lines in text container and it's size so that bounding rectange of this text container will have the width of text view and unlimited height. We also have to invalidate layout information to properly calculate the range of text to trim. Then we find the range that we should replace with "Read more" text and if it's not empty we replace text in this range with trimText prefixed by "... "

Autolayout

When text view is in trim mode it needs to wrap it's content and become smaller than in full mode. To do so we need to redefine it's intrinsic content size.

override func intrinsicContentSize() -> CGSize {
    textContainer.size = CGSizeMake(bounds.size.width, CGFloat.max)
    var intrinsicContentSize = layoutManager.boundingRectForGlyphRange(layoutManager.glyphRangeForTextContainer(textContainer), inTextContainer: textContainer).size
    intrinsicContentSize.width = UIViewNoIntrinsicMetric
    intrinsicContentSize.height += (textContainerInset.top + textContainerInset.bottom)
    return intrinsicContentSize
}

First we set text container's size, again unlimited by height, then we find bounding rect for all text in this text container and take it's size. We don't need intrinsic size on width, so we set it to UIViewNoIntrinsicMetric. And we increase height by top and bottom insets of text container.

Aslo we need to update vertical constraints in createView and invalidate intrinsic size:

func updateText() {
    ...
    invalidateIntrinsicContentSize()
}

func resetText() {
    ...
    invalidateIntrinsicContentSize()
}

...

func createView(textView: UITextView) -> UIView {
    ...
    view.addConstraints(NSLayoutConstraint
        .constraintsWithVisualFormat("V:|-padding-[textView]-(>=padding)-|",
            options: nil,
            metrics: metrics,
            views: ["textView": textView]))
    ...
}

Initialization

Though we've done everything we need to make our text view work properly if you look now in Assistant Editor you will probably see something like this:

This is defenetly not what we want. It turns out that to fix that we need to disable scrolling and editing in our text view.
Now everything should work as expected and you should see something like this:

Handling taps

Next we want our text view to switch it's state to full mode if we tap on "Read more" text. To do that we can check the point we tapped in hitTest function and reset to full mode if we need.

We need a function that will check if point is in range of trimText:

var trimTextRangePadding: UIEdgeInsets = UIEdgeInsetsZero

private func pointInTrimTextRange(point: CGPoint) -> Bool {
    let offset = CGPointMake(textContainerInset.left, textContainerInset.top)
    var boundingRect = layoutManager.boundingRectForCharacterRange(trimTextRange(), inTextContainer: textContainer, textContainerOffset: offset)
    boundingRect = CGRectOffset(boundingRect, textContainerInset.left, textContainerInset.top)
    boundingRect = CGRectInset(boundingRect, -(trimTextRangePadding.left + trimTextRangePadding.right), -(trimTextRangePadding.top + trimTextRangePadding.bottom))
    return CGRectContainsPoint(boundingRect, point)
}

Here we use a new property to define padding around trimText bounding rect in which we will handle taps.

Now we can implement our hitTest function:

public override func touchesEnded(touches: Set<UITouch>, withEvent event: UIEvent?) {
    guard let point = touches.first?.locationInView(self) else { return }

    if needsTrim() && pointInTrimTextRange(point) {
        maximumNumberOfLines = 0
        shouldTrim = false
    }
}

Note: originally I've made a mistake doing that in hitTest method. The thing is that this method may be called by the system several times during handling of a single touch event. Thus this method should not have any side effects.

Interface Builder

This is the easiest part 'cause all we need to make our component to update in Interface Builder and to set it's properties in Attributes Inspector is to add @IBDesignable and @IBInspectable directives. We don't need to define prepareForInterfaceBuilder 'cause when we change maximumNumberOfLines or other properties we make layout update.

@IBDesignable
class ReadMoreTextView: UITextView {

    @IBInspectable
    var maximumNumberOfLines: Int = 0

    @IBInspectable
    var trimText: NSString?

    @IBInspectable
    var shouldTrim: Bool = false

    ...
}

Conclusion

We have developed custom text view in Swift and we used TextKit functionality for that. You can easily extend this component to add for example attributed trim text property so user can customize it's appearance. Also you might see how it's possible to develop components just in playgrounds. After you finished you can move all the code of your component in separate source file and import it to your project. Thought playgrounds lack interactivity (i.e. you can not recieve touch events from Assistant Editor) and some times don't update fast still lots of things could be done just in playgrounds with no need to create and setup whole new project.

Source code for this article is available on github.

Quick overview of Swift Playgrounds in iOS Simulator

Mon, 16 Mar 2015 21:36:49 GMT

Probably lately you've seen few posts on this subject like this or that. Both of described techiques share the same secret - how playground is run in Simulator. Actually it's quite easy, but not obviouse as all windows needed for that are hidden by default - you just need to open up File Inspector for your playground file, select iOS platform and check "Run in Full Simulator". This will run iOS simulator and run your playground almost like ordinary application.

But this techniques differ in a way they present "interactivity" of playgrounds. The latter uses XCPlayground framework to render views directly in timeline. This can be usefull for fast prototyping of views and animations.
The former renders playground in iOS simulator and actually let you interact with it using touch events. It uses CFRunLoopRun() to start run loop and make app alive and responsive. I find this more powerfull - you can prototype not only views and animations but the whole screens, transitions and many other things that you can do in real application. All you need is just a boilerplate code for window setup, which you can place in snippet. I've created basic gist to demonstrate that technique.

Both of these techniques are still very unstable (just like playgrounds in general), they break often, restart slowly and have issues. But it's very interesting opportunity for experiments. Maybe there will be time when we always will start developing new features in playgrounds.

Info.plist preprocessing

Sat, 13 Dec 2014 21:13:19 GMT

This is quiet interesting XCode feature I was not aware of until last week. Maybe you will find it not so interesting and definitely will not use this on everyday basis but sometimes it can be helpfull. For example it can be convenient for separation of production and test configurations (some of them).

In project Build settings you can find section called "Packaging" and there are several keys we are interested in:

Preprocess Info.plist File (INFOPLIST_PREPROCESS)
Info.plist Preprocessor Prefix File (INFOPLIST_PREFIX_HEADER)
Info.plist Preprocessor Definitions (INFOPLIST_PREPROCESSOR_DEFINITIONS)

To enable Info.plist preprocessing INFOPLIST_PREPROCESS setting should be set to YES (default value is NO).
In INFOPLIST_PREFIX_HEADER setting you can specify path to files that would be used during preprocessing. I recommend to name these files something like InfoPlistPrefix.Debug.h and InfoPlistPrefix.Release.h. So this setting value will look like this:

$(PROJECT_DIR)/$(PROJECT_NAME)/Supporting Files/InfoPlistPrefix.$(CONFIGURATION).h

In these files you can define preprocessor macros:

//InfoPlistPrefix.Debug.h
#define COPYRIGHT $(CONFIGURATION) build __DATE__  __TIME__.

//InfoPlistPrefix.Release.h
#define COPYRIGHT Copyright (c) 2014.

Now you can use this macros as a value for a key in Info.plist (i.e. NSHumanReadableCopyright) and during preprocessing it will be replaced by what you've defined:

<key>NSHumanReadableCopyright</key>
<string>COPYRIGHT</string>

The same can be achieved using INFOPLIST_PREPROCESSOR_DEFINITIONS but I prefer using prefix files cause it's more readable and clear.

Using this feature is metter of taste because you can achieve the same results using #ifdef in your code or declaring custom preprocessor macros in Build Settings directly. As for me build settings are for configuring build process. I.e. you can define there app bundle identifier suffix and reference to it in Info.plist. As for Info.plist it is a place for configuring your application, how it looks and behaves.

Here is one use case that can be arguable - should you place logging level settings in Info.plist. Info.plist can be read and changed even without jailbreak. So user can change your logging level and read all your logs (i.e. API requests). If it's something you don't want to happen use Build Settings so that logging behaviour would be defined at compile time, not at runtime. For the same reason never put any private data like your social app keys and secrets in Info.plist.

And don't forget to clean project after making changes in Info.plist prefix files or Info.plist preprocessor definitions.

iOS storyboards segregation

Mon, 08 Dec 2014 00:07:57 GMT

Recently here at Rambler&Co mobile team we decided to try technique of storyboards segregation (separation in other words). We came to the conclusion that this simple technique together with other techniques we use can help us to improve our's projects architecture, code readability and stability. Here is what we came up with.

Many techniques of applications development are based on user stories (or use cases), in short - small logically connected pieces of functionality that application provides to user. Developers too also use the term of 'use cases' in application architecture design. So why not to use this concept to devide one massive storyboard in smaller pieces?

Usually if you are using storyboards in your project you may have at least one storyboard. If you have relatively simple project with few screens and transitions it is just fine - most likely you will also have very few user stories. But if you have some kind of large project with lots of different screens (e.g. Afisha-Restaurants) and possible segues among them then separating your single storyboard in several smaller storyboards can help you to maintain your code (by maintaining I mean i.e. merging storyboards) and to be clear about what transitions you have and where they point.

To go from one storyboard to another we need some special segue. What our cross-storyboard segue should do is to substitute it's destination view controller that it get's when segue is created by UIKit with some other view controller from another storyboard. First we must decide how our segue will know where to get it's destination view controller from. There are two ways. One is to include this information in segue itself, right in it's identifier. Another is to include this information in destination view controller using some placeholder in place of view controller in source storyboard. First one is fairly simple and fully described in linked blog post. We will go the second way cause I like it more than tying up with segue identifiers. And we will use the power of Objective-C runtime.

To make our view controllers hold information about thier storyboards and thier storyboard identifiers we create a category of UIViewController that will add two properties - storyboardName and storyboardIdentifier. The first should match actual name of storyboard that contains view controller. The second should match view controller's storyboard ID from view controller's identity inspector (UIViewController does not provide such property from the box, so we have to duplicate it).

@interface UIViewController (Storyboards)

@property (nonatomic, copy) IBInspectable NSString *storyboardName;
@property (nonatomic, copy) IBInspectable NSString *storyboardIdentifier;

@end

The IBInspectable keyword will let us set this properties right in Interface Builder. In fact what this keyword does is just adding input fields for corresponding properties to attributes inspector. But you can (and always could) do the same using plane old runtime attributes in identity inspector. IBInspectable-marked properties will be automatically detected by Interface Builder no matter where they are declared.

Also we will add convenient method to create view controllers using this two properties:

+ (instancetype)viewControllerFromStoryboardWithName:(NSString *)storyboardName withStoryboardIdentifier:(NSString *)storyboardIdentifier;

Implementation looks like this:

#import <objc/runtime.h>

@implementation UIViewController (Storyboards)

- (NSString *)storyboardName
{
    return objc_getAssociatedObject(self, @selector(storyboardName));
}

- (void)setStoryboardName:(NSString *)storyboardName
{
    objc_setAssociatedObject(self, @selector(storyboardName), storyboardName, OBJC_ASSOCIATION_COPY_NONATOMIC);
}

- (NSString *)storyboardIdentifier
{
    return objc_getAssociatedObject(self, @selector(storyboardIdentifier));
}

- (void)setStoryboardIdentifier:(NSString *)storyboardIdentifier
{
    objc_setAssociatedObject(self, @selector(storyboardIdentifier), storyboardIdentifier, OBJC_ASSOCIATION_COPY_NONATOMIC);
}

+ (instancetype)viewControllerFromStoryboardWithName:(NSString *)storyboardName withStoryboardIdentifier:(NSString *)storyboardIdentifier
{
    if (storyboardName.length > 0 && storyboardIdentifier.length > 0) {
        UIStoryboard *storyboard = [UIStoryboard storyboardWithName:storyboardName bundle:nil];
        if (storyboard) {
            return [storyboard instantiateViewControllerWithIdentifier:storyboardIdentifier];
        }
    }
    return nil;
}

@end

Really no need for comments (if you need read this NSHipster blog post for associated objects reference).

Now let's implement our "magic" segue. We can do this by subclassing UIStoryboardSegue but then we will have to create subclasses for every kind of presentation we use. Instead we will use method swizzling (I will no go into details of swizzling, check out this NSHipster blog post for reference). With this code even your custom segues will work with view controllers from other storyboards with no need to modify segue code.

//interface
@interface UIStoryboardSegue (Storyboards)

@end

//implementation
#include "UIViewController+Storyboards.h"
#import "NSObject+Swizzling.h"

@implementation UIStoryboardSegue (Storyboards)

+ (void)load
{
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        //Using NSObject category that actually performs swizzling
        [self swizzleSelector:@selector(initWithIdentifier:source:destination:) withSelector:@selector(storyboards_initWithIdentifier:source:destination:)];
    });
}

- (instancetype)storyboards_initWithIdentifier:(NSString *)identifier source:(UIViewController *)source destination:(UIViewController *)destination
{
    return [self storyboards_initWithIdentifier:identifier source:source destination:[self destinationWithDestination:destination]];
}

- (UIViewController *)destinationWithDestination:(UIViewController *)destination
{
    UIViewController *newDestination = [UIViewController viewControllerFromStoryboardWithName:destination.storyboardName withStoryboardIdentifier:destination.storyboardIdentifier];
    return newDestination?:destination;
}

@end

That's all with code for now. Now let's see how to use this in the project.

In your main storyboard select view controller(s) you want to separate to other storyboard. Create new storyboard and move selected controllers there.
In original storyboard leave the first of selected view controllers which will correspond to initial view controller of newly created storyboard. Now remove it's view - you just does not need it here any more cause you now have it in other storyboard. Now we have a placeholder for real view controller that will be loaded from other storyboard.
Set storyboardName and storyboardIdentifier for this placeholder.

Remember that storyboard name should be the name of storyboard to load view controller and storyboard identifier should match one of this storyboard view controllers' stroyboard IDs (I always recommend to use view controller's class name for storyboard ID).

And you are done. When segue will be performed view controller will be loaded from storyboard with provided name. It can be any view controller in the storyboard, not necessarily initial view controller.

Of course this technique has some disadvantages and side effects you should concider. For example -(id)initWithCoder: and -(void)awakeFromNib will be called twice for controllers that are used in two different storyboards. Wherein -(void)viewDidLoad is called once. You can get rid of this by setting base class to UIViewController for this controllers' placeholders. Anyway two controllers will be instantiated but at least this will not call your own code twice.
You can also consider for yourself using runtime as disadvantage. Than you can use subclassing.

One more thing that should be mentioned is what if we have UINavigationController or UITabBarController (and likely UISplitViewController too)? For instance UITabBarController's child view controllers are set in storyboards using relationships, not segues and we can not customize relationships. So if you want to devide your storyboard by tab bar items you have a problem. But it's easy to fix using what we have done already. Remember we added convenient method in our UIViewController category that can create view controllers using storyboard name and storyboard identifier? Let's use it. Also we will need some method swizzling again. If you prefer not to use method swizzling you can create subclass or user other techniques, like dependecy injection, but for me it's too much for this simple task.

Let's add UITabBarController category and swizzle it's -(void)awakeFromNib method (it will look absolutelly the same way for UINavigationController and actually as far as UITabBarController and UINavigationController does not override UIViewController's implementation of -awakeFromNib we can swizzle this method just in UIViewController). When this method is called viewControllers property of the instance is already set and all view controllers in this array already has their custom storyboardName and storyboardIdentifier properties set.

//interface
@interface UITabBarController(Storyboards)

@end

//implementation
#import "NSObject+Swizzling.h"

@implementation UITabBarController(Storyboards)

+ (void)load
{
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{
        [self swizzleSelector:@selector(awakeFromNib) withSelector:@selector(storyboards_awakeFromNib)];
    });
}

- (void)storyboards_awakeFromNib
{
    [self storyboards_awakeFromNib];

    NSMutableArray *viewControllers = [self.viewControllers mutableCopy];
    [self.viewControllers enumerateObjectsUsingBlock:^(UIViewController *vc, NSUInteger idx, BOOL *stop) {
        UIViewController *newVC = [UIViewController viewControllerFromStoryboardWithName:vc.storyboardName withStoryboardIdentifier:vc.storyboardIdentifier];
        if (newVC) {
            [viewControllers replaceObjectAtIndex:idx withObject:newVC];
        }
    }];
    [self setViewControllers:viewControllers];
}

@end

Here we replace view controllers from viewControllers property with view controllers loaded from other storyboards.
Now if you have UITabBarController as your root view controller your initial storyboard can contain just this controller and placeholders for it's child view controllers.

As a result all we have to do to separate storyboards is to set storyboard names and storyboard identifiers for some of our view controllers. With little efforts we are now able to maintain and read our storyboards easily and structure our code using cleaner architecture.