@@ -85,16 +85,30 @@ instance (DBComposite a, OrdTable (HKD a Expr)) => DBMax (Composite a)
8585instance (DBComposite a, OrdTable (HKD a Expr)) => DBMin (Composite a)
8686
8787
88+-- | 'DBComposite' is used to associate composite type metadata with a Haskell
89+-- type.
8890type DBComposite :: Type -> Constraint
8991class (DBType a, HKDable a) => DBComposite a where
92+ -- | The names of all fields in the composite type that @a@ maps to.
9093 compositeFields :: HKD a Name
94+
95+ -- | The name of the composite type that @a@ maps to.
9196 compositeTypeName :: String
9297
9398
99+-- | Collapse a 'HKD' into a PostgreSQL composite type.
100+--
101+-- 'HKD' values are represented in queries by having a column for each field in
102+-- the corresponding Haskell type. 'compose' collapses these columns into a
103+-- single column expression, by combining them into a PostgreSQL composite
104+-- type.
94105compose :: DBComposite a => HKD a Expr -> Expr a
95106compose = castExpr . fromPrimExpr . encoder
96107
97108
109+-- | Expand a composite type into a 'HKD'.
110+--
111+-- 'decompose' is the inverse of 'compose'.
98112decompose :: forall a. DBComposite a => Expr a -> HKD a Expr
99113decompose (toPrimExpr -> a) = fromColumns $ htabulate \field ->
100114 case hfield names field of