A GraphQL server implementation written in NodeJS/Typescript. It uses the standard graphql library to receive GraphQL requests and send back appropriate responses.
npm install --save @dreamit/graphql-server
TypeScript declarations are provided within the project.
The following table shows which version of graphql-js library is compatible with which version of @dreamit/graphql-server. As @dreamit/graphql-server defines graphql-js as peerDependency you might want to choose a fitting version according to the graphql-js version used in your project and by other libraries depending on graphql-js.
GraphQLServerRequest and GraphQLServerResponse object (e.g. Express).You can create a new instance of GraphQLServer with the options necessary for your tasks. The handleRequest function of the GraphQLServer can be integrated with many fitting webservers.
const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({schema: someExampleSchema})
graphQLServerExpress.all('/graphql', (req, res) => {
return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({port: graphQLServerPort})
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)
GraphQLServer provides default values and behaviour out of the box. It is recommended to at least provide a schema so the request won't be rejected because of a missing/invalid schema. When using it with a local schema it is recommended to provide a rootValue to return a fitting value. Examples for these requests can be found in the integration test in the GraphQLServer.integration.test.ts class in the tests folder.
Validation rules can be used to define how the GraphQLServer should behave when validating the request against the given schema. To ease the use GraphQLServer uses the specifiedRules from graphql-js library. If you don't want to use the default validation rules you can overwrite them by setting defaultValidationRules option to [].
Warning! Setting both defaultValidationRules and customValidationRules options to [] will disable validation. This might result in unexpected responses that are hard to use for API users or frontends.
import {NoSchemaIntrospectionCustomRule} from 'graphql'
const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({schema: someExampleSchema, defaultValidationRules: []})
graphQLServerExpress.all('/graphql', (req, res) => {
return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({port: graphQLServerPort})
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)
If you want to define custom validation rules you can use the customValidationRules option (e.g. to handle introspection like shown in the example below).
Introspection can be used to get information about the available schema. While this may be useful in development environments and public APIs you should consider disabling it for production if e.g. your API is only used with a specific matching frontend.
Introspection can be disabled by adding the NoSchemaIntrospectionCustomRule from the graphql-js library to the customValidationRules option.
import {NoSchemaIntrospectionCustomRule} from 'graphql'
const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({schema: someExampleSchema, customValidationRules: [NoSchemaIntrospectionCustomRule]})
graphQLServerExpress.all('/graphql', (req, res) => {
return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({port: graphQLServerPort})
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)
Hot reload of the GraphQL schema can be used to update the existing schema to a new version without restarting the GraphQL server, webserver or whole application. When setting a new schema it will be used for the next incoming request while the old schema will be used for requests that are being processed at the moment. Hot reloading is especially useful for remote schemas that are processed in another application like a webservice.
The schema can be changed simply by calling setSchema in the GraphQLServer instance. In the example below a second route is used to trigger a schema update.
const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({schema: someExampleSchema})
graphQLServerExpress.all('/graphql', (req, res) => {
return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.all('/updateme', (req, res) => {
const updatedSchema = someMagicHappened()
customGraphQLServer.setSchema(updatedSchema)
return res.status(200).send()
})
graphQLServerExpress.listen({port: graphQLServerPort})
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)
The implementation uses prom-client library to provide default NodeJS metrics as well as three custom metrics for the GraphQL server:
A simple metrics endpoint can be created by using getMetricsContentType and getMetrics functions from the GraphQLServer instance. In the example below a second route is used to return metrics data.
const graphQLServerPort = 3592
const graphQLServerExpress = express()
const customGraphQLServer = new GraphQLServer({schema: someExampleSchema})
graphQLServerExpress.all('/graphql', (req, res) => {
return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.get('/metrics', async (req, res) => {
return res.contentType(customGraphQLServer.getMetricsContentType()).send(await customGraphQLServer.getMetrics());
})
graphQLServerExpress.listen({port: graphQLServerPort})
console.info(`Starting GraphQL server on port ${graphQLServerPort}`)
The GraphQLServer does not handle CORS requests on its own. It is recommended to handle this on the webserver level, e.g. by using cors library with an Express webserver like in the example below.
const graphQLServerPort = 3592
const graphQLServerExpress = express()
graphQLServerExpress.use(cors())
const customGraphQLServer = new GraphQLServer({schema: someExampleSchema})
graphQLServerExpress.all('/graphql', (req, res) => {
return customGraphQLServer.handleRequest(req, res)
})
graphQLServerExpress.listen({port: graphQLServerPort})
console.info(`Starting GraphQL server on port ${graphQLServerPort}`) Webserver framework compatibility
The GraphQLServer.handleRequest function works with webservers that provide a fitting request and response object that match GraphQLServerRequest and GraphQLServerResponse interfaces. As Express version 2.x matches both no further adjustment is necessary.
If one or both objects do not match GraphQLServerRequest and GraphQLServerResponse it might still be possible to implement these interfaces and map the webserver framework to the graphql-server implementations. An example how to support fastify can be found in the fastify-example
The GraphQLServer accepts the following options. Note that all options are optional and can be overwritten by calling the setOptions function of the GraphQLServer instance.
debug: If true additional log output will be created.schema: The schema that is used to handle the request and send a response. If undefined the GraphQLServer will reject responses with a GraphQL error response with status code 500.shouldUpdateSchemaFunction: Function that can be used to determine whether a schema update should be executed.formatErrorFunction: Function that can be used to format occurring GraphQL errors. Given a GraphQLError it should return a GraphQLFormattedError. By default defaultFormatErrorFunction is called that uses error.toJSON to format the error.schemaValidationFunction: Function that is called when a schema is set or updated. Given a GraphQLSchema it can return a ReadonlyArray<GraphQLError> or an empty array if no errors occurred/should be returned. By default validateSchema from graphql-js library is called.parseFunction: Function that is called to create a DocumentNode with the extracted query in the request information. Given a source and ParseOptions it should return a DocumentNode. By default parse from graphql-js library is called.defaultValidationRules: Default validation rules that are used when validateSchemaFunction is called. Both defaultValidationRules and customValidationRules will be merged together when validateSchemaFunction is called. By default specifiedRules from graphql-js are used. Can be overwritten if no or other default rules should be used.customValidationRules: Custom validation rules that are used when validateSchemaFunction is called. Both defaultValidationRules and customValidationRules will be merged together when validateSchemaFunction is called. By default, an empty array is set. Can be overwritten to add additional rules like NoSchemaIntrospectionCustomRule.validationTypeInfo: Validation type info that is used when validateSchemaFunction is called.validationOptions: Validation options containing { maxErrors?: number } that is used when validateSchemaFunction is called.removeValidationRecommendations: If true removes validation recommendations like "users not found. Did you mean user?". For non-production environments it is usually safe to allow recommendations. For production environments when not providing access to third-party users it is considered good practice to remove these recommendations so users can not circumvent disabled introspection request by using recommendations to explore the schema.validateFunction: Validation function that validates the extracted request against the available schema. By default validate from graphql-js library is called.rootValue: Root value that is used when executeFunction is called. Can be used to define resolvers that handle how defined queries and/or mutations should be resolved (e.g. fetch object from database and return entity).contextFunction: Given a Request and Response this function is used to create a context value that is used when executeFunction is called. Default implementation is defaultContextFunction. Can be used to extract information from the request and/or response and return them as context. This is often used to extract headers like 'Authorization' and set them in the execute function. defaultContextFunction just returns the whole initial Request object.fieldResolver: Field resolver function that is used when executeFunction is called. Default is undefined, if custom logic is necessary it can be added.typeResolver: Type resolver function that is used when executeFunction is called. Default is undefined, if custom logic is necessary it can be added.executeFunction: Execute function that executes the parsed DocumentNode (created in parseFunction) using given schema, values and resolvers. Returns a Promise or value of an ExecutionResult. By default execute from graphql-js library is called.extensionFunction: Extension function that can be used to add additional information to the extensions field of the response. Given a Request, GraphQLRequestInfo and ExecutionResult it should return undefined or an ObjMap of key-value-pairs that are added to theextensions field. By default defaultExtensions is used and returns undefined.reassignAggregateError: If true and the ExecutionResult created by the executeFunction contains an AggregateError (e.g. an error containing a comma-separated list of errors in the message and an originalError containing multiple errors) this function will reassign the originalError.errors to the ExecutionResult.errors field. This is helpful if another application creates AggregateErrors while the initiator of the request (e.g. a Frontend app) does not expect or know how to handle AggregateErrors.collectErrorMetricsFunction:: Given an error name as string, Error, request and request context this function can be used to trigger collecting error metrics. Default implementation is defaultCollectErrorMetrics that increase the error counter for the given errorName or Error by 1.logger: Logger to be used in the GraphQL server. TextLogger and JsonLogger are available in the module. Own Logger can be created by implementing Logger interface.requestInformationExtractor: The RequestInformationExtractor used to extract information from the Request and return a Promise<GraphQLRequestInfo>. By default, the DefaultRequestInformationExtractor is used that tries to extract the information from the body and URL params of the request. Own Extractor can be created by implementing RequestInformationExtractor interface.metricsClient: The MetricsClient used to collect metrics from the GraphQLServer. By default, the DefaultMetricsClient is used that collects default NodeJS and three custom metrics using prom-client library. Own MetricsClient can be used by implementing MetricsClient interface.To make it easier to customise and extend the GraphQLServer classes and class functions are public. This makes extending a class and overwriting logic easy.
In the example below the logic of TextLogger is changed to add the text "SECRETAPP" in front of every log output.
export class SecretApplicationTextLogger extends TextLogger {
prepareLogOutput(logEntry: LogEntry): string {
return `SECRETAPP - ${super.prepareLogOutput(logEntry)}`
}
}
If you have questions or issues please visit our Issue page and open a new issue if there are no fitting issues for your topic yet.
graphql-server is under MIT-License.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4