# `Selecto.SelectionShape`

Structured selection helpers for building and materializing nested result shapes.

This module lets callers provide a list/tuple selection shape and receive rows
back in that same nested shape via `execute_shape/2`.

Nested lists/tuples that exclusively reference fields from a single joined
schema are treated as subselect nodes and compiled to `json_agg` correlated
subqueries.

# `shape_input`

```elixir
@type shape_input() :: list() | tuple()
```

# `execute_shape`

```elixir
@spec execute_shape(
  Selecto.t(),
  keyword()
) :: {:ok, list()} | {:error, Selecto.Error.t()}
```

Execute a shape query and materialize rows into the configured nested shape.

Returns `{:ok, shaped_rows}`.

# `select_shape`

```elixir
@spec select_shape(Selecto.t(), shape_input()) :: Selecto.t()
```

Compile a nested selection shape into regular Selecto selectors + subselect specs.

The generated execution plan is stored on `selecto.set.selection_shape` and can
be used with `execute_shape/2`.

# `shape_rows`

```elixir
@spec shape_rows(list(), map()) :: list()
```

Materialize DB rows according to a compiled shape plan.

---

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