@spec authenticate_request(t(), Electric.Client.Fetch.Request.t()) ::
  Electric.Client.Fetch.Request.authenticated()

Authenticate the given request using the authenticator configured in the Client.

@spec authenticate_shape(t(), Electric.Client.ShapeDefinition.t()) ::
  Electric.Client.Authenticator.headers()

Get authentication query parameters for the given Elixir.Electric.Client.ShapeDefinition.

Use the given client to delete the shape instance from the server.

Delete shape only works if Electric is configured to allow_shape_deletion.

@spec embedded(Electric.Shapes.Api.options()) :: {:ok, t()} | {:error, term()}

Get a client instance that runs against an embedded instance of electric, that is an electric app running as a dependency of the current application.

@spec new(client_options()) :: {:ok, t()} | {:error, term()}

Create a new client.

Options

• :base_url - The URL of the electric server, not including the path. E.g. for local development this would be http://localhost:3000.

• :endpoint - The full URL of the shape API endpoint. E.g. for local development this would be http://localhost:3000/v1/shape. Use this if you need a non-standard API path.

• :params (map of atom/0 keys and term/0 values) - Additional query parameters to include in every request to the Electric backend. The default value is %{}.

• :parser - A {module, args} tuple specifying the Electric.Client.ValueMapper implementation to use for mapping values from the sync stream into Elixir terms. The default value is {Electric.Client.ValueMapper, []}.

• :fetch - A {module, opts} tuple specifying the Electric.Client.Fetch implementation to use for calling the Electric API.

  See Electric.Client.Fetch.HTTP for the options available when using the default HTTP fetcher.

   Client.new(
     base_url: "http://localhost:3000",
     fetch: {Electric.Client.Fetch.HTTP,
       # never error, just keep retrying if the Electric server is down
       timeout: :infinity,
       # add a bearer token to every request (see `authenticator` if you need more
       # control over authenticating your requests
       headers: [{"authorize", "Bearer some-token-here"}]}
   )

  The default value is {Electric.Client.Fetch.HTTP, []}.

:base_url vs. :endpoint

If you configure your client using e.g. base_url: "http://localhost:3000" Electric will append the default shape API path "/v1/shape" to create the final endpoint configuration, in this case "http://localhost:3000/v1/shape".

If you wish to use a non-standard endpoint path because, for example, you wrap your Shape API calls in an authentication proxy, then configure the endpoint directly:

Client.new(endpoint: "https://my-server.my-domain.com/electric/shape/proxy")

@spec new!(client_options()) :: t() | no_return()

Create a new client with the given options or raise if the configuration is invalid.

@spec shape(String.t(), Electric.Client.ShapeDefinition.options()) ::
  {:ok, Electric.Client.ShapeDefinition.t()} | {:error, term()}

A shortcut to ShapeDefinition.new/2.

iex> Elixir.Client.shape("my_table")
{:ok, %Electric.Client.ShapeDefinition{table: "my_table"}}

@spec shape!(ecto_shape()) :: Electric.Client.ShapeDefinition.t() | no_return()

Create a ShapeDefinition from an Ecto query.

Accepts any implementation of Ecto.Queryable (e.g. an %Ecto.Query{} struct or Ecto.Schema module) to generate a ShapeDefinition.

iex> query = from(t in MyApp.Todo, where: t.completed == false)
iex> Elixir.Client.shape!(query)
%Electric.Client.ShapeDefinition{table: "todos", where: "(\"completed\" = FALSE)"}

Also takes an Ecto.Changeset or 1-arity function returning an Ecto.Changeset:

iex> Elixir.Client.shape!(&MyApp.Todo.changeset/1)
%Electric.Client.ShapeDefinition{table: "todos", columns: ["title", "completed"]}

Values from the Electric change stream will be mapped to instances of the passed Ecto.Schema module.

Column subsets

Specifying a subset of columns to stream can be done in two ways:

1. Passing a changeset will filter the table columns according to the applied validations so if you want a shape to include a column, you must ensure that it has some kind of validation, using e.g. Ecto.Changeset.validate_required/2

2. Using Ecto.Query.select/3 to select a subset of columns within the query:

   Electric.Client.shape!( from(t in MyApp.Todo, where: t.completed == false, select: [:id, :title]) )

select/3 allows for various ways to specify the columns, we only support the following forms:

• select(Todo, [t], [:id, :name])
• select(Todo, [t], [t.id, t.name])
• select(Todo, [t], {t.id, t.name})
• select(Todo, [t], struct(t, [:id, :name]))
• select(Todo, [t], map(t, [:id, :name]))

You definitely can't add virtual columns like this:

• select(Todo, [t], map(t, %{t | reason: "here"}))

We also support Ecto.Query.select_merge/3 to add additional columns:

• select(Todo, [t], map(t, [:id, :name])) |> select_merge([:completed])

@spec shape!(String.t(), Electric.Client.ShapeDefinition.options()) ::
  Electric.Client.ShapeDefinition.t() | no_return()

A shortcut to ShapeDefinition.new!/2.

@spec stream(t(), stream_options()) :: Enumerable.t(message())

@spec stream(t(), Electric.Client.ShapeDefinition.t()) :: Enumerable.t(message())

@spec stream(t(), String.t() | ecto_shape()) :: Enumerable.t(message())

@spec stream(String.t(), stream_options()) :: Enumerable.t(message())

Get a stream of update messages.

This accepts a variety of arguments:

Examples:

• Using a custom endpoint that returns a pre-defined shape.

  If you have used Electric.Phoenix to mount a pre-defined shape into your Phoenix application, then by creating a client with the endpoint set to the URL of this route you can stream data directly from this client:

  {:ok, client} = Electric.Client.new(endpoint: "http://localhost:4000/shapes/todo")
  stream = Electric.Client.stream(client)

  Equivalently you can just pass the URL as the argument to stream:

  stream = Electric.Client.stream("http://localhost:4000/shapes/todo")

• Using a simple table name to define a shape:

  {:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")
  stream = Electric.Client.stream(client, "todos")

• Using a full shape definition:

  {:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")
  {:ok, shape} = Electric.Client.shape("todos", where: "completed = false", replica: :full)
  stream = Electric.Client.stream(client, shape)

• Or with an Ecto query or Ecto.Schema struct:

  {:ok, client} = Electric.Client.new(base_url: "http://localhost:3000")
  stream = Electric.Client.stream(client, from(t in MyApp.Todos.Todo, where: t.completed == false))

If you want to pass options to your stream, then pass them as the second argument or use stream/3.

@spec stream(t(), shape(), stream_options()) :: Enumerable.t(message())

Use the client to return a stream of update messages for the given shape.

shape can be a table name, e.g. "my_table", a full ShapeDefinition including a table name and where clause, or (if Ecto is installed) an Ecto.Queryable instance, such as an Ecto.Query or a Ecto.Schema struct.

Options

• :parser - A {module, args} tuple specifying the Electric.Client.ValueMapper implementation to use for mapping values from the sync stream into Elixir terms. The default value is nil.

• :live (boolean/0) - If true (the default) reads an infinite stream of update messages from the server. The default value is true.

• :replica - Instructs the server to send just the changed columns for an update (:modified) or the full row (:full). The default value is :default.

• :resume - Resume the stream from the given point. Message.ResumeMessage messages are appended to the change stream if you terminate it early using live: false

• :errors - How errors from the Electric server should be handled.

  • :raise (default) - raise an exception if the server returns an error
  • :stream - put the error into the message stream (and terminate)

  The default value is :raise.

@spec url(t(), Electric.Client.Fetch.Request.attrs()) :: binary()

Return an authenticated URL for the given request attributes.