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
@type t() :: %Yex.Awareness{reference: reference()}
Functions
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]
@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)
[]
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
@spec demonitor_change(reference()) :: :ok
Stop monitoring awareness changes started with monitor_change/2.
@spec demonitor_update(reference()) :: :ok
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.
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>>}
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 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)
%{}
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"}}
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 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
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.
Examples
iex> {:ok, _awareness} = Yex.Awareness.new(Yex.Doc.new())
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"}}