Spear.Client behaviour (Spear v0.1.3) View Source
A macro for defining a module which represents a connection to an EventStoreDB
Like an Ecto.Repo
or an Extreme
client, this macro allows you to call
functions on the module representing the connection instead of passing
the connection pid or name as an argument to functions in Spear
. This
can be useful for client connections central to a service. All callbacks
provided by this module are implemented on clients created with
use Spear.Client
.
This pattern can be useful for applications which depend on an EventStoreDB
connection similar to applications which depend on a (e.g.) PostgreSQL
connection via Ecto.Repo
. Writing clients as modules provides an
intuitive "is-a" interface (e.g. "MyEventStoreClient
is an EventStoreDB
client"). Since this module defines a complete behaviour for a client
module, mocking calls to the EventStoreDB is easy via a test dependency
like the wonderful Dashbit library Mox
.
If a service does not know which connections it may need until runtime, the
functions in Spear may be used with a connection processes spawned via
DynamicSupervisor.start_child/2
instead.
Configuration
The __using__/1
macro defined by this module takes an optional :otp_app
option. If provided, a helper clause for the start_link/1
callback will
be injected which will fetch configuration for the connection from
Application.get_env(otp_app, __MODULE__)
, if available.
Otherwise configuration for the connection may be passed through arguments
to start_link/1
.
Examples
defmodule MyEventStoreClient do
use Spear.Client, otp_app: :my_app
end
[MyEventStoreClient] |> Supervisor.start_link(strategy: :one_for_one)
iex> MyEventStoreClient.stream!(:all) |> Enum.take(1)
[%Spear.Event{}]
Link to this section Summary
Callbacks
A wrapper around Spear.append/3
A wrapper around Spear.append/4
A wrapper around Spear.cancel_subscription/2
A wrapper around Spear.delete_stream/2
A wrapper around Spear.delete_stream/3
A wrapper around Spear.ping/1
A wrapper around Spear.ping/2
A wrapper around Spear.read_stream/2
A wrapper around Spear.read_stream/3
Starts a client as part of a supervision tree.
A wrapper around Spear.stream!/2
A wrapper around Spear.stream!/3
A wrapper around Spear.subscribe/3
A wrapper around Spear.subscribe/4
Link to this section Callbacks
Specs
append(event_stream :: Enumerable.t(), stream_name :: String.t()) :: :ok | {:error, any()}
A wrapper around Spear.append/3
Specs
append( event_stream :: Enumerable.t(), stream_name :: String.t(), opts :: Keyword.t() ) :: :ok | {:error, any()}
A wrapper around Spear.append/4
Specs
A wrapper around Spear.cancel_subscription/2
cancel_subscription(subscription_reference, timeout)
View Source (since 0.1.0)Specs
A wrapper around Spear.cancel_subscription/3
Specs
A wrapper around Spear.delete_stream/2
Specs
A wrapper around Spear.delete_stream/3
Specs
ping() :: :pong | {:error, any()}
A wrapper around Spear.ping/1
Specs
A wrapper around Spear.ping/2
Specs
read_stream(stream_name :: String.t() | :all) :: {:ok, Enumerable.t()} | {:error, any()}
A wrapper around Spear.read_stream/2
Specs
read_stream(stream_name :: String.t() | :all, opts :: Keyword.t()) :: {:ok, Enumerable.t()} | {:error, any()}
A wrapper around Spear.read_stream/3
Specs
start_link(args :: Keyword.t()) :: GenServer.on_start()
Starts a client as part of a supervision tree.
This function is defaulted to pull connection parameters from application
config or from the args
Examples
# lib/my_app/application.ex
[
{MyEventStoreClient, connection_string: "esdb://localhost:2113"},
..
]
|> Supervisor.start_link(strategy: :one_for_one)
Specs
stream!(stream_name :: String.t() | :all) :: Enumerable.t()
A wrapper around Spear.stream!/2
Specs
stream!(stream_name :: String.t() | :all, opts :: Keyword.t()) :: Enumerable.t()
A wrapper around Spear.stream!/3
Specs
subscribe( subscriber :: pid() | GenServer.name(), stream_name :: String.t() | :all ) :: {:ok, reference()} | {:error, any()}
A wrapper around Spear.subscribe/3
Specs
subscribe( subscriber :: pid() | GenServer.name(), stream_name :: String.t() | :all, opts :: Keyword.t() ) :: {:ok, reference()} | {:error, any()}
A wrapper around Spear.subscribe/4