feat(handler): Request may contain a context value

Author: enisdenjo

docs/README.md

@@ -125,13 +125,14 @@ ___
 
 ### Handler
 
-Ƭ **Handler**<`RawRequest`\>: (`req`: [`Request`](interfaces/Request.md)<`RawRequest`\>) => `Promise`<[`Response`](README.md#response)\>
+Ƭ **Handler**<`RawRequest`, `Context`\>: (`req`: [`Request`](interfaces/Request.md)<`RawRequest`, `Context`\>) => `Promise`<[`Response`](README.md#response)\>
 
 #### Type parameters
 
 | Name | Type |
 | :------ | :------ |
 | `RawRequest` | `unknown` |
+| `Context` | `unknown` |
 
 #### Type declaration
 
@@ -148,7 +149,7 @@ considered internal errors and you should take care of them accordingly.
 
 | Name | Type |
 | :------ | :------ |
-| `req` | [`Request`](interfaces/Request.md)<`RawRequest`\> |
+| `req` | [`Request`](interfaces/Request.md)<`RawRequest`, `Context`\> |
 
 ##### Returns
 
@@ -158,7 +159,7 @@ ___
 
 ### createHandler
 
-▸ **createHandler**<`RawRequest`\>(`options`): [`Handler`](README.md#handler)<`RawRequest`\>
+▸ **createHandler**<`RawRequest`, `Context`\>(`options`): [`Handler`](README.md#handler)<`RawRequest`, `Context`\>
 
 Makes a GraphQL over HTTP Protocol compliant server handler. The handler can
 be used with your favourite server library.
@@ -217,16 +218,17 @@ console.log('Listening to port 4000');
 | Name | Type |
 | :------ | :------ |
 | `RawRequest` | `unknown` |
+| `Context` | `unknown` |
 
 #### Parameters
 
 | Name | Type |
 | :------ | :------ |
-| `options` | [`HandlerOptions`](interfaces/HandlerOptions.md)<`RawRequest`\> |
+| `options` | [`HandlerOptions`](interfaces/HandlerOptions.md)<`RawRequest`, `Context`\> |
 
 #### Returns
 
-[`Handler`](README.md#handler)<`RawRequest`\>
+[`Handler`](README.md#handler)<`RawRequest`, `Context`\>
 
 ___
 

docs/interfaces/HandlerOptions.md

@@ -1,12 +1,13 @@
 [graphql-http](../README.md) / HandlerOptions
 
-# Interface: HandlerOptions<RawRequest\>
+# Interface: HandlerOptions<RawRequest, Context\>
 
 ## Type parameters
 
 | Name | Type |
 | :------ | :------ |
 | `RawRequest` | `unknown` |
+| `Context` | `unknown` |
 
 ## Table of contents
 
@@ -25,7 +26,7 @@
 
 ### context
 
-• `Optional` **context**: [`ExecutionContext`](../README.md#executioncontext) \| (`req`: [`Request`](Request.md)<`RawRequest`\>, `args`: `ExecutionArgs`) => [`Response`](../README.md#response) \| [`ExecutionContext`](../README.md#executioncontext) \| `Promise`<[`Response`](../README.md#response) \| [`ExecutionContext`](../README.md#executioncontext)\>
+• `Optional` **context**: [`ExecutionContext`](../README.md#executioncontext) \| (`req`: [`Request`](Request.md)<`RawRequest`, `Context`\>, `args`: `ExecutionArgs`) => [`Response`](../README.md#response) \| [`ExecutionContext`](../README.md#executioncontext) \| `Promise`<[`Response`](../README.md#response) \| [`ExecutionContext`](../README.md#executioncontext)\>
 
 A value which is provided to every resolver and holds
 important contextual information like the currently
@@ -89,7 +90,7 @@ ___
 
 ### onOperation
 
-• `Optional` **onOperation**: (`req`: [`Request`](Request.md)<`RawRequest`\>, `args`: `ExecutionArgs`, `result`: `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\>) => `void` \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response) \| `Promise`<`void` \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response)\>
+• `Optional` **onOperation**: (`req`: [`Request`](Request.md)<`RawRequest`, `Context`\>, `args`: `ExecutionArgs`, `result`: `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\>) => `void` \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response) \| `Promise`<`void` \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response)\>
 
 #### Type declaration
 
@@ -111,7 +112,7 @@ further execution.
 
 | Name | Type |
 | :------ | :------ |
-| `req` | [`Request`](Request.md)<`RawRequest`\> |
+| `req` | [`Request`](Request.md)<`RawRequest`, `Context`\> |
 | `args` | `ExecutionArgs` |
 | `result` | `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> |
 
@@ -123,7 +124,7 @@ ___
 
 ### onSubscribe
 
-• `Optional` **onSubscribe**: (`req`: [`Request`](Request.md)<`RawRequest`\>, `params`: [`RequestParams`](RequestParams.md)) => `void` \| readonly `GraphQLError`[] \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| readonly `GraphQLError`[] \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
+• `Optional` **onSubscribe**: (`req`: [`Request`](Request.md)<`RawRequest`, `Context`\>, `params`: [`RequestParams`](RequestParams.md)) => `void` \| readonly `GraphQLError`[] \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| readonly `GraphQLError`[] \| `ExecutionResult`<`ObjMap`<`unknown`\>, `ObjMap`<`unknown`\>\> \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
 
 #### Type declaration
 
@@ -160,7 +161,7 @@ further execution.
 
 | Name | Type |
 | :------ | :------ |
-| `req` | [`Request`](Request.md)<`RawRequest`\> |
+| `req` | [`Request`](Request.md)<`RawRequest`, `Context`\> |
 | `params` | [`RequestParams`](RequestParams.md) |
 
 ##### Returns
@@ -195,7 +196,7 @@ ___
 
 ### schema
 
-• `Optional` **schema**: `GraphQLSchema` \| (`req`: [`Request`](Request.md)<`RawRequest`\>, `args`: `Omit`<`ExecutionArgs`, ``"schema"``\>) => [`Response`](../README.md#response) \| `GraphQLSchema` \| `Promise`<[`Response`](../README.md#response) \| `GraphQLSchema`\>
+• `Optional` **schema**: `GraphQLSchema` \| (`req`: [`Request`](Request.md)<`RawRequest`, `Context`\>, `args`: `Omit`<`ExecutionArgs`, ``"schema"``\>) => [`Response`](../README.md#response) \| `GraphQLSchema` \| `Promise`<[`Response`](../README.md#response) \| `GraphQLSchema`\>
 
 The GraphQL schema on which the operations will
 be executed and validated against.

docs/interfaces/Request.md

@@ -1,6 +1,6 @@
 [graphql-http](../README.md) / Request
 
-# Interface: Request<RawRequest\>
+# Interface: Request<RawRequest, Context\>
 
 Server agnostic request interface containing the raw request
 which is server dependant.
@@ -10,12 +10,14 @@ which is server dependant.
 | Name |
 | :------ |
 | `RawRequest` |
+| `Context` |
 
 ## Table of contents
 
 ### Properties
 
 - [body](Request.md#body)
+- [context](Request.md#context)
 - [headers](Request.md#headers)
 - [method](Request.md#method)
 - [raw](Request.md#raw)
@@ -29,6 +31,14 @@ which is server dependant.
 
 ___
 
+### context
+
+• `Readonly` **context**: `Context`
+
+Context value about the incoming request, you're free to pass any information here.
+
+___
+
 ### headers
 
 • `Readonly` **headers**: [`RequestHeaders`](RequestHeaders.md)

src/__tests__/handler.ts

@@ -1,6 +1,7 @@
 import { jest } from '@jest/globals';
 import { GraphQLError } from 'graphql';
 import fetch from 'node-fetch';
+import { Request } from '../common';
 import { startTServer } from './utils/tserver';
 
 it.each(['schema', 'context', 'onSubscribe', 'onOperation'])(
@@ -51,3 +52,25 @@ it('should respond with result returned from onSubscribe', async () => {
   expect(res.json()).resolves.toEqual({ data: { __typename: 'Query' } });
   expect(onOperationFn).not.toBeCalled(); // early result, operation did not happen
 });
+
+it.each(['schema', 'context', 'onSubscribe', 'onOperation'])(
+  'should provide the request context to %s',
+  async (option) => {
+    const optionFn = jest.fn<(req: Request<unknown, unknown>) => void>();
+
+    const context = {};
+    const server = startTServer({
+      changeRequest: (req) => ({
+        ...req,
+        context,
+      }),
+      [option]: optionFn,
+    });
+
+    const url = new URL(server.url);
+    url.searchParams.set('query', '{ __typename }');
+    await fetch(url.toString());
+
+    expect(optionFn.mock.calls[0][0]?.context).toBe(context);
+  },
+);

src/__tests__/utils/tserver.ts

@@ -1,4 +1,5 @@
 import { createHandler, HandlerOptions } from '../../handler';
+import { Request } from '../../common';
 import http from 'http';
 import net from 'net';
 import { Response } from 'node-fetch';
@@ -19,11 +20,16 @@ export interface TServer {
   dispose: Dispose;
 }
 export function startTServer(
-  options: HandlerOptions<http.IncomingMessage> = {},
+  options: HandlerOptions<http.IncomingMessage> & {
+    changeRequest?: (
+      req: Request<http.IncomingMessage, unknown>,
+    ) => Request<http.IncomingMessage, unknown>;
+  } = {},
 ): TServer {
+  const { changeRequest = (req) => req, ...handlerOptions } = options;
   const handle = createHandler({
     schema,
-    ...options,
+    ...handlerOptions,
   });
   const [url, dispose] = startDisposableServer(
     http.createServer(async (req, res) => {
@@ -34,17 +40,20 @@ export function startTServer(
         if (!req.method) {
           throw new Error('Missing request method');
         }
-        const [body, init] = await handle({
-          url: req.url,
-          method: req.method,
-          headers: req.headers,
-          body: await new Promise<string>((resolve) => {
-            let body = '';
-            req.on('data', (chunk) => (body += chunk));
-            req.on('end', () => resolve(body));
+        const [body, init] = await handle(
+          changeRequest({
+            url: req.url,
+            method: req.method,
+            headers: req.headers,
+            body: await new Promise<string>((resolve) => {
+              let body = '';
+              req.on('data', (chunk) => (body += chunk));
+              req.on('end', () => resolve(body));
+            }),
+            raw: req,
+            context: null,
           }),
-          raw: req,
-        });
+        );
         res.writeHead(init.status, init.statusText, init.headers).end(body);
       } catch (err) {
         if (err instanceof Error) {

src/common.ts

@@ -30,7 +30,7 @@ export interface RequestHeaders {
  *
  * @category Common
  */
-export interface Request<RawRequest> {
+export interface Request<RawRequest, Context> {
   readonly method: string;
   readonly url: string;
   readonly headers: RequestHeaders;
@@ -42,6 +42,10 @@ export interface Request<RawRequest> {
    * `http.IncomingMessage` when just using Node with `http.createServer`.
    */
   readonly raw: RawRequest;
+  /**
+   * Context value about the incoming request, you're free to pass any information here.
+   */
+  readonly context: Context;
 }
 
 /**

src/handler.ts

@@ -40,7 +40,7 @@ export type ExecutionContext =
   | null;
 
 /** @category Server */
-export interface HandlerOptions<RawRequest = unknown> {
+export interface HandlerOptions<RawRequest = unknown, Context = unknown> {
   /**
    * The GraphQL schema on which the operations will
    * be executed and validated against.
@@ -60,7 +60,7 @@ export interface HandlerOptions<RawRequest = unknown> {
   schema?:
     | GraphQLSchema
     | ((
-        req: Request<RawRequest>,
+        req: Request<RawRequest, Context>,
         args: Omit<ExecutionArgs, 'schema'>,
       ) => Promise<GraphQLSchema | Response> | GraphQLSchema | Response);
   /**
@@ -71,7 +71,7 @@ export interface HandlerOptions<RawRequest = unknown> {
   context?:
     | ExecutionContext
     | ((
-        req: Request<RawRequest>,
+        req: Request<RawRequest, Context>,
         args: ExecutionArgs,
       ) => Promise<ExecutionContext | Response> | ExecutionContext | Response);
   /**
@@ -123,7 +123,7 @@ export interface HandlerOptions<RawRequest = unknown> {
    * further execution.
    */
   onSubscribe?: (
-    req: Request<RawRequest>,
+    req: Request<RawRequest, Context>,
     params: RequestParams,
   ) =>
     | Promise<
@@ -152,7 +152,7 @@ export interface HandlerOptions<RawRequest = unknown> {
    * further execution.
    */
   onOperation?: (
-    req: Request<RawRequest>,
+    req: Request<RawRequest, Context>,
     args: ExecutionArgs,
     result: ExecutionResult,
   ) =>
@@ -172,8 +172,8 @@ export interface HandlerOptions<RawRequest = unknown> {
  *
  * @category Server
  */
-export type Handler<RawRequest = unknown> = (
-  req: Request<RawRequest>,
+export type Handler<RawRequest = unknown, Context = unknown> = (
+  req: Request<RawRequest, Context>,
 ) => Promise<Response>;
 
 /**
@@ -231,9 +231,9 @@ export type Handler<RawRequest = unknown> = (
  *
  * @category Server
  */
-export function createHandler<RawRequest = unknown>(
-  options: HandlerOptions<RawRequest>,
-): Handler<RawRequest> {
+export function createHandler<RawRequest = unknown, Context = unknown>(
+  options: HandlerOptions<RawRequest, Context>,
+): Handler<RawRequest, Context> {
   const {
     schema,
     context,