Morpheus

Morpheus is an Elixir library designed to seamlessly convert between camelCase and snake_case in Phoenix projects. It provides a simple and efficient way to transform map keys, making it easier to work with different naming conventions in your APIs.

Motivation

This library was inspired by proper_case, which hasn't been updated since May 2020. Morpheus was created as a modern alternative with:

• Compatibility with latest Elixir (1.17)
• Minimal dependencies (only Jason required)
• Focus on the most common use case: converting between snake_case and camelCase
• Lightweight and simple API

Features

• Convert map keys from snake_case to camelCase and vice versa
• Handle nested maps and lists
• Preserve atom and string key types
• Seamless integration with Phoenix for automatic conversion of JSON responses
• Plug for converting incoming request parameters from camelCase to snake_case
• Efficient and lightweight

Installation

Add morpheus to your list of dependencies in mix.exs:

def deps do
  [
    {:morpheus, "~> 0.1.0"}
  ]
end

Then run mix deps.get to install the package.

Configuration

To use Morpheus for automatic conversion of your Phoenix JSON responses, add the following to your config/config.exs:

# This will already be present in your `config/config.exs` file
config :phoenix, :json_library, Jason

# Add this line below jason config
config :phoenix, :format_encoders, json: Morpheus.Config

This configuration tells Phoenix to use Morpheus for JSON encoding, which will automatically convert all outgoing JSON responses to camelCase.

Usage

Basic Usage

You can use Morpheus functions directly in your code:

iex> Morpheus.snake_to_camel("user_name")
"userName"

iex> Morpheus.camel_to_snake("firstName")
"first_name"

iex> Morpheus.snake_to_camel(:user_email)
:userEmail

iex> Morpheus.convert_map_keys(%{user_name: "John", "last_login" => "2023-01-01"}, &Morpheus.snake_to_camel/1)
%{userName: "John", "lastLogin" => "2023-01-01"}

Automatic Conversion in Phoenix

Outgoing Responses

With the configuration set up, Morpheus will automatically convert all your JSON responses. For example:

defmodule MyApp.UserController do
  use MyApp, :controller

  def show(conn, %{"id" => id}) do
    user = %{
      user_id: id,
      first_name: "John",
      last_name: "Doe",
      email_address: "[email protected]"
    }

    json(conn, user)
  end
end

The JSON response will be automatically converted to:

{
  "userId": "1",
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "[email protected]"
}

Incoming Requests

Morpheus provides a plug to automatically convert incoming request parameters from camelCase to snake_case. To use this plug, add it to your router pipeline:

defmodule MyApp.Router do
  use MyApp, :router

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

  scope "/api", MyApp do
    pipe_through :api
    # Your routes here
  end
end

This plug will convert all incoming parameters to snake_case. For example, if a client sends a request with camelCase parameters:

{
  "userId": 1,
  "firstName": "John",
  "lastName": "Doe"
}

Your controller will receive these parameters in snake_case:

def create(conn, params) do
  # params will be:
  # %{
  #   "user_id" => 1,
  #   "first_name" => "John",
  #   "last_name" => "Doe"
  # }
end

This allows you to work with snake_case in your Elixir code while maintaining camelCase in your API interface.

Advanced Usage

Handling Mixed Keys

Morpheus can handle maps with mixed key types:

mixed_map = %{
  "user_name" => "John",
  "userEmail" => "[email protected]",
  1 => "first",
  nested: %{
    "last_login" => "2023-01-01",
    preferredLanguage: "en"
  },
  user_id: 1
}

converted = Morpheus.convert_map_keys(mixed_map, &Morpheus.snake_to_camel/1)

This will convert string and atom keys while leaving integer keys unchanged.

Contributing

Contributions to Morpheus are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Write tests for your changes
4. Implement your changes
5. Run mix test to ensure all tests pass
6. Submit a pull request

Please make sure to update tests as appropriate and adhere to the Elixir style guide.

License

Morpheus is released under the MIT License. See the LICENSE file for details.

Author

Morpheus is developed and maintained by Dinesh Anbazhagan. You can reach out with any questions or feedback.

---

We hope Morpheus helps simplify your work with different naming conventions in your Phoenix projects. Happy coding!