Spear.Client behaviour (Spear v0.1.4) 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

Link to this section Callbacks

Link to this callback

append(event_stream, stream_name)

View Source (since 0.1.0)

Specs

append(event_stream :: Enumerable.t(), stream_name :: String.t()) ::
  :ok | {:error, any()}

A wrapper around Spear.append/3

Link to this callback

append(event_stream, stream_name, opts)

View Source (since 0.1.0)

Specs

append(
  event_stream :: Enumerable.t(),
  stream_name :: String.t(),
  opts :: Keyword.t()
) :: :ok | {:error, any()}

A wrapper around Spear.append/4

Link to this callback

cancel_subscription(subscription_reference)

View Source (since 0.1.0)

Specs

cancel_subscription(subscription_reference :: reference()) ::
  :ok | {:error, any()}

A wrapper around Spear.cancel_subscription/2

Link to this callback

cancel_subscription(subscription_reference, timeout)

View Source (since 0.1.0)

Specs

cancel_subscription(subscription_reference :: reference(), timeout()) ::
  :ok | {:error, any()}

A wrapper around Spear.cancel_subscription/3

Link to this callback

delete_stream(stream_name)

View Source (since 0.1.0)

Specs

delete_stream(stream_name :: String.t()) :: :ok | {:error, any()}

A wrapper around Spear.delete_stream/2

Link to this callback

delete_stream(stream_name, opts)

View Source (since 0.1.0)

Specs

delete_stream(stream_name :: String.t(), opts :: Keyword.t()) ::
  :ok | {:error, any()}

A wrapper around Spear.delete_stream/3

Specs

ping() :: :pong | {:error, any()}

A wrapper around Spear.ping/1

Link to this callback

ping(timeout)

View Source (since 0.1.2)

Specs

ping(timeout()) :: :pong | {:error, any()}

A wrapper around Spear.ping/2

Link to this callback

read_stream(stream_name)

View Source (since 0.1.0)

Specs

read_stream(stream_name :: String.t() | :all) ::
  {:ok, Enumerable.t()} | {:error, any()}

A wrapper around Spear.read_stream/2

Link to this callback

read_stream(stream_name, opts)

View Source (since 0.1.0)

Specs

read_stream(stream_name :: String.t() | :all, opts :: Keyword.t()) ::
  {:ok, Enumerable.t()} | {:error, any()}

A wrapper around Spear.read_stream/3

Link to this callback

start_link(args)

View Source (optional) (since 0.1.0)

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)
Link to this callback

stream!(stream_name)

View Source (since 0.1.0)

Specs

stream!(stream_name :: String.t() | :all) :: Enumerable.t()

A wrapper around Spear.stream!/2

Link to this callback

stream!(stream_name, opts)

View Source (since 0.1.0)

Specs

stream!(stream_name :: String.t() | :all, opts :: Keyword.t()) :: Enumerable.t()

A wrapper around Spear.stream!/3

Link to this callback

subscribe(subscriber, stream_name)

View Source (since 0.1.0)

Specs

subscribe(
  subscriber :: pid() | GenServer.name(),
  stream_name :: String.t() | :all
) :: {:ok, reference()} | {:error, any()}

A wrapper around Spear.subscribe/3

Link to this callback

subscribe(subscriber, stream_name, opts)

View Source (since 0.1.0)

Specs

subscribe(
  subscriber :: pid() | GenServer.name(),
  stream_name :: String.t() | :all,
  opts :: Keyword.t()
) :: {:ok, reference()} | {:error, any()}

A wrapper around Spear.subscribe/4