feat: ✨ Code cleanup and standardization of error handling

Author: erlendellefsen

CLAUDE.md

@@ -13,6 +13,7 @@ This is **Intility.JsonApiToolkit**, a .NET library that implements the JSON:API
   - Microsoft.AspNetCore.Mvc
   - Microsoft.EntityFrameworkCore
   - Microsoft.AspNetCore.JsonPatch
+  - Microsoft.Extensions.DependencyInjection.Abstractions
   - Intility.Logging.AspNetCore
 - **Test Framework**: xUnit with Moq for mocking
 - **Documentation**: DocFX for API documentation
@@ -83,7 +84,7 @@ Documentation is built using DocFX and deployed to GitHub Pages. The documentati
 
 - **Convention-based mapping**: Properties are automatically mapped from C# PascalCase to JSON camelCase
 - **Query parameter parsing**: Standard JSON:API query syntax (`filter[field]=value`, `sort=field,-field2`, `page[number]=1&page[size]=10`, `include=relationship`)
-- **Async-first**: Main controller method `JsonApiOkAsync()` is async and works with `IQueryable<T>`
+- **Async-first**: Main controller method `JsonApiQueryAsync()` is async and works with `IQueryable<T>`
 - **Entity Framework integration**: Uses EF Core's `Include()` and query building capabilities
 - **Filter expressions**: Complex filtering with operators (eq, ne, gt, lt, contains, etc.), logical grouping, and enum support
 - **JSON column detection**: Collections and complex objects without ID properties are automatically mapped as JSON attributes instead of relationships (useful for EF Core owned entities stored as JSON columns)
@@ -137,7 +138,7 @@ Tests are organized by component:
 ### Common Patterns
 
 - Controllers should inherit from `JsonApiController`
-- Use `JsonApiOkAsync(queryable, "resourceType")` for collections with full query processing
+- Use `JsonApiQueryAsync(queryable, "resourceType")` for collections with full query processing
 - Use `JsonApiOk(entity, "resourceType")` for already-loaded entities or collections
 - Entity types should have an `Id` property (auto-detected by `EntityMapper.GetIdProperty()`)
 - Use `QueryParameters queryParams = GetJsonApiQueryParameters()` to access parsed query parameters

JsonApiToolkit/Extensions/Querying/QueryHelpers.cs

@@ -40,7 +40,7 @@ public static class QueryHelpers
         if (property != null)
             return property;
 
-        string pascalCase = StringExtensions.ToPascalCase(jsonPropertyName);
+        string pascalCase = jsonPropertyName.ToPascalCase();
         property = entityType.GetProperty(pascalCase);
 
         return property
@@ -57,7 +57,7 @@ public static class QueryHelpers
     /// <param name="value">The string value from the query parameter</param>
     /// <param name="targetType">The target property type to convert to</param>
     /// <returns>
-    /// /// The converted value, or trows an exception if conversion fails or is not supported
+    /// /// The converted value, or throws an exception if conversion fails or is not supported
     /// </returns>
     /// <remarks>
     /// Handles common primitive types (int, long, decimal, bool, DateTime, Guid, Uri, TimeSpan,

JsonApiToolkit/Extensions/StringExtensions.cs

@@ -34,7 +34,7 @@ public static string ToCamelCase(this string str)
     /// Used for converting JSON property names (camelCase) to C# property names (PascalCase).
     /// Returns the original string if it's null or empty.
     /// </remarks>
-    public static string ToPascalCase(string str)
+    public static string ToPascalCase(this string str)
     {
         if (string.IsNullOrEmpty(str))
             return str;

JsonApiToolkit/Filters/JsonApiExceptionFilter.cs

@@ -28,45 +28,65 @@ public class JsonApiExceptionFilter(ILogger<JsonApiExceptionFilter> logger) : IE
     /// </remarks>
     public void OnException(ExceptionContext context)
     {
-        var (status, title) = context.Exception switch
-        {
-            JsonApiBadRequestException => (400, "Bad Request"),
-            JsonApiNotFoundException => (404, "Not Found"),
-            JsonApiConflictException => (409, "Conflict"),
-            JsonApiUnauthorizedException => (401, "Unauthorized"),
-            JsonApiForbiddenException => (403, "Forbidden"),
-            JsonApiTooManyRequestsException => (429, "Too Many Requests"),
-            _ => (500, "Internal Server Error"),
-        };
+        int status;
+        string title;
+        JsonApiError error;
 
-        if (status == 500)
-        {
-            // Log full stack trace for unexpected errors
-            _logger.LogError(context.Exception, "An unhandled exception occurred");
-        }
-        else
+        if (context.Exception is JsonApiException jsonApiException)
         {
-            // Log only the message for handled exceptions
+            // Handle structured JSON:API exceptions
+            status = jsonApiException.StatusCode;
+            title = GetTitleForStatusCode(status);
+
+            error = new JsonApiError
+            {
+                Status = status.ToString(),
+                Title = title,
+                Detail = jsonApiException.Message,
+                Code = jsonApiException.Code,
+                Source = jsonApiException.ErrorSource,
+                Meta = jsonApiException.Meta,
+            };
+
+            // Log handled exceptions
             _logger.LogInformation(
                 "Handled JSON:API exception: {Type} - {Message}",
-                context.Exception.GetType().Name,
-                context.Exception.Message
+                jsonApiException.GetType().Name,
+                jsonApiException.Message
             );
         }
-
-        var error = new JsonApiError
+        else
         {
-            Status = status.ToString(),
-            Title = title,
-            Detail =
-                status != 500
-                    ? context.Exception.Message
-                    : "An error occurred while processing your request.",
-        };
+            // Handle unexpected exceptions
+            status = 500;
+            title = "Internal Server Error";
+
+            error = new JsonApiError
+            {
+                Status = status.ToString(),
+                Title = title,
+                Detail = "An error occurred while processing your request.",
+            };
+
+            // Log full stack trace for unexpected errors
+            _logger.LogError(context.Exception, "An unhandled exception occurred");
+        }
 
         var response = new JsonApiErrorResponse { Errors = [error] };
 
         context.Result = new ObjectResult(response) { StatusCode = status };
         context.ExceptionHandled = true;
     }
+
+    private static string GetTitleForStatusCode(int statusCode) =>
+        statusCode switch
+        {
+            400 => "Bad Request",
+            401 => "Unauthorized",
+            403 => "Forbidden",
+            404 => "Not Found",
+            409 => "Conflict",
+            429 => "Too Many Requests",
+            _ => "Error",
+        };
 }

…elpers/MapIncludePathsToClrProperties.cs …piToolkit/Helpers/EfIncludePathHelper.csJsonApiToolkit/Helpers/MapIncludePathsToClrProperties.cs renamed to JsonApiToolkit/Helpers/EfIncludePathHelper.cs JsonApiToolkit/Helpers/MapIncludePathsToClrProperties.cs renamed to JsonApiToolkit/Helpers/EfIncludePathHelper.cs

@@ -1,34 +1,236 @@
-// Supress warnings for this file
-#pragma warning disable RCS1194
-
 namespace JsonApiToolkit.Models.Errors;
 
+/// <summary>
+/// Base class for all JSON:API exceptions that provides comprehensive error information.
+/// </summary>
+/// <remarks>
+/// This base class supports the full JSON:API error object specification, allowing
+/// for detailed error reporting with structured metadata, source information, and error codes.
+/// </remarks>
+public abstract class JsonApiException : Exception
+{
+    /// <summary>
+    /// HTTP status code for this error.
+    /// </summary>
+    public int StatusCode { get; }
+
+    /// <summary>
+    /// Application-specific error code for categorizing the error.
+    /// </summary>
+    public string? Code { get; }
+
+    /// <summary>
+    /// Source information indicating where the error occurred.
+    /// </summary>
+    public ErrorSource? ErrorSource { get; }
+
+    /// <summary>
+    /// Additional metadata about the error.
+    /// </summary>
+    public Dictionary<string, object>? Meta { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiException class.
+    /// </summary>
+    /// <param name="statusCode">HTTP status code</param>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    protected JsonApiException(
+        int statusCode,
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(message, innerException)
+    {
+        StatusCode = statusCode;
+        Code = code;
+        ErrorSource = errorSource;
+        Meta = meta;
+    }
+}
+
 /// <summary>
 /// Exception representing a 400 Bad Request error.
 /// </summary>
-public class JsonApiBadRequestException(string message) : Exception(message) { }
+public class JsonApiBadRequestException : JsonApiException
+{
+    /// <summary>
+    /// Initializes a new instance of the JsonApiBadRequestException class.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    public JsonApiBadRequestException(string message)
+        : base(400, message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiBadRequestException class with detailed error information.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    public JsonApiBadRequestException(
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(400, message, code, errorSource, meta, innerException) { }
+}
 
 /// <summary>
 /// Exception representing a 404 Not Found error.
 /// </summary>
-public class JsonApiNotFoundException(string message) : Exception(message) { }
+public class JsonApiNotFoundException : JsonApiException
+{
+    /// <summary>
+    /// Initializes a new instance of the JsonApiNotFoundException class.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    public JsonApiNotFoundException(string message)
+        : base(404, message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiNotFoundException class with detailed error information.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    public JsonApiNotFoundException(
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(404, message, code, errorSource, meta, innerException) { }
+}
 
 /// <summary>
 /// Exception representing a 409 Conflict error.
 /// </summary>
-public class JsonApiConflictException(string message) : Exception(message) { }
+public class JsonApiConflictException : JsonApiException
+{
+    /// <summary>
+    /// Initializes a new instance of the JsonApiConflictException class.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    public JsonApiConflictException(string message)
+        : base(409, message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiConflictException class with detailed error information.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    public JsonApiConflictException(
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(409, message, code, errorSource, meta, innerException) { }
+}
 
 /// <summary>
 /// Exception representing a 401 Unauthorized error.
 /// </summary>
-public class JsonApiUnauthorizedException(string message) : Exception(message) { }
+public class JsonApiUnauthorizedException : JsonApiException
+{
+    /// <summary>
+    /// Initializes a new instance of the JsonApiUnauthorizedException class.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    public JsonApiUnauthorizedException(string message)
+        : base(401, message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiUnauthorizedException class with detailed error information.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    public JsonApiUnauthorizedException(
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(401, message, code, errorSource, meta, innerException) { }
+}
 
 /// <summary>
 /// Exception representing a 403 Forbidden error.
 /// </summary>
-public class JsonApiForbiddenException(string message) : Exception(message) { }
+public class JsonApiForbiddenException : JsonApiException
+{
+    /// <summary>
+    /// Initializes a new instance of the JsonApiForbiddenException class.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    public JsonApiForbiddenException(string message)
+        : base(403, message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiForbiddenException class with detailed error information.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    public JsonApiForbiddenException(
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(403, message, code, errorSource, meta, innerException) { }
+}
 
 /// <summary>
 /// Exception representing a 429 Too Many Requests error.
 /// </summary>
-public class JsonApiTooManyRequestsException(string message) : Exception(message) { }
+public class JsonApiTooManyRequestsException : JsonApiException
+{
+    /// <summary>
+    /// Initializes a new instance of the JsonApiTooManyRequestsException class.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    public JsonApiTooManyRequestsException(string message)
+        : base(429, message) { }
+
+    /// <summary>
+    /// Initializes a new instance of the JsonApiTooManyRequestsException class with detailed error information.
+    /// </summary>
+    /// <param name="message">Error message</param>
+    /// <param name="code">Application-specific error code</param>
+    /// <param name="errorSource">Source information</param>
+    /// <param name="meta">Additional metadata</param>
+    /// <param name="innerException">Inner exception</param>
+    public JsonApiTooManyRequestsException(
+        string message,
+        string? code = null,
+        ErrorSource? errorSource = null,
+        Dictionary<string, object>? meta = null,
+        Exception? innerException = null
+    )
+        : base(429, message, code, errorSource, meta, innerException) { }
+}