chore: add docs

Author: MikaAK

docs/explanation/error_design_principles.md

@@ -0,0 +1,92 @@
+# Error Design Principles
+
+This document explains the design philosophy and principles behind the ErrorMessage library, helping you understand why it was created and how it can improve your application's error handling.
+
+## Why Consistent Error Handling Matters
+
+Error handling is a critical aspect of any robust application. Inconsistent error handling can lead to:
+
+1. **Unpredictable behavior**: When errors are represented differently across your application, it becomes difficult to predict how errors will be structured.
+2. **Fragile error handling**: String-based error matching is brittle and can break when error messages change.
+3. **Poor user experience**: Inconsistent error reporting leads to confusing user interfaces and API responses.
+4. **Difficult debugging**: Without structured errors, it's harder to track down the root cause of issues.
+
+ErrorMessage addresses these problems by providing a consistent structure for all errors in your application.
+
+## HTTP Status Codes as a Universal Language
+
+ErrorMessage uses HTTP status codes as the foundation for error classification. This approach has several advantages:
+
+1. **Universality**: HTTP status codes are widely understood across programming languages and platforms.
+2. **Semantic meaning**: Each status code has a well-defined meaning (e.g., 404 for "not found", 403 for "forbidden").
+3. **Standardization**: Using HTTP status codes means your error system aligns with web standards.
+4. **API compatibility**: When building web APIs, your internal error representation maps directly to HTTP responses.
+
+Even for non-web applications, HTTP status codes provide a comprehensive and well-understood taxonomy of error conditions that can be applied to many domains.
+
+## The Three-Part Error Structure
+
+ErrorMessage uses a three-part structure for errors:
+
+1. **Code**: An atom representing the error type (e.g., `:not_found`, `:internal_server_error`)
+2. **Message**: A human-readable description of what went wrong
+3. **Details**: Additional context-specific information about the error
+
+This structure provides a balance between:
+
+- **Simplicity**: The core structure is easy to understand and use
+- **Flexibility**: The details field can contain any data structure needed for your specific use case
+- **Consistency**: All errors follow the same pattern, making them predictable
+
+## Pattern Matching vs. String Matching
+
+One of the key benefits of ErrorMessage is the ability to pattern match on error codes rather than error messages:
+
+```elixir
+# Fragile approach (depends on exact message text)
+case result do
+  {:error, "User not found: " <> _} -> handle_not_found()
+  # ...
+end
+
+# Robust approach with ErrorMessage
+case result do
+  {:error, %ErrorMessage{code: :not_found}} -> handle_not_found()
+  # ...
+end
+```
+
+Pattern matching on error codes is:
+
+1. **More robust**: Changing error messages doesn't break your error handling logic
+2. **More explicit**: The intent of your code is clearer
+3. **More maintainable**: Error handling code is less likely to break over time
+
+## Serialization Considerations
+
+ErrorMessage includes built-in support for converting errors to strings (for logging) and maps (for JSON serialization). This addresses common challenges with error serialization:
+
+1. **Complex data structures**: The `ensure_json_serializable/1` function handles conversion of Elixir-specific data types (like PIDs, Date/Time structs, etc.) to JSON-compatible formats.
+2. **Request context**: When available, the request ID is automatically included in serialized errors, making it easier to correlate errors with specific requests.
+3. **Consistent output**: All errors are serialized in a consistent format, making it easier to process them in clients.
+
+## Integration with Existing Systems
+
+ErrorMessage is designed to integrate seamlessly with:
+
+- **Phoenix**: For web API error responses
+- **Logger**: For structured error logging
+- **Plug**: For HTTP status code mapping
+
+This integration-friendly design means you can adopt ErrorMessage incrementally in your application without having to rewrite existing code all at once.
+
+## When to Use ErrorMessage
+
+ErrorMessage is particularly valuable in:
+
+1. **API-driven applications**: Where consistent error responses are crucial
+2. **Microservice architectures**: Where errors might cross service boundaries
+3. **Large codebases**: Where consistency across modules is important
+4. **Long-lived applications**: Where maintainability over time is a priority
+
+While ErrorMessage can be used in any Elixir application, these scenarios highlight where it provides the most value.

docs/explanation/error_handling_in_elixir.md

@@ -0,0 +1,175 @@
+# Error Handling in Elixir and ErrorMessage
+
+This document explains how error handling typically works in Elixir and how ErrorMessage enhances the standard approach.
+
+## Traditional Error Handling in Elixir
+
+Elixir, like Erlang, follows the "Let it crash" philosophy, which encourages developers to focus on the happy path and let supervisors handle failures. However, this doesn't mean that we should ignore errors entirely. For expected errors that are part of normal program flow, Elixir provides several conventions:
+
+### Return Values
+
+The most common pattern in Elixir for handling errors is to return tagged tuples:
+
+```elixir
+# Success case
+{:ok, result}
+
+# Error case
+{:error, reason}
+```
+
+This pattern allows for easy pattern matching:
+
+```elixir
+case MyModule.some_function() do
+  {:ok, result} -> handle_success(result)
+  {:error, reason} -> handle_error(reason)
+end
+```
+
+### Exceptions
+
+Elixir also supports exceptions for exceptional circumstances:
+
+```elixir
+try do
+  some_function_that_might_raise()
+rescue
+  e in SomeError -> handle_error(e)
+end
+```
+
+However, exceptions are generally used for unexpected errors rather than as a control flow mechanism.
+
+## Limitations of Traditional Approaches
+
+While these approaches work well for simple cases, they have limitations:
+
+1. **Inconsistent Error Structure**: The `:error` tuple can contain any term as its reason, leading to inconsistent error handling across different parts of an application.
+
+2. **String-Based Error Messages**: Many libraries use simple strings as error reasons, which makes pattern matching fragile.
+
+3. **Limited Context**: Error reasons often lack detailed context about what went wrong.
+
+4. **No Standard for HTTP Integration**: When building web applications, there's no standard way to map errors to HTTP status codes.
+
+## How ErrorMessage Improves Error Handling
+
+ErrorMessage addresses these limitations by providing:
+
+### 1. Consistent Structure
+
+All errors follow the same structure:
+
+```elixir
+%ErrorMessage{
+  code: :error_code,
+  message: "Human-readable message",
+  details: additional_context
+}
+```
+
+This consistency makes error handling more predictable across your application.
+
+### 2. Code-Based Pattern Matching
+
+Instead of matching on error messages (which might change), you can match on error codes:
+
+```elixir
+case result do
+  {:ok, value} -> handle_success(value)
+  {:error, %ErrorMessage{code: :not_found}} -> handle_not_found()
+  {:error, %ErrorMessage{code: :unauthorized}} -> handle_unauthorized()
+  {:error, _} -> handle_other_errors()
+end
+```
+
+### 3. Rich Context
+
+The `details` field can contain any data structure, allowing you to provide rich context about what went wrong:
+
+```elixir
+ErrorMessage.not_found("User not found", %{
+  user_id: id,
+  search_params: params,
+  timestamp: DateTime.utc_now()
+})
+```
+
+### 4. HTTP Integration
+
+ErrorMessage is built around HTTP status codes, making it easy to integrate with web applications:
+
+```elixir
+def render_error(conn, %ErrorMessage{} = error) do
+  conn
+  |> put_status(ErrorMessage.http_code(error))
+  |> json(ErrorMessage.to_jsonable_map(error))
+end
+```
+
+## ErrorMessage in the Elixir Ecosystem
+
+ErrorMessage complements other Elixir error handling approaches:
+
+### With Standard Libraries
+
+ErrorMessage works alongside standard Elixir patterns:
+
+```elixir
+def find_user(id) do
+  case Repo.get(User, id) do
+    nil -> {:error, ErrorMessage.not_found("User not found", %{user_id: id})}
+    user -> {:ok, user}
+  end
+end
+```
+
+### With Ecto
+
+You can convert Ecto changeset errors to ErrorMessage:
+
+```elixir
+def create_user(params) do
+  %User{}
+  |> User.changeset(params)
+  |> Repo.insert()
+  |> case do
+    {:ok, user} -> 
+      {:ok, user}
+    {:error, changeset} ->
+      errors = Ecto.Changeset.traverse_errors(changeset, &translate_error/1)
+      {:error, ErrorMessage.unprocessable_entity("Invalid user data", errors)}
+  end
+end
+```
+
+### With Phoenix
+
+ErrorMessage integrates well with Phoenix for API error handling:
+
+```elixir
+defmodule MyApp.FallbackController do
+  use Phoenix.Controller
+  
+  def call(conn, {:error, %ErrorMessage{} = error}) do
+    conn
+    |> put_status(ErrorMessage.http_code(error))
+    |> put_view(MyApp.ErrorView)
+    |> render("error.json", error: error)
+  end
+end
+```
+
+## When to Use ErrorMessage
+
+ErrorMessage is particularly valuable in:
+
+1. **API-driven applications**: Where consistent error responses are crucial
+2. **Complex business logic**: Where detailed error context helps with debugging
+3. **Cross-module boundaries**: Where consistent error handling improves maintainability
+4. **Web applications**: Where mapping errors to HTTP status codes is important
+
+Most systems will benefit from ErrorMessage providing significant benefits for applications that need structured, consistent error handling, as well as benefitting pattern matching on error codes.
+
+For further reading checkout this [blog post](https://learn-elixir.dev/blogs/safer-error-systems-in-elixir)