Deprecate Language.GraphQL.Execute.Schema

It is not a schema (at least not a complete one), but a resolver list,
and the resolvers should be provided by the user separately, because the
schema can originate from a GraphQL document. Schema name should be free
to provide a data type for the real schema later.

3 files changed, 50 insertions, 46 deletions

diff --git a/src/Language/GraphQL.hs b/src/Language/GraphQL.hs
index 7ac08d7..c33eb95 100644
--- a/src/Language/GraphQL.hs
+++ b/src/Language/GraphQL.hs
@@ -5,32 +5,31 @@ module Language.GraphQL
     ) where
 
 import Control.Monad.IO.Class (MonadIO)
-import qualified Data.Text as T
-
 import qualified Data.Aeson as Aeson
-import Text.Megaparsec (parse)
-
+import Data.List.NonEmpty (NonEmpty)
+import qualified Data.Text as T
+import Language.GraphQL.Error
 import Language.GraphQL.Execute
 import Language.GraphQL.Parser
-import Language.GraphQL.Schema
-
-import Language.GraphQL.Error
+import qualified Language.GraphQL.Schema as Schema
+import Text.Megaparsec (parse)
 
--- | Takes a 'Schema' and text representing a @GraphQL@ request document.
---   If the text parses correctly as a @GraphQL@ query the query is
---   executed according to the given 'Schema'.
---
---   Returns the response as an @Aeson.@'Aeson.Value'.
-graphql :: MonadIO m => Schema m -> T.Text -> m Aeson.Value
+-- | If the text parses correctly as a @GraphQL@ query the query is
+-- executed using the given 'Schema.Resolver's.
+graphql :: MonadIO m
+    => NonEmpty (Schema.Resolver m) -- ^ Resolvers.
+    -> T.Text -- ^ Text representing a @GraphQL@ request document.
+    -> m Aeson.Value -- ^ Response.
 graphql = flip graphqlSubs $ const Nothing
 
--- | Takes a 'Schema', a variable substitution function and text
---   representing a @GraphQL@ request document.  If the text parses
---   correctly as a @GraphQL@ query the substitution is applied to the
---   query and the query is then executed according to the given 'Schema'.
---
---   Returns the response as an @Aeson.@'Aeson.Value'.
-graphqlSubs :: MonadIO m => Schema m -> Subs -> T.Text -> m Aeson.Value
-graphqlSubs schema f =
-    either parseError (execute schema f)
+-- | If the text parses correctly as a @GraphQL@ query the substitution is
+-- applied to the query and the query is then executed using to the given
+-- 'Schema.Resolver's.
+graphqlSubs :: MonadIO m
+    => NonEmpty (Schema.Resolver m) -- ^ Resolvers.
+    -> Schema.Subs -- ^ Variable substitution function.
+    -> T.Text -- ^ Text representing a @GraphQL@ request document.
+    -> m Aeson.Value -- ^ Response.
+graphqlSubs schema f
+    = either parseError (execute schema f)
     . parse document ""
diff --git a/src/Language/GraphQL/Execute.hs b/src/Language/GraphQL/Execute.hs
index 5a815b8..9228dd5 100644
--- a/src/Language/GraphQL/Execute.hs
+++ b/src/Language/GraphQL/Execute.hs
@@ -1,7 +1,6 @@
 {-# LANGUAGE OverloadedStrings #-}
 
--- | This module provides the function to execute a @GraphQL@ request --
---   according to a 'Schema'.
+-- | This module provides functions to execute a @GraphQL@ request.
 module Language.GraphQL.Execute
     ( execute
     , executeWithName
@@ -9,51 +8,53 @@ module Language.GraphQL.Execute
 
 import Control.Monad.IO.Class (MonadIO)
 import qualified Data.Aeson as Aeson
+import Data.List.NonEmpty (NonEmpty(..))
 import qualified Data.List.NonEmpty as NE
-import Data.List.NonEmpty (NonEmpty((:|)))
 import Data.Text (Text)
 import qualified Data.Text as Text
 import qualified Language.GraphQL.AST as AST
 import qualified Language.GraphQL.AST.Core as AST.Core
 import qualified Language.GraphQL.AST.Transform as Transform
 import Language.GraphQL.Error
-import Language.GraphQL.Schema (Schema)
 import qualified Language.GraphQL.Schema as Schema
 
--- | 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.
+-- | The substitution is applied to the document, and the 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.
+-- Returns the result of the query against the schema wrapped in a /data/
+-- field, or errors wrapped in an /errors/ field.
 execute :: MonadIO m
-    => Schema m
-    -> Schema.Subs
-    -> AST.Document
+    => NonEmpty (Schema.Resolver m) -- ^ Resolvers.
+    -> Schema.Subs -- ^ Variable substitution function.
+    -> AST.Document -- @GraphQL@ document.
     -> m Aeson.Value
 execute schema subs doc =
     maybe transformError (document schema Nothing) $ Transform.document subs doc
   where
     transformError = return $ singleError "Schema transformation error."
 
--- | Takes a 'Schema', operation name, 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.
+-- | The substitution is applied to the document, and the resolvers are applied
+-- to the resulting fields. The operation name can be used if the document
+-- defines multiple root operations.
 --
---   Returns the result of the query against the 'Schema' wrapped in a /data/ field, or
---   errors wrapped in an /errors/ field.
+-- Returns the result of the query against the schema wrapped in a /data/
+-- field, or errors wrapped in an /errors/ field.
 executeWithName :: MonadIO m
-    => Schema m
-    -> Text
-    -> Schema.Subs
-    -> AST.Document
+    => NonEmpty (Schema.Resolver m) -- ^ Resolvers
+    -> Text -- ^ Operation name.
+    -> Schema.Subs -- ^ Variable substitution function.
+    -> AST.Document -- ^ @GraphQL@ Document.
     -> m Aeson.Value
 executeWithName schema name subs doc =
     maybe transformError (document schema $ Just name) $ Transform.document subs doc
   where
     transformError = return $ singleError "Schema transformation error."
 
-document :: MonadIO m => Schema m -> Maybe Text -> AST.Core.Document -> m Aeson.Value
+document :: MonadIO m
+    => NonEmpty (Schema.Resolver m)
+    -> Maybe Text
+    -> AST.Core.Document
+    -> m Aeson.Value
 document schema Nothing (op :| []) = operation schema op
 document schema (Just name) operations = case NE.dropWhile matchingName operations of
     [] -> return $ singleError
@@ -65,7 +66,10 @@ document schema (Just name) operations = case NE.dropWhile matchingName operatio
     matchingName _ = False
 document _ _ _ = return $ singleError "Missing operation name."
 
-operation :: MonadIO m => Schema m -> AST.Core.Operation -> m Aeson.Value
+operation :: MonadIO m
+    => NonEmpty (Schema.Resolver m)
+    -> AST.Core.Operation
+    -> m Aeson.Value
 operation schema (AST.Core.Query _ flds)
     = runCollectErrs (Schema.resolve (NE.toList schema) (NE.toList flds))
 operation schema (AST.Core.Mutation _ flds)
diff --git a/src/Language/GraphQL/Schema.hs b/src/Language/GraphQL/Schema.hs
index 08b52ce..3170a32 100644
--- a/src/Language/GraphQL/Schema.hs
+++ b/src/Language/GraphQL/Schema.hs
@@ -1,7 +1,7 @@
 {-# LANGUAGE OverloadedStrings #-}
 
 -- | This module provides a representation of a @GraphQL@ Schema in addition to
---   functions for defining and manipulating Schemas.
+-- functions for defining and manipulating schemas.
 module Language.GraphQL.Schema
     ( Resolver
     , Schema
@@ -43,6 +43,7 @@ import Language.GraphQL.Trans
 import Language.GraphQL.Type
 import Language.GraphQL.AST.Core
 
+{-# DEPRECATED Schema "Use NonEmpty (Resolver m) instead" #-}
 -- | A GraphQL schema.
 --   @m@ is usually expected to be an instance of 'MonadIO'.
 type Schema m = NonEmpty (Resolver m)