fix: Spear.append/3 raw?: true raw return

Issue #96

Passing a `raw?: true` option to `Spear.append/3` or `Spear.Client/append`
continued to return `:ok` instead of `{:ok, AppendResp.t()}`.

This contradicted the docs and the `Spear.append_batch/5` behaviour.

Solution:

This commit adds the conditional case in `Spear.append/3`
to return `{:ok, AppendResp.t()}` when `raw?` is `true`.

`Spear.Client.append` will also be fixed as a result.

Additional Notes:

* Added to `SpearTest`: to test `append/3` for both raw true and false
* Added to `SpearTest`: to test `append_batch/5` for both raw true and false.
* Updated the `Spear.append/3` type spec to add the missing
  `{:ok, AppendResp.t()}` return type.
* Updated the `Spear.Client.append/3` and `Spear.Client.append/4`
  callback specs to add the missing `{:ok, AppendResp.t()}` return type.

lib/spear.ex

@@ -390,7 +390,8 @@ defmodule Spear do
           connection :: Spear.Connection.t(),
           stream_name :: String.t(),
           opts :: Keyword.t()
-        ) :: :ok | {:error, reason :: Spear.ExpectationViolation.t() | any()}
+        ) ::
+          :ok | {:ok, AppendResp.t()} | {:error, reason :: Spear.ExpectationViolation.t() | any()}
   def append(event_stream, conn, stream_name, opts \\ []) when is_binary(stream_name) do
     default_write_opts = [
       expect: :any,
@@ -400,6 +401,7 @@ defmodule Spear do
 
     opts = default_write_opts |> Keyword.merge(opts)
     params = Enum.into(opts, %{})
+    raw? = Keyword.get(opts, :raw?, false)
 
     messages =
       [Spear.Writing.build_append_request(params)]
@@ -413,6 +415,9 @@ defmodule Spear do
            messages,
            Keyword.take(opts, [:credentials, :timeout])
          ) do
+      {:ok, Streams.append_resp(result: {:success, _} = response)} when raw? == true ->
+        {:ok, response}
+
       {:ok, Streams.append_resp(result: {:success, _})} ->
         :ok
 

lib/spear/client.ex

@@ -67,14 +67,14 @@ defmodule Spear.Client do
   """
   @doc since: "0.1.0"
   @callback append(event_stream :: Enumerable.t(), stream_name :: String.t()) ::
-              :ok | {:error, any()}
+              :ok | {:ok, AppendResp.t()} | {:error, any()}
 
   @doc """
   A wrapper around `Spear.append/4`
   """
   @doc since: "0.1.0"
   @callback append(event_stream :: Enumerable.t(), stream_name :: String.t(), opts :: Keyword.t()) ::
-              :ok | {:error, any()}
+              :ok | {:ok, AppendResp.t()} | {:error, any()}
 
   @doc """
   A wrapper around `Spear.append_batch/4`

test/spear_test.exs

@@ -923,6 +923,25 @@ defmodule SpearTest do
       assert Spear.cancel_subscription(c.conn, subscription) == :ok
     end
 
+    test "the append/3 with `raw?: false` returns :ok", c do
+      assert :ok =
+               random_events()
+               |> Stream.take(7)
+               |> Spear.append(c.conn, c.stream_name, expect: :empty, raw?: false)
+    end
+
+    test "the append/3 with `raw?: true` returns the raw result", c do
+      assert {:ok, result} =
+               random_events()
+               |> Stream.take(7)
+               |> Spear.append(c.conn, c.stream_name, expect: :empty, raw?: true)
+
+      assert {:success,
+              {:"event_store.client.streams.AppendResp.Success", {:current_revision, 6},
+               {:position, {:"event_store.client.streams.AppendResp.Position", _p1, _p2}}}} =
+               result
+    end
+
     @tag compatible(">= 21.6.0")
     test "append_batch/5 appends a batch of events", c do
       assert {:ok, batch_id, request_id} =
@@ -978,6 +997,49 @@ defmodule SpearTest do
       assert Spear.stream!(c.conn, c.stream_name) |> Enum.map(& &1.body) == Enum.to_list(0..19)
     end
 
+    test "the append_batch/5 with `raw?: false` returns :ok", c do
+      assert {:ok, batch_id, request_id} =
+               random_events()
+               |> Stream.take(5)
+               |> Spear.append_batch(c.conn, :new, c.stream_name, expect: :empty, raw?: false)
+
+      assert_receive %Spear.BatchAppendResult{
+        result: result,
+        batch_id: ^batch_id,
+        request_id: ^request_id,
+        revision: 4
+      }
+
+      assert :ok = result
+
+      assert Spear.cancel_subscription(c.conn, request_id) == :ok
+
+      assert Spear.stream!(c.conn, c.stream_name) |> Enum.map(& &1.body) == Enum.to_list(0..4)
+    end
+
+    test "the append_batch/5 with `raw?: true` returns the raw result", c do
+      assert {:ok, batch_id, request_id} =
+               random_events()
+               |> Stream.take(5)
+               |> Spear.append_batch(c.conn, :new, c.stream_name, expect: :empty, raw?: true)
+
+      assert_receive %Spear.BatchAppendResult{
+        result: result,
+        batch_id: ^batch_id,
+        request_id: ^request_id,
+        revision: 4
+      }
+
+      assert {:success,
+              {:"event_store.client.streams.BatchAppendResp.Success", {:current_revision, 4},
+               {:position, {:"event_store.client.AllStreamPosition", _p1, _p2}}}} =
+               result
+
+      assert Spear.cancel_subscription(c.conn, request_id) == :ok
+
+      assert Spear.stream!(c.conn, c.stream_name) |> Enum.map(& &1.body) == Enum.to_list(0..4)
+    end
+
     @tag compatible(">= 21.6.0")
     test "append_batch/5 can fragment with the :done? flag and :batch_id", c do
       assert {:ok, batch_id, request_id} =