[BREAKING CHANGE]: update WorkflowAction API to expose access to Workflow instance values (#349)

this BREAKING change updates the WorkflowAction API to pass through a
new parameter in the `apply()` method that allows reading values off the
corresponding node's current Workflow instance. the new method signature
is:

```swift
func apply(toState state: inout State, context: ApplyContext<WorkflowType>) -> Output?
```

which mirrors the `render()` API, but uses a new `ApplyContext`
parameter to expose access to the runtime-managed data. the public API
for `ApplyContext` exposes a read-only subscript for accessing Workflow
values via keypath:

```swift
public struct ApplyContext<WorkflowType: Workflow> {
    public subscript<Value>(
        workflowValue keyPath: KeyPath<WorkflowType, Value>
    ) -> Value 
}
```
---

for reviewing purposes, i'd suggest using the 'commit filter' function
to exclude the commit labeled 'AUTOMATED' as that one is essentially
just noise where a bunch of new parameters were added.

also, there's definitely some more documentation to be written here, but
i've currently punted on that somewhat. do feel free to point out places
you'd like to see anything specific though.

Author: jamieQ

Samples/AsyncWorker/Sources/AsyncWorkerWorkflow.swift

@@ -34,7 +34,7 @@ extension AsyncWorkerWorkflow {
 
         typealias WorkflowType = AsyncWorkerWorkflow
 
-        func apply(toState state: inout AsyncWorkerWorkflow.State) -> AsyncWorkerWorkflow.Output? {
+        func apply(toState state: inout AsyncWorkerWorkflow.State, context: ApplyContext<WorkflowType>) -> AsyncWorkerWorkflow.Output? {
             switch self {
             // Update state and produce an optional output based on which action was received.
             case .fakeNetworkRequestLoaded(let result):

Samples/ObservableComposition/Sources/CounterWorkflow.swift

@@ -49,7 +49,7 @@ struct CounterWorkflow: Workflow {
         case increment
         case decrement
 
-        func apply(toState state: inout CounterWorkflow.State) -> CounterWorkflow.Output? {
+        func apply(toState state: inout CounterWorkflow.State, context: ApplyContext<WorkflowType>) -> CounterWorkflow.Output? {
             switch self {
             case .increment:
                 state.count += state.info.stepSize

Samples/ObservableComposition/Sources/MultiCounterWorkflow.swift

@@ -31,7 +31,7 @@ struct MultiCounterWorkflow: Workflow {
     struct ResetAction: WorkflowAction {
         typealias WorkflowType = MultiCounterWorkflow
 
-        func apply(toState state: inout MultiCounterWorkflow.State) -> Never? {
+        func apply(toState state: inout MultiCounterWorkflow.State, context: ApplyContext<WorkflowType>) -> Never? {
             state.resetToken = .init()
             return nil
         }
@@ -43,7 +43,7 @@ struct MultiCounterWorkflow: Workflow {
 
         case showSum(Bool)
 
-        func apply(toState state: inout MultiCounterWorkflow.State) -> Never? {
+        func apply(toState state: inout MultiCounterWorkflow.State, context: ApplyContext<WorkflowType>) -> Never? {
             switch self {
             case .showSum(let showSum):
                 state.showSum = showSum
@@ -58,7 +58,7 @@ struct MultiCounterWorkflow: Workflow {
         case addCounter
         case removeCounter(UUID)
 
-        func apply(toState state: inout MultiCounterWorkflow.State) -> Never? {
+        func apply(toState state: inout MultiCounterWorkflow.State, context: ApplyContext<WorkflowType>) -> Never? {
             switch self {
             case .addCounter:
                 state.addCounter()

Samples/SampleApp/Sources/DemoWorkflow.swift

@@ -76,7 +76,7 @@ extension DemoWorkflow {
         case refreshComplete(String)
         case refreshError(Error)
 
-        func apply(toState state: inout DemoWorkflow.State) -> DemoWorkflow.Output? {
+        func apply(toState state: inout DemoWorkflow.State, context: ApplyContext<WorkflowType>) -> DemoWorkflow.Output? {
             switch self {
             case .titleButtonTapped:
                 switch state.colorState {

Samples/SampleApp/Sources/RootWorkflow.swift

@@ -45,7 +45,7 @@ extension RootWorkflow {
 
         case login(name: String)
 
-        func apply(toState state: inout RootWorkflow.State) -> RootWorkflow.Output? {
+        func apply(toState state: inout RootWorkflow.State, context: ApplyContext<WorkflowType>) -> RootWorkflow.Output? {
             switch self {
             case .login(name: let name):
                 state = .demo(name: name)

Samples/SampleApp/Sources/WelcomeWorkflow.swift

@@ -46,7 +46,7 @@ extension WelcomeWorkflow {
         case nameChanged(String)
         case login
 
-        func apply(toState state: inout WelcomeWorkflow.State) -> WelcomeWorkflow.Output? {
+        func apply(toState state: inout WelcomeWorkflow.State, context: ApplyContext<WorkflowType>) -> WelcomeWorkflow.Output? {
             switch self {
             case .nameChanged(let updatedName):
                 state.name = updatedName

Samples/SplitScreenContainer/DemoApp/DemoWorkflow.swift

@@ -43,7 +43,7 @@ extension DemoWorkflow {
 
         case viewTapped
 
-        func apply(toState state: inout DemoWorkflow.State) -> Never? {
+        func apply(toState state: inout DemoWorkflow.State, context: ApplyContext<WorkflowType>) -> Never? {
             switch self {
             case .viewTapped:
                 state += 1

Samples/TicTacToe/Sources/Authentication/AuthenticationWorkflow.swift

@@ -61,7 +61,7 @@ extension AuthenticationWorkflow {
         case authenticationError(AuthenticationService.AuthenticationError)
         case dismissAuthenticationAlert
 
-        func apply(toState state: inout AuthenticationWorkflow.State) -> AuthenticationWorkflow.Output? {
+        func apply(toState state: inout AuthenticationWorkflow.State, context: ApplyContext<WorkflowType>) -> AuthenticationWorkflow.Output? {
             switch self {
             case .back:
                 switch state {

Samples/TicTacToe/Sources/Authentication/LoginWorkflow.swift

@@ -49,7 +49,7 @@ extension LoginWorkflow {
         case passwordUpdated(String)
         case login
 
-        func apply(toState state: inout LoginWorkflow.State) -> LoginWorkflow.Output? {
+        func apply(toState state: inout LoginWorkflow.State, context: ApplyContext<WorkflowType>) -> LoginWorkflow.Output? {
             switch self {
             case .emailUpdated(let email):
                 state.email = email

Samples/TicTacToe/Sources/Game/ConfirmQuitWorkflow.swift

@@ -56,7 +56,7 @@ extension ConfirmQuitWorkflow {
 
         typealias WorkflowType = ConfirmQuitWorkflow
 
-        func apply(toState state: inout ConfirmQuitWorkflow.State) -> ConfirmQuitWorkflow.Output? {
+        func apply(toState state: inout ConfirmQuitWorkflow.State, context: ApplyContext<WorkflowType>) -> ConfirmQuitWorkflow.Output? {
             switch self {
             case .cancel:
                 return .cancel

Samples/TicTacToe/Sources/Game/RunGameWorkflow.swift

@@ -58,7 +58,7 @@ extension RunGameWorkflow {
         case back
         case confirmQuit
 
-        func apply(toState state: inout RunGameWorkflow.State) -> RunGameWorkflow.Output? {
+        func apply(toState state: inout RunGameWorkflow.State, context: ApplyContext<WorkflowType>) -> RunGameWorkflow.Output? {
             switch self {
             case .updatePlayerX(let name):
                 state.playerX = name

Samples/TicTacToe/Sources/Game/TakeTurnsWorkflow.swift

@@ -47,7 +47,7 @@ extension TakeTurnsWorkflow {
 
         case selected(row: Int, col: Int)
 
-        func apply(toState state: inout TakeTurnsWorkflow.State) -> TakeTurnsWorkflow.Output? {
+        func apply(toState state: inout TakeTurnsWorkflow.State, context: ApplyContext<WorkflowType>) -> TakeTurnsWorkflow.Output? {
             switch state.gameState {
             case .ongoing(turn: let turn):
                 switch self {

Samples/TicTacToe/Sources/Main/MainWorkflow.swift

@@ -48,7 +48,7 @@ extension MainWorkflow {
         case authenticated(sessionToken: String)
         case logout
 
-        func apply(toState state: inout MainWorkflow.State) -> MainWorkflow.Output? {
+        func apply(toState state: inout MainWorkflow.State, context: ApplyContext<WorkflowType>) -> MainWorkflow.Output? {
             switch self {
             case .authenticated(sessionToken: let sessionToken):
                 state = .runningGame(sessionToken: sessionToken)

Samples/Tutorial/Frameworks/Tutorial1Complete/Sources/Welcome/WelcomeWorkflow.swift

@@ -47,7 +47,7 @@ extension WelcomeWorkflow {
 
         case nameChanged(name: String)
 
-        func apply(toState state: inout WelcomeWorkflow.State) -> WelcomeWorkflow.Output? {
+        func apply(toState state: inout WelcomeWorkflow.State, context: ApplyContext<WorkflowType>) -> WelcomeWorkflow.Output? {
             switch self {
             case .nameChanged(name: let name):
                 // Update our state with the updated name.

Samples/Tutorial/Frameworks/Tutorial2Complete/Sources/RootWorkflow.swift

@@ -54,7 +54,7 @@ extension RootWorkflow {
         case logIn(name: String)
         case logOut
 
-        func apply(toState state: inout RootWorkflow.State) -> RootWorkflow.Output? {
+        func apply(toState state: inout RootWorkflow.State, context: ApplyContext<WorkflowType>) -> RootWorkflow.Output? {
             switch self {
             case .logIn(name: let name):
                 // When the `login` action is received, change the state to `todo`.

Samples/Tutorial/Frameworks/Tutorial2Complete/Sources/Todo/List/TodoListWorkflow.swift

@@ -45,7 +45,7 @@ extension TodoListWorkflow {
     enum Action: WorkflowAction {
         typealias WorkflowType = TodoListWorkflow
 
-        func apply(toState state: inout TodoListWorkflow.State) -> TodoListWorkflow.Output? {
+        func apply(toState state: inout TodoListWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoListWorkflow.Output? {
             switch self {
                 // Update state and produce an optional output based on which action was received.
             }

Samples/Tutorial/Frameworks/Tutorial2Complete/Sources/Welcome/WelcomeWorkflow.swift

@@ -50,7 +50,7 @@ extension WelcomeWorkflow {
         case nameChanged(name: String)
         case didLogIn
 
-        func apply(toState state: inout WelcomeWorkflow.State) -> WelcomeWorkflow.Output? {
+        func apply(toState state: inout WelcomeWorkflow.State, context: ApplyContext<WorkflowType>) -> WelcomeWorkflow.Output? {
             switch self {
             case .nameChanged(name: let name):
                 // Update our state with the updated name.

Samples/Tutorial/Frameworks/Tutorial3Complete/Sources/RootWorkflow.swift

@@ -54,7 +54,7 @@ extension RootWorkflow {
         case logIn(name: String)
         case logOut
 
-        func apply(toState state: inout RootWorkflow.State) -> RootWorkflow.Output? {
+        func apply(toState state: inout RootWorkflow.State, context: ApplyContext<WorkflowType>) -> RootWorkflow.Output? {
             switch self {
             case .logIn(name: let name):
                 state = .todo(name: name)

Samples/Tutorial/Frameworks/Tutorial3Complete/Sources/Todo/Edit/TodoEditWorkflow.swift

@@ -66,7 +66,7 @@ extension TodoEditWorkflow {
         case discardChanges
         case saveChanges
 
-        func apply(toState state: inout TodoEditWorkflow.State) -> TodoEditWorkflow.Output? {
+        func apply(toState state: inout TodoEditWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoEditWorkflow.Output? {
             switch self {
             case .titleChanged(let title):
                 state.todo.title = title

Samples/Tutorial/Frameworks/Tutorial3Complete/Sources/Todo/List/TodoListWorkflow.swift

@@ -73,7 +73,7 @@ extension TodoListWorkflow {
         case discardChanges
         case saveChanges(todo: TodoModel, index: Int)
 
-        func apply(toState state: inout TodoListWorkflow.State) -> TodoListWorkflow.Output? {
+        func apply(toState state: inout TodoListWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoListWorkflow.Output? {
             switch self {
             case .onBack:
                 // When a `.onBack` action is received, emit a `.back` output

Samples/Tutorial/Frameworks/Tutorial3Complete/Sources/Welcome/WelcomeWorkflow.swift

@@ -50,7 +50,7 @@ extension WelcomeWorkflow {
         case nameChanged(name: String)
         case didLogIn
 
-        func apply(toState state: inout WelcomeWorkflow.State) -> WelcomeWorkflow.Output? {
+        func apply(toState state: inout WelcomeWorkflow.State, context: ApplyContext<WorkflowType>) -> WelcomeWorkflow.Output? {
             switch self {
             case .nameChanged(name: let name):
                 // Update our state with the updated name.

Samples/Tutorial/Frameworks/Tutorial4Complete/Sources/RootWorkflow.swift

@@ -54,7 +54,7 @@ extension RootWorkflow {
         case logIn(name: String)
         case logOut
 
-        func apply(toState state: inout RootWorkflow.State) -> RootWorkflow.Output? {
+        func apply(toState state: inout RootWorkflow.State, context: ApplyContext<WorkflowType>) -> RootWorkflow.Output? {
             switch self {
             case .logIn(name: let name):
                 // When the `login` action is received, change the state to `todo`.

Samples/Tutorial/Frameworks/Tutorial4Complete/Sources/Todo/Edit/TodoEditWorkflow.swift

@@ -66,7 +66,7 @@ extension TodoEditWorkflow {
         case discardChanges
         case saveChanges
 
-        func apply(toState state: inout TodoEditWorkflow.State) -> TodoEditWorkflow.Output? {
+        func apply(toState state: inout TodoEditWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoEditWorkflow.Output? {
             switch self {
             case .titleChanged(let title):
                 state.todo.title = title

Samples/Tutorial/Frameworks/Tutorial4Complete/Sources/Todo/List/TodoListWorkflow.swift

@@ -58,7 +58,7 @@ extension TodoListWorkflow {
         case selectTodo(index: Int)
         case new
 
-        func apply(toState state: inout TodoListWorkflow.State) -> TodoListWorkflow.Output? {
+        func apply(toState state: inout TodoListWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoListWorkflow.Output? {
             switch self {
             case .onBack:
                 // When a `.onBack` action is received, emit a `.back` output

Samples/Tutorial/Frameworks/Tutorial4Complete/Sources/Todo/TodoWorkflow.swift

@@ -71,7 +71,7 @@ extension TodoWorkflow {
         case editTodo(index: Int)
         case newTodo
 
-        func apply(toState state: inout TodoWorkflow.State) -> TodoWorkflow.Output? {
+        func apply(toState state: inout TodoWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoWorkflow.Output? {
             switch self {
             case .back:
                 return .back
@@ -97,7 +97,7 @@ extension TodoWorkflow {
         case discardChanges
         case saveChanges(todo: TodoModel, index: Int)
 
-        func apply(toState state: inout TodoWorkflow.State) -> TodoWorkflow.Output? {
+        func apply(toState state: inout TodoWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoWorkflow.Output? {
             guard case .edit = state.step else {
                 fatalError("Received edit action when state was not `.edit`.")
             }

Samples/Tutorial/Frameworks/Tutorial4Complete/Sources/Welcome/WelcomeWorkflow.swift

@@ -50,7 +50,7 @@ extension WelcomeWorkflow {
         case nameChanged(name: String)
         case didLogIn
 
-        func apply(toState state: inout WelcomeWorkflow.State) -> WelcomeWorkflow.Output? {
+        func apply(toState state: inout WelcomeWorkflow.State, context: ApplyContext<WorkflowType>) -> WelcomeWorkflow.Output? {
             switch self {
             case .nameChanged(name: let name):
                 // Update our state with the updated name.

Samples/Tutorial/Frameworks/Tutorial5Complete/Sources/RootWorkflow.swift

@@ -54,7 +54,7 @@ extension RootWorkflow {
         case logIn(name: String)
         case logOut
 
-        func apply(toState state: inout RootWorkflow.State) -> RootWorkflow.Output? {
+        func apply(toState state: inout RootWorkflow.State, context: ApplyContext<WorkflowType>) -> RootWorkflow.Output? {
             switch self {
             case .logIn(name: let name):
                 state = .todo(name: name)

Samples/Tutorial/Frameworks/Tutorial5Complete/Sources/Todo/Edit/TodoEditWorkflow.swift

@@ -66,7 +66,7 @@ extension TodoEditWorkflow {
         case discardChanges
         case saveChanges
 
-        func apply(toState state: inout TodoEditWorkflow.State) -> TodoEditWorkflow.Output? {
+        func apply(toState state: inout TodoEditWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoEditWorkflow.Output? {
             switch self {
             case .titleChanged(let title):
                 state.todo.title = title

Samples/Tutorial/Frameworks/Tutorial5Complete/Sources/Todo/List/TodoListWorkflow.swift

@@ -58,7 +58,7 @@ extension TodoListWorkflow {
         case selectTodo(index: Int)
         case new
 
-        func apply(toState state: inout TodoListWorkflow.State) -> TodoListWorkflow.Output? {
+        func apply(toState state: inout TodoListWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoListWorkflow.Output? {
             switch self {
             case .onBack:
                 // When a `.onBack` action is received, emit a `.back` output

Samples/Tutorial/Frameworks/Tutorial5Complete/Sources/Todo/TodoWorkflow.swift

@@ -71,7 +71,7 @@ extension TodoWorkflow {
         case editTodo(index: Int)
         case newTodo
 
-        func apply(toState state: inout TodoWorkflow.State) -> TodoWorkflow.Output? {
+        func apply(toState state: inout TodoWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoWorkflow.Output? {
             switch self {
             case .back:
                 return .back
@@ -97,7 +97,7 @@ extension TodoWorkflow {
         case discardChanges
         case saveChanges(todo: TodoModel, index: Int)
 
-        func apply(toState state: inout TodoWorkflow.State) -> TodoWorkflow.Output? {
+        func apply(toState state: inout TodoWorkflow.State, context: ApplyContext<WorkflowType>) -> TodoWorkflow.Output? {
             guard case .edit = state.step else {
                 fatalError("Received edit action when state was not `.edit`.")
             }

Samples/Tutorial/Frameworks/Tutorial5Complete/Sources/Welcome/WelcomeWorkflow.swift

@@ -50,7 +50,7 @@ extension WelcomeWorkflow {
         case nameChanged(name: String)
         case didLogIn
 
-        func apply(toState state: inout WelcomeWorkflow.State) -> WelcomeWorkflow.Output? {
+        func apply(toState state: inout WelcomeWorkflow.State, context: ApplyContext<WorkflowType>) -> WelcomeWorkflow.Output? {
             switch self {
             case .nameChanged(name: let name):
                 // Update our state with the updated name.

Samples/WorkflowCombineSampleApp/WorkflowCombineSampleApp/DemoWorkflow.swift

@@ -37,7 +37,7 @@ extension DemoWorkflow {
 
         let publishedDate: Date
 
-        func apply(toState state: inout DemoWorkflow.State) -> DemoWorkflow.Output? {
+        func apply(toState state: inout DemoWorkflow.State, context: ApplyContext<WorkflowType>) -> DemoWorkflow.Output? {
             state.date = publishedDate
             return nil
         }

Tooling/Templates/Workflow (Verbose).xctemplate/Default/___FILEBASENAME___Workflow.swift

@@ -25,7 +25,7 @@ extension ___VARIABLE_productName___Workflow {
     enum Action: WorkflowAction {
         typealias WorkflowType = ___VARIABLE_productName___Workflow
 
-        func apply(toState state: inout ___VARIABLE_productName___Workflow.State) -> ___VARIABLE_productName___Workflow.Output? {
+        func applytoState state: inout ___VARIABLE_productName___Workflow.State, context: ApplyContext<WorkflowType> -> ___VARIABLE_productName___Workflow.Output? {
             switch self {
                 // Update state and produce an optional output based on which action was received.
             }

Tooling/Templates/Workflow (Verbose).xctemplate/generateWorkerReactiveSwift/___FILEBASENAME___Workflow.swift

@@ -25,7 +25,7 @@ extension ___VARIABLE_productName___Workflow {
     enum Action: WorkflowAction {
         typealias WorkflowType = ___VARIABLE_productName___Workflow
 
-        func apply(toState state: inout ___VARIABLE_productName___Workflow.State) -> ___VARIABLE_productName___Workflow.Output? {
+        func apply(toState state: inout ___VARIABLE_productName___Workflow.State, context: ApplyContext<WorkflowType>) -> ___VARIABLE_productName___Workflow.Output? {
             switch self {
                 // Update state and produce an optional output based on which action was received.
             }

Tooling/Templates/Workflow (Verbose).xctemplate/generateWorkerRxSwift/___FILEBASENAME___Workflow.swift

@@ -25,7 +25,7 @@ extension ___VARIABLE_productName___Workflow {
     enum Action: WorkflowAction {
         typealias WorkflowType = ___VARIABLE_productName___Workflow
 
-        func apply(toState state: inout ___VARIABLE_productName___Workflow.State) -> ___VARIABLE_productName___Workflow.Output? {
+        func apply(toState state: inout ___VARIABLE_productName___Workflow.State, context: ApplyContext<WorkflowType>) -> ___VARIABLE_productName___Workflow.Output? {
             switch self {
                 // Update state and produce an optional output based on which action was received.
             }

Workflow/Sources/AnyWorkflowConvertible.swift

@@ -115,10 +115,12 @@ extension AnyWorkflowConvertible {
     /// Process an `Output`
     ///
     /// - Parameter apply: On `Output`, mutate `State` as necessary and return new `Output` (or `nil`).
-    public func onOutput<Parent>(_ apply: @escaping ((inout Parent.State, Output) -> Parent.Output?)) -> AnyWorkflow<Rendering, AnyWorkflowAction<Parent>> {
+    public func onOutput<Parent>(
+        _ apply: @escaping (inout Parent.State, Output) -> Parent.Output?
+    ) -> AnyWorkflow<Rendering, AnyWorkflowAction<Parent>> {
         asAnyWorkflow()
             .mapOutput { output in
-                AnyWorkflowAction { state -> Parent.Output? in
+                AnyWorkflowAction { state, _ -> Parent.Output? in
                     apply(&state, output)
                 }
             }