defmodule Momento.CacheClient do
  alias Momento.Auth.CredentialProvider
  alias Momento.Responses.{CreateCache, DeleteCache, ListCaches, Set, Get, Delete}
  alias Momento.Responses.SortedSet
  alias Momento.Requests.CollectionTtl
  alias Momento.Internal.ScsControlClient
  alias Momento.Internal.ScsDataClient
  alias Momento.Config.Configuration, as: Configuration

  require Logger

  @moduledoc ~S"""
  Client to perform operations against a Momento cache.

  A client is created by supplying a configuration, a credential provider, and a default time-to-live:
      config = Momento.Configurations.Laptop.latest()

      credential_provider = Momento.Auth.CredentialProvider.from_env_var!("MOMENTO_AUTH_TOKEN")
      default_ttl_seconds = 60.0
      client = CacheClient.create!(config, credential_provider, default_ttl_seconds)

  The resulting struct maintains the connection and can be given to any of the CacheClient functions to make calls to Momento:
      iex> Momento.CacheClient.set(client, "cache", "key", "value")
      {:ok, %Momento.Responses.Set.Ok{}}

  """

  @typedoc """
  Contains all state necessary to connect to the Momento cache, including its configuration and connections.
  Functions that interact with a cache require it as the first argument.
  """
  @enforce_keys [
    :config,
    :credential_provider,
    :default_ttl_seconds,
    :control_client,
    :data_client
  ]
  defstruct [
    :config,
    :credential_provider,
    :default_ttl_seconds,
    :control_client,
    :data_client
  ]

  @opaque t() :: %__MODULE__{
            config: Configuration.t(),
            credential_provider: CredentialProvider.t(),
            default_ttl_seconds: number(),
            control_client: ScsControlClient.t(),
            data_client: ScsDataClient.t()
          }

  @doc """
  Create a new CacheClient instance.

  ## Parameters

  - `config`: A `%Momento.Config.Configuration{}` containing all tunable client settings.
  - `credential_provider`: A `%Momento.Auth.CredentialProvider{}` representing the credentials to connect to the server.
  - `default_ttl_seconds`: A number representing the time in seconds that a value added to the cache will persist.
    CacheClient methods that write to a cache can override this value.

  ## Raises

  - An error if the client cannot connect to momento.

  ## Returns

  - `{:ok, %Momento.CacheClient{}}` on a successful client creation.
  - `{:error, any()}` if an error occurs.
  """
  @spec create(
          config :: Configuration.t(),
          credential_provider :: CredentialProvider.t(),
          default_ttl_seconds :: number()
        ) :: {:ok, t()} | {:error, any()}
  def create(config, credential_provider, default_ttl_seconds) do
    with {:ok, control_client} <- ScsControlClient.create(credential_provider),
         {:ok, data_client} <- ScsDataClient.create(credential_provider) do
      {:ok,
       %__MODULE__{
         config: config,
         credential_provider: credential_provider,
         default_ttl_seconds: default_ttl_seconds,
         control_client: control_client,
         data_client: data_client
       }}
    end
  end

  @doc """
  Create a new CacheClient instance.

  ## Parameters

  - `config`: A `%Momento.Config.Configuration{}` containing all tunable client settings.
  - `credential_provider`: A `%Momento.Auth.CredentialProvider{}` representing the credentials to connect to the server.
  - `default_ttl_seconds`: A number representing the time in seconds that a value added to the cache will persist.
    CacheClient methods that write to a cache can override this value.

  ## Raises

  - An error if the client cannot connect to momento.

  ## Returns

  - A `%Momento.CacheClient{}` struct representing the connected client.
  """
  @spec create!(
          config :: Configuration.t(),
          credential_provider :: CredentialProvider.t(),
          default_ttl_seconds :: number()
        ) :: t()
  def create!(config, credential_provider, default_ttl_seconds) do
    result = create(config, credential_provider, default_ttl_seconds)

    case result do
      {:ok, client} -> client
      {:error, e} -> raise e
    end
  end

  @doc """
  List all caches.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.

  ## Returns

  - `{:ok, %Momento.Responses.ListCaches.Ok{caches: caches}}` on a successful listing. It contains:
    - `caches: [%Momento.Responses.CacheInfo{}]`
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.list_caches(client)
      {:ok,
      %Momento.Responses.ListCaches.Ok{
       caches: [
         %Momento.Responses.CacheInfo{
           name: "cache"
         }
       ]
      }}
  """
  @spec list_caches(client :: t()) :: ListCaches.t()
  def list_caches(client) do
    ScsControlClient.list_caches(client.control_client)
  end

  @doc """
  Create a cache if it does not exist.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache to create. Must be a string.

  ## Returns

  - `{:ok, %Momento.Responses.CreateCache.Ok{}}` on a successful create.
  - `:already_exists` if a cache with the specified name already exists.
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.create_cache(client, "cache")
      {:ok, %Momento.Responses.CreateCache.Ok{}}

      iex> Momento.CacheClient.create_cache(client, "cache")
      :already_exists
  """
  @spec create_cache(
          client :: t(),
          cache_name :: String.t()
        ) :: CreateCache.t()
  def create_cache(client, cache_name) do
    ScsControlClient.create_cache(client.control_client, cache_name)
  end

  @doc """
  Delete a cache and all items stored in it.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache to delete. Must be a string.

  ## Returns

  - `{:ok, %Momento.Responses.DeleteCache.Ok{}}` on a successful delete.
  - `{:error, error}` if an error occurs, or when deleting a cache that doesn't exist.

  ## Examples

      iex> Momento.CacheClient.delete_cache(client, "cache")
      {:ok, %Momento.Responses.DeleteCache.Ok{}}
  """
  @spec delete_cache(
          client :: t(),
          cache_name :: String.t()
        ) :: DeleteCache.t()
  def delete_cache(client, cache_name) do
    ScsControlClient.delete_cache(client.control_client, cache_name)
  end

  @doc """
  Set a value in a cache. Replaces the existing value if one is present.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache to store the value in. Must be a string.
  - `key`: The key to store the value under. Must be a binary.
  - `value`: The value to be stored. Must be a binary.

  ## Options

  - `ttl_seconds`: The time-to-live of the cache entry in seconds. Must be positive. Defaults to the client TTL.

  ## Returns

  - `{:ok, %Momento.Responses.Set.Ok{}}` on a successful set.
  - `{:error, error}` tuple if an error occurs.

  ## Examples

      iex> Momento.CacheClient.set(client, "cache", "key", "value")
      {:ok, %Momento.Responses.Set.Ok{}}

      iex> Momento.CacheClient.set(client, "cache", "key", "value", ttl_seconds: 600.0)
      {:ok, %Momento.Responses.Set.Ok{}}
  """
  @spec set(
          client :: t(),
          cache_name :: String.t(),
          key :: binary(),
          value :: binary(),
          opts :: [ttl_seconds :: number()]
        ) :: Set.t()
  def set(client, cache_name, key, value, opts \\ []) do
    ttl = Keyword.get(opts, :ttl_seconds, client.default_ttl_seconds)
    ScsDataClient.set(client.data_client, cache_name, key, value, ttl)
  end

  @doc """
  Get a value from a cache.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache to fetch the value from. Must be a string.
  - `key`: The key of the value to fetch. Must be a binary.

  ## Returns

  - `{:ok, %Momento.Responses.Get.Hit{}}` if the key exists. It contains:
    - `value: binary()`
  - `:miss` if the key does not exist.
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.set(client, "cache", "key", "value")
      {:ok, %Momento.Responses.Set.Ok{}}

      iex> Momento.CacheClient.get(client, "cache", "key")
      {:ok, %Momento.Responses.Get.Hit{value: "value"}}

      iex> Momento.CacheClient.get(client, "cache", "non-existent-key")
      :miss
  """
  @spec get(client :: t(), cache_name :: String.t(), key :: binary) :: Get.t()
  def get(client, cache_name, key) do
    ScsDataClient.get(client.data_client, cache_name, key)
  end

  @doc """
  Delete a value from the cache.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache to delete the value in. Must be a string.
  - `key`: The key to delete. Must be a binary.

  ## Returns

  - `{:ok, %Momento.Responses.Delete.Ok{}}` on a successful deletion.
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.set(client, "cache", "key", "value")
      {:ok, %Momento.Responses.Set.Ok{}}

      iex> Momento.CacheClient.delete(client, "cache", "key")
      {:ok, %Momento.Responses.Delete.Ok{}}
  """
  @spec delete(client :: t(), cache_name :: String.t(), key :: binary) :: Delete.t()
  def delete(client, cache_name, key) do
    ScsDataClient.delete(client.data_client, cache_name, key)
  end

  @doc """
  Add a value and score to a sorted set. Replaces the existing score if the value is already present.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to store the value in. Must be a string.
  - `value`: The value to be stored. Must be a binary.
  - `score`: The score of the value. Determines the value's position in the sorted set. Must be a number.

  ## Options

  - `collection_ttl`: The TTL for the sorted set in the cache. Defaults to the client TTL.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.PutElement.Ok{}}` on a successful put.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_element(client, "cache", "sorted-set", "value", 1.0)
      {:ok, %Momento.Responses.SortedSet.PutElement.Ok{}}

      iex> ttl = Momento.Requests.CollectionTtl.of(60.0)
      %Momento.Requests.CollectionTtl{ttl_seconds: 60.0, refresh_ttl: true}

      iex> Momento.CacheClient.sorted_set_put_element(client, "cache", "sorted-set", "value", 1.0, collection_ttl: ttl)
      {:ok, %Momento.Responses.SortedSet.PutElement.Ok{}}

      iex> ttl = Momento.Requests.CollectionTtl.refresh_ttl_if_provided(nil)
      %Momento.Requests.CollectionTtl{ttl_seconds: nil, refresh_ttl: false}

      iex> Momento.CacheClient.sorted_set_put_element(client, "cache", "sorted-set", "value", 1.0, collection_ttl: ttl)
      {:ok, %Momento.Responses.SortedSet.PutElement.Ok{}}
  """
  @spec sorted_set_put_element(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          value :: binary(),
          score :: number(),
          opts :: [collection_ttl :: CollectionTtl.t()]
        ) :: SortedSet.PutElement.t()
  def sorted_set_put_element(
        client,
        cache_name,
        sorted_set_name,
        value,
        score,
        opts \\ []
      ) do
    collection_ttl =
      Keyword.get(opts, :collection_ttl, CollectionTtl.of(client.default_ttl_seconds))

    case ScsDataClient.sorted_set_put_elements(
           client.data_client,
           cache_name,
           sorted_set_name,
           [{value, score}],
           collection_ttl
         ) do
      {:ok, _} -> {:ok, %Momento.Responses.SortedSet.PutElement.Ok{}}
      {:error, error} -> {:error, error}
    end
  end

  @doc """
  Add the given values and scores to a sorted set. Replaces the existing score for any value already present.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to store the value in. Must be a string.
  - `elements`: The values and scores to be stored. Must be an enum of binary to number.

  ## Options

  - `collection_ttl`: The TTL for the sorted set in the cache. Defaults to the client TTL.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}` on a successful put.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set", [{"val1", 1.0}, {"val2", 2.0}])
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set", %{"val1" => 1.0, "val2" => 2.0})
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> ttl = Momento.Requests.CollectionTtl.of(60.0)
      %Momento.Requests.CollectionTtl{ttl_seconds: 60.0, refresh_ttl: true}

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set", [{"val1", 1.0}], collection_ttl: ttl)
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}
  """
  @spec sorted_set_put_elements(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          elements :: %{binary() => number()} | [{binary(), number()}],
          opts :: [collection_ttl :: CollectionTtl.t()]
        ) :: SortedSet.PutElements.t()
  def sorted_set_put_elements(
        client,
        cache_name,
        sorted_set_name,
        elements,
        opts \\ []
      ) do
    collection_ttl =
      Keyword.get(opts, :collection_ttl, CollectionTtl.of(client.default_ttl_seconds))

    ScsDataClient.sorted_set_put_elements(
      client.data_client,
      cache_name,
      sorted_set_name,
      elements,
      collection_ttl
    )
  end

  @doc """
  Fetch the values and scores from a sorted set by rank. The returned values are ordered by their scores.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to fetch the values from. Must be a string.

  ## Options

  - `start_rank`: The inclusive 0-indexed rank of the first value. If not provided,
  the fetch starts from the beginning of the set. Must be an integer.
  - `end_rank`: The exclusive 0-indexed rank of the last value. If not provided,
  the fetch goes to the end of the set. Must be an integer.
  - `sort_order`: The order to sort the set before trimming by rank and fetching.
  Defaults to ascending. Must be :asc or :desc.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.Fetch.Hit{}}` if the sorted set exists. It contains:
    - `value: [{binary(), float()}]`
  - `:miss` if the sorted set does not exist.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set",
      ...> [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}])
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> Momento.CacheClient.sorted_set_fetch_by_rank(client, "cache", "sorted-set")
      {:ok,
      %Momento.Responses.SortedSet.Fetch.Hit{
       value: [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}]
      }}

      iex> Momento.CacheClient.sorted_set_fetch_by_rank(client, "cache", "sorted-set", sort_order: :desc)
      {:ok,
      %Momento.Responses.SortedSet.Fetch.Hit{
       value: [{"val3", 3.0}, {"val2", 2.0}, {"val1", 1.0}]
      }}

      iex> Momento.CacheClient.sorted_set_fetch_by_rank(client, "cache", "sorted-set", start_rank: 1, end_rank: 2)
      {:ok, %Momento.Responses.SortedSet.Fetch.Hit{value: [{"val2", 2.0}]}}

      iex> Momento.CacheClient.sorted_set_fetch_by_rank(client, "cache", "sorted-set", start_rank: 5, end_rank: 10)
      {:ok, %Momento.Responses.SortedSet.Fetch.Hit{value: []}}

      iex> Momento.CacheClient.sorted_set_fetch_by_rank(client, "cache", "empty-sorted-set")
      :miss
  """
  @spec sorted_set_fetch_by_rank(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          opts :: [start_rank: integer(), end_rank: integer(), sort_order: :asc | :desc]
        ) :: SortedSet.Fetch.t()
  def sorted_set_fetch_by_rank(
        client,
        cache_name,
        sorted_set_name,
        opts \\ []
      ) do
    start_rank = Keyword.get(opts, :start_rank)
    end_rank = Keyword.get(opts, :end_rank)
    sort_order = Keyword.get(opts, :sort_order, :asc)

    ScsDataClient.sorted_set_fetch_by_rank(
      client.data_client,
      cache_name,
      sorted_set_name,
      start_rank,
      end_rank,
      sort_order
    )
  end

  @doc """
  Fetch the values and scores from a sorted set by score. The returned values are ordered by their scores.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to fetch the values from. Must be a string.

  ## Options

  - `min_score`: The inclusive minimum score for a fetched value. If not provided,
  the fetch starts from the beginning of the set. Must be a number.
  - `end_rank`: The inclusive maximum score for a fetched value. If not provided,
  the fetch goes to the end of the set. Must be a number.
  - `offset`: The number of elements to skip before returning the first element.
  Must be an integer. Defaults to 0.
  - `count`: The maximum number of elements to return. Must be an integer.
  Defaults to all elements.
  - `sort_order`: The order to sort the set before trimming by rank and fetching.
  Defaults to ascending. Must be :asc or :desc.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.Fetch.Hit{}}` if the sorted set exists. It contains:
    - `value: [{binary(), float()}]`
  - `:miss` if the sorted set does not exist.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set",
      ...> [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}])
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> Momento.CacheClient.sorted_set_fetch_by_score(client, "cache", "sorted-set")
      {:ok,
      %Momento.Responses.SortedSet.Fetch.Hit{
       value: [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}]
      }}

      iex> Momento.CacheClient.sorted_set_fetch_by_score(client, "cache", "sorted-set", sort_order: :desc)
      {:ok,
      %Momento.Responses.SortedSet.Fetch.Hit{
       value: [{"val3", 3.0}, {"val2", 2.0}, {"val1", 1.0}]
      }}

      iex> Momento.CacheClient.sorted_set_fetch_by_score(client, "cache", "sorted-set", min_score: 1.1, max_score: 3.0)
      {:ok,
      %Momento.Responses.SortedSet.Fetch.Hit{value: [{"val2", 2.0}, {"val3", 3.0}]}}

      iex> Momento.CacheClient.sorted_set_fetch_by_score(client, "cache", "sorted-set", offset: 1, count: 1)
      {:ok, %Momento.Responses.SortedSet.Fetch.Hit{value: [{"val2", 2.0}]}}

      iex> Momento.CacheClient.sorted_set_fetch_by_score(client, "cache", "sorted-set", min_score: 99.9)
      {:ok, %Momento.Responses.SortedSet.Fetch.Hit{value: []}}

      iex> Momento.CacheClient.sorted_set_fetch_by_score(client, "cache", "empty-sorted-set")
      :miss
  """
  @spec sorted_set_fetch_by_score(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          opts :: [
            min_score: number(),
            max_score: number(),
            offset: integer(),
            count: integer(),
            sort_order: :asc | :desc
          ]
        ) :: SortedSet.Fetch.t()
  def sorted_set_fetch_by_score(
        client,
        cache_name,
        sorted_set_name,
        opts \\ []
      ) do
    min_score = Keyword.get(opts, :min_score)
    max_score = Keyword.get(opts, :max_score)
    offset = Keyword.get(opts, :offset)
    count = Keyword.get(opts, :count)
    sort_order = Keyword.get(opts, :sort_order, :asc)

    ScsDataClient.sorted_set_fetch_by_score(
      client.data_client,
      cache_name,
      sorted_set_name,
      min_score,
      max_score,
      offset,
      count,
      sort_order
    )
  end

  @doc """
  Remove an element from a sorted set.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to remove the value from. Must be a string.
  - `value`: The value to be removed. Must be a binary.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.RemoveElement.Ok{}}` on a successful put.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_remove_element(client, "cache", "sorted-set", "value")
      {:ok, %Momento.Responses.SortedSet.RemoveElement.Ok{}}

  """
  @spec sorted_set_remove_element(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          value :: binary()
        ) :: Momento.Responses.SortedSet.RemoveElement.t()
  def sorted_set_remove_element(
        client,
        cache_name,
        sorted_set_name,
        value
      ) do
    case ScsDataClient.sorted_set_remove_elements(
           client.data_client,
           cache_name,
           sorted_set_name,
           [value]
         ) do
      {:ok, _} -> {:ok, %Momento.Responses.SortedSet.RemoveElement.Ok{}}
      {:error, error} -> {:error, error}
    end
  end

  @doc """
  Remove multiple elements from a sorted set.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to remove the values from. Must be a string.
  - `values`: The value to be removed. Must be a list of binaries.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.RemoveElements.Ok{}}` on a successful put.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_remove_elements(client, "cache", "sorted-set", ["value1", "value2"])
      {:ok, %Momento.Responses.SortedSet.RemoveElements.Ok{}}

  """
  @spec sorted_set_remove_elements(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          values :: [binary()]
        ) :: Momento.Responses.SortedSet.RemoveElements.t()
  def sorted_set_remove_elements(
        client,
        cache_name,
        sorted_set_name,
        values
      ) do
    ScsDataClient.sorted_set_remove_elements(
      client.data_client,
      cache_name,
      sorted_set_name,
      values
    )
  end

  @doc """
  Get the rank of a value in a sorted set.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to get the rank from. Must be a string.
  - `value`: The value to check the rank of. Must be a binary.

  ## Options

  - `sort_order`: The order to sort the set before finding the rank of the value.
  Defaults to ascending. Must be :asc or :desc.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.GetRank.Hit{}}` if the value exists. It contains:
    - `rank: integer()`
  - `:miss` if the value does not exist.
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set",
      ...> [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}])
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> Momento.CacheClient.sorted_set_get_rank(client, "cache", "sorted-set", "val1")
      {:ok, %Momento.Responses.SortedSet.GetRank.Hit{rank: 0}}

      iex> Momento.CacheClient.sorted_set_get_rank(client, "cache", "sorted-set", "val1", sort_order: :desc)
      {:ok, %Momento.Responses.SortedSet.GetRank.Hit{rank: 2}}

      iex> Momento.CacheClient.sorted_set_get_rank(client, "cache", "sorted-set", "non-existent-value")
      :miss
  """
  @spec sorted_set_get_rank(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          value :: binary(),
          opts :: [sort_order: :asc | :desc]
        ) :: Momento.Responses.SortedSet.GetRank.t()
  def sorted_set_get_rank(
        client,
        cache_name,
        sorted_set_name,
        value,
        opts \\ []
      ) do
    sort_order = Keyword.get(opts, :sort_order, :asc)

    ScsDataClient.sorted_set_get_rank(
      client.data_client,
      cache_name,
      sorted_set_name,
      value,
      sort_order
    )
  end

  @doc """
  Get the score of a value in a sorted set.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to get the score from. Must be a string.
  - `value`: The value to check the score of. Must be a binary.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.GetScore.Hit{}}` if the value exists. It contains:
    - `score: float()`
  - `:miss` if the value does not exist.
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set",
      ...> [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}])
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> Momento.CacheClient.sorted_set_get_score(client, "cache", "sorted-set", "val1")
      {:ok, %Momento.Responses.SortedSet.GetScore.Hit{score: 1.0}}

      iex> Momento.CacheClient.sorted_set_get_score(client, "cache", "sorted-set", "non-existent-value")
      :miss
  """
  @spec sorted_set_get_score(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          value :: binary()
        ) :: Momento.Responses.SortedSet.GetScore.t()
  def sorted_set_get_score(
        client,
        cache_name,
        sorted_set_name,
        value
      ) do
    ScsDataClient.sorted_set_get_score(
      client.data_client,
      cache_name,
      sorted_set_name,
      value
    )
  end

  @doc """
  Get the scores of the given values in a sorted set.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to get the score from. Must be a string.
  - `values`: The value to check the score of. Must be a list of binaries.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.GetScores.Hit{}}` if the value exists. It contains:
    - `value: [{binary(), float() | nil}]`
  - `:miss` if the sorted set does not exist.
  - `{:error, error}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_put_elements(client, "cache", "sorted-set",
      ...> [{"val1", 1.0}, {"val2", 2.0}, {"val3", 3.0}])
      {:ok, %Momento.Responses.SortedSet.PutElements.Ok{}}

      iex> Momento.CacheClient.sorted_set_get_scores(client, "cache", "sorted-set", ["val1", "val2"])
      {:ok,
      %Momento.Responses.SortedSet.GetScores.Hit{
       value: [{"val1", 1.0}, {"val2", 2.0}]
      }}

      iex> Momento.CacheClient.sorted_set_get_scores(client, "cache", "sorted-set", ["non-existent-value"])
      {:ok,
      %Momento.Responses.SortedSet.GetScores.Hit{
       value: [{"non-existent-value", nil}]
      }}

      iex> Momento.CacheClient.sorted_set_get_scores(client, "cache", "non-existent-set", ["val1"])
      :miss
  """
  @spec sorted_set_get_scores(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          values :: [binary()]
        ) :: Momento.Responses.SortedSet.GetScores.t()
  def sorted_set_get_scores(
        client,
        cache_name,
        sorted_set_name,
        values
      ) do
    ScsDataClient.sorted_set_get_scores(
      client.data_client,
      cache_name,
      sorted_set_name,
      values
    )
  end

  @doc """
  Increments the score of a value in a sorted set. Adds the value if it is not present.

  ## Parameters

  - `client`: A `%Momento.CacheClient{}` representing the connected client.
  - `cache_name`: The name of the cache containing the sorted set. Must be a string.
  - `sorted_set_name`: The name of the sorted set to increment the value in. Must be a string.
  - `value`: The value to be incremented. Must be a binary.
  - `amount`: The amount to increment the value's score Must be a number.

  ## Options

  - `collection_ttl`: The TTL for the sorted set in the cache. Defaults to the client TTL.

  ## Returns

  - `{:ok, %Momento.Responses.SortedSet.IncrementScore.Ok{}}` on a successful increment.
  - `{:error, %Momento.Error{}}` if an error occurs.

  ## Examples

      iex> Momento.CacheClient.sorted_set_get_score(client, "cache", "sorted-set", "value")
      :miss

      iex> Momento.CacheClient.sorted_set_increment_score(client, "cache", "sorted-set", "value", 1.0)
      {:ok, %Momento.Responses.SortedSet.IncrementScore.Ok{score: 1.0}}

      iex> Momento.CacheClient.sorted_set_get_score(client, "cache", "sorted-set", "value")
      {:ok, %Momento.Responses.SortedSet.GetScore.Hit{score: 1.0}}
  """
  @spec sorted_set_increment_score(
          client :: t(),
          cache_name :: String.t(),
          sorted_set_name :: String.t(),
          value :: binary(),
          amount :: number(),
          opts :: [collection_ttl :: CollectionTtl.t()]
        ) :: Momento.Responses.SortedSet.IncrementScore.t()
  def sorted_set_increment_score(
        client,
        cache_name,
        sorted_set_name,
        value,
        amount,
        opts \\ []
      ) do
    collection_ttl =
      Keyword.get(opts, :collection_ttl, CollectionTtl.of(client.default_ttl_seconds))

    ScsDataClient.sorted_set_increment_score(
      client.data_client,
      cache_name,
      sorted_set_name,
      value,
      amount,
      collection_ttl
    )
  end
end