summaryrefslogtreecommitdiff
path: root/Data/GraphQL
diff options
context:
space:
mode:
Diffstat (limited to 'Data/GraphQL')
-rw-r--r--Data/GraphQL/AST.hs64
-rw-r--r--Data/GraphQL/Encoder.hs3
-rw-r--r--Data/GraphQL/Error.hs21
-rw-r--r--Data/GraphQL/Execute.hs33
-rw-r--r--Data/GraphQL/Parser.hs3
-rw-r--r--Data/GraphQL/Schema.hs68
6 files changed, 89 insertions, 103 deletions
diff --git a/Data/GraphQL/AST.hs b/Data/GraphQL/AST.hs
index 5fdd146..99eaa79 100644
--- a/Data/GraphQL/AST.hs
+++ b/Data/GraphQL/AST.hs
@@ -1,7 +1,5 @@
-{- | This module defines an
- abstract syntax tree for the GraphQL language, based on
- <https://facebook.github.io/graphql/ Facebook's GraphQL Specification>.
--}
+-- | This module defines an abstract syntax tree for the @GraphQL@ language based on
+-- <https://facebook.github.io/graphql/ Facebook's GraphQL Specification>.
module Data.GraphQL.AST where
@@ -44,33 +42,26 @@ data Selection = SelectionField Field
| SelectionInlineFragment InlineFragment
deriving (Eq,Show)
-{- | <https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields Field Specification>
-
- A selection set is primarily composed of fields.
- A field describes one discrete piece of information
- available to request within a selection set.
-
- Some fields describe complex data or relationships to other data.
- In order to further explore this data, a field may itself contain
- a selection set, allowing for deeply nested requests.
- All GraphQL operations must specify their selections down to
- fields which return scalar values to ensure an unambiguously
- shaped response.
-
--}
+-- | A 'SelectionSet' is primarily composed of 'Field's. A 'Field' describes one
+-- discrete piece of information available to request within a 'SelectionSet'.
+--
+-- Some 'Field's describe complex data or relationships to other data. In
+-- order to further explore this data, a 'Field' may itself contain a
+-- 'SelectionSet', allowing for deeply nested requests. All @GraphQL@ operations
+-- must specify their 'Selection's down to 'Field's which return scalar values to
+-- ensure an unambiguously shaped response.
+--
+-- <https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields Field Specification>
data Field = Field Alias Name [Argument] [Directive] SelectionSet
deriving (Eq,Show)
type Alias = Name
-{- | <https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments Argument Specification>
-
- Fields are conceptually functions which return values,
- and occasionally accept arguments which alter their behavior.
- These arguments often map directly to function arguments within a
- GraphQL server’s implementation.
-
--}
+-- | 'Field's are conceptually functions which return values, and occasionally accept
+-- 'Argument's which alter their behavior. These 'Argument's often map directly to
+-- function arguments within a @GraphQL@ server’s implementation.
+--
+-- <https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments Argument Specification>
data Argument = Argument Name Value deriving (Eq,Show)
-- * Fragments
@@ -90,18 +81,15 @@ type TypeCondition = NamedType
-- * Values
-{- | <https://facebook.github.io/graphql/#sec-Input-Values Input Value Specification>
-
- Field and directive arguments accept input values
- of various literal primitives; input values can be scalars,
- enumeration values, lists, or input objects.
-
- If not defined as constant (for example, in DefaultValue),
- input values can be specified as a variable.
- List and inputs objects may also contain
- variables (unless defined to be constant).
-
--}
+-- | 'Field' and 'Directive' 'Arguments' accept input values of various literal
+-- primitives; input values can be scalars, enumeration values, lists, or input
+-- objects.
+--
+-- If not defined as constant (for example, in 'DefaultValue'), input values
+-- can be specified as a 'Variable'. List and inputs objects may also contain
+-- 'Variable's (unless defined to be constant).
+--
+-- <https://facebook.github.io/graphql/#sec-Input-Values Input Value Specification>
data Value = ValueVariable Variable
| ValueInt Int32
-- GraphQL Float is double precison
diff --git a/Data/GraphQL/Encoder.hs b/Data/GraphQL/Encoder.hs
index 6245bb0..86f090b 100644
--- a/Data/GraphQL/Encoder.hs
+++ b/Data/GraphQL/Encoder.hs
@@ -1,7 +1,6 @@
{-# LANGUAGE CPP #-}
{-# LANGUAGE OverloadedStrings #-}
--- | This module defines a printer
--- for the GraphQL language.
+-- | This module defines a printer for the @GraphQL@ language.
module Data.GraphQL.Encoder where
#if !MIN_VERSION_base(4,8,0)
diff --git a/Data/GraphQL/Error.hs b/Data/GraphQL/Error.hs
index 25632b4..74f08e4 100644
--- a/Data/GraphQL/Error.hs
+++ b/Data/GraphQL/Error.hs
@@ -26,17 +26,17 @@ parseError :: Applicative f => String -> f Aeson.Value
parseError s =
pure $ Aeson.object [("errors", Aeson.toJSON [makeErrorMsg $ pack s])]
--- | A wrapper for an applicative functor, for passing around error messages.
+-- | A wrapper for an 'Applicative' to pass error messages around.
type CollectErrsT f a = f (a,[Aeson.Value])
--- | Takes a (wrapped) list (foldable functor) of values and errors and
+-- | Takes a (wrapped) list (foldable functor) of values and errors,
-- joins the values into a list and concatenates the errors.
joinErrs
:: (Functor m, Functor f, Foldable f)
=> m (f (a,[Aeson.Value])) -> CollectErrsT m (f a)
joinErrs = fmap $ fmap fst &&& concatMap snd
--- | Wraps the given applicative to handle errors
+-- | Wraps the given 'Applicative' to handle errors
errWrap :: Functor f => f a -> f (a, [Aeson.Value])
errWrap = fmap (flip (,) [])
@@ -51,12 +51,13 @@ makeErrorMsg s = Aeson.object [("message",Aeson.toJSON s)]
addErrMsg :: Functor f => Text -> CollectErrsT f a -> CollectErrsT f a
addErrMsg = addErr . makeErrorMsg
--- | Runs the given query computation, but collects the errors into an error
--- list, which is then sent back with the data.
+-- | Runs the given query, but collects the errors into an error
+-- list which is then sent back with the data.
runCollectErrs :: Functor f => CollectErrsT f Aeson.Value -> f Aeson.Value
runCollectErrs = fmap finalD
- where finalD (dat,errs) =
- Aeson.object $
- if null errs
- then [("data",dat)]
- else [("data",dat),("errors",Aeson.toJSON $ reverse errs)]
+ where
+ finalD (dat,errs) =
+ Aeson.object
+ $ if null errs
+ then [("data",dat)]
+ else [("data",dat),("errors",Aeson.toJSON $ reverse errs)]
diff --git a/Data/GraphQL/Execute.hs b/Data/GraphQL/Execute.hs
index a0436f6..86887ff 100644
--- a/Data/GraphQL/Execute.hs
+++ b/Data/GraphQL/Execute.hs
@@ -1,6 +1,6 @@
{-# LANGUAGE CPP #-}
--- | This module provides the function execute which executes a GraphQL
--- request according to a given GraphQL schema.
+-- | This module provides the function to execute a @GraphQL@ request --
+-- according to a 'Schema'.
module Data.GraphQL.Execute (execute) where
#if !MIN_VERSION_base(4,8,0)
@@ -17,18 +17,18 @@ import qualified Data.GraphQL.Schema as Schema
import Data.GraphQL.Error
-{- | Takes a schema, a substitution and a GraphQL document.
- The substition is applied to the document using rootFields, and
- the schema's resolvers are applied to the resulting fields.
- Returns the result of the query against the schema wrapped in a
- "data" field, or errors wrapped in a "errors field".
--}
+-- | Takes a 'Schema', a variable substitution function ('Schema.Subs'), and a
+-- @GraphQL@ 'document'. The substitution is applied to the document using
+-- 'rootFields', and the 'Schema''s resolvers are applied to the resulting fields.
+--
+-- Returns the result of the query against the 'Schema' wrapped in a /data/ field, or
+-- errors wrapped in an /errors/ field.
execute :: Alternative f
=> Schema.Schema f -> Schema.Subs -> Document -> f Aeson.Value
execute (Schema resolvs) subs doc = runCollectErrs res
where res = Schema.resolvers resolvs $ rootFields subs doc
--- | rootFields takes in a substitution and a GraphQL document.
+-- | Takes a variable substitution function and a @GraphQL@ document.
-- If the document contains one query (and no other definitions)
-- it applies the substitution to the query's set of selections
-- and then returns their fields.
@@ -37,11 +37,10 @@ rootFields subs (Document [DefinitionOperation (Query (Node _varDefs _ _ sels))]
Schema.fields $ substitute subs <$> sels
rootFields _ _ = []
--- | substitute takes in a substitution and a selection.
--- If the selection is a field it applies the substitution to the
--- field's arguments using subsArg,
--- and recursively applies the substitution to the arguments of fields
--- nested in the primary field.
+-- | Takes a variable substitution function and a selection. If the
+-- selection is a field it applies the substitution to the field's
+-- arguments using 'subsArg', and recursively applies the substitution to
+-- the arguments of fields nested in the primary field.
substitute :: Schema.Subs -> Selection -> Selection
substitute subs (SelectionField (Field alias name args directives sels)) =
SelectionField $ Field
@@ -54,9 +53,9 @@ substitute subs (SelectionField (Field alias name args directives sels)) =
substitute _ sel = sel
-- TODO: Support different value types
--- | subsArg takes in a substitution and an argument.
--- If the argument's value is a variable the substitution
--- is applied to the variable's name.
+-- | Takes a variable substitution function and an argument. If the
+-- argument's value is a variable the substitution is applied to the
+-- variable's name.
subsArg :: Schema.Subs -> Argument -> Maybe Argument
subsArg subs (Argument n (ValueVariable (Variable v))) =
Argument n . ValueString <$> subs v
diff --git a/Data/GraphQL/Parser.hs b/Data/GraphQL/Parser.hs
index ed9df80..227c9a8 100644
--- a/Data/GraphQL/Parser.hs
+++ b/Data/GraphQL/Parser.hs
@@ -1,7 +1,6 @@
{-# LANGUAGE CPP #-}
{-# LANGUAGE OverloadedStrings #-}
--- | This module defines a parser
--- for GraphQl request documents.
+-- | This module defines a parser for @GraphQL@ request documents.
module Data.GraphQL.Parser where
import Prelude hiding (takeWhile)
diff --git a/Data/GraphQL/Schema.hs b/Data/GraphQL/Schema.hs
index 0a30eb9..7966392 100644
--- a/Data/GraphQL/Schema.hs
+++ b/Data/GraphQL/Schema.hs
@@ -1,9 +1,8 @@
{-# LANGUAGE CPP #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE LambdaCase #-}
--- | This module provides the type Schema,
--- representing a GraphQL schema, and functions for defining
--- a schema.
+-- | This module provides a representation of a @GraphQL@ Schema in addition to
+-- functions for defining and manipulating Schemas.
module Data.GraphQL.Schema
( Schema(..)
, Resolver
@@ -25,14 +24,16 @@ module Data.GraphQL.Schema
) where
#if !MIN_VERSION_base(4,8,0)
-import Control.Applicative (pure, (<|>))
+import Control.Applicative (pure)
+import Control.Arrow (first)
import Data.Foldable (foldMap)
import Data.Traversable (traverse)
import Data.Monoid (Monoid(mempty,mappend))
#else
+import Data.Bifunctor (first)
import Data.Monoid (Alt(Alt,getAlt))
#endif
-import Control.Applicative (Alternative(..))
+import Control.Applicative (Alternative((<|>), empty))
import Data.Maybe (catMaybes)
import Data.Foldable (fold)
@@ -42,30 +43,27 @@ import qualified Data.HashMap.Strict as HashMap
import Data.Text (Text)
import qualified Data.Text as T (null, unwords)
-import Control.Arrow
-
import Data.GraphQL.AST
import Data.GraphQL.Error
--- | Schema represents a GraphQL schema.
--- f usually has to be an instance of Alternative.
+-- | A GraphQL schema.
+-- @f@ is usually expected to be an instance of 'Alternative'.
data Schema f = Schema [Resolver f]
--- | Resolver resolves a field in to a wrapped Aeson.Object with error information
--- (or empty). The wrapped f usually has to be an instance of Alternative.
+-- | Resolves a 'Field' into an @Aeson.@'Aeson.Object' with error information
+-- (or 'empty'). @f@ is usually expected to be an instance of 'Alternative'.
type Resolver f = Field -> CollectErrsT f Aeson.Object
--- | Subs represents a substitution.
+-- | Variable substitution function.
type Subs = Text -> Maybe Text
--- | Objects represent a list of named fields, each of which
--- yield a value of a specific type.
+-- | Create a named 'Resolver' from a list of 'Resolver's.
object :: Alternative f => Text -> [Resolver f] -> Resolver f
object name resolvs = objectA name $ \case
[] -> resolvs
_ -> empty
--- | Fields can accept arguments to further specify the return value.
+-- | Like 'object' but also taking 'Argument's.
objectA
:: Alternative f
=> Text -> ([Argument] -> [Resolver f]) -> Resolver f
@@ -78,39 +76,39 @@ scalar name s = scalarA name $ \case
[] -> pure s
_ -> empty
--- | Arguments can be used to further specify a scalar's return value.
+-- | Like 'scalar' but also taking 'Argument's.
scalarA
:: (Alternative f, Aeson.ToJSON a)
=> Text -> ([Argument] -> f a) -> Resolver f
scalarA name f fld@(Field _ _ args _ []) = withField name (errWrap $ f args) fld
scalarA _ _ _ = empty
--- | Arrays are like objects but have an array of resolvers instead of a list.
+-- | Like 'object' but taking lists of 'Resolver's instead of a single list.
array :: Alternative f => Text -> [[Resolver f]] -> Resolver f
array name resolvs = arrayA name $ \case
[] -> resolvs
_ -> empty
--- | Arguments can be used to further specify an array's return values.
+-- | Like 'array' but also taking 'Argument's.
arrayA
:: Alternative f
=> Text -> ([Argument] -> [[Resolver f]]) -> Resolver f
arrayA name f fld@(Field _ _ args _ sels) =
withField name (joinErrs $ traverse (flip resolvers $ fields sels) $ f args) fld
--- | An enum represents one of a finite set of possible values.
--- Used in place of a scalar when the possible responses are easily enumerable.
+-- | Represents one of a finite set of possible values.
+-- Used in place of a 'scalar' when the possible responses are easily enumerable.
enum :: Alternative f => Text -> f [Text] -> Resolver f
enum name enums = enumA name $ \case
[] -> enums
_ -> empty
--- | Arguments can be used to further specify an enum's return values.
+-- | Like 'enum' but also taking 'Argument's.
enumA :: Alternative f => Text -> ([Argument] -> f [Text]) -> Resolver f
enumA name f fld@(Field _ _ args _ []) = withField name (errWrap $ f args) fld
enumA _ _ _ = empty
--- | Used to implement a resolver with arguments.
+-- | Helper function to facilitate 'Argument' handling.
withField
:: (Alternative f, Aeson.ToJSON a)
=> Text -> CollectErrsT f a -> Field -> CollectErrsT f (HashMap Text Aeson.Value)
@@ -121,25 +119,27 @@ withField name f (Field alias name' _ _ _) =
where
aliasOrName = if T.null alias then name' else alias
--- | resolvers takes a list of resolvers and a list of fields,
--- and applies each resolver to each field. Resolves into a value
--- containing the resolved field, or a null value and error information.
+-- | Takes a list of 'Resolver's and a list of 'Field's and applies each
+-- 'Resolver' to each 'Field'. Resolves into a value containing the
+-- resolved 'Field', or a null value and error information.
resolvers :: Alternative f => [Resolver f] -> [Field] -> CollectErrsT f Aeson.Value
resolvers resolvs =
fmap (first Aeson.toJSON . fold)
- . traverse (\fld -> (getAlt $ foldMap (Alt . ($ fld)) resolvs) <|> errmsg fld)
- where errmsg (Field alias name _ _ _) = addErrMsg msg $ (errWrap . pure) val
- where val = HashMap.singleton aliasOrName Aeson.Null
- msg = T.unwords ["field", name, "not resolved."]
- aliasOrName = if T.null alias then name else alias
-
--- | Checks whether the given selection contains a field and
--- returns the field if so, else returns Nothing.
+ . traverse (\fld -> getAlt (foldMap (Alt . ($ fld)) resolvs) <|> errmsg fld)
+ where
+ errmsg (Field alias name _ _ _) = addErrMsg msg $ (errWrap . pure) val
+ where
+ val = HashMap.singleton aliasOrName Aeson.Null
+ msg = T.unwords ["field", name, "not resolved."]
+ aliasOrName = if T.null alias then name else alias
+
+-- | Checks whether the given 'Selection' contains a 'Field' and
+-- returns the 'Field' if so, else returns 'Nothing'.
field :: Selection -> Maybe Field
field (SelectionField x) = Just x
field _ = Nothing
--- | Returns a list of the fields contained in the given selection set.
+-- | Returns a list of the 'Field's contained in the given 'SelectionSet'.
fields :: SelectionSet -> [Field]
fields = catMaybes . fmap field
generated by cgit v1.2.3 (git 2.26.2) at 2026-06-28 18:48:10 +0000