# `Issho.Participant`
[🔗](https://github.com/hattoriai/issho/blob/v0.1.0/lib/issho/participant.ex#L1)

An actor in a room from Elixir: an agent running in your app, a job, a
script. It joins like a browser, with the same presence, awareness,
locks, transactions and policy, and the people in the room see it.

    {:ok, claude} = Issho.join_as(MyApp.Issho, agent, "board:42", on_behalf_of: ada)

    {:ok, doc} = Issho.Participant.open(claude, "board:42")
    Issho.Participant.place(claude, %{"doc" => "board:42", "at" => %{"node" => "n7"}})
    Issho.Participant.lock(claude, [%{"doc" => "board:42", "at" => %{"node" => "n7"}}])
    {:ok, _receipt} = Issho.Participant.transact(claude, "board:42", ops)
    Issho.Participant.leave(claude)

A participant is a process linked to the one that joins. It forwards
what happens in the room to that process (or to `:notify`) as
`{Issho.Participant, participant, event, payload}` messages: `"tx"`,
`"aware"`, `"presence_diff"` and `"bye"`, as a browser receives them.

`transact/3` takes a list of operations (Issho builds the envelope, on
the latest revision) or a whole transaction map, to retry one with its
original id.

# `aware`

```elixir
@spec aware(GenServer.server(), map()) :: :ok | {:error, term()}
```

Merges keys into the participant's awareness state (`"status"`, your own).

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `leave`

```elixir
@spec leave(GenServer.server()) :: :ok
```

Leaves the room.

# `lock`

```elixir
@spec lock(GenServer.server(), [map()]) :: :ok | {:error, term()}
```

Sets the places the participant locks (`[]` releases them).

# `locks`

```elixir
@spec locks(GenServer.server()) :: [{map(), String.t()}]
```

The places locked in the room by anyone, each with its holder's key.

# `open`

```elixir
@spec open(GenServer.server(), String.t()) :: {:ok, map()} | {:error, term()}
```

Opens a document of the room; gives its snapshot.

# `place`

```elixir
@spec place(GenServer.server(), map() | nil) :: :ok | {:error, term()}
```

Sets the participant's place (`nil` for none), keeping its locks.

# `read`

```elixir
@spec read(GenServer.server(), String.t()) :: {:ok, map()} | {:error, term()}
```

The document's current snapshot.

# `transact`

```elixir
@spec transact(GenServer.server(), String.t(), [map()] | map()) ::
  {:ok, map()} | {:error, term()}
```

Commits operations, or a whole transaction, to an open document.

---

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