DIARIO DE PROGRAMACIÓN

About Phantom Types

Wed, 20 Oct 2021 00:00:00 +0000

Let’s say we have to call an external SDK in order to perform any kind of work. This SDK requires a token, and this token is a String.

So we have a function to call the SDK called:

sdk.work(accessToken: String)

And our design wraps that function into:

work(accessToken: String)

The way to get that token is to call GET: /api/sdk/accessToken, with the following response:

{
    "access_token": "0000"
}
/// mapped to:
struct SDKGetTokenResponse: Decodable {
    let accessToken: String
}

And that’s fine, then X service returns the String and that’s the thing we work with. The String Type. While we’re building this we have enough context to know the String type is returned from the SDKGetToken service and we use it in the work use case.

Maybe this is fine, and compiles and works but the next time we read the work function, two months later, we think, WTF is that string?, where does it come from? We only can follow the flow with the caller’s function, if Xcode wants work that day, but we can’t perform any search over the String type, because we will have tons of strings on our code.

Phantom Types.

A phantom type is a generic type in which implementation we don’t use the generic type:

Encode information about how and where a value can be used
Help us to provide more information on function signatures

Given the previous example, what if instead of having that accessToken as a String we wrap it inside AccessToken ?

{
    "access_token": "0000"
}
/// mapped to:
enum SDK {}

struct GetTokenResponse<SDKName>: Decodable {
    let accessToken: AccessToken<SDKName>
}

struct AccessToken<SDKName> {
    let rawValue: String
}

extension AccessToken: Decodable {
    init(from decoder: Decoder) throws {
        let container = try decoder.singleValueContainer()
        self.init(rawValue: try container.decode())
    }
}

The function work will look like:

func work(accessToken: AccessToken<SDK>) {
    SDK.work(accessToken.rawValue)
}

Creating the AccessToken structure with a Phantom Type, our code is more concise, reading the type we know what it is, and we can perform a global search to know where it comes from, where it is used, etc.

Even if we’re using more than one SDK, all that we need to do to extend our code is to create another SDKName enum and our work is done:

{
    "access_token": "0000"
}
/// mapped to:
enum SDK {}
enum AnotherSDK {}

struct GetTokenResponse<SDKName>: Decodable {
    let accessToken: AccessToken<SDKName>

    enum CodingKeys: String, CodingKey {
        case accessToken = "access_token"
    }

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

struct AccessToken<SDKName> {
    let rawValue: String
}

func work(accessToken: AccessToken<SDK>) {
    SDK.work(accessToken.rawValue)
}


func anotherWork(accessToken: AccessToken<AnotherSDK>) {
    AnotherSDK.work(accessToken.rawValue)
}

For testing, we can extend that type with a static let stub to perform asserts with the dot notation, and only one option will be available, instead of having a lot of values inside String type.

But our code will be so conscious that we won’t be able to compare two AccessToken if our SDKName generic type doesn’t match.

About Arithmetic Expressions

Sat, 27 Feb 2021 00:00:00 +0000

Some days ago I watched this episode from PointFree , and I wanted to come over with a couple of exercises playing with the arithmetic expression of the exercise.

Decomposing the expresion to the minimum value

As other posts I wrote, we’re going to start decomposing an arithmetic expression to the minimum value. This is the most important step on FPP, where we work composing little functions into higher systems. Like we saw on the validators post, to build model validators we start decomposing the validator to the most simple expression and then start to grouping them into a bigger ones.

So, what is the most simple expression inside an arithmetic operation like 2 + 2? The number. The most simple expression is the way to provide a number, and over it, we will build everything.

The functional way

() -> Int

Now that we have identified what is the most simple expression to start to work on, we can build an expression based on it. Let’s write an example.

typealias Expression = () -> Int

let two: Expression = { 2 }
let operation: Expression =  { two() + two() }

As we saw, a function that returns a number can wrap the most basic expression, give us a number, and the add operation. But to be honest, this is far from been usable. So, like other times, let’s wrap that function inside a type. Wrapping functions inside types allow us to add functionality to the type while the base work of our functions still keeps simple.

struct Expression {
  let run: () -> Int
}

let two = Expression { 2 }
let operation = Expression { two.run() + two.run() }

Still far from been usable. We are building the add operation inside the expression, but we could improve the design naming inside Expression the add operation.

struct Expression {
  let run: () -> Int
}

extension Expression {
  func add(_ expression: Expression) -> Expression {
    .init { self.run() + expression.run() }
  }
}

let two = Expression { 2 }
let operation = two.add(two)

And like the add, we are going to add the substract function.

struct Expression {
  let run: () -> Int
}

extension Expression {
  func add(_ expression: Expression) -> Expression {
    .init { self.run() + expression.run() }
  }
  
  func sub(_ expression: Expression) -> Expression {
    .init { self.run() - expression.run() }
  }
}

let two = Expression { 2 }
let operation = two.add(two).sub(two)

And we can extend the Expression type to allow as many operations as we want. But what if we want to work with other type of values instead only Int. We can make it generic.

struct Expression<Value> {
  let run: () -> Value
}

extension Expression where Value == Int {
  func add(_ expression: Expression) -> Expression {
    .init { self.run() + expression.run() }
  }
  
  func sub(_ expression: Expression) -> Expression {
    .init { self.run() - expression.run() }
  }
}

let two = Expression { 2 }
let operation = two.add(two).sub(two)

At this point, Expression is built, and let us extend it with more operations without too much efforrt and we can limit those extensions bassed on the type of the Expression.

What if we want to print the built expression? (like 2+2)

At this point, we find that our model doesn’t allow it. Our model has coupled how we build the model and how the model works. This means we’re coupling our model with his interpretation. Being the interpretation the way of our model behaves.

So, how can we fix it?

The enum choice.

The model proposed by point free on the (chapter)[https://www.pointfree.co/episodes/ep26-domain-specific-languages-part-1] split the model from the interpretation, building only the expression based on the operations, but not applying any logic to it.

It starts with from the same point, what is the most simple expression inside 2 + 2?. The Int value, so let’s build a model that allow us to represent it.

enum Expression {
  case value(Int)
}

And then, like we have the value, we can add to our Expression model the operation values. Those operations will be cases of our enum.

enum Expression {
  case value(Int)
  case add
  case sub
}

Our operations are defined, but them still need parameters to work. The paremeters of the operation could be Int, but our model already allow us to express an Int as an Expression, in our .value case. So let’s add the parameters needed for the operations.

indirect enum Expression { // indirect will allow us to have recursive enum cases
  case value(Int)
  case add(Expression, Expression)
  case sub(Expression, Expression)
}

Now we can build up our Expression with add and sub, but also our model let us concatenate more than one operation, because an Expression could be a value or a set of operations wrapped inside it.

let expression: Expression = .add(.value(2), .add(.value(2), .value(2)))

Our model is done. Now is time to execute it. So we can have the next function:

func evaluate(expression: Expression) -> Int {
  switch operation {
    case let .value(value):
        return value
    case let .add(aOP, bOP):
        return evaluate(aOP) + evaluate(bOP)
    case let .sub(aOP, bOP):
        return evaluate(aOP) - evaluate(bOP)
    }
}

Okey, but in a real world, we can’t have a lot of functions spreaded on all our code, so let’s wrap it inside a type. We have to pay speccial attention to evaluate function because is a recursive function, so we will need a way to create a type that will be created with a function that receive is own type as parameter. This is needed to be able to call itself recursively.

struct Runner {
    private let _run: (Runner, Expression) -> Int

    init(_ run: @escaping (Runner, Expression) -> Int) {
        self._run = run
    }

    func run(_ operation: Expression) -> Int {
        _run(self, operation)
    }
}

This way we’re able to have an evaluator runner inside our Runner type with the dot notation available.

extension Runner {
  static let evaluator = Runner { runner, expression in
    switch operation {
    case let .value(value):
        return value
    case let .add(aOP, bOP):
        return runner.run(aOP) + runner.run(bOP)
    case let .sub(aOP, bOP):
        return runner.run(aOP) - runner.run(bOP)
    case let .mul(rExpr, lExpr):
        return runner.run(rExpr) * runner.run(lExpr)
    }
  }
}

Finally, the usage of this is really simple:

let expression: Expression = .add(.value(2), .add(.value(2), .value(2)))
let result = Runner.evaluator.run(expression)

As we have the model interpretation outside wrapped on the Runner type, now we can build another runner that will print the expression instead of evaluating it. Like we want to get an String now instead a number, we need to make the output of our Runner generic.

struct Runner<Output> {
    private let _run: (Runner, Expression) -> Output

    init(_ run: @escaping (Runner, Expression) -> Output) {
        self._run = run
    }

    func run(_ operation: Expression) -> Output {
        _run(self, operation)
    }
}

The generic types doesn’t allow us to have static let inside if we don’t limit the wrapping generic types to concrete ones. So our evaluator runner will looks:

extension Runner where Output == Int {
    static let evaluator = Runner<Int> { runner, operation in
        switch operation {
        case let .value(value):
            return Double(value)
        case let .add(aOP, bOP):
            return runner.run(aOP) + runner.run(bOP)
        case let .sub(aOP, bOP):
            return runner.run(aOP) - runner.run(bOP)
        }
    }
}

With our types already updated, let’s built the printer runner.

extension Runner where Output == String {
  static let printer = Runner<String> { runner, operation in
    switch operation {
    case let .value(value):
        return value
    case let .add(aOP, bOP):
        return "\(runner.run(aOP)) + \(runner.run(bOP))"
    case let .sub(aOP, bOP):
        return "\(runner.run(aOP)) - \(runner.run(bOP))"
    }
  }
}

The usage will be like this.

let expression: Expression = .add(.value(2), .add(.value(2), .value(2)))
let result = Runner.evaluator.run(expression)
let stringResult = Runner.printer.run(expression)

To improve how we run the expressions, we could extend our Expression type a little bit:

extension Expression {
    func evaluated<Output>(by runner: Runner<Output>) -> Output {
        runner.run(self)
    }
}

Now the usage will be.

let expression: Expression = .add(.value(2), .add(.value(2), .value(2)))
let result = expression.evaluated(by: .evaluator)
let stringResult = expression.evaluated(by: .printer)

Another cool improvement we can make is to don’t close the value type of our Expression model to an Int value. So let’s make the .value case generic and update all our components.

indirect enum Expression<Value> {
    case value(Value)
    case add(Expression, Expression)
    case sub(Expression, Expression)
}

struct Runner<Input, Output> {
    private let _run: (Runner<Input, Output>, Expression<Input>) -> Output

    init(_ run: @escaping (Runner<Input, Output>, Expression<Input>) -> Output) {
        self._run = run
    }

    func run(_ operation: Expression<Input>) -> Output {
        _run(self, operation)
    }
}

extension Runner where Input == Int, Output == Double {
    static let evaluatorRunner = Runner<Int, Double> { runner, operation in
        switch operation {
        case let .value(value):
            return Double(value)
        case let .add(aOP, bOP):
            return runner.run(aOP) + runner.run(bOP)
        case let .sub(aOP, bOP):
            return runner.run(aOP) - runner.run(bOP)
        }
    }
}

extension Runner where Input == Int, Output == String {
    static let printRunner = Runner<Int, String> { runner, operation in
        switch operation {
        case let .value(value):
            return "\(value)"
        case let .add(aOP, bOP):
            return "\(runner.run(aOP)) + \(runner.run(bOP))"
        case let .sub(aOP, bOP):
            return "\(runner.run(aOP)) - \(runner.run(bOP))"
        }
    }
}

Now we can build Expressions not only for Int type but also for any other type that we want to work on.

Mapping

Expression has a generic type inside it, this allow us to have the same expressions with different types inside, maybe we even need to transform them. Tranforming an Expression<Int> to Expression<String> could be really simple if we implement high order functions like map operation inside our Expression type.

extension Expression {
    func map<NewValue>(_ transform: (Value) -> NewValue) -> Expression<NewValue> {
        switch self {
        case .value(let value):
            return .value(transform(value))
        case let .add(lExpression, rExpression):
            return .add(lExpression.map(transform), rExpression.map(transform))
        case let .sub(lExpression, rExpression):
            return .sub(lExpression.map(transform), rExpression.map(transform))
        }
    }
}

As you may see, the key point of the map, as on the other functions we’ve built to use oeprations, is the recurisivity on it due to the indirect cases of the enum. We are interating over all the expressions inside the initial expression and only mutate the value case.

Mutating an expression will be like:

let expression: Expression<Int> = .add(.value(2), .add(.value(2), .value(2)))
let stringExpression = expression.map { "\($0)" }

Adding Vars

Like the people from Pointfree does, let’s add the var case. This case allow us to create vars inside our expression that will be suplied by values when evaluating them.

indirect enum Expression { // indirect will allow us to have recursive enum cases
  case value(Int)
  case add(Expression, Expression)
  case sub(Expression, Expression)
  case `var`(String)
}

The Runner object also needs to be update, it needs to receive a Dictionary of String and values, but unlike pointfree, instead of Ints, we will use Expression.

Using expressions as the value of the variables, if you saw the video, will avoid us to implement the bind case.

The bind case was a special case to bind an Expression to a var, but it add complexity and is really unneded if we model the dictionary to have Expressions. Also, thanks to the Runner generic type, we can limit the dictionary Expression to only allow Expressions with the same type.

Finally our code look like:

indirect enum Expression<Value> {
    case value(Value)
    case add(Expression, Expression)
    case sub(Expression, Expression)
    case `var`(String)
}

extension Expression {
    func map<NewValue>(_ transform: (Value) -> NewValue) -> Expression<NewValue> {
        switch self {
        case .value(let value):
            return .value(transform(value))
        case let .add(lExpression, rExpression):
            return .add(lExpression.map(transform), rExpression.map(transform))
        case let .sub(lExpression, rExpression):
            return .sub(lExpression.map(transform), rExpression.map(transform))
        case let .var(key):
            return .var(key)
        }
    }
     
    func evaluate<Output>(_ runner: Runner<Value, Output>, environment: [String: Expression] = [:]) -> Output {
        runner.run(self, environment: environment)
    }
}

struct Runner<Input, Output> {
    private let _run: (Runner<Input, Output>, Expression<Input>, [String: Expression<Input>]) -> Output

    init(_ run: @escaping (Runner<Input, Output>, Expression<Input>, [String: Expression<Input>]) -> Output) {
        self._run = run
    }

    func run(_ operation: Expression<Input>, environment: [String: Expression<Input>] = [:]) -> Output {
        _run(self, operation, environment)
    }
}

extension Runner where Input == Int, Output == Double {
    static let evaluatorRunner = Runner<Int, Double> { runner, operation, environment in
        switch operation {
        case let .value(value):
            return Double(value)
        case let .add(aOP, bOP):
            return runner.run(aOP, environment: environment) + runner.run(bOP, environment: environment)
        case let .sub(aOP, bOP):
            return runner.run(aOP, environment: environment) - runner.run(bOP, environment: environment)
        case let .var(key):
            guard let value = environment[key] else {
                fatalError("Not found Expression for var \(key)")
            }
            return runner.run(value, environment: environment)
        }
    }
}

extension Runner where Input == String, Output == String {
    static let printRunner = Runner<String, String> { runner, operation, environment in
        switch operation {
        case let .value(value):
            return value
        case let .add(aOP, bOP):
            return "\(runner.run(aOP, environment: environment)) + \(runner.run(bOP, environment: environment))"
        case let .sub(aOP, bOP):
            return "\(runner.run(aOP, environment: environment)) - \(runner.run(bOP, environment: environment))"
        case let .var(key):
            guard let value = environment?[key] else {
                fatalError("Not found Expression for var \(key)")
            }
            return runner.run(value, environment: environment)
        }
    }
}

Then use the vars will be:

let expression: Expression<Int> = .add(.var("x"), .value(6))
let result = expression.evaluate(.evaluatorRunner, environment: ["x": .value(2)])

Friendly sintax

The model is working. The interpretation is abstracted from the model creation. That’s okey, but, why if we’re building an expression based on arithmetic operations, don’t we use operators?

In order to do this, we’re going to extend the Expression model to be ExpressibleByIntegerLiteral limited to the Int expression.

extension Expression: ExpressibleByIntegerLiteral where Value == Int {
    init(integerLiteral value: IntegerLiteralType) {
        self = .value(value)
    }
}

To build the .var case, we’re going to implement the ExpressibleByStringLitleral, this has a trade-off that we must consider. We don’t be able to build an Expression<String> from litlerals, because we will use the string literal to build the var case on any type of Expression.

extension Expression: ExpressibleByStringLiteral {
    init(stringLiteral value: StringLiteralType) {
        self = .var(value)
    }
}

And then, we only need to create the operators.

extension Expression {
    static func +(lhs: Expression, rhs: Expression) -> Expression {
        .add(lhs, rhs)
    }
    
    static func -(lhs: Expression, rhs: Expression) -> Expression {
        .sub(lhs, rhs)
    }
}

Now, we can build Expressions like if we are writting code.

let expression: Expression<Int> = 6 + 2 + "x"
let result = expression.evaluate(.evaluatorRunner, environment: ["x": .value(2)])

Conclusion

At the end, all of these ways of coding looks pretty similar. First you have to find what is the minimum expression to your goal, usually that minimum expression will be a function. Then wrap it inside a type, and then extend the type to compose or whatever.

For the functional choice, we’ve started from () -> Int, wrapped it inside a Type. Added a couple of functions inside the type to allow add and sub, and made it generic. I didn’t implements the oeprators and Expressible protocols inside this case, but it could be implemented too like in the enum choice.

On the other hand, for the enum choice, we’ve started from the most simple case .value(Int) and then add the other cases. We’ve created the runner to wrap inside an object how the Expression is interpreted, based on the function (Expression) -> Int. Then we’ve updated it to be generic. Added the .var case with the environment dictionary, and some sugar syntax to write the expressions with operators.

All the code

import Foundation

indirect enum Expression<Value> {
    case value(Value)
    case add(Expression, Expression)
    case sub(Expression, Expression)
    case mul(Expression, Expression)
    case `var`(String)
}

extension Expression {
    func map<NewValue>(_ transform: (Value) -> NewValue) -> Expression<NewValue> {
        switch self {
        case .value(let value):
            return .value(transform(value))
        case let .add(lExpression, rExpression):
            return .add(lExpression.map(transform), rExpression.map(transform))
        case let .sub(lExpression, rExpression):
            return .sub(lExpression.map(transform), rExpression.map(transform))
        case let .mul(lExpression, rExpression):
            return .mul(lExpression.map(transform), rExpression.map(transform))
        case let .var(key):
            return .var(key)
        }
    }
     
    func evaluate<Output>(_ runner: Runner<Value, Output>, environment: [String: Expression]? = nil) -> Output {
        runner.run(self, environment: environment)
    }
}

extension Expression: ExpressibleByIntegerLiteral where Value == Int {
    init(integerLiteral value: IntegerLiteralType) {
        self = .value(value)
    }
}

extension Expression: ExpressibleByStringLiteral {
    init(stringLiteral value: StringLiteralType) {
        self = .var(value)
    }
}

extension Expression {
    static func +(lhs: Expression, rhs: Expression) -> Expression {
        .add(lhs, rhs)
    }
    static func -(lhs: Expression, rhs: Expression) -> Expression {
        .sub(lhs, rhs)
    }
    static func *(lhs: Expression, rhs: Expression) -> Expression {
        .mul(lhs, rhs)
    }
}

struct Runner<Input, Output> {
    private let _run: (Runner<Input, Output>, Expression<Input>, [String: Expression<Input>]?) -> Output

    init(_ run: @escaping (Runner<Input, Output>, Expression<Input>, [String: Expression<Input>]?) -> Output) {
        self._run = run
    }

    func run(_ operation: Expression<Input>, environment: [String: Expression<Input>]? = nil) -> Output {
        _run(self, operation, environment)
    }
}

extension Runner where Input == Int, Output == Double {
    static let evaluatorRunner = Runner<Int, Double> { runner, operation, environment in
        switch operation {
        case let .value(value):
            return Double(value)
        case let .add(aOP, bOP):
            return runner.run(aOP, environment: environment) + runner.run(bOP, environment: environment)
        case let .sub(aOP, bOP):
            return runner.run(aOP, environment: environment) - runner.run(bOP, environment: environment)
        case let .mul(rExpr, lExpr):
            return runner.run(rExpr, environment: environment) * runner.run(lExpr, environment: environment)
        case let .var(key):
            guard let value = environment?[key] else {
                fatalError("Not found Expression for var \(key)")
            }
            return runner.run(value, environment: environment)
        }
    }
}

extension Runner where Input == String, Output == String {
    static let printRunner = Runner<String, String> { runner, operation, environment in
        switch operation {
        case let .value(value):
            return value
        case let .add(aOP, bOP):
            return "\(runner.run(aOP, environment: environment)) + \(runner.run(bOP, environment: environment))"
        case let .sub(aOP, bOP):
            return "\(runner.run(aOP, environment: environment)) - \(runner.run(bOP, environment: environment))"
        case let .mul(rExpr, lExpr):
            return "\(runner.run(rExpr, environment: environment)) * \(runner.run(lExpr, environment: environment))"
        case let .var(key):
            guard let value = environment?[key] else {
                fatalError("Not found Expression for var \(key)")
            }
            return runner.run(value, environment: environment)
        }
    }
}

let expression: Expression<Int> =  6 + 2 + "x"
let result = expression.evaluate(.evaluatorRunner, environment: ["x": .value(2)])

Highly Composable Validators

Sat, 13 Jun 2020 00:00:00 +0000

How many times, we need to validate a form, get usable errors for that validation rules, validate some user data while the user inputs it…

This time we’re going to cover how to build little but composable Validators. We’re going to start decomposing a Validator to is most simple code unit, and then we’ll start to build over that until we build our models validators, and of course, making them easy to test.

So let’s start thinking about what it’s a validator.

The most simple code unit to represent a validator it’s a function that given a value will tell us if the value it’s valid or not. We can represent this like: (Value) -> Bool. This could be our start point.

To make this more understandable, let’s put an example where we have to validate an User. We will need to validate his email, and his phone number (based on spanish rules, 9 digits).

struct User {
    let email: String
    let phone: String 
}

So, with the previous validator unit code, we will have:

let validateEmail: (String) -> Bool = { email in
    email.contains("@")
}

let validatePhone: (String) -> Bool = { phone in
    let numberSet = CharacterSet(charactersIn: "0123456789")
    let phoneSet = CharacterSet(charactersIn: phone)
    return phone.count == 9 && phoneSet.isSubset(of: numberSet)
}

These two functions will return us a boolean if the String is a valid email or phone, obviously this validations are dumb examples.

But now, would be better if we have that funtions wrapped inside an object that validates. So let’s create an object that will validate a value.

struct Validator<Value> {
    private let validation: (Value) -> Bool

    func validate(_ value: Value) -> Bool {
        validation(value)
    }
}

Now that we have a very simple struct to build our Validators, we can start extend it to name those validators and wrap them over Validators of the Value they’re validating.

Then our previous validations functions will be:

extension Validator where Value == String {
    static let emailValidator = Validator<String> { email in
        email.contains("@")
    }

    static let phoneValidator = Validator<String> { phone in
        let numberSet = CharacterSet(charactersIn: "0123456789")
        let phoneSet = CharacterSet(charactersIn: phone)
        return phone.count == 9 && phoneSet.isSubset(of: numberSet)
    }
}

With this simple struct to wrap our validations, now we can use the dot notation to refer our validators, wherever we need use them.

let emailValidator: Validator<String> = .emailValidator

Composing validators

Our validator it’s a type. It’s a type that wraps a function, and thanks to that we can start composing them in a simple way. In order to do this we only need to extend our Validator type and create a function to compose them.

extension Validator {
    static func compose(first: Validator<Value>, second: Validator<Value>) -> Validator<Value> {
        Validator<Value> { value in
            first.validate(value) && second.validate(value)
        }
    }
}

With that simple extension we’re creating a new validator that wraps the previous two validators. This way we can compose more complex Validator based on the simples ones. We keep the testability easy because we can test each simple rule, the compose method, and we avoid to test the composed ones, that will be harder to test.

But we keep with one problem, we only can compose from two to other two, and we’re looking for compose as many as we want. So let’s build a new function to compose a bunch of them.

static func compose(_ validators: Validator<Value>...) -> Validator<Value> {
    guard let first = validators.first else { preconditionFailure("Empty validators") }
    return validators.dropFirst().reduce(first) { compose(first: $0, second: $1) }
}

With that simply function we can compose into one Validator as many validators as we want. The dot notation is still available.

To show how we can use it, let’s create another validator to assert that one string is not empty, and then we will add that validator to the email validator.

extension Validator where Value == String {
    static let containsAt = Validator<String> { string in
        string.contains("@")
    }
    
    static let notEmptyString = Validator<String> { string in
        !string.isEmpty
    }

    // the composed one
    static let emailValidator = Validator<String>.compose(
        .containsAt,
        .notEmptyString
    )
}

As you may see, we’re creating very simple validators with one rule and then composing as many rules as we want to create more complex validators, but at this moment, we have one problem, we can’t know if the validation fails what is the failing rule.

Very inspired on the point free validated I took the Validated object to handle the validated value or the validation error if it fails, but with a little difference, I like that if a validation fails, only return the first error, not all. Because I (this is very personal opinion) don’t like that forms that you start to input one value and all the form starts failing.

So, let’s create the Validated object and the adapt our validator to use it.

enum Validated<Value, Error> {
    case valid(Value)
    case invalid(Error)
}

As you may see, this error is not implementing Swift.Error, because we don’t want to throw anything.

Now that we have the Validated object, let’s update our validator to work with it. The main key of this is to return the first error that we get validating and like we will see, now our validators, validate a type and could give us a ValidationError typed.

struct Validator<Value, Error> {
    let validation: (Value) -> Validated<Value, Error>

    func validate(_ value: Value) -> Validated<Value, Error> {
        validation(value)
    }
}

At this moment, we have to update how our compose functions works.

//The first compose function to wrap two validators into a new one.
private func compose(first: Validator<Value, Error>, second: Validator<Value, Error>) -> Validator<Value, Error> {
    Validator<Value, Error> {
        switch first($0) {
        case .valid(let value): return second(value)
        case .invalid(let error): return .invalid(error)
        }
    }
}

//The second compose function to wrap as many validators as we need into a new one.
static func compose(_ validators: Validator<Value, Error>...) -> Validator<Value, Error> {
    guard let first = validators.first else { preconditionFailure("Empty validators") }
    return validators.dropFirst().reduce(first) { compose(first: $0, second: $1) }
}

I’ve set as private the first compose function to clean how the valdiators are composed and provide only one function to compose them.

Now let’s update how the phone and email validator works.

enum StringValidationError {
    case emptyString
    case notValidEmail
    case phoneInvalidLength
    case mustContainsOnlyNumbers
}

extension Validator where Value == String, Error == StringValidationError {
    static let notEmpty = Validator<String, StringValidationError> { string in
        string.isEmpty ? .invalid(.emptyString) : .valid(string)
    }

    static let containsAt = Validator<String, StringValidationError> { string in
        string.contains("@") ? .valid(string) : .invalid(.notValidEmail)
    }

    static let phoneLength = Validator<String, StringValidationError> { string in
        string.count == 9 ? .valid(string) : .invalid(.phoneInvalidLength)
    }

    static let onlyNumbers = Validator<String, StringValidationError> { string in
        let numberSet = CharacterSet(charactersIn: "0123456789")
        let stringSet = CharacterSet(charactersIn: string)
        return stringSet.isSubset(of: numberSet) ? .valid(string) : .invalid(.mustContainsOnlyNumbers)
    }

    static let phoneValidator = Validator<String, StringValidationError>.compose(
        .notEmpty,
        .phoneLength,
        .onlyNumbers
    )

    static let emailValidator = Validator<String, StringValidationError>.compose(
        .containsAt,
        .notEmpty
    )
}

At this point, we know if the validation fail, what is the produced error.

Okey, but now, how we can compose from this primitive types validators to a bigger one?

Compose them to validate complex models

Back to the user model proposed previously. We need a way to compose a validator of the User model, that validates each path (if needed) of the user, and not only that, when we’re validating the user, we want to get errors of the UserValidationError domain, not from the StringValidationError so we will also need a new way transform the path domain ValidationError to the Model domain ValidationError.

To create the user Validator from other validators we need a function to compose a Model Validator that takes the value from a model’s path, and validates it with the provided validator and then if error it’s produced, mutate it from the path domain error to the model domain error.

I know this sounds a little bit hard, but the function it’s reallly simple. What we need? The path, the validator and the mutating func, so let’s create the function that given those values prodive us the new Validator. This function will be also on the Validator object to keep the dot notation and be able to use it when composing.

extension Validator {
    static func path<SubValue, SubError>(_ keypath: KeyPath<Value, SubValue>,
                                         _ validation: Validator<SubValue, SubError>,
                                         mapError: @escaping (SubError) -> Error) -> Validator<Value, Error> {
        Validator<Value, Error> { value in
            switch validation(value[keyPath: keypath]) {
            case .valid: return .valid(value)
            case .invalid(let error): return .invalid(mapError(error))
            }
        }
    }
}

This is the key point of our Validator, with that simple function, we can compose simple validators into a biggers validators to validate models from the path values.

Now we can create a user validator that uses the email and phone validator to validate the required paths.

enum UserValidationError {
    case .invalidEmail(StringValidationError)
    case .invalidPhone(StringValidationError)
}

extension Validator where Value == User, Error = UserValidationError {
    static let userValidator = Validator<User, UserValidationError>.compose(
        path(\.email, .emailValidator, mapError: { .invalidEmail($0) }),
        path(\.phone, .phoneValidator, mapError: { .invalidPhone($0) })
    )
}

And now, we can see what path it’s failing, and what it’s the failure of the path. As the map error it’s a simple function that given one error returns a new error type, the possibilities of that mapping are endless. For example, if we only want to show to the user a message, our StringValidationError could have a failulreReason: String with a message like “Can’t be empty”, and we can compose the messages to do something like mapError: { .invalidEmail("email \($0.failureReason") }, or whatever.

Conclusions

We’ve seen how creating simple Validation rules, we can compose them to create more complex validators like email or phone based on two or more rules, and then, go even further and compose those Validators to create a Model type validator that validates each path of the model with painless, keeping simplicity and readability.

These type of validaros keep being easy testable, because they’re based on simple rules and we can avoid test the composed ones, because if the compose function is tested and the simples rules are tested too, the composed one will work fine always. Not forget that if you’re mapping errors with a lot of logic, you should test that error mappings.

Copying objects in Swift

Fri, 08 May 2020 00:00:00 +0000

How many times, working with structs, we want to grab a copy, mutate one value, and then return the mutated value. The traditional way of do this, always has been the next lines of code:

var copy = whatever
copy.foo = bar
return copy

With those lines, we can make mistakes, we can return whatever instead of copy, ending with the wrong value. Also make our coder harder to read, because we’re writting three lines to perform a single operation, an operation not named, and we need to see what variable it’s changing to know what’s happening.

But nowadays, we got some protocols and features on the language that could help us to avoid that.

Not only that, we can make our code more readable, and self explaining. We’re going to introduce a protocol that will help us to do this.

For our goal, we need to have the ability of use object.copy { $0.foo = bar }. This function it’s a pure function, it’s a function designed inside a protocol, so all our objets will have it only implementing the protocol.

Kotlin has this feature included on the language, let’s see an example:

data class User(val name: String = "", val age: Int = 0)

val jack = User(name = "Jack", age = 1)
val olderJack = jack.copy(age = 2)

This copy funciton is really useful when working with maps or flatMaps, or any type that let’s us map over it. Like Promises, Observables, Result… We can map the value inside the wrapper, and then return it mutated, in one line. Our code will be easier to read and follow, but also more expressive and more concise. But this is not only useful when working with Wrapping types, we can even use this, for example, tag an item as favourite, we take the value from the DB, mutate the copy and then save the mutated copy, avoiding to have mutating objects on our code.

We can take the given data class, mutate it, and return the new, in one line. To give you more context, if we have the next user struct, and we want to do a function, to increment x years of the user age, I need to implement the next function:

struct User {
    let name: String
    let age: Int

    func older(by years: Int) -> User {
        //this doesn't work
        copy(age = age + years)
    }
}

Like swift doesn’t have this function included on the language, we can do the next:

struct User {
    let name: String
    let age: Int

    func older(by years: Int) -> User {
        copy(age: age + years)
    }
}

extension User {
    func copy(name: String? = nil, age: Int? = nil) -> User {
        User(name: self.name ?? name, age: self.age ?? age)
    }
}

The main key point of this, is that we are mutating the value, but as you can see, we don’t have the function as mutating. Because the value that we mutate it’s a copy instead of the original object. This way we can avoid side effects, caused by mutate an object that it’s inside another object. We should try to make as many pure functions as we can. We avoid mutate things without know what we’re doing and these functions are easier to test and easier to read since we don’t need to go out of the scope of the function to see whats happening…

Back to the last example, we have the same function as kotlin has and the older function working, but we have to write a lot of boilerplate code, each time we want have it available inside one object. We could use sourcery to generate this kind of functions automatically, but this time, I want to make a protocol, with the goal of only implementing it, we can do this kind of operation over any struct.

To do this, we’re going to work with the next protocol.

protocol Copyable {}

And then, let’s add some functions to mutate a fresh copy and then return it mutated.

extension Copyable {
    func copy(_ mutator: (inout Self) -> Void) -> Self {
        var copy = self
        mutator(&copy)
        return copy
    }
}

This is how we can mutate self with the given closure and then return the mutated copy of self. But we must pay a price, the price of having our properties inside the object as var instead let. We need to make our objects variables as vars to be allowed to mutate them. Our User with this looks like

struct User {
    let name: String
    private(set) var age: Int

    func older(by age: Int) -> User {
        copy { $0.age = $0.age + 1 }
    }
}

Now, starting from the basic copy function, we can add more syntactic sugar to make it more readable. How? Using Keypaths in our Copyable protocol and using inside the old copy function.

extension Copyable {
    func replacing<T>(to keyPath: WritableKeyPath<Self, T>, value:  T) -> Self {
        copy { $0[keyPath: keyPath] = value }
    }
}

In our User code:

struct User {
    let name: String
    private(set) var age: Int

    func older(by years: Int) -> User {
        replacing(\.age, to: age + years)
    }
}

This kind of functions and way of programming, lead us to make our code more readable, while keeping non mutating objects.

We can even extend more the Copyable extension with more functions to have for example an adding function that will look like:

func adding<T>(to keyPath: WritableKeyPath<Self, T>, value: T, merging: (T, T) -> T) -> Self {
    copy { $0[keyPath: keyPath] = merging($0[keyPath: keyPath], value) }
}

Now, using the new function, our code under User will look like:

struct User: Copyable {
    let name: String
    private(set) var age: Int
    
    func older(by years: Int) -> User {
        adding(to: \.age, value: years, merging: +)
    }
}

Like + it’s a function that takes two values with the same type and returns the new one, we don’t need to create the closure and add the values inside, the clousure will be the add function itself.

The last trick is the one with the highest price. If we make our structs properties vars, without private(set), we could use the adding or replacing functions outside the struct object. The price will be the ability to mutate the properties without using our protocol functions always that our object be mutable. This could lead us to have some problems (that some times we can fix).

Let’s supose we have the next ViewModel with an State:

final class ViewModel {
    var state: State
} 

Each time we want to update the state properties, if it is an struct instead an enum, after loading some data, we could do:

state.data = loadedData

On the other hand, if State is inside a parent class, we could close the state modification only by function

open class ViewModel<State> {
    private(set) state: State

    final func update(state: State) {
        self.state = state
    }
}

Or even:

open class ViewModel<State: Copyable> {
    private(set) state: State

    final func update(state mutator: (inout State) -> Void) {
        self.state = state.copy(mutator)
    }
}

This way, update the state after get some data should be:

update(state: { $0.data = someData })

We can even go further with functional.

Extra tip.

Like you’ll see, this is going to be less usable than the copy function, but we’re here only to enjoy.

In swift, we have the option working with types that given a type returns a function, a funtion that given the type instance, return itself. Let’s see the example with the User.

We can write User.older, and this will return a function that given the user, return a the older function itself ((User) -> ((by: Int) -> User)).

Knowing that, we can update our update(state: ) to something that receives that kind of functions and the value. So we can endup with the following syntax in our ViewModel and remove the Copyable State requirement.

final class UserVM: ViewModel<User> {
    
    func olderUser() {
        update(state: User.older, by: 11)
    }
    
}

The function on the ViewModel, will receive a function that given the State and the value, returns a function that given a value, returns the State.

class VM<State> {
    private(set) var state: State {
        didSet { print(state) }
    }
    
    init(state: State) {
        self.state = state
    }
    
    func update<T>(state mutator: (State) -> ((T) -> State), by: T) {
        self.state = mutator(state)(by)
    }
    
}

Xcode at scale - Final conclusions

Sun, 26 Apr 2020 00:00:00 +0000

This is the last step of a serie named iOS at Scale based on the next steps:

This is the end, my only friend, the end.

Let’s do a little recap over what we’ve done here.

How remove Xcode conclicts and support Xcode on Scale, having configurations in files instead the project, allowing us to have these configurations in a format understandable on our versioning system.
How with Tuist we can make our life easier, better and more productive creating modules.
How we can create SPM Packages without pain to have the option of reuse code along our whole company, or our projects.
How use apple guidelines to give our protocols better names.
How reduce code using maps over Result and the same concept on the Promises, and how this could make our code easier to understand, faster to develop, reduce the quantity and make harder to introduce bugs.
How we can develop in a few steps our own Networking library.
How we can develop our custom Storage library, and how we can integrate cache fast and easy.
How we can develop our Promises framwork.
How to extend a SPM package with more targets to extend functionality without touching the original code.
How we can perform a refactor on a big project lead by little steps and keep our application working to be able to build new features in the meanwhile.
We also noticed about some bad practices that have been removed.
We created small composable objects, that are rusable and extensibles, applying POP.
How we can have reactive views with Single Data Flow applying new techniques like Type Erasure. Keeping decoupled our Views from the ViewModels.
We saw how a good component like the Navigator that we read from one post, can be not so useful if we don’t understand fine how and why it works.
How priorize functions and types over Classes, like the HTTPRequests and the new endpoint creation. And how this can minify our code.
How apply patterns like IoC without Pain and make the Core of our app works decoupled from the MarvelClient.
How do dependency injection in our app, without have our modules dependents about how we do it.

This serie is designed, to show and cover how maintain a big project, how we can apply new techniques and tools to our daily tasks and be more productive, while we can reduce our code quantity at the same time that we get more code quality, our software is more solid, and with more ability to change over the years.

I don’t talked anything about SwiftLint or SwiftFormat, but they help a lot to maintain the same code style, to fail first and of course, to avoid things like functionName(){ instead of functionName() {. This tools are very easy to add to our projects, and really help indexing, formatting and maintaining our code. You may find a project with those tools and tuist here.

Working in large teams, with many people, we have to limit very well ourselves to be ables to complete tasks without the needs of touching a lot of code in colindant modules, make simple functions, and create components easy to extend and share, are a must. Nowadays we have tools like SPM or Tuist that help us defining those Modules, encapsulate them, and give us the ability to share and reuse like we need.

The main difference when working on a true professional project, I guess that it doesn’t reside all on the code, the code have a great percentage, you know, but, we forget about the project setting up. We must automate as many as we can our configurations, provide a Makefile (or whatever scripting tool) to help if one person is new on our company, it could run make project and has the repostiory working, with dependencies downloaded, and the project automatically generated. That must be our goal. But not only make the new mates an easier onboarding, this way our project will be easy reproducible on our CI system, and if someone need to know how the project it’s beign built, only looking to one file can understand all the steps, because they are defined.

Finally, I hope you enjoyed the journey as many as I’ve enjoyed developing it. Our code vision must change, we must priorize to use this kind of new techniques over the old ones. Apple is going for that, SwiftUI and Combine are a fact. But not only apple is leading us for those techniques, Android has Live Data, ViewModels, Eithers, are supported from Google, one more time, leading us to build reactive and more functional apps. Because the code reduction is incredible. How our code decrease along it still doing the same or more, for me has no words. All of this, without forget protocol oriented programming, how extensions works, and how combine all of these techniques build better and solid software.

You can find me on Twitter

Steps

Xcode at scale - Introducing to promises 2 - Refactor to use them

Sat, 25 Apr 2020 00:00:00 +0000

This is the eleventh step of a serie named iOS at Scale based on the next steps:

This is our last series post, where we’re going to see how promises can make our life a little bit easier.

One of the things that a like about promises it’s the function signature with them. We return objects instead having closures as parameters. We return a new kind of object that we can map over. Promises allow us to group them into one, make our code more declarative and read our code easier.

They can do as many things as we develop on them, and they are generics (one work, a lot of usages). In this case, our promises are very basic, but we’re going to see how even a very basic promises help us on our daily basics.

In order to do this, we’re going to see another cool feature of SPM. At the moment we have two different packages, one for the Promises, and one for the Networking. This time, we’re going inside Networking, to create another Target that will be Networking+Promises.

This way, we still have the option to use Networking without Promises, and also we can go developing more Promise features if we want. Of course, we have 2 different targets, this means two bundle testing… A lot of benefits.

So let’s do it.

Refactor applying promises

The first thing to do, it’s create a new folder hirarchy on the Networking folder, like this time we’re going to have two targets, we’re going to follow the SPM guidelines. We will have Networking/Networking and Networking/NetworkingPromises. One for the Networking code and the other for the Networking+Promises code.

Then we have to update our Package.swift. The Manifest of our package now must indicate the new target, and also we will add the test target for it. (commit: 4dabb6a)

Now it’s time to update our dependency graph inside the project. First, we add the new product as dependency on our dependencies on Tuist. And then we touch the Tuist Manfiest files. Like with other Libraries, we must add it only one time for the project, so we add it to the Core (it’s our lower package, due that from it depends MarvelClient, remember the IoC, and from MarvelClient depends the other packages). (commit: 6d2211c)

With all set, now we start to work on the NetworkingPromise.swift extension. (I did it before, but I show the little work now). The only thing we need to do, it’s to create a Promise, that perform the request and then unwrap the result to pass the values to the promise. Like we have done the code of the perform with the old Done<T, E>, we can use that and wrap it inside the promise.

public extension HTTPPerforming {
    func perform<T: Decodable, E: Decodable>(_ endpoint: Endpoint) -> Promise<T, Error<E>> {
        Promise { future in
            self.perform(endpoint) { (result: Result<T, Error<E>>) in
                switch result {
                case .success(let value): future.fulfill(value)
                case .failure(let error): future.reject(error)
                }
            }
        }
    }
}

That’s it. That’s all the code that we need to make our Networking library work with promises.

Now, let’s start to modifying our services inside the MarvelClient. We will import now on the service part, not only the Networking, but also NetworkingPromisesand Promises. Then change the code of the services to return promises.

We pass from:

public func characters(offset: Int?, _ done: @escaping (Result<[Character], MarvelError>) -> Void) {
    client.perform(Endpoint(path: "/v1/public/characters", parameters: ["offset": offset ?? 0])) { (result: Result<Response<[Character]>, Error<MarvelError>>) in
        done(result.map(\.body.results).mapTerror(\.marvelError))
    }
}

public func character(by id: Int, _ done: @escaping (Result<[Character], MarvelError>) -> Void) {
    client.perform(Endpoint(path: "/v1/public/characters/\(id)")) { (result: Result<Response<[Character]>, Error<MarvelError>>) in
        done(result.map(\.body.results).mapTerror(\.marvelError))
    }
}

To: (commit: 790091e)

public func characters(offset: Int?) -> Promise<[Character], MarvelError> {
    (client.perform(Endpoint(path: "/v1/public/characters", parameters: ["offset": offset ?? 0])) as Promise<Response<[Character]>, Error<MarvelError>>)
    .then { $0.body.results }
    .catch { $0.marvelError }
}

public func character(by id: Int) -> Promise<[Character], MarvelError> {
    (client.perform(Endpoint(path: "/v1/public/characters/\(id)")) as Promise<Response<[Character]>, Error<MarvelError>>)
        .then { $0.body.results }
        .catch { $0.marvelError }
}

Now that we have adapted our Servicing, let’s to adapt the Provider, but this time unwrapping the promise to a Done again, to check that the app still working, and show that we may refactor by layers or even method by method while we develop more functionalities, instead refactor the whole app in one time. (commit: 7a24cea)

public func characters(offset: Int?, _ done: @escaping Done<[Core.Character], CharacterRepositoryError>) {
    service.characters(offset: offset)
        .then { $0.map(\.coreCharacter) }.then { done(.success($0)) }
        .catch { $0.repositoryError }.catch { done(.failure($0)) }
}

public func character(by id: Int, _ done: @escaping Done<Core.Character, CharacterRepositoryError>) {
    service.character(by: id)
        .then { try $0.first.map(\.coreCharacter) ?? CharacterRepositoryError.notFound }.then { done(.success($0)) }
        .catch { $0.repositoryError }.catch { done(.failure($0)) }
}

On that part, we see how we can do steps by then. First we take the service promise and map it, and then, we uwrapp the promise and call the done. This way, we take the promise and come back to the Done, and we can do an incremental refactor, if our app it’s big. This way of doing refactors of one technologies newer ones it’s easy, because we do it layer by layer, or object by object…, and we’re nor bound to make a whole app refactor. Or even worse, start an app from zero because our legacy code it’s unrefactorizable.

Okey, so now we can continue to end our refactor to have promises working on all layers.

The next step its to refactor the Provider Interface inside Core to adapt it to promises.

public protocol CharacterProviding {
    func characters(offset: Int?) -> Promise<[Character], CharacterRepositoryError>
    func character(by id: Int) -> Promise<Character, CharacterRepositoryError>
}

Then the Provider Implementation inside our MarvelClient.

public func characters(offset: Int?) -> Promise<[Core.Character], CharacterRepositoryError> {
    service.characters(offset: offset)
        .then { $0.map(\.coreCharacter) }
        .catch { $0.repositoryError }
}

public func character(by id: Int) -> Promise<Core.Character, CharacterRepositoryError> {
    service.character(by: id)
        .then { try $0.first.map(\.coreCharacter) ?? CharacterRepositoryError.notFound }
        .catch { $0.repositoryError }
}

We got working now the Provider and the repository of core stops compiling, so let’s fix the repository also.

public func characters(offset: Int?) -> Promise<[Character], CharacterRepositoryError> {
    provider.characters(offset: offset).then { result in
        completion(result.map { $0.run { $0.forEach { self.cache.set(value: $0) } } } )
    }
}

At this point, we see how we can make our code simpler again, to remove the run usage, if we extend the promises and add a new then that let us to do something with the Value, but not mutate it. This way, we operate the value, and then, return the promise again. So, to end that method refactor, let’s add the Promise extension inside the Promise framework.

func then(on queue: Queue = DispatchQueue.main,
          _ runValue: @escaping (T) -> Void) -> Promise<T, E> {
    map(
        on: queue,
        mapValue: {
            runValue($0)
            return Promise<T, E>(value: $0)
        },
        mapError: { Promise<T, E>(error: $0) }
    )
}

And using it, our character repository functions looks like:

public func characters(offset: Int?) -> Promise<[Character], CharacterRepositoryError> {
    provider.characters(offset: offset).then {
        $0.forEach { self.cache.set(value: $0) }
    }
}

public func character(with id: Int) -> Promise<Character, CharacterRepositoryError> {
    if let character = cache.get(id: id as Character.ID) as Character? {
        return Promise(value: character)
    } else {
        return provider.character(by: id).then { self.cache.set(value: $0) }
    }
}

For the last, we only need to update the two UseCases of the features.

extension GetCharacterDetail: GetCharacterDetailProtocol {
    func execute(with id: CharacterId) -> Promise<CharacterDetail, CharacterDetailError> {
        characterRepository.character(with: id)
            .then { CharacterDetail(with: $0) }
            .catch { CharacterDetailError(characterRepositoryError: $0) }
    }
}

And the GetCharacters:

extension GetCharacters: GetCharactersProtocol {
    func execute(offset: Int?) -> Promise<[CharacterListModel], CharacterListError> {
        characterRepository.characters(offset: offset)
            .then { $0.map { CharacterListModel(with: $0) } }
            .catch { CharacterListError(characterRepositoryError: $0) }
    }
}

As we see until now, our maps are easier to read, and we’ve reduced a lot the code quantity.

Now time for our ViewModel and Presenter, this case it’s a little bit different, to ilustrate that we can pass the functions to parameters that receives a closure. Because functions are named closures or a closure it’s an anonimous function.

func loadCharacterDetail() {
    getCharacterDetail.execute(with: characterId)
        .then(getCharactersFinished)
        .catch(getCharactersFinished)
}

This is the actual code of the Presenter, as we see, now we need one more extension inside our Promises. Yes, the .always method that will execute the content when the promise finish. Also if it’s fulfilled or rejected.

getCharacters.execute(offset: offset) { [weak self] result in
    guard let s = self else { return }
    s.loading = false
    switch result {
    case .success(let characters):
        s.getCharactersFinished(with: characters)
    case .failure(let error):
        s.getCharactersFinished(with: error)
    }

So let’s develop the .always. Back to the Promises framework, let’s create a new file named Always. This extension only have to do one thing, perform one block and then return the new promise with the received values.

@discardableResult
func always(on queue: Queue = DispatchQueue.main,
            _ do: @escaping () -> Void) -> Promise<T, E> {
    map(
        on: queue,
        mapValue: {
            `do`()
            return Promise(value: $0)
        },
        mapError: {
            `do`()
            return Promise(error: $0)
        }
    )
}

And using it on the CharacterListContainerPresenter.

func loadCharactersList() {
    guard !loading else { return }
    
    loading = true
    getCharacters.execute(offset: offset)
        .always { self.loading = false }
        .then(getCharactersFinished)
        .catch(getCharactersFinished)
}

That’s it. We got now all our app working with our custom developed Promises. (commit: d23d168)

Conclusions

We saw how easy is to extend one Package adding new functionality while we don’t touch the original code in our library.
We performed a step by step refactor, by layers, covering how we can do this kind of recfactor in a real big app.
We saw the power of promises, how them can make our code, simpler, more readable and robust.

Working with promises, it’s a good first step to start with functional concepts like Monads, the one it’s a concept that we must fully understand, because it’s the base of our code, Optionals are Monads, Arrays are monads, and like in this case the Promises.

Also we need to understand how the map, flatmap, and other functions works. This kind of functions allow us to remove ifs and make our code more readable, because our data flow it’s very clear, since we don’t have two branches on the code (they are, but wrapped inside the result, promise or whatever), we only take one object, and map one value if need, and map the error if needed. And the mapping process it’s even easier to read, because we know that one function give us one type, we take that type, mutate it, and return a new type. This is how all the core of this application it’s working right now.

Steps

Xcode at scale - Introducing to Promises - Creating our own framework

Fri, 24 Apr 2020 00:00:00 +0000

This is the tenth step of a serie named iOS at Scale based on the next steps:

Since Swift it’s here, the way of coding have changed. This is a Fact. On the old obj-c times are gone, on old times we only have Protocols and Clases, and we must build our code over that. We suffer a explosion of classes when doing architectures like VIPER, we was lead to build new classes wrapping other components, add extra layers of complexity, and in the end, write a lot of more code.

Generic and functions as a type bring us the option to start building very smalls components, with a very closed responsability, and start combining them.

Since creation, Swift it’s a game changer.

We have new tools that may help us on our daily basics coding. Our mindset have to change. We still use the same principles, Solid, Kiss, OOP, and the most common design patterns are still here, but new friends are come too, we have Type Erasure, POP, Closures… And now that  it’s providing his own RX framework like Combine, framework where Swift UI it’s built, don’t understand how these tools works is not an option.

We’re going to make a little step inside functional programming, we’re going to create a very little Promises framework, with a couple of clases, to lose the fear to this concepts, also, we’re cover that we don’t need a big external library like PromiseKit, Google Promises, or even RxSwift to get the benefits of FPP.

Lets start making!

Please go to start-promises on git (git checkout start-promises).

To generate the project with Tuist we must run tuist generate on the Workspace.swift folder. Check the a little bit the code and let’s stop to think one minute.

The first step it’s create our own Package as we are going to add only code, SPM it’s a great option, and we can share this package along our company, open source, what ever.

Creating the SPM Package

As this package will not fit under Modules of our app because it really is a dependency, we will create another folder called Libraries to know that those packages are shared. Then on Library/Promises folder we execute swift package init --type library. We have our package ready. (commit: ed82c10)

Note: like this package will be only one target and for iOS, I’ll do a little cleanup. Note: SPM allow us to share our packages to other platforms, following this kind of settups will make us able to reuse a lot of components

I’ve removed the test for linux, and set that this library only build for iOS with minimum version iOS 10. Also moved the source code to Sources instead Sources/Promises. (commit: ca06faa)

Okey, we have the package, but we need set it as dependency and we able to work on it, more now that the package it’s under initial development.

In order to do this, we need to add the package dependency to our Support Module, due that this Module it’s available to the whole app, and we want Promises also available to the whole app.

Also, to have the SPM under development, we only have to add it to our Workspace (doc). (tuist do this automatically when use the path Package initializer) (commit: 0af3a05)

Start to creating our Promises

Promises are objects that will help us doing asynchronous tasks, with fixed Types and allow us to mutating the given data by then & catch methods. Its very similar to the used method on the project Done<Value, E: Error> = (Result<Value, Error>) -> Void but with more syntax sugar, and easy to extend but not to modify (Open Close principle).

The result approach it’s fine, but learned the promises, learned a the basis of FPP.

Even using Result if we do this:

public typealias CharactersCompletion = (_ result: Result<[Character], CharacterRepositoryError>) -> Void

We’re adding extra complexity, we are creating more typealias for each type of response on our Repository layer, and this is creating more code to maintain, less standard solutions… since we can have only one Completion declared on support:

public typealias Done<T, E: Error> = (Result<T, E>) -> Void

The first thing that help me a lot about FPP it’s read a function with the following sentence, a function it’s something that GIVEN some parameters, DO some work and RETURNS something. This is extreamly useful since we can have Objects, with function as properties, intializer parameters and combining this features with generics will make our code work easier.

Since our promises will execute some work, we need to add them the hability to choice where to perform that work. This will be expressed by a protocol called Queue. (commit: fd69d7e)

protocol Queue {
    func execute(_ work: @escaping () -> Void)
}

And our Promises will have an State, since they could be pending, fullfilled (completed) or rejected (completed with error). So lets create an enum State with this possible states. We end up with this: (commit: 6efbaa7)

enum State<Value, E: Error> {

    case pending()

    case fulfilled(value: Value)

    case rejected(error: E)


    var isPending: Bool {
        if case .pending = self {
            return true
        } else {
            return false
        }
    }
    
    var isFulfilled: Bool {
        if case .fulfilled = self {
            return true
        } else {
            return false
        }
    }
    
    var isRejected: Bool {
        if case .rejected = self {
            return true
        } else {
            return false
        }
    }

}

Now we’re going to create the promise object, this object must be initializated with a work to perform, and a Queue where perform it. But we need a way to nofify the Promise when the work it’s done. We’re going to do this creating a new object called Future, this object has two blocks, one to fullfill the Promise, and another to reject it. (commit: 0ea74a8)

public struct Future<T, E: Error> {
    
    public let fullfill: (T) -> Void
    public let reject: (E) -> Void
    
}

With the need of a place to store the callbacks that will be executed when the promise ends, a good choice it’s to keep them on the State.pending, so we need to add a place that stores the work to perform when the promise completes.

This work have two options fullfill and reject, since the promise can be completed with success or error. This fits perfectly with the Future object we’ve created, so let’s add the Future into the State.pending, (because we only need to keep the blocks if the promise it’s not completed)

We need that the pending state can be initialized with an empty future, so instead of a Future, let’s add an Array of Futures. (commit: 1288f38)

enum State<Value, E: Error> {

    case pending(future: [Future<Value, E>])

    case fulfilled(value: Value)

    case rejected(error: E)

}

Now that we have all those components, let start to creating our Promise. The first thing that we need it’s an empty initialzer, and remember, Promise must has an State, and how we will mutate the promise, but we don’t want that it changes his reference, it must be a class (final to be closed to modification) (commit: 0515e26).

public final class Promise<T, E: Error> {
    
    private var state: State<T, E>
    
    public init() {
        self.state = .pending(futures: [])
    }
    
}

Now we must be able to create the promise with a work that when ends launch the fulfill or the reject method. So let’s add it. (commit: a7cfcc3)

public final class Promise<T, E: Error> {
    
    private var state: State<T, E>
    
    public init() {
        self.state = .pending(futures: [])
    }
    
    public convenience init(on queue: Queue, _ work: @escaping (Future<T, E>) -> Void) {
        self.init()
        queue.execute {
            work(Future(fulfill: self.fulfill, reject: self.reject))
        }
    }

    private func fulfill(with value: T) {
        
    }

    private func reject(with error: E) {
        
    }

}

And we will need the option to create a Promise with Error or Value, so let’s add those initializer methods. (commit: 06e592c)

Now we are going to do the hard part. Lets make our promises work, how them work? Adding futures to the pending state. Thats all. Seriously. Thats all.

private func addFuture(future: Future<T, E>) {
    switch state {
    case .pending(let futures):
        state = .pending(futures: futures + [future])
    case .fulfilled(let value):
        future.fulfill(value)
    case .rejected(let error):
        future.reject(error)
    }
}

That it’s the most important method on the Promise. Let’s explain all steps on that method to be clear. If the promise is pending (work it’s currently being executed), we take the prevous futures and add the new one, but we keep .pending. If the promise has done the work, and there is a value, we execute the given future.fulfill passing to it the value. And the last, if has done the work with an error, we call the rejected with the given error. (commit: 981cd16)

We still have empty functions on Promise.fulfill and Promise.reject so lets fill them.

private func fulfill(with value: T) {
    guard case .pending(let futures) = state else { return }
    state = .fulfilled(value: value)
    futures.forEach { $0.fulfill(value) }
}

private func reject(with error: E) {
    guard case .pending(let futures) = state else { return }
    state = .rejected(error: error)
    futures.forEach { $0.reject(error) }
}

This methods can be only called one time, the thime that the work ends, then they mutate the state to fulfilled or rejected, and then the rest of thens and catch will be instantly executed because the promise has done the job. (commit: e858fd4)

Now that we understand how a promise works, we need to make the state mutation thread safe. In order to do this, the only thing we need it’s a private queue and make the state mutations inside that queue.

Finally Promise looks like: (commit: d660548)

public final class Promise<T, E: Error> {
    
    private var state: State<T, E>
    private let lockQueue = DispatchQueue(label: "promise.lock.queue", qos: .userInitiated)
    
    public init() {
        self.state = .pending(futures: [])
    }
    
    public init(value: T) {
        self.state = .fulfilled(value: value)
    }
    
    public init(error: E) {
        self.state = .rejected(error: error)
    }
    
    public convenience init(on queue: Queue, _ work: @escaping (Future<T, E>) -> Void) {
        self.init()
        queue.execute {
            work(Future(fulfill: self.fulfill, reject: self.reject))
        }
    }

    private func fulfill(with value: T) {
        lockQueue.async {
            guard case .pending(let futures) = self.state else { return }
            self.state = .fulfilled(value: value)
            futures.forEach { $0.fulfill(value) }
        }
    }

    private func reject(with error: E) {
        lockQueue.async {
            guard case .pending(let futures) = self.state else { return }
            self.state = .rejected(error: error)
            futures.forEach { $0.reject(error) }
        }
    }
    
    private func addFuture(future: Future<T, E>) {
        lockQueue.async {
            switch self.state {
            case .pending(let futures):
                self.state = .pending(futures: futures + [future])
            case .fulfilled(let value):
                future.fulfill(value)
            case .rejected(let error):
                future.reject(error)
            }
        }
    }
    
}

At this point that we’re going to start using the Queue protocol, we’re going to extend DisptchQueue to conform the protocol and add it as default parameter on the Promise.init(queue, work).

extension DispatchQueue: Queue {
    func execute(_ work: @escaping () -> Void) {
        async { work() }
    }
}

public convenience init(on queue: Queue = DispatchQueue.global(qos: .userInitiated), _ work: @escaping (Future<T, E>) -> Void) {
        self.init()
        queue.execute {
            work(Future(fulfill: self.fulfill, reject: self.reject))
        }
    }

Now we are going to add the then method, this method will set (or call if finished) fulfill and reject methods. (commit: a7279a0)

@discardableResult
public func then(on queue: Queue = DispatchQueue.main, _ fulfill: @escaping (Value) -> Void, _ reject: @escaping (Error) -> Void) -> Promise<T, E> {
    addFuture(future: Future(fulfill: fulfill, reject: reject))
    return self
}

But as we can see, then method expects to execute on an specified queue. This means that we need to update our Future object to perform his clousures on that queue.

public struct Future<T, E: Error> {
    
    public typealias Fulfill = (T) -> Void
    public typealias Reject = (E) -> Void
    
    public let fulfill: Fulfill
    public let reject: Reject
    private let queue: Queue?
    
    init(on queue: Queue? = nil, fulfill: @escaping Fulfill, reject: @escaping Reject) {
        self.queue = queue
        self.fulfill = fulfill
        self.reject = reject
    }
    
    func callFulfill(value: T, _ completion: @escaping () -> Void = {}) {
        assert(queue != nil, "callFulfill only can be called if queue is not nil")
        queue!.execute {
            self.fulfill(value)
            completion()
        }
    }
    
    func callReject(error: E, _ completion: @escaping () -> Void = {}) {
        assert(queue != nil, "callReject only can be called if queue is not nil")
        queue!.execute {
            self.reject(error)
            completion()
        }
    }
    
}

To avoid this complex Future struct and merge two functionalities on the same object, (pass to the user to complete the promise, and add it as callback to the pending state) we’re going to create a new struct Callback to handle this and let the Future only to the user.

You can check the end of this changes on fe12512.

Now we must add a function that mutate both values inside our promise, the error to a new error and the Value to a new Value. This function, adds a Callback to our Promise, that will execute the given blocks on the given queue when the promise ends with the promise result, and create a new Promise with the result of that Callbacks. So the mutation happens inside the maps.

Like we are typing the error, our mapValue if throws must throw always the new promise type error, and the mapp error is needed for mutate from the first Promise error to the new Promise error (commit: 0a257c5).

Also I’ve marked as private the old then. (I’ll why explain a little bit later).

@discardableResult
public func map<NewValue, NewError: Error>(on queue: Queue = DispatchQueue.main,
                                            _ mapValue: @escaping (T) throws -> Promise<NewValue, NewError>,
                                            _ mapError: @escaping (E) -> NewError) -> Promise<NewValue, NewError> {
    Promise<NewValue, NewError> { future in
        self.then(
            on: queue,
            fulfill: { oldValue in
                do {
                    try mapValue(oldValue).then(on: queue, fulfill: future.fulfill, reject: future.reject)
                } catch let error {
                    future.reject(error as! NewError)
                }
            },
            reject: { oldError in
                future.reject(mapError(oldError))
            }
        )
    }
}

With that map done, to map Values and Errors, now we can create the then to map only the value. This function it’s pretty easy. We only need to use the last function, but only updates de Value type. (commit: 10731ba)

@discardableResult
public func then<NewValue>(on queue: Queue = DispatchQueue.main,
                            _ mapValue: @escaping (T) throws -> NewValue) -> Promise<NewValue, E> {
    map(
        on: queue,
        mapValue: { Promise<NewValue, E>(value: try mapValue($0)) },
        mapError: { Promise<NewValue, E>(error: $0) }
    )
}

And then, the same but for errors. (commit: 92e8a7d)

@discardableResult
public func `catch`<NewError: Error>(on queue: Queue = DispatchQueue.main,
                                        _ mapError: @escaping (E) -> NewError) -> Promise<T, NewError> {
    map(
        on: queue,
        mapValue: { Promise<T, NewError>(value: $0) },
        mapError: { Promise<T, NewError>(error: mapError($0)) }
    )
}

Once we have all this functions inside the Promise, it’s time to check that it works, and to do this, we can simply add a couple of tests.

At this time, I was testing the .catch and to only catch without mutate the Error type, I’ve needed to extend the Promise and add a new catch method.

Also I’ve done a little refactor, creating two new files, Then.swift and Catch.swift where I extracted those method, to take some code out of how the promise works, due that really those methods are syntactic suggar for what we already have.

Finally, you can go to this commit and check the test passing (commit: 166f7bb).

Conclusion

We created from the scratch a very simple Promise framework that allow us to mutate values and perform asynchronous task.

We combined enums with structs, we worked with functional concepts like Monads.

If we understand how this Promise works, we will understand easier new concepts like subscribers, new SwiftUI @ObservedObjects, swift Combine, and we can adopt a less code way, with less options to write bugs.

Notice that this Promise Framework its highly inspided on Khanlou Promise frameworks, but allowing us to type the Error.

Typing the error limit us on what erros can be thrown, and since Swift doesn’t allow us to type errors under throwing functions, if we throw a not expected error type inside map or then, these promises will crash on runtime. But typing erros we will have the option of switch over a known error.

To avoid this, you can do remove the error typed on the promise, or use one of the most popular frameworks named on the start of the article that doesn’t allow to type the promise.

I encourage you to test the framework, start to extend it and understand how it works closely. Maybe not promises, but FPP combined with OOP like nowadays we can do, it’s the future of how the apps will be made, and we need know it.

Steps

Xcode at scale - Cache made easy

Thu, 23 Apr 2020 00:00:00 +0000

This is the nineth step of a serie named iOS at Scale based on the next steps:

Yes, we’re near to the end. We’re on Extra-Balls.

For this chapter, I want to build a simple Cache with protocol oriented programming. This way, I’ll cover how to develop a new component, with a new package and how to merge it inside our stack. And we will find out how easy it is.

The first thing I’m going to do, again, it’s to create it with the option to share. For this, like on previos post, I’m going to use SPM.

So, let’s work! Go to the step-9 on git.

Creating a cache, POP

The first thing we need it’s to create the new folder under Libraries, at the moment, this library will only contain a cache, but like this could scale, let’s name it Storage. And like before, a little clean up into the generated library. (commit: 1a91ca7)

Now, that we have our package created, let’s add it as dependency to our Core and start to work on it. (commit: 413c7df)

I’ve also changed how these packages under development are managed on tuist. Package on Tuist can be defined with path instead url, this will insert them on our project directly without need to add them to the Workspace as extra files (as I do). But, to ilustrate better what libraries are under development, I’ll keep having them as extra files. This way, we have a folder Libraries available on our workspace.

To create the Cache, I’m going to define the protocol with the functions that I want to use. This way, we’re out of how them will be implemented, and we’ll keep the usage as easy as possible.

The protocol will be named Caching and with two functions, to set a value and to retrieve a value.

public protocol Caching {
    func set(key: String, value: Any)
    func get(key: String) -> Any?
}

This could be our first Cache protocol to use, but nowadays that we have generics, let’s improve the value Type.

public protocol Caching {
    func set<T>(key: String, value: T)
    func get<T>(key: String) -> T?
}

And now, we have the main interface of our Caching object.

Let`s do the implementation.

public final class MemoryCache {
    private let cache = NSCache<String, Any>()
}

Like NSCache, need a class type to be the key of the dictionary, let’s create a new object called Key, and how it needs Any to be a class, let’s create a wrapper for the value, called Value.

final class Key: Hashable {
    
    private let key: String
    
    init(_ key: String) {
        self.key = key
    }
    
    func hash(into hasher: inout Hasher) {
        hasher.combine(key)
    }
    
    static func == (lhs: Key, rhs: Key) -> Bool {
        lhs.key == rhs.key
    }
}


final class Value {
    let value: Any
    
    init(_ value: Any) {
        self.value = value
    }
}

And now to make it work, the Key must be an NSObject with hashvalue and isEqual, so, to do this, I’m going to create a WrappedKey, that wraps our real Key. And I’ll add an extension to Key to create an WrappedKey fast, easy and located.

extension MemoryCache {
    final class WrappedKey: NSObject {
        let key: Key
        
        init(_ key: Key) {
            self.key = key
        }
        
        override var hash: Int { key.hashValue }
        
        override func isEqual(_ object: Any?) -> Bool {
            guard let wrapped = object as? WrappedKey else { return false }
            return self.key == wrapped.key
        }
    }
}

private extension Key {
    var wrapped: WrappedKey { .init(self) }
}

public final class MemoryCache {
    private let cache = NSCache<WrappedKey, Value>()
}

Now, let’s create the implementation of Caching. (commit: c4cd3c3)

extension MemoryCache: Caching {
    public func set<T>(key: String, value: T) {
        cache.setObject(Value(value), forKey: Key(key).wrapped)
    }
    
    public func get<T>(key: String) -> T? {
        cache.object(forKey: Key(key).wrapped)?.value as? T
    }
}

We got working now our cache. But to make it easier to use, we’re going to extend the protocol and add some util functions. Like we got the main two methods working, we’re going to create some methods that will handle the key for us and make our life easier.

func set<T>(value: T) {
        
}

I want to use that interface, and use an ID as key for the object, so, we need that T conforms Identifiable.

Like Identifiable it’s only available for iOS 13 or more, let’s add inside Cache our Identifiable implementation. If we go to the code on the Identifiable protocol, we will find out that the code it’s really simple. So copy & paste the code inside a new Cache file. This way, we’re working with our protocol, but at the moment that we update the project version to iOS 13, removing this implementation will make the project works without change anything more.

public protocol Identifiable {

    /// A type representing the stable identity of the entity associated with `self`.
    associatedtype ID : Hashable

    /// The stable identity of the entity associated with `self`.
    var id: Self.ID { get }
}

func set<T>(value: T) where T: Identifiable {
        
}

And now let’s make the implementation.

func set<T>(value: T) where T: Identifiable {
    set(key: "\(value.id)", value: value)
}

func get<T>(id: T.ID) -> T? where T: Identifiable {
    get(key: "\(id)")
}

We’re finding ourselves creating the Key each time we want use it, so this time we can create an extension of Key to be initialized with an ID of an Identifiable object.

extension Key {
    convenience init<T>(id: T.ID) where T: Identifiable {
        self.init("\(id)")
    }
}

And our Caching implementation looks:

public extension Caching {
    func set<T>(value: T) where T: Identifiable {
        set(key: Key(id: value.id), value: value)
    }
    
    func get<T>(id: T.ID) -> T? where T: Identifiable {
        get(key: Key(id: id))
    }
}

Now that we have an object with an ID, we got the Key, but what happens if we want to store two different kind of object, wich ID it’s the same? We will find us overriding a previous value that we dont want to override. So, how we got the type when saving the object and when retrieving. Let’s combine the Type with the ID. The responsible of this work it’s Key initializer itself, so we only need to work on it.

private extension Key {
    convenience init<T>(id: T.ID, class: T.Type) where T: Identifiable {
        self.init("\(type(of: T.self))\(id)")
    }
}

Now, let’s update the Caching interface, to receive a Key instad of String. And this is how finally look our Caching protocol. (commit: 4e63906)

public protocol Caching {
    func set<T>(key: Key, value: T)
    func get<T>(key: Key) -> T?
}

public extension Caching {
    func set<T>(value: T) where T: Identifiable {
        set(key: Key(id: value.id, class: T.self), value: value)
    }
    
    func get<T>(id: T.ID) -> T? where T: Identifiable {
        get(key: Key(id: id, class: T.self))
    }
}

Using the Cache from the Core

Now, we got the Cache available from Core. Let’s use it on our repository.

Note: I’m going to couple Core to our Storage library, but we can create our own Caching protocol inside core, and wrap the Storage.Caching with it and stay decoupled (that interface only has to forward the get, set functions to the Storage.Cache functions).

Finally, let’s update our Repostiory to have the Caching dependency. (commit: 8c78256)

public final class InternalCharacterRepository {
    let provider: CharacterProviding
    let cache: Caching
    
    public init(provider: CharacterProviding, cache: Caching) {
        self.provider = provider
        self.cache = cache
    }
}

And now, let’s create a component inside app to register Caching and update Repostiory factory to inject it. (commit: 71a88b1)

let storageComponent = Component {
    single { MemoryCache() as Caching }
}

let repositoryComponent = Component {
    factory { InternalCharacterRepository(provider: $0(), cache: $0()) as CharacterRepository }
}

Finally, lets make our Repository cache the characters.

public func characters(offset: Int?, completion: @escaping Done<[Character], CharacterRepositoryError>) {
    provider.characters(offset: offset) { result in
        result.map { $0.forEach { self.cache.set(value: $0) } }
    }
}

As we see, we need Character to conform Identifiable. So let’s do it.

extension Character: Identifiable {}

And I’ve introduced one more thing. A protocol named Runnable with the only idea of do more things in one line.

public protocol Runnable {}

public extension Runnable {
    @inlinable
    func run(_ work: (Self) -> Void) -> Self {
        work(self)
        return self
    }
}

As we see, the Runnable only takes itself, pass it to a closure to do some work, and then return itself. This way, we can use the map of the result ot iterate the objects instead of mutate them. Because like we’re inside the completion block, we need the map to return something that will be what be passed to the completion parameter. And like the map only get’s called if our result it’s success, we get the cache working only on the success branch. (commit: 47ac463)

public func characters(offset: Int?, completion: @escaping Done<[Character], CharacterRepositoryError>) {
    provider.characters(offset: offset) { result in
        completion(result.map { $0.run { $0.forEach { self.cache.set(value: $0) } } } )
    }
}

Now, we’re storing our objects but not reading them. Let’s make our repostiory read for the character detail.

public func character(with id: Int, completion: @escaping Done<Character, CharacterRepositoryError>) {
    if let character = cache.get(id: id as Character.ID) as Character? {
        completion(.success(character))
    } else {
        provider.character(by: id, completion)
    }
}

And for the last, if we don’t have cached the character, we make the request, but then we’re not storing that character on the cache, so let’s make our character(by: id) stores also the response. (commit: 4d26f9f)

public func character(with id: Int, completion: @escaping Done<Character, CharacterRepositoryError>) {
    if let character = cache.get(id: id as Character.ID) as Character? {
        completion(.success(character))
    } else {
        provider.character(by: id) {
            completion($0.map { $0.run { self.cache.set(value: $0) } })
        }
    }
}

We got our cache working!

Conclusion

This chapter we’ve seen how to do a very, very easy cache. Using Protocol Oriented Programmin to with only a couple of methods, handle how new Identifable Items are saved and retrieved. Also covering the use of the NSCache and how we can wrap old needs like extends from NSObject in our Swift classes.

We’ve also covered how to develop and integrate a new library on our code base it’s extramly easy and painless without the needs of update any of our Features modules.

Also we’ve seen how map combined with the new protocol Runnable allow us to do more with less, and how combinning these little functions we end up building big features.

Steps

Xcode at scale - Dependency Injection - flexible and composable

Wed, 22 Apr 2020 00:00:00 +0000

This is the eighth step of a serie named iOS at Scale based on the next steps:

From the very beginning, Dependency Injection is one of the things that I really enjoy doing when developping. From my point of view, is one of the basis of programming, the basis on which are built all of the good software practices. DI it’s here to facilitate us replace components by test doubles, makes the principle of Interface Segregation take importance, because is by DI how we can pass objects according to an interface without pain to substitute for others. DI not only will help with Liskov Principle, but also will help to reuse little components along all the code base. I can’t imagine daily programming without DI.

To do so, we have available a lot of patterns. We can inject by constructor, by properties, by methods, using anotations, Factories ServiceLocator… Since Swift have default parameters, it’s very easy to do DI with those default parameters, and at least have the option to pass other instance if necesary. We can even DI based on default parameters plus Singleton Instances. On the other hand there are libraries or frameworks like Needle that generates code for us. Other libraries are container based where we provide some registrations to after retrieve components. Those registrations are little factories that combining them we build bigger components. But yo he venido aquí a hablar de mi libro (sorry, spanish joke, the translation is I’ve come here to talk about my book).

Maybe like I started my developer life working on Java, with Spring, I’m used to get help with a tool with this task. I really like how Components, Services and Autowire works togheter on that platform, I also remember how we must define the graph on an xml file based on class names Strings, and how this could stop working only with a typo (that it’s pain).

In this post I’m going to intruce Injection, a lightwight library for dependency injection. Injection it’s built with the idea of be able to reuse your code pieces in an easy way, build them with factories, group that factories on Components (if you want), and provides an standard component to build your Screens named ModuleBuilders.

The way you work with Injection it’s providing on the application launch the Components/Factories that you want to share, and then, creating your ModuleBuilders to build your Screens. With these ModuleBuliders on the game, we gain the option to pass to our instances run time parameters, named and typed.

This library, fits very well with the Navigator component, since the Screen creation it’s only a function that returns a ViewController and our ModuleBuilders are created with the purpose of return the Root thing you have on your application.

Injection its on early stage of development, but meets the basics to be working on production apps. And it counts with a DSL very easy to read. Mainly insipred on Koin.

Like we’ve seen on previous post, on of the main sources on pain of the code base, has been the DI. Not because an Assembly object will be always a pain, not. It has been a source of pain because it has a lot of variables and interfaces propagated along all the modules that makes to me the dependency graph hard to follow when refactoring. Also these assemblies has mixed dependencies from several modules, and they was stored on memory after creation, instead of beign built, create whatever thing they must create and die.

So let’s update the project to use Injection.

Refactor how Dependency Injection it’s done

Move to step-6 tag on git.

The first thing we need to do it’s add Injection as dependency to the project with SPM. Like SPM builts static libraries, we only can add this dependency to one framework of the app. Like I want to use the Features Modules Screens, in an easy way from other features, and the definition of others app components I want do it on the app, I’ll add the depedency to DisplayKit. This way I have it available on the features among the App. (commit: 6813496)

Now with injection added, I’m going to start creating our Injection Components by layer. One for each layer of the core components. The first component to do is the MarvelClient component. We can see on the Assembly of this component, how we have writed the keys to connect with the Marvel API, with a comment //This should be in other part, and yes, it should be.

I’ve created an Environment file that it’s located on App/Sources/Environment.swift, this file could be ignored on git, create an App/Sources/Environment.swift.template for example, and with Makefile or other automatizing tool like fastlane or a simple bash script, create a command to, if there’s no Environment.swift provided, copy the template, and then generate the project. This way, our developers only has to run a command on the shell to have the project working and we’re not sharing our secrets. (You may find an implementation of this command here)

Finally, our MarvelClient component will look like: (commit: 32fc02f)

let marvelComponent = Component {
    factory { Authorization(publicKey: Environment.publicKey, privateKey: Environment.privateKey) as Authorizating }
    single { HTTPClient(host: Environment.host, session: .shared, authorization: $0()) as HTTPPerforming }
    factory { CharacterService(client: $0()) as CharacterServicing }
    factory { CharacterProvider(service: $0()) as CharacterProviding }
}

As we may see, the dependencies of CharacterService or CharacterProvider are given by the $0(). This it’s the resove() function on the module where the Component is registered, this way, you can have the same component but change the dependencies depending of the Module where they are registered. You will see in action later.

Now that we have our client component done, let’s do the Repository layer Component. (commit: bd31fe0) This repository as you can see is very small, and we could remove it to use a simple factory, but if the application grows, the most possible thing it’s to have more than one repository.

let repositoryComponent = Component {
    factory { InternalCharacterRepository(provider: $0()) as CharacterRepository }
}

Now, with those components created, we’re going to provide them to injection to make them available inside the ModuleBuilders. This must be done whenever you want before instanciate your Screens by ModuleBuilders, so I suggest you to do it on the AppDelegate, and it will look like: (commit: 34f0d9d)

injectMe {
    component { marvelComponent }
    component { repositoryComponent }
}

That creates a shared Module and provides it to Injection. This module will be taken on the ModuleBuilders where you also will have the option to extend it with another Component.

Mow we have available those components inside ModuleBuilders, so let’s create our first ModuleBuilder for the Loading and Retry ViewController. (commit: 9bd9238)

public final class LoadingModuleBuilder: ModuleBuilder<UIViewController> {
    
    private let message: String
    
    public init(message: String) {
        self.message = message
    }
    
    public override func build() -> UIViewController {
        LoadingViewController(detailText: message)
    }
}

public final class RetryModuleBuilder: ModuleBuilder<UIViewController> {
    private let title: String
    private let description: String
    
    public init(title: String, description: String) {
        self.title = title
        self.description = description
    }
    
    public override func build() -> UIViewController {
        RetryViewController(title: title, descriptionText: description)
    }
}

As we see, RetryViewController has a delegate with only one function, in my opinion, we can simplify delegation by functions, like in this case, we can pass it by the constructor, like we’ll see. (commit: 109e553)

Then, let’s create the DetailContainer module builder and the detail module builder. Once created, we could remove the assembly. Then, update the dependency on the app core assembly, because we’re not using Assembly anymore on character detail screen. The module builder it’s reponsible of build all dependencies for one Screen, this way, we have localized where those dependencies are created or provided, but keeping the flexibility of use dependencies provided by injectMe.

Also, if we want to reuse some view or some view model for other Screen, we can create another ModuleBuilder, and reuse those compoenents. Each module builder it’s reponsible to build one screen, also we have the option to override injectMe components if needed simply adding to the Component the new factory for the types we want to override. This way, we have the granularity needed to make each screen as we need, while avoiding to have screen components assemblies instanciated on memory like we have before.

Now we also simplified how the screen creation it’s done, because we’ve removed the assembly-provider needs. (commit: cbd0271)

public extension Screen {
    static func detail(character id: CharacterId) -> Screen {
        .init { CharacterDetailContainerModuleBuilder(characterId: id).build() }
    }
}

Now that we have removed all the detail assemblies, we can remove the providers interfaces, and the character detail view controller factory. Also we’ve removed the formatter dependency on the Detail that was not used. (commit: 000c156)

We keep having the ability of update how Loading or Retry ViewControllers are built by updating the module builder, but this time the creation of these view controllers, can be done on the container directly instead having a factory. Our ModuleBuilders are factories by themselves.

Also, our Injection code keeps out of our code base, making Injection easy reemplazable with other library, or our custom DI, or simply to don’t make all our instances highly depends on what features Injection provides. Before, we have the Assemblies on the modules, and features was depending on those modules very hard, now it’s our app who choices about what instance to use for what dependency. And testing we can inherit from the app module, and override as many factories we need for the test. (We can for example, provide a fake HTTPPerforming, that instead going to network, give us stubs for requests)

Note: like the app assembly it’s a Singleton, with the others Assemblies like lazy vars, if our app grows, we’re loading on memory a lot of assemblies that won’t be released, this will cause our app run with a lot of memory while the user navigates though our app, so that implementation won’t scale so fine

Now let’s do the same for the List Module. As we see, we’ve reduced a lot the complexity of the Assemblies. (commit: 3db140d).

At this point, we’ve lost the Navgation between the list and the detail. This is cause about how we’re doing the navigation, we will fix this after, now let’s update the app core assembly.

To update the Assembly on the app core, before I’ll refactor how the navigation components are named, only Navigator, to Navigating to express that it’s a protocol. Then remove the old NavigatorKitAssembly and the AppCoreKitAssembly.

And now, we got accesible on all ModuleBuilders on our app the Navigator, and due it’s a single it will be always the same instance. (single are the factories for Singleton instances)

final class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    
    public func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        self.window = UIWindow(frame: UIScreen.main.bounds)
        let navigator: Navigating = Navigator(window: window!)
        
        injectMe {
            component { marvelComponent }
            component { repositoryComponent }
            component { uiComponent }
            single { navigator }
        }
        
        navigator.handle(navigation: .root(.list))
        return true
    }
    
}

Now that we have the navigation made simpler. Let’s do navigation between features easy and painless. The only target that has all the features available it’s the app target, so in that target, we will need to handle the navigation. And we will do this with protocols, to be easy injectables, and replaceable for test doubles if needed.

And then, we will be using the component modularization provided by Injection to keep this clean.

We need a protocol for the list navigation, and the component proposed to this will be a Coordinator.

Let’s create the CharacterListCoordinator: (commit: a9a6d77)

public protocol CharacterListCoordinating {
    func characterDetail(id: Int)
}

And then, we create a base Coordinator to share the simple initializer with the Navigator component.

class Coordinator {
    
    let navigator: Navigating
    
    init(navigator: Navigating) {
        self.navigator = navigator
    }
    
}

Then, the character list coordinator.

final class CharacterListCoordinator: Coordinator, CharacterListCoordinating {
    func characterDetail(id: Int) {
        navigator.handle(navigation: .push(.detail(character: id)))
    }
}

And the last, we’re going to create a Injection coordinatorsComponent to provide this instances to the features. (commit: 1b3cfe7)

let coordinatorsComponent = Component {
    factory { CharacterListCoordinator(navigator: $0()) as CharacterListCoordinating }
}

This components doesn’t need to be a singleton instance, since them use the navigator provided by the DI, and really, they only wire features, the don’t know anything about the Navigation. Also keep beeing simple pieces of code that only wire two features. These pieces are simples and easy to maintain, but keep in mind that in a big application the will be a lot.

Now we have to update the ModuleBuilder of the presenter that performs the navigation. (commit: 3acc3ad)

// CharacterListPresenter
func characterSelected(at index: Int) {
    let character = characters[index]
    coordinator.characterDetail(id: character.id)
}

Inclusive now, we can even remove the NavigationKit dependency from the Features if we want, and move the extensions of the Screen to the app target if we want.

This way we have our features even more decoupled of the NavigatorKit component. But I like to see the Screen definition under the ModuleBuilder, because we’re going to have a 1:1 relation from ModuleBuilder to Screen. So if we find one ModuleBuilder without Screen definition, maybe it’s a signal that we lost something.

Conclusions

In this chaper we’ve reduced the complexity subyacent to the Assemblies. Not because having Factories with ServiceLocator it’s a bad pattern. Because them was based on many protocols, without structure inside them and was making very hard to read the depedency graph.

We are clearer no about how the navigation it’s done with Coordinators that are easy pieces of code and allow us to customize navigation as many as we want.

Now, we have a very simple navigation beetween screens, all coordinators are built in the same way, and all navigations are performed by the Navigator but inside the app target, the responsible to built this navigation.

Now we saw that we can change the Navigator for other component if we want in a very easy way, and we have all our pieces of code easy to read, to maintain and to perform further refactors like the two next chapters.

I introduced Injection, but you can use other library, on simply use Service Locator / Factory pattens. Our code base won’t be better for use one tool or other, it will depends on what we’re doing.

If you want to give a try to Injection, I encorage you to it. You can group your factories by modules also, define those modules where you want, combine and share them. With MdouleBuilders you’ll have factories to build your screens with needed dependencies, and you can create as many Modules as you need. Since Components are not other thing than an array of functions, they will not use to much memory beign variables out of scope as we already saw here. Modules are where factories functions are mutated to objects if needed, this will happen only on single (until new type of factories arrive), the instance factory factory it’s an struct with the function to build the instance, so really it won’t use so much memory neither.

Steps

Xcode at scale - Refactor AppCore - we really need it?

Tue, 21 Apr 2020 00:00:00 +0000

This is the seventh step of a serie named iOS at Scale based on the next steps:

The final module has come. It’s time to see what AppCore module it’s giving us and why. Lets move to the step-5 on git.

One of the thoughts about this module, is that I don’t understand why this module it’s here. I’m fully agree about make our applications by modules, to limit those modules responsabilities, hide how that module works with access modifiers of our codes, and expose only the components that we need to expose. This is the most usual thing in other languages like Java. But before of create a Module, we must stop and think, We really need it? Becuase not always more it’s better.

I guess the app target must have inside the AppDelegate and must be responsible of building the app. Talking about modularized apps, I have mixed feelings about Feature Freamework, about his opportunity cost, but I understand that on big teams, they limit very well what pieces of code has to touch each team, and that could and make up for the complexity it adds (note that with Tuist or other project generators this complixity it’s very reduced). But, back to the AppCore module, that module it’s doing what our app module has to do. Why we should have this module instead move the code the app directly?

AppCore it’s an extra complexity layer that should be removed. Remember to keep all things as simple as possible.

Refactor the app core module

The first thing to do, it’s to move all the code inside AppCore, to the app target. (commit: d30ebd9)

Then, we must remove the Module/AppCore folder, and updates the dependencies of our app Manifest. (commit: aa460e5)

With those simple steps, we keep our app compiling, and we’ve already removed an extra Module, that wasn’t giving us anything.

Not let’s going deeper inside the app target.

Refactor the app target

One of the points that we should keep in mind when developping, it’s to maintain the code as easy as possible. This is not an idea of mine, it’s what KISS principle says. I guess this principle is one of the most forgotten by us as developers, we always try to think on the future of the system what we’re building, and some times we make hard things when it doesn’t has reasons to be.

Let’s see the AppDelegate. In this case, we here are doing exactly that, premature optimizations. We’ve built an AppLaunchCoordinator, to keep the code inside AppDelegate as less as possible, while all the methods on the AppLaunchCoordinator are with a comment, and should be removed.

Also notice that we don’t gain anything removing all the code on our AppDelegate, but having all that code inside other class like the AppLaunchCoordinator has. This is only move the complexity of one class, to another, but not reduces it, backwards, it adds an extra complexity layer. So take this as a bad practice.

So, the first step to do it’s remove the AppLaunchCoordinator. If inside our application, our AppDelegate is really simple, as this is, keep the code inside the app delegate. Then, if we discover that our app delegate’s grows, I suggegst you to do one of the three exposed methods here Refactor Massive AppDelegate. Take the one that better fits on your needs.

Now, our app delegate looks like: (commit: 51c4bb9)

It’s time to fix the dependency graph. (commit: 29d2c8e)

final class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    var navigator: Navigator?

    public func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        setUpAppDelegateDependencies()
        setUpWindow()
        self.navigator = AppCoreKitAssembly.current.navigator
        navigator?.handle(navigation: .root(.list(assembly: AppCoreKitAssembly.current.charactersListKit)))
        return true
    }
    
}

private extension AppDelegate {
  
    func setUpAppDelegateDependencies() {
        if AppCoreKitAssembly.current == nil {
            AppCoreKitAssembly.current = AppCoreKitAssembly()
        }
    }
    
    func setUpWindow() {
        window = AppCoreKitAssembly.window
        window!.frame = UIScreen.main.bounds
    }
    
}

Now, we can make this even simpler.

Like swift static lets are lazy, let’s make AppCoreKitAssembly being a swift singleton. Let’s create a private init and then make the current instanciate himself. (commit: 42a7e3f)

Then, we can remove the setUpAppDelegateDependencies on the AppDelegate. And we end up with an AppDelegate like this: (commit: a5f47e6)

final class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    var navigator: Navigator?

    public func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        self.window = AppCoreKitAssembly.current.window
        self.navigator = AppCoreKitAssembly.current.navigator
        navigator?.handle(navigation: .root(.list(assembly: AppCoreKitAssembly.current.charactersListKit)))
        return true
    }
    
}

Conclusions

This chapter has been short. But what we’ve done?

We’ve removed the AppCore extra module that wasn’t giving us nothing more complexity.
We’ve removed extra complexity inside the AppDelegate.
Removed the AppLaunchCoordinator layer, showing up that some times, more layers is not better code. More if these layers are simple forwards from one site to other.
Fix the bad singleton creation making our AppDelegate even simpler.

We should question always to ourselves when we’re going to add a new layer or new component, if it give us something. Not always have more layers it’s meaning that our code it’s more abstrated or decoupled. Each layer we add to our code it’s adding complexity and more code to maintain and that can make our code hard to refactor in the future.