# `Exdantic.Config.Builder`
[🔗](https://github.com/nshkrdotcom/exdantic/blob/v0.1.0/lib/exdantic/config/builder.ex#L1)

Fluent builder for creating Exdantic configurations.

This module provides a chainable API for building complex configurations
in a readable and intuitive way.

# `t`

```elixir
@type t() :: %Exdantic.Config.Builder{opts: map()}
```

# `aggressive_coercion`

Convenience method to enable aggressive coercion.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.aggressive_coercion()
    %Exdantic.Config.Builder{opts: %{coercion: :aggressive}}

# `allow_extra`

Convenience method to allow extra fields.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.allow_extra()
    %Exdantic.Config.Builder{opts: %{extra: :allow}}

# `apply_preset`

```elixir
@spec apply_preset(t(), atom()) :: t()
```

Applies a preset configuration to the builder.

## Parameters
  * `builder` - The builder instance
  * `preset` - The preset name (same as Exdantic.Config.preset/1)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.apply_preset(:strict)
    %Exdantic.Config.Builder{opts: %{strict: true, extra: :forbid, ...}}

# `build`

```elixir
@spec build(t()) :: Exdantic.Config.t()
```

Builds the final configuration from the builder.

## Parameters
  * `builder` - The builder instance

## Returns
  * Exdantic.Config struct with the configured options

## Examples

    iex> config = Exdantic.Config.Builder.new()
    ...> |> Exdantic.Config.Builder.strict()
    ...> |> Exdantic.Config.Builder.forbid_extra()
    ...> |> Exdantic.Config.Builder.build()
    %Exdantic.Config{strict: true, extra: :forbid, ...}

# `case_insensitive`

Convenience method to disable case sensitivity.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.case_insensitive()
    %Exdantic.Config.Builder{opts: %{case_sensitive: false}}

# `case_sensitive`

```elixir
@spec case_sensitive(t(), boolean()) :: t()
```

Sets case sensitivity for field names.

## Parameters
  * `builder` - The builder instance
  * `enabled` - Whether to enable case sensitivity (default: true)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.case_sensitive()
    %Exdantic.Config.Builder{opts: %{case_sensitive: true}}

    iex> builder |> Exdantic.Config.Builder.case_sensitive(false)
    %Exdantic.Config.Builder{opts: %{case_sensitive: false}}

# `clone`

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

Clones a builder instance.

## Parameters
  * `builder` - The builder instance to clone

## Returns
  * New builder instance with the same configuration

## Examples

    iex> original = Exdantic.Config.Builder.new() |> Exdantic.Config.Builder.strict()
    iex> cloned = Exdantic.Config.Builder.clone(original)
    %Exdantic.Config.Builder{opts: %{strict: true}}

# `coercion`

```elixir
@spec coercion(t(), Exdantic.Config.coercion_strategy()) :: t()
```

Sets the coercion strategy.

## Parameters
  * `builder` - The builder instance
  * `strategy` - The coercion strategy (:none, :safe, :aggressive)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.coercion(:safe)
    %Exdantic.Config.Builder{opts: %{coercion: :safe}}

# `description_generator`

```elixir
@spec description_generator(t(), (atom() -> String.t())) :: t()
```

Sets a custom description generator function.

## Parameters
  * `builder` - The builder instance
  * `generator_fn` - Function that takes a field name and returns a description

## Returns
  * Updated builder instance

## Examples

    iex> desc_fn = fn field -> "Field for " <> Atom.to_string(field) end
    iex> builder |> Exdantic.Config.Builder.description_generator(desc_fn)
    %Exdantic.Config.Builder{opts: %{description_generator: #Function<...>}}

# `detailed_errors`

Convenience method to set detailed error format.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.detailed_errors()
    %Exdantic.Config.Builder{opts: %{error_format: :detailed}}

# `error_format`

```elixir
@spec error_format(t(), Exdantic.Config.error_format()) :: t()
```

Sets the error format style.

## Parameters
  * `builder` - The builder instance
  * `format` - The error format (:detailed, :simple, :minimal)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.error_format(:simple)
    %Exdantic.Config.Builder{opts: %{error_format: :simple}}

# `extra`

```elixir
@spec extra(t(), Exdantic.Config.extra_strategy()) :: t()
```

Sets how extra fields should be handled.

## Parameters
  * `builder` - The builder instance
  * `strategy` - The extra field strategy (:allow, :forbid, :ignore)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.extra(:forbid)
    %Exdantic.Config.Builder{opts: %{extra: :forbid}}

# `for_api`

Creates a configuration for API validation scenarios.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance with API-friendly settings

## Examples

    iex> builder |> Exdantic.Config.Builder.for_api()
    %Exdantic.Config.Builder{opts: %{strict: true, extra: :forbid, ...}}

# `for_development`

Creates a configuration for development scenarios.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance with development-friendly settings

## Examples

    iex> builder |> Exdantic.Config.Builder.for_development()
    %Exdantic.Config.Builder{opts: %{strict: false, coercion: :aggressive, ...}}

# `for_json_schema`

Creates a configuration for JSON Schema generation scenarios.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance with JSON Schema-friendly settings

## Examples

    iex> builder |> Exdantic.Config.Builder.for_json_schema()
    %Exdantic.Config.Builder{opts: %{use_enum_values: true, error_format: :minimal, ...}}

# `for_production`

Creates a configuration for production scenarios.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance with production-ready settings

## Examples

    iex> builder |> Exdantic.Config.Builder.for_production()
    %Exdantic.Config.Builder{opts: %{strict: true, frozen: true, ...}}

# `forbid_extra`

Convenience method to forbid extra fields.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.forbid_extra()
    %Exdantic.Config.Builder{opts: %{extra: :forbid}}

# `frozen`

```elixir
@spec frozen(t(), boolean()) :: t()
```

Sets whether the configuration should be frozen (immutable).

## Parameters
  * `builder` - The builder instance
  * `enabled` - Whether to freeze the config (default: true)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.frozen()
    %Exdantic.Config.Builder{opts: %{frozen: true}}

# `max_union_length`

```elixir
@spec max_union_length(t(), non_neg_integer()) :: t()
```

Sets the maximum length for anyOf unions in JSON Schema.

## Parameters
  * `builder` - The builder instance
  * `max_length` - Maximum union length

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.max_union_length(3)
    %Exdantic.Config.Builder{opts: %{max_anyof_union_len: 3}}

# `merge`

```elixir
@spec merge(t(), map() | keyword()) :: t()
```

Merges additional options into the builder.

## Parameters
  * `builder` - The builder instance
  * `opts` - Additional options to merge

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.merge(%{strict: true, frozen: true})
    %Exdantic.Config.Builder{opts: %{strict: true, frozen: true}}

# `new`

```elixir
@spec new() :: %Exdantic.Config.Builder{opts: %{}}
```

Creates a new configuration builder.

## Returns
  * New ConfigBuilder instance

## Examples

    iex> builder = Exdantic.Config.Builder.new()
    %Exdantic.Config.Builder{opts: %{}}

# `no_coercion`

Convenience method to disable coercion.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.no_coercion()
    %Exdantic.Config.Builder{opts: %{coercion: :none}}

# `reset`

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

Resets the builder to an empty state.

## Parameters
  * `builder` - The builder instance

## Returns
  * Reset builder instance

## Examples

    iex> builder = Exdantic.Config.Builder.new() |> Exdantic.Config.Builder.strict()
    iex> reset_builder = Exdantic.Config.Builder.reset(builder)
    %Exdantic.Config.Builder{opts: %{}}

# `safe_coercion`

Convenience method to enable safe coercion.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.safe_coercion()
    %Exdantic.Config.Builder{opts: %{coercion: :safe}}

# `simple_errors`

Convenience method to set simple error format.

## Parameters
  * `builder` - The builder instance

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.simple_errors()
    %Exdantic.Config.Builder{opts: %{error_format: :simple}}

# `strict`

```elixir
@spec strict(t(), boolean()) :: t()
```

Sets strict validation mode.

## Parameters
  * `builder` - The builder instance
  * `enabled` - Whether to enable strict mode (default: true)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.strict()
    %Exdantic.Config.Builder{opts: %{strict: true}}

    iex> builder |> Exdantic.Config.Builder.strict(false)
    %Exdantic.Config.Builder{opts: %{strict: false}}

# `summary`

```elixir
@spec summary(t()) :: map()
```

Returns a summary of the current builder configuration.

## Parameters
  * `builder` - The builder instance

## Returns
  * Map with current configuration options

## Examples

    iex> builder = Exdantic.Config.Builder.new() |> Exdantic.Config.Builder.strict()
    iex> Exdantic.Config.Builder.summary(builder)
    %{options_set: [:strict], option_count: 1, ready_to_build: true}

# `title_generator`

```elixir
@spec title_generator(t(), (atom() -&gt; String.t())) :: t()
```

Sets a custom title generator function.

## Parameters
  * `builder` - The builder instance
  * `generator_fn` - Function that takes a field name and returns a title

## Returns
  * Updated builder instance

## Examples

    iex> title_fn = fn field -> field |> Atom.to_string() |> String.capitalize() end
    iex> builder |> Exdantic.Config.Builder.title_generator(title_fn)
    %Exdantic.Config.Builder{opts: %{title_generator: #Function<...>}}

# `use_enum_values`

```elixir
@spec use_enum_values(t(), boolean()) :: t()
```

Sets whether to use enum values instead of names.

## Parameters
  * `builder` - The builder instance
  * `enabled` - Whether to use enum values (default: true)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.use_enum_values()
    %Exdantic.Config.Builder{opts: %{use_enum_values: true}}

# `validate_and_build`

```elixir
@spec validate_and_build(t()) :: {:ok, Exdantic.Config.t()} | {:error, [String.t()]}
```

Validates the builder configuration before building.

## Parameters
  * `builder` - The builder instance

## Returns
  * `{:ok, config}` if valid
  * `{:error, reasons}` if invalid

## Examples

    iex> valid_builder = Exdantic.Config.Builder.new() |> Exdantic.Config.Builder.strict()
    iex> Exdantic.Config.Builder.validate_and_build(valid_builder)
    {:ok, %Exdantic.Config{...}}

    iex> invalid_builder = Exdantic.Config.Builder.new()
    ...> |> Exdantic.Config.Builder.strict()
    ...> |> Exdantic.Config.Builder.allow_extra()
    iex> Exdantic.Config.Builder.validate_and_build(invalid_builder)
    {:error, ["strict mode conflicts with extra: :allow"]}

# `validate_assignment`

```elixir
@spec validate_assignment(t(), boolean()) :: t()
```

Sets whether to validate field assignments.

## Parameters
  * `builder` - The builder instance
  * `enabled` - Whether to enable assignment validation (default: true)

## Returns
  * Updated builder instance

## Examples

    iex> builder |> Exdantic.Config.Builder.validate_assignment()
    %Exdantic.Config.Builder{opts: %{validate_assignment: true}}

# `when_false`

```elixir
@spec when_false(t(), boolean() | (-&gt; boolean()), (t() -&gt; t())) :: t()
```

Applies configuration only if a condition is false.

## Parameters
  * `builder` - The builder instance
  * `condition` - Boolean condition or function that returns boolean
  * `config_fn` - Function to apply if condition is false

## Returns
  * Updated builder instance

## Examples

    iex> is_development = Application.get_env(:my_app, :env) == :dev
    iex> builder |> Exdantic.Config.Builder.when_false(is_development, &Exdantic.Config.Builder.frozen/1)
    %Exdantic.Config.Builder{...}

# `when_true`

```elixir
@spec when_true(t(), boolean() | (-&gt; boolean()), (t() -&gt; t())) :: t()
```

Conditionally applies a configuration based on a predicate.

## Parameters
  * `builder` - The builder instance
  * `condition` - Boolean condition or function that returns boolean
  * `config_fn` - Function to apply if condition is true

## Returns
  * Updated builder instance

## Examples

    iex> is_production = Application.get_env(:my_app, :env) == :prod
    iex> builder |> Exdantic.Config.Builder.when_true(is_production, &Exdantic.Config.Builder.frozen/1)
    %Exdantic.Config.Builder{...}

    iex> builder |> Exdantic.Config.Builder.when_true(true, fn b ->
    ...>   b |> Exdantic.Config.Builder.strict() |> Exdantic.Config.Builder.forbid_extra()
    ...> end)
    %Exdantic.Config.Builder{opts: %{strict: true, extra: :forbid}}

---

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