connection.ex

defmodule Absinthe.Relay.Connection.Options do
  @moduledoc false

  alias Absinthe.Relay.Connection

  @typedoc false
  @type t :: %{
          optional(:after) => nil | Connection.cursor(),
          optional(:before) => nil | Connection.cursor(),
          optional(:first) => nil | pos_integer(),
          optional(:last) => nil | pos_integer(),
          optional(any()) => any()
        }

  defstruct after: nil, before: nil, first: nil, last: nil
end

defmodule Absinthe.Relay.Connection do
  @moduledoc """
  Support for paginated result sets.

  Define connection types that provide a standard mechanism for slicing and
  paginating result sets.

  For information about the connection model, see the Relay Cursor
  Connections Specification at
  https://facebook.github.io/relay/graphql/connections.htm.

  ## Connection

  Given an object type, eg:

  ```
  object :pet do
    field :name, :string
  end
  ```

  You can create a connection type to paginate them by:

  ```
  connection node_type: :pet
  ```

  This will automatically define two new types: `:pet_connection` and
  `:pet_edge`.

  We define a field that uses these types to paginate associated records
  by using `connection field`. Here, for instance, we support paginating a
  person's pets:

  ```
  object :person do
    field :first_name, :string
    connection field :pets, node_type: :pet do
      resolve fn
        pagination_args, %{source: person} ->
          Absinthe.Relay.Connection.from_list(
            Enum.map(person.pet_ids, &pet_from_id(&1)),
            pagination_args
          )
        end
      end
    end
  end
  ```

  The `:pets` field is automatically set to return a `:pet_connection` type,
  and configured to accept the standard pagination arguments `after`, `before`,
  `first`, and `last`. We create the connection by using
  `Absinthe.Relay.Connection.from_list/2`, which takes a list and the pagination
  arguments passed to the resolver.

  It is possible to provide additional pagination arguments to a relay
  connection:

  ```
  connection field :pets, node_type: :pet do
    arg :custom_arg, :custom
    # other args...
    resolve fn
     pagination_args_and_custom_args, %{source: person} ->
        # ... return {:ok, a_connection}
    end
  end
  ```

  Note: `Absinthe.Relay.Connection.from_list/2` expects that the full list of
  records be materialized and provided. If you're using Ecto, you probably want
  to use `Absinthe.Relay.Connection.from_query/2` instead.

  Here's how you might request the names of the first `$petCount` pets a person
  owns:

  ```
  query FindPets($personId: ID!, $petCount: Int!) {
    person(id: $personId) {
      pets(first: $petCount) {
        pageInfo {
          hasPreviousPage
          hasNextPage
        }
        edges {
          node {
            name
          }
        }
      }
    }
  }
  ```

  `edges` here is the list of intermediary edge types (created for you
  automatically) that contain a field, `node`, that is the same `:node_type` you
  passed earlier (`:pet`).

  `pageInfo` is a field that contains information about the current
  view; the `startCursor`, `endCursor`, `hasPreviousPage`, and
  `hasNextPage` fields.

  ### Pagination Direction

  By default, connections will support bidirectional pagination, but you can
  also restrict the connection to just the `:forward` or `:backward` direction
  using the `:paginate` argument:

  ```
  connection field :pets, node_type: :pet, paginate: :forward do
  ```

  ### Customizing Types

  If you'd like to add additional fields to the generated connection and edge
  types, you can do that by providing a block to the `connection` macro, eg,
  here we add a field, `:twice_edges_count` to the connection type, and another,
  `:node_name_backwards`, to the edge type:

  ```
  connection node_type: :pet do
    field :twice_edges_count, :integer do
      resolve fn
        _, %{source: conn} ->
          {:ok, length(conn.edges) * 2}
      end
    end
    edge do
      field :node_name_backwards, :string do
        resolve fn
          _, %{source: edge} ->
            {:ok, edge.node.name |> String.reverse}
        end
      end
    end
  end
  ```

  Just remember that if you use the block form of `connection`, you must call
  the `edge` macro within the block.

  ### Customizing the node itself

  It's also possible to customize the way the `node` field of the
  connection's edge is resolved.  This can, for example, be useful if
  you're working with a NoSQL database that returns relationships as
  lists of IDs. Consider the following example which paginates over
  the user's account array, but resolves each one of them
  independently.

  ```
  object :account do
    field :id, non_null(:id)
    field :name, :string
  end

  connection node_type :account do
    edge do
      field :node, :account do
        resolve fn %{node: id}, _args, _info ->
          Account.find(id)
        end
      end
    end
  end

  object :user do
    field :name, string
    connection field :accounts, node_type: :account do
      resolve fn %{accounts: accounts}, _args, _info ->
        Absinthe.Relay.Connection.from_list(ids, args)
      end
    end
  end

  ```

  This would resolve the connections into a list of the user's
  associated accounts, and then for each node find that particular
  account (preferably batched).

  ## Creating Connections

  This module provides two functions that mirror similar JavaScript functions,
  `from_list/2,3` and `from_slice/2,3`. We also provide `from_query/2,3` if you
  have Ecto as a dependency for convenience.

  Use `from_list` when you have all items in a list that you're going to
  paginate over.

  Use `from_slice` when you have items for a particular request, and merely need
  a connection produced from these items.

  ### Supplying Edge Information

  In some cases you may wish to supply extra information about the edge
  so that it can be used in the schema. For example:

  ```
  connection node_type: :user do
    edge do
      field :role, :string
    end
  end
  ```

  To do this, pass `from_list` a list of 2-element tuples
  where the first element is the node and the second element
  either a map or a keyword list of the edge attributes.

  ```
  [
    {%{name: "Jim"}, role: "owner"},
    {%{name: "Sari"}, role: "guest"},
    {%{name: "Lee"}, %{role: "guest"}}, # This is OK, too
  ]
  |> Connection.from_list(args)
  ```

  This is useful when using ecto to include relationship information
  on the edge itself via `from_query`:

  ```
  # In a UserResolver module
  alias Absinthe.Relay

  def list_teams(args, %{context: %{current_user: user}}) do
    TeamAssignment
    |> from
    |> where([a], a.user_id == ^user.id)
    |> join(:left, [a], t in assoc(a, :team))
    |> select([a,t], {t, map(a, [:role])})
    |> Relay.Connection.from_query(&Repo.all/1, args)
  end
  ```

  Be aware that if you pass `:node` in the arguments provided as the second
  element of the edge tuple, that value will be ignored and a warning logged.

  If you provide a `:cursor` argument, then your value will override
  the internally generated cursor. This may or may not be desirable.

  ## Schema Macros

  For more details on connection-related macros, see
  `Absinthe.Relay.Connection.Notation`.
  """

  alias Absinthe.Relay.Connection.Options
  require Logger

  @cursor_prefix "arrayconnection:"

  @type t :: %{
          edges: [edge],
          page_info: page_info
        }

  @typedoc """
  An opaque pagination cursor

  Internally it has the base64 encoded structure:

  ```
  #{@cursor_prefix}:$offset
  ```
  """
  @type cursor :: binary

  @type edge :: %{
          node: term,
          cursor: cursor
        }

  @typedoc """
  Offset from zero.

  Negative offsets are not supported.
  """
  @type offset :: non_neg_integer
  @type limit :: non_neg_integer

  @type page_info :: %{
          start_cursor: cursor,
          end_cursor: cursor,
          has_previous_page: boolean,
          has_next_page: boolean
        }

  @doc """
  Get a connection object for a list of data.

  A simple function that accepts a list and connection arguments, and returns
  a connection object for use in GraphQL.

  The data given to it should constitute all data that further
  pagination requests may page over. As such, it may be very
  inefficient if you're pulling data from a database which could be
  used to more directly retrieve just the desired data.

  See also `from_query` and `from_slice`.

  ## Example
  ```
  #in a resolver module
  @items ~w(foo bar baz)
  def list(args, _) do
    Connection.from_list(@items, args)
  end
  ```
  """
  @spec from_list(data :: list, args :: Options.t()) :: {:ok, t} | {:error, any}
  def from_list(data, args, opts \\ []) do
    with {:ok, direction, limit} <- limit(args, opts[:max]),
         {:ok, offset} <- offset(args) do
      count = length(data)

      {offset, limit} =
        case direction do
          :forward ->
            {offset || 0, limit}

          :backward ->
            end_offset = offset || count
            start_offset = max(end_offset - limit, 0)
            limit = if start_offset == 0, do: end_offset, else: limit
            {start_offset, limit}
        end

      opts =
        opts
        |> Keyword.put(:has_previous_page, offset > 0)
        |> Keyword.put(:has_next_page, count > offset + limit)

      data
      |> Enum.slice(offset, limit)
      |> from_slice(offset, opts)
    end
  end

  @type from_slice_opts :: [
          has_previous_page: boolean,
          has_next_page: boolean
        ]

  @type pagination_direction :: :forward | :backward

  @doc """
  Build a connection from slice

  This function assumes you have already retrieved precisely the number of items
  to be returned in this connection request.

  Often this function is used internally by other functions.

  ## Example

  This is basically how our `from_query/2` function works if we didn't need to
  worry about backwards pagination.
  ```
  # In PostResolver module
  alias Absinthe.Relay

  def list(args, %{context: %{current_user: user}}) do
    {:ok, :forward, limit} = Connection.limit(args)
    {:ok, offset} = Connection.offset(args)

    Post
    |> where(author_id: ^user.id)
    |> limit(^limit)
    |> offset(^offset)
    |> Repo.all
    |> Relay.Connection.from_slice(offset)
  end
  ```
  """
  @spec from_slice(data :: list, offset :: offset) :: {:ok, t}
  @spec from_slice(data :: list, offset :: offset, opts :: from_slice_opts) :: {:ok, t}
  def from_slice(items, offset, opts \\ []) do
    {edges, first, last} = build_cursors(items, offset)

    page_info = %{
      start_cursor: first,
      end_cursor: last,
      has_previous_page: Keyword.get(opts, :has_previous_page, false),
      has_next_page: Keyword.get(opts, :has_next_page, false)
    }

    {:ok, %{edges: edges, page_info: page_info}}
  end

  @doc """
  Build a connection from an Ecto Query

  This will automatically set a limit and offset value on the Ecto
  query, and then run the query with whatever function is passed as
  the second argument.

  Notes:
  - Your query MUST have an `order_by` value. Offset does not make
    sense without one.
  - `last: N` must always be accompanied by either a `before:` argument
    to the query,
  or an explicit `count: ` option to the `from_query` call.
  Otherwise it is impossible to derive the required offset.

  ## Example
  ```
  # In a PostResolver module
  alias Absinthe.Relay

  def list(args, %{context: %{current_user: user}}) do
    Post
    |> where(author_id: ^user.id)
    |> Relay.Connection.from_query(&Repo.all/1, args)
  end
  ```
  """

  @type from_query_opts ::
          [
            count: non_neg_integer,
            max: pos_integer
          ]
          | from_slice_opts

  if Code.ensure_loaded?(Ecto) do
    @spec from_query(Ecto.Queryable.t(), (Ecto.Queryable.t() -> [term]), Options.t()) ::
            {:ok, map} | {:error, any}
    @spec from_query(
            Ecto.Queryable.t(),
            (Ecto.Queryable.t() -> [term]),
            Options.t(),
            from_query_opts
          ) :: {:ok, map} | {:error, any}
    def from_query(query, repo_fun, args, opts \\ []) do
      require Ecto.Query

      with {:ok, offset, limit} <- offset_and_limit_for_query(args, opts) do
        records =
          query
          |> Ecto.Query.limit(^(limit + 1))
          |> Ecto.Query.offset(^offset)
          |> repo_fun.()

        opts =
          opts
          |> Keyword.put(:has_previous_page, offset > 0)
          |> Keyword.put(:has_next_page, length(records) > limit)

        from_slice(Enum.take(records, limit), offset, opts)
      end
    end
  else
    def from_query(_, _, _, _, _ \\ []) do
      raise ArgumentError, """
      Ecto not Loaded!

      You cannot use this unless Ecto is also a dependency
      """
    end
  end

  @doc false
  @spec offset_and_limit_for_query(Options.t(), from_query_opts) ::
          {:ok, offset, limit} | {:error, any}
  def offset_and_limit_for_query(args, opts) do
    with {:ok, direction, limit} <- limit(args, opts[:max]),
         {:ok, offset} <- offset(args) do
      case direction do
        :forward ->
          {:ok, offset || 0, limit}

        :backward ->
          case {offset, opts[:count]} do
            {nil, nil} ->
              {:error,
               "You must supply a count (total number of records) option if using `last` without `before`"}

            {nil, value} ->
              {:ok, max(value - limit, 0), limit}

            {value, _} ->
              start_offset = max(value - limit, 0)
              limit = if start_offset == 0, do: value, else: limit
              {:ok, start_offset, limit}
          end
      end
    end
  end

  @doc """
  Same as `limit/1` with user provided upper bound.

  Often backend developers want to provide a maximum value above which no more
  records can be retrieved, no matter how many are asked for by the front end.

  This function provides that capability. For use with `from_list` or
  `from_query` use the `:max` option on those functions.
  """
  @spec limit(args :: Options.t(), max :: pos_integer | nil) ::
          {:ok, pagination_direction, limit} | {:error, any}
  def limit(args, nil), do: limit(args)

  def limit(args, max) do
    with {:ok, direction, limit} <- limit(args) do
      {:ok, direction, min(max, limit)}
    end
  end

  @doc """
  The direction and desired number of records in the pagination arguments.
  """
  @spec limit(args :: Options.t()) :: {:ok, pagination_direction, limit} | {:error, any}
  def limit(%{first: first}) when not is_nil(first), do: {:ok, :forward, first}
  def limit(%{last: last}) when not is_nil(last), do: {:ok, :backward, last}
  def limit(_), do: {:error, "You must either supply `:first` or `:last`"}

  @doc """
  Returns the offset for a page.

  The limit is required because if using backwards pagination the limit will be
  subtracted from the offset.

  If no offset is specified in the pagination arguments, this will return `nil`.
  """
  @spec offset(args :: Options.t()) :: {:ok, offset | nil} | {:error, any}
  def offset(%{after: cursor}) when not is_nil(cursor) do
    with {:ok, offset} <- cursor_to_offset(cursor) do
      {:ok, offset + 1}
    else
      {:error, _} ->
        {:error, "Invalid cursor provided as `after` argument"}
    end
  end

  def offset(%{before: cursor}) when not is_nil(cursor) do
    with {:ok, offset} <- cursor_to_offset(cursor) do
      {:ok, max(offset, 0)}
    else
      {:error, _} ->
        {:error, "Invalid cursor provided as `before` argument"}
    end
  end

  def offset(_), do: {:ok, nil}

  defp build_cursors([], _offset), do: {[], nil, nil}

  defp build_cursors([item | items], offset) do
    offset = offset || 0
    first = offset_to_cursor(offset)
    edge = build_edge(item, first)
    {edges, _} = do_build_cursors(items, offset + 1, [edge], first)
    first = edges |> List.first() |> get_in([:cursor])
    last = edges |> List.last() |> get_in([:cursor])
    {edges, first, last}
  end

  defp do_build_cursors([], _, edges, last), do: {Enum.reverse(edges), last}

  defp do_build_cursors([item | rest], i, edges, _last) do
    cursor = offset_to_cursor(i)
    edge = build_edge(item, cursor)
    do_build_cursors(rest, i + 1, [edge | edges], cursor)
  end

  defp build_edge({item, args}, cursor) do
    args
    |> Enum.flat_map(fn
      {key, _} when key in [:node] ->
        Logger.warning("Ignoring additional #{key} provided on edge (overriding is not allowed)")
        []

      {key, val} ->
        [{key, val}]
    end)
    |> Enum.into(build_edge(item, cursor))
  end

  defp build_edge(item, cursor) do
    %{
      node: item,
      cursor: cursor
    }
  end

  @doc """
  Creates the cursor string from an offset.
  """
  @spec offset_to_cursor(integer) :: binary
  def offset_to_cursor(offset) do
    [@cursor_prefix, to_string(offset)]
    |> IO.iodata_to_binary()
    |> Base.encode64()
  end

  @doc """
  Rederives the offset from the cursor string.
  """
  @spec cursor_to_offset(binary) :: {:ok, integer} | {:error, any}
  def cursor_to_offset(cursor) do
    with {:ok, @cursor_prefix <> raw} <- Base.decode64(cursor),
         {parsed, _} <- Integer.parse(raw) do
      {:ok, parsed}
    else
      _ -> {:error, "Invalid cursor"}
    end
  end
end