Return Type Design

A method's return type is the fulfillment of its promise. It answers: "What do I get back?" The answer must be clear, type-safe, and expressive enough to handle all possible outcomes—success, absence, failure, and everything in between.

Return type design is deceptively complex. Consider a simple method: getUser(userId). What should it return?

• A User object? (What if user doesn't exist?)
• A nullable User | null? (Caller might forget to check)
• An Optional<User>? (Forces handling, but adds verbosity)
• A Result<User, Error>? (Distinguishes 'not found' from 'database error')

Each choice carries implications for caller code, error handling patterns, and API consistency. The right answer depends on context, conventions, and the semantics you want to convey.

This page equips you to make these decisions deliberately—understanding the trade-offs and choosing return types that make APIs robust and intuitive.

Let's start with a fundamental question: should you ever return void?

When Void Is Appropriate

Void returns are appropriate for pure side-effect methods where:

1. The method performs an action (writes to database, sends message, etc.)
2. Success is indicated by normal completion (no exception)
3. There's nothing meaningful to return

// Acceptable void returns
void closeConnection();
void logEvent(Event event);
void shutdown();
void dispose();

When Void Is Problematic

Void becomes an anti-pattern when it discards useful information:

The Command-Query-Responsibility-Segregation (CQRS) Nuance

CQRS advocates that commands (mutations) should not return values—they should be pure commands. This is philosophically clean but pragmatically inconvenient. In practice, most systems adopt a compromise:

• Commands return acknowledgment or created identity: createUser() returns the created UserId or full User
• Commands return action result: updateOrder() returns whether anything changed
• But commands don't return unrelated query data: Don't return the user count when creating a user

The key principle: don't discard information the caller will need to fetch anyway.

When a method might not have a value to return, how should this absence be communicated? This is one of the most consequential return type decisions.

The Billion-Dollar Mistake

Tony Hoare, inventor of null references, called them his 'billion-dollar mistake'. Null is problematic because:

1. It's implicit — Nothing in the type signature indicates that null is possible
2. It's easy to ignore — Callers can forget to check
3. It propagates — Null flows through code until it crashes far from its origin
4. It's ambiguous — Does null mean 'not found', 'not applicable', or 'error'?

Optional/Maybe Types: Explicit Absence

Modern languages provide Optional types that make absence explicit in the type system:

When to Use Which

TypeScript's Approach: Union Types

// TypeScript uses union types with strict null checks
function findUser(id: UserId): User | undefined {
    return users.get(id);
}

// Caller must narrow the type
const user = findUser(id);
if (user === undefined) {
    throw new UserNotFoundError(id);
}
// After check, TypeScript knows user is User, not undefined
const email = user.email; // Safe!

When operations can fail, how should failure be communicated? This is one of the great debates in programming language design, and your API must pick a side—or thoughtfully blend approaches.

Exceptions: Implicit Error Channel

Exceptions create a separate control flow for error cases:

public User getUser(UserId id) throws UserNotFoundException {
    User user = repository.find(id);
    if (user == null) {
        throw new UserNotFoundException(id);
    }
    return user;
}

// Caller
try {
    User user = getUser(id);
    processUser(user);
} catch (UserNotFoundException e) {
    // Handle missing user
}

Result Types: Explicit Error Channel

Result types (also called Either, Try, or similar) make errors part of the return type:

type Result<T, E> = { success: true; value: T } | { success: false; error: E };

function getUser(id: UserId): Result<User, UserNotFoundError> {
    const user = repository.find(id);
    if (user === undefined) {
        return { success: false, error: new UserNotFoundError(id) };
    }
    return { success: true, value: user };
}

// Caller must handle both cases
const result = getUser(id);
if (!result.success) {
    // Handle error
    console.error(result.error.message);
    return;
}
const user = result.value; // TypeScript knows this is User

When a method returns multiple items, collection return types require careful design.

Never Return Null for Collections

This is a cardinal rule: if a method returns a collection and there are no items, return an empty collection—never null.

// WRONG: Returns null for no results
public List<Order> getOrders(CustomerId id) {
    List<Order> orders = repository.findByCustomer(id);
    if (orders.isEmpty()) {
        return null; // Forces every caller to null-check
    }
    return orders;
}

// RIGHT: Returns empty list for no results
public List<Order> getOrders(CustomerId id) {
    return repository.findByCustomer(id); // Empty list if none
}

// Caller code is clean:
for (Order order : getOrders(customerId)) {
    process(order);
}
// Works correctly whether there are 0, 1, or many orders

Choosing Collection Types

Return the most appropriate collection interface:

Mutability Considerations

Should the returned collection be mutable or immutable?

// Dangerous: Returns internal mutable list
public List<Item> getItems() {
    return this.items; // Caller can mutate our internal state!
}

// Safe: Returns immutable copy
public List<Item> getItems() {
    return List.copyOf(this.items); // Immutable view
}

// Safe: Returns unmodifiable view
public List<Item> getItems() {
    return Collections.unmodifiableList(this.items); // View, not copy
}

Guidelines:

1. Public APIs: Return immutable collections (or unmodifiable views)
2. Internal methods: May return mutable if documented and performance-critical
3. Document mutability: If returning mutable, explicitly document that caller may modify

Sometimes a method needs to return multiple pieces of related information. Rather than using out parameters, multiple return values (in languages that support them), or cramming everything into a generic tuple, design dedicated response objects.

When to Use Response Objects

1. Method returns multiple related values
2. Return includes metadata (counts, pagination info, timing)
3. Return includes partial success (some items succeeded, some failed)
4. Return may grow over time (extensibility)

Designing Response Objects

Batch Operation Results

Batch operations often have partial success—some items succeed, others fail. Design response objects that capture this:

Asynchronous operations require special return types that represent values that will be available in the future.

Promise/Future-Based Returns

Most modern languages provide Promise, Future, Task, or similar types for async operations:

Observable/Stream Returns

For operations that produce multiple values over time, use stream or observable types:

// RxJS Observable for streaming data
function watchOrders(customerId: string): Observable<Order> {
    return new Observable(subscriber => {
        const unsubscribe = ordersCollection
            .where('customerId', '==', customerId)
            .onSnapshot(snapshot => {
                snapshot.docChanges().forEach(change => {
                    if (change.type === 'added') {
                        subscriber.next(change.doc.data() as Order);
                    }
                });
            });
        
        return () => unsubscribe();
    });
}

// Usage: subscribes to real-time updates
watchOrders(customerId).subscribe({
    next: order => console.log('New order:', order),
    error: err => console.error('Error:', err),
});

Generics allow return types to be parameterized, enabling type-safe, reusable APIs.

Basic Generic Returns

// Repository with generic return types
public interface Repository<T, ID> {
    Optional<T> findById(ID id);      // Returns Optional<User> for Repository<User, UserId>
    List<T> findAll();                // Returns List<User>
    T save(T entity);                 // Returns saved User
    void delete(T entity);
}

// Usage maintains full type safety
Repository<User, UserId> userRepo = ...;
Optional<User> user = userRepo.findById(userId); // Fully typed!

Bounded Generics for Constraints

// Generic with upper bound: T must be Comparable
public <T extends Comparable<T>> T findMax(List<T> items) {
    return items.stream()
        .max(Comparator.naturalOrder())
        .orElseThrow();
}

// Usage
Integer maxNum = findMax(List.of(1, 5, 3)); // Works: Integer is Comparable
User maxUser = findMax(users); // Compile error if User isn't Comparable

Wildcard Returns

// Covariant return: can return List of any Number subtype
public List<? extends Number> getValues() {
    return List.of(1, 2.5, 3L); // Mixed Integer, Double, Long
}

// Caller can read but not add
List<? extends Number> values = getValues();
Number n = values.get(0); // OK: can read as Number
values.add(1); // ERROR: can't add, type unknown

TypeScript Generics in Returns

// Generic response wrapper for API calls
interface ApiResponse<T> {
    data: T;
    meta: {
        requestId: string;
        timestamp: Date;
    };
}

async function fetchResource<T>(url: string): Promise<ApiResponse<T>> {
    const response = await fetch(url);
    const data = await response.json();
    return {
        data: data as T,
        meta: {
            requestId: response.headers.get('x-request-id')!,
            timestamp: new Date(),
        },
    };
}

// Usage: caller specifies expected type
const userResponse = await fetchResource<User>('/api/user/123');
const user: User = userResponse.data; // Fully typed!