Tomlify

A simple and elegant JSON to TOML converter API built with Elixir and Phoenix.

Overview

Tomlify is a lightweight web service that converts JSON data to TOML format. It provides a simple HTTP API endpoint that accepts JSON input and returns properly formatted TOML output.

Features

• Simple API: Single endpoint for JSON to TOML conversion
• Robust: Comprehensive test coverage with 40+ tests
• Type Support: Handles strings, numbers, booleans, null values, arrays, and nested objects
• TOML Tables: Automatically converts nested JSON objects to TOML tables
• Health Check: Built-in health check endpoint for monitoring
• Quality Tooling: Includes Credo, Dialyzer, and automated formatting

Installation

Prerequisites

• Elixir 1.14 or higher
• Erlang/OTP 24 or higher

Setup

1. Clone the repository:

git clone https://github.com/pivattogui/tomlify
cd tomlify

2. Install dependencies:

mix deps.get

3. Run the application:

mix phx.server

The server will start on http://localhost:4000

API Documentation

Convert JSON to TOML

Endpoint: POST /convert

Content-Type: application/json

Request Body: Any valid JSON object

Response: Plain text TOML format

Examples

Simple values

curl -X POST http://localhost:4000/convert \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "age": 30, "active": true}'

Response:

name = "John Doe"
age = 30
active = true

Nested objects (TOML tables)

curl -X POST http://localhost:4000/convert \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My App",
    "database": {
      "host": "localhost",
      "port": 5432
    }
  }'

Response:

title = "My App"

[database]
host = "localhost"
port = 5432

Arrays

curl -X POST http://localhost:4000/convert \
  -H "Content-Type: application/json" \
  -d '{"tags": ["elixir", "phoenix", "toml"], "scores": [95, 87, 92]}'

Response:

tags = ["elixir", "phoenix", "toml"]
scores = [95, 87, 92]

Complex configuration

curl -X POST http://localhost:4000/convert \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "MyApp",
    "version": "1.0.0",
    "features": ["auth", "api"],
    "server": {
      "host": "0.0.0.0",
      "port": 4000
    },
    "database": {
      "adapter": "postgresql",
      "pool_size": 10
    }
  }'

Response:

app_name = "MyApp"
version = "1.0.0"
features = ["auth", "api"]

[server]
host = "0.0.0.0"
port = 4000

[database]
adapter = "postgresql"
pool_size = 10

Health Check

Endpoint: GET /health

Response:

{
  "status": "ok",
  "service": "tomlify",
  "timestamp": "2025-11-29T12:00:00Z"
}

Development

Running Tests

Run all tests:

mix test

Code Quality

Run the complete quality check suite:

mix quality

This runs:

• Code formatting check
• Credo static analysis
• Dialyzer type checking
• All tests

Individual Quality Tools

Format code:

mix format

Run Credo:

mix credo --strict

Run Dialyzer:

mix dialyzer

Architecture

The project follows Phoenix's standard structure with a few key components:

• Tomlify.Converter - Core conversion logic
• TomlifyWeb.ConvertController - HTTP endpoint handler
• TomlifyWeb.HealthController - Health check endpoint

Conversion Logic

The converter implements a simple TOML encoder that:

1. Separates top-level values from nested objects
2. Encodes simple key-value pairs first
3. Creates TOML table sections for nested objects
4. Handles various data types (strings, numbers, booleans, arrays, null)

Project Structure

tomlify/
├── config/          # Application configuration
├── lib/
│   ├── tomlify/
│   │   ├── application.ex     # OTP application
│   │   └── converter.ex       # JSON to TOML conversion logic
│   ├── tomlify_web/
│   │   ├── controllers/
│   │   │   ├── convert_controller.ex
│   │   │   ├── health_controller.ex
│   │   │   └── error_json.ex
│   │   ├── endpoint.ex
│   │   ├── router.ex
│   │   └── telemetry.ex
│   └── tomlify.ex
├── test/            # Test files
│   ├── tomlify/
│   │   └── converter_test.exs        # Unit tests
│   └── tomlify_web/
│       └── controllers/
│           ├── convert_controller_test.exs  # Integration tests
│           └── health_test.exs
├── mix.exs          # Project dependencies
└── README.md

Testing

The project has comprehensive test coverage including:

Unit Tests (test/tomlify/converter_test.exs)

• Simple values (strings, numbers, booleans, null)
• Arrays (strings, numbers, mixed types, empty)
• Nested maps (TOML tables)
• Edge cases (empty maps, special characters)
• Error handling (invalid inputs)
• Complex scenarios (realistic configurations)

Integration Tests (test/tomlify_web/controllers/convert_controller_test.exs)

• HTTP endpoint behavior
• Content-Type handling
• Various JSON structures
• Response format validation

Total: 40 tests, 0 failures

Production Deployment

Environment Variables

• SECRET_KEY_BASE - Phoenix secret key (required in production)
• PHX_HOST - Application host (default: example.com)
• PORT - HTTP port (default: 4000)
• DNS_CLUSTER_QUERY - DNS cluster query for distributed deployments

Building a Release

MIX_ENV=prod mix release

Running in Production

PHX_SERVER=true _build/prod/rel/tomlify/bin/tomlify start

Limitations

The current implementation has the following limitations:

• Does not support deeply nested TOML tables (nested within nested)
• Does not support TOML array of tables syntax
• Does not support inline tables
• Does not escape special characters in strings (quotes, backslashes, etc.)
• Does not support TOML datetime types

These are intentional design decisions to keep the implementation simple and focused on common use cases.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

This project follows standard Elixir conventions:

• Run mix format before committing
• Ensure mix quality passes
• Add tests for new features
• Update documentation as needed

License

This project is available as open source under the terms of the MIT License.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Acknowledgments

Built with:

• Elixir - Functional programming language
• Phoenix - Web framework
• Bandit - HTTP server