Protocols

This is an abstract protocol representing an Interactor object and Interactor objects should not conform to this directly.

See more

public protocol AbstractInteractable<Request> : AnyObject

A protocol that represents the configuration for a collection of Action objects, either a group of actions running in parallel, or a sequence of actions running in serial order.

Types conforming to this protocol hold multiple ActionConfiguring child configurations under one umbrella. When perform(with:sequenceOutputs:) is called on an ActionPerformableCollection object, it runs the child actions. If this object is an ActionGroup, the results are then merged by the merger object into a single ContentType value, which the group’s output conduit passes on to the next step in the sequence, if one exists.

ActionGroupConfiguration is the primary concrete conforming type.

See more

@MainActor
public protocol ActionCollectionConfiguring<InteractorType, ContentType> : ActionConfiguring

This protocol represents an object that can be used to configure an Action for use in an ActionPerformableCollection object.

See more

@MainActor
public protocol ActionConfiguring<InteractorType, ContentType>

This protocol represents a type which can be used to identify an ActionPerformable object.

Providing a type for steps is optional, but useful when a sequence contains multiple steps whose results share the same content type. For example, two network requests of different API endpoints may return the same model and you need to handle them differently. String conforms to this protocol out of the box, or you can conform your own enum for type-safe lookups.

public protocol ActionIdentifying : Hashable, Sendable

A protocol that defines an object which can perform an action as part of an ActionPerformableCollection object. This action generally represents a single Interactor request.

Conforming types represent discrete, async steps in a sequence or one of several parallel tasks in a group. Each step receives accumulated outputs from prior steps and returns an updated ActionCollectionResults object, enabling a chain of actions to build on each other’s results.

See more

@MainActor
public protocol ActionPerformable<ContentType> : AnyObject, Sendable

A protocol that defines a collection of ActionPerformable objects that can be run together, such as a sequence or group.

Conforming types manage an ordered or grouped set of actions sharing the same ContentType, and are responsible for performing them and accumulating their results into an ActionCollectionResults object.

See more

@MainActor
public protocol ActionPerformableCollection<ContentType> : ActionPerformable

This protocol represents objects that merge the results of an ActionGroup‘s child actions into a single content value which is passed on through the group’s output conduit. This merging step is necessary in order for an ActionGroup to participate in the action sequence, as the sequence expects a single ContentType value to be passed from action to action.

See more

@MainActor
public protocol ActionResultsMerging<ContentType>

A protocol that defines a conduit between steps in an action sequence.

Conduit objects that conform to this protocol receive the output of the current sequence step action and optionally transform the output into a data form the next action can use the next action in the sequence, before then injecting the output into the next step in the sequence.

See more

@MainActor
public protocol ActionSequenceConduiting<ContentType>

A narrow, type-erased entry point for assigning an interactor assistant to a Destination.

This exists so callers holding any InteractorConfiguring<InteractorType> can dispatch the assignment without exposing the configuration’s Interactor associated type (and the Interactor.Request.ResultData == Destination.ContentType constraint that would otherwise be required at the call site).

See more

@MainActor
public protocol AssistantAssigning

This protocol represents a datasource Interactor actor. Datasources are designed to provide data models to a Destination based on requests, such as requesting objects from a server for display in a navigation stack. For more information on Interactors, please see the documentation for Interactable.

See more

public protocol AsyncDatasourceable<Item> : AsyncInteractable

Undocumented

See more

public protocol AsyncInteractable<Request> : AbstractInteractable, Actor

See more

This protocol represents an assistant which helps a Destination make requests of an Interactor which participates in async/await flows. Concrete assistants conforming to this protocol should handle requests for a specific Interactor type.

See more

@MainActor
public protocol AsyncInteractorAssisting<InteractorType, ContentType> : InteractorAssisting

A protocol that defines a condition used to select a branch path in an ActionBranch step.

When an ActionBranch runs, it evaluates each BranchConditionable condition in order by calling their evaluate(content:) method and selects the first case whose condition returns true. This protocol also provides an implementation of negated() so that a the same condition can be used in the inverse sense (i.e. “is online” vs. “is offline”).

Implement this protocol to define reusable, named conditions:

struct HasImagesCondition: BranchConditionable {
    func evaluate(content: AppContent?) -> Bool {
        guard case .images(let images) = content else { return false }
        return !images.isEmpty
    }
}

See more

@MainActor
public protocol BranchConditionable<ContentType>

A protocol that defines an object capable of transforming a value of one type into a value of another type.

Conforming types receive a value of the associated Input type, apply a transformation to it, and return a value of the associated Output type. The transformation may throw if the input is invalid or the transformation cannot be completed.

This protocol serves two roles in an ActionSequence:

• Transforming a sequence step’s output for the next step, via step(_:inputTransformer:) or an ActionBranchConfiguration‘s transformer parameter. In this role Input and Output are typically the same type: the transformation changes the value, not the type (e.g. an array of images into an array of file models, both cases of the same content enum).
• Converting an Interactor’s raw request result into a sequence step’s ContentType, via ActionConfiguration’s resultTransformer parameter. This is only needed when an Interactor’s Request.ResultData type differs from the step’s ContentType. For example, an API Interactor might define its own ResultData enum whose cases represent each supported endpoint, and a transformer packages that into the ContentType used elsewhere in the sequence.

Example: transforming a sequence step’s output

In this example transformer we’re taking an array of images as input and transforming them into an array of models containing the image data and filenames to save them to. Since this transforms a step’s output for use by the next step, Input and Output are both inferred as AppContentType.

struct ImageFileTransformer: ContentTransformable {
    func transform(input: AppContentType) throws -> AppContentType {
        guard case .images(let images) = input else { return input }

        let timestamp = Int(Date().timeIntervalSince1970)
        let models: [DataModel] = try images.enumerated().map { index, image in
            guard let data = image.pngData() else {
                throw SequenceDemoError.invalidImage
            }
            return DataModel(data: data, fileName: "fetched-image-\(timestamp)-\(index).png")
        }
    }
}

Example: converting an Interactor’s result

Here we’re taking a FilterResultType value returned by an image-filtering Interactor and converting it into the AppContentType used throughout the rest of the sequence. ResultData (FilterResultType) and ContentType (AppContentType) are inferred as different types.

struct ApplyImageFilterResultTransformer: ContentTransformable {
    func transform(input: FilterResultType) throws -> AppContentType {
        switch input {
            case .filteredImages(let urls):
                return .savedFiles(urls: urls)
        }
    }
}

See more

@MainActor
public protocol ContentTransformable<Input, Output> : Sendable

This protocol represents a delegate object that provides status updates during the retrieval of items by a Datasourceable object.

See more

public protocol DatasourceItemsProviderStatusDelegate : AnyObject

This protocol represents a datasource Interactor. Datasources are designed to provide data models to a Destination based on simple data fetches, such as requesting objects from a server for display in a navigation stack. For more information on Interactors, please see the documentation for Interactable.

See more

public protocol Datasourceable<Item> : Interactable

This protocol represents an object that holds Destination presentation objects.

See more

public protocol DestinationConfigurationsContaining<EventType, DestinationType, TabType, ContentType>

This protocol defines methods that an object should implement to receive updates from DestinationInterfaceCoordinator objects.

See more

@MainActor
public protocol DestinationInterfaceCoordinatorDelegate : AnyObject

This abstract protocol represents an object that coordinates the presentation of a Destination within a UI framework.

See more

@MainActor
public protocol DestinationInterfaceCoordinating

A protocol representing a user interface object that is handled by Destinations. This is typically a View in SwiftUI or a UIViewController in UIKit.

See more

@MainActor
public protocol DestinationInterfacing<DestinationType, ContentType, TabType>

This protocol represents classes which the internal state of classes conforming to the Destinationable protocol.

See more

public protocol DestinationInternalStateable<EventType, DestinationType, TabType, ContentType, InteractorType>

This protocol represents a Destination navigator path object. It should be implemented to allow for system-level navigation stacks like SwiftUI’s NavigationStack into the Destinations ecosystem, which the DestinationNavigator class implements.

See more

@MainActor
public protocol DestinationPathNavigating : AnyObject

This is an abstract protocol which defines Provider classes which build and provide new Destination objects, including their interface elements. Each Provider should be responsible for building a unique Destination and its associated interface.

See more

@MainActor
public protocol DestinationProviding

This protocol represents an interface’s state object which holds a reference to its associated Destination.

See more

@MainActor
public protocol DestinationStateable<Destination, StateModel> : AnyObject

This protocol represents a Destination in the Destinations ecosystem.

A Destination represents a unique area in an app which can be navigated to by the user. In SwiftUI this is typically a fullscreen View object, and in UIKit it’s a UIViewController class or subclass, but it can also be a group of Destinations like a TabBar or a carousel. Destinations hold references to the UI element they’re associated with, but they don’t handle the particulars of laying out elements on the screen. Instead, the role of Destination objects in the ecosystem is to send and receive messages and datasource requests on behalf of their UI, such as passing on a message to trigger an action when a user taps a button.

In most cases you should be able to use the provided ViewDestination or ControllerDestination classes for SwiftUI or UIKit apps respectively. They are customized to a particular Destination through generic arguments. To handle presentation requests that require specialized configuration or need to handle content models, you can create custom assistants which conform to the InterfaceActionConfiguring protocol. To handle requests to an interactor, you can create assistants which conform to the InteractorAssisting protocol. There are more specific classes to support interfaces like TabBars, but you can also use your own Destination classes by conforming to ViewDestinationable or ControllerDestinationable if you should need custom functionality or just want to avoid using generics.

There is a two-way connection between a Destination and its interface which is handled by a DestinationStateable-conforming object. Destinations comes with a DestinationInterfaceState object which can be used for this purpose, though you can create your own class if you’d like to store other state in it. When a Destination is removed from the ecosystem, cleanup is done internally to ensure no retain cycles occur.

See more

@MainActor
public protocol Destinationable<DestinationType, ContentType, TabType> : AssistantAssigning, InteractorResultHandling, Identifiable

This protocol represents Flow objects which coordinate routing, navigation, and the management of Destination objects as a user moves through an app’s interface.

Flows manage the creation, appearance, and removal of Destinations as a user navigates through the app. They are the single source of truth for what Destinations currently exist in the ecosystem. Typically you don’t interact with them directly after they’ve been configured. In most cases you can use one of the provided ViewFlow or ControllerFlow classes for SwiftUI and UIKit apps respectively.

See more

@MainActor
public protocol Flowable : AnyObject, Observable

This protocol represents classes which holds internal state specific to the GroupedDestinationable protocol.

See more

public protocol GroupDestinationInternalStateable<DestinationType, ContentType, TabType>

This abstract protocol represents a type of Destination which manages child Destinations, such as a NavigationStack in SwiftUI.

See more

@MainActor
public protocol GroupedDestinationable<DestinationType, ContentType, TabType> : AnyObject

This protocol represents Interactors that handle requests using a synchronous context, typically providing results for requests via a InteractorResponseClosure.

Interactors provide an interface to perform some business logic, often acting as a datasource by interfacing with an API, handling system APIs, or some other self-contained work.

The concept of Interactors comes from Clean Swift, used in its architecture as a way to move logic and datasource management out of view controllers. In Destinations, the Interactable protocol represents Interactor objects which provide an interface to perform some logic or data request, typically by interfacing with an backend API, handling system APIs, or some other self-contained work. Datasourceable inherits from this protocol and should be used for objects which specifically represent a datasource of some kind. There are also Actor-based async versions of these protocols available.

Though requests to Interactors can be made using a Destination’s performRequest method, in general one should use the performAction method. This abstracts the specific implementation details of an interactor away from the interface and lets it focus on making requests through a standardized request.

The recommended way is to assign an event type to your request and using an InteractorAssisting-conforming assistant to configure the request, leaving the Destination’s interface free of associated business logic.

Interactors are typically created by Destination providers and stored in the Destination. Like with presentations of new Destinations, Interactor requests are associated with a particular InterfaceAction object and are represented by an InteractorConfiguration model object. Action types for each Interactor are defined as enums, keeping Interactor-specific knowledge out of the interface.

For example, here we’re creating an Interactor action for making a pagination request to the ColorsDatasource, and then assign it to a moreButton event type:

 let paginateAction = InteractorConfiguration<ColorsListProvider.InteractorType, ColorsDatasource>(interactorType: .colors, actionType: .paginate, assistantType: .basic)
 let colorsProvider = ColorsListProvider(interactorsData: [.moreButton: paginateAction])

And here is that event type being called by a Destination’s interface. Note that performAction can throw and the Destination method handleThrowable automatically handles that for you, logging any errors to the console with the built-in Logger class.

destination().handleThrowable {
   try destination().performAction(eventType: .moreButton)
}

See more

public protocol Interactable<Request> : AbstractInteractable

This protocol represents an assistant which helps a Destination make requests of an Interactor. Concrete assistants conforming to this protocol should handle requests for a specific Interactor type.

See more

@MainActor
public protocol InteractorAssisting<InteractorType, ContentType> : Sendable

This protocol represents a configuration for a specific action an Interactor should take.

See more

@MainActor
public protocol InteractorConfiguring<InteractorType>

This protocol represents an Interactor configuration model which defines a request to perform an action.

See more

public protocol InteractorRequestConfiguring : Sendable

This protocol represents an enum which defines types of actions for a particular Interactor.

public protocol InteractorRequestActionTypeable : Hashable, Sendable

A protocol that defines an interface for performing Interactor requests and handling their results.

Conforming types are generally type-erased Destinations that dispatch requests to Interactors and process the Result objects that their operations return. This allows Interactor assistants to be reused across different Destination objects instead of being tightly coupled to one.

See more

@MainActor
public protocol InteractorResultHandling<InteractorType, ContentType> : AnyObject, Sendable

This protocol represents an assistant which configures an InterfaceAction object that should present a Destination. This is typically used in conjunction with a Destination such as ControllerDestination or ViewDestination.

See more

@MainActor
public protocol InterfaceActionConfiguring<EventType, DestinationType, ContentType>

This protocol represents an interface’s state object, holding a reference to its associated Destination and a navigator object which manages the state of the interface’s navigation stack.

See more

@MainActor
public protocol NavigationDestinationStateable<Destination> : DestinationStateable

This protocol represents a state model associated with a Destination.

See more

@MainActor
public protocol StateModeling<Destination> : AnyObject

This protocol represents an object that coordinates the presentation of a Destination within the SwiftUI framework.

See more

@MainActor
public protocol DestinationSwiftUICoordinating : DestinationInterfaceCoordinating

This protocol represents a type of Destination which manages child Destinations in a SwiftUI project.

@MainActor
public protocol GroupedViewDestinationable<DestinationType, ContentType, TabType> : GroupedDestinationable, ViewDestinationable

A protocol representing a SwiftUI View that is associated with a Destination and contains a NavigationStack.

See more

@MainActor
public protocol NavigatingDestinationInterfacing<DestinationType, ContentType, TabType> : ViewDestinationInterfacing where Self.DestinationState : NavigationDestinationStateable

This protocol represents a type of Destination which manages a SwiftUI NavigationStack.

See more

@MainActor
public protocol NavigatingViewDestinationable<DestinationType, ContentType, TabType> : GroupedViewDestinationable where Self.ViewType : NavigatingDestinationInterfacing

A protocol defining a SwiftUI View which handles a NavigationSplitView and conforms to Destinations.

@MainActor
public protocol NavigationSplitViewDestinationInterfacing : ViewDestinationInterfacing where Self.Destination : NavigationSplitViewDestinationable

This protocol represents a Destination whose interface View handles a NavigationSplitView.

See more

@MainActor
public protocol NavigationSplitViewDestinationable<DestinationType, ContentType, TabType> : GroupedViewDestinationable where Self.ViewType : NavigationSplitViewDestinationInterfacing

This protocol configures the presentation of a SwiftUI sheet.

See more

public protocol SheetPresentationConfiguring : Equatable, Identifiable

This protocol represents a StateModeling-conforming object attached to a View that supports presenting a SwiftUI sheet via its SheetPresenter object.

To present a sheet using Destinations, simply have the View‘s state model adopt this protocol, add the built-in ViewModifier .destinationSheet(stateModel.sheetPresentation)) to the View, and present a Destination with a presentationType of .sheet(type: .present).

See more

@MainActor
public protocol SheetPresenting : StateModeling where Self.Destination : ViewDestinationable

This protocol represents a model used for presenting a SwiftUI sheet element.

See more

public protocol Sheetable : Identifiable

A protocol defining a SwiftUI View which handles a TabView and conforms to Destinations.

See more

@MainActor
public protocol TabBarViewDestinationInterfacing<TabType> : TabBarDestinationInterfacing, ViewDestinationInterfacing where Self.Destination : TabBarViewDestinationable

This protocol represents a Destination whose interface view handles a TabBar.

See more

@MainActor
public protocol TabBarViewDestinationable<DestinationType, ContentType, TabType> : GroupedViewDestinationable

A protocol representing a SwiftUI View that is associated with a Destination.

See more

@MainActor
public protocol ViewDestinationInterfacing<DestinationType, ContentType, TabType> : DestinationInterfacing, View where Self.Destination : ViewDestinationable

This protocol represents objects which construct and provide ViewDestinationable objects, including their associated interface elements. Provider objects which conform to this protocol should build discrete Destinations based on their specific destination type.

See more

@MainActor
public protocol ViewDestinationProviding<DestinationType, ContentType, TabType> : DestinationProviding where Self.PresentationType == DestinationPresentationType<Self.DestinationType, Self.ContentType, Self.TabType>

This protocol represents a Destination which is associated with a SwiftUI View.

See more

@MainActor
public protocol ViewDestinationable<DestinationType, ContentType, TabType> : Destinationable

This protocol represents a Flow which coordinates routing and navigation as a user moves through a SwiftUI-based app.

See more

@MainActor
public protocol ViewFlowable<DestinationType, ContentType, TabType> : Flowable where Self.InterfaceCoordinator == DestinationSwiftUICoordinator, Self.PresentationType == DestinationPresentationType<Self.DestinationType, Self.ContentType, Self.TabType>

This protocol represents a View that manages a TabBar.

@MainActor
public protocol TabBarDestinationInterfacing : DestinationInterfacing

This protocol represents an enum describing the types of content that are able to be sent through Destinations.

public protocol ContentTypeable : Equatable, Sendable

This protocol represents an enum which defines Destination presentation types.

See more

@MainActor
public protocol DestinationPresentationTypeable

This protocol represents enums which define event types associated with a Destination.

See more

public protocol EventTypeable : CaseIterable, Hashable, Sendable

This protocol represents an enum which defines Interactors in the app. It can be scoped to an individual Destination.

public protocol InteractorTypeable : Hashable, Sendable

This protocol represents an enum which defines Destination types for an app which can be routed to.

See more

public protocol RoutableDestinations : CaseIterable, Hashable

A protocol representing an enum which defines tabs for a tab bar interface.

See more

public protocol TabTypeable : CaseIterable, Hashable where Self.AllCases : RandomAccessCollection

A protocol representing UIViewControllers which conform to Destinations

See more

@MainActor
public protocol ControllerDestinationInterfacing : UIViewController, DestinationInterfacing

This protocol represents a UINavigationController that is associated with a Destination.

@MainActor
public protocol NavigationControllerDestinationInterfacing : UINavigationController, ControllerDestinationInterfacing where Self.DestinationState : NavigationDestinationStateable

This protocol represents objects which construct and provide ControllerDestinationable objects, including their associated interface elements. Provider objects which conform to this protocol should build discrete Destinations based on their specific destination type.

See more

@MainActor
public protocol ControllerDestinationProviding<DestinationType, ContentType, TabType> : DestinationProviding where Self.PresentationType == DestinationPresentationType<Self.DestinationType, Self.ContentType, Self.TabType>

This protocol represents a Destination which is associated with a UIViewController.

See more

@MainActor
public protocol ControllerDestinationable<DestinationType, ContentType, TabType> : Destinationable

This protocol represents a Flow which coordinates routing and navigation as a user moves through a UIKit-based app.

See more

@MainActor
public protocol ControllerFlowable<DestinationType, ContentType, TabType> : Flowable where Self.InterfaceCoordinator == DestinationUIKitCoordinator, Self.PresentationType == DestinationPresentationType<Self.DestinationType, Self.ContentType, Self.TabType>

This protocol represents an object that coordinates the presentation of a Destination within the UIKit framework.

See more

@MainActor
public protocol DestinationUIKitCoordinating : DestinationInterfaceCoordinating, UINavigationControllerDelegate

This protocol represents a type of Destination which manages child Destinations in a UIKit project.

@MainActor
public protocol GroupedControllerDestinationable<DestinationType, ContentType, TabType> : ControllerDestinationable, GroupedDestinationable

This protocol represents a Destination whose interface is a UINavigationController.

See more

@MainActor
public protocol NavigatingControllerDestinationable<DestinationType, ContentType, TabType> : GroupedControllerDestinationable where Self.ControllerType : NavigationControllerDestinationInterfacing

A protocol representing a UISplitViewController class which conforms to Destinations.

@MainActor
public protocol SplitViewControllerDestinationInterfacing : UISplitViewController, ControllerDestinationInterfacing where Self.Destination : SplitViewControllerDestinationable

This protocol represents a Destination whose interface is a UISplitViewController.

See more

@MainActor
public protocol SplitViewControllerDestinationable<DestinationType, ContentType, TabType> : GroupedControllerDestinationable where Self.ControllerType : UISplitViewController

This protocol represents an object that adapts a SwiftUI View for use inside a UIViewController.

See more

@MainActor
public protocol SwiftUIAdaptable

This protocol represents the Destination of a UIKit controller which hosts SwiftUI content.

See more

@MainActor
public protocol SwiftUIContainerDestinationable<DestinationType, ContentType, TabType> : ControllerDestinationable

This protocol represents a controller that serves as a container for a SwiftUI View.

See more

@MainActor
public protocol SwiftUIContainerInterfacing<Content> : ControllerDestinationInterfacing

This protocol represents a SwiftUI View that is hosted by a container controller within UIKit.

See more

@MainActor
public protocol SwiftUIHostedInterfacing : ViewDestinationInterfacing

A protocol representing a UITabBarController class which conforms to Destinations.

See more

@MainActor
public protocol TabBarControllerDestinationInterfacing<TabType> : UITabBarController, ControllerDestinationInterfacing, TabBarDestinationInterfacing where Self.Destination : TabBarControllerDestinationable

This protocol represents a Destination whose interface is a UITabBarController.

See more

@MainActor
public protocol TabBarControllerDestinationable<DestinationType, ContentType, TabType> : GroupedControllerDestinationable