Pure

Pure makes Pure DI easy in Swift. This repository also introduces a way to do Pure DI in a Swift application.

Table of Contents

• Background
  • Pure DI
  • Composition Root
    • AppDependency
    • Testing AppDelegate
    • Separating AppDelegate
  • Lazy Dependency
    • Using Factory
    • Using Configurator
  • Problem
• Getting Started
  • Depenency and Payload
  • Module
    • Factory Module
    • Configurator Module
  • Customizing
    • Storyboard Support
    • URLNavigator Support
• Installation
• Contributing
• License

Background

Pure DI

Pure DI is a way to do a dependency injection without a DI container. The term was first introduced by Mark Seemann. The core concept of Pure DI is not to use a DI container and to compose an entire object dependency graph in the Composition Root.

Composition Root

The Composion Root is where the entire object graph is resolved. In a Cocoa application, AppDelegate is the Composition Root.

AppDependency

The root dependencies are the app delegate's dependency and the root view controller's dependency. The best way to inject those dependencies is to create a struct named AppDependency and store both dependencies in it.

structAppDependency{letnetworking:NetworkingletremoteNotificationService:RemoteNotificationService}extensionAppDependency{staticfunc resolve()->AppDependency{letnetworking=Networking()letremoteNotificationService=RemoteNotificationService()returnAppDependency(
networking: networking
remoteNotificationService: remoteNotificationService)}}

It is important to separate a production environment from a testing environment. We have to use an actual object in a production environment and a mock object in a testing environment.

AppDelegate is created automatically by the system using init(). In this initializer we're going to initialize the actaul app dependency with AppDependency.resolve(). On the other hand, we're going to provide a init(dependency:) to inject a mock app dependency in a testing environment.

classAppDelegate:UIResponder,UIApplicationDelegate{privateletdependency:AppDependency
/// Called from the system (it's private: not accessible in the testing environment)
privateoverrideinit(){self.dependency =AppDependency.resolve()
super.init()}
/// Called in a testing environment
init(dependency:AppDependency){self.dependency = dependency
super.init()}}

The app dependency can be used as the code below:

func application(_ application:UIApplication, didFinishLaunchingWithOptions launchOptions:[UIApplicationLaunchOptionsKey:Any]?)->Bool{
// inject rootViewController's dependency
iflet viewController =self.window?.rootViewController as?RootViewController{
viewController.networking =self.dependency.networking
}}func application(_ application:UIApplication, didReceiveRemoteNotification userInfo:[AnyHashable:Any], fetchCompletionHandler completionHandler:@escaping(UIBackgroundFetchResult)->Void){
// delegates remote notification receive event
self.dependency.remoteNotificationService.receiveRemoteNotification(userInfo)}

Testing AppDelegate

AppDelegate is one of the most important class in a Cocoa application. It resolves an app dependency and handles app events. It can be easily tested as we separated the app dependency.

This is an example test case of AppDelegate. It verifies that AppDelegate correctly injects root view controller's dependency in application(_:didFinishLaunchingWithOptions).

classAppDelegateTests:XCTestCase{func testInjectRootViewControllerDependencies(){
// given
letnetworking=MockNetworking()letmockDependency=AppDependency(
networking: networking,
remoteNotificationService:MockRemoteNotificationService())letappDelegate=AppDelegate(dependency: mockDependency)
appDelegate.window =UIWindow()
appDelegate.window?.rootViewController =UIStoryboard(name:"Main", bundle:nil).instantiateInitialViewController()
// when
_ = appDelegate.application(.shared, didFinishLaunchingWithOptions:nil)
// then
letrootViewController= appDelegate.window?.rootViewController as?RootViewControllerXCTAssertTrue(rootViewController?.networking === networking)}}

You can write tests for verifying remote notification events, open url events and even an app termination event.

Separating AppDelegate

But there is a problem: AppDelegate is still created by the system while testing. It causes AppDependency.resolve() gets called so we have to use a fake app delegate class in a testing environment.

First of all, create a new file in the test target. Define a new class named TestAppDelegate and implement basic requirements of the delegate protocol.

// iOS
classTestAppDelegate:NSObject,UIApplicationDelegate{varwindow:UIWindow?}
// macOS
classTestAppDelegate:NSObject,NSApplicationDelegate{}

Then create another file named main.swift to your application target. This file will replace the entry point of the application. We are going to provide different app delegates in this file. Don't forget to replace "MyAppTests.TestAppDelegate" with your project target and class name.

// iOS
UIApplicationMain(CommandLine.argc,CommandLine.unsafeArgv,NSStringFromClass(UIApplication.self),NSStringFromClass(NSClassFromString("MyAppTests.TestAppDelegate")??AppDelegate.self))
// macOS
func createAppDelegate()->NSApplicationDelegate{iflet cls =NSClassFromString("AllkdicTests.TestAppDelegate")as?(NSObject&NSApplicationDelegate).Type {return cls.init()}else{returnAppDelegate(dependency:AppDependency.resolve())}}letapplication=NSApplication.shared
application.delegate =createAppDelegate()
_ =NSApplicationMain(CommandLine.argc,CommandLine.unsafeArgv)

Finally, remove the @UIApplicationMain and @NSApplicationMain from the AppDelegate.

 // iOS
- @UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate
// macOS
- @NSApplicationMain
class AppDelegate: NSObject, NSApplicationDelegate

It is also a good practice to add a test case to verify that the application is using TestAppDelegate in a testing environment.

XCTAssertTrue(UIApplication.shared.delegate is TestAppDelegate)

Lazy Dependency

Using Factory

In Cocoa applications, view controllers are created lazily. For example, DetailViewController is not created until the user taps an item on ListViewController. In this case we have to pass a factory closure of DetailViewController to ListViewController.

/// A root view controller
classListViewController{vardetailViewControllerFactory:((Item)->DetailViewController)!func presentItemDetail(_ selectedItem:Item){letdetailViewController=self.detailViewControllerFactory(selectedItem)self.present(detailViewController, animated:true)}}staticfunc resolve()->AppDependency{letstoryboard=UIStoryboard(name:"Main", bundle:nil)letnetworking=Networking()letdetailViewControllerFactory:(Item)->DetailViewController={ selectedItem inletdetailViewController= storyboard.instantiateViewController(withIdentifier:"DetailViewController")as!DetailViewController
detailViewController.networking = networking
detailViewController.item = selectedItem
return detailViewController
}returnAppDependency(
networking: networking,
detailViewControllerFactory: detailViewControllerFactory
)}

But it has a critical problem: we cannot test the factory closure. Because the factory closure is created in the Composition Root but we should not access the Composition Root in a testing environment. What if I forget to inject the DetailViewController.networking property?

One possible approach is to create a factory closure outside of the Composition Root. Note that Storyboard and Networking is from the Composition Root, and Item is from the previous view controller so we have to separate the scope.

extensionDetailViewController{staticletfactory:(UIStoryboard,Networking)->(Item)->DetailViewController={ storyboard, networking inreturn{ selectedItem inletdetailViewController= storyboard.instantiateViewController(withIdentifier:"DetailViewController")as!DetailViewController
detailViewController.networking = networking
detailViewController.item = selectedItem
return detailViewController
}}}staticfunc resolve()->AppDependency{letstoryboard=...letnetworking=...return.init(
detailViewControllerFactory:DetailViewController.factory(storyboard, networking))}

Now we can test the DetailViewController.factory closure. Every dependencies are resolved in the Composition Root and a selected item can be passed from ListViewController to DetailViewController in runtime.

Using Configurator

There is another lazy dependency. Cells are created lazily but we cannot use the factory closure because the cells are created by the framework. We can just configure the cells.

Imagine that an UICollectionViewCell or UITableViewCell displays an image. There is an imageDownloader which downloads an actual image in a production environment and returns a mock image in a testing environment.

classItemCell{varimageDownloader:ImageDownloaderType?varimageURL:URL?{
didSet {guardlet imageDownloader =self.imageDownloader else{return}self.imageView.setImage(with:self.imageURL, using: imageDownloader)}}}

This cell is displayed in DetailViewController . DetailViewController should inject imageDownloader to the cell and sets the image property. Like we did in the factory, we can create a configurator closure for it. But this closure takes an existing instance and doens't have a return value.

classItemCell{staticletconfigurator:(ImageDownloaderType)->(ItemCell,UIImage)->Void={ imageDownloader
return{ cell, image in
cell.imageDownloader = imageDownloader
cell.image = image
}}}

DetailViewController can have the configurator and use it when configurating cell.

classDetailViewController{varitemCellConfigurator:((ItemCell,UIImage)->Void)?func collectionView(_ collectionView:UICollectionView, cellForItemAt indexPath:IndexPath)->UICollectionViewCell{...self.itemCellConfigurator?(cell, image)return cell
}}

DetailViewController.itemCellConfigurator is injected from a factory.

extensionDetailViewController{staticletfactory:(UIStoryboard,Networking,(ItemCell,UIImage)->Void)->(Item)->DetailViewController={ storyboard, networking, imageCellConfigurator inreturn{ selectedItem inletdetailViewController= storyboard.instantiateViewController(withIdentifier:"DetailViewController")as!DetailViewController
detailViewController.networking = networking
detailViewController.item = selectedItem
detailViewController.imageCellConfigurator = imageCellConfigurator
return detailViewController
}}}

And the Composition Root finally looks like:

staticfunc resolve()->AppDependency{letstorybard=...letnetworking=...letimageDownloader=...letlistViewController=...
listViewController.detailViewControllerFactory =DetailViewController.factory(
storyboard,
networking,ImageCell.configurator(imageDownloader))...}

Problem

Theoretically it works. But as you can see in the DetailViewController.factory it will be very complicated when there are many dependencies. This is why I created Pure. Pure makes factories and configurators neat.

Getting Started

Dependency and Payload

First of all, take a look at the factory and the configurator we used in the example code.

staticletfactory:(UIStoryboard,Networking,(ItemCell,UIImage)->Void)->(Item)->DetailViewControllerstaticletconfigurator:(ImageDownloaderType)->(ItemCell,UIImage)->Void

Those are the functions that return another function. The outer functions are executed in the Composition Root to inject static dependencies like Networking and the inner functions are executed in the view controllers to pass a runtime information like selectedItem. The parameter of the outer function is Dependency. The parameter of the inner function is Payload.

static let factory: (UIStoryboard, Networking, (ItemCell, UIImage) -> Void) -> (Item) -> DetailViewController
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^
Dependency Payload
static let configurator: (ImageDownloaderType) -> (ItemCell, UIImage) -> Void
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Dependency Payload

Pure generalizes the factory and configurator using Dependency and Payload.

Module

Pure treats every class that requires a dependency and a payload as a Module. A protocol Module requires two types: Dependency and Payload.

protocolModule{
/// A dependency that is resolved in the Composition Root.
associatedtypeDependency
/// A runtime information for configuring the module.
associatedtypePayload}

There are two types of module: FactoryModule and ConfiguratorModule.

Factory Module

FactoryModule is a generalized version of factory closure. It requires an initializer which takes both dependency and payload.

protocolFactoryModule:Module{init(dependency:Dependency, payload:Payload)}classDetailViewController:FactoryModule{structDependency{letstoryboard:UIStoryboardletnetworking:Networking}structPayload{letselectedItem:Item}init(dependency:Dependency, payload:Payload){}}

When a class conforms to FactoryModule, it will have a nested type Factory. Factory.init(dependency:) takes a dependency of the module and has a method create(payload:) which creates a new instance.

classFactory<Module>{letdependency:Module.Dependencyfunc create(payload:Module.Payload)->Module}
// In AppDependency
letfactory=DetailViewController.Factory(dependency:.init(
storyboard: storyboard
networking: networking
))
// In ListViewController
letviewController= factory.create(payload:.init(
selectedItem: selectedItem
))

Configurator Module

ConfiguratorModule is a generalized version of configurator closure. It requires a configure() method which takes both dependency and payload.

protocolConfiguratorModule:Module{func configure(dependency:Dependency, payload:Payload)}classItemCell:ConfiguratorModule{structDependency{letimageDownloader:ImageDownloaderType}structPayload{letimage:UIImage}func configure(dependency:Dependency, payload:Payload){self.imageDownloader = dependency.imageDownloader
self.image = payload.image
}}

When a class conforms to ConfiguratorModule, it will have a nested type Configurator. Configurator.init(dependency:) takes a dependency of the module and has a method configure(_:payload:) which configures an existing instance.

classConfigurator<Module>{letdependency:Module.Dependencyfunc configure(_ module:Module, payload:Module.Payload)}
// In AppDependency
letconfigurator=ItemCell.Configurator(dependency:.init(
imageDownloader: imageDownloader
))
// In DetailViewController
configurator.configure(cell, payload:.init(image: image))

With FactoryModule and ConfiguratorModule, the example can be refactored as below:

staticfunc resolve()->AppDependency{letstorybard=...letnetworking=...letimageDownloader=...return.init(
detailViewControllerFactory:DetailViewController.Factory(dependency:.init(
storyboard: storyboard,
networking: networking,
itemCellConfigurator:ItemCell.Configurator(dependency:.init(
imageDownloader: imageDownloader
)))))}

Customizing

Factory and Configurator are customizable. This is an example of customized factory:

extensionFactorywhere Module ==DetailViewController{func create(payload:Module.Payload, extraValue:ExtraValue)->Payload{letmodule=self.create(payload: payload)
module.extraValue = extraValue
return module
}}

Storyboard Support

FactoryModule can support Storyboard-instantiated view controllers using customizing feature. The code below is an example for storyboard support of DetailViewController:

extensionFactorywhere Module ==DetailViewController{func create(payload:Module.Payload)->Payload{letmodule=self.dependency.storyboard.instantiateViewController(withIdentifier:"DetailViewController")as!Module
module.networking = dependency.networking
module.itemCellConfigurator = dependency.itemCellConfigurator
module.selectedItem = payload.selectedItem
return module
}}

URLNavigator Support

URLNavigator is an elegant library for deeplink support. Pure can be also used in registering a view controller to a navigator.

classUserViewController{structPayload{letuserID:Int}}extensionFactorywhere Module ==UserViewController{func create(url:URLConvertible, values:[String:Any], context:Any?)->Module?{guardlet userID =values["id"]else{returnnil}returnself.create(payload:.init(userID: userID))}}letnavigator=Navigator()
navigator.register("myapp://user/<id>",UserViewController.Factory().create)

Installation

• Using CocoaPods:

  pod'Pure'

• Carthage is not yet supported.

Contribution

Any discussions and pull requests are welcomed 💖

• To development:

  $ make project

• To test:

  $ swift test

License

Pure is under MIT license. See the LICENSE file for more info.