Advantage common convention for naming root types. (#470)

This is a result of a conversation I had with @lacker that we should provide a stronger opinion on what to name the root types, and then advantage that opinion. Here's the result of that:

If you use the type names `Query` and `Mutation` for your root types, then printing the schema or parsing a schema IDL can omit the `schema { query: Query, mutation: Mutation }` boilerplate. If your root type names are anything other than these, then you have to include it.

There doesn't seem to be a significant downsite to this except for the relative complication of understanding why sometimes a `schema {}` description is included and sometimes it isn't.

Author: leebyron

src/utilities/__tests__/buildASTSchema-test.js

@@ -457,10 +457,6 @@ type Subscription {
 
   it('Unreferenced type implementing referenced interface', () => {
     const body = `
-schema {
-  query: Query
-}
-
 type Concrete implements Iface {
   key: String
 }
@@ -479,10 +475,6 @@ type Query {
 
   it('Unreferenced type implementing referenced union', () => {
     const body = `
-schema {
-  query: Query
-}
-
 type Concrete {
   key: String
 }
@@ -499,10 +491,6 @@ union Union = Concrete
 
   it('Supports @deprecated', () => {
     const body = `
-schema {
-  query: Query
-}
-
 enum MyEnum {
   VALUE
   OLD_VALUE @deprecated
@@ -522,15 +510,16 @@ type Query {
 
 describe('Failures', () => {
 
-  it('Requires a schema definition', () => {
+  it('Requires a schema definition or Query type', () => {
     const body = `
 type Hello {
   bar: Bar
 }
 `;
     const doc = parse(body);
-    expect(() => buildASTSchema(doc))
-      .to.throw('Must provide a schema definition.');
+    expect(() => buildASTSchema(doc)).to.throw(
+      'Must provide schema definition with query type or a type named Query.'
+    );
   });
 
   it('Allows only a single schema definition', () => {
@@ -563,8 +552,9 @@ type Hello {
 }
 `;
     const doc = parse(body);
-    expect(() => buildASTSchema(doc))
-      .to.throw('Must provide schema definition with query type.');
+    expect(() => buildASTSchema(doc)).to.throw(
+      'Must provide schema definition with query type or a type named Query.'
+    );
   });
 
   it('Allows only a single query type', () => {

src/utilities/__tests__/extendSchema-test.js

@@ -156,11 +156,7 @@ describe('extendSchema', () => {
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -209,11 +205,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -271,11 +263,7 @@ type Unused {
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -330,11 +318,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -384,11 +368,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -464,11 +444,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -547,11 +523,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -619,11 +591,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(testSchema);
     expect(printSchema(testSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-}
-
-type Bar implements SomeInterface {
+`type Bar implements SomeInterface {
   name: String
   some: SomeInterface
   foo: Foo
@@ -709,13 +677,7 @@ union SomeUnion = Foo | Biz
     expect(extendedSchema).to.not.equal(mutationSchema);
     expect(printSchema(mutationSchema)).to.equal(originalPrint);
     expect(printSchema(extendedSchema)).to.equal(
-`schema {
-  query: Query
-  mutation: Mutation
-  subscription: Subscription
-}
-
-type Mutation {
+`type Mutation {
   mutationField: String
   newMutationField: Int
 }

src/utilities/buildASTSchema.js

@@ -10,7 +10,6 @@
 
 import find from '../jsutils/find';
 import invariant from '../jsutils/invariant';
-import keyMap from '../jsutils/keyMap';
 import keyValMap from '../jsutils/keyValMap';
 import { valueFromAST } from './valueFromAST';
 import { TokenKind } from '../language/lexer';
@@ -128,6 +127,9 @@ function getNamedTypeAST(typeAST: Type): NamedType {
  * This takes the ast of a schema document produced by the parse function in
  * src/language/parser.js.
  *
+ * If no schema definition is provided, then it will look for types named Query
+ * and Mutation.
+ *
  * Given that AST it constructs a GraphQLSchema. As constructed
  * they are not particularly useful for non-introspection queries
  * since they have no resolve methods.
@@ -140,6 +142,7 @@ export function buildASTSchema(ast: Document): GraphQLSchema {
   let schemaDef: ?SchemaDefinition;
 
   const typeDefs: Array<TypeDefinition> = [];
+  const astMap: {[name: string]: TypeDefinition} = Object.create(null);
   const directiveDefs: Array<DirectiveDefinition> = [];
   for (let i = 0; i < ast.definitions.length; i++) {
     const d = ast.definitions[i];
@@ -157,63 +160,67 @@ export function buildASTSchema(ast: Document): GraphQLSchema {
       case UNION_TYPE_DEFINITION:
       case INPUT_OBJECT_TYPE_DEFINITION:
         typeDefs.push(d);
+        astMap[d.name.value] = d;
         break;
       case DIRECTIVE_DEFINITION:
         directiveDefs.push(d);
         break;
     }
   }
 
-  if (!schemaDef) {
-    throw new Error('Must provide a schema definition.');
-  }
-
   let queryTypeName;
   let mutationTypeName;
   let subscriptionTypeName;
-  schemaDef.operationTypes.forEach(operationType => {
-    const typeName = operationType.type.name.value;
-    if (operationType.operation === 'query') {
-      if (queryTypeName) {
-        throw new Error('Must provide only one query type in schema.');
-      }
-      queryTypeName = typeName;
-    } else if (operationType.operation === 'mutation') {
-      if (mutationTypeName) {
-        throw new Error('Must provide only one mutation type in schema.');
-      }
-      mutationTypeName = typeName;
-    } else if (operationType.operation === 'subscription') {
-      if (subscriptionTypeName) {
-        throw new Error('Must provide only one subscription type in schema.');
+  if (schemaDef) {
+    schemaDef.operationTypes.forEach(operationType => {
+      const typeName = operationType.type.name.value;
+      if (operationType.operation === 'query') {
+        if (queryTypeName) {
+          throw new Error('Must provide only one query type in schema.');
+        }
+        if (!astMap[typeName]) {
+          throw new Error(
+            `Specified query type "${typeName}" not found in document.`
+          );
+        }
+        queryTypeName = typeName;
+      } else if (operationType.operation === 'mutation') {
+        if (mutationTypeName) {
+          throw new Error('Must provide only one mutation type in schema.');
+        }
+        if (!astMap[typeName]) {
+          throw new Error(
+            `Specified mutation type "${typeName}" not found in document.`
+          );
+        }
+        mutationTypeName = typeName;
+      } else if (operationType.operation === 'subscription') {
+        if (subscriptionTypeName) {
+          throw new Error('Must provide only one subscription type in schema.');
+        }
+        if (!astMap[typeName]) {
+          throw new Error(
+            `Specified subscription type "${typeName}" not found in document.`
+          );
+        }
+        subscriptionTypeName = typeName;
       }
-      subscriptionTypeName = typeName;
+    });
+  } else {
+    if (astMap.Query) {
+      queryTypeName = 'Query';
+    }
+    if (astMap.Mutation) {
+      mutationTypeName = 'Mutation';
+    }
+    if (astMap.Subscription) {
+      subscriptionTypeName = 'Subscription';
     }
-  });
-
-  if (!queryTypeName) {
-    throw new Error('Must provide schema definition with query type.');
-  }
-
-  const astMap: {[name: string]: TypeDefinition} =
-    keyMap(typeDefs, d => d.name.value);
-
-  if (!astMap[queryTypeName]) {
-    throw new Error(
-      `Specified query type "${queryTypeName}" not found in document.`
-    );
-  }
-
-  if (mutationTypeName && !astMap[mutationTypeName]) {
-    throw new Error(
-      `Specified mutation type "${mutationTypeName}" not found in document.`
-    );
   }
 
-  if (subscriptionTypeName && !astMap[subscriptionTypeName]) {
+  if (!queryTypeName) {
     throw new Error(
-      `Specified subscription type "${
-        subscriptionTypeName}" not found in document.`
+      'Must provide schema definition with query type or a type named Query.'
     );
   }
 

src/utilities/schemaPrinter.js

@@ -72,13 +72,18 @@ function printFilteredSchema(
     .filter(typeFilter)
     .sort((name1, name2) => name1.localeCompare(name2))
     .map(typeName => typeMap[typeName]);
+
   return [ printSchemaDefinition(schema) ].concat(
     directives.map(printDirective),
     types.map(printType)
-  ).join('\n\n') + '\n';
+  ).filter(Boolean).join('\n\n') + '\n';
 }
 
-function printSchemaDefinition(schema: GraphQLSchema): string {
+function printSchemaDefinition(schema: GraphQLSchema): ?string {
+  if (isSchemaOfCommonNames(schema)) {
+    return;
+  }
+
   const operationTypes = [];
 
   const queryType = schema.getQueryType();
@@ -99,6 +104,37 @@ function printSchemaDefinition(schema: GraphQLSchema): string {
   return `schema {\n${operationTypes.join('\n')}\n}`;
 }
 
+/**
+ * GraphQL schema define root types for each type of operation. These types are
+ * the same as any other type and can be named in any manner, however there is
+ * a common naming convention:
+ *
+ *   schema {
+ *     query: Query
+ *     mutation: Mutation
+ *   }
+ *
+ * When using this naming convention, the schema description can be omitted.
+ */
+function isSchemaOfCommonNames(schema: GraphQLSchema): boolean {
+  const queryType = schema.getQueryType();
+  if (queryType && queryType.name !== 'Query') {
+    return false;
+  }
+
+  const mutationType = schema.getMutationType();
+  if (mutationType && mutationType.name !== 'Mutation') {
+    return false;
+  }
+
+  const subscriptionType = schema.getSubscriptionType();
+  if (subscriptionType && subscriptionType.name !== 'Subscription') {
+    return false;
+  }
+
+  return true;
+}
+
 function printType(type: GraphQLType): string {
   if (type instanceof GraphQLScalarType) {
     return printScalar(type);