# DeliriumTremex

DeliriumTremex is a library for standardized
[GraphQL](http://graphql.org/)
error handling through
[Absinthe](https://hex.pm/packages/absinthe).

## Idea

All errors should be returned it the `errors` field.

Errors have the following format:

```JSON
{
  "key": "username",
  "message": "Username is already taken",
  "messages": ["is already taken", "is too short"],
  "fullMessages": ["Username is already taken", "Username is too short"],
  "index": null,
  "subErrors": null
}
```

Field explantion:

* `key` - The key the error is attached to
* `message` - A single error message associated to the key
* `messages` - List of all the non-formatted error messages associated with the key
* `fullMessages` - List of all the formatted error messages associated with the key
* `index` - If the error is a nested error, specifies the index in the array at which the error occured
* `subErrors` - Contains all sub-errors of the key

Sub-errors are errors that occur in nested data. E.g. let's say that you are
creating an article together with an array of comments. If any of those
comments fail validation their errors would be returned in the `subErrors`
array.

E.g.: If the second comment's content is too short.

```JSON
{
  "key": "comments",
  "message": "Error validating all comments",
  "messages": null,
  "fullMessages": null,
  "index": null,
  "subErrors": [
    {
      "key": "content",
      "message": "Content is too short",
      "messages": ["is too short"],
      "fullMessages": ["Content is too short"],
      "index": 1,
      "subErrors": null
    }
  ]
}
```

Note that sub-errors can also have sub-errors which allows for basically
infinite nesting. This should satisfy most use cases.

## Integrations

Currently `DeliriumTremex` integrates with:

* [Ecto](https://github.com/elixir-ecto/ecto) - Automatically formats validation errors if passed a changeset.

## Installation

Add the following to your `mix.exs` file:

```Elixir
defp deps do
  [
    {:absinthe, "~> 1.4"},
    {:delirium_tremex, "~> 0.1.0"}
  ]
end
```

If you have other dependencies just append the contents of the list above to
your dependencies.

## Usage

In your GraphQL/Absinthe schema add the following middleware to the
queries/mutations for which you want the errors to be formatted.

e.g.

```Elixir
alias DeliriumTremex.Middleware.HandleErrors

query do
  field :current_account, type: :account do
    resolve &AccountResolver.current_account/2
    middleware HandleErrors # <-- This line adds the error handeling
  end
end

mutation do
  field :register, type: :account do
    arg :username, :string
    arg :password, :string

    resolve &AccountResolver.register/2
    middleware HandleErrors # <-- This line adds the error handeling
  end
end
```
### Error builder

In your config.exs you can specify an optional error builder file to handle specific error responses.

Unhandled error responses will be formatted as unknown errors.
e.g.
```Elixir
%{
  key: :unknown_error,
  message: "Something went wrong",
  messages: ["Something went wrong"]
}
```

Example for the config.exs:
```Elixir
config :delirium_tremex,
  error_builder: YourAppName.ErrorBuilder
```

Example for the error_builder.ex:
```Elixir
defmodule YourAppName.ErrorBuilder do
  def unauthorized do
    %{
      message: "You have insufficient privileges to access this resource",
      messages: ["You have insufficient privileges to access this resource"]
    }
  end
end
```
## Contribution

For suggestions, fixes or questions, please feel free to open an issue.
Pull requests are always welcome.

## License

This project is licensed under the MIT license. It comes with absolutely no
warranty. [The license is available in this repository.](/LICENSE.txt)