Neptunee.OperationResponse 1.0.4

Neptunee.OperationResponse

Neptunee.OperationResponse streamlines how you handle the response in your application. It eliminates complex if/else statements and offers multi-status support, a user-friendly API,validations checks, JSON compatibility, sync/async operations, and more. It's a clean way to manage the outcomes of your backend.

<p align="center"> <img width="23%" src="icon.png" alt="icon"/>

Overview

The code Inside your Controllers, ApiEndpoints or Command/Query Handlers will be more cleaner and readable.

Operation<Response>
    .SuccessIf(request.Age >= 18, MyValidationErrors.AgeUnder18) // AgeUnder18 is new Error("Age must be 18 or older")
    .OrFailureIf(request.Amount > 1000, MyValidationErrors.AmountOverMax) // AmountOverMax is new SpecificError("Amount","Over maximum") 
    .SetMessageOnFailure("One or more validation errors occur")
    .SetMessageOnSuccess("It's work")
    .OnSuccess(op =>
    {
        //your logic
    })
    .OnFailure(op => _logger.LogError("the logging"))

The Operation<Response> Converted to IActionResult For actions in the controllers or IResult for the endpoint.

{
  "IsSuccess": true,
  "Message": "It's work",
  "Response": {
    // your response object
  }
}

{
  "IsSuccess": false,
  "Message": "One or more validation errors occur",
  "Errors": [
    "Age must be 18 or older"
  ],
  "SpecificErrors": [
    {
      "Code": "Amount",
      "Description": "Over maximum"
    }
  ]
}

Schema

<details> <summary>Operation<TResponse></summary>

Properties

Methods

Static Factory Methods

</details> <details> <summary>SuccessIf.Sync</summary>

<br>Partial class Operation<TResponse>.

Methods

Static Factory Methods

</details> <details> <summary>SuccessIf.Async</summary>

<br>Asynchronous of SuccessIf.Sync.

Methods

Static Factory Methods

</details>

<details> <summary>FailureIf.Sync</summary>

<br>Partial class Operation<TResponse>.

Methods

Static Factory Methods

</details>

<details> <summary>FailureIf.Async</summary>

<br>Asynchronous of FailureIf.Sync.

Methods

Static Factory Methods

</details> <details> <summary>NoResponse</summary>

<br>The NoResponse is abstract record to define that operation will not return actual response data.

</details> <details> <summary>Error</summary>

<br>The Error record represents a error with a textual description. It is commonly used to provide human-readable error messages.

Properties

Conversion Operators

</details>

<details> <summary>SpecificError</summary>

<br>Inherits Error. <br>Representing an error with both a code and a description. It is commonly used to provide more specific error information, such as in any prop or field it happened.

Properties

</details> <details> <summary>Result</summary>

<br>Use the Result class in scenarios where you need to handle logic before passing the relevant information to the Operation<TResponse>. <br>It used as an intermediary layer that can encapsulate and communicate information between services or methods.

Properties

Methods

Static Factory Methods

</details> <details> <summary>Result<TValue></summary>

<br>Inherits Result. <br>Use Result<TValue> in case there are TValue will returned.

Properties

Methods

Conversion Operators

</details> <details> <summary>OperationSettings</summary>

<br>Provides a central place to manage and configure settings related to the serialization of Operation<TResponse> objects.

Properties

Methods

Use the OperationSettings class to configure the JSON serialization options for Operation<TResponse> and to manage custom JSON converters.

</details>

<details> <summary>OperationServiceCollectionExtensions</summary>

<br>Offers extension methods for configuring the Operation<TResponse> JSON serialization options within MVC and HTTP serialization options in ASP.NET Core.

Methods

Use the OperationServiceCollectionExtensions class when you want to configure JSON serialization options for your ASP.NET Core application, especially when working with Operation<TResponse> and related types.

</details> <details> <summary>OperationWrapper</summary>

</details>

Documentation

<details> <summary>How to validate and set errors</summary>

<br>There are bunch of ways to validate your operation (check out all methods in Schema). <br>For defining errors there are 3 ways:

• Error(string Description) record.
• SpecificError(string Code,string Description) record inherits Error(string Description).
• string implicit convert to Error(string Description).

All errors set to List<Error>.

public class SampleRequestHandler : IRequestHandler<Request,Operation<NoResponse>>
{
    // ctor and injections
    
    public async Task<Operation<NoResponse>> HandelAsync(Request request)
        => await Operation
            .SuccessIf(request.Prop == true, "the error") // way 1
            .OrFailureIf(() => request.Prop == true, new Error("the error")) // way 2
            .OrFailureIf(request.Prop == true, new SpecificError("the code", "description")) // way 3
            .AndFailureIfAsync(async () => await _service.IsGoneAsync(), op =>
            {
                //case: logic if this error occur 
                op.SetStatusCode(HttpStatusCode.Gone);
                op.Error(/* chose way you like */);
            })
            .OnSuccessAsync(op =>
            {
                // your logic
            });
}

The deference between Or / And methods is the And methods check if Operation<TResponse> is still success before execute, otherwise will skip. <br> So you may use And in case you have expensive check that you only want to check when everything else is alright. </details> <details> <summary>How to set status code</summary>

<br>You can use SetStatusCode() method to set custom status code you need. <br>No need to set the Ok & BadRequest status because will automatically set if the Errors property was empty or not.

    public Operation<NoResponse> Handel(Request request)
        => Operation<NoResponse>
            .IfSuccsus(/* passing params */)
            .OnSuccess(op =>
            {
                op.SetStatusCode(HttpStatusCode.Created);
                // logic
            });

    public Operation<NoResponse> Handel(Request request)
    {
        // logic
        retrun Operation<NoResponse>.SetStatusCode(HttpStatusCode.Continue)
    } 

</details> <details> <summary>How to set message</summary>

public class SampleRequestHandler : IRequestHandler<Request,Operation>
{
    // ctor and injections
    
    public async Task<Operation<NoResponse>> HandelAsync(Request request)
        => await Operation
            .SuccessIf(request.Prop == true, "the error") // way 1
            .OrFailureIf(request.Prop == true, new Error("the error")) // way 2
            .OrFailureIf(request.Prop == true, new SpecificError("the code", "description")) // way 3
            .AndFailureIfAsync(async () => await _service.IsGoneAsync(), op =>
            {
                // case: logic if this error occur 
                op.SetStatusCode(HttpStatusCode.Gone);
                op.Error(/* chose way you like */);
            })
+           .SetMessageOnSuccess("your succses message") // way 1
+           .SetMessageOnFailure("your failure message") // way 2
+           .SetMessage("your message") // way 3
            .OnSuccessAsync(op =>
            {
                // your logic
            });
}

This setters check if the message is null first, so like the example above the SetMessage() will not execute but the setters has optional parameter bool overwrite = false can make it execute (SetMessage("your message",true)) in your rare case. </details>

<details> <summary>How to set response</summary>

<br>You can use SetResponse() method to set the actual data of the operation or just return the response that will implicitly convert to Operation<TResponse> with 200 as status code and OK as message.

    public Operation<Response> Handel(Request request)
        => Operation<Response>
            .IfSuccsus(/* passing params */)
            .OnSuccess(op =>
            {
                // logic
                op.SetResponse(new Response(/* passing params */));
            });

    public Operation<Response> Handel(Request request)
    {
        // logic
        retrun new Response(/* passing params */);
    } 

</details>

<details> <summary>How to serialize</summary>

<br>When serialize Operation<TResponse> must use JsonSerializerOptions in OperationSettings.

JsonSerializer.Serialize(operation, OperationSettings.JsonSerializerOptions);

To configure these options for MVC and HTTP serialization in ASP.NET Core. In other words, to use them when calling ToIActionResult() or ToIResult() should use:

bulider.Services.AddOperationSerializerOptions();

You can also change the default converters or options using OperationSettings methods, check the schema here.

OperationSettings.ResetErrorConverter<IgnoreEmptyCombineErrorConverter>();

or pass to optional parameters in AddOperationSerializerOptions():

bulider.Services.AddOperationSerializerOptions(externalPropsJsonConverter: new ExternalPropsConverter());

The JsonSerializerOptions has 3 JSON converts for Operation<TResponse>, ExternalProps and Errors.

P.S: can check the available JSON converters in Custom JSON converters bellow. </details>

<details> <summary>Custom JSON converters</summary>

<br>The custom JSON converters divided to:

• Operation<TResponse>
  • OperationConverter with Factory (the default):
    • IsSuccess : serialize to boolean.
    • Message : serialize to string if is not null otherwise to name of status code.
    • Response : serialize to object if is not null otherwise ignore it.
    • Errors : serialize depends on the custom converter provided (the default: IgnoreEmptySplitErrorConverter).
    • ExtrenalProps : serialize depends on the custom converter provided (the default: IgnoreEmptyExternalPropsConverter).

    {
      "IsSuccess": true,
      "Message": "OK"
    }
    

    {
      "IsSuccess": false,
      "Message": "BadRequest",
      "Errors": [
        "the error"
      ]
    }
    

    {
      "IsSuccess": true,
      "Message": "Custom message",
      "Response": {
        // The actual response object
      }
    }
    

• ExternalProps
  • ExternalPropsConverter:
    • ExternalProps : serialize to object.

    {
      "IsSuccess": true,
      "Message": "OK",
      "ExternalProps": {
        "key": "value"
      }
    }
    

    {
      "IsSuccess": true,
      "Message": "OK",
      "ExternalProps": {}
    }
    

  • IgnoreEmptyExternalPropsConverter (the default):

    Inherits ExternalPropsConverter

    • ExternalProps: serialize to object if are not empty otherwise ignore it.

    {
      "IsSuccess": true,
      "Message": "OK",
      "ExternalProps": {
        "key": "value"
      }
    }
    

    {
      "IsSuccess": true,
       "Message": "OK"
    }
    

• Errors
  • SplitErrorConverter:
    • Errors : serialize the Error(string Description) to list of strings.
    • SpecificErrors : serialize the SpecificError(string Code,string Description) to list of objects.

    {
      "IsSuccess": false,
      "Message": "BadRequest",
      "Errors": [
        "the error"
      ],
      "SpecificErrors": [
        {
          "Code": "The Code",
          "Description": "The Description"
        }
      ]
    }
    

    {
      "IsSuccess": true,
      "Message": "OK",
      "Errors": [],
      "SpecificErrors": []
    }
    

  • CombineErrorConverter:
    • Errors : serialize to list of strings by converting SpecificError(string Code,string Description) object to $"{Code} : {Description}" string.

    {
      "IsSuccess": false,
      "Message": "BadRequest",
      "Errors": [
        "the error",
        "The Code : The Description"
      ]
    }
    

    {
      "IsSuccess": true,
      "Message": "OK",
      "Errors": []
    }
    

  • IgnoreEmptySplitErrorConverter (the default):

    Inherits SplitErrorConverter

    • Errors : serialize the Error(string Description) to list of strings if are not empty otherwise ignore it..
    • SpecificErrors : serialize the SpecificError(string Code,string Description) to list of objects if are not empty otherwise ignore it.

    {
     "IsSuccess": false,
     "Message": "BadRequest",
     "Errors": [
       "the error"
     ],
     "SpecificErrors": [
       {
         "Code": "The Code",
         "Description": "The Description"
       }
     ]
    }
    

    {
      "IsSuccess": false,
      "Message": "BadRequest",
      "Errors": [
        "the error"
      ]
    }
    

    {
      "IsSuccess": true,
      "Message": "OK"
    }
    

  • IgnoreEmptyCombineErrorConverter:

    Inherits CombineErrorConverter

    • Errors : serialize to list of strings by converting SpecificError(string Code,string Description) object to $"{Code} : {Description}" string if are not empty otherwise ignore it.

    {
      "IsSuccess": false,
      "Message": "BadRequest",
      "Errors": [
        "The Code : The Description"
      ]
    }
    

    {
      "IsSuccess": true,
      "Message": "OK"
    }
    

</details>

Real Scenarios

Let say we have

public record SingUpRequest(string Email, string Password);

public record SingUpResponse(Guid Id);

public static class Errors
{
    public static class Users
    {
        public static Error EmailAlreadyExists = "Email is already used";
    }
}

DI registration

bulider.Services.AddOperationSerializerOptions();

Logic

public class SingUpRequestHandler : IRequestHandler<SingUpRequest, Operation<SingUpResponse>>
{
    private readonly IUserService _userService;

    public SingUpRequestHandler(IuserService userService)
    {
        _userService = userService;
    }

    public async Task<Operation<SingUpResponse>> HandelAsync(SingUpRequest request) // #1
        => await Operation<SingUpResponse>
            .FailureIf(await _userService.IsEmailExistsAsync(request.Email), Errors.Users.EmailAlreadyExists)
            // .FailureIf(await userService.IsEmailExistsAsync(request.Email), new Error("Email is already used")) #2
            // .FailureIf(await userService.IsEmailExistsAsync(request.Email), "Email is already used") #3
            // .FailureIf(await userService.IsEmailExistsAsync(request.Email), new SpecificError("Email","already used")) #4
            // .FailureIf(await userService.IsEmailExistsAsync(request.Email), op => op.Error(Errors.Users.EmailAlreadyExists)) #5 and more
            .OnSuccessAsync(async op =>
            {
                var user = new User(request.Email);
                await _userService.CraeteAsync(request.Email, request.Password);
                op.SetResponse(new SingUpResponse(user.Id));
            });

    public async Task<Operation<SingUpResponse>> HandelAsync(SingUpRequest request) // #2
    {
        if (await _userService.IsEmailExistsAsync(request.Email))
        {
            return Errors.Users.EmailAlreadyExists; // #1 implicit conversion
            // return Operation<SingUpResponse>.BadRequest().Error(Errors.Users.EmailAlreadyExists); #2
        }

        var user = new User(request.Email);
        await _userService.CraeteAsync(request.Email, request.Password);
        return new SingUpResponse(user.Id); // #1 implicit conversion
        // return Operation<SingUpResponse>.Ok().SetResponse(new SingUpResponse(user.Id)); #2
    }
}

Controllers APIs

public class UsersController : BaseController
{
    [HttpPost]
    public async Task<IActionResult> SingUp([FromBody] SingUpRequest request, [FromServices] IRequestHandler<SingUpRequest, Operation<SingUpResponse>> handler)
        => await handler.HandelAsync(request).ToIActionResultAsync();
}

Minimal APIs

app.MapPost("/users/singUp", async ([FromBody] SingUpRequest request, [FromServices] IRequestHandler<SingUpRequest, Operation<SingUpResponse>> handler)
    => await handler.HandelAsync(request).ToIResultAsync());

Outputs

{
  "IsSuccess": true,
  "Message": "Ok",
  "Response": {
    "Id": "7BA82D5E-5A84-463B-80A1-34D923F9B027"
  }
}

{
  "IsSuccess": false,
  "Message": "BadRequest",
  "Errors": [
    "Email is already used"
  ]
}