# `Selecto.Output.Transformers.Structs`

Transforms query results into structured data using Elixir structs.

This transformer creates struct instances from database rows, providing:
- Dynamic struct module support or predefined structs
- Field name transformations (snake_case, camelCase, PascalCase)
- Type coercion from database types to Elixir types
- Validation of required fields and field mapping
- Memory-efficient processing for large datasets

## Options

* `:struct_module` - Module to create structs from (required)
* `:field_mapping` - Map of database field names to struct field names
* `:transform_keys` - Key transformation strategy (:snake_case, :camel_case, :pascal_case)
* `:coerce_types` - Whether to coerce database types to Elixir types (default: true)
* `:type_strategy` - Type coercion strategy (:strict, :lenient, :preserve)
* `:validate_fields` - Whether to validate all struct fields are present
* `:default_values` - Map of default values for missing fields
* `:enforce_keys` - Whether to enforce required struct keys

## Examples

    # Basic struct transformation
    transform(rows, columns, aliases, User, [])

    # With field mapping and validation
    transform(rows, columns, aliases, User, [
      field_mapping: %{"user_id" => :id, "full_name" => :name},
      validate_fields: true,
      enforce_keys: true
    ])

    # Dynamic struct creation
    transform(rows, columns, aliases, nil, [
      struct_module: DynamicRecord,
      transform_keys: :camel_case,
      coerce_types: true
    ])

# `struct_option`

```elixir
@type struct_option() ::
  {:struct_module, module()}
  | {:field_mapping, map()}
  | {:transform_keys, :snake_case | :camel_case | :pascal_case | :none}
  | {:coerce_types, boolean()}
  | {:type_strategy, :strict | :lenient | :preserve}
  | {:validate_fields, boolean()}
  | {:default_values, map()}
  | {:enforce_keys, boolean()}
```

# `struct_options`

```elixir
@type struct_options() :: [struct_option()]
```

# `stream_transform`

```elixir
@spec stream_transform(
  rows :: Enumerable.t(),
  columns :: list(),
  aliases :: map(),
  struct_module :: module() | nil,
  options :: struct_options()
) :: {:ok, Enumerable.t()} | {:error, Selecto.Error.t()}
```

Streams struct transformation for large datasets.

Returns a stream of struct instances to minimize memory usage.

# `transform`

```elixir
@spec transform(
  rows :: [list()],
  columns :: list(),
  aliases :: map(),
  struct_module :: module() | nil,
  options :: struct_options()
) :: {:ok, [struct()]} | {:error, Selecto.Error.t()}
```

Transforms database result rows into struct instances.

Returns a list of struct instances with properly typed and named fields.

---

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