Merge send/task/run/fireForget/merge/concat into a single API name

[Jeehut]

I am using TCA for a while now, and I've come across several hurdles, some of which have been fixed with the recent features added. But here's one thing that still makes me scratch my head from time to time even after writing over 100 reducers:

What call is the correct one when I want to return an Effect in a Reducer when reacting to an Action?

Many APIs in TCA have been streamlined and made more consistent in preparation of the 1.0 release, such as BindingState and BindingAction, or PresentationState and PresentationAction, or the consistently named .ifLet operator for different kinds of child types (sheets, alerts, etc.), or even putting State and Action into a namespace. All these changes helped make developing with TCA more natural and less annoying. I even accepted the (to me) new term Reducer by viewing it as something unrelated to the reduce method, being its own thing with its own meaning (= a mix between an action handler and a state updater).

But the methods we can call inside a reducer to return an effect seem to lack this level of consistency:

• .send(Action): Immediately emits a single action to the system, the action is passed to it as a parameter.
• .task { ... }: Executes code in an asynchronous context (= allows await calls), closure must return exactly one Action.
• .run { send in ... }: Executes code in an asynchronous context (like .task), closure can emit unlimited actions to send.
• .fireAndForget { ... }: Executes code in an asynchronous context (like .task), closure can't emit any actions.
• .merge(Effect...): Starts multiple effects from one action case, running them all at the same time.
• .concatenate(Effect...): Starts multiple effects from one action case, running them one after another.

Just from reading these descriptions, I immediately think that task, run and fireAndForget are pretty much doing the same thing but with different number of actions passed back into the system. That's an opportunity to streamline them. Similarly, merge and concatenate also seem to be doing a similar thing with differences in behavior. Another streamlining opportunity.

But in the best case, we can even fine one name for all these APIs which only differs in ways that describe their differences. What is it that they all have in common? They all emit a given number of actions (for fireAndForget the number simply is zero). So I would suggest that they all get renamed to something like .emit or .send or something else that makes sense for sending/emitting actions into the system. I will use emit for the detailed naming down below to not confuse users with the existing send word, but it could be adjusted for any other unified word if you prefer another one.

The mapping of the existing methods to the new unified name could look like this:

• .send(Action) becomes .emitOne(Action) or short .emit(Action)
• .task { ... } becomes .emitOne { ... } or short .emit { ... } (or even .emitOneAsync { ... })
• .run { send in ... } becomes .emitMany { send ... } or short .emit { send ... } (or even .emitManyAsync { send in ... })
• .fireAndForget { ... } becomes .emitZero { ... } or short .noEmit { ... } (or .emitZeroAsync { ... }?)
• .merge(Effect...) becomes .emitAllAtOnce(Effect...) (or .emitAllConcurrently(Effect...))
• .concatenate(Effect...) becomes .emitOneAfterTheOther(Effect...) (or emitAllSequentially(Effect...))

For the merge and concatenate replacements I suggest to add an EffectBuilder to allow writing like this instead (if possible):

return .emitAll(.concurrently) { // or .sequentially
   Effect.emitOne(.someAction)
   Effect.emitOneAsync {
      let someValue = await self.someDependency.doSomething()
      return .someAction
   }
   Effect.emitManyAsync { send in
      let someValue = await self.someDependency.doAnotherThing()
      send(someValue)
      send(await self.someDependency.doSomethingElse(someValue))
   }
}

I may try to write an extension to Effect and an EffectBuilder that mimics above behavior.
But I wanted to share the idea first. What do you think?

[stephencelis]

@Jeehut We actually posted an RFC to simplify the surface area of Effect creation here:

#1520

Notably, we suggest eliminating fireAndForget and task since they don't offer a ton over run, and instead just have a single run interface. There's a little discussion about changing the name from run to something else, though, like a plain ole Effect { initializer, though a named, static func still feels nice alongside .none and .send.

I also think we want to keep send the way it is since it evokes other sends in the library:

viewStore.send(.action)
return .send(.action)
return .run { send in send(.action) }
await testStore.send(.action)

And I think .merge and .concatenate are rarely used in a typical TCA app, and really only aid in building reducer operators that combine a lot of reducers together, so dedicated names seem if anything better here since folks won't accidentally encounter than when autocompleting run or some flavor of emit.

[stephencelis]

I feel that .merge and .concatenate are too much "implementation detail" kind of naming. I don't find that their names intuitively describe their difference in behavior, neither does it show their similarity. Considering the future API names, I would suggest to split .merge into two different APIs:

These API names come from Combine/Rx/ReactiveSwift and behave in the same way. We adopted the names when the Effect type was more tightly coupled to the Combine framework. We could explore other names now that it isn't so tightly coupled, though we'd probably still want to lean on prior art for naming.

The reason I would introduce a separate .manySend API is because after you stated these are "rarely used" I checked my project and found 14 usages of .merge of which 12 were only using multiples of .send inside. I wouldn't call 14 uses in 38 reducers "rarely used" though.

Can you explain what these calls are used for? In general we advise against using Effect.send for things like sharing logic. The occasional use of Effect.send we have in our code bases is to communicate "delegate" actions to parent domains, and these are typically one-off effects and not effects that need to be merged.

Regarding .concatenate I only found 3 uses of it in my project, so that is rare. But I have a question: How is calling .concatenate different from using a .run with multiple await send(Action) calls inside? Isn't the behavior of .run already a "run one effect after the other" behavior? If so, maybe .concatenate could be entirely dropped in favor of .run?

As I mentioned, .merge and .concatenate aren't really for one-off reducers, but are instead intended to be used in reducer operators, where you may run a base reducer and a child reducer and then combine the Effect values somehow. Effects aren't really "runnable" on their own, so if you have 2 Effects that you've produced from running 2 reducers and want to run the first effect, let it complete, then run the other, you need to use Effect.concatenate.

P.S. The thread states that .task and .fireAndForget would receive "loud" warnings in 1.0 but I didn't get any on the prerelease/1.0 branch. Has the plan changed?

The thread is an RFC still, and hasn't landed in any branch.

[Jeehut]

@stephencelis I've read about your performance tips a few months ago and in fact I reworked some of my logic already to ensure my app stays performant. But I didn't run into any performance issues with most of them so I didn't change them all. Maybe I could actually rework them in a way that there's no need for .send or .merge, but this will take time.

An example use for merge with multiple sends is something like this:

      switch action {
      // ...
      case .binding(\.$translationKey):
         return .merge(
            .send(.checkKeyAlreadyExists),  // runs a long-running in-flight-cancellable effect and updates the state
            .send(.updateAutoCompletion),  // starts a long-running in-flight-cancellable effect and updates the state
            .send(.checkIntegerParam)  // runs a quick check and changes the state to "singular"/"plural" mode if needed
         )
      }

Looking at this code for example, I could easily put checkIntegerParam into a helper function as it's fast. But checkKeyAlreadyExists and updateAutoCompletion start long-running effects, both of them with their own in-flight cancellable IDs, how would I be able to do this without using .merge? Even if I put their entire logic into a function that receives an inout State and returns an Effect<Action> (which I do in many places already), I would still need to separate them because other interactions might trigger them, too. I want to start them both at the same time.

So it might be true that I'm incorrectly using .send, I'm not so sure about .merge though. Or am I missing something?

[stephencelis]

@Jeehut It's tough to tell from this sample, but are you only using these actions for code organization and to describe what's being done?

Could you have used helper methods and async let (or a task group) to achieve similar and eliminate most of these extra actions?

case .binding(\.$translationKey):
  return .run { send in
    async let keyExists = self.checkKeyAlreadyExists()
    async let autocompletionUpdate = self.updateAutoCompletion()
    async let mode = self.checkIntegerParam()

    await send(.keyResponse(keyExists))
    await send(.autocompletionResponse(autocompletionUpdate))
    await send(.modeResponse(mode))
  }

You have a lot of freedom here. You could pass the Send<Action> to the helpers if they need to spin off a long async sequence and feed multiple things back into the store. You could send binding actions to mutate state more directly, etc.

In general we recommend minimizing the number of actions you define and feed back into the system, the majority should be:

• User actions that map directly to a user input (like loginButtonTapped) or lifecycle event (like onAppear and scenePhaseChanged)
• Actions that feed data back into the reducer (like loginResponse or timerTick)

Both of these actions are "required": the system would generally not be able to function without them.

Then, a pattern we follow that is completely additive:

• "Delegate" actions that provide a more "public" interface to parent features to listen for, this is the majority of Effect.sends we have in our code bases. You can totally squeak by without these actions and have parent domains snoop on any action they may care about, but we think delegate actions are a better style of communication.

Beyond this, there may be some, but we're not sure there are many more, exceptions.

[Jeehut]

@stephencelis Thank you for the explanation and code example. You convinced me, I think I better understand now. I'll do another round of refactoring then. I will try to rework my structure to minimize the actions sent into the system like described above. With your distinction of different types of actions, things become more clear.

Only thing you didn't cover is cancellation. But I guess, I'll just have to use Structured Concurrency properly. I'll try.

I'm even thinking about introducing some subtypes to my Action to make things more clear, maybe something like Lifecycle, User, Effect, and ForParent. I'll play around with this idea while I'm doing the refactoring. I'll let you know if I run into a situation where I still need .merge or .send and explain in more detail why that was. But it might not even happen.

[stephencelis]

@Jeehut withTaskCancellation(id:) provides a way to "bracket" cancellable work in a larger async context, but this solution is a bit imperfect when it comes to testing and the unreliable nature of testing SwiftUI concurrency, so if you encounter a flakey test when testing cancellation logic that is bracketed this way, you may want to refactor to use some flavor of Effect.merge(a, b.cancellable(id:), c), etc., instead, to work around the problem.