Copyright	(c) Dennis Gosnell 2016
License	BSD-style (see LICENSE file)
Maintainer	cdep.illabout@gmail.com
Stability	experimental
Portability	POSIX
Safe Haskell	None
Language	Haskell2010

Web.Envelope

Description

This module contains the Envelope type and helper functions. The Envelope 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.

>>> import qualified Data.ByteString.Lazy.Char8 as C8
>>> import Data.Aeson (decode, encode)

Let's look at how a success reponse is encoded and decoded. It is encoded as an object with a single member: "data".

>>> let successEnvelope = toSuccessEnvelope 3 :: Envelope Text Int
>>> C8.putStrLn $ encode successEnvelope
{"data":3}
>>> decode "{\"data\":3}" :: Maybe (Envelope Text Int)
Just (EnvelopeSuccess (Success 3))

Now lets look at how an error response is encoded and decoded. It is encoded as an object with two members: "extra" and "error".

>>> let errorEnvelope = toErrEnvelope "DB_ERROR" "there was an error with the database" :: Envelope String Int
>>> C8.putStrLn $ encode errorEnvelope
{"extra":"there was an error with the database","error":"DB_ERROR"}
>>> 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"}))

The Success and Err types are used within the Envelope type synonym.

Synopsis

type Envelope e a = Envelope' (Err e) (Success a)
data Envelope' e a
- = EnvelopeErr e
- | EnvelopeSuccess a
newtype Success a = Success a
data Err e = Err {
- errErr :: e
- errExtra :: Maybe Text
}
toErr :: e -> Text -> Err e
toErr' :: e -> Err e
throwEnvelopeErr :: MonadError (Err e) m => e -> Text -> m a
throwEnvelopeErr' :: MonadError (Err e) m => e -> m a
toSuccessEnvelope :: a -> Envelope e a
toErrEnvelope :: e -> Text -> Envelope e a
toErrEnvelope' :: e -> Envelope e a

Documentation

type Envelope e a = Envelope' (Err e) (Success a) #

Main type to be used. Wrapper around responses from an API, mainly used with a JSON API.

Type synonym around Envelope'.

data Envelope' e a #

Wrapper around either a success or an error. Isomorphic to Either.

The only interesting part of this type is the ToJSON and FromJSON instances.

Constructors

EnvelopeErr e
EnvelopeSuccess a

Instances

(Eq e, Eq a) => Eq (Envelope' e a) #
Instance details Defined in Web.Envelope Methods (==) :: Envelope' e a -> Envelope' e a -> Bool # (/=) :: Envelope' e a -> Envelope' e a -> Bool #
(Data e, Data a) => Data (Envelope' e a) #
Instance details Defined in Web.Envelope Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Envelope' e a -> c (Envelope' e a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Envelope' e a) # toConstr :: Envelope' e a -> Constr # dataTypeOf :: Envelope' e a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Envelope' e a)) # dataCast2 :: Typeable t => (forall d e0. (Data d, Data e0) => c (t d e0)) -> Maybe (c (Envelope' e a)) # gmapT :: (forall b. Data b => b -> b) -> Envelope' e a -> Envelope' e a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Envelope' e a -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Envelope' e a -> r # gmapQ :: (forall d. Data d => d -> u) -> Envelope' e a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Envelope' e a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Envelope' e a -> m (Envelope' e a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Envelope' e a -> m (Envelope' e a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Envelope' e a -> m (Envelope' e a) #
(Show e, Show a) => Show (Envelope' e a) #
Instance details Defined in Web.Envelope Methods showsPrec :: Int -> Envelope' e a -> ShowS # show :: Envelope' e a -> String # showList :: [Envelope' e a] -> ShowS #
Generic (Envelope' e a) #
Instance details Defined in Web.Envelope Associated Types type Rep (Envelope' e a) :: Type -> Type # Methods from :: Envelope' e a -> Rep (Envelope' e a) x # to :: Rep (Envelope' e a) x -> Envelope' e a #
(ToJSON e, ToJSON a) => ToJSON (Envelope' e a) #
Instance details Defined in Web.Envelope Methods toJSON :: Envelope' e a -> Value # toEncoding :: Envelope' e a -> Encoding # toJSONList :: [Envelope' e a] -> Value # toEncodingList :: [Envelope' e a] -> Encoding #
(FromJSON e, FromJSON a) => FromJSON (Envelope' e a) #	Tries to parse a successful response. If you are using the `Envelope` type synonym, this will use the `FromJSON` instance for `Success`. If that fails, try to parse an error response. If you are using the `Envelope` type synonym, this will use the `FromJSON` instance for `Err`.
Instance details Defined in Web.Envelope Methods parseJSON :: Value -> Parser (Envelope' e a) # parseJSONList :: Value -> Parser [Envelope' e a] #
(ToForm a, ToForm e) => ToForm (Envelope' e a) #	Uses the underlying `ToForm` instance for both the `EnvelopeErr` case and the `EnvelopeSuccess` case.
Instance details Defined in Web.Envelope Methods toForm :: Envelope' e a -> Form #
(FromForm a, FromHttpApiData e) => FromForm (Envelope' (Err e) a) #	Looks for the key `"error"` in the `Form`. If it is found, assume this form is an `'Err e'`. If it is not found, assume this `Form` is an `a`. WARNING: If the `a` is encoded with a key `"error"`, this `Form` will be decoded as a `EnvelopeErr` instead of a `EnvelopeSuccess`. This is probably not what you want.
Instance details Defined in Web.Envelope Methods fromForm :: Form -> Either Text (Envelope' (Err e) a) #
type Rep (Envelope' e a) #
Instance details Defined in Web.Envelope type Rep (Envelope' e a) = D1 (MetaData "Envelope'" "Web.Envelope" "envelope-0.2.2.0-14Qu29JDe7c9Dp94B3kbTx" False) (C1 (MetaCons "EnvelopeErr" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 e)) :+: C1 (MetaCons "EnvelopeSuccess" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a)))

newtype Success a #

Newtype wrapper to be able to provide specific instances. Used with Envelope.

Constructors

Success a

Instances

Eq a => Eq (Success a) #
Instance details Defined in Web.Envelope Methods (==) :: Success a -> Success a -> Bool # (/=) :: Success a -> Success a -> Bool #
Data a => Data (Success a) #
Instance details Defined in Web.Envelope Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Success a -> c (Success a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Success a) # toConstr :: Success a -> Constr # dataTypeOf :: Success a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Success a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Success a)) # gmapT :: (forall b. Data b => b -> b) -> Success a -> Success a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Success a -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Success a -> r # gmapQ :: (forall d. Data d => d -> u) -> Success a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Success a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Success a -> m (Success a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Success a -> m (Success a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Success a -> m (Success a) #
Show a => Show (Success a) #
Instance details Defined in Web.Envelope Methods showsPrec :: Int -> Success a -> ShowS # show :: Success a -> String # showList :: [Success a] -> ShowS #
Generic (Success a) #
Instance details Defined in Web.Envelope Associated Types type Rep (Success a) :: Type -> Type # Methods from :: Success a -> Rep (Success a) x # to :: Rep (Success a) x -> Success a #
ToJSON a => ToJSON (Success a) #	For `Success a`, wrap the `a` in an object with a `"data"` field. The resulting JSON object will look like this: { "data": ... }
Instance details Defined in Web.Envelope Methods toJSON :: Success a -> Value # toEncoding :: Success a -> Encoding # toJSONList :: [Success a] -> Value # toEncodingList :: [Success a] -> Encoding #
FromJSON e => FromJSON (Success e) #	Parse the JSON object produced by the `ToJSON` instance.
Instance details Defined in Web.Envelope Methods parseJSON :: Value -> Parser (Success e) # parseJSONList :: Value -> Parser [Success e] #
ToForm a => ToForm (Success a) #	Use the `ToForm` instance of the underlying datatype.
Instance details Defined in Web.Envelope Methods toForm :: Success a -> Form #
FromForm a => FromForm (Success a) #	Use the `FromForm` instance of the underlying datatype.
Instance details Defined in Web.Envelope Methods fromForm :: Form -> Either Text (Success a) #
type Rep (Success a) #
Instance details Defined in Web.Envelope type Rep (Success a) = D1 (MetaData "Success" "Web.Envelope" "envelope-0.2.2.0-14Qu29JDe7c9Dp94B3kbTx" True) (C1 (MetaCons "Success" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a)))

data Err e #

Wrapper to add an extra field with info about the error. Used with Envelope.

Constructors

Err
Fields errErr :: e Actual error information we want to send. errExtra :: Maybe Text Additional error information in plain text.

Instances

Eq e => Eq (Err e) #
Instance details Defined in Web.Envelope Methods (==) :: Err e -> Err e -> Bool # (/=) :: Err e -> Err e -> Bool #
Data e => Data (Err e) #
Instance details Defined in Web.Envelope Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Err e -> c (Err e) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Err e) # toConstr :: Err e -> Constr # dataTypeOf :: Err e -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Err e)) # dataCast2 :: Typeable t => (forall d e0. (Data d, Data e0) => c (t d e0)) -> Maybe (c (Err e)) # gmapT :: (forall b. Data b => b -> b) -> Err e -> Err e # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Err e -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Err e -> r # gmapQ :: (forall d. Data d => d -> u) -> Err e -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Err e -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Err e -> m (Err e) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Err e -> m (Err e) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Err e -> m (Err e) #
Show e => Show (Err e) #
Instance details Defined in Web.Envelope Methods showsPrec :: Int -> Err e -> ShowS # show :: Err e -> String # showList :: [Err e] -> ShowS #
Generic (Err e) #
Instance details Defined in Web.Envelope Associated Types type Rep (Err e) :: Type -> Type # Methods from :: Err e -> Rep (Err e) x # to :: Rep (Err e) x -> Err e #
ToJSON e => ToJSON (Err e) #	For `Err e`, wrap the `e` in an object with `"extra"` and `"error"` fields. The resulting JSON object will look like this: { "extra": ..., "error": .... }
Instance details Defined in Web.Envelope Methods toJSON :: Err e -> Value # toEncoding :: Err e -> Encoding # toJSONList :: [Err e] -> Value # toEncodingList :: [Err e] -> Encoding #
FromJSON e => FromJSON (Err e) #	Parse the JSON object produced by the `ToJSON` instance.
Instance details Defined in Web.Envelope Methods parseJSON :: Value -> Parser (Err e) # parseJSONList :: Value -> Parser [Err e] #
ToHttpApiData e => ToForm (Err e) #	Just use the `ToForm` instance of the underlying datatype. The resulting Form object will look like this: [("extra", ...), ("error", ....)]
Instance details Defined in Web.Envelope Methods toForm :: Err e -> Form #
FromHttpApiData e => FromForm (Err e) #	Parse a form produced by the `ToForm` instance. Use `FromHttpApiData`s `parseQueryParam` to parse the `error` parameter.
Instance details Defined in Web.Envelope Methods fromForm :: Form -> Either Text (Err e) #
(FromForm a, FromHttpApiData e) => FromForm (Envelope' (Err e) a) #	Looks for the key `"error"` in the `Form`. If it is found, assume this form is an `'Err e'`. If it is not found, assume this `Form` is an `a`. WARNING: If the `a` is encoded with a key `"error"`, this `Form` will be decoded as a `EnvelopeErr` instead of a `EnvelopeSuccess`. This is probably not what you want.
Instance details Defined in Web.Envelope Methods fromForm :: Form -> Either Text (Envelope' (Err e) a) #
type Rep (Err e) #
Instance details Defined in Web.Envelope type Rep (Err e) = D1 (MetaData "Err" "Web.Envelope" "envelope-0.2.2.0-14Qu29JDe7c9Dp94B3kbTx" False) (C1 (MetaCons "Err" PrefixI True) (S1 (MetaSel (Just "errErr") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 e) :*: S1 (MetaSel (Just "errExtra") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Text))))

toErr :: e -> Text -> Err e #

Smart constructor for Err.

>>> toErr "DB_ERROR" "an error occurred"
Err {errErr = "DB_ERROR", errExtra = Just "an error occurred"}

toErr' :: e -> Err e #

Smart constructor for Err that doesn't use an errExtra.

>>> toErr' "DB_ERROR"
Err {errErr = "DB_ERROR", errExtra = Nothing}

throwEnvelopeErr :: MonadError (Err e) m => e -> Text -> m a #

Throw an 'Err e' using throwError in a Monad that implements MonadError.

If you have ExceptT (Err e) somewhere inside your monad transformer stacks, this function can be used to throw an error (return early) in a function.

>>> import Control.Monad.Except (runExcept)
>>> throwEnvelopeErr "BAD_ERROR" "a very bad error occurred!" :: Either (Err String) Int
Left (Err {errErr = "BAD_ERROR", errExtra = Just "a very bad error occurred!"})

Here is a longer example using a monad stack.

type MyMonadStack = ReaderT Int (ExceptT (Err String) IO)

doSomething :: Int -> MyMonadStack Int
doSomething int =
    if int < 0
        then
            throwEnvelopeErr "INT_TOO_SMALL" "the integer passed to doSomething is too small"
        else
            return (int + 1)

throwEnvelopeErr' :: MonadError (Err e) m => e -> m a #

Like throwEnvelopeErr but without providing a message.

>>> import Control.Monad.Except (runExcept)
>>> throwEnvelopeErr "BAD_ERROR" "a very bad error occurred!" :: Either (Err String) Int
Left (Err {errErr = "BAD_ERROR", errExtra = Just "a very bad error occurred!"})

toSuccessEnvelope :: a -> Envelope e a #

Wrap an a in a success Envelope.

>>> toSuccessEnvelope 3 :: Envelope String Int
EnvelopeSuccess (Success 3)

toErrEnvelope :: e -> Text -> Envelope e a #

Wrap an a and an additional message in an error Envelope.

>>> 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"})

toErrEnvelope' :: e -> Envelope e a #

Wrap an a in an error Envelope.

>>> toErrEnvelope' "DB_ERROR" :: Envelope String Int
EnvelopeErr (Err {errErr = "DB_ERROR", errExtra = Nothing})