The Four Return Types

What You’ll Learn

• Why exactly four return types are sufficient
• When to use each type: T, Option, Result, Promise
• How to convert between types
• Why Java’s standard library isn’t enough

Overview

Every function in JBCT returns one of four semantic shapes: T, Option<T>, Result<T>, or Promise<T>. Not “usually” or “preferably”—one of the four, always. Two qualifications keep the rule exact rather than merely emphatic. The shapes compose in one permitted way, Result<Option<T>> and its asynchronous form Promise<Option<T>>, where fallibility and optionality are genuinely independent concerns; every deeper nesting is a smell this chapter names later. And void remains available at the edges as a deliberate signal that failure is irrelevant to the caller, distinct from Result<Unit>, where it is not. This isn’t an arbitrary restriction; it’s intentional compression of complexity into type signatures.

Why by criteria:

• Mental Overhead: Hidden error channels (exceptions), hidden optionality (null), hidden asynchrony (blocking I/O) force remembering behavior not in signatures. Explicit types eliminate this (+3).
• Reliability: Compiler verifies error handling, null safety, and async boundaries when encoded in types (+3).
• Complexity: Four types cover all scenarios - no guessing about combinations (+2).

T - Synchronous, Cannot Fail, Always Present

Use this when the operation is pure computation with no possibility of failure or missing data. Mathematical calculations, transformations of valid data, simple getters. If you can’t think of a way this function could fail or return nothing, it returns T.

public record FullName(String value) {
    public String initials() {  // returns String (T)
        return value.chars()
                    .filter(Character::isUpperCase)
                    .collect(StringBuilder::new,
                             StringBuilder::appendCodePoint,
                             StringBuilder::append)
                    .toString();
    }
}

The signature String initials() tells you: this always succeeds, always returns a value, completes immediately.

Return T when:

• Pure computation (e.g., calculateTotal, formatCurrency)
• Transformation of already-valid data (e.g., toUpperCase, extractId)
• Getters for required fields (e.g., user.email(), order.total())

Option<T> - Synchronous, Cannot Fail, May Be Missing

Use this when absence is a valid outcome but failure isn’t possible. Lookups that might not find anything, optional configuration, nullable database columns when null is semantically meaningful. The key: missing data is normal business behavior, not an error.

public interface PreferenceRepository {
    Option<Theme> findThemePreference(UserId id);  // might not be set
}

The signature Option<Theme> tells you: this always succeeds, but the value might be absent. The caller must handle both cases.

Return Option<T> when:

• Lookup might not find anything (e.g., findByUsername)
• Field is genuinely optional in the domain (e.g., user.middleName())
• “Not found” is a normal outcome, not an error

Result<T> - Synchronous, Can Fail, Business/Validation Errors

Use this when an operation might fail for business or validation reasons. Parsing input, enforcing invariants, business rules that can be violated. Failures are represented as typed Cause objects, not exceptions.

Note: Cause represents domain failures or error reasons. Think of it as “FailureReason” or “DomainError”—the typed representation of why a business operation failed.

public record Email(String value) {
    private static final Pattern EMAIL_PATTERN =
        Pattern.compile("^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+$");
    private static final Fn1<Cause, String> INVALID_EMAIL =
        Causes.forOneValue("Invalid email format: %s");

    public static Result<Email> email(String raw) {
        return Verify.ensure(raw, Verify.Is::present)
                     .map(String::trim)
                     .filter(INVALID_EMAIL, EMAIL_PATTERN.asMatchPredicate())
                     .map(Email::new);
    }
}

The signature Result<Email> tells you: this might fail (invalid format), completes immediately, failure is typed.

Return Result<T> when:

• Validating input (e.g., Email.email(raw))
• Enforcing business rules (e.g., checkInvariant)
• Parsing or constructing domain objects (e.g., OrderId.orderId(raw))

Why Result: Error Handling Philosophy

Error handling logic belongs where business context exists to make decisions. Sometimes that’s close to where the error occurred; sometimes the error propagates unchanged because only the caller has enough context to decide.

Different mechanisms have distinct trade-offs:

Mechanism	Transparency	Ergonomics	Reliability
Checked exceptions	✅ Explicit	❌ Verbose, coupling	✅ Compiler-enforced
Unchecked exceptions	❌ Hidden	⚠ Mental overhead	❌ Silent failures
Errors as values (Go)	✅ Visible	❌ Manual propagation	❌ Easy to ignore
Functional (Result)	✅ In type	✅ Monadic composition	✅ Compiler-enforced

Result<T> combines the best: explicit in signature, ergonomic via map/flatMap, compiler-verified handling.

Promise<T> - Asynchronous, Can Fail

Use this for any operation that leaves the process: I/O, external service calls, inter-process communication. Promise<T> is semantically equivalent to Result<T> but asynchronous - failures are carried in the Promise itself, not nested inside it.

public interface AccountRepository {
    Promise<Account> findById(AccountId id);  // async lookup, can fail
}

The signature Promise<Account> tells you: this completes later (async), might fail (network, database), failure is carried in the Promise.

Promise as Async Result

Think of Promise<T> as the asynchronous counterpart to Result<T>. Both represent operations that can succeed or fail with typed errors. The only difference is timing: Result<T> completes immediately, Promise<T> completes later. The same map/flatMap patterns work identically; converting is trivial (result.async() lifts to Promise, promise.await() blocks to Result). When you understand Result<T>, you understand Promise<T>.

Promise Resolution and Thread Safety:

Promise resolution is thread-safe and happens exactly once:

• Multiple threads can attempt resolution - only the first succeeds
• Resolution serves as synchronization point
• Transformations execute after resolution
• Side effects execute independently

var promise = Promise.<User>promise();

// Multiple threads racing to resolve - only first wins
executor.submit(() -> promise.succeed(user1));  // First to resolve
executor.submit(() -> promise.succeed(user2));  // Ignored

// All transformations see the same result (user1)
promise.map(this::processUser)
       .flatMap(this::saveToDatabase)
       .onSuccess(this::logSuccess);

Return Promise<T> when:

• Any I/O operation (database, HTTP, file system)
• External service calls
• Any other operation that leaves the process (messaging, inter-process calls)

A long-running computation is not on this list. CPU-bound work returns Result<T> no matter how long it takes: Promise marks crossing the process boundary, and how an operation is scheduled is the caller’s decision, made visible at the composition site (Promise.lift), never encoded in the leaf’s type.

Why Exactly Four?

These four types form a complete basis for composition. You can lift “up” when needed (Option to Result to Promise), but you never nest the same concern twice.

Each type represents one orthogonal concern:

• Synchronous vs. asynchronous: now vs. later
• Can fail vs cannot fail: error channel present or absent
• Value vs optional value: presence guaranteed or not

Decision table:

Return Type Matrix

Allowed Return Types

Discouraged

Forbidden (Double-Monad Nesting)

Rule: Each concern (optionality, failure, asynchrony) appears at most once in a return type; emptiness is the collection’s own concern, already carried as a value.

Why Not Java’s Built-in Types?

“Can’t I just use Optional, CompletableFuture, and exceptions?”

You could, but you’d hit these problems:

Key differences:

• Explicit in types: Signature tells you failure modes, no hidden exceptions
• Consistent composition: map/flatMap work the same across all types
• No nesting: One concern per type level
• Better inference: AI can generate correct error handling from types alone

Type Conversions

Lifting: Moving Between Types

You can lift a “lower” type into a “higher” one:

// T → Option/Result/Promise
Option.option(value)
Result.success(value)
Promise.success(value)

// Option → Result/Promise
option.toResult(cause)
option.async(cause)

// Result → Promise
result.async()

Example:

public Promise<Response> execute(Request request) {
    return ValidRequest.validRequest(request)
                       .async()  // Result → Promise
                       .flatMap(step1::apply)
                       .flatMap(step2::apply);
}

Forbidden Nesting: Promise<Result<T>>

Promise<Result<T>> is forbidden. Promise<T> already carries failures - nesting Result inside creates two error channels.

Wrong:

Promise<Result<User>> loadUser(UserId id) { /* ... */ }

// Caller must unwrap twice - absurd ceremony
loadUser(id)
    .flatMap(resultUser -> resultUser.fold(
        Cause::promise,
        user -> Promise.success(user)
    ));

Right:

Promise<User> loadUser(UserId id) { /* ... */ }

// Caller just chains
return loadUser(id).flatMap(nextStep);

Allowed Nesting: Result<Option<T>>

Result<Option<T>> is permitted sparingly for “optional value that can fail validation.”

Result<Option<ReferralCode>> refCode = ReferralCode.referralCode(input);
// Success(None) = not provided, valid
// Success(Some(code)) = provided and valid
// Failure(cause) = provided but invalid

Use Verify.ensureOption() (Pragmatica Core 0.9.0+) to implement this pattern:

public static Result<Option<ReferralCode>> referralCode(String raw) {
    return Verify.ensureOption(
        Option.option(raw).map(String::trim).filter(s -> !s.isEmpty()),
        PATTERN.asMatchPredicate(),
        INVALID_FORMAT
    ).map(opt -> opt.map(ReferralCode::new));
}

API Quick Reference

Type Conversions

// Option conversions
option.toResult(cause)      // Option → Result
option.async(cause)         // Option → Promise
option.toOptional()         // Option → Java Optional

// Result conversions
result.async()              // Result → Promise
result.option()             // Result → Option (loses error)

// Promise conversions
promise.await()             // Promise → Result (blocks)
promise.await(timeout)      // Promise → Result (with timeout)

// Cause conversions (preferred)
cause.result()              // Cause → Result failure
cause.promise()             // Cause → Promise failure

Creating Instances

// Option
Option.some(value)
Option.none()
Option.option(nullable)     // null → none

// Result
Result.success(value)
cause.result()              // Preferred for failure

// Promise
Promise.success(value)
cause.promise()             // Preferred for failure
Promise.promise()           // Unresolved

Key Takeaways

1. Four types cover all cases - T, Option, Result, Promise
2. Signatures tell everything - failure modes, optionality, synchrony
3. Lift up, never nest - Convert to higher types, never Promise<Result<T>>
4. Consistent composition - Same map/flatMap across all types
5. Use Cause methods - Prefer cause.result() over Result.failure(cause)

When void Is the Right Return Type

The four return kinds cover cases where the caller uses the result. But there’s a distinct category where no caller ever inspects the outcome: fire-and-forget side effects.

Two legitimate cases:

1. API Conformance — An external API requires void (JDK’s Runnable, framework event handlers)
2. Fire-and-Forget Side Effects — The caller deliberately discards the outcome (metrics, event publishing, cache warming)

// Fire-and-forget — caller doesn't care about outcome
void recordLatency(String operation, Duration elapsed);
void publishDomainEvent(OrderPlaced event);

The void return type is a semantic signal: errors are handled internally, never propagated to the caller. Compare:

• Result<Unit> — failure matters (e.g., deleteUser)
• Promise<Unit> — async, failure matters (e.g., sendEmail)
• void — failure is irrelevant to caller (e.g., recordMetric)

Note: The Void type parameter (as in Result<Void>) remains forbidden — use Unit. The void return type is the fire-and-forget signal.

Exercises

See Appendix B for exercises on:

• Exercise 1.3: Type Lifting
• Exercise 1.4: Cause Creation
• Exercise 1.5: Pragmatica Core Operations

What’s Next

Pragmatica Core Essentials covers Pragmatica Core - the library that provides these four types. You’ll learn the API in depth and see common usage patterns.