View Source Yex.Awareness (y_ex v0.7.2)

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.

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)
[]

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>>}

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.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.

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.

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"}}

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

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()

demonitor_change(ref)

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

demonitor_update(ref)

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

encode_update(awareness, clients \\ nil)

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

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()]

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()}

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.

Examples

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

set_local_state(awareness, map)

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

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"}}