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.
@see encode_state_as_update/2
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
@type input_type() :: any_type() | Yex.PrelimType.t()
Functions
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
Applies a v1 encoded update to the document.
Same as apply_update/2.
Returns {:error, {:encoding_exception, message}} when update cannot be decoded.
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"
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.
Re-encodes a v2 update as a v1 update without changing its content.
The output matches yjs convertUpdateFormatV2ToV1 byte for byte.
@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}}
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
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.
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 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)
@see encode_state_as_update/2
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.
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)
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)
@see encode_state_vector/1
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}}
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.
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.
Computes the state vector and encodes it with the v1 format.
Same as encode_state_vector/1.
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)
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.
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.
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"
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.
Merges multiple v2 encoded updates into a single v2 update.
Returns {:error, {:encoding_exception, message}} when an update cannot be decoded.
Normalize a number to a format that can be used in Yjs.
@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}}}
@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, _}}.
@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.
@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.
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.
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.