# `Issho.Documents`
[🔗](https://github.com/hattoriai/issho/blob/v0.4.0/lib/issho/documents.ex#L1)

The authorities (`Issho.Authority`) of an Issho instance: one for each
open document, found by name on every node of a cluster.

The registry is `:global` unless the instance's `:registry` is a module
with `name(instance, document_id)`, which returns a `GenServer` name
(a `{:via, ...}` tuple for Horde or a partitioned registry).

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `open`

```elixir
@spec open(atom(), String.t(), Issho.Identity.t() | nil, keyword()) ::
  {:ok, pid()} | {:error, term()}
```

The authority of a document, started if it is not running anywhere.

What the document is (its spec) comes from the policy's
`c:Issho.Policy.document/2`, asked with the identity of whoever opens it
first, whoever that is: a page, an embed of the same document in another
page, an agent. A `:spec` given by your server's own code (a component
that holds the document's initial content and its hook) is what the
document is only when the policy does not say (it answers
`{:error, _}`, or has no `document/2`). Defined in the policy, a
document is the same wherever it opens first; given by components, the
first to open it gives its spec, and the others' are not used. A browser
never gives a spec.

A spec is a map:

  * `:engine` (required): the document's `Issho.Engine` or binding.
  * `:initial`: the initial content, when the store has nothing.
  * `:opts`: the engine's options.
  * `:store`: `{module, context}`, or `:none` for a document that lasts
    as long as its authority (`Issho.Store.None`); the instance's store
    unless given.
  * `:on_transaction`: a function of the operations and a context
    (`:document`, `:author`, `:revision`, and the state `:before` and
    `:after`), run once for each accepted transaction, after the engine
    and before it is saved and confirmed. It answers `:ok` (or `{:ok,
    anything}`), or `{:error, reason}` to refuse the transaction: the
    place to save each change in your own tables.
  * `:events`: a function of the operations and the same context, run
    once for each accepted transaction after it is saved, which gives
    the events it makes happen (`[{name, data}]`), emitted in the room
    (`Issho.Events`) with the document and its author: a card that lands
    on a frame, a comment.

# `whereis`

```elixir
@spec whereis(atom(), String.t()) :: pid() | nil
```

The authority of a document if it is running, on any node, or `nil`.

---

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