Destinationable

@MainActor
public protocol Destinationable<DestinationType, ContentType, TabType> : AnyObject, 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 user interaction types for this Destination’s interface.

    Declaration

    Swift

    associatedtype UserInteractionType : UserInteractionTypeable

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

    Declaration

    Swift

    associatedtype DestinationType : RoutableDestinations

  • An enum which defines types of Interactors. Each Destination may have its own Interactor types.

    Declaration

    Swift

    associatedtype InteractorType : InteractorTypeable

  • 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.

    Declaration

    Swift

    associatedtype ContentType : ContentTypeable

  • A type of AppDestinationConfigurations which handles Destination presentation configurations.

    Declaration

    Swift

    typealias DestinationConfigurations = AppDestinationConfigurations<UserInteractionType, 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<UserInteractionType, DestinationType, ContentType, TabType, InteractorType> { get set }

  • Performs the interface action associated with the specified user interaction type.

    Default Implementation

    Declaration

    Swift

    @MainActor
func performInterfaceAction(interactionType: UserInteractionType, content: ContentType?) throws

    Parameters

    interactionType

    The user interaction type whose action should be run.
    content

    Optional content to use with the interface 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>, interactionType: UserInteractionType) -> InterfaceAction<UserInteractionType, DestinationType, ContentType>

    Parameters

    presentationClosure

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

    A model object used to configure the presentation.
    interactionType

    The user interaction 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<UserInteractionType, 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 type.

    Default Implementation

    Declaration

    Swift

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

    Parameters

    interactionType

    The user interaction 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

    @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.
  • interactor(for:) Default implementation

    Returns an Interactor for the specified type.

    Default Implementation

    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.
  • addInterfaceAction(action:) Default implementation

    Adds an interface action.

    Default Implementation

    Declaration

    Swift

    @MainActor
func addInterfaceAction(action: InterfaceAction<UserInteractionType, 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 type of user interaction.

    Default Implementation

    Declaration

    Swift

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

    Parameters

    assistant

    The Interactor assistant to add.
    interactionType

    The type of user interaction which this assistant should handle requests for.

  • 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(), this method is only called once on a Destination.

    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

    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

    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.

  • handleInteractorResult(result:for:) Default implementation

    Handles the result of an Interactor request in a synchronous context.

    Default Implementation

    Declaration

    Swift

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

    Parameters

    result

    The Result object containing data returned from the request.
    request

    The original request used in this Interactor operation.
  • handleAsyncInteractorResult(result:for:) Default implementation, asynchronous

    Handles the result of an async Interactor request.

    Default Implementation

    Declaration

    Swift

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

    Parameters

    result

    The Result object containing data returned from the request.
    request

    The original request used in this Interactor operation.

  • 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.

    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.
  • description Extension method

    A description of this object.

    Declaration

    Swift

    @MainActor
var description: String { get }