Result<V, E>

Result<User, String> ok  = Result.ok(user);
Result<User, String> err = Result.err("user not found");

result.isSuccess()  // true if Ok
result.isError()    // true if Err

switch (result) {
    case Result.Ok<User, String>(var user) -> System.out.println("ok: " + user.name());
    case Result.Err<User, String>(var err) -> System.out.println("err: " + err);
}

// fold — the preferred extractor: both branches are forced
String response = result.fold(
    user  -> "Welcome, " + user.name(),
    error -> "Error: " + error
);

// Eager fallback
User user = result.getOrElse(User.anonymous());

// Lazy fallback (supplier called only on Err)
User user = result.getOrElseGet(() -> userRepo.defaultUser());

// Throw a domain exception when an error is a programming error
User user = result.getOrThrow(e -> new IllegalStateException("Unexpected: " + e));

Result<String, String> name = result.map(User::name);
// Ok("Alice") or the original Err unchanged

// Translate the error type while preserving the value track
Result<User, OrderError> translated =
    result.mapError(msg -> new OrderError(msg));

Result<Profile, String> profile =
    findUser(id)                       // Result<User, String>
        .flatMap(user -> loadProfile(user)); // returns Result<Profile, String>

// Filter with a static error value
Result<User, String> active =
    result.filter(User::isActive, "account is inactive");

// Filter with a dynamic error derived from the value
Result<User, String> active =
    result.filter(User::isActive, u -> "account " + u.id() + " is inactive");

result
    .peek(user  -> log.info("Processing user {}", user.id()))    // on Ok
    .peekError(err -> log.warn("Request failed: {}", err))       // on Err
    .map(User::name);

// recover: Err -> Ok using the error value
Result<User, String> result =
    findUser(id).recover(err -> User.guest());

// recoverWith: Err -> Result (may itself fail)
Result<User, String> result =
    findUser(id).recoverWith(err -> findUserByEmail(err));

// sequence: List<Result<V,E>> -> Result<List<V>, E>
// Stops at the first Err (fail-fast)
List<Result<User, String>> lookups = ids.stream()
    .map(userRepo::findById)
    .toList();

Result<List<User>, String> allOrFirst = Result.sequence(lookups);

// traverse: applies a fallible mapper to each element and collects
Result<List<String>, String> names =
    Result.traverse(ids, id -> userRepo.findById(id).map(User::name));

// Group by a key — each group is a guaranteed-non-empty NonEmptyList
Map<Integer, NonEmptyList<String>> byLength =
    Stream.of("a", "bb", "cc", "ddd")
          .collect(Result.groupingBy(String::length));
// {1 -> ["a"], 2 -> ["bb", "cc"], 3 -> ["ddd"]}

// Downstream variant — transform each group after grouping
Map<Integer, Long> countByLength =
    Stream.of("a", "bb", "cc", "ddd")
          .collect(Result.groupingBy(String::length, nel -> (long) nel.size()));
// {1 -> 1, 2 -> 2, 3 -> 1}

// Domain example — group users by role
Map<Role, NonEmptyList<User>> byRole =
    users.stream()
         .collect(Result.groupingBy(User::role));

// Count per role using the downstream variant
Map<Role, Integer> countByRole =
    users.stream()
         .collect(Result.groupingBy(User::role, NonEmptyList::size));

// ── Results.toList() — returns first Err (stream still fully traversed) ──────
Result<List<Integer>, String> validated =
    Stream.<Result<Integer, String>>of(Result.ok(1), Result.ok(2), Result.ok(3))
          .collect(Results.toList());
// → Ok([1, 2, 3])

Result<List<Integer>, String> firstFails =
    Stream.<Result<Integer, String>>of(Result.ok(1), Result.err("bad"), Result.ok(3))
          .collect(Results.toList());
// → Err("bad")

// Real-world: validate every line in a CSV upload — returns first parse error
// Note: all lines are parsed; toList() does not short-circuit upstream evaluation.
// Do not rely on early termination for expensive or side-effecting parse logic.
Result<List<OrderRow>, String> rows = csvLines.stream()
    .map(OrderRow::parse)          // Stream<Result<OrderRow, String>>
    .collect(Results.toList());    // Ok(all rows) or first Err encountered

// ── Results.partitioning() — process all, split into oks and errors ───────────
Results.Partition<OrderRow, String> p = csvLines.stream()
    .map(OrderRow::parse)
    .collect(Results.partitioning());

List<OrderRow>  good   = p.oks();    // rows that parsed successfully
List<String>    bad    = p.errors(); // parse error messages

// Real-world: import as many records as possible; report failures separately
importService.bulkInsert(p.oks());
auditLog.recordRejections(p.errors());

// ── Results.groupingBy() — group elements by a derived key ───────────────────
Map<Status, NonEmptyList<Order>> byStatus =
    orders.stream()
          .collect(Results.groupingBy(Order::status));
// Every map value is NonEmptyList — the non-emptiness is in the type

// Downstream variant: count orders per status
Map<Status, Integer> countByStatus =
    orders.stream()
          .collect(Results.groupingBy(Order::status, NonEmptyList::size));

Result<String, String> ok  = Result.ok("hello");
Result<String, String> err = Result.err("oops");

// Result → Option (discards the error; Err → None)
Option<String> opt = ok.toOption();

// Result → Try (maps error to Throwable)
Try<String> tried = ok.toTry(e -> new RuntimeException(e));

// Result → Either<E, V>  (Ok → right, Err → left)
Either<String, String> either = ok.toEither();

// Result → Optional<V>  (Err → Optional.empty())
Optional<String> javaOpt = ok.toOptional();

// Result → CompletableFuture<V>  (Err → failed future with NoSuchElementException)
CompletableFuture<String> future = ok.toFuture();

// Result → CompletableFuture<V>  with error mapper
CompletableFuture<String> future2 = err.toFuture(e -> new IllegalStateException(e));

// ── From other types ──────────────────────────────────────────────────────────

// Option → Result
Option<String> option = Option.some("hello");
Result<String, String> fromOpt = option.toResult("not found");

// Try → Result (keeps Throwable as typed error)
Try<String> t = Try.of(() -> Files.readString(path));
Result<String, Throwable> fromTry = t.toResult();

// Optional → Result  (empty → Err(NoSuchElementException))
Result<String, NoSuchElementException> fromOptional =
    Result.fromOptional(Optional.of("hello"));

// Either<E, V> → Result  (left → Err, right → Ok)
Either<String, Integer> right = Either.right(42);
Result<Integer, String> fromEither = Result.fromEither(right);

// CompletableFuture → Result (blocks; unwraps CompletionException)
Result<String, Throwable> fromFuture =
    Result.fromFuture(CompletableFuture.completedFuture("done"));

// Bad: creates Result<Result<Profile, String>, String>
Result<Result<Profile, String>, String> nested =
    findUser(id).map(user -> loadProfile(user));

// Good: flat result
Result<Profile, String> profile =
    findUser(id).flatMap(user -> loadProfile(user));

// Bad: silently discards the error track
String name = result.getOrElse(User.anonymous()).name();

// Good: make both branches explicit
String name = result.fold(
    user  -> user.name(),
    error -> { log.warn("Using anonymous due to: {}", error); return "anonymous"; }
);

sealed interface OrderError {
    record InvalidItems(List<String> reasons) implements OrderError {}
    record PaymentFailed(String code)         implements OrderError {}
    record ShippingUnavailable(String region) implements OrderError {}
}

public Result<OrderConfirmation, OrderError> placeOrder(OrderRequest req) {
    return validateItems(req.items())          // Result<List<Item>, OrderError>
        .flatMap(items -> charge(req.payment(), items))  // Result<Receipt, OrderError>
        .flatMap(receipt -> ship(req.address(), receipt)) // Result<Shipment, OrderError>
        .map(shipment -> new OrderConfirmation(shipment.trackingId()));
}