# `Yex.SharedType`
[🔗](https://github.com/satoren/y_ex/blob/main/lib/shared_type/shared_type.ex#L1)

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.

# `branch_id`

```elixir
@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`

```elixir
@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()}
```

# `alive?`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

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

# `unobserve_deep`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
