Introducing TCA Composer - A swift macro framework for eliminating boiler-plate code in TCA Reducers

[scogeo]

Intro

I was inspired by the recent Point-Free Macro Bonanza to explore some ideas I have had for some time in reducing boilerplate in TCA-based apps. Macros seemed like the perfect way to accomplish this. The project began with a modest goal of simplifying how to use scopes in TCA. Instead of writing code like store.scope(state: \.child, action: \.child), I wanted to more concisely write store.scopes.child. That turned out to be fairly easy to implement and my mind was then filled with possibilities of what else I could accomplish with macros. So I began incrementally adding new capabilities to my macro framework using my own apps as a test bed and playground.

The final result is called TCA Composer. I'm happy to release it publicly today after a couple months of development in private. Over the coming days and weeks I will be improving the documentation, adding additional examples, and implementing a few additional capabilities that many may find useful.

Example

To show you how TCA Composer works, let's start with a simple TwoCounters example that uses the canonical Counter reducer to combining two Counter reducers into a single reducer and add some basic functions such as optionally displaying the sum of the two counters and providing a button to reset both counters to zero.

First, let's see how this Reducer would be implemented normally:

import ComposableArchitecture 

@Reducer
struct TwoCounters {
  @ObservableState
  struct State: Equatable {
    var counter1 = Counter.State()
    var counter2 = Counter.State()
    var isDisplaySum = true
  }

  enum Action: BindableAction, ViewAction {
    case bindable(BindableState<State>)
    case counter1(Counter.Action)
    case counter2(Counter.Action)
    case view(View)

    enum View {
      case resetCountersTapped
    }
  }

  var body: some Reducer<State, Action> {
    BindingReducer()
    Scope(state: \.counter1, action: \.counter1) {
      Counter()
    }
    Scope(state: \.counter2, action: \.counter2) {
      Counter()
    }
    Reduce { state, action in
      switch action {
        case .view(.resetCountersTapped):
          state.counter1.count = 0
          state.counter2.count = 0

        case .bindable,
            .counter1,
            .counter2:
          return .none
        }
      }
    }
  }
}

While this is very straightforward to implement, it is necessary to make code changes in three spearate places for each child reducer, once in each of Action, State, and the body. The changes are trivial, but can be error prone in practice, especially when you introduce optional state, identified arrays, navigation, etc. In addition, complex reducers and SwiftUI Views can encounter the dreaded The compiler is unable to type-check this expression in reasonable time; error from simple typos and syntax errors.

Composer simplfies all of this so you can define your child reducers in a single place, and it will generate all of the necessary boilerplate for you. It also generates what I call a ScopePath for each child reducer, allowing you to scope stores using dynamic member lookup on a new scopes operation on an extension of Store.

Using the TCAComposer library here is what the TwoCounters reducer looks like:

 import ComposableArchitecture 
 import TCAComposer
 
 @ComposeReducer(
   .bindable,
   children: [
     .reducer("counter1", of: Counter.self, initialState: .init()),
     .reducer("counter2", of: Counter.self, initialState: .init())
   ]
 )
 @Composer
 struct TwoCounters {
   
   struct State {
     var isDisplayingSum = false
   }

   enum ViewAction {
     case resetCountersTapped
   }
   
   @ComposeBodyActionCase
   func view(state: inout State, action: ViewAction) {
     switch action {
     case .resetCountersTapped:
       state.counter1.count = 0
       state.counter2.count = 0
     }
   }
 }

Let's see what code was generated. Click to expand the @Composer macro

@ComposeReducer(
  .bindable,
  children: [
    .reducer("counter1", of: Counter.self, initialState: .init()),
    .reducer("counter2", of: Counter.self, initialState: .init())
  ]
)
@Composer
struct TwoCounters {
  
+ @_ComposerScopePathable
+ @_ComposedStateMember("counter1", of: Counter.State.self, initialValue: .init())
+ @_ComposedStateMember("counter2", of: Counter.State.self, initialValue: .init())
+ @ObservableState
  struct State {
    var isDisplayingSum = false
  }
  
+ @CasePathable
  enum ViewAction {
    case resetCountersTapped
  }
  
  @ComposeBodyActionCase
  func view(state: inout State, action: ViewAction) {
    switch action {
    case .resetCountersTapped:
      state.counter1.count = 0
      state.counter2.count = 0
    }
  }
  
+ @CasePathable
+ enum Action: ComposableArchitecture.BindableAction, ComposableArchitecture.ViewAction {
+   case binding(BindingAction<State>)
+   case counter1(Counter.Action)
+   case counter2(Counter.Action)
+   case view(ViewAction)
+ }
+
+ @ComposableArchitecture.ReducerBuilder<Self.State, Self.Action>
+ var body: some ReducerOf<Self> {
+   ComposableArchitecture.BindingReducer()
+   ComposableArchitecture.Scope(state: \.counter1, action: \Action.Cases.counter1) {
+     Counter()
+   }
+   ComposableArchitecture.Scope(state: \.counter2, action: \Action.Cases.counter2) {
+     Counter()
+   }
+   ComposableArchitecture.CombineReducers {
+     TCAComposer.ReduceAction(\Action.Cases.view) { state, action in
+       self.view(state: &state, action: action)
+         return .none
+     }
+   }
+ }
+
+ struct AllComposedScopePaths {
+   var counter1: TCAComposer.ScopePath<TwoCounters.State, Counter.State, TwoCounters.Action, Counter.Action> {
+     get {
+       return TCAComposer.ScopePath(state: \State.counter1, action: \Action.Cases.counter1)
+     }
+   }
+   var counter2: TCAComposer.ScopePath<TwoCounters.State, Counter.State, TwoCounters.Action, Counter.Action> {
+     get {
+       return TCAComposer.ScopePath(state: \State.counter2, action: \Action.Cases.counter2)
+     }
+   }
+ }
}

Wow, that's a lot code! Composer has automatically generated an Action that includes conformance for BindingAction thanks to the .bindable option. The Action also incorporates cases for our two reducer children and the view action from @ComposeBodyActionCase macro. The automatically generated body calls the BindingReducer, scopes the two child reducers and then finally invokes our view function to reduce the ViewAction.

You will also notice that new macros appear that begin with an underscore are attached to State. These are internal macros that Composer uses to generate code in portions of your Reducer code and are a byproduct of how the swift macro system works. The internal macros are not meant to be used by you and may change from release to release. Here's what they look like when fully expanded for State:

 @ObservableState
 struct State {
   var isDisplayingSum = false
    
+  static var allComposedScopePaths: AllComposedScopePaths {
+    AllComposedScopePaths()
+  }
+ 
+  @ObservationStateTracked
+  var counter1: Counter.State = .init()
+  @ObservationStateIgnored
+  private var _counter1: Counter.State
+ 
+  @ObservationStateTracked
+  var counter2: Counter.State = .init()
+  @ObservationStateIgnored
+  private var _counter2: Counter.State
 }

The macros automatically added new members to State for our child reducers including the required support for @ObservableState. The @_ComposerScopePathable macro combined with the generated AllComposedScopePaths struct provides support for improving view ergonomics by generating a ScopePath for each child reducer so that you can scope a child reducer using store.scopes.counter1, rather than the more verbose store.scope(state: \.counter1, action: \.counter1). Pretty cool, eh?

Summary

Composer can do this and so much more. For more information, please checkout the the tca-composer repo.

If you have any comments or questions about Composer please post them on my announcement discussion in my repo.

[mbrandonw]

Hi @scogeo, thanks for sharing! The macros certainly pack a punch!

We will also be announcing a few updates to @Reducer next week that address a few of these things, but not all of them. If you want to PR adding your library to the "Companion libraries" section of the TCA readme we would happily merge it.

[scogeo]

Thank you @mbrandonw. Great suggestion, I've submitted a PR.

I also saw in your recent blog post that you will be releasing some changes to @Reducer, so I took a sneak peek at the development branch. Definitely some great improvements! I also like that you implemented a concept in TCAComposer that I call ScopeSwitchable. I saw a discussion about this a few weeks back, but I didn't chime in because I wasn't sure at the time if I was going to publicly release this library. Once you release the update next week, I'll update my library to make use of your protocols and design and I can delete my own extensions. :)

I was planning on creating a separate discussion next week on the topic of ScopePaths. That is the first feature I implemented in Composer, long before I even tried to generate code for State, Action, and body. I think it would be a valuable concept to introduce into TCA, and while not as straightforward to implement as generating enum reducers, it has a bigger payoff in many ways. I wanted to share some details around my early prototypes that you both may find interesting, as I think this is something you could bring to the library relatively soon. And then, I can delete even more code in TCAComposer. :)

Also, thank you and @stephencelis so much for MacroTesting! I literally would not have been able to build a macro library this complex without it.