Sharing state in the Composable Architecture

[LK]

The Problem

A common problem that I run into is the need to have some state shared across many levels of the reducer/store hierarchy.

One option is to replicate the same state across multiple sub-states:

See code

struct User {
    // ...
}

struct AppState {
    var authenticatedUser: User
    var gameState: GameState
    var leaderboardState: LeaderboardState
}

struct GameState {
    var authenticatedUser: User
    // ...
}

struct LeaderboardState {
    var authenticatedUser: User
    // ...
}

This works, but now I need to make sure that I keep all of the copies of my authenticatedUser in sync. If my game state reducer updates some field on the user, my global reducer needs to remember to copy over the user state everywhere else, or I risk missing out on some state changes in other parts of my app. I end up losing some of the benefits of being able to compose reducers because my global reducer must be bloated with this excess logic for each copy of authenticatedUser.

A more promising approach is to retain a single source of truth for the shared state. If there's only one authenticatedUser hanging around, we no longer need to worry about keeping state changes synced up. We can even make some convenient helper functions — inspired by pullback, scope, and friends — to do the heavy lifting for us and eliminate some of the boilerplate.

See code

struct Merged<Context, State> {
    let context: Context
    let state: State

    // We can even use @dynamicMemberLookup to hide the extra layer of indirection we introduce here.
}

extension Store {
    func scopeWithContext<Context, GlobalPrivateState, LocalPrivateState, LocalAction>(
        state toLocalPrivateState: @escaping (GlobalPrivateState) -> LocalPrivateState,
        action toGlobalAction: @escaping (LocalAction) -> Action
    ) -> Store<Merged<Context, LocalPrivateState>, LocalAction>
    where State == Merged<Context, GlobalPrivateState> {
        // ...
    }
}

extension Reducer {
    func pullbackWithContext<
        Context, LocalPrivateState, GlobalPrivateState, GlobalAction, GlobalEnvironment
    >(
        state toLocalState: WritableKeyPath<GlobalPrivateState, LocalPrivateState>,
        action toLocalAction: CasePath<GlobalAction, Action>,
        environment toLocalEnvironment: @escaping (GlobalEnvironment) -> Environment
    ) -> Reducer<Merged<Context, GlobalPrivateState>, GlobalAction, GlobalEnvironment>
    where State == Merged<Context, LocalPrivateState> {
        // ...
    }
}

Now, we can traverse up and down the state tree and take the context along as we go. When we use scopeWithContext, we're not converting from Store<GlobalState, GlobalAction> to Store<LocalState, LocalAction> anymore — we can convert Store<Merged<Context, GlobalState>, GlobalAction> to Store<Merged<Context, LocalState>, LocalAction>. (The logic works similarly for converting reducers that operate on Merged<Context, LocalState> to those that operate on Merged<Context, GlobalState> using pullbackWithContext.)

This works, but we run into a pretty annoying problem: if we need to use the context towards the bottom of the state tree, every store/reducer above it must also carry the context along with it. Since all (or most) of our stores/reducers now have a state type of Merged<Context, State>, a lot of the convenient helpers that TCA provides — think .optional, .forEach, IfLetStore, etc. — no longer fit the bill. If we used to have a store that held on to something of type OptionalState?, we would use IfLetStore to conditionally render something based on the nullity of the value in the store. But now, our store would hold on to something that looks like Merged<Context, OptionalState?>, and that no longer fits. We would need to reinvent every utility to understand our new state structure.

The Solution

Instead of passing the context all the way up and down the state tree, we can borrow a page from React[1] and introduce the context anywhere we need it directly, without needing to pass it down through scopes and pullbacks. To do that, we introduce the concept of a ContextHandle — a global reference to our app's context — that our store and reducers can connect to as necessary. Here's what that might look like:

struct Context {
    var authenticatedUser: User
}

let contextHandle: ContextHandle<Context>(.init(authenticatedUser: /* ... */))

let appStore: Store<AppState, AppAction> = // ...
let localStore: Store<Merged<Context, LocalState>, LocalAction> = appStore
    .scope(/* ... */)
    .withContext(contextHandle)

let globalReducer: Reducer<AppState, AppAction, AppEnvironment> = .combine(
    Reducer<Merged<Context, LocalState>, LocalAction, LocalEnvironment> {
        // ...
    }
    .withContext(contextHandle)
    .pullback(/* ... */),
    // ...
)

Importantly, we can continue to scope down stores and reducers without passing along the context at every step. This means that all of the existing helper utilities will continue to work as they used to, but we can selectively plug in to the app context for cases where it's necessary. It also means that we can eliminate the number of state updates we need to deal with, since only the relevant features will get updated when the global context changes.

Testability

The introduction of a global uncontrolled dependency — the context handle — can make testing a challenge. There are two approaches we can use:

1. Control the global context handle in the tests directly. Because the global context contains a mutable reference to the context state, we can mutate the context state before running a feature's tests. However, this breaks the isolation between test cases and can cause unpredictable behavior if not controlled properly.
2. Use .withContext() within the test itself. With this approach, each feature that relies on the app context will export a reducer that operates on Merged<Context, State>. In the test, we can create a (local) context handle, call .withContext to get a reducer that operates just on State, and then run our tests from there. We will now have a local context that we can manipulate for our tests that won't interfere with other reducers, but this requires diligence to avoid accidentally leaking in a dependency on global state.

One potential solution is to derive the context handle from the environment (in this case, the function signature of Reducer.withContext would change to take an argument of type (Environment) -> ContextHandle). Combined with the SystemEnvironment approach, we can (partially) still alleviate the boilerplate of passing the context down every level of the hierarchy, but we can fully control the context handle from our tests. However the store's .withContext would still require a global dependency. I'm open to thoughts/ideas!

Composition

Using a single global context can also make it challenging to decompose an app into separate build targets. If the individual screens are each located in their own build target, they cannot depend on a global context that is defined in the main build target. However, they can define their own context handles for feature-specific shared data. For cases where the context type is shared across multiple features, we can just use a shared library that all build targets depend on.

The Conclusion

I have a fork of TCA that implements some of these ideas, but I'm open to hearing thoughts on what the best approach here would be. This has been one of the few and biggest pain points for me when building a large project around TCA, and I'm sure I'm not the only one, so excited to hear what others think.

-LK

[iampatbrown]

Hey @LK Just saw your post over at Swift Forums :) Thanks for reminding me to check this out. I'll have a look later today and let you know what I think :) Awesome post!

[eimantas]

Thanks for the write up! Sharing a global state across the app of >10 modules is also a challenge I am trying to work with.

Considering all of the points you mentioned (testability, composition, etc.) how does context differ from environment? One can define a var on root environment like userData: () -> User? and use it in reducers transparently w/o state knowing a lot of stuff (that's how I currently "roll").

[iampatbrown]

@eimantas makes a good point about using the environment. It would also be possible to use Effect.run to subscribe to changes to the shared environment context. I'm hesitant about using this myself as I like to keep modules isolated from each other. I opt for the computed property approach at the moment, which despite the boiler plate, has been working pretty well.

The Merged/CombinedState struct is pretty nice as a general way to merge two states. I'll start trying to use that more if I can.

I'm keen to see where you go with this. Some nice ideas and definitely a common problem people have :)

Thanks for taking the time to write this up and sharing it with us.

[LK]

@iampatbrown Thanks for the input! Could you expand a bit more on how this breaks module isolation? As far as I see it, if you have shared state or dependencies you will likely need some shared module anyway, and the context handle could just live in the same place. At test time you can swap out the handle in the environment to control what shared state your reducers see/controls.

[iampatbrown]

Changes to the Context struct will impact all modules that depend on it right?

[LK]

Isn't the same true with the computed property approach?

[iampatbrown]

I might be misunderstanding something... do the feature stores/reducers refer to Merged<Context, State> or just State? What would this example look like using Context

struct StateA: Equatable { var user, value: String }
enum ActionA { case changedUser(String), changedValue(String) }
let reducerA = Reducer<StateA, ActionA, Void>.empty

struct StateB: Equatable { var user, value, bAndC: String }
enum ActionB { case changedUser(String), changedValue(String), changedBAndC(String) }
let reducerB = Reducer<StateB, ActionB, Void>.empty

struct StateC: Equatable { var user, value, bAndC: String }
enum ActionC { case changedUser(String), changedValue(String), changedBAndC(String) }
let reducerC = Reducer<StateC, ActionC, Void>.empty

struct AppState: Equatable {
  var user, onlyA, onlyB, onlyC, bAndC: String

  var stateA: StateA {
    get { .init(user: user, value: onlyA) }
    set { user = newValue.user; onlyA = newValue.value }
  }

  var stateB: StateB {
    get { .init(user: user, value: onlyB, bAndC: bAndC) }
    set { user = newValue.user; onlyB = newValue.value; bAndC = newValue.bAndC }
  }

  var stateC: StateC {
    get { .init(user: user, value: onlyC, bAndC: bAndC) }
    set { user = newValue.user; onlyC = newValue.value; bAndC = newValue.bAndC }
  }
}

enum AppAction { case a(ActionA), b(ActionB), c(ActionC) }

let appReducer = Reducer<AppState, AppAction, Void>.combine(
  reducerA.pullback(state: \AppState.stateA, action: /AppAction.a, environment: {}),
  reducerB.pullback(state: \AppState.stateB, action: /AppAction.b, environment: {}),
  reducerC.pullback(state: \AppState.stateC, action: /AppAction.c, environment: {})
)

[AlexisQapa]

When I just need to add a simple value to my state I use something like

public func both<Whole, A, B>(_ a: @escaping (Whole) -> A?, _ b: @escaping (Whole) -> B?) -> (Whole) -> (A, B)? {
	{
		guard let va = a($0), let vb = b($0) else { return nil }
		return (va, vb)
	}
}

public func both<Whole, A, B>(_ a: @escaping (Whole) -> A, _ b: @escaping (Whole) -> B?) -> (Whole) -> (A, B)? {
	{
		guard let vb = b($0) else { return nil }
		return (a($0), vb)
	}
}

public func both<Whole, A, B>(_ a: @escaping (Whole) -> A, _ b: @escaping (Whole) -> B) -> (Whole) -> (A, B) {
	{
		(a($0), b($0))
	}
}

so I can do store.scope(state: both(\.first, \.second)) thought I usually either use a computed property or replay the state depending on the feature needs.

One downside is naming the parts of the module state which become a tuple of states.

[LK]

Cool idea, will definitely borrow this; thanks!

[jtouzy]

What about Shared State from CaseStudies ?

All our app is based on this mechanism for state sharing.
We don't have any subState property in the parent state, they're always computed to keep the full modules tree entirely reactive to any changes. And no performance issue tho.

As an example :

extension BottomTabBarContainer.State {
  var bottomTabBarState: BottomTabBar.State {
    get {
      .init(
        theme: theme,
        items: items,
        selectedItemId: selectedItemId
      )
    }
    set {
      items = newValue.items
      selectedItemId = newValue.selectedItemId
    }
  }
}

[LK]

Thanks for the data point! We found that for a complicated enough state tree, the boilerplate was a bit too heavy to deal with. So the goal going in was to get the same behavior with less code. As an added bonus, if we only need some shared state several layers deep in the state tree, we no longer need to pass it through every intermediate layer that doesn't need the shared state.

[SebastianBoldt]

I am currently experiencing the same problems while using TCA.
1.If I want to share state between my parent and my child, the approach from the case studies works for simple view relationships but for me it's hard to understand how to use it when the child also has sub-child states that also need to get initialised somehow?
2. @jtouzy Does this mean that the parent state has every possible value from all the sub features already in it?

The most feasible solution for me so far is, that every state holds a copy of the value that should trigger the update and it gets updated inside the reducer and bubbles down the hierarchy -> But here is another thing that bothers me: I am note sure how this works if not all States are connected using .scope, for example if you have a feature with a local scope that is not connected to it's parent state.