Yex.SharedType (y_ex v0.13.0)

Copy Markdown View Source

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

Types

Logical identifier of a shared type, the same on every replica of a document.

t()

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

branch_id()

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

t()

@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

alive?(shared_type)

@spec alive?(t()) :: boolean()

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

branch_id(shared_type)

@spec branch_id(t()) :: branch_id()

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"}

observe(shared_type, opt \\ [])

@spec observe(
  t(),
  keyword()
) :: reference()

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:

  • ref is a monitor reference returned by this function;
  • event is a struct that describes the change;
  • origin is the origin passed to the Yex.Doc.transaction() function, nil when none was given, or the %Yex.UndoManager{} for an undo or redo.
  • metadata is the metadata passed to the observe function.

Options

  • :metadata - provides metadata to be attached to this observe.

Returns

  • A reference that can be used to unsubscribe the observer

observe_deep(shared_type, opt \\ [])

@spec observe_deep(
  t(),
  keyword()
) :: reference()

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:

  • ref is a monitor reference returned by this function;
  • events is a list of structs that describes the changes;
  • origin is the origin passed to the Yex.Doc.transaction() function, nil when none was given, or the %Yex.UndoManager{} for an undo or redo.
  • metadata is the metadata passed to the observe_deep function.

Options

  • :metadata - provides metadata to be attached to this observe.

Returns

  • A reference that can be used to unsubscribe the deep observer

resolve(doc, branch_id)

@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 - doc has no such type: a root that was never created, or a nested type whose update doc has not integrated yet (including one still pending on a missing predecessor). It is not always transient: a nested type that doc integrated while an earlier range of the same client was still missing, and that was then deleted and garbage collected, stays :not_found until the missing range arrives.
  • :deleted - doc has 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 :deleted for 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 as Yex.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}

unobserve(observe_ref)

@spec unobserve(reference()) :: :ok

Unobserve the shared type for changes. Removes the observer registered with the given reference.

unobserve_deep(observe_ref)

@spec unobserve_deep(reference()) :: :ok

Unobserve the shared type and its children for changes. Removes the deep observer registered with the given reference.