feat(handler): Custom request params parser (#100)

Author: enisdenjo

README.md

@@ -725,6 +725,78 @@ console.log('Listening to port 4000');
 
 </details>
 
+<details id="graphql-upload-http">
+<summary><a href="#graphql-upload-http">🔗</a> Server handler usage with <a href="https://github.com/jaydenseric/graphql-upload">graphql-upload</a> and <a href="https://nodejs.org/api/http.html">http</a></summary>
+
+```js
+import http from 'http';
+import { createHandler } from 'graphql-http/lib/use/http';
+import processRequest from 'graphql-upload/processRequest.mjs'; // yarn add graphql-upload
+import { schema } from './my-graphql';
+
+const handler = createHandler({
+  schema,
+  async parseRequestParams(req) {
+    const params = await processRequest(req.raw, req.context.res);
+    if (Array.isArray(params)) {
+      throw new Error('Batching is not supported');
+    }
+    return {
+      ...params,
+      // variables must be an object as per the GraphQL over HTTP spec
+      variables: Object(params.variables),
+    };
+  },
+});
+
+const server = http.createServer((req, res) => {
+  if (req.url.startsWith('/graphql')) {
+    handler(req, res);
+  } else {
+    res.writeHead(404).end();
+  }
+});
+
+server.listen(4000);
+console.log('Listening to port 4000');
+```
+
+</details>
+
+<details id="graphql-upload-express">
+<summary><a href="#graphql-upload-express">🔗</a> Server handler usage with <a href="https://github.com/jaydenseric/graphql-upload">graphql-upload</a> and <a href="https://expressjs.com/">express</a></summary>
+
+```js
+import express from 'express'; // yarn add express
+import { createHandler } from 'graphql-http/lib/use/express';
+import processRequest from 'graphql-upload/processRequest.mjs'; // yarn add graphql-upload
+import { schema } from './my-graphql';
+
+const app = express();
+app.all(
+  '/graphql',
+  createHandler({
+    schema,
+    async parseRequestParams(req) {
+      const params = await processRequest(req.raw, req.context.res);
+      if (Array.isArray(params)) {
+        throw new Error('Batching is not supported');
+      }
+      return {
+        ...params,
+        // variables must be an object as per the GraphQL over HTTP spec
+        variables: Object(params.variables),
+      };
+    },
+  }),
+);
+
+app.listen({ port: 4000 });
+console.log('Listening to port 4000');
+```
+
+</details>
+
 <details id="audit-jest">
 <summary><a href="#audit-jest">🔗</a> Audit for servers usage in <a href="https://jestjs.io">Jest</a> environment</summary>
 

docs/interfaces/handler.HandlerOptions.md

@@ -23,6 +23,7 @@
 - [onOperation](handler.HandlerOptions.md#onoperation)
 - [onSubscribe](handler.HandlerOptions.md#onsubscribe)
 - [parse](handler.HandlerOptions.md#parse)
+- [parseRequestParams](handler.HandlerOptions.md#parserequestparams)
 - [rootValue](handler.HandlerOptions.md#rootvalue)
 - [schema](handler.HandlerOptions.md#schema)
 - [validate](handler.HandlerOptions.md#validate)
@@ -203,6 +204,16 @@ GraphQL parse function allowing you to apply a custom parser.
 
 ___
 
+### parseRequestParams
+
+• `Optional` **parseRequestParams**: [`ParseRequestParams`](../modules/handler.md#parserequestparams)<`RequestRaw`, `RequestContext`\>
+
+The request parser for an incoming GraphQL request.
+
+Read more about it in [ParseRequestParams](../modules/handler.md#parserequestparams).
+
+___
+
 ### rootValue
 
 • `Optional` **rootValue**: `unknown`

docs/modules/handler.md

@@ -16,6 +16,7 @@
 - [Handler](handler.md#handler)
 - [OperationArgs](handler.md#operationargs)
 - [OperationContext](handler.md#operationcontext)
+- [ParseRequestParams](handler.md#parserequestparams)
 - [RequestHeaders](handler.md#requestheaders)
 - [Response](handler.md#response)
 - [ResponseBody](handler.md#responsebody)
@@ -108,6 +109,48 @@ the `context` server option.
 
 ___
 
+### ParseRequestParams
+
+Ƭ **ParseRequestParams**<`RequestRaw`, `RequestContext`\>: (`req`: [`Request`](../interfaces/handler.Request.md)<`RequestRaw`, `RequestContext`\>) => `Promise`<[`RequestParams`](../interfaces/common.RequestParams.md) \| [`Response`](handler.md#response) \| `void`\> \| [`RequestParams`](../interfaces/common.RequestParams.md) \| [`Response`](handler.md#response) \| `void`
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `RequestRaw` | `unknown` |
+| `RequestContext` | `unknown` |
+
+#### Type declaration
+
+▸ (`req`): `Promise`<[`RequestParams`](../interfaces/common.RequestParams.md) \| [`Response`](handler.md#response) \| `void`\> \| [`RequestParams`](../interfaces/common.RequestParams.md) \| [`Response`](handler.md#response) \| `void`
+
+The 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.
+
+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](handler.md#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.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `req` | [`Request`](../interfaces/handler.Request.md)<`RequestRaw`, `RequestContext`\> |
+
+##### Returns
+
+`Promise`<[`RequestParams`](../interfaces/common.RequestParams.md) \| [`Response`](handler.md#response) \| `void`\> \| [`RequestParams`](../interfaces/common.RequestParams.md) \| [`Response`](handler.md#response) \| `void`
+
+___
+
 ### RequestHeaders
 
 Ƭ **RequestHeaders**: { `[key: string]`: `string` \| `string`[] \| `undefined`; `set-cookie?`: `string` \| `string`[]  } \| { `get`: (`key`: `string`) => `string` \| ``null``  }

src/__tests__/handler.ts

@@ -242,3 +242,116 @@ it('should respect plain errors toJSON implementation', async () => {
     }
   `);
 });
+
+it('should use the custom request params parser', async () => {
+  const server = startTServer({
+    parseRequestParams() {
+      return {
+        query: '{ hello }',
+      };
+    },
+  });
+
+  const url = new URL(server.url);
+  url.searchParams.set('query', '{ __typename }');
+  const res = await fetch(url.toString(), {
+    // different methods and content-types are not disallowed by the spec
+    method: 'PUT',
+    headers: { 'content-type': 'application/lol' },
+  });
+
+  await expect(res.json()).resolves.toMatchInlineSnapshot(`
+    {
+      "data": {
+        "hello": "world",
+      },
+    }
+  `);
+});
+
+it('should use the response returned from the custom request params parser', async () => {
+  const server = startTServer({
+    parseRequestParams() {
+      return [
+        'Hello',
+        { status: 200, statusText: 'OK', headers: { 'x-hi': 'there' } },
+      ];
+    },
+  });
+
+  const url = new URL(server.url);
+  url.searchParams.set('query', '{ __typename }');
+  const res = await fetch(url.toString());
+
+  expect(res.ok).toBeTruthy();
+  expect(res.headers.get('x-hi')).toBe('there');
+  await expect(res.text()).resolves.toBe('Hello');
+});
+
+it('should report thrown Error from custom request params parser', async () => {
+  const server = startTServer({
+    parseRequestParams() {
+      throw new Error('Wrong.');
+    },
+  });
+
+  const url = new URL(server.url);
+  url.searchParams.set('query', '{ __typename }');
+  const res = await fetch(url.toString());
+
+  expect(res.status).toBe(400);
+  await expect(res.json()).resolves.toMatchInlineSnapshot(`
+    {
+      "errors": [
+        {
+          "message": "Wrong.",
+        },
+      ],
+    }
+  `);
+});
+
+it('should report thrown GraphQLError from custom request params parser', async () => {
+  const server = startTServer({
+    parseRequestParams() {
+      throw new GraphQLError('Wronger.');
+    },
+  });
+
+  const url = new URL(server.url);
+  url.searchParams.set('query', '{ __typename }');
+  const res = await fetch(url.toString(), {
+    headers: { accept: 'application/json' },
+  });
+
+  expect(res.status).toBe(200);
+  await expect(res.json()).resolves.toMatchInlineSnapshot(`
+    {
+      "errors": [
+        {
+          "message": "Wronger.",
+        },
+      ],
+    }
+  `);
+});
+
+it('should use the default if nothing is returned from the custom request params parser', async () => {
+  const server = startTServer({
+    parseRequestParams() {
+      return;
+    },
+  });
+
+  const url = new URL(server.url);
+  url.searchParams.set('query', '{ hello }');
+  const res = await fetch(url.toString());
+
+  await expect(res.json()).resolves.toMatchInlineSnapshot(`
+    {
+      "data": {
+        "hello": "world",
+      },
+    }
+  `);
+});