Add 'TypedQueryDocumentNode' TS type (graphql#2749)

integrationTests/ts/index.ts

@@ -1,6 +1,7 @@
+import { parse } from 'graphql/language';
 import { GraphQLString, GraphQLSchema, GraphQLObjectType } from 'graphql/type';
-import { ExecutionResult } from 'graphql/execution';
-import { graphqlSync } from 'graphql';
+import { ExecutionResult, execute } from 'graphql/execution';
+import { TypedQueryDocumentNode, graphqlSync } from 'graphql';
 
 interface SomeExtension {
   number: number;
@@ -69,3 +70,28 @@ const result: ExecutionResult = graphqlSync({
   `,
   variableValues: { who: 'Dolly' },
 });
+
+// Tests for TS specific TypedQueryDocumentNode type
+const queryDocument = parse(`
+  query helloWho($who: String){
+    test(who: $who)
+  }
+`);
+
+type ResponseData = { test: string };
+const typedQueryDocument = queryDocument as TypedQueryDocumentNode<
+  ResponseData,
+  {}
+>;
+
+// Supports conversion to DocumentNode
+execute({ schema, document: typedQueryDocument });
+
+function wrappedExecute<T>(document: TypedQueryDocumentNode<T>) {
+  return execute({ schema, document }) as ExecutionResult<T>;
+}
+
+const { data } = wrappedExecute(typedQueryDocument);
+if (data != null) {
+  const typedData: ResponseData = data;
+}

src/index.d.ts

@@ -461,4 +461,5 @@ export {
   BuildSchemaOptions,
   BreakingChange,
   DangerousChange,
+  TypedQueryDocumentNode,
 } from './utilities/index';

src/utilities/index.d.ts

@@ -112,5 +112,8 @@ export {
   DangerousChange,
 } from './findBreakingChanges';
 
+// Wrapper type that contains DocumentNode and types that can be deduced from it.
+export { TypedQueryDocumentNode } from './typedQueryDocumentNode';
+
 // @deprecated: Report all deprecated usage within a GraphQL document.
 export { findDeprecatedUsages } from './findDeprecatedUsages';

src/utilities/typedQueryDocumentNode.d.ts

@@ -0,0 +1,14 @@
+import { DocumentNode, ExecutableDefinitionNode } from '../language/ast';
+
+/**
+ * Wrapper type that contains DocumentNode and types that can be deduced from it.
+ */
+interface TypedQueryDocumentNode<
+  TResponseData = Record<string, any>,
+  TRequestVariables = Record<string, any>
+> extends DocumentNode {
+  readonly definitions: ReadonlyArray<ExecutableDefinitionNode>;
+  // FIXME: remove once TS implements proper way to enforce nominal typing
+  readonly __enforceStructuralTypingOnResponseDataType?: TResponseData;
+  readonly __enforceStructuralTypingOnRequestVariablesType?: TRequestVariables;
+}