defmodule Quarry do
  @moduledoc """
  A data-driven ecto query builder for nested associations.

  Quarry allows you to interact with your database thinking only about your data, and generates queries
  for exactly what you need. You can specify all the filters, loads, and sorts with any level of granularity
  and at any association level, and Quarry will build a query for you that optimizes for joining just the data
  that is necessary and no more. To optimize has_many associations, subqueries are used for preloading the entity.
  This is generally more optimal than joining and selecting all the data because it avoids pulling n*m
  records into memory.
  """
  require Ecto.Query

  alias Quarry.{From, Filter, Load, Sort}

  @type operation :: :lt | :gt | :lte | :gte | :starts_with | :ends_with
  @type filter_param :: String.t() | number
  @type tuple_filter_param :: {operation(), filter_param()}
  @type filter :: %{optional(atom()) => filter_param() | tuple_filter_param()}
  @type load :: atom() | [atom() | keyword(load())]
  @type sort :: atom() | [atom() | [atom()] | {:asc | :desc, atom() | [atom()]}]
  @type opts :: [
          filter: filter(),
          load: load(),
          sort: sort(),
          limit: integer(),
          offset: integer()
        ]

  @type error :: %{type: :filter | :load, path: [atom()], message: String.t()}

  @doc """
  Builds a query for an entity type from parameters


  ## Examples

  ```elixir
  # Top level attribute
  iex> Quarry.build!(Quarry.Post, filter: %{title: "Value"})
  #Ecto.Query<from p0 in Quarry.Post, as: :post, where: as(:post).title == ^"Value">

  # Field on nested belongs_to relationship
  iex> Quarry.build!(Quarry.Post, filter: %{author: %{publisher: "Publisher"}})
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: a1 in assoc(p0, :author), as: :post_author, where: as(:post_author).publisher == ^"Publisher">

  # Field on nested has_many relationship
  iex> Quarry.build!(Quarry.Post, filter: %{comments: %{body: "comment body"}})
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: c1 in assoc(p0, :comments), as: :post_comments, where: as(:post_comments).body == ^"comment body">


  # Can filter by explicit operation
  iex> Quarry.build!(Quarry.Post, filter: %{author: %{user: %{login_count: {:eq, 1}}}})
  iex> Quarry.build!(Quarry.Post, filter: %{author: %{user: %{login_count: {:lt, 1}}}})
  iex> Quarry.build!(Quarry.Post, filter: %{author: %{user: %{login_count: {:gt, 1}}}})
  iex> Quarry.build!(Quarry.Post, filter: %{author: %{user: %{login_count: {:lte, 1}}}})
  iex> Quarry.build!(Quarry.Post, filter: %{author: %{user: %{login_count: {:gte, 1}}}})
  iex> Quarry.build!(Quarry.Post, filter: %{title: {:starts_with, "How to"}})
  iex> Quarry.build!(Quarry.Post, filter: %{title: {:ends_with, "learn vim"}})
  ```

  ### Load examples

  ```elixir
  # Single atom
  iex> Quarry.build!(Quarry.Post, load: :author)
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: a1 in assoc(p0, :author), as: :post_author, preload: [author: a1]>

  # List of atoms
  iex> Quarry.build!(Quarry.Post, load: [:author, :comments])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: a1 in assoc(p0, :author), as: :post_author, preload: [comments: #Ecto.Query<from c0 in Quarry.Comment, as: :post_comment>], preload: [author: a1]>

  # Nested entities
  iex> Quarry.build!(Quarry.Post, load: [comments: :user])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, preload: [comments: #Ecto.Query<from c0 in Quarry.Comment, as: :post_comment, join: u1 in assoc(c0, :user), as: :post_comment_user, preload: [user: u1]>]>

  # List of nested entities
  iex> Quarry.build!(Quarry.Post, load: [author: [:user, :posts]])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: a1 in assoc(p0, :author), as: :post_author, join: u2 in assoc(a1, :user), as: :post_author_user, preload: [author: [posts: #Ecto.Query<from p0 in Quarry.Post, as: :post_author_post>]], preload: [author: {a1, [user: u2]}]>

  # Use Quarry on nested has_many association
  iex> Quarry.build!(Quarry.Post, load: [comments: [filter: %{body: "comment"}, load: :user]])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, preload: [comments: #Ecto.Query<from c0 in Quarry.Comment, as: :post_comment, join: u1 in assoc(c0, :user), as: :post_comment_user, where: as(:post_comment).body == ^"comment", preload: [user: u1]>]>
  ```

  ### Sort examples

  ```elixir
  # Single field
  iex> Quarry.build!(Quarry.Post, sort: :title)
  #Ecto.Query<from p0 in Quarry.Post, as: :post, order_by: [asc: as(:post).title]>

  # Multiple fields
  iex> Quarry.build!(Quarry.Post, sort: [:title, :body])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, order_by: [asc: as(:post).title], order_by: [asc: as(:post).body]>

  # Nested fields
  iex> Quarry.build!(Quarry.Post, sort: [[:author, :publisher], :title, [:author, :user, :name]])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: a1 in assoc(p0, :author), as: :post_author, join: u2 in assoc(a1, :user), as: :post_author_user, order_by: [asc: as(:post_author).publisher], order_by: [asc: as(:post).title], order_by: [asc: as(:post_author_user).name]>

  # Descending sort
  iex> Quarry.build!(Quarry.Post, sort: [:title, desc: :body, desc: [:author, :publisher]])
  #Ecto.Query<from p0 in Quarry.Post, as: :post, join: a1 in assoc(p0, :author), as: :post_author, order_by: [asc: as(:post).title], order_by: [desc: as(:post).body], order_by: [desc: as(:post_author).publisher]>
  ```

  ### Limit example

  ```elixir
  iex> Quarry.build!(Quarry.Post, limit: 10)
  #Ecto.Query<from p0 in Quarry.Post, as: :post, limit: ^10>
  ```

  ### Offset example

  ```elixir
  iex> Quarry.build!(Quarry.Post, limit: 10, offset: 20)
  #Ecto.Query<from p0 in Quarry.Post, as: :post, limit: ^10, offset: ^20>
  ```

  """
  @spec build!(atom(), opts()) :: Ecto.Query.t()
  def build!(schema, opts \\ []) do
    {query, _errors} = build(schema, opts)
    query
  end

  @spec build(atom(), opts()) :: {Ecto.Query.t(), [error()]}
  def build(schema, opts \\ []) do
    default_opts = %{
      binding_prefix: nil,
      load_path: [],
      filter: %{},
      load: [],
      sort: [],
      limit: nil,
      offset: nil
    }

    opts = Map.merge(default_opts, Map.new(opts))

    {schema, []}
    |> From.build(opts.binding_prefix)
    |> Filter.build(opts.filter, opts.load_path)
    |> Load.build(opts.load, opts.load_path)
    |> Sort.build(opts.sort, opts.load_path)
    |> limit(opts.limit)
    |> offset(opts.offset)
  end

  defp limit({query, errors}, value) when is_integer(value),
    do: {Ecto.Query.limit(query, ^value), errors}

  defp limit(token, _limit), do: token

  defp offset({query, errors}, value) when is_integer(value),
    do: {Ecto.Query.offset(query, ^value), errors}

  defp offset(token, _value), do: token
end