Structure Effect

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.

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
}

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.
  }
}

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())

This function is useful for executing work in an asynchronous context and capture the result in an Effect so that the reducer, a non-asynchronous context, can process it.

Effect.task {
  guard case let .some((data, _)) = try? await URLSession.shared
    .data(from: .init(string: "http://numbersapi.com/42")!)
  else {
    return "Could not load"
  }

  return String(decoding: data, as: UTF8.self)
}

Note that due to the lack of tools to control the execution of asynchronous work in Swift, it is not recommended to use this function in reducers directly. Doing so will introduce thread hops into your effects that will make testing difficult. You will be responsible for adding explicit expectations to wait for small amounts of time so that effects can deliver their output.

Instead, this function is most helpful for calling async/await functions from the live implementation of dependencies, such as URLSession.data, MKLocalSearch.start and more.

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)
    .debounce(id: SearchId(), for: 0.5, scheduler: environment.mainQueue)
    .map(Action.searchResponse)

case let .textChanged(text):
  return environment.search(text)
    .deferred(for: 0.5, scheduler: environment.mainQueue)
    .map(Action.searchResponse)

This effect can provide an additional layer of certainty that a tested code path does not execute a particular effect.

For example, let's say we have a very simple counter application, where a user can increment and decrement a number. The state and actions are simple enough:

struct CounterState: Equatable {
  var count = 0
}

enum CounterAction: Equatable {
  case decrementButtonTapped
  case incrementButtonTapped
}

Let's throw in a side effect. If the user attempts to decrement the counter below zero, the application should refuse and play an alert sound instead.

We can model playing a sound in the environment with an effect:

struct CounterEnvironment {
  let playAlertSound: () -> Effect<Never, Never>
}

Now that we've defined the domain, we can describe the logic in a reducer:

let counterReducer = Reducer<
  CounterState, CounterAction, CounterEnvironment
> { state, action, environment in
  switch action {
  case .decrementButtonTapped:
    if state > 0 {
      state.count -= 0
      return .none
    } else {
      return environment.playAlertSound()
        .fireAndForget()
    }

  case .incrementButtonTapped:
    state.count += 1
    return .non
  }
}

Let's say we want to write a test for the increment path. We can see in the reducer that it should never play an alert, so we can configure the environment with an effect that will fail if it ever executes:

func testIncrement() {
  let store = TestStore(
    initialState: CounterState(count: 0)
    reducer: counterReducer,
    environment: CounterEnvironment(
      playSound: .failing("playSound")
    )
  )

  store.send(.increment) {
    $0.count = 1
  }
}

By using a .failing effect in our environment we have strengthened the assertion and made the test easier to understand at the same time. We can see, without consulting the reducer itself, that this particular action should not access this effect.