Deprecate 'formatError' and added 'GraphQLError.toJSON' instead (#3259)

src/error/GraphQLError.ts

@@ -215,12 +215,64 @@ export class GraphQLError extends Error {
     return output;
   }
 
-  // FIXME: workaround to not break chai comparisons, should be remove in v16
+  toJSON(): GraphQLFormattedError {
+    type WritableFormattedError = {
+      -readonly [P in keyof GraphQLFormattedError]: GraphQLFormattedError[P];
+    };
+
+    const formattedError: WritableFormattedError = {
+      message: this.message,
+    };
+
+    if (this.locations != null) {
+      formattedError.locations = this.locations;
+    }
+
+    if (this.path != null) {
+      formattedError.path = this.path;
+    }
+
+    if (this.extensions != null) {
+      formattedError.extensions = this.extensions;
+    }
+
+    return formattedError;
+  }
+
   get [Symbol.toStringTag](): string {
     return 'Object';
   }
 }
 
+/**
+ * See: https://spec.graphql.org/draft/#sec-Errors
+ */
+export interface GraphQLFormattedError {
+  /**
+   * A short, human-readable summary of the problem that **SHOULD NOT** change
+   * from occurrence to occurrence of the problem, except for purposes of
+   * localization.
+   */
+  readonly message: string;
+  /**
+   * If an error can be associated to a particular point in the requested
+   * GraphQL document, it should contain a list of locations.
+   */
+  readonly locations?: ReadonlyArray<SourceLocation>;
+  /**
+   * If an error can be associated to a particular field in the GraphQL result,
+   * it _must_ contain an entry with the key `path` that details the path of
+   * the response field which experienced the error. This allows clients to
+   * identify whether a null result is intentional or caused by a runtime error.
+   */
+  readonly path?: ReadonlyArray<string | number>;
+  /**
+   * Reserved for implementors to extend the protocol however they see fit,
+   * and hence there are no additional restrictions on its contents.
+   */
+  readonly extensions?: { [key: string]: unknown };
+}
+
 /**
  * Prints a GraphQLError to a string, representing useful location information
  * about the error's position in the source.
@@ -230,3 +282,13 @@ export class GraphQLError extends Error {
 export function printError(error: GraphQLError): string {
   return error.toString();
 }
+
+/**
+ * Given a GraphQLError, format it according to the rules described by the
+ * Response Format, Errors section of the GraphQL Specification.
+ *
+ * @deprecated Please use `error.toString` instead. Will be removed in v17
+ */
+export function formatError(error: GraphQLError): GraphQLFormattedError {
+  return error.toJSON();
+}

src/error/__tests__/GraphQLError-test.ts

@@ -9,7 +9,7 @@ import { Kind } from '../../language/kinds';
 import { parse } from '../../language/parser';
 import { Source } from '../../language/source';
 
-import { GraphQLError, printError } from '../GraphQLError';
+import { GraphQLError, printError, formatError } from '../GraphQLError';
 
 const source = new Source(dedent`
   {
@@ -204,3 +204,37 @@ describe('toString', () => {
     `);
   });
 });
+
+describe('toJSON', () => {
+  it('Deprecated: format an error using formatError', () => {
+    const error = new GraphQLError('Example Error');
+    expect(formatError(error)).to.deep.equal({
+      message: 'Example Error',
+    });
+  });
+
+  it('includes path', () => {
+    const error = new GraphQLError('msg', null, null, null, [
+      'path',
+      3,
+      'to',
+      'field',
+    ]);
+
+    expect(error.toJSON()).to.deep.equal({
+      message: 'msg',
+      path: ['path', 3, 'to', 'field'],
+    });
+  });
+
+  it('includes extension fields', () => {
+    const error = new GraphQLError('msg', null, null, null, null, null, {
+      foo: 'bar',
+    });
+
+    expect(error.toJSON()).to.deep.equal({
+      message: 'msg',
+      extensions: { foo: 'bar' },
+    });
+  });
+});

src/error/index.ts

@@ -1,8 +1,6 @@
-export { GraphQLError, printError } from './GraphQLError';
+export { GraphQLError, printError, formatError } from './GraphQLError';
+export type { GraphQLFormattedError } from './GraphQLError';
 
 export { syntaxError } from './syntaxError';
 
 export { locatedError } from './locatedError';
-
-export { formatError } from './formatError';
-export type { GraphQLFormattedError } from './formatError';

src/execution/execute.ts

@@ -13,7 +13,7 @@ import { promiseForObject } from '../jsutils/promiseForObject';
 import { addPath, pathToArray } from '../jsutils/Path';
 import { isIterableObject } from '../jsutils/isIterableObject';
 
-import type { GraphQLFormattedError } from '../error/formatError';
+import type { GraphQLFormattedError } from '../error/GraphQLError';
 import { GraphQLError } from '../error/GraphQLError';
 import { locatedError } from '../error/locatedError';