CompletableFutureExample.java

• CompletableFutureExample.java

public void createExample() {
   // Get the MonadError instance
   MonadError<CompletableFutureKind.Witness, Throwable> futureMonad = Instances.monadError(completableFuture());

   // --- Lift a pure value into an already-completed future ---
   Kind<CompletableFutureKind.Witness, String> successKind = futureMonad.of("Success!");

   // --- Create a failed future from an exception ---
   RuntimeException error = new RuntimeException("Something went wrong");
   Kind<CompletableFutureKind.Witness, String> failureKind = futureMonad.raiseError(error);

   // --- Wrap an existing CompletableFuture ---
   CompletableFuture<Integer> existingFuture = CompletableFuture.supplyAsync(() -> {
      try {
         TimeUnit.MILLISECONDS.sleep(20);
      } catch (InterruptedException e) { /* ignore */ }
      return 123;
   });
   Kind<CompletableFutureKind.Witness, Integer> wrappedExisting = FUTURE.widen(existingFuture);

   CompletableFuture<Integer> failedExisting = new CompletableFuture<>();
   failedExisting.completeExceptionally(new IllegalArgumentException("Bad input"));
   Kind<CompletableFutureKind.Witness, Integer> wrappedFailed = FUTURE.widen(failedExisting);

   // Unwrap back to CompletableFuture at system boundaries
   CompletableFuture<String> unwrappedSuccess = FUTURE.narrow(successKind);
   CompletableFuture<String> unwrappedFailure = FUTURE.narrow(failureKind);
}

• CompletableFutureExample.java

These examples show how the type class instance composes async operations — the same map/flatMap vocabulary you use with Either, IO, or any other monad.

public void monadExample() {
   MonadError<CompletableFutureKind.Witness, Throwable> futureMonad = Instances.monadError(completableFuture());

   // --- map: transform the result when it completes ---
   Kind<CompletableFutureKind.Witness, Integer> initialValueKind = futureMonad.of(10);
   Kind<CompletableFutureKind.Witness, String> mappedKind = futureMonad.map(
           value -> "Result: " + value,
           initialValueKind
   );
   System.out.println("Map Result: " + FUTURE.join(mappedKind)); // Output: Result: 10

   // --- flatMap: sequence async operations that depend on previous results ---
   Function<String, Kind<CompletableFutureKind.Witness, String>> asyncStep2 =
           input -> FUTURE.widen(
                   CompletableFuture.supplyAsync(() -> input + " -> Step2 Done")
           );

   Kind<CompletableFutureKind.Witness, String> flatMappedKind = futureMonad.flatMap(
           asyncStep2,
           mappedKind // "Result: 10" feeds into asyncStep2
   );
   System.out.println("FlatMap Result: " + FUTURE.join(flatMappedKind));
   // Output: Result: 10 -> Step2 Done

   // --- ap: apply a function from one future to a value from another ---
   Kind<CompletableFutureKind.Witness, Function<Integer, String>> funcKind =
           futureMonad.of(i -> "FuncResult:" + i);
   Kind<CompletableFutureKind.Witness, Integer> valKind = futureMonad.of(25);

   Kind<CompletableFutureKind.Witness, String> apResult = futureMonad.ap(funcKind, valKind);
   System.out.println("Ap Result: " + FUTURE.join(apResult)); // Output: FuncResult:25

   // --- map2: combine two independent futures ---
   Kind<CompletableFutureKind.Witness, Integer> f1 = futureMonad.of(5);
   Kind<CompletableFutureKind.Witness, String> f2 = futureMonad.of("abc");

   BiFunction<Integer, String, String> combine = (i, s) -> s + i;
   Kind<CompletableFutureKind.Witness, String> map2Result = futureMonad.map2(f1, f2, combine);
   System.out.println("Map2 Result: " + FUTURE.join(map2Result)); // Output: abc5
}

• CompletableFutureExample.java

This is where CompletableFutureMonad shines. Unlike exceptionally which returns a plain value, handleErrorWith returns a new Kind — so recovery itself can be asynchronous.

 public void errorHandlingExample(){
   MonadError<CompletableFutureKind.Witness, Throwable> futureMonad = Instances.monadError(completableFuture());

   Kind<CompletableFutureKind.Witness, String> failedKind =
           futureMonad.raiseError(new IllegalStateException("Processing Failed"));

   // Recovery handler — inspect the error and return a new async computation
   Function<Throwable, Kind<CompletableFutureKind.Witness, String>> recoveryHandler =
           error -> {
              if (error instanceof IllegalStateException) {
                 // Recovery can itself be async
                 return FUTURE.widen(CompletableFuture.supplyAsync(() ->
                         "Recovered from: " + error.getMessage()));
              }
              // Re-raise anything we can't handle
              return futureMonad.raiseError(
                      new RuntimeException("Recovery failed", error));
           };

   // Apply the handler — transforms the failed future into a recovered one
   Kind<CompletableFutureKind.Witness, String> recovered =
           futureMonad.handleErrorWith(failedKind, recoveryHandler);
   System.out.println(FUTURE.join(recovered));
   // Output: Recovered from: Processing Failed

   // Success values pass through untouched — the handler is never called
   Kind<CompletableFutureKind.Witness, String> successKind = futureMonad.of("All Good");
   Kind<CompletableFutureKind.Witness, String> handledSuccess =
           futureMonad.handleErrorWith(successKind, recoveryHandler);
   System.out.println(FUTURE.join(handledSuccess));
   // Output: All Good
}

The handler receives the cause of the failure, unwrapped from CompletionException when necessary. This lets you pattern-match on specific exception types and choose recovery strategies — retry, fallback, or re-raise — all within the same compositional pipeline.

CompletableFuture has dedicated JMH benchmarks measuring async composition overhead, error recovery, and chain depth. Key expectations:

• of / raiseError are very fast — they wrap already-completed futures with no thread scheduling
• flatMap chains add minimal overhead beyond the underlying thenCompose cost
• handleErrorWith matches exceptionallyCompose performance while providing stronger composition guarantees

./gradlew :hkj-benchmarks:jmh --includes=".*CompletableFutureBenchmark.*"

See Benchmarks & Performance for full details, expected ratios, and how to interpret results.