# `Selecto.FieldResolver`

Enhanced field resolution system for Selecto with disambiguation, aliasing, and dynamic resolution.

This module provides advanced field resolution capabilities including:
- Field disambiguation when multiple tables have same field names
- Dynamic field resolution at runtime
- Field aliasing for better naming and conflict resolution
- Smart error messages with suggestions
- Support for qualified field references
- Join-aware field validation
- Parameterized joins with dot notation support

## Field Reference Formats

### Basic Field References
- `"field_name"` - Field from source table
- `"join.field_name"` - Qualified field from specific join
- `"table_alias.field_name"` - Field using table alias

### Parameterized Join References (New)
- `"join:param.field_name"` - Parameterized join with single parameter
- `"join:param1:param2.field_name"` - Multiple parameters
- `"join:50:true:'quoted param'.field_name"` - Mixed parameter types

### Advanced Field References
- `{:field, "field_name", alias: "custom_alias"}` - Field with custom alias
- `{:qualified_field, "join.field_name"}` - Explicitly qualified field
- `{:disambiguated_field, "field_name", from: "join"}` - Disambiguated field reference

## Usage Examples

    # Basic resolution
    {:ok, field_info} = FieldResolver.resolve_field(selecto, "user_name")

    # Qualified resolution
    {:ok, field_info} = FieldResolver.resolve_field(selecto, "users.name")

    # Parameterized join resolution
    {:ok, field_info} = FieldResolver.resolve_field(selecto, "products:electronics:true.name")

    # With disambiguation
    {:ok, field_info} = FieldResolver.resolve_field(selecto, {:disambiguated_field, "name", from: "users"})

    # Get all available fields
    all_fields = FieldResolver.get_available_fields(selecto)

    # Find field suggestions
    suggestions = FieldResolver.suggest_fields(selecto, "nam")

# `field_info`

```elixir
@type field_info() :: %{
  name: String.t(),
  qualified_name: String.t(),
  source_join: atom(),
  type: atom(),
  alias: String.t() | nil,
  table_alias: String.t() | nil,
  parameters: [map()] | nil,
  parameter_signature: String.t() | nil
}
```

# `field_reference`

```elixir
@type field_reference() :: String.t() | atom() | tuple()
```

# `resolution_result`

```elixir
@type resolution_result() :: {:ok, field_info()} | {:error, term()}
```

# `get_available_fields`

```elixir
@spec get_available_fields(Selecto.t()) :: %{required(String.t()) => field_info()}
```

Get all available fields from all joins and the source table.

Returns a map with field names as keys and field info as values.

# `get_disambiguation_options`

```elixir
@spec get_disambiguation_options(Selecto.t(), String.t()) :: [field_info()]
```

Get disambiguation options for an ambiguous field.

# `is_ambiguous_field?`

```elixir
@spec is_ambiguous_field?(Selecto.t(), String.t()) :: boolean()
```

Check if a field reference is ambiguous (exists in multiple tables).

# `resolve_field`

```elixir
@spec resolve_field(Selecto.t(), field_reference()) :: resolution_result()
```

Resolve a field reference to detailed field information.

Handles various field reference formats and provides disambiguation when needed.

# `suggest_fields`

```elixir
@spec suggest_fields(Selecto.t(), String.t()) :: [String.t()]
```

Find field suggestions for a partial field name.

Useful for autocomplete and error messages with suggestions.

# `validate_field_references`

```elixir
@spec validate_field_references(Selecto.t(), [field_reference()]) ::
  :ok | {:error, [term()]}
```

Validate that all field references in a list are resolvable.

---

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