fix: Spear.append/3 raw?: true raw return (#97)

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, 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

@@ -7,6 +7,8 @@ defmodule SpearTest do
   import Spear.Uuid, only: [uuid_v4: 0]
   import VersionHelper
 
+  require Spear.Records.Streams, as: Streams
+
   @max_append_bytes 1_048_576
   @checkpoint_after 32 * 32 * 32
 
@@ -923,6 +925,31 @@ 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
+      result =
+        random_events()
+        |> Stream.take(7)
+        |> Spear.append(c.conn, c.stream_name, expect: :empty, raw?: true)
+
+      assert {:ok, Streams.append_resp(result: {:success, _})} = result
+    end
+
+    test "the append/3 with `raw?: true` returns expectation error as raw", c do
+      result =
+        random_events()
+        |> Stream.take(1)
+        |> Spear.append(c.conn, c.stream_name, expect: 9999, raw?: true)
+
+      assert {:ok, Streams.append_resp(result: {:wrong_expected_version, _})} = 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 +1005,48 @@ defmodule SpearTest do
       assert Spear.stream!(c.conn, c.stream_name) |> Enum.map(& &1.body) == Enum.to_list(0..19)
     end
 
+    @tag compatible(">= 21.6.0")
+    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
+
+    @tag compatible(">= 21.6.0")
+    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, Streams.batch_append_resp_success()} = 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} =