@spec decode(iodata(), [decode_opt()]) ::
  {:ok, term()} | {:error, RustyJson.DecodeError.t()}

Decodes a JSON string to an Elixir term.

Returns {:ok, term} on success or {:error, reason} on failure.

Options

• :keys - How to decode object keys. One of:

  • :strings - Keep as strings (default, safe)
  • :atoms - Convert to atoms (unsafe with untrusted input)
  • :atoms! - Convert to existing atoms only (safe, raises if atom missing)
  • :copy - Copy key binaries (equivalent to :strings in RustyJson)
  • :intern - Cache repeated keys during parsing. ~30% faster for arrays of objects with the same schema (REST APIs, GraphQL, database results, webhooks). The cache is capped at 4096 unique keys; beyond that, new keys are allocated normally (no worse than default). This bounds worst-case CPU time and stops paying cache overhead when keys aren't being reused. Caution: 2-3x slower for single objects or varied schemas—only use for homogeneous arrays of 10+ objects.
  • A function of arity 1 - Applied recursively to each key string. Example: keys: &String.upcase/1

• :strings - How to handle decoded strings. :reference (default) or :copy. Both produce copies in RustyJson (Rust NIFs always copy into BEAM binaries), so this option exists for Jason API compatibility.

• :objects - How to decode JSON objects. :maps (default) or :ordered_objects. When :ordered_objects, returns %RustyJson.OrderedObject{} structs that preserve key insertion order.

• :floats - How to decode JSON floats. :native (default) returns Elixir floats, :decimals returns %Decimal{} structs for exact decimal representation.

• :decoding_integer_digit_limit - Maximum number of digits allowed in the integer part of a JSON number. Integers exceeding this limit cause a decode error. Default: 1024, or the value of Application.compile_env(:rustyjson, :decoding_integer_digit_limit). Set to 0 to disable the limit.

Examples

iex> RustyJson.decode(~s({"name":"Alice","age":30}))
{:ok, %{"age" => 30, "name" => "Alice"}}

iex> RustyJson.decode(~s([1, 2, 3]))
{:ok, [1, 2, 3]}

iex> RustyJson.decode("invalid")
{:error, "Unexpected character at position 0"}

Security Considerations

Avoid keys: :atoms with untrusted input. Atoms are not garbage collected, so an attacker could exhaust your atom table by sending JSON with many unique keys.

Use keys: :atoms! if you expect specific keys to exist, or keys: :strings (default).

See decode!/2 for a version that raises on error.

@spec decode!(iodata(), [decode_opt()]) :: term()

Decodes a JSON string to an Elixir term, raising on error.

Same as decode/2 but raises RustyJson.DecodeError on failure. The raised exception includes :data, :position, and :token fields for detailed error diagnostics.

Options

See decode/2 for available options.

Examples

iex> RustyJson.decode!(~s({"x": [1, 2, 3]}))
%{"x" => [1, 2, 3]}

iex> RustyJson.decode!(~s({"x": 1}), keys: :atoms)
%{x: 1}

iex> RustyJson.decode!(~s({"x": 1}), keys: &String.upcase/1)
%{"X" => 1}

iex> RustyJson.decode!("null")
nil

iex> RustyJson.decode!("true")
true

iex> RustyJson.decode!(~s({"price":19.99}), floats: :decimals)
%{"price" => Decimal.new("19.99")}

JSON Types to Elixir

Error Cases

iex> RustyJson.decode!("invalid")
** (RustyJson.DecodeError) Unexpected character at position 0

iex> RustyJson.decode!("{trailing: comma,}")
** (RustyJson.DecodeError) Expected string key at position 1

@spec encode(term(), [encode_opt()]) ::
  {:ok, String.t()} | {:error, RustyJson.EncodeError.t() | Exception.t()}

Encodes an Elixir term to a JSON string.

Returns {:ok, json} on success or {:error, reason} on failure.

Options

• :pretty - Pretty print with indentation. true uses 2 spaces, or pass an integer for custom spacing. Default: false

• :escape - Escape mode for special characters. One of :json (default), :html_safe, :javascript_safe, or :unicode_safe. See escape_mode/0.

• :compress - Compression algorithm. :gzip or {:gzip, 0..9} for specific level. Default: :none

• :protocol - Enable RustyJson.Encoder protocol for custom types. Default: true

• :lean - Skip struct type detection (DateTime, Decimal, etc. encoded as raw maps). Default: false

• :maps - Key uniqueness mode. :naive (default) allows duplicate serialized keys, :strict errors on duplicate keys (e.g. atom :a and string "a").

• :sort_keys - Sort map keys lexicographically in output. Default: false. JSON objects are unordered per RFC 8259. Enable for deterministic output (useful for snapshot tests, caching, or diffing). Note: Jason always sorts keys; RustyJson does not by default for performance.

Examples

iex> RustyJson.encode(%{name: "Alice", scores: [95, 87, 92]})
{:ok, ~s({"name":"Alice","scores":[95,87,92]})}

iex> RustyJson.encode(%{valid: true}, pretty: true)
{:ok, "{\n  \"valid\": true\n}"}

iex> RustyJson.encode("invalid UTF-8: " <> <<0xFF>>)
{:error, "Failed to decode binary as UTF-8"}

Error Handling

Common error cases:

• Invalid UTF-8 binary
• Non-finite float (NaN, Infinity)
• Circular references (will cause stack overflow)

See encode!/2 for a version that raises on error.

@spec encode!(term(), [encode_opt()]) :: String.t()

Encodes an Elixir term to a JSON string, raising on error.

Same as encode/2 but raises RustyJson.EncodeError on failure.

Options

See encode/2 for available options.

Examples

iex> RustyJson.encode!(%{hello: "world"})
~s({"hello":"world"})

iex> RustyJson.encode!([1, 2, 3], pretty: 4)
"""
[
    1,
    2,
    3
]
"""

iex> RustyJson.encode!(~D[2024-01-15])
~s("2024-01-15")

iex> RustyJson.encode!(%{html: "<script>"}, escape: :html_safe)
~s({"html":"\u003cscript\u003e"})

Custom Encoding

For custom types, implement RustyJson.Encoder. The protocol is used by default (protocol: true). Implementations should return iodata via RustyJson.Encode functions for best performance:

defmodule Money do
  defstruct [:amount, :currency]
end

defimpl RustyJson.Encoder, for: Money do
  def encode(%Money{amount: amount, currency: currency}, opts) do
    RustyJson.Encode.map(%{amount: Decimal.to_string(amount), currency: currency}, opts)
  end
end

iex> money = %Money{amount: Decimal.new("99.99"), currency: "USD"}
iex> RustyJson.encode!(money)
~s({"amount":"99.99","currency":"USD"})

For backwards compatibility, returning a plain map is also supported and will be re-encoded automatically (with a small overhead).

Compression

iex> json = RustyJson.encode!(%{data: String.duplicate("x", 1000)}, compress: :gzip)
iex> :zlib.gunzip(json)
~s({"data":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"})

@spec encode_to_iodata(term(), [encode_opt()]) ::
  {:ok, iodata()} | {:error, RustyJson.EncodeError.t() | Exception.t()}

Encodes a term to iodata (for Phoenix compatibility).

This function exists to implement the Phoenix JSON library interface. Returns {:ok, binary} on success or {:error, reason} on failure.

A Note on iodata

RustyJson returns a single binary, not an iolist. This is intentional and provides excellent performance for payloads up to ~100MB.

The memory efficiency comes from the encoding process (no intermediate allocations), not from chunked output. A 10MB payload uses ~15MB peak memory.

For truly massive payloads (100MB+), consider:

• Streaming the data structure itself (encode in chunks)
• Using compression (compress: :gzip reduces output 5-10x)
• Pagination or chunked API design

Examples

iex> RustyJson.encode_to_iodata(%{status: "ok"})
{:ok, ~s({"status":"ok"})}

@spec encode_to_iodata!(term(), [encode_opt()]) :: iodata()

Encodes a term to iodata, raising on error (for Phoenix compatibility).

This function exists to implement the Phoenix JSON library interface. Raises RustyJson.EncodeError on failure.

See encode_to_iodata/2 for notes on iodata behavior.

Examples

iex> RustyJson.encode_to_iodata!(%{status: "ok"})
~s({"status":"ok"})