lib/flop.ex

defmodule Flop do
  @moduledoc """
  Flop is a helper library for filtering, ordering and pagination with Ecto.

  ## Usage

  The simplest way of using this library is just to use
  `Flop.validate_and_run/3` and `Flop.validate_and_run!/3`. Both functions
  take a queryable and a parameter map, validate the parameters, run the query
  and return the query results and the meta information.

      iex> Flop.Repo.insert_all(MyApp.Pet, [
      ...>   %{name: "Harry", age: 4, species: "C. lupus"},
      ...>   %{name: "Maggie", age: 1, species: "O. cuniculus"},
      ...>   %{name: "Patty", age: 2, species: "C. aegagrus"}
      ...> ])
      iex> params = %{order_by: ["name", "age"], page: 1, page_size: 2}
      iex> {:ok, {results, meta}} =
      ...>   Flop.validate_and_run(
      ...>     MyApp.Pet,
      ...>     params,
      ...>     repo: Flop.Repo
      ...>   )
      iex> Enum.map(results, & &1.name)
      ["Harry", "Maggie"]
      iex> meta.total_count
      3
      iex> meta.total_pages
      2
      iex> meta.has_next_page?
      true

  Under the hood, these functions just call `Flop.validate/2` and `Flop.run/3`,
  which in turn calls `Flop.all/3` and `Flop.meta/3`. If you need finer control
  about if and when to execute each step, you can call those functions directly.

  See `Flop.Meta` for descriptions of the meta fields.

  ## Global configuration

  You can set some global options like the default Ecto repo via the application
  environment. All global options can be overridden by passing them directly to
  the functions or configuring the options for a schema module via
  `Flop.Schema`.

      import Config

      config :flop, repo: MyApp.Repo

  See `t:Flop.option/0` for a description of all available options.

  ## Config modules

  Instead of setting global options in the application environment, you can also
  create a Flop config module. This is especially useful in an umbrella
  application, or if you have multiple Repos.

  ```elixir
  defmodule MyApp.Flop do
    use Flop, repo: MyApp.Repo, default_limit: 25
  end
  ```

  > #### `use Flop` {: .info}
  >
  > When you `use Flop`, the Flop module will define wrapper functions around
  > all of the `Flop` functions that take a query, the Flop parameters, and
  > options as arguments. The options passed to `use Flop` will be used as
  > default options in all the wrapper functions, but you can still override
  > them.

  The wrapped functions are:

  - `Flop.all/3`
  - `Flop.count/3`
  - `Flop.filter/3`
  - `Flop.meta/3`
  - `Flop.order_by/3`
  - `Flop.paginate/3`
  - `Flop.query/3`
  - `Flop.run/3`
  - `Flop.validate_and_run/3`
  - `Flop.validate_and_run!/3`

  So instead of using `Flop.validate_and_run/3`, you would call
  `MyApp.Flop.validate_and_run/3`.

  If you have both a config module and a global application config, Flop will
  fall back to the application config if an option is not set.

  See `t:Flop.option/0` for a description of all available options.

  ## Schema options

  You can set some options for a schema by deriving `Flop.Schema`. The options
  are evaluated at the validation step.

      defmodule Pet do
        use Ecto.Schema

        @derive {Flop.Schema,
                 filterable: [:name, :species],
                 sortable: [:name, :age],
                 default_limit: 20,
                 max_limit: 100}

        schema "pets" do
          field :name, :string
          field :age, :integer
          field :species, :string
          field :social_security_number, :string
        end
      end

  You need to pass the schema to `Flop.validate/2` or any function that
  includes the validation step with the `:for` option.

      iex> params = %{"order_by" => ["name", "age"], "limit" => 5}
      iex> {:ok, flop} = Flop.validate(params, for: MyApp.Pet)
      iex> flop.limit
      5

      iex> params = %{"order_by" => ["name", "age"], "limit" => 10_000}
      iex> {:error, meta} = Flop.validate(params, for: MyApp.Pet)
      iex> [limit: [{msg, _}]] = meta.errors
      iex> msg
      "must be less than or equal to %{number}"

      iex> params = %{"order_by" => ["name", "age"], "limit" => 10_000}
      iex> {:error, %Flop.Meta{} = meta} =
      ...>   Flop.validate_and_run(
      ...>     MyApp.Pet,
      ...>     params,
      ...>     for: MyApp.Pet
      ...>   )
      iex> [limit: [{msg, _}]] = meta.errors
      iex> msg
      "must be less than or equal to %{number}"

  ## Ordering

  To add an ordering clause to a query, you need to set the `:order_by` and
  optionally the `:order_directions` parameter. `:order_by` should be the list
  of fields, while `:order_directions` is a list of `t:Flop.order_direction/0`.
  `:order_by` and `:order_directions` are zipped when generating the `ORDER BY`
  clause. If no order directions are given, `:asc` is used as default.

      iex> params = %{
      ...>   "order_by" => ["name", "age"],
      ...>   "order_directions" => ["asc", "desc"]
      ...> }
      iex> {:ok, flop} = Flop.validate(params)
      iex> flop.order_by
      [:name, :age]
      iex> flop.order_directions
      [:asc, :desc]

  Flop uses these two fields instead of a keyword list, so that the order
  instructions can be easily passed in a query string.

  ## Pagination

  For queries using `OFFSET` and `LIMIT`, you have the choice between
  page-based pagination parameters:

      %{page: 5, page_size: 20}

  and offset-based pagination parameters:

      %{offset: 100, limit: 20}

  For cursor-based pagination, you can either use `:first`/`:after` or
  `:last`/`:before`. You also need to pass the `:order_by` parameter or set a
  default order for the schema via `Flop.Schema`.

      iex> Flop.Repo.insert_all(MyApp.Pet, [
      ...>   %{name: "Harry", age: 4, species: "C. lupus"},
      ...>   %{name: "Maggie", age: 1, species: "O. cuniculus"},
      ...>   %{name: "Patty", age: 2, species: "C. aegagrus"}
      ...> ])
      iex>
      iex> # forward (first/after)
      iex>
      iex> params = %{first: 2, order_by: [:species, :name]}
      iex> {:ok, {results, meta}} = Flop.validate_and_run(MyApp.Pet, params)
      iex> Enum.map(results, & &1.name)
      ["Patty", "Harry"]
      iex> meta.has_next_page?
      true
      iex> end_cursor = meta.end_cursor
      "g3QAAAACdwRuYW1lbQAAAAVIYXJyeXcHc3BlY2llc20AAAAIQy4gbHVwdXM="
      iex> params = %{first: 2, after: end_cursor, order_by: [:species, :name]}
      iex> {:ok, {results, meta}} = Flop.validate_and_run(MyApp.Pet, params)
      iex> Enum.map(results, & &1.name)
      ["Maggie"]
      iex> meta.has_next_page?
      false
      iex>
      iex> # backward (last/before)
      iex>
      iex> params = %{last: 2, order_by: [:species, :name]}
      iex> {:ok, {results, meta}} = Flop.validate_and_run(MyApp.Pet, params)
      iex> Enum.map(results, & &1.name)
      ["Harry", "Maggie"]
      iex> meta.has_previous_page?
      true
      iex> start_cursor = meta.start_cursor
      "g3QAAAACdwRuYW1lbQAAAAVIYXJyeXcHc3BlY2llc20AAAAIQy4gbHVwdXM="
      iex> params = %{last: 2, before: start_cursor, order_by: [:species, :name]}
      iex> {:ok, {results, meta}} = Flop.validate_and_run(MyApp.Pet, params)
      iex> Enum.map(results, & &1.name)
      ["Patty"]
      iex> meta.has_previous_page?
      false

  By default, it is assumed that the query result is a list of maps or structs.
  If your query returns a different data structure, you can pass the
  `:cursor_value_func` option to retrieve the cursor values. See
  `t:Flop.option/0` and `Flop.Cursor` for more information.

  You can restrict which pagination types are available. See `t:Flop.option/0`
  for details.

  ## Filters

  Filters can be passed as a list of maps. It is recommended to define the
  filterable fields for a schema using `Flop.Schema`.

      iex> Flop.Repo.insert_all(MyApp.Pet, [
      ...>   %{name: "Harry", age: 4, species: "C. lupus"},
      ...>   %{name: "Maggie", age: 1, species: "O. cuniculus"},
      ...>   %{name: "Patty", age: 2, species: "C. aegagrus"}
      ...> ])
      iex>
      iex> params = %{filters: [%{field: :name, op: :=~, value: "Mag"}]}
      iex> {:ok, {results, meta}} = Flop.validate_and_run(MyApp.Pet, params)
      iex> meta.total_count
      1
      iex> [pet] = results
      iex> pet.name
      "Maggie"

  See `t:Flop.Filter.op/0` for a list of all available filter operators.

  ## GraphQL and Relay

  The parameters used for cursor-based pagination follow the Relay
  specification, so you can just pass the arguments you get from the client on
  to Flop.

  `Flop.Relay` can convert the query results returned by
  `Flop.validate_and_run/3` into `Edges` and `PageInfo` formats required for
  Relay connections.

  For example, if you have a context module like this:

      defmodule MyApp.Flora
        import Ecto.query, warn: false

        alias MyApp.Flora.Plant

        def list_plants_by_continent(%Continent{} = continent, %{} = args) do
          Plant
          |> where(continent_id: ^continent.id)
          |> Flop.validate_and_run(args, for: Plant)
        end
      end

  Then your Absinthe resolver for the `plants` connection may look something
  like this:

      def list_plants(args, %{source: %Continent{} = continent}) do
        with {:ok, result} <-
               Flora.list_plants_by_continent(continent, args) do
          {:ok, Flop.Relay.connection_from_result(result)}
        end
      end
  """
  use Ecto.Schema

  alias Ecto.Changeset
  alias Ecto.Queryable
  alias Flop.Adapter
  alias Flop.Cursor
  alias Flop.CustomTypes.ExistingAtom
  alias Flop.Filter
  alias Flop.Meta
  alias Flop.NimbleSchemas

  require Ecto.Query
  require Logger

  @default_opts [default_limit: 50, max_limit: 1000]

  defmacro __using__(opts) do
    opts =
      NimbleSchemas.validate!(
        opts,
        :backend_option,
        Flop,
        __CALLER__.module
      )

    {legacy_adapter_opts, opts} = Keyword.split(opts, [:query_opts, :repo])
    adapter = Keyword.fetch!(opts, :adapter)

    adapter_opts =
      Keyword.merge(legacy_adapter_opts, Keyword.fetch!(opts, :adapter_opts))

    adapter_opts =
      adapter.init_backend_opts(opts, adapter_opts, __CALLER__.module)

    opts = Keyword.put(opts, :adapter_opts, adapter_opts)

    quote do
      @doc false
      def __flop_options__, do: unquote(opts)

      unquote(backend_functions(__CALLER__.module))
      unquote(validate_functions(__CALLER__.module))
    end
  end

  defp backend_functions(backend_module) do
    for func <- [
          :all,
          :count,
          :filter,
          :meta,
          :order_by,
          :paginate,
          :query,
          :run,
          :validate_and_run,
          :validate_and_run!
        ] do
      quote do
        def unquote(func)(q, map_or_flop, opts \\ []) do
          apply(Flop, unquote(func), [
            q,
            map_or_flop,
            Keyword.put(opts, :backend, unquote(backend_module))
          ])
        end
      end
    end
  end

  defp validate_functions(backend_module) do
    for func <- [:validate, :validate!] do
      quote do
        def unquote(func)(map_or_flop, opts \\ []) do
          apply(Flop, unquote(func), [
            map_or_flop,
            Keyword.put(opts, :backend, unquote(backend_module))
          ])
        end
      end
    end
  end

  @typedoc """
  These options can be passed to most functions or configured via the
  application environment.

  ## Options

  ### General

  - `:for` - The Ecto schema module for validation and query building.
    `Flop.Schema` must be derived for this module.
  - `:cursor_value_func` - A function used to extract the cursor value from a
    record. It takes the record and the list of fields used in the `ORDER BY`
    clause as arguments, and returns a map with the order fields as keys and the
    corresponding record values as values. Default is
    `Flop.Cursor.get_cursor_from_node/2`.
  - `:replace_invalid_params` - If set to `true`, invalid parameters are
    replaced with default values or removed instead of causing errors. Default
    is `false`.

  ### Defaults

  - `:default_limit` - The default limit for queries. Used when no specific
    limit is set in the parameters or schema.  Set to `false` to not set any
    default limit. Default is `50`.
  - `:default_order` - The default ordering for a query when no order is
    specified in the parameters, or if ordering is disabled. Can be set in the
    schema or in the options passed to the query functions.
  - `:default_pagination_type` - The default pagination type when it cannot be
    inferred from the parameters.
  - `:max_limit` - The maximum limit for queries. Used when no maximum limit is
    set in the parameters or schema. Set to `false` to not set any maximum
    limit. Default is `1000`.

  ### Modifying counts

  - `:count_query` - A separate base query for counting. Can only be passed as
    an option to one of the query functions. See `Flop.validate_and_run/3` and
    `Flop.count/3`.
  - `:count` - A precomputed count. Useful when the count is already known.

  ### Disabling features

  - `:filtering` (boolean) - Enables or disables filtering. When set to `false`,
    filter parameters are ignored.
  - `:ordering` (boolean) - Enables or disables ordering. When set to `false`,
    order parameters are ignored, but the default order is still applied.
  - `:pagination` (boolean) - Enables or disables pagination. When set to
    `false`, pagination parameters are ignored.
  - `:pagination_types` - The allowed pagination types. Parameters for
    disallowed pagination types will not be cast. By default, all types are
    allowed. See also `t:Flop.pagination_type/0`.

  ### Additional options

  - `:extra_opts` (keyword list) - Extra options for custom fields.
  - `:adapter_opts` - Adapter-specific options. For backward compatibility,
    options for the Ecto adapter can be set directly at the root level.

  ## Look-up order

  Options are looked up in the following order:

  1. Function arguments
  2. Schema-level options
  3. Module-level options in the config (backend) module
  4. Global options in the application environment
  5. Library defaults
  """
  @type option ::
          {:cursor_value_func, (any, [atom] -> map)}
          | {:default_limit, pos_integer | false}
          | {:default_order, default_order()}
          | {:default_pagination_type, pagination_type() | false}
          | {:filtering, boolean}
          | {:for, module}
          | {:max_limit, pos_integer | false}
          | {:count_query, Ecto.Queryable.t()}
          | {:count, integer}
          | {:ordering, boolean}
          | {:pagination, boolean}
          | {:pagination_types, [pagination_type()]}
          | {:replace_invalid_params, boolean}
          | {:extra_opts, Keyword.t()}
          | {:adapter_opts, adapter_option()}
          | adapter_option()
          | private_option()

  @typep private_option ::
           {:adapter, module} | {:backend, module}

  @doc """
  Options specific to the Ecto adapter.

  - `:repo` - The Ecto Repo module used for database queries.
  - `:query_opts` - Options passed to the `Ecto.Repo` query functions. Refer to
    the Ecto documentation for `c:Ecto.Repo.all/2`, `c:Ecto.Repo.aggregate/3`,
    and the ["Shared Options"](https://hexdocs.pm/ecto/Ecto.Repo.html#module-shared-options)
    section of `Ecto.Repo`.
  """
  @type adapter_option :: {:repo, module} | {:query_opts, Keyword.t()}

  @typedoc """
  A map with the order fields and the order directions.

  Each atom in `:order_by` corresponds to a field by which the data is ordered.
  The list of order fields and order directions is zipped when the parameters
  are applied. If no order directions are given or the list of order directions
  is shorter than the list of order fields, `:asc` is used as a default order
  direction.
  """
  @type default_order ::
          %{
            required(:order_by) => [atom],
            optional(:order_directions) => [order_direction()]
          }

  @typedoc """
  Represents the supported order direction values.
  """
  @type order_direction ::
          :asc
          | :asc_nulls_first
          | :asc_nulls_last
          | :desc
          | :desc_nulls_first
          | :desc_nulls_last

  @typedoc """
  Represents the pagination type.

  - `:offset` - pagination using the `offset` and `limit` parameters
  - `:page` - pagination using the `page` and `page_size` parameters
  - `:first` - cursor-based pagination using the `first` and `after` parameters
  - `:last` - cursor-based pagination using the `last` and `before` parameters
  """
  @type pagination_type :: :offset | :page | :first | :last

  @typedoc """
  Represents the query parameters for filtering, ordering and pagination.

  ### Fields

  - `after`: Used for cursor-based pagination. Must be used with `first` or a
    default limit.
  - `before`: Used for cursor-based pagination. Must be used with `last` or a
    default limit.
  - `decoded_cursor`: Used internally to hold on to the decoded cursor between
    validation and query execution. Value is discarded when meta is built.
  - `limit`, `offset`: Used for offset-based pagination.
  - `first`: Used for cursor-based pagination. Can be used alone to begin
    pagination from the start or in conjunction with `after`.
  - `last`: Used for cursor-based pagination.
  - `page`, `page_size`: Used for offset-based pagination as an alternative to
    `offset` and `limit`.
  - `order_by`: List of fields to order by. Fields can be restricted by
    deriving `Flop.Schema` in your Ecto schema.
  - `order_directions`: List of order directions applied to the fields defined
    in `order_by`. If empty or the list is shorter than the `order_by` list,
    `:asc` will be used as a default for each missing order direction.
  - `filters`: List of filters, see `t:Flop.Filter.t/0`. Each `Filter.t()`
    represents a filter operation on a specific field.

  Note: Pagination fields are mutually exclusive.
  """
  @type t :: %__MODULE__{
          after: String.t() | nil,
          before: String.t() | nil,
          decoded_cursor: map | nil,
          filters: [Filter.t()] | nil,
          first: pos_integer | nil,
          last: pos_integer | nil,
          limit: pos_integer | nil,
          offset: non_neg_integer | nil,
          order_by: [atom | String.t()] | nil,
          order_directions: [order_direction()] | nil,
          page: pos_integer | nil,
          page_size: pos_integer | nil
        }

  @primary_key false
  embedded_schema do
    field :after, :string
    field :before, :string
    field :first, :integer
    field :last, :integer
    field :limit, :integer
    field :offset, :integer
    field :order_by, {:array, ExistingAtom}

    field :order_directions, {:array, Ecto.Enum},
      values: [
        :asc,
        :asc_nulls_first,
        :asc_nulls_last,
        :desc,
        :desc_nulls_first,
        :desc_nulls_last
      ]

    field :page, :integer
    field :page_size, :integer
    field :decoded_cursor, :map

    embeds_many :filters, Filter
  end

  @doc """
  Adds clauses for filtering, ordering and pagination to a
  `t:Ecto.Queryable.t/0`.

  The parameters are represented by the `t:Flop.t/0` type. Any `nil` values
  will be ignored.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.

  ## Examples

      iex> flop = %Flop{limit: 10, offset: 19}
      iex> Flop.query(MyApp.Pet, flop)
      #Ecto.Query<from p0 in MyApp.Pet, limit: ^10, offset: ^19>

  Or enhance an already defined query:

      iex> require Ecto.Query
      iex> flop = %Flop{limit: 10}
      iex> q = Ecto.Query.where(MyApp.Pet, species: "dog")
      iex> Flop.query(q, flop, for: MyApp.Pet)
      #Ecto.Query<from p0 in MyApp.Pet, where: p0.species == \"dog\", limit: ^10>

  Note that when using cursor-based pagination, the applied limit will be
  `first + 1` or `last + 1`. The extra record is removed by `Flop.run/3`.

  Also note that you will need to pass the `for` option in order for Flop to be
  able to find your join, compound, alias and custom field configuration.
  """
  @doc group: :queries
  @spec query(Queryable.t(), Flop.t(), [option()]) :: Queryable.t()
  def query(q, %Flop{} = flop, opts \\ []) do
    q
    |> filter(flop, opts)
    |> order_by(flop, opts)
    |> paginate(flop, opts)
  end

  @doc """
  Applies the given Flop to the given queryable and returns all matchings
  entries.

      iex> Flop.all(MyApp.Pet, %Flop{}, repo: Flop.Repo)
      []

  You can also configure a default repo in your config files:

      config :flop, repo: MyApp.Repo

  This allows you to omit the third argument:

      iex> Flop.all(MyApp.Pet, %Flop{}, for: MyApp.Pet)
      []

  Note that when using cursor-based pagination, the applied limit will be
  `first + 1` or `last + 1`. The extra record is removed by `Flop.run/3`, but
  not by this function.

  Also note that you will need to pass the `for` option in order for Flop to be
  able to find your join, compound, alias and custom field configuration.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.
  """
  @doc since: "0.6.0"
  @doc group: :queries
  @spec all(Queryable.t(), Flop.t(), [option()]) :: [any]
  def all(q, %Flop{} = flop, opts \\ []) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)

    q
    |> query(flop, opts)
    |> adapter.list(opts)
  end

  @doc """
  Applies the given Flop to the given queryable, retrieves the data and the
  meta data.

  This function does _not_ validate or apply default parameters to the given
  flop parameters. You can validate the parameters with `Flop.validate/2` or
  `Flop.validate!/2`, or you can use `Flop.validate_and_run/3` or
  `Flop.validate_and_run!/3` instead of this function.

  Note that you will need to pass the `for` option to both to `validate/2`,
  `validate!/2` and `run/3`. Otherwise, Flop would not know how to find your
  field configuration (join fields, alias fields, custom fields, compound
  fields).

      iex> opts = [for: MyApp.Pet]
      iex> flop = Flop.validate!(%{}, opts)
      iex> {data, meta} = Flop.run(MyApp.Pet, flop, opts)
      iex> data == []
      true
      iex> match?(%Flop.Meta{}, meta)
      true

  See the documentation for `Flop.validate_and_run/3` for supported options.
  """
  @doc since: "0.6.0"
  @doc group: :queries
  @spec run(Queryable.t(), Flop.t(), [option()]) :: {[any], Meta.t()}
  def run(q, flop, opts \\ [])

  def run(
        q,
        %Flop{
          before: nil,
          first: first,
          last: nil
        } = flop,
        opts
      )
      when is_integer(first) do
    results = all(q, flop, opts)
    {Enum.take(results, first), meta(results, flop, opts)}
  end

  def run(
        q,
        %Flop{
          after: nil,
          first: nil,
          last: last
        } = flop,
        opts
      )
      when is_integer(last) do
    results = all(q, flop, opts)

    page_data =
      results
      |> Enum.take(last)
      |> Enum.reverse()

    {page_data, meta(results, flop, opts)}
  end

  def run(q, %Flop{} = flop, opts) do
    {all(q, flop, opts), meta(q, flop, opts)}
  end

  @doc """
  Validates the given flop parameters and retrieves the data and meta data on
  success.

      iex> {:ok, {[], %Flop.Meta{}}} =
      ...>   Flop.validate_and_run(MyApp.Pet, %Flop{}, for: MyApp.Pet)
      iex> {:error, %Flop.Meta{} = meta} =
      ...>   Flop.validate_and_run(MyApp.Pet, %Flop{limit: -1})
      iex> meta.errors
      [
        limit: [
          {"must be greater than %{number}",
           [validation: :number, kind: :greater_than, number: 0]}
        ]
      ]

  ## Options

  - `for`: Passed to `Flop.validate/2`. Also used to look up the join, alias,
    compound and custom field configuration.
  - `repo`: The `Ecto.Repo` module. Required if no default repo is configured.
  - `cursor_value_func`: An arity-2 function to be used to retrieve an
    unencoded cursor value from a query result item and the `order_by` fields.
    Defaults to `Flop.Cursor.get_cursor_from_node/2`.
  - `count_query`: Lets you override the base query for counting, e.g. if you
    don't want to include unnecessary joins. The filter parameters are applied
    to the given query. See also `Flop.count/3`.
  """
  @doc since: "0.6.0"
  @doc group: :queries
  @spec validate_and_run(Queryable.t(), map | Flop.t(), [option()]) ::
          {:ok, {[any], Meta.t()}} | {:error, Meta.t()}
  def validate_and_run(q, map_or_flop, opts \\ []) do
    with {:ok, flop} <- validate(map_or_flop, opts) do
      {:ok, run(q, flop, opts)}
    end
  end

  @doc """
  Same as `Flop.validate_and_run/3`, but raises on error.
  """
  @doc since: "0.6.0"
  @doc group: :queries
  @spec validate_and_run!(Queryable.t(), map | Flop.t(), [option()]) ::
          {[any], Meta.t()}
  def validate_and_run!(q, map_or_flop, opts \\ []) do
    flop = validate!(map_or_flop, opts)
    run(q, flop, opts)
  end

  @doc """
  Returns the total count of entries matching the filter conditions of the
  Flop.

  The pagination and ordering option are disregarded.

      iex> Flop.count(MyApp.Pet, %Flop{}, repo: Flop.Repo)
      0

  You can also configure a default repo in your config files:

      config :flop, repo: MyApp.Repo

  This allows you to omit the third argument:

      iex> Flop.count(MyApp.Pet, %Flop{})
      0

  You can override the default query by passing the `:count_query` option. This
  doesn't make a lot of sense when you use `count/3` directly, but allows you to
  optimize the count query when you use one of the `run/3`,
  `validate_and_run/3` and `validate_and_run!/3` functions.

      query = join(Pet, :left, [p], o in assoc(p, :owner))
      count_query = Pet
      count(query, %Flop{}, count_query: count_query, for: Pet)

  The filter parameters of the given Flop are applied to the custom count query.

  If for some reason you already have the count, you can pass it as the `:count`
  option.

      count(query, %Flop{}, count: 42, for: Pet)

  If you pass both the `:count` and the `:count_query` options, the `:count`
  option will take precedence.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.

  Note that you will need to pass the `for` option in order for Flop to be
  able to find your join, compound, alias and custom field configuration.
  """
  @doc since: "0.6.0"
  @doc group: :queries
  @spec count(Queryable.t(), Flop.t(), [option()]) :: non_neg_integer
  def count(q, %Flop{} = flop, opts \\ []) do
    if count = opts[:count] do
      count
    else
      q =
        if count_query = opts[:count_query] do
          filter(count_query, flop, opts)
        else
          filter(q, flop, opts)
        end

      adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
      adapter.count(q, opts)
    end
  end

  @doc """
  Returns meta information for the given query and flop that can be used for
  building the pagination links.

      iex> Flop.meta(MyApp.Pet, %Flop{limit: 10}, repo: Flop.Repo)
      %Flop.Meta{
        current_offset: 0,
        current_page: 1,
        end_cursor: nil,
        flop: %Flop{limit: 10},
        has_next_page?: false,
        has_previous_page?: false,
        next_offset: nil,
        next_page: nil,
        opts: [repo: Flop.Repo],
        page_size: 10,
        previous_offset: nil,
        previous_page: nil,
        start_cursor: nil,
        total_count: 0,
        total_pages: 0
      }

  The function returns both the current offset and the current page, regardless
  of the pagination type. If the offset lies in between pages, the current page
  number is rounded up. This means that it is possible that the values for
  `current_page` and `next_page` can be identical. This can only occur if you
  use offset/limit based pagination with arbitrary offsets, but in that case,
  you will use the `previous_offset`, `current_offset` and `next_offset` values
  to render the pagination links anyway, so this shouldn't be a problem.

  Unless cursor-based pagination is used, this function will run a query to
  figure get the total count of matching records.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.
  """
  @doc since: "0.6.0"
  @doc group: :queries
  @spec meta(Queryable.t() | [any], Flop.t(), [option()]) :: Meta.t()
  def meta(query_or_results, flop, opts \\ [])

  def meta(
        results,
        %Flop{
          first: first,
          order_by: order_by,
          before: nil,
          last: nil
        } = flop,
        opts
      )
      when is_list(results) and is_integer(first) do
    {start_cursor, end_cursor} =
      results
      |> Enum.take(first)
      |> Cursor.get_cursors(order_by, opts)

    %Meta{
      backend: opts[:backend],
      flop: %{flop | decoded_cursor: nil},
      start_cursor: start_cursor,
      end_cursor: end_cursor,
      has_next_page?: length(results) > first,
      has_previous_page?: !is_nil(flop.after),
      opts: opts,
      page_size: first,
      schema: opts[:for]
    }
  end

  def meta(
        results,
        %Flop{
          after: nil,
          first: nil,
          order_by: order_by,
          last: last
        } = flop,
        opts
      )
      when is_list(results) and is_integer(last) do
    {start_cursor, end_cursor} =
      results
      |> Enum.take(last)
      |> Enum.reverse()
      |> Cursor.get_cursors(order_by, opts)

    %Meta{
      backend: opts[:backend],
      flop: %{flop | decoded_cursor: nil},
      start_cursor: start_cursor,
      end_cursor: end_cursor,
      has_next_page?: !is_nil(flop.before),
      has_previous_page?: length(results) > last,
      opts: opts,
      page_size: last,
      schema: opts[:for]
    }
  end

  def meta(q, %Flop{} = flop, opts) do
    total_count = count(q, flop, opts)
    page_size = flop.page_size || flop.limit
    total_pages = get_total_pages(total_count, page_size)
    current_offset = get_current_offset(flop)
    current_page = get_current_page(flop, total_pages)

    {has_previous_page?, previous_offset, previous_page} =
      get_previous(current_offset, current_page, page_size)

    {has_next_page?, next_offset, next_page} =
      get_next(
        current_offset,
        current_page,
        page_size,
        total_count,
        total_pages
      )

    %Meta{
      backend: opts[:backend],
      current_offset: current_offset,
      current_page: current_page,
      flop: %{flop | decoded_cursor: nil},
      has_next_page?: has_next_page?,
      has_previous_page?: has_previous_page?,
      next_offset: next_offset,
      next_page: next_page,
      opts: opts,
      page_size: page_size,
      previous_offset: previous_offset,
      previous_page: previous_page,
      schema: opts[:for],
      total_count: total_count,
      total_pages: total_pages
    }
  end

  defp get_previous(offset, current_page, limit) do
    has_previous? = offset > 0
    previous_offset = if has_previous?, do: max(0, offset - limit), else: nil
    previous_page = if current_page > 1, do: current_page - 1, else: nil

    {has_previous?, previous_offset, previous_page}
  end

  defp get_next(_, _, nil = _page_size, _, _) do
    {false, nil, nil}
  end

  defp get_next(current_offset, _, page_size, total_count, _)
       when current_offset + page_size >= total_count do
    {false, nil, nil}
  end

  defp get_next(current_offset, current_page, page_size, _, total_pages) do
    {true, current_offset + page_size, min(total_pages, current_page + 1)}
  end

  defp get_total_pages(0, _), do: 0
  defp get_total_pages(_, nil), do: 1
  defp get_total_pages(total_count, limit), do: ceil(total_count / limit)

  defp get_current_offset(%Flop{offset: nil, page: nil}), do: 0

  defp get_current_offset(%Flop{offset: nil, page: page, page_size: page_size}),
    do: (page - 1) * page_size

  defp get_current_offset(%Flop{offset: offset}), do: offset

  defp get_current_page(%Flop{offset: nil, page: nil}, _), do: 1
  defp get_current_page(%Flop{offset: nil, page: page}, _), do: page

  defp get_current_page(%Flop{limit: limit, offset: offset, page: nil}, total),
    do: min(ceil(offset / limit) + 1, total)

  ## Ordering

  @doc """
  Applies the `order_by` and `order_directions` parameters of a `t:Flop.t/0`
  to an `t:Ecto.Queryable.t/0`.

  Used by `Flop.query/2`.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.

  Note that you will need to pass the `for` option in order for Flop to be
  able to find your join, compound, alias and custom field configuration.
  """
  @doc group: :queries
  @spec order_by(Queryable.t(), Flop.t(), [option()]) :: Queryable.t()
  def order_by(q, flop, opts \\ [])

  def order_by(q, %Flop{order_by: nil}, _opts), do: q

  # For backwards cursor pagination
  def order_by(
        q,
        %Flop{
          last: last,
          order_by: fields,
          order_directions: directions,
          first: nil,
          after: nil,
          offset: nil
        },
        opts
      )
      when is_integer(last) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)

    prepared_directions =
      fields
      |> prepare_order_fields_and_directions(directions)
      |> reverse_ordering()

    adapter.apply_order_by(q, prepared_directions, opts)
  end

  def order_by(
        q,
        %Flop{order_by: fields, order_directions: directions},
        opts
      ) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)

    prepared_directions =
      prepare_order_fields_and_directions(
        fields,
        directions
      )

    adapter.apply_order_by(q, prepared_directions, opts)
  end

  @spec prepare_order_fields_and_directions([atom], [order_direction()]) :: [
          {order_direction(), atom}
        ]
  defp prepare_order_fields_and_directions(fields, directions) do
    directions = directions || []
    field_count = length(fields)
    direction_count = length(directions)

    directions =
      if direction_count < field_count,
        do: directions ++ List.duplicate(:asc, field_count - direction_count),
        else: directions

    Enum.zip(directions, fields)
  end

  ## Pagination

  @doc """
  Applies the pagination parameters of a `t:Flop.t/0` to an
  `t:Ecto.Queryable.t/0`.

  The function supports both `offset`/`limit` based pagination and
  `page`/`page_size` based pagination.

  If you validated the `t:Flop.t/0` with `Flop.validate/1` before, you can be
  sure that the given `t:Flop.t/0` only has pagination parameters set for one
  pagination method. If you pass an unvalidated `t:Flop.t/0` that has
  pagination parameters set for multiple pagination methods, this function
  will arbitrarily only apply one of the pagination methods.

  Used by `Flop.query/2`.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.

  Note that you will need to pass the `for` option in order for Flop to be
  able to find your join, compound, alias and custom field configuration.
  """
  @doc group: :queries
  @spec paginate(Queryable.t(), Flop.t(), [option()]) :: Queryable.t()
  def paginate(q, flop, opts \\ [])

  def paginate(q, %Flop{limit: limit, offset: offset}, opts)
      when (is_integer(limit) and limit >= 1) or
             (is_integer(offset) and offset >= 0) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    adapter.apply_limit_offset(q, limit, offset, opts)
  end

  def paginate(q, %Flop{page: page, page_size: page_size}, opts)
      when is_integer(page) and is_integer(page_size) and
             page >= 1 and page_size >= 1 do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    adapter.apply_page_page_size(q, page, page_size, opts)
  end

  def paginate(
        q,
        %Flop{
          first: first,
          after: nil,
          before: nil,
          last: nil,
          limit: nil
        },
        opts
      )
      when is_integer(first) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    adapter.apply_limit_offset(q, first + 1, nil, opts)
  end

  def paginate(
        q,
        %Flop{
          first: first,
          after: after_,
          decoded_cursor: decoded_cursor,
          order_by: order_by,
          order_directions: order_directions,
          before: nil,
          last: nil,
          limit: nil
        },
        opts
      )
      when is_integer(first) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    struct = if module = opts[:for], do: struct(module)
    orderings = prepare_order_fields_and_directions(order_by, order_directions)
    decoded_cursor = decoded_cursor || Cursor.decode!(after_)
    cursor_fields = prepare_cursor_fields(struct, decoded_cursor, orderings)

    q
    |> adapter.apply_cursor(cursor_fields, opts)
    |> adapter.apply_limit_offset(first + 1, nil, opts)
  end

  def paginate(
        q,
        %Flop{
          last: last,
          before: nil,
          first: nil,
          after: nil,
          limit: nil
        },
        opts
      )
      when is_integer(last) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    adapter.apply_limit_offset(q, last + 1, nil, opts)
  end

  def paginate(
        q,
        %Flop{
          last: last,
          before: before,
          decoded_cursor: decoded_cursor,
          order_by: order_by,
          order_directions: order_directions,
          first: nil,
          after: nil,
          limit: nil
        },
        opts
      )
      when is_integer(last) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    struct = if module = opts[:for], do: struct(module)

    orderings =
      order_by
      |> prepare_order_fields_and_directions(order_directions)
      |> reverse_ordering()

    decoded_cursor = decoded_cursor || Cursor.decode!(before)
    cursor_fields = prepare_cursor_fields(struct, decoded_cursor, orderings)

    q
    |> adapter.apply_cursor(cursor_fields, opts)
    # add 1 to limit, so that we know whether there are more items to show
    |> adapter.apply_limit_offset(last + 1, nil, opts)
  end

  def paginate(q, _, _), do: q

  @spec prepare_cursor_fields(struct | nil, map, [{atom, atom}]) :: [
          {order_direction(), atom, any, Flop.FieldInfo.t()}
        ]
  defp prepare_cursor_fields(struct, decoded_cursor, ordering) do
    Enum.map(ordering, fn {direction, field} ->
      field_info = struct && Flop.Schema.field_info(struct, field)
      cursor_value = Map.get(decoded_cursor, field)
      {direction, field, cursor_value, field_info}
    end)
  end

  @spec reverse_ordering([order_direction()]) :: [order_direction()]
  defp reverse_ordering(order_directions) do
    Enum.map(order_directions, fn {direction, field} ->
      {reverse_direction(direction), field}
    end)
  end

  defp reverse_direction(:asc), do: :desc
  defp reverse_direction(:asc_nulls_first), do: :desc_nulls_last
  defp reverse_direction(:asc_nulls_last), do: :desc_nulls_first
  defp reverse_direction(:desc), do: :asc
  defp reverse_direction(:desc_nulls_first), do: :asc_nulls_last
  defp reverse_direction(:desc_nulls_last), do: :asc_nulls_first

  defguardp is_direction(value)
            when value in [
                   :asc,
                   :asc_nulls_first,
                   :asc_nulls_last,
                   :desc,
                   :desc_nulls_first,
                   :desc_nulls_last
                 ]

  defguardp is_asc_direction(value)
            when value in [
                   :asc,
                   :asc_nulls_first,
                   :asc_nulls_last
                 ]

  defguardp is_desc_direction(value)
            when value in [
                   :desc,
                   :desc_nulls_first,
                   :desc_nulls_last
                 ]

  ## Filter

  @doc """
  Applies the `filter` parameter of a `t:Flop.t/0` to an `t:Ecto.Queryable.t/0`.

  Used by `Flop.query/2`.

  This function does _not_ validate or apply default parameters to the given
  Flop struct. Be sure to validate any user-generated parameters with
  `validate/2` or `validate!/2` before passing them to this function.

  Note that you will need to pass the `for` option in order for Flop to be
  able to find your join, compound, alias and custom field configuration.
  """
  @doc group: :queries
  @spec filter(Queryable.t(), Flop.t(), [option()]) :: Queryable.t()
  def filter(q, flop, opt \\ [])

  def filter(q, %Flop{filters: nil}, _), do: q
  def filter(q, %Flop{filters: []}, _), do: q

  def filter(q, %Flop{filters: filters}, opts) when is_list(filters) do
    schema_struct =
      case opts[:for] do
        nil -> nil
        module -> struct(module)
      end

    Enum.reduce(filters, q, &apply_filter(&2, &1, schema_struct, opts))
  end

  defp apply_filter(query, %Filter{field: nil}, _, _), do: query
  defp apply_filter(query, %Filter{value: nil}, _, _), do: query

  defp apply_filter(query, %Filter{} = filter, schema_struct, opts) do
    adapter = Keyword.get(opts, :adapter, Adapter.Ecto)
    adapter.apply_filter(query, filter, schema_struct, opts)
  end

  ## Validation

  @doc """
  Validates a `t:Flop.t/0`.

  ## Examples

      iex> params = %{"limit" => 10, "offset" => 0, "texture" => "fluffy"}
      iex> Flop.validate(params)
      {:ok,
       %Flop{
         filters: [],
         limit: 10,
         offset: 0,
         order_by: nil,
         order_directions: nil,
         page: nil,
         page_size: nil
       }}

      iex> flop = %Flop{offset: -1}
      iex> {:error, %Flop.Meta{} = meta} = Flop.validate(flop)
      iex> meta.errors
      [
        offset: [
          {"must be greater than or equal to %{number}",
           [validation: :number, kind: :greater_than_or_equal_to, number: 0]}
        ]
      ]

  It also makes sure that only one pagination method is used.

      iex> params = %{limit: 10, offset: 0, page: 5, page_size: 10}
      iex> {:error, %Flop.Meta{} = meta} = Flop.validate(params)
      iex> meta.errors
      [limit: [{"cannot combine multiple pagination types", []}]]

  If you derived `Flop.Schema` in your Ecto schema to define the filterable
  and sortable fields, you can pass the module name to the function to validate
  that only allowed fields are used. The function will also apply any default
  values set for the schema.

      iex> params = %{"order_by" => ["species"]}
      iex> {:error, %Flop.Meta{} = meta} = Flop.validate(params, for: MyApp.Pet)
      iex> [order_by: [{msg, [_, {_, enum}]}]] = meta.errors
      iex> msg
      "has an invalid entry"
      iex> enum
      [:name, :age, :owner_name, :owner_age]

  Note that currently, trying to use an existing field that is not allowed as
  seen above will result in the error message `has an invalid entry`, while
  trying to use a field name that does not exist in the schema (or more
  precisely: a field name that doesn't exist as an atom) will result in
  the error message `is invalid`. This might change in the future.
  """
  @doc group: :queries
  @spec validate(Flop.t() | map, [option()]) ::
          {:ok, Flop.t()} | {:error, Meta.t()}
  def validate(flop_or_map, opts \\ [])

  def validate(%Flop{} = flop, opts) do
    flop
    |> flop_struct_to_map()
    |> validate(opts)
  end

  def validate(%{} = params, opts) do
    result =
      params
      |> Flop.Validation.changeset(opts)
      |> Changeset.apply_action(:replace)

    case result do
      {:ok, _} = r ->
        r

      {:error, %Changeset{} = changeset} ->
        Logger.debug("Invalid Flop: #{inspect(changeset)}")
        {:error, Meta.with_errors(params, convert_errors(changeset), opts)}
    end
  end

  defp convert_errors(changeset) do
    changeset
    |> Changeset.traverse_errors(& &1)
    |> map_to_keyword()
  end

  defp map_to_keyword(%{} = map) do
    Enum.into(map, [], fn {key, value} -> {key, map_to_keyword(value)} end)
  end

  defp map_to_keyword(list) when is_list(list) do
    Enum.map(list, &map_to_keyword/1)
  end

  defp map_to_keyword(value), do: value

  defp flop_struct_to_map(%Flop{} = flop) do
    flop
    |> Map.from_struct()
    |> Map.update!(:filters, &filters_to_maps/1)
    |> Enum.reject(fn {_, value} -> is_nil(value) end)
    |> Enum.into(%{})
  end

  defp filters_to_maps(nil), do: nil

  defp filters_to_maps(filters) when is_list(filters),
    do: Enum.map(filters, &filter_to_map/1)

  defp filter_to_map(%Filter{} = filter) do
    filter
    |> Map.from_struct()
    |> Enum.reject(fn {_, value} -> is_nil(value) end)
    |> Enum.into(%{})
  end

  defp filter_to_map(%{} = filter), do: filter

  @doc """
  Same as `Flop.validate/2`, but raises an `Ecto.InvalidChangesetError` if the
  parameters are invalid.
  """
  @doc group: :queries
  @doc since: "0.5.0"
  @spec validate!(Flop.t() | map, [option()]) :: Flop.t()
  def validate!(flop_or_map, opts \\ []) do
    case validate(flop_or_map, opts) do
      {:ok, flop} ->
        flop

      {:error, %Meta{errors: errors, params: params}} ->
        raise Flop.InvalidParamsError, errors: errors, params: params
    end
  end

  @doc """
  Sets the page value of a `Flop` struct while also removing/converting
  pagination parameters for other pagination types.

      iex> set_page(%Flop{page: 2, page_size: 10}, 6)
      %Flop{page: 6, page_size: 10}

      iex> set_page(%Flop{limit: 10, offset: 20}, 8)
      %Flop{limit: nil, offset: nil, page: 8, page_size: 10}

      iex> set_page(%Flop{page: 2, page_size: 10}, "6")
      %Flop{page: 6, page_size: 10}

  The page number will not be allowed to go below 1.

      iex> set_page(%Flop{}, -5)
      %Flop{page: 1}
  """
  @doc since: "0.12.0"
  @doc group: :parameters
  @spec set_page(Flop.t(), pos_integer | binary) :: Flop.t()
  def set_page(%Flop{} = flop, page) when is_integer(page) do
    %{
      flop
      | after: nil,
        before: nil,
        first: nil,
        last: nil,
        limit: nil,
        offset: nil,
        page_size: flop.page_size || flop.limit || flop.first || flop.last,
        page: max(page, 1)
    }
  end

  def set_page(%Flop{} = flop, page) when is_binary(page) do
    set_page(flop, String.to_integer(page))
  end

  @doc """
  Sets the page of a Flop struct to the previous page, but not less than 1.

  ## Examples

      iex> to_previous_page(%Flop{page: 5})
      %Flop{page: 4}

      iex> to_previous_page(%Flop{page: 1})
      %Flop{page: 1}

      iex> to_previous_page(%Flop{page: -2})
      %Flop{page: 1}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec to_previous_page(Flop.t()) :: Flop.t()
  def to_previous_page(%Flop{page: 1} = flop), do: flop

  def to_previous_page(%Flop{page: page} = flop)
      when is_integer(page) and page < 1,
      do: %{flop | page: 1}

  def to_previous_page(%Flop{page: page} = flop) when is_integer(page),
    do: %{flop | page: page - 1}

  @doc """
  Sets the page of a Flop struct to the next page.

  If the total number of pages is given as the second argument, the page number
  will not be increased if the last page has already been reached. You can get
  the total number of pages from the `Flop.Meta` struct.

  ## Examples

      iex> to_next_page(%Flop{page: 5})
      %Flop{page: 6}

      iex> to_next_page(%Flop{page: 5}, 6)
      %Flop{page: 6}

      iex> to_next_page(%Flop{page: 6}, 6)
      %Flop{page: 6}

      iex> to_next_page(%Flop{page: 7}, 6)
      %Flop{page: 6}

      iex> to_next_page(%Flop{page: -5})
      %Flop{page: 1}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec to_next_page(Flop.t(), non_neg_integer | nil) :: Flop.t()
  def to_next_page(flop, total_pages \\ nil)

  def to_next_page(%Flop{page: page} = flop, _)
      when is_integer(page) and page < 0,
      do: %{flop | page: 1}

  def to_next_page(%Flop{page: page} = flop, nil), do: %{flop | page: page + 1}

  def to_next_page(%Flop{page: page} = flop, total_pages)
      when is_integer(total_pages) and page < total_pages,
      do: %{flop | page: page + 1}

  def to_next_page(%Flop{} = flop, total_pages)
      when is_integer(total_pages),
      do: %{flop | page: total_pages}

  @doc """
  Sets the offset value of a `Flop` struct while also removing/converting
  pagination parameters for other pagination types.

      iex> set_offset(%Flop{limit: 10, offset: 10}, 20)
      %Flop{offset: 20, limit: 10}

      iex> set_offset(%Flop{page: 5, page_size: 10}, 20)
      %Flop{limit: 10, offset: 20, page: nil, page_size: nil}

      iex> set_offset(%Flop{limit: 10, offset: 10}, "20")
      %Flop{offset: 20, limit: 10}

  The offset will not be allowed to go below 0.

      iex> set_offset(%Flop{}, -5)
      %Flop{offset: 0}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec set_offset(Flop.t(), non_neg_integer | binary) :: Flop.t()
  def set_offset(%Flop{} = flop, offset) when is_integer(offset) do
    %{
      flop
      | after: nil,
        before: nil,
        first: nil,
        last: nil,
        limit: flop.limit || flop.page_size || flop.first || flop.last,
        offset: max(offset, 0),
        page_size: nil,
        page: nil
    }
  end

  def set_offset(%Flop{} = flop, offset) when is_binary(offset) do
    set_offset(flop, String.to_integer(offset))
  end

  @doc """
  Sets the offset of a Flop struct to the page depending on the limit.

  ## Examples

      iex> to_previous_offset(%Flop{offset: 20, limit: 10})
      %Flop{offset: 10, limit: 10}

      iex> to_previous_offset(%Flop{offset: 5, limit: 10})
      %Flop{offset: 0, limit: 10}

      iex> to_previous_offset(%Flop{offset: 0, limit: 10})
      %Flop{offset: 0, limit: 10}

      iex> to_previous_offset(%Flop{offset: -2, limit: 10})
      %Flop{offset: 0, limit: 10}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec to_previous_offset(Flop.t()) :: Flop.t()
  def to_previous_offset(%Flop{offset: 0} = flop), do: flop

  def to_previous_offset(%Flop{offset: offset, limit: limit} = flop)
      when is_integer(limit) and is_integer(offset),
      do: %{flop | offset: max(0, offset - limit)}

  @doc """
  Sets the offset of a Flop struct to the next page depending on the limit.

  If the total count is given as the second argument, the offset will not be
  increased if the last page has already been reached. You can get the total
  count from the `Flop.Meta` struct. If the Flop has an offset beyond the total
  count, the offset will be set to the last page.

  ## Examples

      iex> to_next_offset(%Flop{offset: 10, limit: 5})
      %Flop{offset: 15, limit: 5}

      iex> to_next_offset(%Flop{offset: 15, limit: 5}, 21)
      %Flop{offset: 20, limit: 5}

      iex> to_next_offset(%Flop{offset: 15, limit: 5}, 20)
      %Flop{offset: 15, limit: 5}

      iex> to_next_offset(%Flop{offset: 28, limit: 5}, 22)
      %Flop{offset: 20, limit: 5}

      iex> to_next_offset(%Flop{offset: -5, limit: 20})
      %Flop{offset: 0, limit: 20}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec to_next_offset(Flop.t(), non_neg_integer | nil) :: Flop.t()
  def to_next_offset(flop, total_count \\ nil)

  def to_next_offset(%Flop{limit: limit, offset: offset} = flop, _)
      when is_integer(limit) and is_integer(offset) and offset < 0,
      do: %{flop | offset: 0}

  def to_next_offset(%Flop{limit: limit, offset: offset} = flop, nil)
      when is_integer(limit) and is_integer(offset),
      do: %{flop | offset: offset + limit}

  def to_next_offset(%Flop{limit: limit, offset: offset} = flop, total_count)
      when is_integer(limit) and
             is_integer(offset) and
             is_integer(total_count) and offset >= total_count do
    %{flop | offset: (ceil(total_count / limit) - 1) * limit}
  end

  def to_next_offset(%Flop{limit: limit, offset: offset} = flop, total_count)
      when is_integer(limit) and
             is_integer(offset) and
             is_integer(total_count) do
    case offset + limit do
      new_offset when new_offset >= total_count -> flop
      new_offset -> %{flop | offset: new_offset}
    end
  end

  @doc """
  Takes a `Flop.Meta` struct and returns a `Flop` struct with updated cursor
  pagination params for going to either the previous or the next page.

  See `to_previous_cursor/1` and `to_next_cursor/1` for details.

  ## Examples

      iex> set_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_previous_page?: true, start_cursor: "b"
      ...>   },
      ...>   :previous
      ...> )
      %Flop{last: 5, before: "b"}

      iex> set_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_next_page?: true, end_cursor: "b"
      ...>   },
      ...>   :next
      ...> )
      %Flop{first: 5, after: "b"}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec set_cursor(Meta.t(), :previous | :next) :: Flop.t()
  def set_cursor(%Meta{} = meta, :previous), do: to_previous_cursor(meta)
  def set_cursor(%Meta{} = meta, :next), do: to_next_cursor(meta)

  @doc """
  Takes a `Flop.Meta` struct and returns a `Flop` struct with updated cursor
  pagination params for going to the previous page.

  ## Examples

      iex> to_previous_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_previous_page?: true, start_cursor: "b"
      ...>   }
      ...> )
      %Flop{last: 5, before: "b"}

      iex> to_previous_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{last: 5, before: "b"},
      ...>     has_previous_page?: true, start_cursor: "a"
      ...>   }
      ...> )
      %Flop{last: 5, before: "a"}

  If there is no previous page, the `Flop` struct is returned unchanged.

      iex> to_previous_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "b"},
      ...>     has_previous_page?: false, start_cursor: "a"
      ...>   }
      ...> )
      %Flop{first: 5, after: "b"}

  It can happen that `has_previous_page?` is `true`, but no start cursor is set,
  for example if the user is on the next-to-last page and switches to the next
  page right after the only item on the last page is deleted. Since the result
  set would be empty and there is no start cursor in this case, this function
  sets the new `before` parameter to `nil`. By doing this, the user is sent to
  the actual last page without skipping any items.

      iex> to_previous_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_previous_page?: true, start_cursor: nil
      ...>   }
      ...> )
      %Flop{last: 5, before: nil}

      iex> to_previous_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{last: 5, before: "b"},
      ...>     has_previous_page?: true, start_cursor: nil
      ...>   }
      ...> )
      %Flop{last: 5, before: nil}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec to_previous_cursor(Meta.t()) :: Flop.t()
  def to_previous_cursor(%Meta{
        flop: %Flop{} = flop,
        has_previous_page?: false
      }),
      do: flop

  def to_previous_cursor(%Meta{
        flop: %Flop{} = flop,
        has_previous_page?: true,
        start_cursor: start_cursor
      }) do
    %{
      flop
      | before: start_cursor,
        last: flop.last || flop.first || flop.page_size || flop.limit,
        after: nil,
        first: nil,
        page: nil,
        page_size: nil,
        limit: nil,
        offset: nil
    }
  end

  @doc """
  Takes a `Flop.Meta` struct and returns a `Flop` struct with updated cursor
  pagination params for going to the next page.

  ## Examples

      iex> to_next_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_next_page?: true, end_cursor: "b"
      ...>   }
      ...> )
      %Flop{first: 5, after: "b"}

      iex> to_next_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{last: 5, before: "b"},
      ...>     has_next_page?: true, end_cursor: "a"
      ...>   }
      ...> )
      %Flop{first: 5, after: "a"}

  If there is no next page, the `Flop` struct is returned unchanged.

      iex> to_next_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_next_page?: false, start_cursor: "b"
      ...>   }
      ...> )
      %Flop{first: 5, after: "a"}

  It can happen that `has_next_page?` is `true`, but no end cursor is set,
  for example if the user is on the second page and switches to the previous
  page right after the only item on the first page is deleted. Since the result
  set is empty and there is no end cursor in this case, this function sets the
  new `after` parameter to `nil`. By doing this, the user is sent to the first
  page without skipping any items.

      iex> to_next_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{first: 5, after: "a"},
      ...>     has_next_page?: true, end_cursor: nil
      ...>   }
      ...> )
      %Flop{first: 5, after: nil}

      iex> to_next_cursor(
      ...>   %Flop.Meta{
      ...>     flop: %Flop{last: 5, before: "b"},
      ...>     has_next_page?: true, end_cursor: nil
      ...>   }
      ...> )
      %Flop{first: 5, after: nil}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec to_next_cursor(Meta.t()) :: Flop.t()
  def to_next_cursor(%Meta{flop: %Flop{} = flop, has_next_page?: false}),
    do: flop

  def to_next_cursor(%Meta{
        flop: %Flop{} = flop,
        has_next_page?: true,
        end_cursor: end_cursor
      }) do
    %{
      flop
      | after: end_cursor,
        first: flop.first || flop.last || flop.page_size || flop.limit,
        before: nil,
        last: nil,
        page: nil,
        page_size: nil,
        limit: nil,
        offset: nil
    }
  end

  @doc """
  Removes the `after` and `before` cursors from a Flop struct.

  ## Example

      iex> reset_cursors(%Flop{after: "A"})
      %Flop{}

      iex> reset_cursors(%Flop{before: "A"})
      %Flop{}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec reset_cursors(Flop.t()) :: Flop.t()
  def reset_cursors(%Flop{} = flop), do: %{flop | after: nil, before: nil}

  @doc """
  Removes all filters from a Flop struct.

  ## Example

      iex> reset_filters(%Flop{filters: [
      ...>   %Flop.Filter{field: :name, value: "Jim"}
      ...> ]})
      %Flop{filters: []}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec reset_filters(Flop.t()) :: Flop.t()
  def reset_filters(%Flop{} = flop), do: %{flop | filters: []}

  @doc """
  Returns the current order direction for the given field.

  ## Examples

      iex> flop = %Flop{order_by: [:name, :age], order_directions: [:desc]}
      iex> current_order(flop, :name)
      :desc
      iex> current_order(flop, :age)
      :asc
      iex> current_order(flop, :species)
      nil
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec current_order(Flop.t(), atom) :: order_direction() | nil
  def current_order(
        %Flop{order_by: order_by, order_directions: order_directions},
        field
      )
      when is_atom(field) do
    get_order_direction(order_directions, get_index(order_by, field))
  end

  @doc """
  Removes the order parameters from a Flop struct.

  ## Example

      iex> reset_order(%Flop{order_by: [:name], order_directions: [:asc]})
      %Flop{order_by: nil, order_directions: nil}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec reset_order(Flop.t()) :: Flop.t()
  def reset_order(%Flop{} = flop),
    do: %{flop | order_by: nil, order_directions: nil}

  @doc """
  Updates the `order_by` and `order_directions` values of a `Flop` struct.

  - If the field is not in the current `order_by` value, it will be prepended to
    the list. By default, the order direction for the field will be set to
    `:asc`.
  - If the field is already at the front of the `order_by` list, the order
    direction will be reversed.
  - If the field is already in the list, but not at the front, it will be moved
    to the front and the order direction will be set to `:asc` (or the custom
    asc direction supplied in the `:directions` option).
  - If the `:directions` option——a 2-element tuple——is passed, the first and
    second elements will be used as custom sort declarations for ascending and
    descending, respectively.

  ## Examples

      iex> flop = push_order(%Flop{}, :name)
      iex> flop.order_by
      [:name]
      iex> flop.order_directions
      [:asc]
      iex> flop = push_order(flop, :age)
      iex> flop.order_by
      [:age, :name]
      iex> flop.order_directions
      [:asc, :asc]
      iex> flop = push_order(flop, :age)
      iex> flop.order_by
      [:age, :name]
      iex> flop.order_directions
      [:desc, :asc]
      iex> flop = push_order(flop, :species)
      iex> flop.order_by
      [:species, :age, :name]
      iex> flop.order_directions
      [:asc, :desc, :asc]
      iex> flop = push_order(flop, :age)
      iex> flop.order_by
      [:age, :species, :name]
      iex> flop.order_directions
      [:asc, :asc, :asc]

  By default, the function toggles between `:asc` and `:desc`. You can override
  this with the `:directions` option.

      iex> directions = {:asc_nulls_last, :desc_nulls_last}
      iex> flop = push_order(%Flop{}, :ttfb, directions: directions)
      iex> flop.order_by
      [:ttfb]
      iex> flop.order_directions
      [:asc_nulls_last]
      iex> flop = push_order(flop, :ttfb, directions: directions)
      iex> flop.order_by
      [:ttfb]
      iex> flop.order_directions
      [:desc_nulls_last]

  If a string is passed as the second argument, it will be converted to an atom
  using `String.to_existing_atom/1`. If the atom does not exist, the `Flop`
  struct will be returned unchanged.

      iex> flop = push_order(%Flop{}, "name")
      iex> flop.order_by
      [:name]
      iex> flop = push_order(%Flop{}, "this_atom_does_not_exist")
      iex> flop.order_by
      nil

  Since the pagination cursor depends on the sort order, the `:before` and
  `:after` parameters are reset.

      iex> push_order(%Flop{order_by: [:id], after: "ABC"}, :name)
      %Flop{order_by: [:name, :id], order_directions: [:asc], after: nil}
      iex> push_order(%Flop{order_by: [:id], before: "DEF"}, :name)
      %Flop{order_by: [:name, :id], order_directions: [:asc], before: nil}
  """
  @spec push_order(Flop.t(), atom | String.t(), keyword) :: Flop.t()
  @doc since: "0.10.0"
  @doc group: :parameters
  def push_order(flop, field, opts \\ [])

  def push_order(
        %Flop{order_by: order_by, order_directions: order_directions} = flop,
        field,
        opts
      )
      when is_atom(field) do
    previous_index = get_index(order_by, field)
    previous_direction = get_order_direction(order_directions, previous_index)

    directions = Keyword.get(opts, :directions, nil)

    new_direction =
      new_order_direction(previous_index, previous_direction, directions)

    {order_by, order_directions} =
      get_new_order(
        order_by,
        order_directions,
        field,
        new_direction,
        previous_index
      )

    %{
      flop
      | after: nil,
        before: nil,
        order_by: order_by,
        order_directions: order_directions
    }
  end

  def push_order(flop, field, opts) when is_binary(field) do
    push_order(flop, String.to_existing_atom(field), opts)
  rescue
    _e in ArgumentError -> flop
  end

  defp get_index(nil, _field), do: nil
  defp get_index(order_by, field), do: Enum.find_index(order_by, &(&1 == field))

  defp get_order_direction(_, nil), do: nil
  defp get_order_direction(nil, _), do: :asc

  defp get_order_direction(directions, index),
    do: Enum.at(directions, index, :asc)

  defp new_order_direction(0, current_direction, nil),
    do: reverse_direction(current_direction)

  defp new_order_direction(0, current_direction, {_asc, desc})
       when is_asc_direction(current_direction) and is_direction(desc),
       do: desc

  defp new_order_direction(0, current_direction, {asc, _desc})
       when is_desc_direction(current_direction) and is_direction(asc),
       do: asc

  defp new_order_direction(0, _current_direction, directions) do
    raise Flop.InvalidDirectionsError, directions: directions
  end

  defp new_order_direction(_, _, nil), do: :asc
  defp new_order_direction(_, _, {asc, _desc}) when is_direction(asc), do: asc

  defp new_order_direction(_, _, directions) do
    raise Flop.InvalidDirectionsError, directions: directions
  end

  defp get_new_order(
         order_by,
         order_directions,
         field,
         new_direction,
         previous_index
       ) do
    {order_by, order_directions} =
      if previous_index do
        {List.delete_at(order_by, previous_index),
         List.delete_at(order_directions, previous_index)}
      else
        {order_by, order_directions}
      end

    {[field | order_by || []], [new_direction | order_directions || []]}
  end

  @doc """
  Returns the option with the given key.

  The look-up order is:

  1. the keyword list passed as the second argument
  2. the schema module that derives `Flop.Schema`, if the passed list includes
     the `:for` option
  3. the backend module with `use Flop`
  4. the application environment
  5. the default passed as the last argument
  """
  @doc since: "0.11.0"
  @doc group: :miscellaneous
  @spec get_option(atom, [option()], any) :: any
  def get_option(key, opts, default \\ nil) do
    with nil <- opts[key],
         nil <- schema_option(opts[:for], key),
         nil <- backend_option(opts[:backend], key),
         nil <- global_option(key) do
      Keyword.get(@default_opts, key, default)
    end
  end

  defp schema_option(module, key)
       when is_atom(module) and module != nil and
              key in [
                :default_limit,
                :default_order,
                :filterable_fields,
                :max_limit,
                :pagination_types,
                :default_pagination_type,
                :sortable
              ] do
    apply(Flop.Schema, key, [struct(module)])
  end

  defp schema_option(_, _), do: nil

  defp backend_option(module, key)
       when is_atom(module) and module != nil do
    module.__flop_options__()[key]
  end

  defp backend_option(_, _), do: nil

  defp global_option(key) when is_atom(key) do
    Application.get_env(:flop, key)
  end

  @doc """
  Converts key/value filter parameters at the root of a map, converts them into
  a list of filter parameter maps and nests them under the `:filters` key.

  This is useful in cases where you get some or all filter parameters as
  key/value pairs instead of a full map with operators, for example when you
  expose certain filters with fixed operators on an API, or if you want to
  reflect some or all filters in the URL as path parameters or simple query
  parameters (e.g. `/posts/{tag}` or `/posts?s=searchterm`).

  The given map should have either string keys or atom keys. Passing a map with
  mixed keys will lead to unexpected results and will cause an Ecto error when
  the return value is passed to one of the validation functions.

  The second argument is a list of fields as atoms.

  The `opts` argument is passed to `map_to_filter_params/2`.

  The function returns a map that eventually needs to be passed to one of the
  Flop validation functions (any `Flop.validate*` function) before it can be
  used to make a query.

  ## Examples

  Map with atom keys

      iex> nest_filters(%{name: "Peter", page_size: 10}, [:name])
      %{filters: [%{field: :name, op: :==, value: "Peter"}], page_size: 10}

  Map with string keys

      iex> nest_filters(%{"name" => "Peter"}, [:name])
      %{"filters" => [%{"field" => "name", "op" => :==, "value" =>  "Peter"}]}

  Specifying operators

      iex> nest_filters(%{name: "Peter"}, [:name], operators: %{name: :!=})
      %{filters: [%{field: :name, op: :!=, value: "Peter"}]}

  Renaming fields

      iex> nest_filters(%{nombre: "Peter", page_size: 10}, [:nombre],
      ...>   rename: %{nombre: :name}
      ...> )
      %{filters: [%{field: :name, op: :==, value: "Peter"}], page_size: 10}

      iex> nest_filters(%{"nombre" => "Peter"}, [:nombre],
      ...>   rename: %{nombre: :name}
      ...> )
      %{"filters" => [%{"field" => "name", "op" => :==, "value" =>  "Peter"}]}

      iex> nest_filters(%{"nombre" => "Peter"}, [:nombre],
      ...>   rename: %{nombre: :name},
      ...>   operators: %{name: :like}
      ...> )
      %{"filters" => [%{"field" => "name", "op" => :like, "value" =>  "Peter"}]}

  If the map already has a `filters` key, the extracted filters are added to
  the existing filters.

      iex> nest_filters(%{name: "Peter", filters: [%{field: "age", op: ">", value: 25}]}, [:name])
      %{filters: [%{field: "age", op: ">", value: 25}, %{field: :name, op: :==, value: "Peter"}]}

      iex> nest_filters(%{"name" => "Peter", "filters" => [%{"field" => "age", "op" => ">", "value" => 25}]}, [:name])
      %{"filters" => [%{"field" => "age", "op" => ">", "value" => 25}, %{"field" => "name", "op" => :==, "value" => "Peter"}]}

  If the existing filters are formatted as a map with integer indexes as keys as
  produced by a form, the map is converted to a list first.

      iex> nest_filters(%{name: "Peter", filters: %{"0" => %{field: "age", op: ">", value: 25}}}, [:name])
      %{filters: [%{field: "age", op: ">", value: 25}, %{field: :name, op: :==, value: "Peter"}]}

      iex> nest_filters(%{"name" => "Peter", "filters" => %{"0" => %{"field" => "age", "op" => ">", "value" => 25}}}, [:name])
      %{"filters" => [%{"field" => "age", "op" => ">", "value" => 25}, %{"field" => "name", "op" => :==, "value" => "Peter"}]}
  """
  @doc since: "0.15.0"
  @doc group: :parameters
  @spec nest_filters(map, [atom | String.t()], keyword) :: map
  def nest_filters(%{} = args, fields, opts \\ []) when is_list(fields) do
    fields = fields ++ Enum.map(fields, &Atom.to_string/1)

    filters =
      args
      |> Map.take(fields)
      |> map_to_filter_params(opts)

    key = if has_atom_keys?(args), do: :filters, else: "filters"

    args
    |> Map.update(key, [], &map_to_list/1)
    |> Map.update!(key, &(&1 ++ filters))
    |> Map.drop(fields)
  end

  defp has_atom_keys?(%{} = map) do
    map
    |> Map.keys()
    |> List.first()
    |> is_atom()
  end

  defp map_to_list(%{} = map), do: Map.values(map)
  defp map_to_list(nil), do: []
  defp map_to_list(list) when is_list(list), do: list

  @doc """
  Takes a Flop, converts it to a map and unnests the filters for the given
  fields.

  This is the reverse operation of `nest_filters/3`, with the caveat that the
  result of `nest_filters/3` needs to be validated to convert it to a `Flop`
  struct before it can be passed back to `unnest_filters/3`.

  The function returns a map with `nil` values removed.

  ## Examples

      iex> unnest_filters(
      ...>   %Flop{
      ...>     filters: [%Flop.Filter{field: :name, op: :==, value: "Peter"}],
      ...>     page_size: 10
      ...>   },
      ...>   [:name]
      ...> )
      %{name: "Peter", page_size: 10}

      iex> unnest_filters(
      ...>   %Flop{
      ...>     filters: [%Flop.Filter{field: :name, op: :==, value: nil}],
      ...>     page_size: 10
      ...>   },
      ...>   [:name]
      ...> )
      %{page_size: 10}

  To rename fields, you can pass a map, where the keys are the field names in
  the unnested map and the values are the field names in the `Flop.Filter`
  struct. You can pass the exact same rename map to `nest_filters/3` and
  `unnest_filters/3` to revert the nesting/unnesting.

      iex> unnest_filters(
      ...>   %Flop{
      ...>     filters: [%Flop.Filter{field: :name, op: :==, value: "Peter"}],
      ...>     page_size: 10
      ...>   },
      ...>   [:name],
      ...>   rename: %{nombre: :name}
      ...> )
      %{nombre: "Peter", page_size: 10}
  """
  @doc since: "0.20.0"
  @doc group: :parameters
  @spec unnest_filters(Flop.t(), [atom], keyword) :: map
  def unnest_filters(%Flop{filters: filters} = flop, fields, opts \\ [])
      when is_list(fields) do
    renamings = Enum.into(opts[:rename] || %{}, %{}, fn {k, v} -> {v, k} end)

    {to_unnest, remaining} = Enum.split_with(filters, &(&1.field in fields))

    unnested_map =
      Enum.into(to_unnest, %{}, &{rename_field(&1.field, renamings), &1.value})

    remaining_maps =
      remaining
      |> Enum.map(&Map.from_struct/1)
      |> Enum.reject(&is_nil(&1.value))

    flop
    |> Map.from_struct()
    |> Map.merge(unnested_map)
    |> Map.put(:filters, remaining_maps)
    |> Enum.reject(fn
      {_, nil} -> true
      {_, []} -> true
      _ -> false
    end)
    |> Enum.into(%{})
  end

  @doc """
  Converts a map of filter conditions into a list of Flop filter params.

  The default operator is `:==`. `nil` values are excluded from the result.

      iex> params = map_to_filter_params(
      ...>   %{name: "George", age: 8, species: nil}
      ...> )
      iex> Enum.sort(params)
      [
        %{field: :age, op: :==, value: 8},
        %{field: :name, op: :==, value: "George"}
      ]

      iex> params = map_to_filter_params(
      ...>   %{"name" => "George", "age" => 8, "cat" => true}
      ...>  )
      iex> Enum.sort(params)
      [
        %{"field" => "age", "op" => :==, "value" => 8},
        %{"field" => "cat", "op" => :==, "value" => true},
        %{"field" => "name", "op" => :==, "value" => "George"}
      ]

  You can optionally pass a mapping from field names to operators as a map
  with atom keys.

      iex> params = map_to_filter_params(
      ...>   %{name: "George", age: 8, species: nil},
      ...>   operators: %{name: :ilike_and}
      ...> )
      iex> Enum.sort(params)
      [
        %{field: :age, op: :==, value: 8},
        %{field: :name, op: :ilike_and, value: "George"}
      ]

      iex> map_to_filter_params(
      ...>   %{"name" => "George", "age" => 8, "cat" => true},
      ...>   operators: %{name: :ilike_and, age: :<=}
      ...> )
      [
        %{"field" => "age", "op" => :<=, "value" => 8},
        %{"field" => "cat", "op" => :==, "value" => true},
        %{"field" => "name", "op" => :ilike_and, "value" => "George"}
      ]

  You can also pass a map to rename fields.

      iex> params = map_to_filter_params(
      ...>   %{s: "George", age: 8, species: nil},
      ...>   rename: %{s: :name}
      ...> )
      iex> Enum.sort(params)
      [
        %{field: :age, op: :==, value: 8},
        %{field: :name, op: :==, value: "George"}
      ]

      iex> map_to_filter_params(
      ...>   %{"s" => "George", "cat" => true},
      ...>   rename: %{s: :name, cat: :dog}
      ...> )
      [
        %{"field" => "dog", "op" => :==, "value" => true},
        %{"field" => "name", "op" => :==, "value" => "George"}
      ]

  If both a rename option and an operator are set for a field, the operator
  option needs to use the new field name.

      iex> map_to_filter_params(
      ...>   %{n: "George"},
      ...>   rename: %{n: :name},
      ...>   operators: %{name: :ilike_or}
      ...> )
      [%{field: :name, op: :ilike_or, value: "George"}]

  See also `Flop.Filter.new/2`.
  """
  @doc since: "0.14.0"
  @doc group: :parameters
  @spec map_to_filter_params(map, keyword) :: [map]
  def map_to_filter_params(%{} = map, opts \\ []) do
    operators = opts[:operators]
    renamings = opts[:rename]

    map
    |> Stream.reject(fn
      {_, nil} -> true
      _ -> false
    end)
    |> Enum.map(fn
      {field, value} when is_atom(field) ->
        field = rename_field(field, renamings)

        %{
          field: field,
          op: op_from_mapping(field, operators),
          value: value
        }

      {field, value} when is_binary(field) ->
        field = field |> rename_field(renamings) |> to_string()

        %{
          "field" => field,
          "op" => op_from_mapping(field, operators),
          "value" => value
        }
    end)
  end

  defp op_from_mapping(_field, nil), do: :==

  defp op_from_mapping(field, %{} = operators) when is_atom(field) do
    Map.get(operators, field, :==)
  end

  defp op_from_mapping(field, %{} = operators) when is_binary(field) do
    atom_key = String.to_existing_atom(field)
    Map.get(operators, atom_key, :==)
  rescue
    ArgumentError -> :==
  end

  defp rename_field(field, nil), do: field

  defp rename_field(field, %{} = renamings) when is_atom(field) do
    Map.get(renamings, field, field)
  end

  defp rename_field(field, %{} = renamings) when is_binary(field) do
    atom_key = String.to_existing_atom(field)
    Map.get(renamings, atom_key, field)
  rescue
    ArgumentError -> field
  end

  @doc """
  Returns the names of the bindings that are required for the filters and order
  clauses of the given Flop.

  The second argument is the schema module that derives `Flop.Schema`.

  For example, your schema module might define a join field called `:owner_age`.

      @derive {
        Flop.Schema,
        filterable: [:name, :owner_age],
        sortable: [:name, :owner_age],
        adapter_opts: [
          join_fields: [owner_age: {:owner, :age}]
        ]
      }

  If you pass a Flop with a filter on the `:owner_age` field, the returned list
  will include the `:owner` binding.

      iex> named_bindings(
      ...>   %Flop{
      ...>     filters: [%Flop.Filter{field: :owner_age, op: :==, value: 5}]
      ...>   },
      ...>   MyApp.Pet
      ...> )
      [:owner]

  If on the other hand only normal fields or compound fields are used in the
  filter and order options, or if the filter values are nil, an empty list will
  be returned.

      iex> named_bindings(
      ...>   %Flop{
      ...>     filters: [
      ...>       %Flop.Filter{field: :name, op: :==, value: "George"},
      ...>       %Flop.Filter{field: :owner_age, op: :==, value: nil}
      ...>     ]
      ...>   },
      ...>   MyApp.Pet
      ...> )
      []

  If a join field is part of a compound field, it will be returned.

      iex> named_bindings(
      ...>   %Flop{
      ...>     filters: [
      ...>       %Flop.Filter{field: :pet_and_owner_name, op: :==, value: "Mae"}
      ...>     ]
      ...>   },
      ...>   MyApp.Pet
      ...> )
      [:owner]

  For custom fields, you can set the `:bindings` option when you derive the
  `Flop.Schema` protocol.

  You can use this to dynamically build the join clauses needed for the query.
  See also `Flop.with_named_bindings/4`.

  For more information about join fields, refer to the module documentation of
  `Flop.Schema`.

  ## Options

  - `:order` - If `false`, only bindings needed for filtering are included.
    Defaults to `true`.
  """
  @doc since: "0.16.0"
  @doc group: :queries
  @spec named_bindings(Flop.t(), module, keyword) :: [atom]
  def named_bindings(
        %Flop{filters: filters, order_by: order_by},
        module,
        opts \\ []
      )
      when is_atom(module) do
    order = Keyword.get(opts, :order, true)
    order_by = if order, do: order_by || [], else: []
    filters = filters || []

    if order_by == [] && filters == [] do
      []
    else
      schema_struct = struct(module)

      filter_fields =
        filters |> Enum.reject(&is_nil(&1.value)) |> Enum.map(& &1.field)

      fields = Enum.uniq(order_by ++ filter_fields)

      fields
      |> Enum.map(&get_binding(schema_struct, &1))
      |> List.flatten()
      |> Enum.uniq()
    end
  end

  defp get_binding(schema_struct, field) when is_atom(field) do
    field_info = Flop.Schema.field_info(schema_struct, field)
    get_binding(schema_struct, field_info)
  end

  defp get_binding(_, %{extra: %{type: :join, binding: binding}}), do: binding
  defp get_binding(_, %{extra: %{type: :custom, bindings: bndgns}}), do: bndgns

  defp get_binding(struct, %{extra: %{type: :compound, fields: fields}}) do
    Enum.map(fields, &get_binding(struct, &1))
  end

  defp get_binding(_, _), do: []

  @doc """
  Applies a callback function to a query for all named bindings that are
  necessary for the given `Flop` parameters.

  The callback function must accept a queryable and the name of the binding and
  return a query that includes the given binding. This is the same as
  `Ecto.Query.with_named_binding/3`, except that the callback function _must_
  take the second argument.

  ## Options

  - `:for` (required) - The schema module that derives `Flop.Schema`.
  - `:order` - If `false`, only bindings needed for filtering are included.
    Defaults to `true`.

  ## Example

      def list_pets(params) do
        opts = [for: Pet]

        with {:ok, flop} <- Flop.validate(params, opts) do
          Pet
          |> Flop.with_named_bindings(flop, &join_pet_assocs/2, opts)
          |> Flop.run(flop, opts)
        end
      end

      defp join_pet_assocs(query, :owner) do
        join(query, [p], o in assoc(p, :owner), as: :owner)
      end

      defp join_pet_assocs(query, :toys) do
        join(query, [p], t in assoc(p, :toys), as: :toys)
      end

  Since the callback function has the same arguments and return value as the one
  passed to `Ecto.Query.with_named_binding/3`, you can reuse the function to add
  any other bindings you may need for the query besides the ones for Flop
  filters.

  This also means you can use `Ecto.Query.with_named_binding/3` to recursively
  add bindings in case you need intermediate joins to get to a nested
  association.

      def list_owners(params) do
        opts = [for: Owner]

        with {:ok, flop} <- Flop.validate(params, opts) do
          Pet
          |> Flop.with_named_bindings(flop, &join_owner_assocs/2, opts)
          |> Flop.run(flop, opts)
        end
      end

      defp join_owner_assocs(query, :pets) do
        join(query, [o], p in assoc(o, :pets), as: :pets)
      end

      defp join_owner_assocs(query, :toys) do
        query
        |> Ecto.Query.with_named_binding(:pets, &join_owner_assocs/2)
        |> join(query, [pets: p], t in assoc(p, :toys), as: :toys)
      end
  """
  @doc since: "0.19.0"
  @doc group: :queries
  @spec with_named_bindings(
          Ecto.Queryable.t(),
          Flop.t(),
          (Ecto.Queryable.t(), atom -> Ecto.Queryable.t()),
          keyword
        ) :: Ecto.Queryable.t()
  def with_named_bindings(query, %Flop{} = flop, fun, opts) do
    module = Keyword.fetch!(opts, :for)
    bindings = named_bindings(flop, module, opts)

    Enum.reduce(bindings, query, fn binding, acc_query ->
      Ecto.Query.with_named_binding(acc_query, binding, fun)
    end)
  end

  @doc """
  Returns the names of the alias fields that are required for the order clause
  of the given Flop.

  The second argument is the schema module that derives `Flop.Schema`.

  For example, your schema module might define an alias field called
  `:pet_count`.

      @derive {
        Flop.Schema,
        filterable: [],
        sortable: [:name, :pet_count],
        adapter_opts: [
          alias_fields: [:pet_count]
        ]
      }

  If you pass a Flop that orders by the `:pet_count` field, the returned list
  will include the `:pet_count` alias.

      iex> aliases(%Flop{order_by: [:name, :pet_count]}, MyApp.Owner)
      [:pet_count]

  If on the other hand only normal fields are used in the `order_by` parameter,
  an empty list will be returned.

      iex> aliases(%Flop{order_by: [:name]}, MyApp.Owner)
      []

  You can use this to dynamically build the select clause needed for the query.

  For more information about alias fields, refer to the module documentation of
  `Flop.Schema`.
  """
  @doc since: "0.18.0"
  @doc group: :queries
  @spec aliases(Flop.t(), module) :: [atom]
  def aliases(%Flop{order_by: order_by}, module) when is_atom(module) do
    if order_by == [] do
      []
    else
      schema_struct = struct(module)

      order_by
      |> filter_alias_fields(schema_struct)
      |> Enum.uniq()
    end
  end

  defp filter_alias_fields(order_fields, schema_struct) do
    Enum.reduce(order_fields, [], fn order_field, alias_fields ->
      case Flop.Schema.field_info(schema_struct, order_field) do
        %{extra: %{type: :alias}} -> [order_field | alias_fields]
        _ -> alias_fields
      end
    end)
  end
end