graphql-http / handler
- FormatError
- Handler
- OperationArgs
- OperationContext
- ParseRequestParams
- RequestHeaders
- Response
- ResponseBody
- ResponseHeaders
Ƭ FormatError: (err: Readonly<GraphQLError | Error>) => GraphQLError | Error
▸ (err): GraphQLError | Error
The (GraphQL) error formatter function.
| Name | Type |
|---|---|
err |
Readonly<GraphQLError | Error> |
GraphQLError | Error
Ƭ Handler<RequestRaw, RequestContext>: (req: Request<RequestRaw, RequestContext>) => Promise<Response>
| Name | Type |
|---|---|
RequestRaw |
unknown |
RequestContext |
unknown |
▸ (req): Promise<Response>
The ready-to-use handler. Simply plug it in your favorite HTTP framework and enjoy.
Errors thrown from any of the provided options or callbacks (or even due to library misuse or potential bugs) will reject the handler's promise. They are considered internal errors and you should take care of them accordingly.
| Name | Type |
|---|---|
req |
Request<RequestRaw, RequestContext> |
Promise<Response>
Ƭ OperationArgs<Context>: ExecutionArgs & { contextValue?: Context }
| Name | Type |
|---|---|
Context |
extends OperationContext = undefined |
Ƭ OperationContext: Record<PropertyKey, unknown> | symbol | number | string | boolean | undefined | null
A concrete GraphQL execution context value type.
Mainly used because TypeScript collapses unions
with any or unknown to any or unknown. So,
we use a custom type to allow definitions such as
the context server option.
Ƭ ParseRequestParams<RequestRaw, RequestContext>: (req: Request<RequestRaw, RequestContext>) => Promise<RequestParams | Response | void> | RequestParams | Response | void
| Name | Type |
|---|---|
RequestRaw |
unknown |
RequestContext |
unknown |
▸ (req): Promise<RequestParams | Response | void> | RequestParams | Response | void
The request parser for an incoming GraphQL request in the handler.
It should parse and validate the request itself, including the request method and the content-type of the body.
In case you are extending the server to handle more request types, this is the perfect place to do so.
If an error is thrown, it will be formatted using the provided FormatError and handled following the spec to be gracefully reported to the client.
Throwing an instance of Error will always have the client respond with a 400: Bad Request
and the error's message in the response body; however, if an instance of GraphQLError is thrown,
it will be reported depending on the accepted content-type.
If you return nothing, the default parser will be used instead.
| Name | Type |
|---|---|
req |
Request<RequestRaw, RequestContext> |
Promise<RequestParams | Response | void> | RequestParams | Response | void
Ƭ RequestHeaders: { [key: string]: string | string[] | undefined; set-cookie?: string | string[] } | { get: (key: string) => string | null }
The incoming request headers the implementing server should provide.
Ƭ Response: readonly [body: ResponseBody | null, init: ResponseInit]
Server agnostic response returned from graphql-http containing the
body and init options needing to be coerced to the server implementation in use.
Ƭ ResponseBody: string
Server agnostic response body returned from graphql-http needing
to be coerced to the server implementation in use.
Ƭ ResponseHeaders: { accept?: string ; allow?: string ; content-type?: string } & Record<string, string>
The response headers that get returned from graphql-http.
▸ createHandler<RequestRaw, RequestContext, Context>(options): Handler<RequestRaw, RequestContext>
Makes a GraphQL over HTTP spec compliant server handler. The handler can be used with your favorite server library.
Beware that the handler resolves only after the whole operation completes.
Errors thrown from any of the provided options or callbacks (or even due to library misuse or potential bugs) will reject the handler's promise. They are considered internal errors and you should take care of them accordingly.
For production environments, its recommended not to transmit the exact internal error details to the client, but instead report to an error logging tool or simply the console.
Simple example usage with Node:
import http from 'http';
import { createHandler } from 'graphql-http';
import { schema } from './my-graphql-schema';
// Create the GraphQL over HTTP handler
const handler = createHandler({ schema });
// Create a HTTP server using the handler on `/graphql`
const server = http.createServer(async (req, res) => {
if (!req.url.startsWith('/graphql')) {
return res.writeHead(404).end();
}
try {
const [body, init] = await handler({
url: req.url,
method: req.method,
headers: req.headers,
body: () => new Promise((resolve) => {
let body = '';
req.on('data', (chunk) => (body += chunk));
req.on('end', () => resolve(body));
}),
raw: req,
});
res.writeHead(init.status, init.statusText, init.headers).end(body);
} catch (err) {
// BEWARE not to transmit the exact internal error message in production environments
res.writeHead(500).end(err.message);
}
});
server.listen(4000);
console.log('Listening to port 4000');| Name | Type |
|---|---|
RequestRaw |
unknown |
RequestContext |
unknown |
Context |
extends OperationContext = undefined |
| Name | Type |
|---|---|
options |
HandlerOptions<RequestRaw, RequestContext, Context> |
Handler<RequestRaw, RequestContext>
▸ parseRequestParams<RequestRaw, RequestContext>(req): Promise<Response | RequestParams>
The GraphQL over HTTP spec compliant request parser for an incoming GraphQL request. It parses and validates the request itself, including the request method and the content-type of the body.
If the HTTP request itself is invalid or malformed, the function will return an appropriate Response.
If the HTTP request is valid, but is not a well-formatted GraphQL request, the function will throw an error and it is up to the user to handle and respond as they see fit.
| Name | Type |
|---|---|
RequestRaw |
unknown |
RequestContext |
unknown |
| Name | Type |
|---|---|
req |
Request<RequestRaw, RequestContext> |
Promise<Response | RequestParams>