# `Arc`
[🔗](https://github.com/Cratis/Arc.Elixir/blob/main/lib/arc.ex#L4)

Arc for Elixir: an opinionated CQRS application framework for Phoenix and Plug, on Cratis
Chronicle.

You declare *what* your application does as plain modules, and Arc serves it:

  * `Arc.Command` - a request struct with a `handle/2` that decides and returns events
  * `Arc.ReadModel` - queries over a Chronicle read model, snapshot or observable
  * `Arc.Application` - the supervised runtime that discovers them
  * `Arc.Plug` - the Arc HTTP contract, so `@cratis/arc`, `@cratis/arc.react` and Cratis
    Components work against it unchanged
  * `Arc.LiveView` - the same commands and queries, called in-process from LiveView
  * `Arc.ProxyGenerator` - opt-in TypeScript proxies for React
  * `Arc.Test` - ExUnit scenarios that run the real pipelines

Use `execute/3` and `query/5` to call the pipelines from code.

# `context`

```elixir
@spec context(module(), keyword()) :: Arc.Context.t()
```

Builds a context for `application` from the given options.

# `execute`

```elixir
@spec execute(module(), struct() | {module(), map()}, keyword()) ::
  Arc.CommandResult.t()
```

Executes a command through the full pipeline.

`command` is a command struct, or a `{module, wire_map}` pair to bind a wire map first.

## Options

  * `:principal`, `:tenant`, `:correlation_id`, `:causation_id`, `:metadata` - context values
  * `:validate_only` - authorize and validate without handling

# `new_id`

```elixir
@spec new_id() :: String.t()
```

A new UUID v4 string, for a command key such as a new author's id.

    %RegisterAuthor{id: Arc.new_id(), name: "Ada"}

# `query`

```elixir
@spec query(module(), module(), atom(), map(), keyword()) :: Arc.QueryResult.t()
```

Executes a query of a read model by function name.

`args` are the declared parameters, as a map keyed by name (atoms or strings).

## Options

  * context options as for `execute/3`
  * `:page`, `:page_size`, `:sort_by`, `:sort_direction` - see `Arc.Pipeline.execute_query/5`

---

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