#' Enrich a data frame with an EFSA catalogue.
#' 
#' This function takes a data frame and joins it with an EFSA catalog. The EFSA
#'   catalog must be itself a data frame.
#' 
#' @param dataframe `data.frame`. The data frame to be enriched.
#' 
#' @param catalogue `data.frame`. The data frame that contains the EFSA
#'   catalogue to be used for the enrichment. It must contain at least two
#'   columns, namely: NAME and CODE.
#' 
#' @param joinBy `character` (string). The variable to be used as the join key.
#' 
#' @param enrichedColumnName `character` (string). The name of the column added
#'   to the original data.
#'
#' @return The specified data frame enriched with the catalogue data.
#' 
#' @importFrom checkmate assert_data_frame assert_names assert_string
#' @importFrom dplyr select mutate left_join
#' @importFrom rlang .data :=
#'
#' @examples
#' dataframe_ <- iris |> dplyr::rename(CODE = Species)
#' 
#' catalogue_ <- iris |>
#'   dplyr::rename(CODE = Species) |>
#'   dplyr::mutate(NAME = "test") |>
#'   dplyr::select(CODE, NAME) |>
#'   unique()
#' 
#' enriched_ <- enrich(
#'   dataframe = dataframe_,
#'   catalogue = catalogue_,
#'   joinBy = "CODE",
#'   enrichedColumnName = "enrichedColumn")
#' 
#' @export
#' 
enrich <- function(dataframe, catalogue, joinBy, enrichedColumnName) {

  assert_data_frame(dataframe)
  assert_data_frame(catalogue)
  assert_names(names(catalogue), must.include = c("NAME", "CODE"))
  assert_string(joinBy)
  assert_string(enrichedColumnName)

  catalogue <- catalogue |>
    select("NAME", "CODE") |>
    mutate(!!joinBy := .data$CODE)

  enriched_ <- left_join(dataframe, catalogue, by = joinBy) |>
    select(!!enrichedColumnName := "NAME", names(dataframe))

  return(enriched_)
}
