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

Yex is wrapper library for the Yjs CRDT library.

# `any_type`

```elixir
@type any_type() ::
  binary()
  | Yex.Buffer.t()
  | map()
  | list()
  | integer()
  | float()
  | boolean()
  | nil
```

# `input_type`

```elixir
@type input_type() :: any_type() | Yex.PrelimType.t()
```

# `apply_update`

```elixir
@spec apply_update(Yex.Doc.t(), binary()) :: :ok | {:error, term()}
```

Apply a document update on the shared document.

Returns `{:error, {:encoding_exception, message}}` when `update` cannot be decoded.

## Examples syncs two clients by exchanging the complete document structure
    iex> doc1 = Yex.Doc.new()
    iex> doc2 = Yex.Doc.new()
    iex> {:ok, state1} = Yex.encode_state_as_update(doc1)
    iex> {:ok, state2} = Yex.encode_state_as_update(doc2)
    iex> Yex.apply_update(doc1, state2)
    :ok
    iex> Yex.apply_update(doc2, state1)
    :ok

# `apply_update_v1`

```elixir
@spec apply_update_v1(Yex.Doc.t(), binary()) :: :ok | {:error, term()}
```

Applies a v1 encoded update to the document.

Same as `apply_update/2`.

Returns `{:error, {:encoding_exception, message}}` when `update` cannot be decoded.

# `apply_update_v2`

```elixir
@spec apply_update_v2(Yex.Doc.t(), binary()) :: :ok | {:error, term()}
```

Applies a v2 encoded update to the document.

Returns `{:error, {:encoding_exception, message}}` when `update` cannot be decoded.

## Examples
    iex> doc1 = Yex.Doc.new()
    iex> doc2 = Yex.Doc.new()
    iex> Yex.Text.insert(Yex.Doc.get_text(doc1, "text"), 0, "Hello")
    iex> {:ok, update} = Yex.encode_state_as_update_v2(doc1)
    iex> Yex.apply_update_v2(doc2, update)
    :ok
    iex> Yex.Text.to_string(Yex.Doc.get_text(doc2, "text"))
    "Hello"

# `convert_update_format_v1_to_v2`

```elixir
@spec convert_update_format_v1_to_v2(binary()) :: {:ok, binary()} | {:error, term()}
```

Re-encodes a v1 update as a v2 update without changing its content.

The output matches yjs `convertUpdateFormatV1ToV2` byte for byte. Input left over after
the update, such as a v2 update passed by mistake, returns
`{:error, {:encoding_exception, _}}` instead of an empty update.

# `convert_update_format_v2_to_v1`

```elixir
@spec convert_update_format_v2_to_v1(binary()) :: {:ok, binary()} | {:error, term()}
```

Re-encodes a v2 update as a v1 update without changing its content.

The output matches yjs `convertUpdateFormatV2ToV1` byte for byte.

# `decode_state_vector`

```elixir
@spec decode_state_vector(binary()) ::
  {:ok, %{required(non_neg_integer()) =&gt; non_neg_integer()}} | {:error, term()}
```

Decodes a v1 encoded state vector into a map of client id to clock.

Accepts the output of `encode_state_vector_v1/1`, `encode_state_vector_from_update/1`
and yjs `encodeStateVector`, like yjs `decodeStateVector`. Input left over after the
state vector, such as the output of `encode_state_vector_v2/1`, returns
`{:error, {:encoding_exception, _}}`.

## Examples
    iex> doc = Yex.Doc.with_options(%Yex.Doc.Options{client_id: 1})
    iex> Yex.Text.insert(Yex.Doc.get_text(doc, "text"), 0, "Hello")
    iex> Yex.decode_state_vector(Yex.encode_state_vector!(doc))
    {:ok, %{1 => 5}}

# `diff_update`

```elixir
@spec diff_update(binary(), binary()) :: {:ok, binary()} | {:error, term()}
```

Returns the part of a v1 `update` that a peer with `state_vector` has not seen yet.

`state_vector` is v1 encoded, as produced by `encode_state_vector_v1/1`,
`encode_state_vector_from_update/1` or yjs `encodeStateVector`. The delete set of
`update` is carried over whole. Same as `diff_update_v1/2`, and as yjs `diffUpdate`
byte for byte.

## Examples
    iex> doc = Yex.Doc.new()
    iex> text = Yex.Doc.get_text(doc, "text")
    iex> Yex.Text.insert(text, 0, "Hello")
    iex> {:ok, state_vector} = Yex.encode_state_vector(doc)
    iex> Yex.Text.insert(text, 5, " World")
    iex> {:ok, update} = Yex.encode_state_as_update(doc)
    iex> {:ok, diff} = Yex.diff_update(update, state_vector)
    iex> byte_size(diff) < byte_size(update)
    true

# `diff_update_v1`

```elixir
@spec diff_update_v1(binary(), binary()) :: {:ok, binary()} | {:error, term()}
```

Returns the part of a v1 `update` that a peer with the v1 `state_vector` has not seen yet.

Same as `diff_update/2`. Input left over after the update or after the state vector,
such as a v2 update or the output of `encode_state_vector_v2/1` passed by mistake,
returns `{:error, {:encoding_exception, _}}`; yjs does not check this.

# `diff_update_v2`

```elixir
@spec diff_update_v2(binary(), binary()) :: {:ok, binary()} | {:error, term()}
```

Returns the part of a v2 `update` that a peer with `state_vector` has not seen yet,
as a v2 update.

`state_vector` is v1 encoded, as in yjs `diffUpdateV2` and the sync protocol: use
`encode_state_vector_v1/1` or `encode_state_vector_from_update_v2/1`. The output of
`encode_state_vector_v2/1` is a different encoding and returns
`{:error, {:encoding_exception, _}}`.

# `encode_state_as_update`

```elixir
@spec encode_state_as_update(Yex.Doc.t(), binary() | nil) ::
  {:ok, binary()} | {:error, term()}
```

Encode the document state as a single update message that can be applied on the remote document. Optionally, specify the target state vector to only write the missing differences to the update message.

Returns `{:error, {:encoding_exception, message}}` when `encoded_state_vector` cannot be
decoded.

## Examples
    iex> doc = Yex.Doc.new()
    iex> {:ok, _binary} = Yex.encode_state_as_update(doc)

# `encode_state_as_update!`

```elixir
@spec encode_state_as_update!(Yex.Doc.t(), binary() | nil) :: binary()
```

@see encode_state_as_update/2

# `encode_state_as_update_v1`

```elixir
@spec encode_state_as_update_v1(Yex.Doc.t(), binary() | nil) ::
  {:ok, binary()} | {:error, term()}
```

Encodes the document state as a v1 update.

Same as `encode_state_as_update/2`. `encoded_state_vector` must be v1 encoded.

Returns `{:error, {:encoding_exception, message}}` when `encoded_state_vector` cannot be
decoded.

# `encode_state_as_update_v2`

```elixir
@spec encode_state_as_update_v2(Yex.Doc.t(), binary() | nil) ::
  {:ok, binary()} | {:error, term()}
```

Encodes the document state as a v2 update.

Optionally, pass a state vector in the yrs v2 encoding (see `encode_state_vector_v2/1`)
to only write the missing differences. The v1 state vectors that the update utilities
return, such as `encode_state_vector_from_update_v2/1`, are a different encoding.

Returns `{:error, {:encoding_exception, message}}` when `encoded_state_vector` cannot be
decoded.

## Examples
    iex> doc = Yex.Doc.new()
    iex> {:ok, _binary} = Yex.encode_state_as_update_v2(doc)

# `encode_state_vector`

```elixir
@spec encode_state_vector(Yex.Doc.t()) :: {:ok, binary()} | {:error, term()}
```

Computes the state vector and encodes it into an Binary.
A state vector describes the state of the local client.
The remote client can use this to exchange only the missing differences.

## Examples
    iex> doc = Yex.Doc.new()
    iex> {:ok, _binary} = Yex.encode_state_vector(doc)

# `encode_state_vector!`

```elixir
@spec encode_state_vector!(Yex.Doc.t()) :: binary()
```

@see encode_state_vector/1

# `encode_state_vector_from_update`

```elixir
@spec encode_state_vector_from_update(binary()) :: {:ok, binary()} | {:error, term()}
```

Returns the v1 encoded state vector of a v1 `update`.

A client counts only up to the first gap in its clocks: a client whose structs do not
start at clock 0 is left out, as in yjs `encodeStateVectorFromUpdate`. Same as
`encode_state_vector_from_update_v1/1`.

## Examples
    iex> doc = Yex.Doc.with_options(%Yex.Doc.Options{client_id: 1})
    iex> Yex.Text.insert(Yex.Doc.get_text(doc, "text"), 0, "Hello")
    iex> {:ok, update} = Yex.encode_state_as_update(doc)
    iex> {:ok, state_vector} = Yex.encode_state_vector_from_update(update)
    iex> Yex.decode_state_vector(state_vector)
    {:ok, %{1 => 5}}

# `encode_state_vector_from_update_v1`

```elixir
@spec encode_state_vector_from_update_v1(binary()) ::
  {:ok, binary()} | {:error, term()}
```

Returns the v1 encoded state vector of a v1 `update`.

Same as `encode_state_vector_from_update/1`. Input left over after the update, such as
a v2 update passed by mistake, returns `{:error, {:encoding_exception, _}}`; yjs does
not check this.

# `encode_state_vector_from_update_v2`

```elixir
@spec encode_state_vector_from_update_v2(binary()) ::
  {:ok, binary()} | {:error, term()}
```

Returns the state vector of a v2 `update`, v1 encoded.

The result is v1 encoded like yjs `encodeStateVectorFromUpdateV2`, so it can be passed
to `diff_update_v2/2` and to yjs peers. It is not the encoding `encode_state_vector_v2/1`
returns, so `encode_state_as_update_v2/2` does not take it.

# `encode_state_vector_v1`

```elixir
@spec encode_state_vector_v1(Yex.Doc.t()) :: {:ok, binary()} | {:error, term()}
```

Computes the state vector and encodes it with the v1 format.

Same as `encode_state_vector/1`.

# `encode_state_vector_v2`

```elixir
@spec encode_state_vector_v2(Yex.Doc.t()) :: {:ok, binary()} | {:error, term()}
```

Computes the state vector and encodes it with the v2 format.

This is the yrs v2 framing, which yjs peers cannot read. `encode_state_as_update_v2/2`
takes it; the update utilities such as `diff_update_v2/2` take the v1 encoding from
`encode_state_vector_v1/1` and reject this one.

## Examples
    iex> doc = Yex.Doc.new()
    iex> {:ok, _binary} = Yex.encode_state_vector_v2(doc)

# `get_pending_ds`

```elixir
@spec get_pending_ds(Yex.Doc.t()) :: {:ok, binary() | nil} | {:error, term()}
```

Returns the pending delete set (v1 encoded) for the document, if any.

A pending delete set holds deletions that arrived out of order and could
not yet be applied. Returns `{:ok, binary()}` when a pending delete set
exists, `{:ok, nil}` otherwise.

# `get_pending_update`

```elixir
@spec get_pending_update(Yex.Doc.t()) :: {:ok, binary() | nil} | {:error, term()}
```

Returns the pending update (v1 encoded) for the document, if any.

A pending update accumulates operations that arrived out of order and
could not yet be applied because their causal predecessors are missing.
Returns `{:ok, binary()}` when a pending update exists, `{:ok, nil}` otherwise.

# `merge_updates`

```elixir
@spec merge_updates([binary()]) :: {:ok, binary()} | {:error, term()}
```

Merges multiple v1 encoded updates into a single update.

The result is equivalent to applying all updates in order, without needing a document.
Same as `merge_updates_v1/1`.

Returns `{:error, {:encoding_exception, message}}` when an update cannot be decoded.

## Examples
    iex> doc = Yex.Doc.new()
    iex> text = Yex.Doc.get_text(doc, "text")
    iex> Yex.Doc.monitor_update(doc)
    iex> Yex.Text.insert(text, 0, "Hello")
    iex> Yex.Text.insert(text, 5, " World")
    iex> assert_receive {:update_v1, update1, _, _}
    iex> assert_receive {:update_v1, update2, _, _}
    iex> {:ok, merged} = Yex.merge_updates([update1, update2])
    iex> doc2 = Yex.Doc.new()
    iex> Yex.apply_update(doc2, merged)
    iex> Yex.Text.to_string(Yex.Doc.get_text(doc2, "text"))
    "Hello World"

# `merge_updates_v1`

```elixir
@spec merge_updates_v1([binary()]) :: {:ok, binary()} | {:error, term()}
```

Merges multiple v1 encoded updates into a single v1 update.

Same as `merge_updates/1`.

Returns `{:error, {:encoding_exception, message}}` when an update cannot be decoded.

# `merge_updates_v2`

```elixir
@spec merge_updates_v2([binary()]) :: {:ok, binary()} | {:error, term()}
```

Merges multiple v2 encoded updates into a single v2 update.

Returns `{:error, {:encoding_exception, message}}` when an update cannot be decoded.

# `normalize`

Normalize a number to a format that can be used in Yjs.

# `parse_update_meta`

```elixir
@spec parse_update_meta(binary()) ::
  {:ok,
   %{
     from: %{required(non_neg_integer()) =&gt; non_neg_integer()},
     to: %{required(non_neg_integer()) =&gt; non_neg_integer()}
   }}
  | {:error, term()}
```

Returns the clock range each client's structs cover in a v1 `update`.

`from` maps each client to the clock of its first struct and `to` to the end (exclusive)
of its last one, as in yjs `parseUpdateMeta`. The delete set is not counted, so an
update that only deletes returns empty maps. Same as `parse_update_meta_v1/1`.

## Examples
    iex> doc = Yex.Doc.with_options(%Yex.Doc.Options{client_id: 1})
    iex> Yex.Text.insert(Yex.Doc.get_text(doc, "text"), 0, "Hello")
    iex> {:ok, update} = Yex.encode_state_as_update(doc)
    iex> Yex.parse_update_meta(update)
    {:ok, %{from: %{1 => 0}, to: %{1 => 5}}}

# `parse_update_meta_v1`

```elixir
@spec parse_update_meta_v1(binary()) ::
  {:ok,
   %{
     from: %{required(non_neg_integer()) =&gt; non_neg_integer()},
     to: %{required(non_neg_integer()) =&gt; non_neg_integer()}
   }}
  | {:error, term()}
```

Returns the clock range each client's structs cover in a v1 `update`.

Same as `parse_update_meta/1`. Input left over after the update, such as a v2 update
passed by mistake, returns `{:error, {:encoding_exception, _}}`.

# `parse_update_meta_v2`

```elixir
@spec parse_update_meta_v2(binary()) ::
  {:ok,
   %{
     from: %{required(non_neg_integer()) =&gt; non_neg_integer()},
     to: %{required(non_neg_integer()) =&gt; non_neg_integer()}
   }}
  | {:error, term()}
```

Returns the clock range each client's structs cover in a v2 `update`.

See `parse_update_meta/1`.

# `snapshot`

```elixir
@spec snapshot(Yex.Doc.t()) :: {:ok, Yex.Snapshot.t()} | {:error, term()}
```

Creates a snapshot of the current document state.

The returned snapshot can later be used with
`Yex.Snapshot.encode_state_v1/1` or `Yex.Snapshot.encode_state_v2/1`
to produce a time-travel update for that point-in-time state.

The source document must have garbage collection disabled
(`Yex.Doc.Options.skip_gc == true`) for snapshot-based time-travel encoding.

# `update_debug_v1`

```elixir
@spec update_debug_v1(binary()) :: {:ok, String.t()} | {:error, term()}
```

Parses an update payload encoded in lib0 v1 format and returns a human-readable debug string.

Returns `{:error, {:encoding_exception, message}}` when `update` cannot be decoded.

# `update_debug_v2`

```elixir
@spec update_debug_v2(binary()) :: {:ok, String.t()} | {:error, term()}
```

Parses an update payload encoded in lib0 v2 format and returns a human-readable debug string.

Returns `{:error, {:encoding_exception, message}}` when `update` cannot be decoded.

---

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