Structural.hs

-- | Stable runtime contract between consumer-owned domain types and
-- Keiro-generated structural wire shapes.
--
-- Stability: this module is a published integration point for consumer binding
-- modules and @keiro-dsl@ generated code. Its types and record field names are
-- stable within a major version. Additions are permitted; renames or semantic
-- changes require a major version bump and a coordinated @keiro-dsl@ release.
--
-- The generated codec is the single authority for the wire schema. A consumer
-- 'Data.Aeson.ToJSON' or 'Data.Aeson.FromJSON' instance may delegate to that
-- generated codec through a binding, but Keiro never delegates structural
-- encoding to a consumer instance.
module Keiro.Codec.Structural
  ( StructuralBinding (..),
    FixtureCases (..),
    bindingDomainRoundTrip,
    bindingShapeRoundTrip,
    encodeViaBinding,
    decodeViaBinding,
  )
where

import Data.Aeson (Value)
import Data.List.NonEmpty (NonEmpty)
import Data.Text (Text)

-- | A total construction and destruction boundary between a consumer-owned
-- type and its declared structural shape.
--
-- Consumer invariants must be represented by the shape. If converting a valid
-- shape into the consumer type can fail, the declaration is not structural and
-- must use Keiro's opaque mapping mode instead.
data StructuralBinding a shape = StructuralBinding
  { bindingToShape :: !(a -> shape),
    bindingFromShape :: !(shape -> a)
  }

-- | Deterministic, labelled consumer values used by generated conformance
-- harnesses.
--
-- The generator checks these cases against every declared union and nullable
-- branch. Values are never invented through @Arbitrary@ or @Default@. Generated
-- harnesses also reject empty or duplicate labels so failures keep a stable
-- identity.
newtype FixtureCases a = FixtureCases
  { fixtureCases :: NonEmpty (Text, a)
  }
  deriving stock (Eq, Show)

-- | Check that a consumer value survives conversion through its shape.
bindingDomainRoundTrip :: (Eq a) => StructuralBinding a shape -> a -> Bool
bindingDomainRoundTrip binding value =
  bindingFromShape binding (bindingToShape binding value) == value

-- | Check that every declared shape survives conversion through the consumer type.
bindingShapeRoundTrip :: (Eq shape) => StructuralBinding a shape -> shape -> Bool
bindingShapeRoundTrip binding shape =
  bindingToShape binding (bindingFromShape binding shape) == shape

-- | Encode a consumer value by first converting it to the generated shape.
--
-- This is the sanctioned delegation direction for a consumer-owned JSON
-- instance: the generated shape encoder remains the wire authority.
encodeViaBinding :: StructuralBinding a shape -> (shape -> Value) -> a -> Value
encodeViaBinding binding encodeShape = encodeShape . bindingToShape binding

-- | Decode the generated shape and then apply the binding's total constructor.
--
-- All failure comes from parsing JSON into the generated shape. Applying the
-- binding introduces no hidden semantic rejection.
decodeViaBinding ::
  StructuralBinding a shape ->
  (Value -> Either Text shape) ->
  Value ->
  Either Text a
decodeViaBinding binding decodeShape value =
  bindingFromShape binding <$> decodeShape value