Namespace: Zentient.Results Assembly: Zentient.Results.dll Available since: v0.1.0

Provides value extraction and unwrapping utilities for IResult<T> instances, enabling safe or deterministic access to the success value.

These methods simplify working with IResult<T> by offering both strict (exception-throwing) and fallback-based access patterns for fluent functional pipelines.

ResultValueExtractionExtensions enables ergonomic and predictable value retrieval while preserving safety and clarity in control flow:

• 🧩 Functional Intent: Keeps result handling declarative and side-effect free.
• 🛑 Fail-Fast Option: Unwrap() enforces success conditions explicitly.
• ✅ Graceful Fallbacks: GetValueOrDefault(...) supports conservative workflows where fallback behavior is expected.
• 📦 Immutability & Consistency: Values are never mutated; methods operate over the final state of the result.

public static class ResultValueExtractionExtensions

• Signature:

  public static TValue Unwrap<TValue>(this IResult<TValue> result)

• Summary: Returns the successful value, or throws if the result is a failure.

• Parameters:

  • result (this IResult<TValue>): The result instance to unwrap.

• Return Value: (TValue) – The success value if present.

• Behavior: Throws InvalidOperationException if the result is a failure.

• Exceptions Thrown:

  • ArgumentNullException (if result is null)
  • InvalidOperationException (if result is failure)

• Remarks: Should only be used when the caller is confident the result is successful (e.g., after IsSuccess check).

• Example Usage:

  var value = result.Unwrap(); // safe only if result.IsSuccess

• Signature:

  public static TValue GetValueOrDefault<TValue>(this IResult<TValue> result, TValue defaultValue)

• Summary: Returns the success value, or the specified default if the result is a failure.

• Parameters:

  • result (this IResult<TValue>): The result instance to inspect.
  • defaultValue (TValue): The fallback value to return if the result failed.

• Return Value: (TValue) – Either the result value or the fallback.

• Behavior: Does not throw. Returns result.Value! on success, or defaultValue otherwise.

• Exceptions Thrown:

  • ArgumentNullException (if result is null)

• Remarks: Ideal for lenient pipelines or UI binding scenarios.

• Example Usage:

  var value = result.GetValueOrDefault("fallback");

IResult<string> configResult = LoadConfig().Try();

string configValue = configResult.GetValueOrDefault("default.json");

if (configResult.IsSuccess)
{
    string actual = configResult.Unwrap(); // Guaranteed safe here
}

• Unwrap() should be used with care—preferably in guarded logic where IsSuccess has been verified.
• GetValueOrDefault() is preferred for defensive and non-throwing patterns.
• Both methods enforce the principle of functional immutability—no internal state is modified.

• IResult<T>
• Result.Try(...)
• ResultTransformationExtensions

#API #ValueExtraction #FunctionalAPI #ExtensionMethods #ResultPattern #ZentientCore

Last Updated: 2025-06-22 Version: 0.4.0