Yex.Awareness (y_ex v0.13.0)

Copy Markdown View Source

Awareness is an optional feature that works well together with Yjs.

Summary

Functions

Applies an update (incoming from remote channel or generated using [Awareness.encode_update] method) and modifies a state of a current instance.

Clears the local state of the current client, marking it as offline for other clients.

Returns the client ID of the local client, which is the client ID of the underlying document.

Stop monitoring awareness changes started with monitor_change/2.

Stop monitoring awareness updates started with monitor_update/2.

Encodes the states of the given clients into an awareness update binary that can be sent to remote peers and applied with apply_update/3. When clients is nil, the states of all known clients are encoded. Raises ArgumentError when a client id is outside 0..9007199254740991.

Returns the IDs of all clients that currently have a state, including the local client.

get local state of the current client

Returns the states of all known clients, keyed by client ID.

Listen to remote and local state changes. Get notified when a state is either added, updated, or removed. You can pass metadata as an option. This value is passed as the fourth element of the message.If omitted, it will be passed as a structure of awareness itself.

Monitor to remote and local awareness changes. This event is called even when the awareness state does not change but is only updated to notify other users that this client is still online. Use this event if you want to propagate awareness state to other users. You can pass metadata as an option. This value is passed as the fourth element of the message.If omitted, it will be passed as a structure of awareness itself.

create a new awareness instance

Clears out a state of a given client, effectively marking it as disconnected. Raises ArgumentError, removing no state, when a client id is outside 0..9007199254740991.

Sets the local state of the current client and notifies monitors.

Types

t()

@type t() :: %Yex.Awareness{reference: reference()}

Functions

apply_update(awareness, update, origin \\ nil)

@spec apply_update(t(), binary(), origin :: term() | nil) :: :ok

Applies an update (incoming from remote channel or generated using [Awareness.encode_update] method) and modifies a state of a current instance.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.new())
iex> Yex.Awareness.clean_local_state(awareness)
iex> Yex.Awareness.apply_update(awareness, <<1, 210, 165, 202, 167, 8, 1, 2, 123, 125>>)
:ok
iex> Yex.Awareness.get_client_ids(awareness)
[2230489810]

clean_local_state(awareness)

@spec clean_local_state(t()) :: :ok

Clears the local state of the current client, marking it as offline for other clients.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 100 }))
iex> Yex.Awareness.clean_local_state(awareness)
iex> Yex.Awareness.get_client_ids(awareness)
[]

client_id(awareness)

@spec client_id(t()) :: integer()

Returns the client ID of the local client, which is the client ID of the underlying document.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 100 }))
iex> Yex.Awareness.client_id(awareness)
100

demonitor_change(ref)

@spec demonitor_change(reference()) :: :ok

Stop monitoring awareness changes started with monitor_change/2.

demonitor_update(ref)

@spec demonitor_update(reference()) :: :ok

Stop monitoring awareness updates started with monitor_update/2.

encode_update(awareness, clients \\ nil)

@spec encode_update(t(), [integer()] | nil) :: {:ok, binary()} | {:error, term()}

Encodes the states of the given clients into an awareness update binary that can be sent to remote peers and applied with apply_update/3. When clients is nil, the states of all known clients are encoded. Raises ArgumentError when a client id is outside 0..9007199254740991.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 10 }))
iex> Yex.Awareness.set_local_state(awareness, %{ "key" => "value" })
iex> Yex.Awareness.encode_update(awareness, [10])
{:ok, <<1, 10, 1, 15, 123, 34, 107, 101, 121, 34, 58, 34, 118, 97, 108, 117, 101, 34, 125>>}

get_client_ids(awareness)

@spec get_client_ids(t()) :: [integer()]

Returns the IDs of all clients that currently have a state, including the local client.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.new())
iex> Yex.Awareness.apply_update(awareness, <<1, 210, 165, 202, 167, 8, 1, 2, 123, 125>>)
iex> Yex.Awareness.get_client_ids(awareness)
[2230489810]

get_local_state(awareness)

@spec get_local_state(t()) :: map()

get local state of the current client

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 100 }))
iex> Yex.Awareness.get_states(awareness)
%{}

get_states(awareness)

@spec get_states(t()) :: %{required(integer()) => term()}

Returns the states of all known clients, keyed by client ID.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 100 }))
iex> Yex.Awareness.set_local_state(awareness, %{ "key" => "value" })
iex> Yex.Awareness.get_states(awareness)
%{100 => %{"key" => "value"}}

monitor_change(awareness, opt \\ [])

@spec monitor_change(
  t(),
  keyword()
) :: reference()

Listen to remote and local state changes. Get notified when a state is either added, updated, or removed. You can pass metadata as an option. This value is passed as the fourth element of the message.If omitted, it will be passed as a structure of awareness itself.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 10 }))
iex> Yex.Awareness.monitor_change(awareness, metadata: %{ "key" => "value" })
iex> Yex.Awareness.apply_update(awareness, <<1, 210, 165, 202, 167, 8, 1, 2, 123, 125>>)
iex> receive do {:awareness_change, %{removed: [], added: [2230489810], updated: []}, _origin,  %{ "key" => "value" } = _metadata} -> :ok end

monitor_update(awareness, opt \\ [])

@spec monitor_update(
  t(),
  keyword()
) :: reference()

Monitor to remote and local awareness changes. This event is called even when the awareness state does not change but is only updated to notify other users that this client is still online. Use this event if you want to propagate awareness state to other users. You can pass metadata as an option. This value is passed as the fourth element of the message.If omitted, it will be passed as a structure of awareness itself.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 10 }))
iex> Yex.Awareness.monitor_update(awareness)
iex> Yex.Awareness.set_local_state(awareness, %{ "key" => "value" })
iex> receive do {:awareness_update, %{removed: [], added: [10], updated: []}, _origin, _awareness} -> :ok end

new(doc)

@spec new(Yex.Doc.t()) :: {:ok, t()}

create a new awareness instance

remove_states(awareness, clients)

@spec remove_states(t(), [integer()]) :: :ok

Clears out a state of a given client, effectively marking it as disconnected. Raises ArgumentError, removing no state, when a client id is outside 0..9007199254740991.

Examples

iex> {:ok, _awareness} = Yex.Awareness.new(Yex.Doc.new())

set_local_state(awareness, map)

@spec set_local_state(t(), map()) :: :ok

Sets the local state of the current client and notifies monitors.

Examples

iex> {:ok, awareness} = Yex.Awareness.new(Yex.Doc.with_options(%Yex.Doc.Options{ client_id: 100 }))
iex> Yex.Awareness.set_local_state(awareness, %{ "key" => "value" })
iex> Yex.Awareness.get_states(awareness)
%{100 => %{"key" => "value"}}