defmodule Morpheus.Plugs.SnakeCaseParams do
  @moduledoc """
  A Phoenix plug that converts incoming request parameters from camelCase to snake_case.

  Automatically converts parameter keys in incoming requests to match Elixir's snake_case
  convention, letting you work with consistent naming in your Phoenix controllers.

  ## Setup

  Add to your router pipeline:

      pipeline :api do
        plug :accepts, ["json"]
        plug Morpheus.Plugs.SnakeCaseParams
      end

  ## Example

      # Incoming request with params:
      %{
        "userName" => "john_doe",
        "userProfile" => %{
          "firstName" => "John",
          "lastName" => "Doe"
        }
      }

      # Parameters in your controller:
      %{
        "user_name" => "john_doe",
        "user_profile" => %{
          "first_name" => "John",
          "last_name" => "Doe"
        }
      }

  ## Key Features

    * Recursive conversion of nested maps and lists
    * Works with both query parameters and request body
    * Converts all parameter keys while preserving values
    * Zero configuration required

  ## Important Notes

    * All camelCase keys will be converted to snake_case
    * The conversion modifies the `params` field of the connection
    * If you need to preserve certain camelCase keys, handle them separately in your controller
  """

  @doc """
  Initializes the plug with the given options.

  Called at compile time. Currently accepts options for future extensibility.

  ## Parameters

    * `opts` - A keyword list of options (currently unused)

  ## Returns

  Returns the options unchanged.
  """
  def init(opts), do: opts

  @doc """
  Converts connection parameters from camelCase to snake_case.

  Called at runtime for each request. Processes both URL query parameters
  and request body parameters.

  ## Parameters

    * `conn` - The `Plug.Conn` struct for the current connection
    * `_opts` - Options from `init/1` (currently unused)

  ## Returns

  Returns the updated connection with converted parameters.

  ## Examples

      # Basic parameter conversion
      # Given a request to "/users?userName=john"
      conn = Morpheus.Plugs.SnakeCaseParams.call(conn, [])
      conn.params
      #=> %{"user_name" => "john"}

      # Nested parameter conversion
      # Given a POST with JSON: {"userProfile": {"firstName": "John"}}
      conn = Morpheus.Plugs.SnakeCaseParams.call(conn, [])
      conn.params
      #=> %{"user_profile" => %{"first_name" => "John"}}
  """
  def call(%{params: params} = conn, _opts) do
    params = Morpheus.convert_map_keys(params, &Morpheus.camel_to_snake/1)
    %{conn | params: params}
  end
end