Swiftpack.co -  julianpomper/SwiftReactor as Swift Package
Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
julianpomper/SwiftReactor
A protocol which should help structure your data flow in SwiftUI (and UIKit).
.package(url: "https://github.com/julianpomper/SwiftReactor.git", from: "2.0.1")

SwiftReactor

A protocol which should help structure your data flow in SwiftUI (and UIKit).

Inspired by @devxoul´s ReactorKit.

Special thanks to @oanhof for contributing.

Concept

This protocol helps to structure and maintain the ReactorKit architecture in your SwiftUI or UIKit (with Combine) project. I highly encourage you to read the concept of this architecture in the ReactorKit´s README.md

Usage

To see the SwiftReactor in action, clone this repository and try the example project

Reactor

For a basic setup just:

  1. inherit from the BaseReactor class
  2. define your Actions, Mutations and your State
  3. implement the mutate(action: Action) and reduce(state: State, mutation: Mutation) method

and you are ready to go.

Click here to show an example
class ExampleReactor: BaseReactor<ExampleReactor.Action, ExampleReactor.Mutation, ExampleReactor.State> {
    enum Action {
        case enterText(String)
        case setSwitch(Bool)
        case setSwitchAsync(Bool)
        case colorChangePressed(Color)
    }
    
    enum Mutation {
        case setText(String)
        case setSwitch(Bool)
        case setBackgroundColor(Color)
    }
    
    struct State {
        var text = "initial text"
        var switchValue = false
        var backgroundColor = Color.white
    }
    
    init() {
        super.init(initialState: State())
    }
    
    override func mutate(action: Action) -> Mutations<Mutation> {
        switch action {
        case .enterText(let text):
            return [.setText(text)] //is equal to: Mutations(sync: .setText(text))
        case .setSwitch(let value):
            return [.setSwitch(value)] //is equal to: Mutations(sync: .setSwitch(value))
        case .setSwitchAsync(let value):
            let mutation = Just(Mutation.setSwitch(!value)).delay(for: 2, scheduler: DispatchQueue.global())
                .eraseToAnyPublisher()
            
            return Mutations(sync: .setSwitch(value), async: mutation)
        case .colorChangePressed(let color):
            return [.setBackgroundColor(color)] //is equal to: Mutations(sync: .setBackgroundColor(color))
        }
    }
    
    override func reduce(state: State, mutation: Mutation) -> State {
        var newState = state
        
        switch mutation {
        case .setText(let text):
            newState.text = text
        case .setSwitch(let value):
            newState.switchValue = value
        case .setBackgroundColor(let color):
            newState.backgroundColor = color
        }
        
        return newState
    }
    
    override func transform(mutation: AnyPublisher<Mutation, Never>) -> AnyPublisher<Mutation, Never> {
        mutation
            .prepend(.setText("hello"))
            .eraseToAnyPublisher()
    }
}

mutate(action: Action)

This method takes an Action and transforms it synchronously or asynchronously into a mutation. If you have any side effects do it here.

Return sync mutations if you want to mutate the state instantly and sychronously on the main thread. Binding and withAnimation require the state to be changed on the main thread synchronously. For that reason use sync mutations for these use cases.

Return async mutations if you have to do async tasks (ex.: network requests) or expensive tasks on a background queue

func mutate(action: Action) -> Mutations {
     switch action {
     case .noMutationNeededAction:
         return .none
     case .enterText(let text):
         return Mutations(sync: .setText(text))
     case .setSwitchAsync(let value):
        let mutation = API.setSetting(value)
            .catch { _ in Just(.setSwitch(!value)) }

        return Mutations(sync: .setSwitch(value), async: mutation)
     }
 }

reduce(state: State, mutation: Mutation)

This method takes a State and a Mutation and returns a new mutated State. Don't perform any side effects in this method. Extract them to the mutate(action: Action) function

func reduce(state: State, mutation: Mutation) -> State {
    var newState = state
    
    switch mutation {
    case .setText(let text):
        newState.text = text
    }
    
    return newState
}

transform()

Use these methods to intersect the state stream. This is the best place to combine and insert global event streams into your reactor. They are being called once, when the state stream is created in the createStateStream() method.

/// Transforms an action and can be used to combine it with other publishers.
func transform(action: AnyPublisher<Action, Never>) -> AnyPublisher<Action, Never>

/// Transforms an mutation and can be used to combine it with other publishers.
func transform(mutation: AnyPublisher<Mutation, Never>) -> AnyPublisher<Mutation, Never>

/// Transforms the state and can be used to combine it with other publishers.
func transform(state: AnyPublisher<State, Never>) -> AnyPublisher<State, Never>

Mutations

Mutations is a struct for a better separation of your sync and async mutations.

  • sync is an Array with Mutations that mutate the state instantly and are always automatically forced on the main thread synchronously. Use them specifically for UI interactions like Bindings, especially if the change should be animated (ex.: withAnimation)

  • async is an AnyPublisher<Mutation, Never> that contains mutations that happen asynchronously and can mutate the state at any given time (ex.: if a network request returns a result). The state is always mutated on the main thread asychronously, everything before that happens on the thread of your choice.

You can initialize sync Mutations like an array. In this case [.mySyncMutation] is equal to Mutations(sync: .mySyncMutation) or [.mySyncMutation, .mySecondSyncMutation] is equal to Mutations(sync: [.mySyncMutation, .mySecondSyncMutation]) .

If you do not want to mutate the state with an Action just return .none that equals to Mutations()

View

struct ContentView: View {
    // access your reactor via the `@EnvironmentObject` property wrapper
    @EnvironmentObject
    var reactor: AppReactor
    
    // you can use this property wrapper to bind your value and action
    // it can be used and behaves like the `@State` property wrapper
    @ActionBinding(\AppReactor.self, keyPath: \.name, action: AppReactor.Action.nameChanged)
    private var name: String
    
    var body: some View {
        VStack {
            // access the value from the binding (the value from your current state)
            Text(name.wrappedValue)
            // bind your action to the changes of this textfield
            TextField("Name", text: $name)
        }
    }
}

Advanced

Reactor Nesting

Click here to expand

It is also possible to split your logic into different reactors but also ensure a single source of truth by nesting reactors states.

    class AppReactor: BaseReactor<AppReactor.Action, AppReactor.Mutation, AppReactor.State> {
    
        [...]
        
        public enum Mutation {
            case setDetail(DetailReactor.State)
        }
        
        struct State {
            var detail: DetailReactor.State
        }
        
        let detailReactor: DetailReactor
        
        init() {
        
            detailReactor = DetailReactor()
        
            super.init(
                initialState: State(
                    detail: detailReactor.state
                )
            )
        }
        
        override func reduce(state: State, mutation: Mutation) -> State {
            var newState = state
        
            switch mutation {
            case let .setDetail(state):
                newState.detail = state
            }
            
            return newState
        }
        
        // transform the state changes to mutations
        override func transform(mutation: AnyPublisher<Mutation, Never>) -> AnyPublisher<Mutation, Never> {
            let detail = detailReactor.$state
                .map { Mutation.setDetail($0) }
            
            return mutation
                .merge(with: detail)
        }
    }

To access or bind actions to nested reactors use the following property wrappers:

    // get the root Reactor
    @EnvironmentReactor()
    var reactor: AppReactor
    
    // get a nested reactor
    @EnvironmentReactor(\AppReactor.detailViewReactor)
    var reactor: DetailReactor
    
    // bind `Action`s using the root reactor
    @ActionBinding(\AppReactor.self, keyPath: \.name, action: AppReactor.Action.nameChanged)
    private var name: String
    
    // bind `Action`s using the nested reactor
    @ActionBinding(\AppReactor.detailViewReactor, keyPath: \.age, action: DetailReactor.Action.ageChanged)
    private var age: Int

Use the Reactor protocol

Click here to expand

If you do not want to inherit the BaseReactor class, you can also implement the Reactor protocol on your own.

  1. add all necessary propeties
  2. add @Published to your state property
  3. call the createStateStream() method (ex.: in your init())
    class CountingReactor: Reactor {
    
        enum Action {
            case countUp
            case countUpAsync
        }
        
        enum Mutation {
            case countUp
        }
        
        struct State {
            var currentCount: Int = 0
        }
        
        public let action = PassthroughSubject<Action, Never>()
        
        public let mutation = PassthroughSubject<Mutation, Never>()
        
        @Published
        public var state = State()
        
        public var cancellables = Set<AnyCancellable>()
        
        public init() {
            createStateStream()
        }
        
        open func mutate(action: Action) -> Mutations<Mutation> {
            switch action {
            case .countUp:
                return [.countUp]
            case .countUpAsync:
                return Mutations(async: Just(.countUp).eraseToAnyPublisher())
            }
        }
        
        open func reduce(state: State, mutation: Mutation) -> State {
            var newState = state
            
            switch mutation {
            case .countUp:
                newState.currentCount += 1
            }
            
            return newState
        }
    }

UIKit

Click here to expand

SwiftReactor is also compatible with UIKit if you need it. To use it, you have to select and install the additional library SwiftReactorUIKit when you add the SwiftPackage to your project.

  1. inherit from the BaseReactorView or BaseReactorViewController class
  2. set the reactor property somewhere (ex.: when the UIView or UIViewController is being created)
  3. implement the bind(reactor:) method and add your bindings
Click here to show an example
let countingViewController = BaseCountingViewController()
countingViewController.reactor = CountingReactor()
final class BaseCountingViewController: BaseReactorViewController<CountingReactor> {
    
    var label = UILabel()
    
    /// automatically called when you set the reactor
    override func bind(reactor: Reactor) {
        reactor.$state
            .map { String($0.currentCount) }
            .assign(to: \.label.text, on: self)
            .store(in: &cancellables)
    }
}

TODOs

  • ☐ Improve example project
  • ☐ Add more tests
  • ☐ Improve README

Installation

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of swift code and is integrated into the swift compiler.

Once you have your Swift package set up (ex: with this guide), adding SwiftReactor as a dependency is as easy as adding it to the dependencies value of your Package.swift.

dependencies: [
    .package(url: "https://github.com/julianpomper/SwiftReactor.git", from: "2.0.0")
]

Manually

If you prefer not to use any of the aforementioned dependency managers, you can integrate it into your project manually.

Requirements

  • Swift 5.1
  • iOS 13
  • watchOS 6
  • tvOS 13
  • macOS 10.15

License

SwiftReactor is released under the MIT license. See LICENSE for details.

GitHub

link
Stars: 46
Last commit: 5 days ago

Ad: Job Offers

iOS Software Engineer @ Perry Street Software
Perry Street Software is Jack’d and SCRUFF. We are two of the world’s largest gay, bi, trans and queer social dating apps on iOS and Android. Our brands reach more than 20 million members worldwide so members can connect, meet and express themselves on a platform that prioritizes privacy and security. We invest heavily into SwiftUI and using Swift Packages to modularize the codebase.

Release Notes

SwiftReactor 2.0
43 weeks ago

We are happy to publish the new version of SwiftReactor(former SwiftUIReactor). We refactored the whole structure to be able to handle threads better, improve binding and the usability in general.

Whats new?

  • Updated README
  • Obviously a new name: SwiftReactor. SwiftUIReactor didn't fit well because we discovered that it also works well with UIKit
  • Fixed issues (thanks @rm98)
    • Concurrency Crash / Issue #3 - fixed
    • Cancellable stored for every executed action #4 - fixed
    • Testability of Reactors #5 - improved
  • Mutations are now split up in sync & async Mutations: Read more here
  • A new BaseReactor class for convenience: Read more here
  • New transform() functions like in ReactorKit: Read more here
  • withAnimation() using ActionBinding is now supported in SwiftUI
  • New property wrappers for nested reactors: Read more here
  • New UIKit helper as optional Swift Package (SwiftReactorUIKit): Read more here

Special thanks to @oanhof for contributing.

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API