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)
+ );
+}