Effect

Undocumented

Initializes an effect that wraps a publisher. Each emission of the wrapped publisher will be emitted by the effect.

This initializer is useful for turning any publisher into an effect. For example:

Effect(
  NotificationCenter.default
    .publisher(for: UIApplication.userDidTakeScreenshotNotification)
)

Alternatively, you can use the .eraseToEffect() method that is defined on the Publisher protocol:

NotificationCenter.default
  .publisher(for: UIApplication.userDidTakeScreenshotNotification)
  .eraseToEffect()

Initializes an effect that immediately emits the value passed in.

Initializes an effect that immediately fails with the error passed in.

An effect that does nothing and completes immediately. Useful for situations where you must return an effect, but you don’t need to do anything.

Creates an effect that can supply a single value asynchronously in the future.

This can be helpful for converting APIs that are callback-based into ones that deal with Effects.

For example, to create an effect that delivers an integer after waiting a second:

Effect<Int, Never>.future { callback in
  DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
    callback(.success(42))
  }
}

Note that you can only deliver a single value to the callback. If you send more they will be discarded:

Effect<Int, Never>.future { callback in
  DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
    callback(.success(42))
    callback(.success(1729)) // Will not be emitted by the effect
  }
}

If you need to deliver more than one value to the effect, you should use the Effect initializer that accepts a Subscriber value.

Initializes an effect that lazily executes some work in the real world and synchronously sends that data back into the store.

For example, to load a user from some JSON on the disk, one can wrap that work in an effect:

Effect<User, Error>.result {
  let fileUrl = URL(
    fileURLWithPath: NSSearchPathForDirectoriesInDomains(
      .documentDirectory, .userDomainMask, true
    )[0]
  )
  .appendingPathComponent("user.json")

  let result = Result<User, Error> {
    let data = try Data(contentsOf: fileUrl)
    return try JSONDecoder().decode(User.self, from: $0)
  }

  return result
}

Initializes an effect from a callback that can send as many values as it wants, and can send a completion.

This initializer is useful for bridging callback APIs, delegate APIs, and manager APIs to the Effect type. One can wrap those APIs in an Effect so that its events are sent through the effect, which allows the reducer to handle them.

For example, one can create an effect to ask for access to MPMediaLibrary. It can start by sending the current status immediately, and then if the current status is notDetermined it can request authorization, and once a status is received it can send that back to the effect:

Effect.run { subscriber in
  subscriber.send(MPMediaLibrary.authorizationStatus())

  guard MPMediaLibrary.authorizationStatus() == .notDetermined else {
    subscriber.send(completion: .finished)
    return AnyCancellable {}
  }

  MPMediaLibrary.requestAuthorization { status in
    subscriber.send(status)
    subscriber.send(completion: .finished)
  }
  return AnyCancellable {
    // Typically clean up resources that were created here, but this effect doesn't
    // have any.
  }
}

Concatenates a variadic list of effects together into a single effect, which runs the effects one after the other.

Feedback filed: https://gist.github.com/mbrandonw/611c8352e1bd1c22461bd505e320ab58

Concatenates a collection of effects together into a single effect, which runs the effects one after the other.

Feedback filed: https://gist.github.com/mbrandonw/611c8352e1bd1c22461bd505e320ab58

Merges a variadic list of effects together into a single effect, which runs the effects at the same time.

Merges a sequence of effects together into a single effect, which runs the effects at the same time.

Creates an effect that executes some work in the real world that doesn’t need to feed data back into the store.

Transforms all elements from the upstream effect with a provided closure.

Turns an effect into one that is capable of being canceled.

To turn an effect into a cancellable one you must provide an identifier, which is used in Effect.cancel(id:) to identify which in-flight effect should be canceled. Any hashable value can be used for the identifier, such as a string, but you can add a bit of protection against typos by defining a new type that conforms to Hashable, such as an empty struct:

struct LoadUserId: Hashable {}

case .reloadButtonTapped:
  // Start a new effect to load the user
  return environment.loadUser
    .map(Action.userResponse)
    .cancellable(id: LoadUserId(), cancelInFlight: true)

case .cancelButtonTapped:
  // Cancel any in-flight requests to load the user
  return .cancel(id: LoadUserId())

An effect that will cancel any currently in-flight effect with the given identifier.

Turns an effect into one that can be debounced.

To turn an effect into a debounce-able one you must provide an identifier, which is used to determine which in-flight effect should be canceled in order to start a new effect. Any hashable value can be used for the identifier, such as a string, but you can add a bit of protection against typos by defining a new type that conforms to Hashable, such as an empty struct:

case let .textChanged(text):
  struct SearchId: Hashable {}

  return environment.search(text)
    .map(Action.searchResponse)
    .debounce(id: SearchId(), for: 0.5, scheduler: environment.mainQueue)

Undocumented

Undocumented

Initializes an effect that lazily executes some work in the real world and synchronously sends that data back into the store.

For example, to load a user from some JSON on the disk, one can wrap that work in an effect:

Effect<User, Error>.catching {
  let fileUrl = URL(
    fileURLWithPath: NSSearchPathForDirectoriesInDomains(
      .documentDirectory, .userDomainMask, true
    )[0]
  )
  .appendingPathComponent("user.json")

  let data = try Data(contentsOf: fileUrl)
  return try JSONDecoder().decode(User.self, from: $0)
}

Upcasts an Effect<Never, Failure> to an Effect<T, Failure> for any type T. This is possible to do because an Effect<Never, Failure> can never produce any values to feed back into the store (hence the name “fire and forget”), and therefore we can act like it’s an effect that produces values of any type (since it never produces values).

This is useful for times you have an Effect<Never, Failure> but need to massage it into another type in order to return it from a reducer:

case .buttonTapped:
  return analyticsClient.track("Button Tapped")
    .fireAndForget()

Returns an effect that repeatedly emits the current time of the given scheduler on the given interval.

While it is possible to use Foundation’s Timer.publish(every:tolerance:on:in:options:) API to create a timer in the Composable Architecture, it is not advisable. This API only allows creating a timer on a run loop, which means when writing tests you will need to explicitly wait for time to pass in order to see how the effect evolves in your feature.

In the Composable Architecture we test time-based effects like this by using the TestScheduler, which allows us to explicitly and immediately advance time forward so that we can see how effects emit. However, because Timer.publish takes a concrete RunLoop as its scheduler, we can’t substitute in a TestScheduler during tests`.

That is why we provide the Effect.timer effect. It allows you to create a timer that works with any scheduler, not just a run loop, which means you can use a DispatchQueue or RunLoop when running your live app, but use a TestScheduler in tests.

To start and stop a timer in your feature you can create the timer effect from an action and then use the .cancel(id:) effect to stop the timer:

struct AppState {
  var count = 0
}

enum AppAction {
  case startButtonTapped, stopButtonTapped, timerTicked
}

struct AppEnvironment {
  var mainQueue: AnySchedulerOf<DispatchQueue>
}

let appReducer = Reducer<AppState, AppAction, AppEnvironment> { state, action, env in
  struct TimerId: Hashable {}

  switch action {
  case .startButtonTapped:
    return Effect.timer(id: TimerId(), every: 1, on: env.mainQueue)
      .map { _ in .timerTicked }

  case .stopButtonTapped:
    return .cancel(id: TimerId())

  case let .timerTicked:
    state.count += 1
    return .none
}

Then to test the timer in this feature you can use a test scheduler to advance time:

func testTimer() { let scheduler = DispatchQueue.testScheduler

let store = TestStore(
  initialState: .init(),
  reducer: appReducer,
  envirnoment: .init(
    mainQueue: scheduler.eraseToAnyScheduler()
  )
)

store.assert(
  .send(.startButtonTapped),

  .do { scheduler.advance(by: .seconds(1)) },
  .receive(.timerTicked) { $0.count = 1 },

  .do { scheduler.advance(by: .seconds(5)) },
  .receive(.timerTicked) { $0.count = 2 },
  .receive(.timerTicked) { $0.count = 3 },
  .receive(.timerTicked) { $0.count = 4 },
  .receive(.timerTicked) { $0.count = 5 },
  .receive(.timerTicked) { $0.count = 6 },

  .send(.stopButtonTapped)
)

}