Composing Reducers

[HarshilShah]

Hiya folks. I've been updating some of my apps to use the protocol-beta and really loving it so far. This post has some feedback/wishes specific to composing the new ReducerProtocol types, which has been pretty much the only hairy bit of my migration so far.

Of the 4 main APIs used to compose reducers, Scope is offered only as a standalone reducer, while ifLet, ifCaseLet, and forEach are only offered as functions on ReducerProtocol, with the backing implementations all being internal to the repo.

Here are some of the issues I’ve seen with this setup, and the use cases I have for them:

Scope

If you have a reducer that composes two reducers, one using optional state and the other non-optional, the body ends up looking like so:

var body: some ReducerProtocol<State, Action> {
  Scope(/* handle honest subfeature... */)
  
  Reduce { /* reducer goes here */ }
  .ifLet(/* handle optional subfeature... */)
}

It feels a bit strange to have any composed reducers declared at both extremities of the body. It would be great if there was an operator version of Scope available too so reducer bodies would be a bit easier to scan.

var body: some ReducerProtocol<State, Action> {
  Reduce { /* reducer goes here */ }
  .scope(/* handle honest subfeature... */ )
  .ifLet(/* handle optional subfeature... */)
}

IfCaseLet

A common pattern I’ve seen across some TCA projects I’ve worked on is having some feature live as part of an enum that is a property of the state of some larger feature. This is a common pattern for navigation, and TCA even includes SwitchStore specifically to handle this use case in SwiftUI, however there’s no corresponding ReducerProtocol API to make the reducers easier to glue together.

The best way to compose together these APIs right now is using Scope with an EmptyReducer() and a bunch of ifCaseLetss, as detailed here: ¹

var body: some ReducerProtocol<State, Action> {
  Scope(state: \.route, action: Action.route) {
    EmptyReducer()
      .ifCaseLet(...)
      .ifCaseLet(...)
      .ifCaseLet(...)
  }
  Reduce { state, action in 
    // Parent logic
  }
}

This has the same scope issue of having to declare subfeatures in two places in the body, but the EmptyReducer() also feels a bit crummy, and also not very obvious.

If the _IfCaseLetReducer were public, however, the EmptyReducer() could be elided and instead a bunch of IfCaseLetReducers could be used directly within the Scope, which combined with the aforementioned function style for Scope, would make a lot of code way more readable.

var body: some ReducerProtocol<State, Action> {
  Reduce { state, action in 
    // Parent logic
  }
  .scope(state: \.route, action: Action.route) {
    IfCaseLet(/* scope to actual feature */)
    IfCaseLet(/* scope to actual feature */)
    IfCaseLet(/* scope to actual feature */)
  )
}

I also think it might be useful to make public the backing reducers for ifLet and forEach for similar use cases, but also I think ifCaseLet perhaps might have a stronger argument for a public API to allow for exactly this SwitchStore equivalent behaviour

Footnotes

1. As an aside, I’m not quite sure if this is maybe a compiler limitation or some other bug, but in my testing I also wasn’t able to add more than 2 ifCaseLet modifiers to the EmptyReducer(); the compiler would just not be able to type-check the expression if I added a third ifCaseLet. I instead had to have 3 Scopes to accommodate all 5 cases of my state enum. ↩

[stephencelis]

Hi @HarshilShah! Thanks for the detailed feedback! And glad to hear that your overall impression has been positive.

There are a few tools shipping in the library that probably aren't highlighted enough in docs and migration guides that hopefully address some of these issues, at least partially.

Scope

If you have a reducer that composes two reducers, one using optional state and the other non-optional, the body ends up looking like so:

var body: some ReducerProtocol<State, Action> {
  Scope(/* handle honest subfeature... */)
  
  Reduce { /* reducer goes here */ }
  .ifLet(/* handle optional subfeature... */)
}

It feels a bit strange to have any composed reducers declared at both extremities of the body. It would be great if there was an operator version of Scope available too so reducer bodies would be a bit easier to scan.

I definitely agree! Generally it's good to group all core reducers together before layering on modifiers, especially since if you don't, you can run into the ordering problem ifLet and other modifiers intend to solve (as you mention).

The "ad hoc" way of doing this is using CombineReducers, which is like SwiftUI's Group view:

var body: some ReducerProtocol<State, Action> {
  CombineReducers {
    Scope(/* handle honest subfeature... */)

    Reduce { /* reducer goes here */ }
  }
  .ifLet(/* handle optional subfeature... */)
}

Another option is to extract the "core" composition into its own property, and delegate to that in the body, which layers on modifiers, though the explicit @ReducerBuilder is admittedly noisy:

@ReducerBuilder<State, Action>
var core: some ReducerProtocol<State, Action> {
  Scope(/* handle honest subfeature... */)

  Reduce { /* reducer goes here */ }
}

var body: some ReducerProtocol<State, Action> {
  self.core
    .ifLet(/* handle optional subfeature... */)
}

We're definitely open to improve these tools, but our current thought is that keeping Scope top-level makes sense because it doesn't have the same ordering issues as ifLet, etc. In fact, you may want to control the order in which a scoped reducer runs. Sometimes you want to run a scoped reducer before a parent, and sometimes you want to run a parent before a scoped reducer.

Because of this, I think a scope modifier might be more difficult for me to reason about when I encounter it, especially in domains that care about running logic before and after scoped features.

With all that said, such a modifier is possible for you to define outside the library, so if you end up taking it for a spin in your applications, we'd love to hear how it works out for you and what ordering you decided on.

IfCaseLet

A common pattern I’ve seen across some TCA projects I’ve worked on is having some feature live as part of an enum that is a property of the state of some larger feature. This is a common pattern for navigation, and TCA even includes SwitchStore specifically to handle this use case in SwiftUI, however there’s no corresponding ReducerProtocol API to make the reducers easier to glue together.

The best way to compose together these APIs right now is using Scope with an EmptyReducer() and a bunch of ifCaseLetss, as detailed here: 1

The core problem here is a routing problem, and more specifically, precise routing with an enum that nests all of its destination domains. Before diving into solutions, I hope we can agree that this is a pretty advanced topic and approach, and it's probably more typical to have a flatter domain with optional state/action pairs for each destination (this is also how folks have to model such things in vanilla SwiftUI). By avoiding the enum, you avoid the nesting, and you avoid the composition problem highlighted above: you would just chain some ifLet reducers together, instead. But this of course loses precision and introduces invalid states (for example 2 destinations presented at once, which can happen in a typical vanilla SwiftUI domain).

With all that said, we like precise modeling (even if it can be more cumbersome and verbose), and we built SwiftUI Navigation for that reason, so here's a way to model things precisely with a nested enum that should avoid the ordering issues you pointed out:

var body: some ReducerProtocol<State, Action> {
  Reduce { state, action in 
    // Parent logic
  }
  .ifLet(\.route, action: /Action.route) {
    Scope(state: /Routes.State.modal, action: /Routes.Action.modal) {
      Modal()
    }
    // ...
  }
}

struct Routes {
  enum State {
    case modal(Modal.State)
    // ...
  }

  enum Action {
    case modal(Modal.Action)
    // ...
  }
}

I believe the route is optional, since a destination does not have to be presented, so we can use ifLet instead of a Scope or scope modifier.

Then, inside the ifLet, we can use a version of Scope that works with enum state and takes a case path, which I think is equivalent to the IfCaseLet you're suggesting.

You might see this version of Scope and think doesn't this re-introduce the issue that ifCaseLet intends to address? The answer is...yes, unfortunately. If you reach for this version of Scope in a domain with parent logic that can change the state's case before the Scope can do its thing, you will get a runtime warning that will push you toward ifCaseLet, instead. But there are instances, like this one, where the domains are truly mutually exclusive, with no parent in sight that can change the case from one to another, so we think it's OK here.

If you want to tidy things up, you could even have Routes conform to reducer and define that mutually-exclusive scoping in its body:

var body: some ReducerProtocol<State, Action> {
  Reduce { state, action in 
    // Parent logic
  }
  .ifLet(\.route, action: /Action.route) {
    Routes()
  }
}

struct Routes: ReducerProtocol {
  enum State {
    case modal(Modal.State)
    // ...
  }

  enum Action {
    case modal(Modal.Action)
    // ...
  }

  var body: some ReducerProtocol<State, Action> {
    Scope(state: /Routes.State.modal, action: /Routes.Action.modal) {
      Modal()
    }
    // ...
  }
}

One more thing: I agree that the argument for Scope with state case paths could apply to ForEachReducer (and maybe even IfLetReducer...though in that instance I'm not so sure). I can imagine a domain with no parent logic, just a place to embed child logic in a list. We're not sure this is common, though, or at least enough to ship a top-level type that people may accidentally reach for when forEach is more appropriate. I'd love to hear about any instances of EmptyReducer().forEach that occur in your application, though!

If EmptyReducer is too weird for those cases, one alternative would be an explicit, empty Reduce as a placeholder for future parent logic:

var body: some ReducerProtocol<State, Action> {
  Reduce { _, _ in
    .none // List domain has no logic
  }
  .forEach(\.self, ...) { ... }
}

Circling back to enum Scope: I'm not 100% sure it's a good idea to even ship this API as currently designed...the use case seems just common enough to warrant it, but maybe we could make things safer with a different design. Ideas welcome!

Sorry this got a lil long 😅 And I hope our current thought process makes sense. Feel free to press back on anything, and please do share more ideas if we can make these APIs better before release 😄

[HarshilShah]

our current thought is that keeping Scope top-level makes sense because it doesn't have the same ordering issues as ifLet, etc. In fact, you may want to control the order in which a scoped reducer runs. Sometimes you want to run a scoped reducer before a parent, and sometimes you want to run a parent before a scoped reducer.

That's a good point and one I hadn't considered, since in my usage I've found I generally want the scoped reducer to always run first

Then, inside the ifLet, we can use a version of Scope that works with enum state and takes a case path, which I think is equivalent to the IfCaseLet you're suggesting.

Ah thank you for this, I was not aware that Scope had this variant, this fixes a lot of stuff!

[stephencelis]

As an aside, I’m not quite sure if this is maybe a compiler limitation or some other bug, but in my testing I also wasn’t able to add more than 2 ifCaseLet modifiers to the EmptyReducer(); the compiler would just not be able to type-check the expression if I added a third ifCaseLet. I instead had to have 3 Scopes to accommodate all 5 cases of my state enum.

Aside-reply to focus on this. Do you have a repro to work with? It could definitely be a compiler limitation, but it'd be nice to understand when it happens.

Also, does switching to use enum Scopes avoid the issue?

[HarshilShah]

I'll try to make and upload a reproducible example for this and follow up in a bit here.

[GreatApe]

I'd say my view is the opposite of this. I find the chained modifier approach quite confusing, it behaves very differently from what it looks like and took a long time for me to understand:

Reduce { /* reducer goes here */ }
  .scope(/* handle sub-feature X... */)
  .scope(/* handle sub-feature Y... */)

This to me has several problems:

1. It looks like .scope is an operator that transforms the root reducer
2. It reads like Y is a sub-feature of X and not the root
3. We can't run a child reducer without having a parent
4. We have no control over ordering

The Scope approach on the other hand does not suffer from any of these deficiencies. It behaves the way it looks - it envelops a child reducer and turns it into a reducer at the top scope. I would strongly prefer this design also for IfLet and IfCaseLet, for reasons 1-3, but I have read that we actually do want to impose a particular ordering in this case, so I suppose it's a no-go.

Though I can't say I understand the ordering argument. Something about the parent potentially setting the state that the optional child reducer operates on to nil, before the child has a chance to work on it, so we should always run the child first. I may have misunderstood, but this doesn't seem like a problem to me. If the parent sets .childState to nil, then presumable it has good reason to do so, and if for some reason we want to have a chance to do some child level work before this, then we just put a child level reducer first.

[mbrandonw]

Over the past 2+ years since first releasing TCA we have (on a number of occasions) had to help people fix problems they were having by informing them that "optionalized" reducers should typically be combined before the core feature, unless you really have a reason to not do that. This came up so many times that we have numerous spots in the documentation and runtime warnings to let people know this is the case.

It's true that the parent may have good reason to nil out some child state, but that doesn't mean the author of the code understands the implications. If the parent inspected a child action, like a "Quit" button being tapped, and decided to nil out the child state, then the child loses the ability to react to that action, which could mean not tracking analytics, not closing resources, etc. You can technically catch this in tests, but only if you go the extra mile to write an integration test between the parent and child.

And as for the readability, we feel that it is inline with how forEach behaves today. And if you defined an ifLet on optional, then they would be very similar:

extension Optional {
  func ifLet(_ do: (Wrapped) -> Void) {
    if let wrapped = self { `do`(wrapped) }
  }
}

[1, 2, 3].forEach { x in
  // do something with x
}

Optional(1).ifLet { x in
  // do something with x
}

Those operations are very similar to the reducer versions, just with the added work of needing to specify the collection or optional domain inside the parent feature:

ParentFeature()
  .forEach(state: \.rows) {
    // do something with row
  }

ParentFeature()
  .ifLet(state: \.child) {
    // do something with child
  }

Hopefully this helps shed some light on why we are going in this direction.

[tgrapperon]

I may add that you can define your own IfLet as EmptyReducer().ifLet{…} if you're aware of the potential issues but still prefer to use the "standard" order. You can create your own ReducerProtocol type with this body, but you can also (ab)use a function in an extension of ReducerProtocol to get the same syntax at call site:

// - DO NOT USE THIS -
extension ReducerProtocol {
  public func IfLet<Wrapped: ReducerProtocol>(
    _ toWrappedState: WritableKeyPath<State, Wrapped.State?>,
    action toWrappedAction: CasePath<Action, Wrapped.Action>,
    @ReducerBuilderOf<Wrapped> then wrapped: () -> Wrapped
  ) -> some ReducerProtocol<State, Action> {
    EmptyReducer()
      .ifLet(toWrappedState, action: toWrappedAction, then: wrapped)
  }
}

This is not what I would recommend, but it shows that the library is flexible enough to adapt to personal preferences with very straightforward shims.
It is also likely that the upcoming presentation/navigation story will allow to simplify many optional reducers. In this case, the trailing position will match SwiftUI's presentation and navigation API's, so it will feel even more natural.

[GreatApe]

I really appreciate the reply, but I can't really say I understand the reasoning!

It's true that the parent may have good reason to nil out some child state, but that doesn't mean the author of the code understands the implications.

Isn't that the whole point of IfLet reducers, that they don't always run? I think I'm missing something, because it it seems to me that in the worst case you may have a design where you want the optional reducer to run "one last time" before disappearing. But that seems like something you'd be aware of. There shouldn't be things there that anyone expects to always run.

As to the second point, I don't think it's quite correct. The two types of forEach/ifLet operators seem quite different to me.

In a normal forEach/ifLet you "open a monad" and apply a closure to the contents, but in Parent().IfLet(...) { Child() } it's not like Child() is in any sense applied to the "contents" of Parent().

Looking closer, you could say that

• Parent() is a (Parent.State, Parent.Action) -> Parent.State function
• Child() is (Child.State, Child.Action) -> Child.State function
• and the first two arguments of the modifier are of course mappings Parent.State <-> Child.State and Child.Action <-> Parent.Action

Now it is indeed true that the ifLet/forEach modifies Parent() in place, just like the traditional versions that are applied to values, but the difference is that the "monad" in question is not Parent(), it's the state and action that are opened up.

Specifically, the modifier does two things:

1. The mappings turn Child() into a function with the same domain and codomain as Parent()
2. This new reducer is combined with Parent() by simply running it on the same inputs, but before Parent()

I think you will agree that this is quite different in nature from the normal forEach, which is much more of a "mathematical" operator.

Personally, I find 1 very clean and easy to grasp, but 2 is a bit strange, even if it makes the code succinct and avoids an apparently very common pitfall.

I also don't have a better suggestion that imposes the ordering.

[GreatApe]

Quick question, regarding your example, is it a design choice or an inevitability that actions are passed upwards first, before being run on a child?

[mbrandonw]

Quick question, regarding your example, is it a design choice or an inevitability that actions are passed upwards first, before being run on a child?

I'm not sure I understand the question. There are only two choices of how to compose reducers like this:

var body: some ReducerProtocol<State, Action> {
  Reducer1()
  Reducer2()
}

Either you run Reducer1 on the state and then Reducer2 on the state that was mutated by Reducer1, or you do the reverse.

In this sense there is no "parent" or "child", they are siblings. We have no way to abstractly know about a parent-child relation by just having a list of reducers, so we run them from top-to-bottom.

Can you provide some concrete code that demonstrates how you think the example I posted earlier should be structured? It seems like even the first example is not how you would like things to be done?

[GreatApe]

Sorry, the last question was a misunderstanding. I forgot for a moment that the parent-scoped body here is the only place where the child reducer appears. This is where you pipe actions into it. Or at least where you specify how the piping should be done. For a moment I imagined that this happened somewhere else for the child.

So disregard this, but do consider giving us the basic IfLet that we deserve.

[tgrapperon]

the functionally much simpler versions should also exist

I think that the modifier approach whole point is to prevent this. If unconstrained variants are provided, they will be used, most likely carelessly by users unaware of the issue. I don't think that the modifiers would make sense anymore if these variants were provided. The problem is not a fundamental one, but more a UX one, with a library that is now very popular and with many users of disparate levels.

Please note that I do prefer the direct approach personally, but I understand the shortcomings. This is something one can't expect from newcomers for example. An API that can't be used wrongly and without gotchas is thus likely a better one, even if it's slightly more inconvenient to activate in more advanced situations where you can (and know how to) provide a better alternative.

I've experimented with a family of ReducerProtocol to try to bake the ordering into the builder, but it ended up being too complex for what it brought to the table, and I don't think it would have worked in every situation to begin with, so I ditched the idea. I'll eventually give it another try.

[stephencelis]

It would be strange if we only have a tool that does "transform and combine in prescribed order" but not the more basic "transform".

@GreatApe The most basic transform does exist, and it's the version of Scope that takes a state case path. In fact, you can reproduce the functionality of the old struct Reducer.optional() functionality using the following:

Scope(state: /Optional.some, action: .self) {
  Child()
}

Of course, to get the pullback functionality you incur some more nesting:

Scope(state: \.optionalChild, action: /Action.optionalChild) {
  Scope(state: /Optional.some, action: .self) {
    Child()
  }
}

The state case path version of Scope is a precise tool to do what you want, but is advanced enough that beginners will probably not reach for it, and if they do and get the ordering wrong, they will be warned and led to ifLet and ifCaseLet instead.

If you are comfortable with the ordering gotcha, you could take the above template to define your own IfLet reducer in your application, or in a "pro tools" library if you so choose. We just don't think it's the right tool to ship for a library that, as @tgrapperon mentions, has an audience that runs the gamut from beginner to advanced, and we'd like the experience to be gentle on users, especially when there's a lot to learn as is.

Also, if you end up using such an IfLet helper in your code base, we'd be curious if you ever hit the ordering-based runtime warning, and we'd be curious if it helps you catch any potential bugs!