@@ -3,35 +3,51 @@ import Foundation
33import SwiftUI
44import XCTestDynamicOverlay
55
6- /// A type that encapsulates a unit of work that can be run in the outside world, and can feed
7- /// actions back to the ``Store``.
8- ///
9- /// Effects are the perfect place to do side effects, such as network requests, saving/loading
10- /// from disk, creating timers, interacting with dependencies, and more. They are returned from
11- /// reducers so that the ``Store`` can perform the effects after the reducer is done running.
12- ///
13- /// There are 2 distinct ways to create an `Effect`: one using Swift's native concurrency tools, and
14- /// the other using Apple's Combine framework:
15- ///
16- /// * If using Swift's native structured concurrency tools then there are 3 main ways to create an
17- /// effect, depending on if you want to emit one single action back into the system, or any number
18- /// of actions, or just execute some work without emitting any actions:
19- /// * ``EffectPublisher/task(priority:operation:catch:file:fileID:line:)``
20- /// * ``EffectPublisher/run(priority:operation:catch:file:fileID:line:)``
21- /// * ``EffectPublisher/fireAndForget(priority:_:)``
22- /// * If using Combine in your application, in particular for the dependencies of your feature
23- /// then you can create effects by making use of any of Combine's operators, and then erasing the
24- /// publisher type to ``EffectPublisher`` with either `eraseToEffect` or `catchToEffect`. Note that
25- /// the Combine interface to ``EffectPublisher`` is considered soft deprecated, and you should
26- /// eventually port to Swift's native concurrency tools.
27- ///
28- /// > Important: ``Store`` is not thread safe, and so all effects must receive values on the same
29- /// thread. This is typically the main thread, **and** if the store is being used to drive UI then
30- /// it must receive values on the main thread.
31- /// >
32- /// > This is only an issue if using the Combine interface of ``EffectPublisher`` as mentioned
33- /// above. If you are using Swift's concurrency tools and the `.task`, `.run` and `.fireAndForget`
34- /// functions on ``EffectTask``, then threading is automatically handled for you.
6+ /// This type is deprecated in favor of ``EffectTask``. See its documentation for more information.
7+ @available (
8+ iOS,
9+ deprecated: 9999.0 ,
10+ message: """
11+ 'EffectPublisher' has been deprecated in favor of 'EffectTask'.
12+
13+ You are encouraged to use `EffectTask<Action>` to model the ouput of your reducers, and to use Swift concurrency to model asynchrony in dependencies.
14+
15+ See the migration roadmap for more information: https://github.com/pointfreeco/swift-composable-architecture/discussions/1477
16+ """
17+ )
18+ @available (
19+ macOS,
20+ deprecated: 9999.0 ,
21+ message: """
22+ 'EffectPublisher' has been deprecated in favor of 'EffectTask'.
23+
24+ You are encouraged to use `EffectTask<Action>` to model the ouput of your reducers, and to use Swift concurrency to model asynchrony in dependencies.
25+
26+ See the migration roadmap for more information: https://github.com/pointfreeco/swift-composable-architecture/discussions/1477
27+ """
28+ )
29+ @available (
30+ tvOS,
31+ deprecated: 9999.0 ,
32+ message: """
33+ 'EffectPublisher' has been deprecated in favor of 'EffectTask'.
34+
35+ You are encouraged to use `EffectTask<Action>` to model the ouput of your reducers, and to use Swift concurrency to model asynchrony in dependencies.
36+
37+ See the migration roadmap for more information: https://github.com/pointfreeco/swift-composable-architecture/discussions/1477
38+ """
39+ )
40+ @available (
41+ watchOS,
42+ deprecated: 9999.0 ,
43+ message: """
44+ 'EffectPublisher' has been deprecated in favor of 'EffectTask'.
45+
46+ You are encouraged to use `EffectTask<Action>` to model the ouput of your reducers, and to use Swift concurrency to model asynchrony in dependencies.
47+
48+ See the migration roadmap for more information: https://github.com/pointfreeco/swift-composable-architecture/discussions/1477
49+ """
50+ )
3551public struct EffectPublisher < Action, Failure: Error > {
3652 @usableFromInline
3753 enum Operation {
@@ -60,20 +76,38 @@ extension EffectPublisher {
6076 }
6177}
6278
63- /// A convenience type alias for referring to an effect that can never fail, like the kind of
64- /// ``EffectPublisher`` returned by a reducer after processing an action .
79+ /// A type that encapsulates a unit of work that can be run in the outside world, and can feed
80+ /// actions back to the ``Store`` .
6581///
66- /// Instead of specifying `Never` as `Failure`:
82+ /// Effects are the perfect place to do side effects, such as network requests, saving/loading
83+ /// from disk, creating timers, interacting with dependencies, and more. They are returned from
84+ /// reducers so that the ``Store`` can perform the effects after the reducer is done running.
6785///
68- /// ```swift
69- /// func reduce(into state: inout State, action: Action) -> EffectPublisher<Action, Never> { … }
70- /// ```
86+ /// There are 2 distinct ways to create an `Effect`: one using Swift's native concurrency tools, and
87+ /// the other using Apple's Combine framework:
7188///
72- /// You can specify a single generic:
89+ /// * If using Swift's native structured concurrency tools then there are 3 main ways to create an
90+ /// effect, depending on if you want to emit one single action back into the system, or any number
91+ /// of actions, or just execute some work without emitting any actions:
92+ /// * ``EffectPublisher/task(priority:operation:catch:file:fileID:line:)``
93+ /// * ``EffectPublisher/run(priority:operation:catch:file:fileID:line:)``
94+ /// * ``EffectPublisher/fireAndForget(priority:_:)``
95+ /// * If using Combine in your application, in particular for the dependencies of your feature
96+ /// then you can create effects by making use of any of Combine's operators, and then erasing the
97+ /// publisher type to ``EffectPublisher`` with either `eraseToEffect` or `catchToEffect`. Note that
98+ /// the Combine interface to ``EffectPublisher`` is considered soft deprecated, and you should
99+ /// eventually port to Swift's native concurrency tools.
73100///
74- /// ```swift
75- /// func reduce(into state: inout State, action: Action) -> EffectTask<Action> { … }
76- /// ```
101+ /// > Important: The publisher interface to ``EffectTask`` is considered deperecated, and you should
102+ /// try converting any uses of that interface to Swift's native concurrency tools.
103+ /// >
104+ /// > Also, ``Store`` is not thread safe, and so all effects must receive values on the same
105+ /// thread. This is typically the main thread, **and** if the store is being used to drive UI then
106+ /// it must receive values on the main thread.
107+ /// >
108+ /// > This is only an issue if using the Combine interface of ``EffectPublisher`` as mentioned
109+ /// above. If you are using Swift's concurrency tools and the `.task`, `.run` and `.fireAndForget`
110+ /// functions on ``EffectTask``, then threading is automatically handled for you.
77111public typealias EffectTask < Action> = Effect < Action , Never >
78112
79113extension EffectPublisher where Failure == Never {
0 commit comments