# `Selecto.Output.Transformers.Json`

JSON transformer for Selecto query results.

Provides JSON serialization with configurable options for null handling,
metadata inclusion, pretty printing, and streaming support for large datasets.

## Options

- `:include_meta` - Include query metadata in response (default: false)
- `:pretty` - Pretty print JSON output (default: false)
- `:null_handling` - How to handle nil values: `:null`, `:omit`, `:empty_string` (default: `:null`)
- `:keys` - Key format: `:strings`, `:atoms` (default: `:strings`). Atom keys
  are used only when the atom already exists; unknown names remain strings.
- `:coerce_types` - Enable type coercion (default: false)
- `:date_format` - Date serialization format: `:iso8601`, `:unix`, `:string` (default: `:iso8601`)
- `:decimal_format` - Decimal format: `:string`, `:float` (default: `:string`)

## Examples

    # Basic JSON serialization
    {:ok, json} = Json.transform(rows, columns, %{}, [])

    # JSON with metadata
    {:ok, json} = Json.transform(rows, columns, %{}, [include_meta: true])

    # Pretty printed JSON with null omission
    {:ok, json} = Json.transform(rows, columns, %{}, [
      pretty: true,
      null_handling: :omit
    ])

    # Streaming for large datasets
    stream = Json.stream_transform(rows, columns, %{}, [pretty: true])

# `json_option`

```elixir
@type json_option() ::
  {:include_meta, boolean()}
  | {:pretty, boolean()}
  | {:null_handling, :null | :omit | :empty_string}
  | {:keys, :strings | :atoms}
  | {:coerce_types, boolean()}
  | {:date_format, :iso8601 | :unix | :string}
  | {:decimal_format, :string | :float}
```

# `json_options`

```elixir
@type json_options() :: [json_option()]
```

# `stream_transform`

```elixir
@spec stream_transform([list()] | Enumerable.t(), [String.t()], map(), json_options()) ::
  Enumerable.t()
```

Transform query results to a JSON stream for large datasets.

Returns a stream that yields JSON strings, useful for processing
large result sets without loading everything into memory.

# `transform`

```elixir
@spec transform([list()], [String.t()], map(), json_options()) ::
  {:ok, String.t()} | {:error, Selecto.Error.t()}
```

Transform query results to JSON string.

Returns a JSON string representation of the query results with configurable
serialization options.

---

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