@type list_type() ::
  {:list,
   type: t(),
   reject_invalid: boolean(),
   min_length: non_neg_integer(),
   max_length: non_neg_integer(),
   nilable: boolean(),
   default: default(),
   in: Enumerable.t(),
   transform: transform(),
   validate: validate()}
  | :list

List type. Validates each element against the given type.

Bare :list validates the value is a list and returns as-is (passthrough).

The shortcut [type] can always be used instead of {:list, type: type}, including with options: {[type], opts}.

Options:

• :type – the element type t/0 (required)
• :reject_invalid – drop invalid items instead of failing
• :min_length – minimum list length (inclusive)
• :max_length – maximum list length (inclusive)
• Shared options

Examples

iex> Mold.parse([:string], ["a", "b"])
{:ok, ["a", "b"]}

iex> Mold.parse([%{name: :string}], [%{"name" => "A"}, %{"name" => "B"}])
{:ok, [%{name: "A"}, %{name: "B"}]}

iex> Mold.parse({[:integer], min_length: 1, max_length: 3}, [])
{:error, [%Mold.Error{reason: {:too_short, min_length: 1}, value: []}]}

iex> Mold.parse({[:string], reject_invalid: true}, ["a", nil, "b"])
{:ok, ["a", "b"]}

iex> Mold.parse([:integer], ["1", "abc", "3"])
{:error, [%Mold.Error{reason: :invalid_format, value: "abc", trace: [1]}]}

@type map_type() ::
  {:map,
   fields: [
     {term(), t() | [type: t(), source: source_path(), optional: boolean()]}
   ],
   keys: t(),
   values: t(),
   source: (term() -> any()),
   reject_invalid: boolean(),
   nilable: boolean(),
   default: default(),
   in: Enumerable.t(),
   transform: transform(),
   validate: validate()}
  | :map

Map type. Three forms:

• Bare :map — validates the value is a map, returns as-is (passthrough).
• {:map, fields: [...]} — validates maps field-by-field. Field names are typically atoms (the default source converts them to strings for lookup); non-atom keys require a custom source.
• {:map, keys: t, values: t} — homogeneous map, parses all keys and values.

Options for fields:

• :fields – list of {name, type} tuples where each value is either a t/0 (name: :string) or a keyword list with field options:
  • :type – the field type t/0 (required)
  • :source – where to read the value from. A single step or a list of steps (path), like get_in/2. Each step can be:
    • function – Access accessor (e.g. Access.at/1, Access.elem/1, Access.key/2)
    • any other term – key lookup via Access.fetch/2 (string, atom, integer, etc.)
  • :optional – when true, omit field from result when missing from input
• :source – a function (field_name -> any()) that derives the source key from each field name (e.g. source: &(Atom.to_string(&1) |> Macro.camelize())). Defaults to &Atom.to_string/1. Propagates recursively to nested maps, including through lists and tuples.

Options for keys/values:

• :keys – type t/0 for all keys
• :values – type t/0 for all values

Both fields and keys/values forms support:

• :reject_invalid – drop items that fail parsing instead of returning an error. For fields, only affects fields marked optional: true — required fields still fail. For keys/values, drops the key-value pair that failed.

Shared options apply to all forms.

Examples

iex> Mold.parse(%{name: :string, age: :integer}, %{"name" => "Alice", "age" => "25"})
{:ok, %{name: "Alice", age: 25}}

Source defaults to &Atom.to_string/1 — field names are looked up as string keys. Custom source per field:

iex> schema = {:map, fields: [
...>   user_name: [type: :string, source: "userName"],
...>   is_active: [type: :boolean, source: "isActive"]
...> ]}
iex> Mold.parse(schema, %{"userName" => "Alice", "isActive" => "true"})
{:ok, %{user_name: "Alice", is_active: true}}

Nested source paths:

iex> schema = {:map, fields: [name: [type: :string, source: ["details", "name"]]]}
iex> Mold.parse(schema, %{"details" => %{"name" => "Alice"}})
{:ok, %{name: "Alice"}}

Access functions for advanced navigation — Access.at/1 for lists, Access.elem/1 for tuples, Access.key/2 with a default, and more:

iex> schema = {:map, fields: [
...>   lat: [type: :float, source: ["coords", Access.at(0)]],
...>   lng: [type: :float, source: ["coords", Access.at(1)]]
...> ]}
iex> Mold.parse(schema, %{"coords" => [49.8, 24.0]})
{:ok, %{lat: 49.8, lng: 24.0}}

Global source function (propagates to nested maps):

iex> schema = {
...>   %{user_name: :string, address: %{zip_code: :string}},
...>   source: &(Atom.to_string(&1) |> Macro.camelize())
...> }
iex> Mold.parse(schema, %{"UserName" => "Alice", "Address" => %{"ZipCode" => "10001"}})
{:ok, %{user_name: "Alice", address: %{zip_code: "10001"}}}

Non-atom field names work with a custom source:

iex> schema = {:map,
...>   source: fn {ns, name} -> Enum.join([ns, name], ":") end,
...>   fields: [
...>     {{:feature, :dark_mode}, :boolean},
...>     {{:feature, :beta}, :boolean}
...>   ]}
iex> Mold.parse(schema, %{"feature:dark_mode" => "true", "feature:beta" => "0"})
{:ok, %{{:feature, :dark_mode} => true, {:feature, :beta} => false}}

Optional fields:

iex> schema = {:map, fields: [
...>   name: :string,
...>   bio: [type: :string, optional: true]
...> ]}
iex> Mold.parse(schema, %{"name" => "Alice"})
{:ok, %{name: "Alice"}}
iex> Mold.parse(schema, %{"name" => "Alice", "bio" => "hello"})
{:ok, %{name: "Alice", bio: "hello"}}
iex> # optional omits the field when missing, but nil still fails — use nilable on the type
iex> Mold.parse(schema, %{"name" => "Alice", "bio" => nil})
{:error, [%Mold.Error{reason: :unexpected_nil, value: nil, trace: ["bio"]}]}

When a field is both optional: true and has a default, optional takes priority for missing fields — the field is omitted from the result. The default only applies when the field is present but nil:

iex> schema = {:map, fields: [
...>   bio: [type: {:string, default: "none"}, optional: true]
...> ]}
iex> Mold.parse(schema, %{})
{:ok, %{}}
iex> Mold.parse(schema, %{"bio" => nil})
{:ok, %{bio: "none"}}

Missing fields are errors:

iex> Mold.parse(%{name: :string}, %{})
{:error, [%Mold.Error{reason: {:missing_field, "name"}, value: %{}, trace: []}]}

Homogeneous maps with keys/values:

iex> Mold.parse({:map, keys: :string, values: :integer}, %{"a" => "1", "b" => "2"})
{:ok, %{"a" => 1, "b" => 2}}

iex> Mold.parse({:map, keys: :atom, values: :string}, %{"name" => "Alice"})
{:ok, %{name: "Alice"}}

Reject invalid — for fields, only optional fields are affected:

iex> schema = {:map, reject_invalid: true, fields: [
...>   name: :string,
...>   age: [type: :integer, optional: true],
...>   bio: [type: :string, optional: true]
...> ]}
iex> Mold.parse(schema, %{"name" => "Alice", "age" => "nope", "bio" => nil})
{:ok, %{name: "Alice"}}
iex> Mold.parse(schema, %{"age" => "25"})
{:error, [%Mold.Error{reason: {:missing_field, "name"}, value: %{"age" => "25"}, trace: []}]}

Reject invalid — for keys/values, drops the key-value pair that failed:

iex> Mold.parse({:map, keys: :string, values: :integer, reject_invalid: true}, %{"a" => "1", "b" => "nope"})
{:ok, %{"a" => 1}}

@type tuple_type() ::
  {:tuple,
   elements: [t()],
   nilable: boolean(),
   default: default(),
   in: Enumerable.t(),
   transform: transform(),
   validate: validate()}
  | :tuple

Tuple type. Validates each element positionally. Accepts both tuples and lists as input.

Bare :tuple validates the value is a tuple (or list), converts lists to tuples, returns as-is.

Options:

• :elements – list of t/0, one per element (required)
• Shared options

Examples

iex> Mold.parse({:tuple, elements: [:string, :integer]}, ["Alice", "25"])
{:ok, {"Alice", 25}}

iex> Mold.parse({:tuple, elements: [:string, :integer]}, {"Alice", "25"})
{:ok, {"Alice", 25}}

iex> Mold.parse({:tuple, elements: [:string, :integer]}, ["only_one"])
{:error, [%Mold.Error{reason: {:unexpected_length, expected: 2, got: 1}, value: ["only_one"]}]}

iex> Mold.parse(:tuple, [1, "two", :three])
{:ok, {1, "two", :three}}