fix(types): accept term() for encoder input to support structs

The Toon.Encoder protocol normalizes input before encoding, so the
public API should accept any term() - not just pre-normalized types.

Changes:
- Add Toon.Types.input() type as term() for encoder parameters
- Update encode/1,2 and encode!/1,2 specs to use input()
- Keep encodable() for normalized output (string-keyed maps)
- Add tests for struct and atom-key encoding via public API

This fixes Dialyzer warnings when calling Toon.encode!/1 with:
- Ecto schemas (structs with atom keys)
- Maps with atom keys
- Any type implementing the Toon.Encoder protocol

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Chris Xu

lib/toon.ex

@@ -78,7 +78,7 @@ defmodule Toon do
       iex> Toon.encode(%{"data" => [1, 2, 3]}, delimiter: "\\t")
       {:ok, "data[3\\t]: 1\\t2\\t3"}
   """
-  @spec encode(Toon.Types.encodable(), keyword()) ::
+  @spec encode(Toon.Types.input(), keyword()) ::
           {:ok, String.t()} | {:error, EncodeError.t()}
   defdelegate encode(data, opts \\ []), to: Encode
 
@@ -96,7 +96,7 @@ defmodule Toon do
       iex> Toon.encode!(%{"count" => 42, "active" => true})
       "active: true\\ncount: 42"
   """
-  @spec encode!(Toon.Types.encodable(), keyword()) :: String.t()
+  @spec encode!(Toon.Types.input(), keyword()) :: String.t()
   defdelegate encode!(data, opts \\ []), to: Encode
 
   @doc """

lib/toon/encode/encode.ex

@@ -32,7 +32,7 @@ defmodule Toon.Encode do
       iex> Toon.Encode.encode(%{"name" => "Alice"}, indent: 4)
       {:ok, "name: Alice"}
   """
-  @spec encode(Toon.Types.encodable(), keyword()) ::
+  @spec encode(Toon.Types.input(), keyword()) ::
           {:ok, String.t()} | {:error, EncodeError.t()}
   def encode(data, opts \\ []) do
     start_time = System.monotonic_time()
@@ -99,7 +99,7 @@ defmodule Toon.Encode do
       iex> Toon.Encode.encode!(%{"tags" => ["a", "b"]})
       "tags[2]: a,b"
   """
-  @spec encode!(Toon.Types.encodable(), keyword()) :: String.t()
+  @spec encode!(Toon.Types.input(), keyword()) :: String.t()
   def encode!(data, opts \\ []) do
     case encode(data, opts) do
       {:ok, result} -> result

lib/toon/shared/types.ex

@@ -12,11 +12,23 @@ defmodule Toon.Types do
   @type primitive :: nil | boolean() | number() | String.t()
 
   @typedoc """
-  A JSON-compatible value that can be encoded to TOON format.
+  Any value that can be passed to the encoder.
 
-  This is a recursive type that includes:
+  The `Toon.Encoder` protocol normalizes input before encoding:
+  - Structs via `@derive Toon.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.
+  """
+  @type input :: term()
+
+  @typedoc """
+  A normalized JSON-compatible value (output of encoding).
+
+  After the Encoder protocol processes input, the result is:
   - Primitives: `nil`, `boolean()`, `number()`, `String.t()`
-  - Maps: `%{optional(String.t()) => encodable()}`
+  - Maps with string keys: `%{optional(String.t()) => encodable()}`
   - Lists: `[encodable()]`
   """
   @type encodable ::

test/toon/encoder_test.exs

@@ -161,4 +161,40 @@ defmodule Toon.EncoderTest do
       assert Toon.Utils.normalize(user) == %{"name" => "Bob", "email" => "bob@test.com"}
     end
   end
+
+  # These tests verify the public API accepts structs and atom-keyed maps.
+  # The Encoder protocol handles normalization, so the type specs must accept term().
+  describe "Toon.encode!/1 accepts structs (Dialyzer compatibility)" do
+    test "encodes struct with @derive Toon.Encoder" do
+      person = %Person{name: "Alice", age: 30}
+      result = Toon.encode!(person)
+
+      assert result =~ "name: Alice"
+      assert result =~ "age: 30"
+    end
+
+    test "encodes struct with explicit Encoder implementation" do
+      date = %CustomDate{year: 2024, month: 6, day: 15}
+      result = Toon.encode!(date)
+
+      assert result == "2024-06-15"
+    end
+  end
+
+  describe "Toon.encode!/1 accepts maps with atom keys (Dialyzer compatibility)" do
+    test "encodes map with atom keys" do
+      data = %{name: "Bob", active: true}
+      result = Toon.encode!(data)
+
+      assert result =~ "name: Bob"
+      assert result =~ "active: true"
+    end
+
+    test "encodes nested map with atom keys" do
+      data = %{user: %{name: "Charlie", age: 25}}
+      result = Toon.encode!(data)
+
+      assert result =~ "name: Charlie"
+    end
+  end
 end