The SharedType protocol defines the behavior of shared types in Yex. This module provides functionality for observing changes to shared types, including arrays, maps, text, and XML nodes.
Summary
Functions
Returns true while shared_type can still be used.
Returns the logical identifier of shared_type.
Registers a change observer that will be message every time this shared type is modified.
Registers a change observer that will be message every time this shared type or any of its children is modified.
Finds the shared type that branch_id names in doc.
Unobserve the shared type for changes. Removes the observer registered with the given reference.
Unobserve the shared type and its children for changes. Removes the deep observer registered with the given reference.
Types
@type branch_id() :: {:root, String.t()} | {:nested, client :: 0..9_007_199_254_740_991, clock :: 0..4_294_967_295}
Logical identifier of a shared type, the same on every replica of a document.
{:root, name} names a root type. {:nested, client, clock} names a type nested inside
another by the ID of the item that created it. Both are plain terms, so they can be stored,
for example with :erlang.term_to_binary/1.
@type t() :: %Yex.Array{doc: term(), reference: term()} | %Yex.Map{doc: term(), reference: term()} | %Yex.Text{doc: term(), reference: term()} | %Yex.XmlElement{doc: term(), reference: term()} | %Yex.XmlText{doc: term(), reference: term()} | %Yex.XmlFragment{doc: term(), reference: term()} | %Yex.WeakLink{doc: term(), reference: term()}
Functions
Returns true while shared_type can still be used.
A root type is always alive. A nested type stops being alive once it or any of its ancestors
is deleted, locally or by a remote update; from then on operations on it raise
Yex.DeletedSharedTypeError. Joins an open Yex.Doc.transaction/3, so a deletion made
earlier in the same transaction is seen.
Examples
iex> doc = Yex.Doc.new()
iex> map = Yex.Doc.get_map(doc, "map")
iex> nested = Yex.Map.set_and_get(map, "nested", Yex.MapPrelim.from(%{}))
iex> Yex.SharedType.alive?(nested)
true
iex> Yex.Map.delete(map, "nested")
iex> Yex.SharedType.alive?(nested)
false
Returns the logical identifier of shared_type.
The identifier is read from the struct itself, so this works on a deleted type and does not go through the document's worker process.
Examples
iex> doc = Yex.Doc.new()
iex> Yex.SharedType.branch_id(Yex.Doc.get_text(doc, "text"))
{:root, "text"}
Registers a change observer that will be message every time this shared type is modified.
If the shared type changes, a message is delivered to the monitoring process in the shape of:
{:observe_event, ref, event, origin, metadata}where:
refis a monitor reference returned by this function;eventis a struct that describes the change;originis the origin passed to theYex.Doc.transaction()function,nilwhen none was given, or the%Yex.UndoManager{}for an undo or redo.metadatais the metadata passed to theobservefunction.
Options
:metadata- provides metadata to be attached to this observe.
Returns
- A reference that can be used to unsubscribe the observer
Registers a change observer that will be message every time this shared type or any of its children is modified.
If the shared type changes, a message is delivered to the monitoring process in the shape of:
{:observe_deep_event, ref, events, origin, metadata}where:
refis a monitor reference returned by this function;eventsis a list of structs that describes the changes;originis the origin passed to theYex.Doc.transaction()function,nilwhen none was given, or the%Yex.UndoManager{}for an undo or redo.metadatais the metadata passed to theobserve_deepfunction.
Options
:metadata- provides metadata to be attached to this observe.
Returns
- A reference that can be used to unsubscribe the deep observer
@spec resolve(Yex.Doc.t(), branch_id()) :: {:ok, t()} | {:error, :not_found | :deleted | :untyped | :unsupported}
Finds the shared type that branch_id names in doc.
Returns the typed struct, such as %Yex.Map{} or %Yex.Text{}. It never creates a type.
Joins an open Yex.Doc.transaction/3.
Ids are scoped to the document that produced them and its replicas.
Errors
:not_found-dochas no such type: a root that was never created, or a nested type whose updatedochas not integrated yet (including one still pending on a missing predecessor). It is not always transient: a nested type thatdocintegrated while an earlier range of the same client was still missing, and that was then deleted and garbage collected, stays:not_founduntil the missing range arrives.:deleted-dochas integrated the id and no live shared type is there: the type was deleted, or the id names other content. A document sharing the client id with the one that produced the id may answer:deletedfor a foreign id.:untyped- a root that only a remote update created and nothing has claimed yet. Claim it with the getter for its kind, such asYex.Doc.get_map/2, and resolve again.:unsupported- a nested type of a kind Yex has no struct for, such as an XmlHook. Resolving again does not change the answer.
Raises ArgumentError for a malformed id: another shape, a name that is not UTF-8, a
client of 2^53 or more, or a clock of 2^32 or more.
Examples
iex> doc = Yex.Doc.new()
iex> text = Yex.Doc.get_text(doc, "text")
iex> {:ok, ^text} = Yex.SharedType.resolve(doc, {:root, "text"})
iex> Yex.SharedType.resolve(doc, {:root, "missing"})
{:error, :not_found}
@spec unobserve(reference()) :: :ok
Unobserve the shared type for changes. Removes the observer registered with the given reference.
@spec unobserve_deep(reference()) :: :ok
Unobserve the shared type and its children for changes. Removes the deep observer registered with the given reference.