Protocols

The following protocols are available globally.

  • Protocol that marks something that can be actually dispatched into the Store. It doesn’t have any particular requirement, and the protocol is actually used to simply mark a category of items. Currently the Store is able to manage 3 types of Dispatchable: SideEffect, StateUpdater and Action (deprecated).

    See more

    Declaration

    Swift

    public protocol Dispatchable : CustomDebugStringConvertible
  • An action represents an event that leads to a change in the state of the application. It can be triggered from a user action, from a system event or any event in general.

    See more

    Declaration

    Swift

    @available(*, deprecated, message: "Use AnyStateUpdater instead")
    public protocol Action : Dispatchable
  • Action can implement this protocol to perform side effects when an instance is dispatched.

    A side effect is nothing more than a piece of code that can interact with external services or APIs (e.g., make a network request, get information from the disk and so on). Side effects are needed because the updatedState(currentState:) function (which is the only other operation that is performed when an action is dispatched) must be pure and therefore it cannot interact with disk, network and so on.

    Dependencies

    You can see from the sideEffect(currentState:previousState:dispatch:dependencies:) signature that a side effect takes as input some dependencies. This is a form of dependency injection for the side effects. By using only methods coming from the dependencies (instead of relying on global imports), testing is much more easier since you can inject a mocked version of the things you need in the side effect. For example, in a test, you may want to inject a mocked version of the class that manages the API requests, in order to control the result of the network call.

    See more

    Declaration

    Swift

    @available(*, deprecated, message: "Use AnySideEffect instead")
    public protocol ActionWithSideEffect : Action
  • Type Erasure for AsyncAction

    See more

    Declaration

    Swift

    @available(*, deprecated, message: "Use AnySideEffect or AnyStateUpdater instead")
    public protocol AnyAsyncAction
  • Protocol that represents an async action.

    An AsyncAction is just an abstraction over Action that provides a way to structure your action.

    You typically use an Async action when you have to deal with operations that are asynchronous. In the most common scenario, you dispatch the initial action, execute an operation in the side effect and then dispatch a completed/failed action based on the result of the operation. If the action has a concept of progress, you can also dispatch progress actions.

    This protocol has as the main goal to standardize the way async actions are managed.

    It is important to note that this is just a a convenience approach to something you can do anyway. You can for instance create three actions: performOperation, OperationCompleted and OperationFailed and achieve the same result. AsyncAction just provide a way to abstract and simplify the process

    Tip & Tricks

    Since the Action protocol is very generic when it comes to the state type that should be updated, a pattern we want to promote is to put in your application a protocol like the following:

    protocol AppAsyncAction: AsyncAction {
     func updatedStateForLoading(currentState: inout AppState)
     // same for completed, failed and progress
    }
    
    extension AppAsyncAction {
     func updatedStateForLoading(currentState: State) -> State {
       guard var state = state as? AppState else {
         fatalError("Something went wrong")
       }
    
       self.updatedStateForLoading(currentState: &state)
       return state
     }
    
     // same for completed, failed and progress
    }
    

    In this way you can save a lot of code since you can use your actions in the following way

    struct A: AppAsyncAction {
     func updatedStateForLoading(currentState: inout AppState) {
       state.props = action.payload
     }
    
     // same for completed, failed and progress
    }
    
    See more

    Declaration

    Swift

    @available(*, deprecated, message: "Use SideEffect or StateUpdater instead")
    public protocol AsyncAction : Action, AnyAsyncAction
  • Protocol to identify a linked action that must be dispatched after another action, called source, is dispatched by the Store.

    See more

    Declaration

    Swift

    @available(*, deprecated, message: "Use DispatchObserverDispatchable instead")
    public protocol LinkeableAction : Action
  • Type erasure for SideEffectContext

    See more

    Declaration

    Swift

    public protocol AnySideEffectContext
  • Type erasure for SideEffect

    See also

    SideEffect
    See more

    Declaration

    Swift

    public protocol AnySideEffect : Dispatchable
  • A side effect is a single atom of the logic of your application. While you can actually use them as you desire, the idea is to implement in each side effect a meaningful, self contained, piece of logic that can be used from other pieces of you application (e.g., dispatched by a View Controller or by another side effect).

    The StateUpdater is strongly tied to the state that it handles and the dependencies it has. This greatily simplifies the code written in normal situations. However, if you need to create updaters that are not strictly tied to a concrete types (e.g., in a library) you can use AnySideEffect.

    ### App Tips & Tricks To further simplify the usage of a StateUpdater you can add to your application a helper protocol

     /// assuming `AppState` is the type of your application's state and `DependenciesContainer` is the
     /// container of your dependencies
     protocol AppSideEffect: SideEffect where StateType == AppState, Dependencies == DependenciesContainer {}
    

    By conforming to AppSideEffect, you will get better autocompletion

    See more

    Declaration

    Swift

    public protocol SideEffect : AnySideEffect
  • Protocol for the state of the applications. In Katana, all the relevant application information should be placed in a single struct that has to implement the State protocol.

    See more

    Declaration

    Swift

    public protocol State
  • Type erasure for StateUpdater

    See also

    StateUpdater
    See more

    Declaration

    Swift

    public protocol AnyStateUpdater : Dispatchable
  • A StateUpdater is a Dispatchable that can be used to update the Store state configuration.

    The StateUpdater is strongly tied to the state that it handles. This greatily simplifies the code written in normal situations. However, if you need to create updaters that are not strictly tied to a concrete state type (e.g., in a library) you can use AnyStateUpdater.

    App Tips & Tricks

    To futherly simplify the usage of a StateUpdater you can add to your application an helper protocol

    /// assuming `AppState` is the type of your application's state
    protocol AppStateUpdater: StateUpdater where StateType == AppState {}
    

    By conforming to AppStateUpdater, you will get better autocompletion

    See more

    Declaration

    Swift

    public protocol StateUpdater : AnyStateUpdater