ViewStore State's deduplication with DeduplicationScope

[tgrapperon]

One of the main issues with Redux-like architectures is the diffing of gigantic app states. TCA elegantly solves this by introducing ViewStore’s. They allow to observe only a relevant portion of a possibly very complex state, and in a SwiftUI app, they prevent unwanted View invalidations when none of the relevant properties of a View has changed.

A classic way to restrict ViewStore to only a portion of State is to use an internal ViewState. This ViewState is Equatable and the store’s state is mapped to a ViewState via store’s scoping. This approach can be observed in isowords, like in GameView for example (slightly modified for explanatory purposes):

public struct GameView: View {
  let store: Store<GameState, GameAction>
  @ObservedObject var viewStore: ViewStore<ViewState, GameAction>

  struct ViewState: Equatable {
    let isDailyChallenge: Bool
    let isGameLoaded: Bool
    let isNavVisible: Bool
    let isTrayVisible: Bool
    let selectedWordString: String

    init(state: GameState) {
      self.isDailyChallenge = state.isDailyChallenge
      self.isGameLoaded = state.isGameLoaded
      self.isNavVisible = state.isNavVisible
      self.isTrayVisible = state.isTrayVisible
      self.selectedWordString = state.selectedWordString
    }
  }

  public init(
    store: Store<GameState, GameAction>
  ) {
    self.store = store
    self.viewStore = ViewStore(self.store.scope(state: ViewState.init(state:)))
  }
[...]

As we can see, there is no specific logic in ViewState. It’s only an Equatable way to wrap a subset of GameState’ properties. Its only purpose is to provide access to these properties and make the ViewStore publish on its objectWillChange publisher when they change. The whole ViewState struct definition is 100% boilerplate in this specific case.

Furthermore, these ViewState’s don’t work out of the box with binding higher-order reducers, as they expect ViewStore.State == Store.State.

The DeduplicationScope I’m proposing allow to use ViewStore<State, Action> directly, and to specify a set of relevant properties used for deduplication in a very concise way. As an example, GameView becomes

public struct GameView<Content>: View where Content: View {
  let store: Store<GameState, GameAction>
  @ObservedObject var viewStore: ViewStore<GameState, GameAction>

  public init(
    store: Store<GameState, GameAction>
  ) {
    self.store = store
    self.viewStore = ViewStore(self.store) {
      \.isDailyChallenge
      \.isGameLoaded
      \.isNavVisible
      \.isTrayVisible
      \.selectedWordString
    }
  }
[...]

As you can see, the whole ViewState is gone, ViewStore.State == GameState, and we list a few GameState’s keypaths we want to watch for changes in a closure after the ViewStore’s instantiation. Furthermore, none of the code below these lines has to be modified. In this example, we are using Swift 5.4 @resultBuilder, but a chaining API is also provided:

ViewStore(self.store,
          deduplicationScope: .init(\.isDailyChallenge)
                              .and(\.isGameLoaded)
                              .and(\.isNavVisible)
                              .and(\.isTrayVisible)
                              .and(\.selectedWordString)
)

In other words, and under the hood, DeduplicationScope is a concise way to build the removeDuplicates closure of ViewStore. We avoid scoping the store for the only benefit of diffing a portion of its state, we don’t instantiate a whole new struct (and most importantly, we don’t have to define it), we can use the binding higher-order reducer out of the box, and we can access constant or non-equatable properties of State.

As a side effect of the implementation, observed properties are checked in the order they’re listed, and we can use this to our advantage to optimize comparison if needed.

The principal issue is the possibility to access an unobserved variable property in State if we forget to list it in the ViewStore’s instantiation. This problem is also frequent in vanilla SwiftUI if we forget to wrap properties with @Published. I guess one can modify the internals of ViewStore and log a message at runtime if the user is accessing a non-observed KeyPath. It could worth the effort if @mbrandonw or @stephencelis green-light it for TCA at some point. In the current state, the proposal is purely additive and can be implemented as a third-party library.

This also adds a few overloads to ViewStore, but it also helps to remove a bunch of code. I guess they can be refactored if needed.

ViewState’s are still very convenient when they carry some logic by themselves (for example, when they define new properties derived from State). This proposal aims at the trivial ones.

Please let me know what you think!
Should I document the code and prepare a PR with a case study?

Here is a complete first implementation of DeduplicationScope:

struct DeduplicationScope<Root> {
  public struct Predicate {
    let eval: (Root, Root) -> Bool
    public init(_ predicate: @escaping (Root, Root) -> Bool) {
      self.eval = predicate
    }

    public init<Value>(keyPath: KeyPath<Root, Value>) where Value: Equatable {
      self.eval = {
        $0[keyPath: keyPath] == $1[keyPath: keyPath]
      }
    }
  }

  let predicates: [Predicate]

  public init(predicates: [Predicate] = []) {
    self.predicates = predicates
  }

  public func scopesAreEqual(lhs: Root, rhs: Root) -> Bool {
    predicates.first { !$0.eval(lhs, rhs) } == nil
  }
}

// MARK: Chaining API
extension DeduplicationScope {
  public init<Value>(_ keyPath: KeyPath<Root, Value>) where Value: Equatable {
    self.predicates = [.init(keyPath: keyPath)]
  }

  public func and<Value>(_ keyPath: KeyPath<Root, Value>) -> Self where Value: Equatable {
    .init(predicates: predicates + [.init(keyPath: keyPath)])
  }
}

#if swift(>=5.4)
// MARK: ResultBuilder
extension DeduplicationScope {
  init(@PredicatesBuilder predicates: () -> [Predicate]) {
    self.predicates = predicates()
  }

  @resultBuilder
  enum PredicatesBuilder {
    static func buildBlock(_ components: DeduplicationScope<Root>.Predicate...)
      -> [DeduplicationScope<Root>.Predicate]
    {
      components
    }

    static func buildExpression<Value>(_ expression: KeyPath<Root, Value>)
      -> DeduplicationScope<Root>.Predicate
      where Value: Equatable
    {
      .init(keyPath: expression)
    }
  }
}
#endif

// MARK: ViewStore
extension ViewStore {
  convenience init(_ store: Store<State, Action>,
                   deduplicationScope: DeduplicationScope<State>)
  {
    self.init(store, removeDuplicates: deduplicationScope.scopesAreEqual)
  }
}

#if swift(>=5.4)
extension ViewStore {
  convenience init(_ store: Store<State, Action>,
                   @DeduplicationScope<State>.PredicatesBuilder predicates: ()
                     -> [DeduplicationScope<State>.Predicate])
  {
    self.init(store, deduplicationScope: DeduplicationScope(predicates: predicates()))
  }
}
#endif

// MARK: WithViewStore
import SwiftUI
extension WithViewStore where Content: View {
  init(
    _ store: Store<State, Action>,
    deduplicationScope: DeduplicationScope<State>,
    @ViewBuilder content: @escaping (ViewStore<State, Action>) -> Content
  ) {
    self = WithViewStore(store,
                         removeDuplicates: deduplicationScope.scopesAreEqual,
                         content: content
    )
  }
}

#if swift(>=5.4)
extension WithViewStore where Content: View {
  init(
    _ store: Store<State, Action>,
    @DeduplicationScope<State>.PredicatesBuilder predicates: () -> [DeduplicationScope<State>.Predicate],
    @ViewBuilder content: @escaping (ViewStore<State, Action>) -> Content
  ) {
    self = WithViewStore(store,
                         deduplicationScope: DeduplicationScope(predicates: predicates()),
                         content: content
    )
  }
}
#endif

[AlexisQapa]

I like the idea and that's a nice use of resultbuilder !

I still see value in having a type containing the view's state, it limits which properties of the state are available to the layout and serve as developer documentation. I also often start a feature without TCA integration by poking layouts using static viewStates. When I have my viewState and viewAction ready, I work toward integrating with TCA and the rest of the app.

I wonder if ResultBuilders could be used to define the type of the viewState in a way that would make only interesting properties available.

[tgrapperon]

I don’t think this is achievable with @resultbuilder at build time unfortunately, as they can only build already existing types. The DeduplicationScope also supports free functions instead of KeyPath’s, but it looks like that if you limit its use to KeyPath’s and make a ViewState generic wrapper, you should be able to check requested properties at runtime using @dynamicMemberLookup. These checks would occur only for development builds, and could log or assert on unobserved property access. I’ll try to implement something like this if this goes farther.

By using a generic ViewState wrapper, one would fall back in the regular ViewState case though, and the only benefit of DeduplicationScope would be the definition of observed properties. Maybe something based on codegen would be a better option in this case.

@resultBuilder’s are a fantastic tool, and there are probably many places they can be used in TCA, like Reducer’s composition for example. I don’t know if they’ll provide much better API though. I’ll start experimenting out of curiosity.

[tgrapperon]

We can also use PropertyWrapper’s in the State to decorate eligible properties. A specific version of ViewStore could only expose these properties and use them for diffing. I’ll also experiment in this direction as it looks like it could provide the best of both worlds.

[Sajjon]

This seems like a great idea to reduce boilerplate! Idea presented 10 months ago, I'm curious why this idea hasn't been picked up..? @tgrapperon maybe open a PR? Or is your solution incompatible with new versions of TCA? I guess a lot has happened since May 2021?

Cheers!

[tgrapperon]

Thanks for the feedback @Sajjon. I didn't push farther because the feature is "unsafe": You can easily reach a property that you forgot to compare, and you'll miss its updates. A dedicated ViewState type can also store derived values. I think this has almost zero chances to be brought inside TCA anyway, as maintainers are trying to keep the library the leanest possible. If something can be implemented as a third party, then it should probably be. I'm even starting to think that bindings should be extracted in a separated module in the future (shipping or not with TCA itself).

But it can indeed be convenient when iterating on a new feature. It's maybe possible to generate some boilerplate for an ad-hoc ViewState from the list of KeyPaths. I'll think about it.
This just an alternative way to build the removeDuplicate closure used when instantiating ViewStore. It works fine with the latest versions of TCA. Generic KeyPath access like this is still a little slower than using explicit comparisons though (this is a Swift limitation that may improve in the future).

You should be able to copy-paste the code here and use it in your project if you want!

[acosmicflamingo]

I'm curious why any View object has a ViewState in it at all now that TCA has "WithViewStore" functionality (as presented in swift-composable-architecture's README):

struct AppView: View {
  let store: Store<AppState, AppAction>

  var body: some View {
    WithViewStore(self.store) { viewStore in  <---- replaces need to write explicit ViewState code
      VStack {
        HStack {
          Button("−") { viewStore.send(.decrementButtonTapped) }
          Text("\(viewStore.count)")
          Button("+") { viewStore.send(.incrementButtonTapped) }
        }

        Button("Number fact") { viewStore.send(.numberFactButtonTapped) }
      }
      .alert(
        item: viewStore.binding(
          get: { $0.numberFactAlert.map(FactAlert.init(title:)) },
          send: .factAlertDismissed
        ),
        content: { Alert(title: Text($0.title)) }
      )
    }
  }
}

I've been looking at some of isowords to learn more about TCA and am finding these explicit ViewStates everywhere: https://github.com/pointfreeco/isowords/blob/main/Sources/HomeFeature/Home.swift#L541:

public struct HomeView: View {
  struct ViewState: Equatable {
    let hasActiveGames: Bool
    let hasChangelog: Bool
    let isChangelogVisible: Bool
    let isNagBannerVisible: Bool
    let tag: HomeRoute.Tag?

    init(state: HomeState) {
      self.hasActiveGames =
        state.savedGames.dailyChallengeUnlimited != nil
        || state.savedGames.unlimited != nil
        || !state.turnBasedMatches.isEmpty
      self.hasChangelog = state.hasChangelog
      self.isChangelogVisible = state.changelog != nil
      self.isNagBannerVisible = state.nagBanner != nil
      self.tag = state.route?.tag
    }
  }

  @Environment(\.colorScheme) var colorScheme
  let store: Store<HomeState, HomeAction>
  @ObservedObject var viewStore: ViewStore<ViewState, HomeAction>

  public init(store: Store<HomeState, HomeAction>) {
    self.store = store
    self.viewStore = ViewStore(store.scope(state: ViewState.init))
  }

Why not just do something like this:

extension HomeState {
    var bool hasActiveGames {
      savedGames.dailyChallengeUnlimited != nil
          || savedGames.unlimited != nil
          || !turnBasedMatches.isEmpty
    }
    var bool isChangelogVisible { changelog != nil }
    var bool isNagBannerVisible { nagBanner != nil }
    var Int tag { route?.tag }
}

At what point is it better to create a ViewState class within a View over using the really nifty WithViewStore? I feel like explicitly adding ViewStates to Views just creates redundant boilerplate code, which makes the View struct more bloated than it needs to be. Am I missing something? Or has isowords just not been updated to replace all ViewState structs with WithViewStores because there are higher priority items to work on?

[tgrapperon]

These are different tools to solve different problems.
WithViewStore is only a convenient way to make your SwiftUI View react to its store's changes. When you use it, it is equivalent to installing @ObservedObject var viewStore: ViewStore in your View. Otherwise, the View would not update automatically when values are changing.

The ViewState approach is not formalized in TCA: this is simply a scope of the store's state into a smaller state, in the same fashion you scope when you compose features (albeit you also "scope" the actions, which is also possible with ViewState/ViewAction, like you can observe in TicTacToe). You do this to restrict the surface of the state presented to the view for two reasons:

• To improve performance by only performing diffing on smaller values instead of the whole state.
• To restrict what the View can see and formalize the ViewStore's contextual "API".

The first reason is by far the main reason why you use ViewStates. Imagine that your view displays a shelf of books. You don't need to know the exact content of the books to draw your shelf: you only need to know their number, color, title, number of pages, etc. If you don't use a ViewState, each time something changes, the app may need to "read" all the books to check if they have changed. It will very likely spend too much time doing so, and you'll miss frames, and the app will become choppy/unresponsive. Now, if you project each book to a "shell" struct that holds only what you want (the title, the color, etc), it will be very simple for the app to compare two arrays of these books' shells to check if their order has changed or if you added some new books. You view doesn't need the content of the books to show them on a shelf, so you don't need to lose time reading them when something changes. That's the idea behind the first reason, and it imposes itself to you when you're working on large apps and performance becomes a concern. For this reason, it is probably a good habit to use ViewState as soon as some feature bears more information than displayed (excepted when this non-visible information is very lightweight).

The second reason is to constrain what your view can reach, and ViewAction like in TicTacToe serve the same purpose. These are only safeguards to prevent the developer to reach what they shouldn't in some context. This is exactly kind of the safety DeduplicationScope was losing, and the reason why I stopped to use them internally.

The common practice is to use WithViewStore with a ViewState, so you get the best of both worlds. WithViewStore is the tool that allows SwiftUI views to react to ViewState changes.

[mbrandonw]

In addition to everything @tgrapperon said, we are adding some documentation to this very topic (and more) that will be merged next week. Here's a preview.

[acosmicflamingo]

@tgrapperon @mbrandonw wow thank you so much for all this wonderful information!!! Yes it absolutely makes sense now 🤩 glad I asked!