Package com.github.darksoulq.abyssallib.common.serialization

Interface DataResult<T>

Type Parameters:
T - The type of the wrapped value.
All Known Implementing Classes:
DataResult.Error, DataResult.Success
public interface DataResult<T>
A monadic container representing the result of a serialization or deserialization operation. Contains either a successful value, potentially with partial warnings, or an error message detailing the failure context.

  • Method Details

    • success

      static <T> DataResult<T> success(T value)
      Creates a successful result containing the provided value with no structural warnings.
      Type Parameters:
      T - The type of the value.
      Parameters:
      value - The value to wrap.
      Returns:
      A successful DataResult.

    • partial

      static <T> DataResult<T> partial(T value, List<DataError> warnings)
      Creates a partial result containing the provided value, logging structural warnings.
      Type Parameters:
      T - The type of the value.
      Parameters:
      value - The value mapped despite violations.
      warnings - The collected issues encountered alongside data generation.
      Returns:
      A successful DataResult with attached warnings.

    • error

      static <T> DataResult<T> error(String message)
      Creates an error result with the provided string message.
      Type Parameters:
      T - The expected type of the value.
      Parameters:
      message - The error message.
      Returns:
      An error DataResult wrapping a custom DataError.

    • error

      static <T> DataResult<T> error(DataError error)
      Creates an error result driven by an explicit DataError type.
      Type Parameters:
      T - The expected type of the value.
      Parameters:
      error - The structural error implementation.
      Returns:
      An error DataResult.

    • isSuccess

      boolean isSuccess()
      Returns:
      True if this result represents a success (including partial successes), false otherwise.

    • isError

      boolean isError()
      Returns:
      True if this result represents an error, false otherwise.

    • isPartial

      boolean isPartial()
      Returns:
      True if this result is successful but carries recorded warnings.

    • result

      Optional<T> result()
      Returns:
      An Optional containing the value if successful, or empty if an error.

    • error

      Optional<String> error()
      Returns:
      An Optional containing the formatted error message if an error, or empty if successful.

    • dataError

      Optional<DataError> dataError()
      Returns:
      An Optional containing the exact DataError type evaluated during deserialization.

    • warnings

      List<DataError> warnings()
      Returns:
      The collection of recorded warnings if this is a partial result.

    • getOrThrow

      T getOrThrow()
      Retrieves the value or throws a RuntimeException if this is an error.
      Returns:
      The wrapped value.
      Throws:
      RuntimeException - If this result represents an error.

    • orElse

      T orElse(T defaultValue)
      Retrieves the value, or returns the provided default value if this is an error.
      Parameters:
      defaultValue - The fallback value.
      Returns:
      The wrapped value or the default.

    • map

      <R> DataResult<R> map(Function<? super T,? extends R> mapper)
      Transforms the wrapped value using the provided mapping function.
      Type Parameters:
      R - The new value type.
      Parameters:
      mapper - The transformation logic.
      Returns:
      A new DataResult containing the transformed value.

    • flatMap

      <R> DataResult<R> flatMap(Function<? super T,? extends DataResult<? extends R>> mapper)
      Transforms the wrapped value into a new DataResult using the provided flat-mapping function. Supports covariant return types to prevent generic capture mismatches.
      Type Parameters:
      R - The new value type.
      Parameters:
      mapper - The transformation logic that yields a DataResult.
      Returns:
      A new DataResult.

    • mapError

      DataResult<T> mapError(Function<String,String> errorMapper)
      Transforms the error message if this result represents an error.
      Parameters:
      errorMapper - The logic to apply to the existing error message.
      Returns:
      A new DataResult with the transformed error.

    • prependPath

      DataResult<T> prependPath(String path)
      Prepends a path segment to the error context or recorded warnings to build a complete diagnostic trajectory.
      Parameters:
      path - The path segment to prepend.
      Returns:
      A new DataResult reflecting the updated path logic.

    • addWarning

      DataResult<T> addWarning(DataError warning)
      Injects a recorded warning into the execution timeline without forcing a structural failure.
      Parameters:
      warning - The localized diagnostic logging message mapped as an error.
      Returns:
      A modified instance retaining the internal value but flagging warning status.