# `Yex.Awareness`
[🔗](https://github.com/satoren/y_ex/blob/main/lib/protocols/awareness.ex#L1)

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

# `t`

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

# `apply_update`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

Stop monitoring awareness changes started with `monitor_change/2`.

# `demonitor_update`

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

Stop monitoring awareness updates started with `monitor_update/2`.

# `encode_update`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@spec get_states(t()) :: %{required(integer()) =&gt; 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`

```elixir
@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`

```elixir
@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`

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

create a new awareness instance

# `remove_states`

```elixir
@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`

```elixir
@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"}}

---

*Consult [api-reference.md](api-reference.md) for complete listing*
