Linear \(O(N)\) ToJSON and FromJSON instances for heterogeneous and homogeneous Record and Variant types without standard GHC.Generics compile slowdowns: the codecs unroll the flat Rep payload directly into a JSON object and back, with no generic-representation tree anywhere.

Architectural Overview & Rationale

Encoding Structure

• A record encodes as an anonymous JSON object with one key per field symbol, in row order.
• A variant encodes as a single-member tagged object {"ctor": fields}, where the member key is the active constructor symbol and the value is the JSON object of that constructor's payload fields (or empty object for a nullary constructor).

Truly Heterogeneous Row Support

Unlike satellites restricted to homogeneous types, polytropos-aeson provides genuine heterogeneous serialization across open rows via AllToJSON and AllFromJSON: every field requires ToJSON / FromJSON at its own concrete type, so rows mixing String, Int, Bool, custom types, or nested rows serialize and deserialize directly without nominal intermediate wrappers.

Why Avoid GHC.Generics Trees for JSON

Standard aeson deriving walks a nested binary tree of M1, (:*:), and (:+:) constructors. On large schemas (30+ fields or constructors), this causes significant compile-time memory blow-up and runtime intermediate allocation overhead. polytropos-aeson walks the flat array of payload slots in a single tight loop directly into aeson's KeyMap.

When to Use This Module

• When serializing or deserializing polytropos open records and variants to and from JSON.

Worked Example

Records are most conveniently constructed using the REC { ... } syntax enabled by the polytropos source plugin (via -fplugin=Polytropos.Plugin):

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TypeApplications #-}
{-# OPTIONS_GHC -fplugin=Polytropos.Plugin #-}

import Data.Aeson (encode, decode)
import Polytropos
import Polytropos.Aeson

-- A genuinely heterogeneous record mixing String, Int, and Bool:
type Config = Record '["host" ':= String, "port" ':= Int, "active" ':= Bool]

cfg :: Config
cfg = REC { host = "localhost", port = 8080, active = True }

-- Encodes to JSON: {"active":true,"host":"localhost","port":8080}
jsonBytes = encode cfg

-- Decodes back to Config:
Just cfg' = decode @Config jsonBytes

Variants with heterogeneous constructors serialize into single-member tagged objects:

type Response = Variant '["Ok" ':= '["body" ':= String, "status" ':= Int], "Err" ':= '["reason" ':= String]]

resp :: Response
resp = VAR { Ok = REC { body = "server ready", status = 200 } }

-- Encodes to JSON: {"Ok":{"body":"server ready","status":200}}
respBytes = encode resp

Homogeneity Evidence and Introspection Helpers

In addition to the primary heterogeneous codecs (AllToJSON, AllFromJSON), this module provides closed type families and reflection classes for inspecting row metadata and enforcing uniform payload types.

1. AllFieldsAre is a closed type family asserting that every field in a row has the uniform type a.
2. RowField and SumField compute the uniform payload type directly from the row or sum row, eliminating type ambiguity for custom instances.
3. FieldNames reifies type-level Symbol field labels into runtime [String] keys in exact row order.
4. AllCtorsHom reifies the constructor topology of a homogeneous sum row into [(String, [String])] (mapping each constructor name to its list of field names).