Support integer map keys and add encode_to_iodata!

Phoenix's `:json_library` contract calls `encode_to_iodata!/1` from its
socket serializers, controllers, and longpoll transport, so configuring
Torque as the JSON library raised UndefinedFunctionError on every
message. `encode_to_iodata/2` already raises on error, so the new
function is a straight alias that also forwards the `:dirty` option.

LiveView renders diffs as maps with integer keys, which encoding
rejected with `:invalid_key`. JSON object names must be strings
(RFC 8259 §4), so an integer key has no direct representation: reject
or stringify are the only options, and Jason stringifies. Route
integer keys through the existing `encode_integer`, which already
handles the i64/u64/bignum cascade, so proplists get the same treatment
for free.

The conversion is lossy — `%{1 => "a"}` round-trips to `%{"1" => "a"}`,
and a map mixing both forms encodes to duplicate names — so document
that in Limitations rather than leave it to be found in production.

Reported in #47.

Author: lpgauth

CLAUDE.md

@@ -93,7 +93,7 @@ Torque is a high-performance JSON library for Elixir using Rustler NIFs backed b
 
 ### Encoding
 
-`encode/1` walks Elixir terms directly (no intermediate representation) and writes JSON bytes to a buffer. Supports maps (atom/binary keys), lists, numbers, booleans, nil, and jiffy-style `{proplist}` tuples.
+`encode/1` walks Elixir terms directly (no intermediate representation) and writes JSON bytes to a buffer. Supports maps (atom/binary/integer keys — integer keys are stringified, since JSON object names must be strings), lists, numbers, booleans, nil, and jiffy-style `{proplist}` tuples.
 
 ### Scheduler Awareness
 

README.md

@@ -104,6 +104,10 @@ already-parsed document via `Torque.get_many_nil(doc, pointers)`.
 {:ok, json} = Torque.encode(%{id: "abc", price: 1.5})
 # "{\"id\":\"abc\",\"price\":1.5}"
 
+# Integer keys are stringified — JSON object names must be strings
+{:ok, json} = Torque.encode(%{0 => "a", 1 => "b"})
+# "{\"0\":\"a\",\"1\":\"b\"}"
+
 # Bang variant
 json = Torque.encode!(%{id: "abc"})
 
@@ -116,8 +120,8 @@ json = Torque.encode_to_iodata(%{id: "abc"})
 
 Unlike decoding, encoding cannot cheaply predict its output size, so dirty
 scheduler dispatch is opt-in. Pass `dirty: true` (accepted by `encode/2`,
-`encode!/2`, and `encode_to_iodata/2`) when terms are expected to encode to
-large output (more than roughly 20 KB):
+`encode!/2`, `encode_to_iodata/2`, and `encode_to_iodata!/2`) when terms are
+expected to encode to large output (more than roughly 20 KB):
 
 ```elixir
 {:ok, json} = Torque.encode(big_term, dirty: true)
@@ -133,6 +137,7 @@ large output (more than roughly 20 KB):
 | `Torque.encode(term, opts)` | Encode term to JSON binary |
 | `Torque.encode!(term, opts)` | Encode term, raising on error |
 | `Torque.encode_to_iodata(term, opts)` | Encode term, returns binary directly (fastest) |
+| `Torque.encode_to_iodata!(term, opts)` | Alias for `encode_to_iodata/2` (Phoenix `:json_library`) |
 | `Torque.get(doc, path)` | Extract field by JSON Pointer path |
 | `Torque.get(doc, path, default)` | Extract field with default for missing paths |
 | `Torque.get_many(doc, paths)` | Extract multiple fields in one NIF call |
@@ -163,7 +168,7 @@ Integers outside the signed/unsigned 64-bit range decode as exact arbitrary-prec
 
 | Elixir | JSON |
 |--------|------|
-| map (atom/binary keys) | object |
+| map (atom/binary/integer keys) | object |
 | list | array |
 | binary | string |
 | integer | number |
@@ -191,7 +196,7 @@ Functions return `{:error, reason}` tuples (or raise `ArgumentError` for bang/io
 |------|-------------|---------|
 | `:unsupported_type` | `encode/1` | Term has no JSON representation (PID, reference, port, …) |
 | `:invalid_utf8` | `encode/1` | Binary string or map key is not valid UTF-8 |
-| `:invalid_key` | `encode/1` | Map key is not an atom or binary (e.g. integer key) |
+| `:invalid_key` | `encode/1` | Map key is not an atom, binary, or integer (e.g. float or tuple key) |
 | `:malformed_proplist` | `encode/1` | `{proplist}` contains a non-`{key, value}` element |
 | `:non_finite_float` | `encode/1` | Float is infinity or NaN (unreachable from normal BEAM code) |
 | `:nesting_too_deep` | `encode/1` | Term exceeds 128 nesting levels |
@@ -286,6 +291,7 @@ MIX_ENV=bench mix run bench/torque_bench.exs
 
 ## Limitations
 
+- **Integer map keys are lossy**: JSON object names must be strings (RFC 8259 §4), so `encode/1` stringifies integer keys and `decode/1` gives them back as binaries — `%{1 => "a"}` round-trips to `%{"1" => "a"}`. A map mixing both forms, like `%{1 => "a", "1" => "b"}`, encodes to duplicate names (`{"1":"a","1":"b"}`); RFC 8259 says names *should* be unique, and decoders resolve the collision however they choose. Jason behaves identically.
 - **Nesting depth**: JSON documents nested deeper than 128 levels return `{:error, :nesting_too_deep}` from `decode/1`, `parse/1`, `get/2`, `get_many/2`, and `encode/1` rather than crashing the VM. Real-world documents are never this deep; the limit exists to prevent stack overflow in the NIF (the dirty CPU scheduler, used for inputs over 20 KB, has a small stack).
 
 ## License

lib/torque.ex

@@ -20,17 +20,18 @@ defmodule Torque do
 
   ## Encoding
 
-  `encode/1` serializes Elixir terms to JSON. Supports maps (atom or
-  binary keys), lists, binaries, numbers, booleans, `nil`, and
-  jiffy-style `{proplist}` tuples.
+  `encode/1` serializes Elixir terms to JSON. Supports maps (atom,
+  binary, or integer keys), lists, binaries, numbers, booleans, `nil`,
+  and jiffy-style `{proplist}` tuples.
 
   ## Scheduler awareness
 
   Decoding and parsing automatically dispatch inputs larger than 20 KB to a
   dirty CPU scheduler to avoid blocking normal BEAM schedulers. Encoding
   cannot cheaply predict its output size up front, so dirty dispatch is
-  opt-in there: pass `dirty: true` to `encode/2`, `encode!/2`, or
-  `encode_to_iodata/2` when terms are expected to produce large output.
+  opt-in there: pass `dirty: true` to `encode/2`, `encode!/2`,
+  `encode_to_iodata/2`, or `encode_to_iodata!/2` when terms are expected
+  to produce large output.
 
   ## Type conversion
 
@@ -116,7 +117,8 @@ defmodule Torque do
 
   ## Supported terms
 
-    * Maps with atom or binary keys
+    * Maps with atom, binary, or integer keys (integer keys are
+      stringified — JSON object names must be strings)
     * Lists (JSON arrays)
     * Binaries (JSON strings)
     * Integers and floats
@@ -212,6 +214,23 @@ defmodule Torque do
     :error, value -> raise ArgumentError, "encode error: #{inspect(value)}"
   end
 
+  @doc """
+  Alias for `encode_to_iodata/2`, which already raises on error.
+
+  Exists to satisfy Phoenix's `:json_library` contract, which calls
+  `encode_to_iodata!/1` from its socket serializers, controllers, and
+  longpoll transport. Set `config :phoenix, :json_library, Torque` to use
+  Torque there.
+
+  ## Examples
+
+      iex> Torque.encode_to_iodata!(%{ok: true})
+      ~s({"ok":true})
+  """
+  @doc group: :encode
+  @spec encode_to_iodata!(term(), keyword()) :: binary()
+  def encode_to_iodata!(term, opts \\ []), do: encode_to_iodata(term, opts)
+
   # --- Parse + Get ---
 
   @doc """

native/torque_nif/src/encoder.rs

@@ -261,6 +261,10 @@ fn encode_map_key(
                     .map_err(|_| EncodeError::InvalidUtf8)?;
             }
         }
+        // Object names must be strings (RFC 8259 §4), so integer keys are
+        // stringified rather than rejected, matching Jason. Skips escaping
+        // because a decimal integer is only digits and a leading '-'.
+        TermType::Integer => encode_integer(env_raw, key, buf)?,
         _ => return Err(EncodeError::InvalidKey),
     }
     buf.push(b'"');

test/encode_test.exs

@@ -151,6 +151,47 @@ defmodule Torque.EncodeTest do
     test "invalid UTF-8 binary map key returns error" do
       assert {:error, :invalid_utf8} = Torque.encode(%{<<0x80>> => "value"})
     end
+
+    test "map with integer keys stringifies them" do
+      assert {:ok, json} = Torque.encode(%{0 => "a", 1 => "b"})
+      assert Jason.decode!(json) == %{"0" => "a", "1" => "b"}
+    end
+
+    test "negative integer map key" do
+      assert {:ok, ~s({"-1":"x"})} = Torque.encode(%{-1 => "x"})
+    end
+
+    test "integer map key beyond i64 uses the u64 path" do
+      assert {:ok, json} = Torque.encode(%{9_223_372_036_854_775_808 => "x"})
+      assert Jason.decode!(json) == %{"9223372036854775808" => "x"}
+    end
+
+    test "bignum map key encodes exactly" do
+      assert {:ok, json} = Torque.encode(%{1_180_591_620_717_411_303_424 => "x"})
+      assert Jason.decode!(json) == %{"1180591620717411303424" => "x"}
+    end
+
+    test "negative bignum map key encodes exactly" do
+      assert {:ok, json} = Torque.encode(%{-1_180_591_620_717_411_303_424 => "x"})
+      assert Jason.decode!(json) == %{"-1180591620717411303424" => "x"}
+    end
+
+    test "proplist with integer keys stringifies them" do
+      assert {:ok, ~s({"1":"a","2":"b"})} = Torque.encode({[{1, "a"}, {2, "b"}]})
+    end
+
+    test "integer and binary keys that collide emit duplicate names" do
+      assert {:ok, json} = Torque.encode(%{1 => "a", "1" => "b"})
+      assert json in [~s({"1":"a","1":"b"}), ~s({"1":"b","1":"a"})]
+    end
+
+    test "float map key is still rejected" do
+      assert {:error, :invalid_key} = Torque.encode(%{1.5 => "x"})
+    end
+
+    test "tuple map key is still rejected" do
+      assert {:error, :invalid_key} = Torque.encode(%{{:a, :b} => "x"})
+    end
   end
 
   describe "encode/2 with dirty: true" do
@@ -227,4 +268,28 @@ defmodule Torque.EncodeTest do
       end
     end
   end
+
+  describe "encode_to_iodata!/2" do
+    test "matches encode_to_iodata/1 output" do
+      term = %{nested: %{list: [1, 2, 3], str: "hello"}}
+      assert Torque.encode_to_iodata!(term) == Torque.encode_to_iodata(term)
+    end
+
+    test "unsupported term raises ArgumentError" do
+      assert_raise ArgumentError, ~r/unsupported_type/, fn ->
+        Torque.encode_to_iodata!(self())
+      end
+    end
+
+    test "accepts dirty: true" do
+      term = %{"a" => [1, 2, 3], "b" => "hello"}
+      assert Torque.encode_to_iodata!(term, dirty: true) == Torque.encode_to_iodata!(term)
+    end
+
+    test "is exported at arity 1 for Phoenix's :json_library contract" do
+      Code.ensure_loaded!(Torque)
+      assert function_exported?(Torque, :encode_to_iodata!, 1)
+      assert function_exported?(Torque, :decode!, 1)
+    end
+  end
 end

test/property_test.exs

@@ -546,8 +546,8 @@ defmodule Torque.PropertyTest do
       assert {:error, :unsupported_type} = Torque.encode({"not_a_list"})
     end
 
-    test "integer map key returns invalid_key" do
-      assert {:error, :invalid_key} = Torque.encode(%{42 => "v"})
+    test "float map key returns invalid_key" do
+      assert {:error, :invalid_key} = Torque.encode(%{4.2 => "v"})
     end
 
     test "proplist item not a tuple returns malformed_proplist" do