goblin

defprotocol Goblin.Tx do
  @moduledoc """
  Transaction helpers for working with Goblin database transactions.

  ## Usage

      Goblin.transaction(db, fn tx ->
        user = Goblin.Tx.get(tx, :user_123)
        
        if user do
          updated = Map.update!(user, :login_count, &(&1 + 1))
          tx = Goblin.Tx.put(tx, :user_123, updated)
          {:commit, tx, :ok}
        else
          :abort
        end
      end)

      Goblin.read(db, fn tx -> 
        key1 = Goblin.Tx.get(tx, :start, 0)
        key2 = Goblin.Tx.get(tx, key1)
        {key1, key2}
      end)
  """

  @type t :: t()
  @type return :: {:commit, Goblin.Tx.t(), term()} | :abort

  @doc """
  Writes a key-value pair within a transaction.

  ## Parameters

  - `tx` - The transaction struct
  - `key` - Any Elixir term to use as the key
  - `value` - Any Elixir term to store

  ## Returns

  - Updated transaction struct

  ## Examples

      tx = Goblin.Tx.put(tx, :user, %{name: "Alice"})
  """
  @spec put(t(), Goblin.db_key(), Goblin.db_value()) :: t()
  def put(tx, key, value)

  @doc """
  Writes key-value pairs within a transaction.

  ## Parameters

  - `tx` - The transaction struct
  - `pairs` - The key-value pairs

  ## Returns

  - Updated transaction structj

  ## Examples

      tx = Goblin.Tx.put_multi(tx, [user1: %{name: "Alice"}, user2: %{name: "Bob"}])
  """
  @spec put_multi(t(), [{Goblin.db_key(), Goblin.db_value()}]) :: t()
  def put_multi(tx, pairs)

  @doc """
  Removes a key within a transaction.

  ## Parameters

  - `tx` - The transaction struct
  - `key` - The key to remove

  ## Returns

  - Updated transaction struct

  ## Examples

      tx = Goblin.Tx.remove(tx, :user)
  """
  @spec remove(t(), Goblin.db_key()) :: t()
  def remove(tx, key)

  @doc """
  Removes keys within a transaction.

  ## Parameters

  - `tx` - The transaction struct
  - `keys` - The list of keys to remove

  ## Returns

  - Updated transaction struct

  ## Examples

      tx = Goblin.Tx.remove_multi(tx, [:user1, :user2])
  """
  @spec remove_multi(t(), [Goblin.db_key()]) :: t()
  def remove_multi(tx, keys)

  @doc """
  Retrieves a value within a transaction.

  ## Parameters

  - `tx` - The transaction struct
  - `key` - The key to look up
  - `default` - A default value if the key is not found, defaults to `nil`

  ## Returns

  - The value associated with the key, or `default` if not found

  ## Examples

      counter = Goblin.Tx.get(tx, :counter, 0)
  """
  @spec get(t(), Goblin.db_key(), term()) :: Goblin.db_value()
  def get(tx, key, default \\ nil)

  @doc """
  Retrieves key-value pairs associated with the provided list of keys.

  ## Parameters

  - `tx` - The transaction struct
  - `keys` - A list of keys to look up

  ## Returns

  - Key-value pairs

  ## Examples

      [user1: %{name: "Alice"}, user2: %{name: "Bob"}] = Goblin.Tx.get_multi(tx, [:user1, :user2])
  """
  @spec get_multi(t(), [Goblin.db_key()]) :: [{Goblin.db_key(), Goblin.db_value()}]
  def get_multi(tx, keys)

  @doc """
  Retrieves a stream over key-value pairs sorted in ascending order by key.

  ## Parameters

  - `tx` - The transaction struct
  - `opts` - A keyword list with two options:
    - `:min` - The minimum key to range over
    - `:max` - The maximum key to range over

  ## Examples

      [user1: %{name: "Alice"}, user2: %{name: "Bob"}] = Goblin.Tx.select(tx) |> Enum.to_list()

      [user1: %{name: "Alice"}] = Goblin.Tx.select(tx, max: :user1) |> Enum.to_list()

      [user2: %{name: "Bob"}] = Goblin.Tx.select(tx, min: :user2) |> Enum.to_list()

      [user1: %{name: "Alice"}, user2: %{name: "Bob"}] = Goblin.Tx.select(tx, min: :user1, max: :user2) |> Enum.to_list()
  """
  @spec select(t(), keyword()) :: Enumerable.t({Goblin.db_key(), Goblin.db_value()})
  def select(tx, opts \\ [])
end