# `Macaw.Layers.Limits`
[🔗](https://github.com/dcoai/macaw_layers/blob/v0.5.0/lib/macaw/layers/limits.ex#L1)

Sanity limits on a document read from elsewhere (spec/01 §5).

| Limit | Default | Bounds |
|---|---|---|
| `bytes` | `8_000_000` | the encoded document's size |
| `depth` | `64` | how deeply objects and arrays nest; the document itself is depth 1 |
| `items` | `100_000` | the entries any one object or array holds |

They bound what reading a document can be made to cost. **A host may tighten every
limit:** a host loading untrusted input knows its inputs and lowers the numbers at its
layer, and a limit it does not name keeps its default. **A host may raise a limit only
by saying so, per limit:** `{:raise, max}` for a host whose inputs are trusted and large
(a bundle import). A plain value above the default is a fault, so no limit is loosened
by mistake.

A fault is `{path, {:limit, name, max, given}}`, worded by `Macaw.Layers.Fault.format/2`.

The walk over a decoded term is the generic part of visualize's
`Visualize.Chart.Limits.structure/2`.

# `name`

```elixir
@type name() :: :bytes | :depth | :items
```

A limit's name.

# `t`

```elixir
@type t() :: %{required(name()) =&gt; pos_integer()}
```

The limits a reader applies, one positive integer per name.

# `defaults`

```elixir
@spec defaults() :: t()
```

The system's sanity values.

# `new`

```elixir
@spec new(keyword() | map()) :: {:ok, t()} | {:error, [Macaw.Layers.Fault.t(), ...]}
```

The limits a reader applies, `given` over `defaults/0`: `{:ok, limits}`, or every fault
of `given` by its name. A plain value tightens a limit; `{:raise, max}` raises it above
its default.

The faults: a name that is not a limit, `:unknown_key`; a value that is neither a
positive integer nor `{:raise, max}`, `{:limit_value, default}`; a plain value above the
default, `{:limit_loosened, default}` (a host can't loosen a sanity limit by mistake);
a raise that is not above it, `{:limit_not_raised, default}`; and `given` neither a
keyword list nor a map, `{:type, :keyword}` at `[]`.

    iex> {:ok, limits} = Macaw.Layers.Limits.new(items: 10)
    iex> limits.items
    10

    iex> {:ok, limits} = Macaw.Layers.Limits.new(items: {:raise, 500_000})
    iex> limits.items
    500000

    iex> Macaw.Layers.Limits.new(items: 500_000, pages: 3)
    {:error, [{[:items], {:limit_loosened, 100000}}, {[:pages], :unknown_key}]}

# `new!`

```elixir
@spec new!(keyword() | map()) :: t()
```

`new/1`, or an `ArgumentError` naming every fault: a host's limits written in code.

# `structure`

```elixir
@spec structure(term(), t()) :: [Macaw.Layers.Fault.t()]
```

Every `depth` and `items` fault of a decoded term, ordered by path.

The term itself is depth 1. A struct is a leaf. Past the depth limit a branch is reported
once, at the first map or list beyond it, and not walked further. A map or list over the
items limit is reported at its own path, with the number of entries it holds.

---

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