README.md

# Kronky

Kronky bridges the gap between [Ecto](https://hexdocs.pm/ecto/Ecto.html) and [Absinthe GraphQL](http://absinthe-graphql.org/) by listing validation messages in a mutation payload.

The primary philosophy is that messages generated by invalid and/or unexpected user input are DATA, and should be returned as such.
On the other hand, errors made in using an api - like querying a field that doesn't exist -, are actually ERRORS and should be returned as errors.

I recommend reading [Validation and User Errors in GraphQL Mutations](https://medium.com/@tarkus/validation-and-user-errors-in-graphql-mutations-39ca79cd00bf) for more discussion on this. The excellent people behind Absinthe also approve this style from what I've seen in their slack.

## Installation

Install by adding `kronky` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [{:kronky, "~> 0.2.2"}]
end
```

## Usage

The best place to find usage examples is by looking at the test cases at the [Kronky Github](https://github.com/Ethelo/kronky) or the docs for [Kronky.Payload](https://hexdocs.pm/kronky/Kronky.Payload.html#content)

Here's a quick summary of what Kronky includes

[Kronky.ValidationMessage](https://hexdocs.pm/kronky/Kronky.ValidationMessage.html#content) structs/objects are created with all the information you'd normally be able to access through [Ecto.Changeset.traverse_errors/2](https://hexdocs.pm/ecto/Ecto.Changeset.html#traverse_errors/2).

Kronky includes a [schema](https://hexdocs.pm/kronky/Kronky.ValidationMessageTypes.html#content) definition to add ValidationMessages to your schema.

[Kronky.Payload](https://hexdocs.pm/kronky/Kronky.Payload.html#content) is middleware that takes your resolver output (either an updated object or a changeset with errors) and converts it into a Kronky Mutation Response (aka Payload).

Payloads have three fields

- `successful` - Indicates if the mutation completed successfully or not. Boolean.
- `messages` - a list of validation errors. Always empty on success
- `result` - the data object that was created/updated/deleted on success. Always nil when unsuccessful.

Finally [Kronky.TestHelper](https://hexdocs.pm/kronky/Kronky.TestHelper.html#content) has some helper methods that make it easier to write ExUnit tests against your schema.

## Caveats

Kronky **does not** currently support nested changesets/graphql objects. It'll probably die horribly if you try. If you need this feature, Kronky may not be for you.

Kronky is very very tightly coupled to Ecto internals, which is probably not a good thing.
Any change in how `Ecto.Changeset` stores/returns validation errors will likely break Kronky until I can update. Use with caution!

## Roadmap

 - Handle Nested Changesets/Objects
 - investigate identifying validations through `Ecto.Changeset.validations` instead of matching on specific error texts.
 - add tests for constraint validations (mock db?)

If you find any issues, or have suggestions for improvements, please open an issue. PRs welcome. :)

## Ethelo

Kronky is maintained and funded by [Ethelo](http://ethelo.com/). Ethelo focuses collective wisdom to find smart, practical and well-supported solutions to tough challenges. Learn about our corporate offerings at http://ethelo.com/, and our social change efforts at http://ethelo.org/.

## Why Kronky?

![Kronk translating Squirrel](https://ci.memecdn.com/1254392.gif)