Scopes

Defining the key actors at the composition root includes defining their lifecycle or scope. Pilgrim provides the following:

objectGraph (default)

This scope means that when an instance is assembled, any dependencies will be treated as shared instances during assembly. Once resolution is complete they are no longer retained. This allows instantiating an entire object graph, for a use-case (say for a ViewController), and then discarding it when that use-case has completed.

For example, here we'll wire up a delegate:

func weatherReportController() -> WeatherReportViewController {
    objectGraph{
        WeatherReportViewController(view: weatherReportView(), weatherClient: coreComponents.weatherClient(),
                weatherReportRepo: coreComponents.weatherReportRepository(),
                cityRepo: coreComponents.cityRepository(), assembly: self)
    }
}

func weatherReportView() -> WeatherReportView {
    objectGraph(WeatherReportView(frame: CGRect.zero)) { [self] (view: WeatherReportView) in
        view.theme = themeAssembly.currentTheme()
        view.delegate = weatherReportController()
    }
} 

Because we have an object graph scope, if we resolve the weatherReportController from the assembly the delegate property on the view controller will be resolved to the same weatherReportViewController() instance. This holds for complex nested object graphs too.

The view controller that gets injected into the view's delegate property as a circular dependency will be the same instance that was declared above. This also applies with complex object graphs, as well as . . .

shared

Indicates that Pilgrim should retain the instance effectively creating a singleton (but without the drawbacks).

func rootViewController() -> RootViewController {
    shared {
        RootViewController(mainContentViewController: weatherReportController(), assembly: self)
    }
}

weakShared

Indicates that a shared instance should be created as long as necessary. When your application's classes stop referencing this component it will be deallocated until needed again.

func knight() -> Knight {
  weakShared(Knight(quest: damselInDistressQuest()))
}

unShared

Indicates that a new instance should always be created.