-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Defines generic 'Envelope' type to wrap reponses from a JSON API.
--   
--   Please see README.md
@package envelope
@version 0.2.2.0


-- | This module contains the <a>Envelope</a> type and helper functions.
--   The <a>Envelope</a> type can be used to wrap responses from a JSON
--   API.
--   
--   The following is an example of using this package.
--   
--   First, we will import some needed modules.
--   
--   <pre>
--   &gt;&gt;&gt; import qualified Data.ByteString.Lazy.Char8 as C8
--   
--   &gt;&gt;&gt; import Data.Aeson (decode, encode)
--   </pre>
--   
--   Let's look at how a success reponse is encoded and decoded. It is
--   encoded as an object with a single member: <tt>"data"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let successEnvelope = toSuccessEnvelope 3 :: Envelope Text Int
--   
--   &gt;&gt;&gt; C8.putStrLn $ encode successEnvelope
--   {"data":3}
--   
--   &gt;&gt;&gt; decode "{\"data\":3}" :: Maybe (Envelope Text Int)
--   Just (EnvelopeSuccess (Success 3))
--   </pre>
--   
--   Now lets look at how an error response is encoded and decoded. It is
--   encoded as an object with two members: <tt>"extra"</tt> and
--   <tt>"error"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let errorEnvelope = toErrEnvelope "DB_ERROR" "there was an error with the database" :: Envelope String Int
--   
--   &gt;&gt;&gt; C8.putStrLn $ encode errorEnvelope
--   {"extra":"there was an error with the database","error":"DB_ERROR"}
--   
--   &gt;&gt;&gt; decode "{\"extra\":\"there was an error with the database\",\"error\":\"DB_ERROR\"}" :: Maybe (Envelope String Int)
--   Just (EnvelopeErr (Err {errErr = "DB_ERROR", errExtra = Just "there was an error with the database"}))
--   </pre>
--   
--   The <a>Success</a> and <a>Err</a> types are used within the
--   <a>Envelope</a> type synonym.
module Web.Envelope

-- | Main type to be used. Wrapper around responses from an API, mainly
--   used with a JSON API.
--   
--   Type synonym around <a>Envelope'</a>.
type Envelope e a = Envelope' (Err e) (Success a)

-- | Wrapper around either a success or an error. Isomorphic to
--   <a>Either</a>.
--   
--   The only interesting part of this type is the <a>ToJSON</a> and
--   <a>FromJSON</a> instances.
data Envelope' e a
EnvelopeErr :: e -> Envelope' e a
EnvelopeSuccess :: a -> Envelope' e a

-- | Newtype wrapper to be able to provide specific instances. Used with
--   <a>Envelope</a>.
newtype Success a
Success :: a -> Success a

-- | Wrapper to add an extra field with info about the error. Used with
--   <a>Envelope</a>.
data Err e
Err :: e -> Maybe Text -> Err e

-- | Actual error information we want to send.
[errErr] :: Err e -> e

-- | Additional error information in plain text.
[errExtra] :: Err e -> Maybe Text

-- | Smart constructor for <a>Err</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toErr "DB_ERROR" "an error occurred"
--   Err {errErr = "DB_ERROR", errExtra = Just "an error occurred"}
--   </pre>
toErr :: e -> Text -> Err e

-- | Smart constructor for <a>Err</a> that doesn't use an <a>errExtra</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toErr' "DB_ERROR"
--   Err {errErr = "DB_ERROR", errExtra = Nothing}
--   </pre>
toErr' :: e -> Err e

-- | Throw an <tt>'Err e'</tt> using <a>throwError</a> in a <a>Monad</a>
--   that implements <a>MonadError</a>.
--   
--   If you have <tt><tt>ExceptT</tt> (<a>Err</a> e)</tt> somewhere inside
--   your monad transformer stacks, this function can be used to throw an
--   error (return early) in a function.
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad.Except (runExcept)
--   
--   &gt;&gt;&gt; throwEnvelopeErr "BAD_ERROR" "a very bad error occurred!" :: Either (Err String) Int
--   Left (Err {errErr = "BAD_ERROR", errExtra = Just "a very bad error occurred!"})
--   </pre>
--   
--   Here is a longer example using a monad stack.
--   
--   <pre>
--   type MyMonadStack = ReaderT Int (ExceptT (Err String) IO)
--   
--   doSomething :: Int -&gt; MyMonadStack Int
--   doSomething int =
--       if int &lt; 0
--           then
--               throwEnvelopeErr "INT_TOO_SMALL" "the integer passed to doSomething is too small"
--           else
--               return (int + 1)
--   </pre>
throwEnvelopeErr :: (MonadError (Err e) m) => e -> Text -> m a

-- | Like <a>throwEnvelopeErr</a> but without providing a message.
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad.Except (runExcept)
--   
--   &gt;&gt;&gt; throwEnvelopeErr "BAD_ERROR" "a very bad error occurred!" :: Either (Err String) Int
--   Left (Err {errErr = "BAD_ERROR", errExtra = Just "a very bad error occurred!"})
--   </pre>
throwEnvelopeErr' :: (MonadError (Err e) m) => e -> m a

-- | Wrap an <tt>a</tt> in a success <a>Envelope</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toSuccessEnvelope 3 :: Envelope String Int
--   EnvelopeSuccess (Success 3)
--   </pre>
toSuccessEnvelope :: a -> Envelope e a

-- | Wrap an <tt>a</tt> and an additional message in an error
--   <a>Envelope</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toErrEnvelope "DB_ERROR" "there was an error with the database" :: Envelope String Int
--   EnvelopeErr (Err {errErr = "DB_ERROR", errExtra = Just "there was an error with the database"})
--   </pre>
toErrEnvelope :: e -> Text -> Envelope e a

-- | Wrap an <tt>a</tt> in an error <a>Envelope</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toErrEnvelope' "DB_ERROR" :: Envelope String Int
--   EnvelopeErr (Err {errErr = "DB_ERROR", errExtra = Nothing})
--   </pre>
toErrEnvelope' :: e -> Envelope e a
instance GHC.Show.Show e => GHC.Show.Show (Web.Envelope.Err e)
instance GHC.Generics.Generic (Web.Envelope.Err e)
instance GHC.Classes.Eq e => GHC.Classes.Eq (Web.Envelope.Err e)
instance Data.Data.Data e => Data.Data.Data (Web.Envelope.Err e)
instance GHC.Show.Show a => GHC.Show.Show (Web.Envelope.Success a)
instance GHC.Generics.Generic (Web.Envelope.Success a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Web.Envelope.Success a)
instance Data.Data.Data a => Data.Data.Data (Web.Envelope.Success a)
instance (GHC.Show.Show a, GHC.Show.Show e) => GHC.Show.Show (Web.Envelope.Envelope' e a)
instance GHC.Generics.Generic (Web.Envelope.Envelope' e a)
instance (GHC.Classes.Eq a, GHC.Classes.Eq e) => GHC.Classes.Eq (Web.Envelope.Envelope' e a)
instance (Data.Data.Data a, Data.Data.Data e) => Data.Data.Data (Web.Envelope.Envelope' e a)
instance (Data.Aeson.Types.ToJSON.ToJSON e, Data.Aeson.Types.ToJSON.ToJSON a) => Data.Aeson.Types.ToJSON.ToJSON (Web.Envelope.Envelope' e a)
instance (Data.Aeson.Types.FromJSON.FromJSON e, Data.Aeson.Types.FromJSON.FromJSON a) => Data.Aeson.Types.FromJSON.FromJSON (Web.Envelope.Envelope' e a)
instance (Web.Internal.FormUrlEncoded.ToForm a, Web.Internal.FormUrlEncoded.ToForm e) => Web.Internal.FormUrlEncoded.ToForm (Web.Envelope.Envelope' e a)
instance (Web.Internal.FormUrlEncoded.FromForm a, Web.Internal.HttpApiData.FromHttpApiData e) => Web.Internal.FormUrlEncoded.FromForm (Web.Envelope.Envelope' (Web.Envelope.Err e) a)
instance Data.Aeson.Types.ToJSON.ToJSON a => Data.Aeson.Types.ToJSON.ToJSON (Web.Envelope.Success a)
instance Data.Aeson.Types.FromJSON.FromJSON e => Data.Aeson.Types.FromJSON.FromJSON (Web.Envelope.Success e)
instance Web.Internal.FormUrlEncoded.ToForm a => Web.Internal.FormUrlEncoded.ToForm (Web.Envelope.Success a)
instance Web.Internal.FormUrlEncoded.FromForm a => Web.Internal.FormUrlEncoded.FromForm (Web.Envelope.Success a)
instance Data.Aeson.Types.ToJSON.ToJSON e => Data.Aeson.Types.ToJSON.ToJSON (Web.Envelope.Err e)
instance Data.Aeson.Types.FromJSON.FromJSON e => Data.Aeson.Types.FromJSON.FromJSON (Web.Envelope.Err e)
instance Web.Internal.HttpApiData.ToHttpApiData e => Web.Internal.FormUrlEncoded.ToForm (Web.Envelope.Err e)
instance Web.Internal.HttpApiData.FromHttpApiData e => Web.Internal.FormUrlEncoded.FromForm (Web.Envelope.Err e)