flop

# Flop

[![CI](https://github.com/woylie/flop/workflows/CI/badge.svg)](https://github.com/woylie/flop/actions/workflows/ci.yml) [![Hex](https://img.shields.io/hexpm/v/flop)](https://hex.pm/packages/flop) [![codecov](https://codecov.io/gh/woylie/flop/branch/main/graph/badge.svg?token=32BSY8O2LI)](https://codecov.io/gh/woylie/flop)

Flop is an Elixir library that applies filtering, ordering, and pagination to
Ecto queries.

## Features

- **Offset pagination:** with `offset`/`limit` or `page`/`page_size`
  parameters.
- **Cursor pagination:** keyset pagination with `first`/`after` and
  `last`/`before`, the same arguments Relay uses.
- **Sorting:** by several fields, each in its own direction, with nulls first or
  last.
- **Filtering:** by a list of filters, each with a field, an operator and a
  value.
- **Parameter validation:** invalid parameters become errors you can show to
  the user.
- **Allow-lists:** only fields configured as filterable or sortable can be used.
- **Join fields:** filter and sort by fields of joined tables, and only add the
  joins needed for a request.
- **Compound fields:** filter several string fields as one, for example a full
  name.
- **Custom fields:** your own filter or order expression for anything the other
  field types do not cover.
- **Relay connections:** edges, nodes and page info in Relay format.
- **[Flop Phoenix](https://hex.pm/packages/flop_phoenix):** pagination links,
  sortable tables and filter forms.

## Installation

To get started, add `flop` to your dependencies list in your project's `mix.exs`
file:

```elixir
def deps do
  [
    {:flop, "~> 0.29.1"}
  ]
end
```

Enable diagnostics in `config/dev.exs` and `config/test.exs`:

```elixir
config :flop, diagnostics: true
```

You can also configure a default repo for Flop by adding the following line to
`config/config.exs`:

```elixir
config :flop, repo: MyApp.Repo
```

If you want to avoid global configuration, you can use a configuration module
instead or pass the repo directly to the functions.

### Compatibility

This package is tested against the Elixir and OTP versions that are still
supported upstream. Older versions down to the requirement in `mix.exs` may
still work, but they are not covered by CI and not officially supported.

### Supported databases

| Database | Status                     |
| -------- | -------------------------- |
| Postgres | Supported and tested in CI |
| MySQL    | Supported and tested in CI |
| SQLite   | Supported and tested in CI |

Flop builds queries with `Ecto.Query` and only uses a couple of fragments to
bridge the gap between databases. The library might work with other Ecto
adapters, but it is only tested with the databases listed above.

Some behavior depends on the used adapter.

#### MySQL

Configure the repo with the charset and the collation your columns use, or
cursor pagination over a string column raises `Illegal mix of collations`:

```elixir
config :my_app, MyApp.Repo,
  charset: "utf8mb4",
  collat