feat(handler): onSubscribe option can return an array of GraphQL errors

Author: enisdenjo

docs/interfaces/HandlerOptions.md

@@ -123,11 +123,11 @@ ___
 
 ### onSubscribe
 
-• `Optional` **onSubscribe**: (`req`: [`Request`](Request.md)<`RawRequest`\>, `params`: [`RequestParams`](RequestParams.md)) => `void` \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
+• `Optional` **onSubscribe**: (`req`: [`Request`](Request.md)<`RawRequest`\>, `params`: [`RequestParams`](RequestParams.md)) => `void` \| `GraphQLError`[] \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| `GraphQLError`[] \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
 
 #### Type declaration
 
-▸ (`req`, `params`): `void` \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
+▸ (`req`, `params`): `void` \| `GraphQLError`[] \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| `GraphQLError`[] \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
 
 The subscribe callback executed right after processing the request
 before proceeding with the GraphQL operation execution.
@@ -136,6 +136,9 @@ If you return `ExecutionArgs` from the callback, it will be used instead of
 trying to build one internally. In this case, you are responsible for providing
 a ready set of arguments which will be directly plugged in the operation execution.
 
+If you return an array of `GraphQLError` from the callback, they will be reported
+to the client while complying with the spec.
+
 Omitting the fields `contextValue` from the returned `ExecutionArgs` will use the
 provided `context` option, if available.
 
@@ -156,7 +159,7 @@ further execution.
 
 ##### Returns
 
-`void` \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
+`void` \| `GraphQLError`[] \| [`Response`](../README.md#response) \| `ExecutionArgs` \| `Promise`<`void` \| `GraphQLError`[] \| [`Response`](../README.md#response) \| `ExecutionArgs`\>
 
 ___
 

docs/interfaces/ResponseInit.md

@@ -29,4 +29,4 @@ ___
 
 ### statusText
 
-• `Optional` `Readonly` **statusText**: `string`
+• `Readonly` **statusText**: `string`

src/__tests__/handler.ts

@@ -1,3 +1,4 @@
+import { GraphQLError } from 'graphql';
 import fetch from 'node-fetch';
 import { startTServer } from './utils/tserver';
 
@@ -16,3 +17,17 @@ it.each(['schema', 'context', 'onSubscribe', 'onOperation'])(
     expect(res.status).toBe(418);
   },
 );
+
+it('should report graphql errors returned from onSubscribe', async () => {
+  const server = startTServer({
+    onSubscribe: () => {
+      return [new GraphQLError('Woah!')];
+    },
+  });
+
+  const url = new URL(server.url);
+  url.searchParams.set('query', '{ __typename }');
+  const res = await fetch(url.toString());
+  expect(res.status).toBe(400);
+  expect(res.json()).resolves.toEqual({ errors: [{ message: 'Woah!' }] });
+});

src/handler.ts

@@ -14,8 +14,10 @@ import {
   DocumentNode,
   getOperationAST as graphqlGetOperationAST,
   OperationTypeNode,
+  GraphQLError,
 } from 'graphql';
 import { isResponse, Request, RequestParams, Response } from './common';
+import { areGraphQLErrors } from './utils';
 
 /**
  * A concrete GraphQL execution context value type.
@@ -98,6 +100,9 @@ export interface HandlerOptions<RawRequest = unknown> {
    * trying to build one internally. In this case, you are responsible for providing
    * a ready set of arguments which will be directly plugged in the operation execution.
    *
+   * If you return an array of `GraphQLError` from the callback, they will be reported
+   * to the client while complying with the spec.
+   *
    * Omitting the fields `contextValue` from the returned `ExecutionArgs` will use the
    * provided `context` option, if available.
    *
@@ -113,8 +118,9 @@ export interface HandlerOptions<RawRequest = unknown> {
     req: Request<RawRequest>,
     params: RequestParams,
   ) =>
-    | Promise<ExecutionArgs | Response | void>
+    | Promise<ExecutionArgs | GraphQLError[] | Response | void>
     | ExecutionArgs
+    | GraphQLError[]
     | Response
     | void;
   /**
@@ -379,9 +385,30 @@ export function createHandler<RawRequest = unknown>(
     }
 
     let args: ExecutionArgs;
-    const maybeResOrExecArgs = await onSubscribe?.(req, params);
-    if (isResponse(maybeResOrExecArgs)) return maybeResOrExecArgs;
-    else if (maybeResOrExecArgs) args = maybeResOrExecArgs;
+    const maybeResErrsOrArgs = await onSubscribe?.(req, params);
+    if (isResponse(maybeResErrsOrArgs)) return maybeResErrsOrArgs;
+    else if (areGraphQLErrors(maybeResErrsOrArgs))
+      return [
+        JSON.stringify({ errors: maybeResErrsOrArgs }),
+        {
+          ...(acceptedMediaType === 'application/json'
+            ? {
+                status: 200,
+                statusText: 'OK',
+              }
+            : {
+                status: 400,
+                statusText: 'Bad Request',
+              }),
+          headers: {
+            'content-type':
+              acceptedMediaType === 'application/json'
+                ? 'application/json; charset=utf-8'
+                : 'application/graphql+json; charset=utf-8',
+          },
+        },
+      ];
+    else if (maybeResErrsOrArgs) args = maybeResErrsOrArgs;
     else {
       if (!schema) throw new Error('The GraphQL schema is not provided');
 

src/utils.ts

@@ -4,7 +4,20 @@
  *
  */
 
+import type { GraphQLError } from 'graphql';
+
 /** @private */
 export function isObject(val: unknown): val is Record<PropertyKey, unknown> {
   return typeof val === 'object' && val !== null;
 }
+
+/** @private */
+export function areGraphQLErrors(obj: unknown): obj is GraphQLError[] {
+  return (
+    Array.isArray(obj) &&
+    // must be at least one error
+    obj.length > 0 &&
+    // error has at least a message
+    obj.every((ob) => 'message' in ob)
+  );
+}