Moduleservant-0.20.2Haskell2010

Servant.API.TypeLevel

This module collects utilities for manipulating servant API types. The functionality in this module is for advanced usage.

The code samples in this module use the following type synonym:

type SampleAPI = "hello" :> Get '[JSON] Int
            :<|> "bye" :> Capture "name" String :> Post '[JSON, PlainText] Bool

1 type
1 class

Packageservant-0.20.2
Exports17
LanguageHaskell2010
LicenceBSD-3-Clause
SourceTypeLevel.hs

The doctests in this module are run with following preamble:

Example12 expressions

>>> :set -XPolyKinds>>> :set -XGADTs>>> :set -XTypeSynonymInstances -XFlexibleInstances>>> import Data.Proxy>>> import Data.Type.Equality>>> import Servant.API>>> data OK ctx where OK :: ctx => OK ctx>>> instance Show (OK ctx) where show _ = "OK">>> let ok :: ctx => Proxy ctx -> OK ctx; ok _ = OK>>> type SampleAPI = "hello" :> Get '[JSON] Int :<|> "bye" :> Capture "name" String :> Post '[JSON, PlainText] Bool>>> type FailAPI = Fragment Bool :> Fragment Int :> Get '[JSON] NoContent>>> let sampleAPI = Proxy :: Proxy SampleAPI

familytype family Endpoints api :: [Type] where

Flatten API into a list of endpoints.

Example1 expression

>>> Refl :: Endpoints SampleAPI :~: '["hello" :> Verb 'GET 200 '[JSON] Int, "bye" :> (Capture "name" String :> Verb 'POST 200 '[JSON, PlainText] Bool)]Refl

Equations

Endpoints (a :<|> b) = AppendList (Endpoints a) (Endpoints b)
Endpoints (e :> a) = MapSub e (Endpoints a)
Endpoints a = '[a]

Lax inclusion

familytype family IsElem' a s :: Constraint

You may use this type family to tell the type checker that your custom type may be skipped as part of a link. This is useful for things like QueryParam that are optional in a URI and do not affect them if they are omitted.

Example2 expressions

>>> data CustomThing>>> type instance IsElem' e (CustomThing :> s) = IsElem e s

Note that IsElem is called, which will mutually recurse back to IsElem' if it exhausts all other options again.

Once you have written a HasLink instance for CustomThing you are ready to go.

familytype family IsElem endpoint api :: Constraint where

Closed type family, check if endpoint is within api. Uses IsElem' if it exhausts all other options.

Example1 expression

>>> ok (Proxy :: Proxy (IsElem ("hello" :> Get '[JSON] Int) SampleAPI))OK

Example1 expression

>>> ok (Proxy :: Proxy (IsElem ("bye" :> Get '[JSON] Int) SampleAPI))...... Could not ......

An endpoint is considered within an api even if it is missing combinators that don't affect the URL:

Example1 expression

>>> ok (Proxy :: Proxy (IsElem (Get '[JSON] Int) (Header "h" Bool :> Get '[JSON] Int)))OK

Example1 expression

>>> ok (Proxy :: Proxy (IsElem (Get '[JSON] Int) (ReqBody '[JSON] Bool :> Get '[JSON] Int)))OK

N.B.:* IsElem a b can be seen as capturing the notion of whether the URL represented by a would match the URL represented by b, *not* whether a request represented by a matches the endpoints serving b (for the latter, use IsIn).

Equations

IsElem e (sa :<|> sb) = Or (IsElem e sa) (IsElem e sb)
IsElem (e :> sa) (e :> sb) = IsElem sa sb
IsElem sa (Header sym x :> sb) = IsElem sa sb
IsElem sa (Header' mods sym x :> sb) = IsElem sa sb
IsElem sa (ReqBody y x :> sb) = IsElem sa sb
IsElem (CaptureAll z y :> sa) (CaptureAll x y :> sb) = IsElem sa sb
IsElem (Capture z y :> sa) (Capture x y :> sb) = IsElem sa sb
IsElem sa (QueryParam x y :> sb) = IsElem sa sb
IsElem sa (QueryParams x y :> sb) = IsElem sa sb
IsElem sa (QueryFlag x :> sb) = IsElem sa sb
IsElem sa (Fragment x :> sb) = IsElem sa sb
IsElem (Verb m s ct typ) (Verb m s ct' typ) = IsSubList ct ct'
IsElem e e = ()
IsElem e (NamedRoutes rs) = IsElem e (ToServantApi rs)
IsElem e a = IsElem' e a

familytype family IsSubAPI sub api :: Constraint where

Check whether sub is a sub-API of api.

Example1 expression

>>> ok (Proxy :: Proxy (IsSubAPI SampleAPI (SampleAPI :<|> Get '[JSON] Int)))OK

Example1 expression

>>> ok (Proxy :: Proxy (IsSubAPI (SampleAPI :<|> Get '[JSON] Int) SampleAPI))...... Could not ......

This uses IsElem for checking; thus the note there applies here.

Equations

IsSubAPI sub api = AllIsElem (Endpoints sub) api

familytype family AllIsElem (xs :: [Type]) api :: Constraint where

Check that every element of xs is an endpoint of api (using IsElem).

Equations

AllIsElem '[] api = ()
AllIsElem (x ': xs) api = (IsElem x api, AllIsElem xs api)

Strict inclusion

familytype family IsIn endpoint api :: Constraint where

Closed type family, check if endpoint is exactly within api.

Example1 expression

>>> ok (Proxy :: Proxy (IsIn ("hello" :> Get '[JSON] Int) SampleAPI))OK

Unlike IsElem, this requires an *exact* match.

Example1 expression

>>> ok (Proxy :: Proxy (IsIn (Get '[JSON] Int) (Header "h" Bool :> Get '[JSON] Int)))...... Could not ......

Equations

IsIn e (sa :<|> sb) = Or (IsIn e sa) (IsIn e sb)
IsIn (e :> sa) (e :> sb) = IsIn sa sb
IsIn e e = ()
IsIn e (NamedRoutes record) = IsIn e (ToServantApi record)

familytype family IsStrictSubAPI sub api :: Constraint where

Check whether sub is a sub API of api.

Like IsSubAPI, but uses IsIn rather than IsElem.

Equations

IsStrictSubAPI sub api = AllIsIn (Endpoints sub) api

familytype family AllIsIn (xs :: [Type]) api :: Constraint where

Check that every element of xs is an endpoint of api (using IsIn).

Example1 expression

>>> ok (Proxy :: Proxy (AllIsIn (Endpoints SampleAPI) SampleAPI))OK

Equations

AllIsIn '[] api = ()
AllIsIn (x ': xs) api = (IsIn x api, AllIsIn xs api)

Helpers

0 declarations

Lists

familytype family MapSub (e :: k) (xs :: [Type]) :: [Type] where

Apply (e :>) to every API in xs.

Equations

MapSub e '[] = '[]
MapSub e (x ': xs) = (e :> x) ': MapSub e xs

familytype family AppendList (xs :: [a]) (ys :: [a]) :: [a] where

Append two type-level lists.

Equations

AppendList '[] ys = ys
AppendList (x ': xs) ys = x ': AppendList xs ys

familytype family IsSubList (a :: [t]) (b :: [t]) :: Constraint where

Equations

IsSubList '[] b = ()
IsSubList (x ': xs) y = And (Elem x y) (IsSubList xs y)

typetype Elem (e :: t) (es :: [t]) = ElemGo e es es

Check that a value is an element of a list:

Example1 expression

>>> ok (Proxy :: Proxy (Elem Bool '[Int, Bool]))OK

Example1 expression

>>> ok (Proxy :: Proxy (Elem String '[Int, Bool]))...... [Char]...'[Int, Bool......

familytype family ElemGo (e :: t) (es :: [t]) (orig :: t1) :: Constraint where

Equations

ElemGo x (x ': xs) orig = ()
ElemGo y (x ': xs) orig = ElemGo y xs orig
ElemGo x '[] orig = TypeError (('ShowType x ':<>: 'Text " expected in list ") ':<>: 'ShowType orig)

Logic

familytype family Or (a :: Constraint) (b :: Constraint) :: Constraint where

If either a or b produce an empty constraint, produce an empty constraint.

Equations

Or () b = ()
Or a () = ()

familytype family And (a :: Constraint) (b :: Constraint) :: Constraint where

If both a or b produce an empty constraint, produce an empty constraint.

Equations

And () () = ()

Fragment

familytype family FragmentUnique api :: Constraint where

Equations

FragmentUnique (sa :<|> sb) = And (FragmentUnique sa) (FragmentUnique sb)
FragmentUnique (Fragment a :> sa) = FragmentNotIn sa (Fragment a :> sa)
FragmentUnique (x :> sa) = FragmentUnique sa
FragmentUnique (Fragment a) = ()
FragmentUnique x = ()

classclass FragmentUnique api => AtMostOneFragment api

If there is more than one fragment in an API endpoint, a compile-time error is raised.

Example2 expressions

>>> type FailAPI = Fragment Bool :> Fragment Int :> Get '[JSON] NoContent>>> instance AtMostOneFragment FailAPI......Only one Fragment allowed per endpoint in api......

Instances3AtMostOneFragment

AtMostOneFragment (Fragment a)Defined in servant-0.20.2 · Servant.API.TypeLevel
AtMostOneFragment (UVerb m cts as)Defined in servant-0.20.2 · Servant.API.TypeLevel
AtMostOneFragment (Verb m s ct typ)Defined in servant-0.20.2 · Servant.API.TypeLevel