result

func (Result[T]) BubbleUp ¶

func (r Result[T]) BubbleUp() T

BubbleUp returns the value if Ok, or panics with a tryError if Err. This enables Rust-like ? operator behavior when combined with Catch(). The panic will be recovered by Catch() and converted back to a Result.

When to use:

• When you want early returns without verbose if-err-return patterns
• When building sequential operations that should stop on first error
• When the calling function uses defer Catch(&res)

IMPORTANT: The calling function MUST use defer Catch(&res) to recover the panic.

Example - Sequential operations with early returns:

func ProcessOrder(orderID int) (res Result[Receipt]) {
    defer Catch(&res)
    order := FindOrder(orderID).BubbleUp()       // Returns early if error
    payment := ProcessPayment(order).BubbleUp()  // Returns early if error
    receipt := GenerateReceipt(payment).BubbleUp() // Returns early if error
    return Ok(receipt)
}

Example - Chained database operations:

func GetUserEmail(userID int) (res Result[string]) {
    defer Catch(&res)
    user := repo.FindUser(userID).BubbleUp()
    profile := repo.FindProfile(user.ProfileID).BubbleUp()
    return Ok(profile.Email)
}

func (Result[T]) Err ¶

func (r Result[T]) Err() error

Err returns the error if Result is in error state, otherwise returns nil. If Result was initialized as Err(nil), this returns ErrEmptyResult to prevent nil errors.

When to use:

• When you need to access the error for logging
• When wrapping errors for context
• When propagating errors up the call stack

Example - Error logging with context:

func UpdateUser(user User) Result[User] {
    result := repo.Update(user)
    if result.IsErr() {
        log.Printf("Failed to update user %d: %v", user.ID, result.Err())
        return result.Err[User](fmt.Errorf("update failed: %w", result.Err()))
    }
    return result
}

func (Result[T]) Expect ¶

func (r Result[T]) Expect(panicMsg string) T

Expect returns the value if Ok, or panics with the provided message if Err. Use ONLY in tests or when the error represents an unrecoverable programming error.

When to use:

• In unit tests where failure indicates a test problem
• After validation where error is impossible
• When error represents an invariant violation

AVOID in production code paths where errors are expected business outcomes.

Example - Test assertion:

func TestCreateUser(t *testing.T) {
    result := service.CreateUser("test@example.com", "password")
    user := result.Expect("user creation should succeed in test")
    assert.Equal(t, "test@example.com", user.Email)
}

Example - Critical initialization:

func InitDatabase() {
    result := ConnectDB(config)
    db := result.Expect("database connection is required for application startup")
}

func (Result[T]) ExpectErr ¶

func (r Result[T]) ExpectErr(panicMsg string) error

ExpectErr returns the error if Result is Err, or panics if Result is Ok. Use this in tests when you expect an operation to fail.

When to use:

• In tests validating error conditions
• When you need to assert that an operation failed
• When testing validation logic

Example - Testing validation errors:

func TestInvalidEmail(t *testing.T) {
    result := ValidateEmail("invalid-email")
    err := result.ExpectErr("validation should fail for invalid email")
    assert.Contains(t, err.Error(), "invalid email")
}

Example - Testing authorization:

func TestUnauthorizedAccess(t *testing.T) {
    result := service.AccessResource(unauthorizedUser, resourceID)
    err := result.ExpectErr("should reject unauthorized access")
    assert.ErrorIs(t, err, ErrUnauthorized)
}

func (Result[T]) IsErr ¶

func (r Result[T]) IsErr() bool

IsErr reports whether the Result contains an error. Equivalent to !IsOk() but reads more naturally when checking for failure.

When to use:

• When early-returning on errors
• When you want to handle errors first
• When checking for failure is more natural than checking for success

Example - Early return on error:

func CreateOrder(userID int, items []Item) Result[Order] {
    userResult := repo.FindUser(userID)
    if userResult.IsErr() {
        return result.Err[Order](fmt.Errorf("user validation failed: %w", userResult.Err()))
    }
    // Continue with order creation...
}

func (Result[T]) IsOk ¶

func (r Result[T]) IsOk() bool

IsOk reports whether the Result contains a successful value. Use this for explicit checking before accessing the value.

When to use:

• When you need to branch on success/failure
• When logging or debugging operation outcomes
• When you need to perform different actions based on success

Example - Conditional processing based on result:

func ProcessUser(userID int) {
    userResult := repo.FindByID(userID)
    if userResult.IsOk() {
        user := userResult.Unwrap()
        SendWelcomeEmail(user)
        log.Printf("Processed user: %s", user.Email)
    } else {
        log.Printf("Failed to process user %d: %v", userID, userResult.Err())
    }
}

func (Result[T]) MapError ¶

func (r Result[T]) MapError(fn func(e error) error) Result[T]

MapError transforms the error if Result is Err, leaving Ok values unchanged. Use this to wrap, annotate, or transform errors while preserving successful values.

When to use:

• When adding context to errors (wrapping with fmt.Errorf)
• When converting between error types
• When sanitizing errors for external APIs

Example - Adding context to database errors:

func GetUser(id int) Result[User] {
    result := repo.FindByID(id)
    return result.MapError(func(err error) error {
        return fmt.Errorf("failed to get user %d: %w", id, err)
    })
}

Example - Converting internal errors to API errors:

func APIGetUser(id int) Result[User] {
    result := db.FindUser(id)
    return result.MapError(func(err error) error {
        if errors.Is(err, sql.ErrNoRows) {
            return ErrUserNotFound // Convert to API error
        }
        return ErrInternalServer // Hide internal details
    })
}

func (Result[T]) Ok ¶

func (r Result[T]) Ok(out *T) error

Ok copies the value into out if successful, returning nil. Returns the error if Result is Err. This provides Go-idiomatic error handling.

When to use:

• When integrating with traditional Go code expecting (value, error)
• When you want Go's "comma ok" style extraction
• When converting from Result back to traditional Go patterns

Example - Traditional Go error handling style:

func ProcessUser(userID int) error {
    var user User
    if err := repo.FindByID(userID).Ok(&user); err != nil {
        return fmt.Errorf("failed to load user: %w", err)
    }
    // Use user...
    return nil
}

Example - HTTP handler with Result:

func HandleGetUser(w http.ResponseWriter, r *http.Request) {
    var user User
    err := service.GetUser(userID).Ok(&user)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(user)
}

func (Result[T]) Unwrap ¶

func (r Result[T]) Unwrap() T

Unwrap returns the value if Ok, or panics with a generic message if Err. Shorthand for Expect with a default panic message.

When to use:

• In tests for quick assertions
• When prototyping

PREFER UnwrapOr, UnwrapOrElse, or proper error handling in production.

Example - Quick test validation:

func TestFindUser(t *testing.T) {
    result := repo.FindByID(123)
    user := result.Unwrap() // Panic if error - acceptable in tests
    assert.NotEmpty(t, user.Name)
}

func (Result[T]) UnwrapOr ¶

func (r Result[T]) UnwrapOr(defaultValue T) T

UnwrapOr returns the value if Ok, otherwise returns the provided default. This is the SAFE way to extract values with a fallback when errors occur.

When to use:

• When you have a reasonable default value for error cases
• When you want to continue execution despite errors
• When the error doesn't need to be propagated

Example - Configuration with defaults:

func GetMaxConnections() int {
    result := LoadConfigValue("max_connections")
    return result.UnwrapOr(100) // Default to 100 if config load fails
}

Example - Cache with fallback:

func GetUserName(userID int) string {
    result := cache.Get(userID)
    user := result.UnwrapOr(User{Name: "Guest"})
    return user.Name
}

func (Result[T]) UnwrapOrElse ¶

func (r Result[T]) UnwrapOrElse(fn func(error) T) T

UnwrapOrElse returns the value if Ok, otherwise computes a fallback from the error. Use when you need to generate a fallback based on the error that occurred.

When to use:

• When the fallback depends on the error type
• When you want to log the error and provide a default
• When the fallback is expensive and should only be computed on error

Example - Error-specific fallback:

func LoadUserProfile(userID int) User {
    result := db.FindUser(userID)
    return result.UnwrapOrElse(func(err error) User {
        log.Printf("Failed to load user %d: %v, returning guest profile", userID, err)
        return GuestUser()
    })
}

Example - Fallback with error categorization:

func GetCachedData(key string) []byte {
    result := cache.Fetch(key)
    return result.UnwrapOrElse(func(err error) []byte {
        if errors.Is(err, ErrCacheExpired) {
            return RefreshCache(key)
        }
        return []byte{}
    })
}

func (Result[T]) Value ¶

func (r Result[T]) Value() option.Option[T]

Value returns an Option[T] containing the value if Ok, or None if Err. Use this when you want to work with the value in an Option context.

When to use:

• When you want to treat the success value as optional
• When converting Result to Option (discarding error details)
• When chaining with Option operations

Example - Converting Result to Option when error details don't matter:

func TryGetCachedUser(userID int) option.Option[User] {
    cacheResult := FetchFromCache(userID)
    return cacheResult.Value() // Some(user) if ok, None if error
}