# `Issho.Documents`
[🔗](https://github.com/hattoriai/issho/blob/v0.1.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 first open: the policy's
`c:Issho.Policy.document/2`, asked with the identity of whoever opens
it, or a `:spec` given by your server's own code, such as a component
that holds the document's initial content and its hook. 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.

# `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*