A sticky index provides position references that are unaffected by document changes, based on the Yjs model. It maintains its relative position when placed before or after specific characters or elements.
Features
- Stable position references unaffected by document changes
- Compatible with shared types like Text, Array, and XML
- Maintains relative positions after insert/delete operations
- Ideal for tracking cursor positions and text selections
Usage
Numeric indices are unsuitable for tracking user selections because their positions change when content is inserted or deleted. Sticky indices provide stable references that maintain their relative positions through such changes:
iex> alias Yex.{StickyIndex, Doc, Text}
iex> doc = Doc.new()
iex> txt = Doc.get_text(doc, "text")
iex> Doc.transaction(doc, fn ->
...> Text.insert(txt, 0, "abc")
...> # => 'abc'
...> # Create position tracker (marked as . in comments)
...> pos = StickyIndex.new(txt, 2, :after)
...> # => 'ab.c'
...>
...> # Modify text
...> Text.insert(txt, 1, "def")
...> # => 'adefb.c'
...> Text.delete(txt, 4, 1)
...> # => 'adef.c'
...>
...> # Get current offset index
...> {:ok, a} = StickyIndex.get_offset(pos)
...> # => 4
...> assert a.index == 4
...> end)
Summary
Functions
Gets the association direction of a StickyIndex.
Decodes a StickyIndex from binary format with the given Doc context (v1 - default).
Decodes a StickyIndex from binary flexbuffer format (v1).
Decodes a StickyIndex from JSON string format (v2).
Encodes a StickyIndex to binary format using flexbuffer encoding (v1 - default).
Encodes a StickyIndex to binary flexbuffer format (v1).
Encodes a StickyIndex to JSON string format (v2).
Reconstructs a StickyIndex from JSON representation.
Resolves the sticky index to its current numeric position in the shared type.
Creates a sticky index for the given position of a shared type.
Converts a StickyIndex to JSON representation.
Types
Functions
@spec assoc(t()) :: -1 | 0
Gets the association direction of a StickyIndex.
Returns
-1for:beforeassociation0for:afterassociation
Decodes a StickyIndex from binary format with the given Doc context (v1 - default).
This reverses the encoding done by encode/1 or encode_v1/1. The Doc is required
to associate the decoded StickyIndex with its document context.
Returns {:error, {:encoding_exception, message}} when binary cannot be decoded.
Decodes a StickyIndex from binary flexbuffer format (v1).
Returns {:error, {:encoding_exception, message}} when binary cannot be decoded.
Decodes a StickyIndex from JSON string format (v2).
This reverses the encoding done by encode_v2/1. The Doc is required to associate
the decoded StickyIndex with its document context.
Returns {:error, {:encoding_exception, message}} when binary cannot be decoded.
Encodes a StickyIndex to binary format using flexbuffer encoding (v1 - default).
This provides a compact binary representation suitable for storage or transmission.
The encoded binary can be decoded using decode/2 or decode_v1/2.
Encodes a StickyIndex to binary flexbuffer format (v1).
Encodes a StickyIndex to JSON string format (v2).
This provides a JSON string representation of the StickyIndex suitable for interoperability with other systems.
Reconstructs a StickyIndex from JSON representation.
This delegates to the reconstruction NIF (Yex.Nif.sticky_index_from_json/2).
Input constraints
jsonmust be a binary JSON payload in StickyIndex/RelativePosition format.docmust be a%Yex.Doc{}associated with the reconstructed StickyIndex.
Returns
{:ok, sticky_index}when reconstruction succeeds{:error, reason}when reconstruction fails (for example:invalid_json)
Resolves the sticky index to its current numeric position in the shared type.
Returns {:ok, %{index: index, assoc: assoc}}, or :error when the position
can no longer be resolved (for example, the shared type has been deleted).
@spec new(shared_type(), integer(), :before | :after) :: t()
Creates a sticky index for the given position of a shared type.
assoc decides which neighbour the index sticks to:
:after- the index sticks to the element atindex, so content inserted at that position goes before it.:before- the index sticks to the element atindex - 1, so content inserted at that position goes after it.
Converts a StickyIndex to JSON representation.
Returns a serialized JSON string with StickyIndex position and association information in a format compatible with Yjs RelativePosition and yffi's ysticky_index_to_json.
Returns
A JSON string containing an object with:
- Exactly one of
"item","type", or"tname" "item"-{"client": u64, "clock": u32}for relative positions in existing content"type"-{"client": u64, "clock": u32}for nested empty-type positions"tname"- Type name string for root-level empty-type positions"assoc"- Association value:-1for:before,0for:after