add Document

Author: Ryu0118

Sources/SimplexArchitecture/Internal/ActionTransition.swift

@@ -1,17 +1,29 @@
 import Foundation
 
+/// ``ActionTransition`` represents a transition between states in a reducer. It captures the previous and next states, the associated side effect,effect context, and the action triggering the transition.
 struct ActionTransition<Reducer: ReducerProtocol> {
+    /// Represents a state. It includes the target state and the reducer state.
     struct State {
         let state: Reducer.Target.States?
         let reducerState: Reducer.ReducerState?
     }
-
+    /// The previous state.
     let previous: Self.State
+    /// The next state.
     let next: Self.State
+    /// The associated side effect.
     let effect: SideEffect<Reducer>
+    /// The unique effect context that represents parent effect.
     let effectContext: UUID
+    /// The Action that cause a change of state
     let action: CombineAction<Reducer>
 
+    /// - Parameters:
+    ///   - previous: The previous state.
+    ///   - next: The next state.
+    ///   - effect: The unique effect context that represents parent effect.
+    ///   - effectContext: The unique effect context that represents parent effect.
+    ///   - action: The action responsible for the transition.
     init(
         previous: Self.State,
         next: Self.State,
@@ -26,15 +38,30 @@ struct ActionTransition<Reducer: ReducerProtocol> {
         self.action = action
     }
 
+    /// Converts the `ActionTransition` to a `StateContainer` representing the next state.
+    ///
+    /// - Parameter target: The target reducer.
+    /// - Returns: A `StateContainer` representing the next state.
     func asNextStateContainer(from target: Reducer.Target) -> StateContainer<Reducer.Target> {
         asStateContainer(from: target, state: next)
     }
 
+    /// Converts the `ActionTransition` to a `StateContainer` representing the previous state.
+    ///
+    /// - Parameter target: The target reducer.
+    /// - Returns: A `StateContainer` representing the previous state.
     func asPreviousStateContainer(from target: Reducer.Target) -> StateContainer<Reducer.Target> {
         asStateContainer(from: target, state: previous)
     }
 
-    private func asStateContainer(from target: Reducer.Target, state: Self.State) -> StateContainer<Reducer.Target> {
-        .init(target, states: state.state, reducerState: state.reducerState)
+    private func asStateContainer(
+        from target: Reducer.Target,
+        state: Self.State
+    ) -> StateContainer<Reducer.Target> {
+        .init(
+            target,
+            states: state.state,
+            reducerState: state.reducerState
+        )
     }
 }

Sources/SimplexArchitecture/Internal/EffectContext.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// Enum to determine parent's Effect
 enum EffectContext {
     @TaskLocal static var id: UUID?
 }

Sources/SimplexArchitecture/Internal/Task+withEffectContext.swift

@@ -1,6 +1,7 @@
 import Foundation
 
 extension Task where Failure == any Error {
+    // Granted when there is no EffectContext in the Task.
     @discardableResult
     static func withEffectContext(
         priority: TaskPriority? = nil,
@@ -19,6 +20,7 @@ extension Task where Failure == any Error {
 }
 
 extension Task where Failure == Never {
+    // Granted when there is no EffectContext in the Task.
     @discardableResult
     static func withEffectContext(
         priority: TaskPriority? = nil,

Sources/SimplexArchitecture/Send.swift

@@ -1,3 +1,4 @@
+/// A type that can send actions back into the system when used from run(priority:operation:catch:fileID:line:).
 public struct Send<Reducer: ReducerProtocol>: Sendable {
     @usableFromInline
     let sendAction: @Sendable (Reducer.Action) -> SendTask
@@ -25,12 +26,14 @@ public struct Send<Reducer: ReducerProtocol>: Sendable {
         sendReducerAction(action)
     }
 
+    /// Sends an action back into the system from an effect.
     @MainActor
     @inlinable
     public func callAsFunction(_ action: Reducer.Action) async {
         await sendAction(action).wait()
     }
 
+    /// Sends an reducer action back into the system from an effect.
     @_disfavoredOverload
     @MainActor
     @inlinable

Sources/SimplexArchitecture/StateContainer.swift

@@ -1,8 +1,8 @@
 import Foundation
 import XCTestDynamicOverlay
 
-// StateContainer is not thread-safe. Therefore, StateContainer must use NSLock or NSRecursiveLock for exclusions when changing values.
-// In Send.swift, NSRecursiveLock is used for exclusions when executing the `reduce(into:action)`.
+/// StateContainer is not thread-safe. Therefore, StateContainer must use NSLock or NSRecursiveLock for exclusions when changing values.
+/// In Store, NSRecursiveLock is used for exclusions when executing the `reduce(into:action)`.
 @dynamicMemberLookup
 public final class StateContainer<Target: ActionSendable> {
     public var reducerState: Target.Reducer.ReducerState {

Sources/SimplexArchitecture/Store/Store+pullback.swift

@@ -3,7 +3,7 @@ import Foundation
 
 // MARK: - Pullback
 
-public extension Store {
+extension Store {
     @inlinable
     func pullback<Parent: ActionSendable>(
         to casePath: consuming CasePath<Parent.Reducer.Action, Reducer.Action>,

Sources/SimplexArchitecture/TestStore.swift

@@ -3,10 +3,19 @@ import CustomDump
 import Dependencies
 import Foundation
 
+/// TestStore is a utility class for testing stores that use Reducer protocols.
+/// It provides methods for sending actions and verifying state changes.
 public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equatable, Reducer.ReducerAction: Equatable {
+
+    // MARK: - Properties
+
+    /// The running state container.
     var runningContainer: StateContainer<Reducer.Target>?
+
+    /// An array of tested actions.
     var testedActions: [ActionTransition<Reducer>] = []
 
+    /// An array of untested actions.
     var untestedActions: [ActionTransition<Reducer>] {
         target.store.sentFromEffectActions.filter { actionTransition in
             !testedActions.contains {
@@ -16,8 +25,15 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
     }
 
     let target: Reducer.Target
+
+    /// The states of the target.
     let states: Reducer.Target.States
 
+    /// Initializes a new test store.
+    ///
+    /// - Parameters:
+    ///   - target: The target Reducer.
+    ///   - states: The states of the target Reducer.
     init(
         target: Reducer.Target,
         states: Reducer.Target.States
@@ -47,6 +63,12 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
         }
     }
 
+    /// Asserts an action was received from an effect and asserts how the state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action expected from an effect.
+    ///   - timeout: The amount of time to wait for the expected action.
+    ///   - expected: A closure that asserts state changed by sending the action to the store. The mutable state sent to this closure must be modified to match the state of the store after processing the given action. Do not provide a closure if no change is expected.
     public func receive(
         _ action: Reducer.ReducerAction,
         timeout: TimeInterval = 5,
@@ -63,6 +85,12 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
         )
     }
 
+    /// Asserts an action was received from an effect and asserts how the state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action expected from an effect.
+    ///   - timeout: The amount of time to wait for the expected action.
+    ///   - expected: A closure that asserts state changed by sending the action to the store. The mutable state sent to this closure must be modified to match the state of the store after processing the given action. Do not provide a closure if no change is expected.
     public func receive(
         _ action: Reducer.Action,
         timeout: TimeInterval = 5,
@@ -107,9 +135,7 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
                 break
             }
 
-            if let firstIndex = untestedActions.firstIndex(where: { $0.action == action }),
-               let stateTransition = untestedActions[safe: firstIndex]
-            {
+            if let stateTransition = untestedActions.first(where: { $0.action == action }) {
                 let expectedContainer = stateTransition.asNextStateContainer(from: target)
                 let actualContainer = stateTransition.asPreviousStateContainer(from: target)
 
@@ -126,7 +152,8 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
         }
     }
 
-    func receiveWithoutStateCheck(
+    /// Asserts an action was received from an effect. Does not assert state changes.
+    public func receiveWithoutStateCheck(
         _ action: Reducer.Action,
         timeout: TimeInterval = 5,
         file: StaticString = #file,
@@ -153,9 +180,7 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
                 break
             }
 
-            if let firstIndex = untestedActions.firstIndex(where: { $0.action == .action(action) }),
-               let stateTransition = untestedActions[safe: firstIndex]
-            {
+            if let stateTransition = untestedActions.first(where: { $0.action == .action(action) }) {
                 testedActions.append(stateTransition)
                 break
             }
@@ -164,86 +189,134 @@ public final class TestStore<Reducer: ReducerProtocol> where Reducer.Action: Equ
         }
     }
 
+    /// Sends an action to the store and asserts when state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action.
+    ///   - assert: A closure that asserts state changed by sending the action to
+    ///     the store. The mutable state sent to this closure must be modified to match the state of
+    ///     the store after processing the given action. Do not provide a closure if no change is
+    ///     expected.
+    /// - Returns: A ``SendTask`` that represents the lifecycle of the effect executed when
+    ///   sending the action.
+    @discardableResult
     @MainActor
     public func send(
         _ action: Reducer.Action,
         assert expected: ((StateContainer<Reducer.Target>) -> Void)? = nil
-    ) async {
+    ) async -> SendTask {
         let expectedContainer = target.store.setContainerIfNeeded(for: target, states: states)
         runningContainer = expectedContainer
         let actualContainer = expectedContainer.copy()
 
-        target.store.sendIfNeeded(action)
+        let sendTask = target.store.sendIfNeeded(action)
 
         expected?(actualContainer)
 
         assertStatesNoDifference(expected: expectedContainer, actual: actualContainer)
         assertReducerNoDifference(expected: expectedContainer, actual: actualContainer)
 
         await Task.megaYield()
+        return sendTask
     }
 
+    /// Sends an action to the store and asserts when state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action.
+    ///   - assert: A closure that asserts state changed by sending the action to
+    ///     the store. The mutable state sent to this closure must be modified to match the state of
+    ///     the store after processing the given action. Do not provide a closure if no change is
+    ///     expected.
+    /// - Returns: A ``SendTask`` that represents the lifecycle of the effect executed when
+    ///   sending the action.
+    @discardableResult
     @MainActor
     public func send(
         _ action: Reducer.Action,
         assert expected: ((StateContainer<Reducer.Target>) -> Void)? = nil
-    ) async where Reducer.Target.States: Equatable {
+    ) async -> SendTask where Reducer.Target.States: Equatable {
         let expectedContainer = target.store.setContainerIfNeeded(for: target, states: states)
         runningContainer = expectedContainer
         let actualContainer = expectedContainer.copy()
 
-        target.store.sendIfNeeded(action)
+        let sendTask = target.store.sendIfNeeded(action)
 
         expected?(actualContainer)
 
         assertStatesNoDifference(expected: expectedContainer, actual: actualContainer)
         assertReducerNoDifference(expected: expectedContainer, actual: actualContainer)
 
         await Task.megaYield()
+
+        return sendTask
     }
 
+    /// Sends an action to the store and asserts when state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action.
+    ///   - assert: A closure that asserts state changed by sending the action to
+    ///     the store. The mutable state sent to this closure must be modified to match the state of
+    ///     the store after processing the given action. Do not provide a closure if no change is
+    ///     expected.
+    /// - Returns: A ``SendTask`` that represents the lifecycle of the effect executed when
+    ///   sending the action.
+    @discardableResult
     @MainActor
     public func send(
         _ action: Reducer.Action,
         assert expected: ((StateContainer<Reducer.Target>) -> Void)? = nil
-    ) async where Reducer.ReducerState: Equatable {
+    ) async -> SendTask where Reducer.ReducerState: Equatable {
         let expectedContainer = target.store.setContainerIfNeeded(for: target, states: states)
         runningContainer = expectedContainer
         let actualContainer = expectedContainer.copy()
 
-        target.store.sendIfNeeded(action)
+        let sendTask = target.store.sendIfNeeded(action)
 
         expected?(actualContainer)
 
         assertStatesNoDifference(expected: expectedContainer, actual: actualContainer)
         assertReducerNoDifference(expected: expectedContainer, actual: actualContainer)
 
         await Task.megaYield()
+        return sendTask
     }
 
+    /// Sends an action to the store and asserts when state changes.
+    ///
+    /// - Parameters:
+    ///   - action: An action.
+    ///   - assert: A closure that asserts state changed by sending the action to
+    ///     the store. The mutable state sent to this closure must be modified to match the state of
+    ///     the store after processing the given action. Do not provide a closure if no change is
+    ///     expected.
+    /// - Returns: A ``SendTask`` that represents the lifecycle of the effect executed when
+    ///   sending the action.
+    @discardableResult
     @MainActor
     public func send(
         _ action: Reducer.Action,
         assert expected: ((StateContainer<Reducer.Target>) -> Void)? = nil
-    ) async where Reducer.ReducerState: Equatable, Reducer.Target.States: Equatable {
+    ) async -> SendTask where Reducer.ReducerState: Equatable, Reducer.Target.States: Equatable {
         let expectedContainer = target.store.setContainerIfNeeded(for: target, states: states)
         runningContainer = expectedContainer
         let actualContainer = expectedContainer.copy()
 
-        target.store.sendIfNeeded(action)
+        let sendTask = target.store.sendIfNeeded(action)
 
         expected?(actualContainer)
 
         assertStatesNoDifference(expected: actualContainer, actual: actualContainer)
         assertReducerNoDifference(expected: actualContainer, actual: actualContainer)
 
         await Task.megaYield()
+
+        return sendTask
     }
 }
 
-// MARK: - +Assert
-
-private extension TestStore {
+extension TestStore {
     private func assertStatesNoDifference(
         expected expectedContainer: StateContainer<Reducer.Target>,
         actual actualContainer: StateContainer<Reducer.Target>
@@ -294,6 +367,10 @@ private extension TestStore {
 }
 
 public extension ActionSendable where Reducer.Action: Equatable, Reducer.ReducerAction: Equatable {
+    /// Creates and returns a new test store.
+    ///
+    /// - Parameter states: The initial states for testing.
+    /// - Returns: A new TestStore instance.
     func testStore(states: States) -> TestStore<Reducer> {
         TestStore(target: self, states: states)
     }