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.

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)

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)