Filtering with Fallback Recovery | Effect Http Client

HttpClient.filterOrElse() is the recovery-oriented counterpart to filterOrFail. Instead of producing an error when the predicate fails, it runs an alternative effect that can return a different response.

This is useful when you want to transparently handle certain response conditions, like falling back to a cached response, retrying with different parameters, or transforming an unexpected response into an expected one.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
} from "effect/unstable/http";
6
import { Effect } from "effect";
7

8
function fetchProductWithFallback(productId: number) {
9
  return Effect.gen(function* () {
10
    const client = (yield* HttpClient.HttpClient).pipe(
11
      // If the response isn't a 200, fall back to product 1
12
      HttpClient.filterOrElse(
13
        (response) => response.status === 200,
14
        (response) =>
15
          Effect.gen(function* () {
16
            console.log(
17
              `Got status ${response.status}, falling back to product 1`,
18
            );
19
            const fallbackClient = yield* HttpClient.HttpClient;
20
            return yield* fallbackClient.get(
21
              "https://dummyjson.com/products/1",
22
            );
23
          }),
24
      ),
25
    );
26

27
    const request = HttpClientRequest.get(
28
      `https://dummyjson.com/products/${productId}`,
29
    );
30

31
    const response = yield* client.execute(request);
32
    const product = yield* response.json;
33

34
    return product;
35
  }).pipe(Effect.provide(FetchHttpClient.layer));
36
}
37

38
// Test with a valid product
39
Effect.runPromise(fetchProductWithFallback(1)).then((product) => {
40
  console.log("Product:", product.title);
41
});
42

43
// Test with an invalid product — falls back to product 1
44
Effect.runPromise(fetchProductWithFallback(99999)).then((product) => {
45
  console.log("Product:", product.title);
46
});

Output:

1
Product: Essence Mascara Lash Princess
2
Got status 404, falling back to product 1
3
Product: Essence Mascara Lash Princess

The first argument is the same predicate as filterOrFail. The difference is the second argument: instead of an error constructor, it’s a function that returns an Effect<HttpClientResponse>. This effect can do anything: make another request, return a cached response, or even succeed with the original response after logging.

The key distinction between the two:

filterOrFail: Predicate fails → error in the error channel. The caller must handle it.
filterOrElse: Predicate fails → alternative effect runs. The caller doesn’t know the filter was triggered.

Use filterOrFail when a bad response is an error your application needs to know about. Use filterOrElse when you can transparently recover and the caller doesn’t need to care.

Stay in the loop