# `ToonEx.Types`
[🔗](https://github.com/ohhi-vn/toon_ex/blob/v1.1.0/lib/toon_ex/shared/types.ex#L1)

Type definitions for TOON encoder and decoder.

This module defines all the types used throughout the TOON library,
ensuring type safety and better documentation.

# `decode_opt`

```elixir
@type decode_opt() ::
  {:keys, :strings | :atoms | :atoms!}
  | {:strict, boolean()}
  | {:indent_size, pos_integer()}
  | {:expand_paths, String.t()}
```

A single decoding option.

# `decode_opts`

```elixir
@type decode_opts() :: [decode_opt()]
```

Options for decoding TOON format.

## Options

  * `:keys` - How to decode map keys (default: `:strings`)
  * `:strict` - Enable strict mode validation (default: `true`)
  * `:indent_size` - Expected indentation size in spaces (default: 2)
  * `:expand_paths` - Path expansion mode: `:off` | `:safe` (default: `:off`)

## Examples

    ToonEx.decode!(toon, keys: :strings)
    ToonEx.decode!(toon, keys: :atoms)
    ToonEx.decode!(toon, strict: false)
    ToonEx.decode!(toon, expand_paths: :safe)

# `delimiter`

```elixir
@type delimiter() :: binary()
```

Valid delimiters for array values.

Can be comma, tab, or pipe character.

# `depth`

```elixir
@type depth() :: non_neg_integer()
```

Indentation depth level.

# `encodable`

```elixir
@type encodable() ::
  nil
  | boolean()
  | number()
  | String.t()
  | %{optional(String.t()) => encodable()}
  | [encodable()]
```

A normalized JSON-compatible value (output of encoding).

After the Encoder protocol processes input, the result is:
- Primitives: `nil`, `boolean()`, `number()`, `String.t()`
- Maps with string keys: `%{optional(String.t()) => encodable()}`
- Lists: `[encodable()]`

# `encode_opt`

```elixir
@type encode_opt() ::
  {:indent, pos_integer()}
  | {:delimiter, delimiter()}
  | {:length_marker, String.t() | nil}
  | {:key_folding, String.t()}
  | {:flatten_depth, non_neg_integer() | :infinity}
```

A single encoding option.

# `encode_opts`

```elixir
@type encode_opts() :: [encode_opt()]
```

Options for encoding TOON format.

## Options

  * `:indent` - Number of spaces for indentation (default: 2)
  * `:delimiter` - Delimiter for array values (default: ",")
  * `:length_marker` - Prefix for array length marker (default: nil)
  * `:key_folding` - Key folding mode: `:off` | `:safe` (default: `:off`)
  * `:flatten_depth` - Max depth for key folding: non-negative integer or `:infinity` (default: `:infinity`)

## Examples

    ToonEx.encode!(data, indent: 4)
    ToonEx.encode!(data, delimiter: "\t")
    ToonEx.encode!(data, length_marker: "#")
    ToonEx.encode!(data, key_folding: :safe)

# `input`

```elixir
@type input() :: term()
```

Any value that can be passed to the encoder.

The `ToonEx.Encoder` protocol normalizes input before encoding:
- Structs via `@derive ToonEx.Encoder` or explicit implementations
- Maps with atom keys are converted to string keys
- Custom types implement the protocol to define their encoding

This is `term()` because any type with an Encoder implementation is valid.

# `iodata_result`

```elixir
@type iodata_result() :: iodata()
```

IO data that can be efficiently concatenated.

# `primitive`

```elixir
@type primitive() :: nil | boolean() | number() | String.t()
```

A JSON-compatible primitive value.

---

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