RFC: Adding filtering to _printChanges(). (I would like input designing the API, please.)

[DandyLyons]

Motivation

One of many phenomenal features of TCA is how one simple line MyReducer()._printChanges() can instantly give you sight over every single action and state change within that Reducer.

But as the app expands over time, the amount of actions and state changes balloons to the point where relevant print statements get buried in a sea of other print statements.

Proposal

Introducing filtering to _printChanges(). I've created new API's to enable filtering. You can filter by which actions you want to be notified of, or which changes you want to be notified of. The implementation for this filtering is super simple, so you can add it to your project today. Just paste in this code: https://gist.github.com/DandyLyons/c185418ec296923bdaced1bcef951c44

I made a PR for this feature, however we agreed that the API design should be refined (hence this discussion). It also still needs to be decided whether this should be added directly to TCA proper or if it would be better to be maintained externally. (If it's decided that it should be maintained externally, then I would be more than happy to release it as a Package.)

Filtering printChanges by Actions:

// Simply return true if you want it to print
MyReducer()
// Print only certain actions
._printChanges(
    .filtered(
    actions: { action in
        // print other actions, but don't print `.childPlayer(.updateProgress)` actions
        switch action {
        case .childPlayer(.updateProgress):
            return false
        default: return true
        }
    })
)

Filtering printChanges by Changes:

// Print only certain changes
._printChanges(
    .filtered(
    changes: { oldState, newState in
        // only print when sheetPlayer changes
        oldState.sheetPlayer != newState.sheetPlayer
    })
)

@mbrandonw suggested an even simpler API which would accept a variadic list of PartialCaseKeyPath<Action>:

Feature()
  ._printChanges(
    actions: \.destination.child1, \.destination.child2
  )

(I don't know have experience with PartialCaseKeyPath so I would appreciate some help implementing this.)

Next Steps

1. Please give me feedback on the call site for these APIs. How could they be improved to be more ergonomic, discoverable etc.
2. Please give me feedback on the actual print structure. I've simply copied and pasted the code from _printChanges() with minimal filtering logic. But perhaps we might want some other changes. Implementation is here.

Future Explorations

We could add a _logChanges() function, that would behave just like _printChanges() except is would log using OSLog's Logger.
See: #2970

[fabstu]

I updated _printChanges() for the old WithViewStore to count same-changes into how many times they occur, super rudimentary collecting changes per second and printing together. This visualized list entries rerendering very well. Hiding initial state diffs was useful as well, not sure whether that was included in printChanges already. But not sure whether it fits into Reducers printing state changes. Just wanted to mention it incase you wanna go in a similar route.

Examples:

19x WithViewStore Interleaf/FocusNoteViewModifier.swift#78 <FocusSync.Update, FocusSync.Action, ...>
    8x (Changed state)
    - FocusSync.Update.update(
    -   updateID: "focus-update_50EF308E-CFF3-42A3-A9A7-EA8F609DFF30",
    -   currentlyFocusedItemID: AnyPrefixedUUID(value: "Node_A4676F8A-A70C-4537-A553-6A4A0D47B179")
    - )
    + FocusSync.Update.none
    8x (Changed state)
    - FocusSync.Update.none
    + FocusSync.Update.update(
    +   updateID: "focus-update_96E52955-D390-44C9-97C8-1E38D731C73F",
    +   currentlyFocusedItemID: AnyPrefixedUUID(value: "Node_A4676F8A-A70C-4537-A553-6A4A0D47B179")
    + )
    3x (Initial state) [diffs hidden]
1x WithViewStore Interleaf/LocalTextEditor.swift#112 <PrefixedUUID<Models.SourceIDs.Node>, Item.Action, ...>
    1x (Initial state) [diffs hidden]
1x WithViewStore Interleaf/ItemHeadView.swift#93 <ItemViewState.Path, Item.Action, ...>
    1x (Changed state)
      ItemViewState.Path(
        components: [
          … (4 unchanged),
    -     [4]: "New Source"
    +     [4]: "New Source3"
        ]
      )

9x WithViewStore Interleaf/FocusNoteViewModifier.swift#78 <FocusSync.Update, FocusSync.Action, ...>
    8x (Changed state)
    - FocusSync.Update.none
    + FocusSync.Update.update(
    +   updateID: "focus-update_F9974156-B891-4DFA-8849-6898D0700051",
    +   currentlyFocusedItemID: AnyPrefixedUUID(value: "Node_A4676F8A-A70C-4537-A553-6A4A0D47B179")
    + )
    1x (Initial state) [diffs hidden]

It was controlled with a minimal .logging(.statistics/.direct.hideInitialStateDiffs).

It worked also recursively, not sure about the feasibility with Reducers. That was useful to see all changes in a view tree to track down slowdown.

[DandyLyons]

That's a really interesting use case.

I don't understand the .logging(.statistics/.direct.hideInitialStateDiffs) syntax. What is the / after statistics?

I wonder if the print outs could be even more helpful if you were to calculate a changes per second metric that was averaged over the last say 30 seconds. There would need to be some sort of way to cache the count of changes from prior seconds though.

It looks like an older version of TCA used to have a similar method on WithViewStore called.debug(String). See: https://pointfreeco.github.io/swift-composable-architecture/0.41.0/documentation/composablearchitecture/withviewstore/debug(_:)

[fabstu]

/ is to note either .statistics or .direct with one as default. Maybe .debug was the one I modified, not sure anymore. The .hideInitialStateDiffs after is supposed to denote it is chainable. Could also be a list of options instead.

wonder if the print outs could be even more helpful if you were to calculate a changes per second metric that was averaged over the last say 30 seconds.

My usecase was reducing the amount of re-evaluations for a single user action/scrolling, with lists this was super obscured due to the repetitions showing too many log messages. Average per second would be a different usecase? Maybe for continuous changes, hmm.

There would need to be some sort of way to cache the count of changes from prior seconds though.

Used a [String: Int] counter on the log messages for that, maybe kinda slow (dunno) but gets the job done. Could also use polynomial rolling hash or something.

This usecase might be useless for reducers. I think a simple filter function does not really need this. I just hoped if you do grouping, the format I thought beautiful for the task. :)

[DandyLyons]

@mbrandonw or @stephencelis: I'm curious about the motivation behind why _ReducerPrinter is named with a _. Is it meant to be an internal type? If I were to maintain an extension library that adds filtering, would it be an issue?

[mbrandonw]

It's just mimicking SwiftUI's _printChanges for now. feel free to use it.