Destinationable

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

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.

  • An enum which defines event types for this Destination’s interface.

    Declaration

    Swift

    associatedtype EventType : EventTypeable

  • An enum which defines all routable Destinations in the app.

    Declaration

    Swift

    associatedtype DestinationType : RoutableDestinations

  • An enum which defines types of tabs in a tab bar.

    Declaration

    Swift

    associatedtype TabType : TabTypeable

  • An enum which defines available Destination presentation types.

    Declaration

    Swift

    typealias PresentationType = DestinationPresentationType<DestinationType, ContentType, TabType>

  • An enum which defines the types of content that are able to be sent through Destinations. A type of AppDestinationConfigurations which handles Destination presentation configurations.

    Declaration

    Swift

    typealias DestinationConfigurations = AppDestinationConfigurations<EventType, DestinationType, ContentType, TabType>

  • A type of AppDestinationConfigurations which handles system navigation events.

    Declaration

    Swift

    typealias NavigationConfigurations = AppDestinationConfigurations<SystemNavigationType, DestinationType, ContentType, TabType>
  • id

    The unique identifier for this Destination.

    Declaration

    Swift

    @MainActor
var id: UUID { get }

  • This enum value conforming to RoutableDestinations represents a specific Destination type.

    Declaration

    Swift

    @MainActor
var type: DestinationType { get }

  • State object for handling functionality for the Destinations ecosystem.

    Declaration

    Swift

    @MainActor
var internalState: DestinationInternalState<EventType, DestinationType, ContentType, TabType, InteractorType> { get set }
  • stateModel Default implementation

    A state model that handles business logic and view state for this Destination.

    Default Implementation

    Declaration

    Swift

    @MainActor
var stateModel: (any StateModeling<Self>)? { get set }
  • performAction(for:content:) Default implementation

    Performs the action associated with the specified event type. This action could be a Destination presentation or a request to an Interactor. The response is returned with a delegate pattern in handleInteractorResult(result:for:).

    This is the method to use for Destination presentations.

    Default Implementation

    Declaration

    Swift

    @MainActor
func performAction(for eventType: EventType, content: ContentType?) throws

    Parameters

    eventType

    The event type whose action should be run.
    content

    Optional content to use with the action.
  • performAction(for:content:) Default implementation, asynchronous

    Asynchronously performs the Interactor action associated with the specified event type and returns its Result.

    If a result transformer is registered for this event type, it’s used to convert the Interactor’s Request.ResultData into ContentType. Otherwise a direct cast is attempted, which succeeds when the two types are the same.

    Important

    Use this method for event types bound to an Interactor. If the event type is bound to a presentation, this method performs the presentation and then returns presentationResultNotSupported(message:), because presentations have no result value to return. That error doesn’t mean the presentation failed. The method also doesn’t wait for the presented interface to appear on screen. Use the throwing performAction(for:content:) for presentation events. This behavior for presentations may change in a future version.

    Default Implementation

    Declaration

    Swift

    @MainActor
func performAction(for eventType: EventType, content: ContentType?) async -> Result<ContentType, Error>

    Parameters

    eventType

    The event type whose action should be run.
    content

    Optional content to use with the action.
  • performActions(for:content:) Default implementation, asynchronous

    Performs the action sequence associated with the specified event type, running each of its Interactor actions in order and passing the result of each action to the next one through its output conduit. The sequence will run until either all actions have completed, an action returns an error, or the sequence is cancelled.

    The event type should be associated with a configuration conforming to ActionCollectionConfiguring, such as an ActionSequenceConfiguration or an ActionGroupConfiguration. For an event associated with a single InteractorConfiguration, use performAction(for:content:) instead; this method returns incompatibleType(message:) for it.

    Default Implementation

    Declaration

    Swift

    @MainActor
func performActions(for eventType: EventType, content: ContentType?) async -> Result<ActionCollectionResults<ContentType>, any Error>

    Parameters

    eventType

    The event type corresponding to the action sequence to be run.
    content

    Optional content to pass to the sequence. Each step in the sequence determines how this content should be used, but generally it should be passed in with the first action’s Interactor request.

    Return Value

    A Result containing an ActionSequenceResults object which holds the results of each completed action, or an Error if the sequence could not be built or one of its actions failed. If the sequence was cancelled, the failure contains an cancelled(partialResults:) error holding the results of any actions which completed before cancellation occurred.

  • performActions(configuration:content:) Default implementation, asynchronous

    Performs a custom action sequence using the provided configuration, running each of its Interactor actions in order and passing the result of each action to the next one through its output conduit. The sequence will run until either all actions have completed, an action returns an error, or the sequence is cancelled.

    Use this overload when you want to supply a sequence configuration directly rather than relying on one pre-registered with the event type.

    Important

    Use of this method (and the lack of eventType to reference in cancelActionSequence(for:)-1z0z5 means that the caller responsible for task cancellation by saving the Task wrapping this method to a property and calling Task.cancel() on it.

    Default Implementation

    Declaration

    Swift

    @MainActor
func performActions(configuration: any ActionCollectionConfiguring<InteractorType, ContentType>, content: ContentType?) async -> Result<ActionCollectionResults<ContentType>, any Error>

    Parameters

    configuration

    An object conforming to ActionCollectionConfiguring which defines the sequence of Interactor actions to run.
    content

    Optional content to pass to the sequence. Each step in the sequence determines how this content should be used, but generally it should be passed in with the first action’s Interactor request.

    Return Value

    A Result containing an ActionSequenceResults object which holds the results of each completed action, or an Error if the sequence could not be built or one of its actions failed. If the sequence was cancelled, the failure contains an cancelled(partialResults:) error holding the results of any actions which completed before cancellation occurred.

  • cancelAllActionSequences() Default implementation

    Cancels all in-progress action sequences on this Destination. This is called automatically by a Flow when this Destination is removed from it.

    Default Implementation

    Declaration

    Swift

    @MainActor
func cancelAllActionSequences()

  • Performs the action associated with the specified event type.

    Default Implementation

    Declaration

    Swift

    @available(*, deprecated, renamed: "performAction(for:content:﹚", message: "This method is deprecated and will be removed in a future version. Please migrate your code to use the `performAction(for:content:﹚` method instead.")
@MainActor
func performInterfaceAction(eventType: EventType, content: ContentType?) throws

    Parameters

    eventType

    The event type whose action should be run.
    content

    Optional content to use with the action.

  • Builds the InterfaceAction objects to handle Destination presentations generated by this Destination. This should be called when configuring a Destination for presentation, typically from a Flowable object.

    Default Implementation

    Declaration

    Swift

    @MainActor
func buildInterfaceActions(presentationClosure: @escaping (_ configuration: DestinationPresentation<DestinationType, ContentType, TabType>) -> Void)

    Parameters

    presentationClosure

    The presentation closure to be used in building the InterfaceAction objects.

  • Builds an InterfaceAction object to handle the specified Destination presentation.

    Default Implementation

    Declaration

    Swift

    @MainActor
func buildInterfaceAction(presentationClosure: @escaping (DestinationPresentation<DestinationType, ContentType, TabType>) -> Void, configuration: DestinationPresentation<DestinationType, ContentType, TabType>, eventType: EventType) -> InterfaceAction<EventType, DestinationType, ContentType>

    Parameters

    presentationClosure

    A presentation closure to be used in building the InterfaceAction object.
    configuration

    A model object used to configure the presentation.
    eventType

    The event type associated with this presentation.

    Return Value

    An InterfaceAction object for this presentation.

  • Builds the InterfaceAction objects to handle requests for this Destination’s interactors.

    Default Implementation

    Declaration

    Swift

    @MainActor
func buildInteractorActions(presentationClosure: @escaping (_ configuration: DestinationPresentation<DestinationType, ContentType, TabType>) -> Void)

    Parameters

    presentationClosure

    The presentation configuration object closure. Currently this is unused.

  • Updates the interface actions associated with this Destination.

    Declaration

    Swift

    @MainActor
func updateInterfaceActions(actions: [InterfaceAction<EventType, DestinationType, ContentType>])

    Parameters

    closures

    An array of InterfaceAction objects containing user interaction closures to be run.

  • Builds the system navigation actions. This should be called when configuring a Destination for presentation, typically from a Flowable object.

    Default Implementation

    Declaration

    Swift

    @MainActor
func buildSystemNavigationActions(presentationClosure: @escaping (DestinationPresentation<DestinationType, ContentType, TabType>) -> Void)

    Parameters

    presentationClosure

    A closure passing in a presentation configuration object to be used in building the system navigation closures.

  • Builds a system navigation action.

    Default Implementation

    Declaration

    Swift

    @MainActor
func buildSystemNavigationAction(presentationClosure: @escaping (DestinationPresentation<DestinationType, ContentType, TabType>) -> Void, configuration: DestinationPresentation<DestinationType, ContentType, TabType>, navigationType: SystemNavigationType) -> InterfaceAction<SystemNavigationType, DestinationType, ContentType>

    Parameters

    presentationClosure

    A closure which helps build the associated InterfaceAction.
    configuration

    A model object which helps configure the system navigation action.
    navigationType

    The type of system navigation event associated with this action.

    Return Value

    An InterfaceAction object for this system event.

  • Updates the system navigation closures associated with this Destination.

    Declaration

    Swift

    @MainActor
func updateSystemNavigationActions(actions: [InterfaceAction<SystemNavigationType, DestinationType, ContentType>])

    Parameters

    closures

    An array of InterfaceAction objects containing system navigation closures to be run.
  • presentation(presentationID:) Default implementation

    Returns a presentation configuration object based on its identifier.

    Default Implementation

    Declaration

    Swift

    @MainActor
func presentation(presentationID: UUID) -> (DestinationPresentation<DestinationType, ContentType, TabType>)?

    Parameters

    presentationID

    The identifier of a presentation configuration object.

    Return Value

    The configuration object, or nil if the specified object was not found.

  • Returns a system navigation configuration object based on its identifier.

    Default Implementation

    Declaration

    Swift

    @MainActor
func systemNavigationPresentation(presentationID: UUID) -> (DestinationPresentation<DestinationType, ContentType, TabType>)?

    Parameters

    presentationID

    The identifier of a presentation configuration object.

    Return Value

    The system navigation configuration object, if one was found.

  • presentation(for:) Default implementation

    Returns a presentation configuration object based on its associated user interaction event type.

    Default Implementation

    Declaration

    Swift

    @MainActor
func presentation(for eventType: EventType) -> (DestinationPresentation<DestinationType, ContentType, TabType>)?

    Parameters

    eventType

    The user interaction event type.

    Return Value

    The configuration object, or nil if the specified object was not found.

  • systemNavigationPresentation(for:) Default implementation

    Returns a system navigation configuration object based on its associated type.

    Default Implementation

    Declaration

    Swift

    @MainActor
func systemNavigationPresentation(for navigationType: SystemNavigationType) -> (DestinationPresentation<DestinationType, ContentType, TabType>)?

    Parameters

    navigationType

    The system navigation type.

    Return Value

    The configuration object, or nil if the specified object was not found.

  • updatePresentation(presentation:) Default implementation

    Updates an existing presentation with a new configuration object. If no presentation is found which matches this object’s identifier, nothing is updated.

    Default Implementation

    Declaration

    Swift

    @MainActor
func updatePresentation(presentation: DestinationPresentation<DestinationType, ContentType, TabType>)

    Parameters

    presentation

    The presentation configuration object to replace an existing one.

  • Updates an existing system navigation presentation with a new configuration object. If no system navigation object is found which matches this object’s identifier, nothing is updated.

    Default Implementation

    Declaration

    Swift

    @MainActor
func updateSystemNavigationPresentation(presentation: DestinationPresentation<DestinationType, ContentType, TabType>)

    Parameters

    presentation

    The presentation configuration object to replace an existing one.

  • Assigns an Interactor to this Destination. An Interactor handles specialized tasks and interactions with other APIs for the Destination.

    Declaration

    Swift

    @available(*, deprecated, renamed: "assignInteractor(_:to:﹚", message: "This method is deprecated and will be removed in a future version. Please migrate your code to use the `assignInteractor(_:to:﹚` method instead.")
@MainActor
func assignInteractor<Request>(interactor: any AbstractInteractable<Request>, for type: InteractorType) where Request : InteractorRequestConfiguring

    Parameters

    interactor

    The Interactor to add.
    type

    Specifies the enum type of this Interactor. This type can be used to look up the Interactor.

  • Assigns an Interactor to this Destination. An Interactor handles specialized tasks and interactions with other APIs for the Destination.

    Declaration

    Swift

    @MainActor
func assignInteractor<Request>(_ interactor: any AbstractInteractable<Request>, to type: InteractorType) where Request : InteractorRequestConfiguring

    Parameters

    interactor

    The Interactor to add.
    type

    Specifies the enum type of this Interactor. This type can be used to look up the Interactor.
  • interactor(for:) Default implementation

    Returns an Interactor for the specified type.

    Default Implementation

    Undocumented

    Declaration

    Swift

    @MainActor
func interactor(for type: InteractorType) -> (any AbstractInteractable)?

    Parameters

    type

    The enum type of an Interactor.

    Return Value

    An Interactor, if one was found.

  • configureInteractor(_:type:) Default implementation

    Configures the Interactor that is assigned to this Destination. You may use this method to make any initial requests to the Interactor to set up the interface’s initial state. This method is called automatically when an Interactor is assigned to it.

    Default Implementation

    Declaration

    Swift

    @MainActor
func configureInteractor(_ interactor: any AbstractInteractable, type: InteractorType)

    Parameters

    interactor

    The Interactor to configure requests for.
    type

    The type of interactor.
  • configureInteractors() Default implementation

    Configures all Interactors that are assigned to this Destination. This method is called internally by this Destination’s Provider.

    Default Implementation

    Declaration

    Swift

    @MainActor
func configureInteractors()
  • addInterfaceAction(action:) Default implementation

    Adds an interface action.

    Default Implementation

    Declaration

    Swift

    @MainActor
func addInterfaceAction(action: InterfaceAction<EventType, DestinationType, ContentType>) throws

    Parameters

    closure

    The closure to add.
  • addSystemNavigationAction(action:) Default implementation

    Adds a system navigation closure.

    Default Implementation

    Declaration

    Swift

    @MainActor
func addSystemNavigationAction(action: InterfaceAction<SystemNavigationType, DestinationType, ContentType>)

    Parameters

    closure

    The closure to add.

  • Assigns an Interactor assistant to a specific event type.

    Default Implementation

    Declaration

    Swift

    @MainActor
func assignInteractorAssistant(assistant: any InteractorAssisting<InteractorType, ContentType>, for eventType: EventType)

    Parameters

    assistant

    The Interactor assistant to add.
    eventType

    The type of event which this assistant should handle requests for.
  • prepareForPresentation() Default implementation

    This method is called automatically when a Destination is presented by a Flow for the first time, but before its associated UI is built. Implement this method in your Destination classes to put any initial state setup actions or datasource retrieval calls here that should only be run when a Destination is first created.

    Unlike prepareForAppearance(isVisible:), this method is only called once on a Destination.

    Default Implementation

    Declaration

    Swift

    @MainActor
func prepareForPresentation()
  • prepareForAppearance(isVisible:) Default implementation

    This method is called automatically when a Destination is about to be presented by a Flow, prior to the associated UI element appearing on-screen. Implement this method in your Destination classes to place any setup tasks that need to be run each time the Destination’s UI element becomes active.

    This method is preferred and is often more reliable than using native UI hooks like View‘s onAppear modifier in SwiftUI projects.

    Default Implementation

    Declaration

    Swift

    @MainActor
func prepareForAppearance(isVisible: Bool)

    Parameters

    isVisible

    Represents whether this Destination will actually be visible on-screen when it is presented. If this Destination was presented within the middle of a Destination path presentation, it would be false. This is useful for instance if you wish to avoid calling setup tasks unless it is the final Destination in a path presentation.
  • prepareForDisappearance(wasVisible:) Default implementation

    This method is called automatically when a Destination is about to become inactive. Implement this method in your Destination classes to place any teardown tasks that need to be run each time the Destination’s UI element is no longer visible or the active element.

    This method is preferred and is often more reliable than using native UI hooks like View‘s onDisappear modifier in SwiftUI projects, and especially in cases where several UI elements may be added in quick succession in a NavigationStack.

    Default Implementation

    Declaration

    Swift

    @MainActor
func prepareForDisappearance(wasVisible: Bool)

    Parameters

    wasVisible

    Represents whether this Destination which is disappearing was actually visible on-screen. If this Destination was presented within the middle of a Destination path presentation, it would be false.
  • performRequest(interactor:request:) Default implementation

    Performs a request with the specified Interactor.

    Default Implementation

    Undocumented

    Declaration

    Swift

    @MainActor
func performRequest<Request>(interactor: InteractorType, request: Request) where Request : InteractorRequestConfiguring
  • performRequest(interactor:request:) Default implementation, asynchronous

    Performs a request with the specified Interactor asynchronously.

    Default Implementation

    Undocumented

    Declaration

    Swift

    @MainActor
func performRequest<Request>(interactor: InteractorType, request: Request) async -> Result<Request.ResultData, Error> where Request : InteractorRequestConfiguring

    Parameters

    interactor

    The type of Interactor that should receive the request.
    request

    A model that defines the request.

    Return Value

    A Result containing an array of items.

  • Performs a system navigation action, executing the closure associated with the provided system navigation type.

    Default Implementation

    Declaration

    Swift

    @MainActor
func performSystemNavigationAction<T>(navigationType: SystemNavigationType, options: T?)

    Parameters

    navigationType

    The type of system navigation event to perform.
    options

    An optional options object for use with the closure.
  • setParentID(id:) Default implementation

    Sets the parent Destination identifier of this child.

    Default Implementation

    Declaration

    Swift

    @MainActor
func setParentID(id: UUID)

    Parameters

    id

    The identifier of the parent Destination.

  • Updates the isSystemNavigating property of the internal state.

    Default Implementation

    Declaration

    Swift

    @MainActor
func updateIsSystemNavigating(isNavigating: Bool)

    Parameters

    isNavigating

    The new value.
  • isSystemNavigating() Default implementation

    Returns the current value of the isSystemNavigating property of the internal state.

    Default Implementation

    Declaration

    Swift

    @MainActor
func isSystemNavigating() -> Bool

    Return Value

    The current value.

  • cleanupResources() Default implementation

    When this method is called, the Destination is about to be removed from the Flow. Any resource references should be removed and in-progress interactor tasks should be stopped.

    Note

    In-progress action sequences do not need to be handled here; the Flow cancels them automatically when removing the Destination.

    Default Implementation

    Declaration

    Swift

    @MainActor
func cleanupResources()

  • Removes the associated interface from this Destination. This method is called automatically when a Destination is removed in order to avoid a retain cycle.

    Declaration

    Swift

    @MainActor
func removeAssociatedInterface()
  • parentDestinationID() Default implementation

    Returns the identifier of this Destination’s parent, if one exists.

    Default Implementation

    Declaration

    Swift

    @MainActor
func parentDestinationID() -> UUID?

    Return Value

    The parent identifier.

  • Provides a way to catch and log Destinations errors from throwable code.

    Default Implementation

    Declaration

    Swift

    @MainActor
func handleThrowable(closure: @escaping () throws -> Void, catchClosure: (() -> Void)?)

    Parameters

    closure

    The throwable code to run.
    catchClosure

    An optional closure to run if the try is caught.
  • logError(error:) Default implementation

    Logs an error to the Destinations logger. It handles DestinationError messages appropriately.

    Default Implementation

    Declaration

    Swift

    @MainActor
func logError(error: Error)

    Parameters

    error

    The Error to log.

  • Declaration

    Swift

    @MainActor
func handleInteractorResult<Request>(result: Result<Request.ResultData, Error>, for request: Request) where Request : InteractorRequestConfiguring
  • handleAsyncInteractorResult(result:for:) Extension method, asynchronous

    Declaration

    Swift

    @MainActor
func handleAsyncInteractorResult<Request>(result: Result<Request.ResultData, Error>, for request: Request) async where Request : InteractorRequestConfiguring
  • description Extension method

    A description of this object.

    Declaration

    Swift

    @MainActor
var description: String { get }

AssistantAssigning protocol conformance

  • Declaration

    Swift

    @discardableResult
@MainActor
func tryAssignInteractorAssistant(_ assistant: any Sendable, for eventType: any Hashable) -> Bool