Yex is wrapper library for the Yjs CRDT library.

Summary

Functions

Apply a document update on the shared document.

Applies a v1 encoded update to the document.

Applies a v2 encoded update to the document.

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

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

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

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

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

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

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.

Encodes the document state as a v1 update.

Encodes the document state as a v2 update.

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.

@see encode_state_vector/1

Returns the v1 encoded state vector of a v1 update.

Returns the v1 encoded state vector of a v1 update.

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

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

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

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

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

Merges multiple v1 encoded updates into a single update.

Merges multiple v1 encoded updates into a single v1 update.

Merges multiple v2 encoded updates into a single v2 update.

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

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

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

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

Creates a snapshot of the current document state.

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

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

Types

any_type()

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

input_type()

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

Functions

apply_update(doc, update)

@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(doc, update)

@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(doc, update)

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

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

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

@spec decode_state_vector(binary()) ::
  {:ok, %{required(non_neg_integer()) => 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(update, state_vector)

@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(update, state_vector)

@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(update, state_vector)

@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(doc, encoded_state_vector \\ nil)

@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!(doc, encoded_state_vector \\ nil)

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

@see encode_state_as_update/2

encode_state_as_update_v1(doc, encoded_state_vector \\ nil)

@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(doc, encoded_state_vector \\ nil)

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

@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!(doc)

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

@see encode_state_vector/1

encode_state_vector_from_update(update)

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

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

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

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

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

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

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

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

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

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

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

parse_update_meta(update)

@spec parse_update_meta(binary()) ::
  {:ok,
   %{
     from: %{required(non_neg_integer()) => non_neg_integer()},
     to: %{required(non_neg_integer()) => 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(update)

@spec parse_update_meta_v1(binary()) ::
  {:ok,
   %{
     from: %{required(non_neg_integer()) => non_neg_integer()},
     to: %{required(non_neg_integer()) => 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(update)

@spec parse_update_meta_v2(binary()) ::
  {:ok,
   %{
     from: %{required(non_neg_integer()) => non_neg_integer()},
     to: %{required(non_neg_integer()) => non_neg_integer()}
   }}
  | {:error, term()}

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

See parse_update_meta/1.

snapshot(doc)

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

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

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