Proposal: Add withNilReporting Convenience Interface for Optional Unwrapping with Fallback and Error Reporting

[vladyslavsosiuk]

I’d like to propose a new convenience interface that simplifies optional unwrapping while also reporting a failure when the value is unexpectedly nil.

✨ Motivation

In many real-world scenarios, we need to unwrap an optional, fall back to a default value if it’s nil, and still report the fact that the value was missing. This is especially important in production environments, where silent fallbacks can mask underlying issues.

This idea is inspired by the existing withErrorReporting pattern, and I believe a similar approach could be applied to optional unwrapping to improve both code clarity and observability.

Proposed API:

public func withNilReporting<R>(
    _ message: @autoclosure () -> String? = nil,
    fileID: StaticString = #fileID,
    filePath: StaticString = #filePath,
    line: UInt = #line,
    column: UInt = #column,
    unwrap body: @autoclosure () -> R?
) -> R? {
    guard let result = body() else {
        reportIssue(
            message() ?? "expected non-nil value of type \(R.self)",
            fileID: fileID,
            filePath: filePath,
            line: line,
            column: column
        )
        return nil
    }
    return result
}

public func withNilReporting<R>(
    default: @autoclosure () -> R,
    _ message: @autoclosure () -> String? = nil,
    fileID: StaticString = #fileID,
    filePath: StaticString = #filePath,
    line: UInt = #line,
    column: UInt = #column,
    unwrap body: @autoclosure () -> R?
) -> R {
    guard let result = body() else {
        reportIssue(
            message() ?? "expected non-nil value of type \(R.self)",
            fileID: fileID,
            filePath: filePath,
            line: line,
            column: column
        )
        return `default`()
    }
    return result
}

✅ Usage Example

Before:

func createOrder(items: [String]?, discounts: [Double]?) {
    guard let items else {
        reportIssue("items should not be nil")
        return
    }
    let _discounts: [Double]
    if let discounts {
        _discounts = discounts
    } else {
        reportIssue("discounts should not be nil")
        _discounts = []
    }
    // ...
}

After:

func createOrder(items: [String]?, discounts: [Double]?) {
    guard let items = withNilReporting(unwrap: items) else {
        return
    }
    let discounts = withNilReporting(default: [], unwrap: discounts)
    // ...
}

📌 Benefits

• Reduces boilerplate code for optional handling.
• Encourages consistent and visible error reporting.
• Makes fallback logic more declarative and readable.

Would love to hear your thoughts.