A highly evolved GraphQL HTTP Server 🧬

GraphQL Helix is a collection of utility functions for building your own GraphQL HTTP server. You can check out Building a GraphQL server with GraphQL Helix on DEV for a detailed tutorial on getting started.

Features

• Framework and runtime agnostic. Use whatever HTTP library you want. GraphQL Helix works in Node, Deno and in the browser.
• HTTP first. GraphQL Helix allows you to create a GraphQL over HTTP specification-compliant server, while exposing a single HTTP endpoint for everything from documentation to subscriptions.
• Server push and client pull. GraphQL Helix supports real-time requests with both subscriptions and @defer and @stream directives.
• Flexible. GraphQL Helix abstracts away logic that's common to all GraphQL HTTP servers, while leaving the implementation to you. Implement the features you want and take full control of your transport layer.
• Minimal. No bloat. No paid platform intergration. Zero dependencies outside of graphql-js.

Installation

npm install graphql-helix

Basic Usage

The following example shows how to integrate GraphQL Helix with Node.js using Express. This example shows how to implement all the basic features, including a GraphiQL interface, subscriptions and support for @stream and @defer. See the rest of the examples for implementations using other frameworks and runtimes. For implementing additional features, see the Recipes section below.

1import express, { RequestHandler } from "express";
2import {
3  getGraphQLParameters,
4  processRequest,
5  renderGraphiQL,
6  shouldRenderGraphiQL,
7} from "../lib";
8import { schema } from "./schema";
9
10const app = express();
11
12app.use(express.json());
13
14app.use("/graphql", async (req, res) => {
15  // Create a generic Request object that can be consumed by Graphql Helix's API
16  const request = {
17    body: req.body,
18    headers: req.headers,
19    method: req.method,
20    query: req.query,
21  };
22
23  // Determine whether we should render GraphiQL instead of returning an API response
24  if (shouldRenderGraphiQL(request)) {
25    res.send(renderGraphiQL());
26  } else {
27    // Extract the GraphQL parameters from the request
28    const { operationName, query, variables } = getGraphQLParameters(request);
29
30    // Validate and execute the query
31    const result = await processRequest({
32      operationName,
33      query,
34      variables,
35      request,
36      schema,
37    });
38
39    // processRequest returns one of three types of results depending on how the server should respond
40    // 1) RESPONSE: a regular JSON payload
41    // 2) MULTIPART RESPONSE: a multipart response (when @stream or @defer directives are used)
42    // 3) PUSH: a stream of events to push back down the client for a subscription
43    if (result.type === "RESPONSE") {
44      // We set the provided status and headers and just the send the payload back to the client
45      result.headers.forEach(({ name, value }) => res.setHeader(name, value));
46      res.status(result.status);
47      res.json(result.payload);
48    } else if (result.type === "MULTIPART_RESPONSE") {
49      // Indicate we're sending a multipart response
50      res.writeHead(200, {
51        Connection: "keep-alive",
52        "Content-Type": 'multipart/mixed; boundary="-"',
53        "Transfer-Encoding": "chunked",
54      });
55
56      // If the request is closed by the client, we unsubscribe and stop executing the request
57      req.on("close", () => {
58        result.unsubscribe();
59      });
60
61      res.write("---");
62
63      // Subscribe and send back each result as a separate chunk. We await the subscribe
64      // call. Once we're done executing the request and there are no more results to send
65      // to the client, the Promise returned by subscribe will resolve and we can end the response.
66      await result.subscribe((result) => {
67        const chunk = Buffer.from(JSON.stringify(result), "utf8");
68        const data = [          "",          "Content-Type: application/json; charset=utf-8",          "Content-Length: " + String(chunk.length),          "",          chunk,        ];
69
70        if (result.hasNext) {
71          data.push("---");
72        }
73
74        res.write(data.join("\r\n"));
75      });
76
77      res.write("\r\n-----\r\n");
78      res.end();
79    } else {
80      // Indicate we're sending an event stream to the client
81      res.writeHead(200, {
82        "Content-Type": "text/event-stream",
83        Connection: "keep-alive",
84        "Cache-Control": "no-cache",
85      });
86
87      // If the request is closed by the client, we unsubscribe and stop executing the request
88      req.on("close", () => {
89        result.unsubscribe();
90      });
91
92      // We subscribe to the event stream and push any new events to the client
93      await result.subscribe((result) => {
94        res.write(`data: ${JSON.stringify(result)}\n\n`);
95      });
96    }
97  }
98});
99
100const port = process.env.PORT || 4000;
101
102app.listen(port, () => {
103  console.log(`GraphQL server is running on port ${port}.`);
104});

API

getGraphQLParameters

1function getGraphQLParameters(request: Request): GraphQLParams;

Extracts the query, variables and operationName values from the request.

processRequest

1function processRequest<TContext, TRootValue>(
2  options: ProcessRequestOptions<TContext, TRootValue>
3): Promise<ProcessRequestResult<TContext, TRootValue>>;

Takes the schema, request, query, variables, operationName and a number of other optional parameters and returns one of three kinds of results, depending on the sort of response the server should send back.

renderGraphiQL

1function renderGraphiQL(options: RenderGraphiQLOptions = {}): string;

Returns the HTML to render a GraphiQL instance.

shouldRenderGraphiQL

1function shouldRenderGraphiQL(request: Request): boolean;

Uses the method and headers in the request to determine whether a GraphiQL instance should be returned instead of processing an API request.

Types

1export interface GraphQLParams {
2  operationName?: string;
3  query?: string;
4  variables?: string | { [name: string]: any };
5}
6
7export interface RenderGraphiQLOptions {
8  /**
9   * An optional GraphQL string to use when no query is provided and no stored
10   * query exists from a previous session.  If undefined is provided, GraphiQL
11   * will use its own default query.
12   */
13  defaultQuery?: string;
14  /**
15   * Whether to open the variable editor by default. Defaults to `true`.
16   */
17  defaultVariableEditorOpen?: boolean;
18  /**
19   * The endpoint requests should be sent. Defaults to `"/graphql"`.
20   */
21  endpoint?: string;
22  /**
23   * The initial headers to render inside the header editor. Defaults to `"{}"`.
24   */
25  headers?: string;
26  /**
27   * Whether the header editor is enabled. Defaults to `true`.
28   */
29  headerEditorEnabled?: boolean;
30  /**
31   * A cryptographic nonce for use with Content-Security-Policy.
32   */
33  nonce?: string;
34  /**
35   * The endpoint subscription requests should be sent to. Defaults to the value of the `endpoint` parameter.
36   */
37  subscriptionsEndpoint?: string;
38}
39
40export interface ProcessRequestOptions<TContext, TRootValue> {
41  /**
42   * A function whose return value is passed in as the `context` to `execute`.
43   */
44  contextFactory?: (
45    executionContext: ExecutionContext
46  ) => Promise<TContext> | TContext;
47  /**
48   * An optional function which will be used to execute instead of default `execute` from `graphql-js`.
49   */
50  execute?: typeof execute;
51  /**
52   * The name of the Operation in the Document to execute.
53   */
54  operationName?: string;
55  /**
56   * An optional function which will be used to create a document instead of the default `parse` from `graphql-js`.
57   */
58  parse?: typeof parse;
59  /**
60   * A Document containing GraphQL Operations and Fragments to execute.
61   */
62  query?: string | DocumentNode;
63  /**
64   * An object describing the HTTP request.
65   */
66  request: Request;
67  /**
68   * A function whose return value is passed in as the `rootValue` to `execute`.
69   */
70  rootValueFactory?: (
71    executionContext: ExecutionContext
72  ) => Promise<TRootValue> | TRootValue;
73  /**
74   * The GraphQL schema used to process the request.
75   */
76  schema: GraphQLSchema;
77  /**
78   * An optional function which will be used to subscribe instead of default `subscribe` from `graphql-js`.
79   */
80  subscribe?: typeof subscribe;
81  /**
82   * An optional function which will be used to validate instead of default `validate` from `graphql-js`.
83   */
84  validate?: typeof validate;
85  /**
86   * An optional array of validation rules that will be applied to the document
87   * in place of those defined by the GraphQL specification.
88   */
89  validationRules?: ReadonlyArray<ValidationRule>;
90  /**
91   * Values for any Variables defined by the Operation.
92   */
93  variables?: string | { [name: string]: any };
94}
95
96export interface ExecutionContext {
97  document: DocumentNode;
98  operation: OperationDefinitionNode;
99  variables?: { readonly [name: string]: unknown };
100}
101
102export interface Request {
103  body?: any;
104  headers: Headers;
105  method: string;
106  query: any;
107}
108
109export type Headers =
110  | Record<string, string | string[] | undefined>
111  | { get(name: string): string | null };
112
113export interface Response<TContext, TRootValue> {
114  type: "RESPONSE";
115  status: number;
116  headers: { name: string; value: string }[];
117  payload: ExecutionResult;
118  context?: TContext;
119  rootValue?: TRootValue;
120  document?: DocumentNode;
121  operation?: OperationDefinitionNode;
122}
123
124export interface MultipartResponse<TContext, TRootValue> {
125  type: "MULTIPART_RESPONSE";
126  subscribe: (onResult: (result: ExecutionResult) => void) => Promise<void>;
127  unsubscribe: () => void;
128  context?: TContext;
129  rootValue?: TRootValue;
130  document?: DocumentNode;
131  operation?: OperationDefinitionNode;
132}
133
134export interface Push<TContext, TRootValue> {
135  type: "PUSH";
136  subscribe: (onResult: (result: ExecutionResult) => void) => Promise<void>;
137  unsubscribe: () => void;
138  context?: TContext;
139  rootValue?: TRootValue;
140  document?: DocumentNode;
141  operation?: OperationDefinitionNode;
142}
143
144export type ProcessRequestResult<TContext, TRootValue> =
145  | Response<TContext, TRootValue>
146  | MultipartResponse<TContext, TRootValue>
147  | Push<TContext, TRootValue>;

Recipes

1app.use("/graphql", async (req, res) => {
2  ...
3
4  const result = await processRequest({
5    operationName,
6    query,
7    variables,
8    request,
9    schema,
10    contextFactory: () => ({
11      req,
12    }),
13  });
14}

1export interface ExecutionContext {
2  document: DocumentNode;
3  operation: OperationDefinitionNode;
4  variables?: { readonly [name: string]: unknown };
5}

1if (result.type === "PUSH") {
2  // Indicate that we're sending a stream of events and should keep the connection open.
3  res.writeHead(200, {
4    "Content-Type": "text/event-stream",
5    Connection: "keep-alive",
6    "Cache-Control": "no-cache",
7  });
8
9  // If the client closes the connection, we unsubscribe to prevent memory leaks.
10  req.on("close", () => {
11    result.unsubscribe();
12  });
13
14  // We subscribe to any new events and push them down to the client that initiated the subscription.
15  await result.subscribe((result) => {
16    res.write(`data: ${JSON.stringify(result)}\n\n`);
17  });
18}

1import express from "express";
2import {
3  getGraphQLParameters,
4  processRequest,
5  renderGraphiQL,
6  shouldRenderGraphiQL,
7} from "graphql-helix";
8import { execute, subscribe } from "graphql";
9import { createServer } from "graphql-ws";
10import { schema } from "./schema";
11
12const app = express();
13
14app.use(express.json());
15
16app.use("/graphql", async (req, res) => {
17  // handle the request using processRequest as shown before
18});
19
20const port = process.env.PORT || 4000;
21
22const server = app.listen(port, () => {
23  createServer(
24    {
25      schema,
26      execute,
27      subscribe,
28    },
29    {
30      server,
31      path: "/graphql",
32    }
33  );
34
35  console.log(`GraphQL server is running on port ${port}.`);
36});

1if (result.type === "MULTIPART_RESPONSE") {
2  // Indicate that this is a multipart response and the connection should be kept open.
3  res.writeHead(200, {
4    Connection: "keep-alive",
5    "Content-Type": 'multipart/mixed; boundary="-"',
6    "Transfer-Encoding": "chunked",
7  });
8
9  // If the client closes the connection, we unsubscribe to prevent memory leaks.
10  req.on("close", () => {
11    result.unsubscribe();
12  });
13
14  res.write("---");
15
16  // Subscribe to new results. The callback will be called with the
17  // ExecutionResult object that should be sent back to the client for each chunk.
18  await result.subscribe((result) => {
19    const chunk = Buffer.from(JSON.stringify(formatResult(result)), "utf8");
20    const data = [      "Content-Type: application/json; charset=utf-8",      "Content-Length: " + String(chunk.length),      "",      chunk,    ];
21
22    if (result.hasNext) {
23      data.push("---");
24    }
25
26    res.write(data.join("\r\n"));
27  });
28
29  // The Promise returned by `subscribe` will only resolve once all chunks have been emitted,
30  // at which point we can end the request.
31  res.write("\r\n-----\r\n");
32  res.end();
33}

1import { InMemoryLiveQueryStore } from "@n1ru4l/in-memory-live-query-store";
2
3const liveQueryStore = new InMemoryLiveQueryStore();
4
5...
6
7const result = await processRequest({
8  operationName,
9  query,
10  variables,
11  request,
12  schema,
13  contextFactory: () => ({
14    liveQueryStore,
15  }),
16  execute: liveQueryStore.execute,
17});

1let queryId: string;
2let operationName: string | undefined;
3let variables: any;
4
5if (req.method === "POST") {
6  queryId = req.body.queryId;
7  operationName = req.body.operationName;
8  variables = req.body.variables;
9} else {
10  queryId = req.query.queryId as string;
11  operationName = req.query.operationName as string;
12  variables = req.query.variables;
13}
14
15const query = queryMap[queryId];
16
17if (!query) {
18  res.status(400);
19  res.json({
20    errors: [
21      new GraphQLError(
22        `Could not find a persisted query with an id of ${queryId}`
23      ),
24    ],
25  });
26  return;
27}
28
29const result = await processRequest({
30  operationName,
31  query,
32  variables,
33  request,
34  schema,
35});

1const result = await processRequest({
2  // ...
3  execute: (
4    schema,
5    documentAst,
6    rootValue,
7    contextValue,
8    variableValues,
9    operationName
10  ) => {
11    const compiledQuery = compileQuery(schema, documentAst, operationName);
12
13    if (isCompiledQuery(compiledQuery)) {
14      return compiledQuery.query(rootValue, contextValue, variableValues || {});
15    }
16
17    return compiledQuery;
18  },
19});

1import lru from "tiny-lru";
2
3const cache = lru(1000, 3600000);

1import { parse } from "graphql";
2
3const result = await processRequest({
4  operationName,
5  query,
6  variables,
7  request,
8  schema,
9  parse: (source, options) => {
10    if (!cache.get(query)) {
11      cache.set(query, parse(source, options));
12    }
13
14    return cache.get(query);
15  },
16});