- mercurius
- API
- Plugin options
- HTTP endpoints
- Decorators
- app.graphql(source, context, variables, operationName)
- app.graphql.extendSchema(schema), app.graphql.defineResolvers(resolvers) and app.graphql.defineLoaders(loaders)
- app.graphql.replaceSchema(schema)
- app.graphql.transformSchema(transforms)
- app.graphql.schema
- reply.graphql(source, context, variables, operationName)
- Errors
- ErrorWithProps
- Error formatter
- API
mercurius supports the following options:
-
schema
: String, String[] or schema definition. The graphql schema. The string will be parsed. -
resolvers
: Object. The graphql resolvers. -
loaders
: Object. See defineLoaders for more details. -
schemaTransforms
: Array of schema-transformation functions. Accept a schema as an argument and return a schema. -
graphql
: Object. Override options for graphql function that Mercurius utilizes.parseOptions
: Object. GraphQL's parse function optionsvalidateOptions
: Object. GraphQL's validate function options
-
graphiql
: boolean | string | Object. Serve GraphiQL on/graphiql
iftrue
or'graphiql'
. Leave empty orfalse
to disable. only applies ifonlyPersisted
option is nottrue
An object can be passed in the config to allow the injection of external graphiql plugins exported in
umd
format.- enabled: boolean, default
true
. Enable disable the graphiql extension - plugins: Array
name
: string. The name of the plugin, it should be the same exported in theumd
props
: Object | undefined. The props to be passed to the pluginumdUrl
: string. The urls of the plugin, it's downloaded at runtime. (eg. https://unpkg.com/myplugin/....)fetcherWrapper
: string. A function name exported by the plugin to read/enrich the fetch response
Check the
example folder
for detailed usage or this document for a detailed explanation on how to build a plugin.Note: If
routes
is false, this option does not have effects. - enabled: boolean, default
-
jit
: Integer. The minimum number of execution a query needs to be executed before being jit'ed.- Default:
0
, jit is disabled.
- Default:
-
routes
: boolean. Serves the Default:true
. A graphql endpoint is exposed at/graphql
. -
path
: string. Change default graphql/graphql
route to another one. -
context
:Function
. Result of function is passed to resolvers as a custom GraphQL context. The function receives therequest
andreply
as parameters. It is only called whenroutes
options istrue
-
prefix
: String. Change the route prefix of the graphql endpoint if enabled. -
defineMutation
: Boolean. Add the empty Mutation definition if schema is not defined (Default:false
). -
errorHandler
:Function
orboolean
. Change the default error handler (Default:true
). Note: If a custom error handler is defined, it should return the standardized response format according to GraphQL spec. -
errorFormatter
:Function
. Change the default error formatter. Allows the status code of the response to be set, and a GraphQL response for the error to be defined. This can be used to format errors for batched queries, which return a successful response overall but individual errors, or to obfuscate or format internal errors. The first argument is theExecutionResult
object, while the second one is the context object. -
queryDepth
:Integer
. The maximum depth allowed for a single query. Note: GraphiQL IDE sends an introspection query when it starts up. This query has a depth of 7 so when thequeryDepth
value is smaller than 7 this query will fail with aBad Request
error -
validationRules
:Function
orFunction[]
. Optional additional validation rules that the queries must satisfy in addition to those defined by the GraphQL specification. When usingFunction
, arguments include additional data from graphql request and the return value must be validation rulesFunction[]
. -
subscription
: Boolean | Object. Enable subscriptions. It uses mqemitter when it is true and exposes the pubsub interface toapp.graphql.pubsub
. To use a custom emitter set the value to an object containing the emitter.subscription.emitter
: Custom emitter.subscription.pubsub
: Custom pubsub, see Subscriptions with custom PubSub for more details. Note that when passing bothemitter
andpubsub
options,emitter
will be ignored.subscription.verifyClient
:Function
A function which can be used to validate incoming connections.subscription.context
:Function
Result of function is passed to subscription resolvers as a custom GraphQL context. The function receives theconnection
andrequest
as parameters.subscription.onConnect
:Function
A function which can be used to validate theconnection_init
payload. If defined it should return a truthy value to authorize the connection. If it returns an object the subscription context will be extended with the returned object.subscription.onDisconnect
:Function
A function which is called with the subscription context of the connection after the connection gets disconnected.subscription.keepAlive
:Integer
Optional interval in ms to send theGQL_CONNECTION_KEEP_ALIVE
message.subscription.fullWsTransport
:Boolean
Enable sending every operation via WS.
-
persistedQueries
: A hash/query map to resolve the full query text using it's unique hash. OverridespersistedQueryProvider
. -
onlyPersisted
: Boolean. Flag to control whether to allow graphql queries other than persisted. Whentrue
, it'll make the server reject any queries that are not present in thepersistedQueries
option above. It will also disable any ide available (graphiql). RequirespersistedQueries
to be set, and overridespersistedQueryProvider
. -
persistedQueryProvider
isPersistedQuery: (request: object) => boolean
: Return true if a given request matches the desired persisted query format.getHash: (request: object) => string
: Return the hash from a given request, or falsy if this request format is not supported.getQueryFromHash: async (hash: string) => string
: Return the query for a given hash.getHashForQuery?: (query: string) => string
: Return the hash for a given query string. Do not provide if you want to skip saving new queries.saveQuery?: async (hash: string, query: string) => void
: Save a query, given its hash.notFoundError?: string
: An error message to return whengetQueryFromHash
returns no result. Defaults toBad Request
.notSupportedError?: string
: An error message to return when a query matchesisPersistedQuery
, but returns no valid hash fromgetHash
. Defaults toBad Request
.
-
allowBatchedQueries
: Boolean. Flag to control whether to allow batched queries. Whentrue
, the server supports recieving an array of queries and returns an array of results. -
compilerOptions
: Object. Configurable options for the graphql-jit compiler. For more details check https://github.com/zalando-incubator/graphql-jit -
additionalRouteOptions
: Object. Takes similar configuration to the Route Options of Fastify. Use cases include being able to add constraints, modify validation schema, increase thebodyLimit
, etc. You can read more about the possible values on fastify.dev's Routes Options
query {
dogs {
name
owner {
name
pet {
name
owner {
name
pet {
name
}
}
}
}
}
}
A queryDepth
of 6
would allow this query. 5
or less would throw with the error - unnamedQuery query exceeds the query depth limit of 5
Executed the GraphQL query passed via query string parameters. The supported query string parameters are:
query
, the GraphQL query.operationName
, the operation name to execute contained in the query.variables
, a JSON object containing the variables for the query.
Executes the GraphQL query or mutation described in the body. The payload must conform to the following JSON schema:
{
type: 'object',
properties: {
query: {
type: 'string',
description: 'the GraphQL query'
},
operationName: {
type: 'string'
},
variables: {
type: ['object', 'null'],
additionalProperties: true
}
}
}
For code from example use:
curl -H "Content-Type:application/json" -XPOST -d '{"query": "query { add(x: 2, y: 2) }"}' http://localhost:3000/graphql
Executes the GraphQL query or mutation described in the body. operationName
and variables
can not be passed using this method. The
payload contains the GraphQL query.
For code from example use:
curl -H "Content-Type:application/graphql" -XPOST -d "query { add(x: 2, y: 2) }" http://localhost:3000/graphql
Serves GraphiQL if enabled by the options.
mercurius adds the following decorators.
Decorate Server with a
graphql
method.
It calls the upstream graphql()
method with the
defined schema, and it adds { app }
to the context.
const Fastify = require('fastify')
const mercurius = require('mercurius')
const app = Fastify()
const schema = `
type Query {
add(x: Int, y: Int): Int
}
`
const resolvers = {
Query: {
add: async (_, { x, y }) => x + y
}
}
app.register(mercurius, {
schema,
resolvers
})
async function run() {
// needed so that graphql is defined
await app.ready()
const query = '{ add(x: 2, y: 2) }'
const res = await app.graphql(query)
console.log(res)
// prints:
//
// {
// data: {
// add: 4
// }
// }
}
run()
app.graphql.extendSchema(schema), app.graphql.defineResolvers(resolvers) and app.graphql.defineLoaders(loaders)
It is possible to add schemas, resolvers and loaders in separate fastify plugins, like so:
const Fastify = require('fastify')
const mercurius = require('mercurius')
const app = Fastify()
const schema = `
type Human {
name: String!
}
type Dog {
name: String!
owner: Human
}
extend type Query {
dogs: [Dog]
add(x: Int, y: Int): Int
}
`
const dogs = [
{ name: 'Max' },
{ name: 'Charlie' },
{ name: 'Buddy' },
{ name: 'Max' }
]
const owners = {
Max: {
name: 'Jennifer'
},
Charlie: {
name: 'Sarah'
},
Buddy: {
name: 'Tracy'
}
}
const resolvers = {
Query: {
dogs: async (_, args, context, info) => dogs,
add: async (_, { x, y }) => x + y
}
}
const loaders = {
Dog: {
async owner(queries, { reply }) {
return queries.map(({ obj }) => owners[obj.name])
}
}
}
app.register(mercurius)
app.register(async function (app) {
app.graphql.extendSchema(schema)
app.graphql.defineResolvers(resolvers)
app.graphql.defineLoaders(loaders)
})
async function run() {
// needed so that graphql is defined
await app.ready()
const query = '{ add(x: 2, y: 2) }'
const res = await app.graphql(query)
console.log(res)
// prints:
//
// {
// data: {
// add: 4
// }
// }
}
run()
It is possible to replace schema and resolvers using makeSchemaExecutable
function in separate fastify plugins, like so:
const Fastify = require('fastify')
const mercurius = require('mercurius')
const { makeExecutableSchema } = require('@graphql-tools/schema')
const app = Fastify()
app.register(mercurius, {
schema: makeExecutableSchema({
typeDefs: `
type Query {
add(x: Int, y: Int): Int
}
`,
resolvers: {
Query: {
add: async (_, { x, y }) => x + y
}
}
})
})
app.register(async function (app) {
app.graphql.replaceSchema(
makeExecutableSchema({
typeDefs: `
type Query {
add(x: Int, y: Int, z: Int): Int
}
`,
resolvers: {
Query: {
add: async (_, { x, y, z }) => x + y + z
}
}
})
)
})
async function run() {
// needed so that graphql is defined
await app.ready()
const query = '{ add(x: 2, y: 2, z: 2) }'
const res = await app.graphql(query)
console.log(res)
// prints:
//
// {
// data: {
// add: 6
// }
// }
}
run()
transforms
can be an array of functions or a single function that accept the schema and returns a schema.
It is an utility function that calls replaceSchema
underneath.
app.graphql.extendSchema(typeDefs)
app.graphql.defineResolvers(resolvers)
app.graphql.transformSchema(directive()) // or [directive()]
Provides access to the built GraphQLSchema
object that mercurius
will use to execute queries. This property will reflect any updates made by extendSchema
or replaceSchema
as well.
Decorate Reply with a
graphql
method.
It calls the upstream graphql()
function with the
defined schema, and it adds { app, reply }
to the context.
const Fastify = require('fastify')
const mercurius = require('mercurius')
const app = Fastify()
const schema = `
type Query {
add(x: Int, y: Int): Int
}
`
const resolvers = {
add: async ({ x, y }) => x + y
}
app.register(mercurius, {
schema,
resolvers
})
app.get('/', async function (req, reply) {
const query = '{ add(x: 2, y: 2) }'
return reply.graphql(query)
})
async function run() {
const res = await app.inject({
method: 'GET',
url: '/'
})
console.log(JSON.parse(res.body), {
data: {
add: 4
}
})
}
run()
Mercurius help the error handling with two useful tools.
- ErrorWithProps class
- ErrorFormatter option
ErrorWithProps can be used to create Errors to be thrown inside the resolvers or plugins.
it takes 3 parameters:
- message
- extensions
- statusCode
'use strict'
throw new ErrorWithProps('message', {
...
}, 200)
Use errors extensions
to provide additional information to query errors
GraphQL services may provide an additional entry to errors with the key extensions
in the result.
'use strict'
const Fastify = require('fastify')
const mercurius = require('mercurius')
const { ErrorWithProps } = mercurius
const users = {
1: {
id: '1',
name: 'John'
},
2: {
id: '2',
name: 'Jane'
}
}
const app = Fastify()
const schema = `
type Query {
findUser(id: String!): User
}
type User {
id: ID!
name: String
}
`
const resolvers = {
Query: {
findUser: (_, { id }) => {
const user = users[id]
if (user) return users[id]
else
throw new ErrorWithProps('Invalid User ID', {
id,
code: 'USER_ID_INVALID',
timestamp: Math.round(new Date().getTime() / 1000)
})
}
}
}
app.register(mercurius, {
schema,
resolvers
})
app.listen({ port: 3000 })
To control the status code for the response, the third optional parameter can be used.
throw new mercurius.ErrorWithProps('Invalid User ID', {moreErrorInfo})
// using the defaultErrorFormatter, the response statusCode will be 200 as defined in the graphql-over-http spec
throw new mercurius.ErrorWithProps('Invalid User ID', {moreErrorInfo}, 500)
// using the defaultErrorFormatter, the response statusCode will be 500 as specified in the parameter
const error = new mercurius.ErrorWithProps('Invalid User ID', {moreErrorInfo}, 500)
error.data = {foo: 'bar'}
throw error
// using the defaultErrorFormatter, the response status code will be always 200 because error.data is defined
Allows the status code of the response to be set, and a GraphQL response for the error to be defined. You find out how to do this here.
By default uses the defaultErrorFormatter
, but it can be overridden in the mercurius options changing the errorFormatter parameter.
Important: using the default formatter, when the error has a data property the response status code will be always 200
While using custom error formatter, you can access the status code provided by the ErrorWithProps object via
originalError
property. Please keep in mind though, that originalError
is a non-enumerable property, meaning it won't
get serialized and/or logged as a whole.
app.register(mercurius, {
schema,
resolvers,
errorFormatter: (result) => ({ statusCode: result.errors[0].originalError.statusCode, response: result })
})
Using the errorFormatter means overriding the defaultErrorFormatter
and it could cause ambiguous GraphQL error message like GraphQL validation error
without indicating where and why the error happens. To retain the default error behaviour, you can reimplement the defaultErrorFormatter
.
import mercurius from 'mercurius';
const { defaultErrorFormatter } = mercurius;
app.register(mercurius, {
schema,
resolvers,
errorFormatter: (result, context) => {
const formatter = defaultErrorFormatter(result, context);
// your custom behaviour here
return {
statusCode: formatter.statusCode || 500,
response: formatter.response,
};
},
});