semantic nullability proposal with single GraphQLSemanticNullable wrapper type

src/__tests__/starWarsIntrospection-test.ts

@@ -42,6 +42,7 @@ describe('Star Wars Introspection Tests', () => {
             { name: '__TypeKind' },
             { name: '__Field' },
             { name: '__InputValue' },
+            { name: '__TypeNullability' },
             { name: '__EnumValue' },
             { name: '__Directive' },
             { name: '__DirectiveLocation' },

src/execution/__tests__/executor-test.ts

@@ -263,6 +263,7 @@ describe('Execute: Handles basic execution tasks', () => {
       'rootValue',
       'operation',
       'variableValues',
+      'errorPropagation',
     );
 
     const operation = document.definitions[0];
@@ -275,6 +276,7 @@ describe('Execute: Handles basic execution tasks', () => {
       schema,
       rootValue,
       operation,
+      errorPropagation: true,
     });
 
     const field = operation.selectionSet.selections[0];

src/execution/__tests__/semantic-nullability-test.ts

@@ -0,0 +1,180 @@
+import { describe, it } from 'mocha';
+
+import { expectJSON } from '../../__testUtils__/expectJSON';
+
+import type { ObjMap } from '../../jsutils/ObjMap';
+
+import { parse } from '../../language/parser';
+
+import {
+  GraphQLNonNull,
+  GraphQLObjectType,
+  GraphQLSemanticNullable,
+} from '../../type/definition';
+import { GraphQLString } from '../../type/scalars';
+import { GraphQLSchema } from '../../type/schema';
+
+import { execute } from '../execute';
+
+describe('Execute: Handles Semantic Nullability', () => {
+  const DeepDataType = new GraphQLObjectType({
+    name: 'DeepDataType',
+    fields: {
+      f: { type: new GraphQLNonNull(GraphQLString) },
+    },
+  });
+
+  const DataType: GraphQLObjectType = new GraphQLObjectType({
+    name: 'DataType',
+    fields: () => ({
+      a: { type: new GraphQLSemanticNullable(GraphQLString) },
+      b: { type: GraphQLString },
+      c: { type: new GraphQLNonNull(GraphQLString) },
+      d: { type: DeepDataType },
+    }),
+  });
+
+  const schema = new GraphQLSchema({
+    useSemanticNullability: true,
+    query: DataType,
+  });
+
+  function executeWithSemanticNullability(
+    query: string,
+    rootValue: ObjMap<unknown>,
+  ) {
+    return execute({
+      schema,
+      document: parse(query),
+      rootValue,
+    });
+  }
+
+  it('SemanticNonNull throws error on null without error', async () => {
+    const data = {
+      b: () => null,
+    };
+
+    const query = `
+      query {
+        b
+      }
+    `;
+
+    const result = await executeWithSemanticNullability(query, data);
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        b: null,
+      },
+      errors: [
+        {
+          message:
+            'Cannot return null for semantic-non-nullable field DataType.b.',
+          path: ['b'],
+          locations: [{ line: 3, column: 9 }],
+        },
+      ],
+    });
+  });
+
+  it('SemanticNonNull succeeds on null with error', async () => {
+    const data = {
+      b: () => {
+        throw new Error('Something went wrong');
+      },
+    };
+
+    const query = `
+      query {
+        b
+      }
+    `;
+
+    const result = await executeWithSemanticNullability(query, data);
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        b: null,
+      },
+      errors: [
+        {
+          message: 'Something went wrong',
+          path: ['b'],
+          locations: [{ line: 3, column: 9 }],
+        },
+      ],
+    });
+  });
+
+  it('SemanticNonNull halts null propagation', async () => {
+    const data = {
+      d: () => ({
+        f: () => null,
+      }),
+    };
+
+    const query = `
+      query {
+        d {
+          f
+        }
+      }
+    `;
+
+    const result = await executeWithSemanticNullability(query, data);
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        d: null,
+      },
+      errors: [
+        {
+          message: 'Cannot return null for non-nullable field DeepDataType.f.',
+          path: ['d', 'f'],
+          locations: [{ line: 4, column: 11 }],
+        },
+      ],
+    });
+  });
+
+  it('SemanticNullable allows null values', async () => {
+    const data = {
+      a: () => null,
+    };
+
+    const query = `
+      query {
+        a
+      }
+    `;
+
+    const result = await executeWithSemanticNullability(query, data);
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        a: null,
+      },
+    });
+  });
+
+  it('SemanticNullable allows non-null values', async () => {
+    const data = {
+      a: () => 'Apple',
+    };
+
+    const query = `
+      query {
+        a
+      }
+    `;
+
+    const result = await executeWithSemanticNullability(query, data);
+
+    expectJSON(result).toDeepEqual({
+      data: {
+        a: 'Apple',
+      },
+    });
+  });
+});

src/execution/execute.ts

@@ -43,6 +43,7 @@ import {
   isListType,
   isNonNullType,
   isObjectType,
+  isSemanticNullableType,
 } from '../type/definition';
 import {
   SchemaMetaFieldDef,
@@ -115,6 +116,7 @@ export interface ExecutionContext {
   typeResolver: GraphQLTypeResolver<any, any>;
   subscribeFieldResolver: GraphQLFieldResolver<any, any>;
   errors: Array<GraphQLError>;
+  errorPropagation: boolean;
 }
 
 /**
@@ -152,6 +154,12 @@ export interface ExecutionArgs {
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
   subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  /**
+   * Set to `false` to disable error propagation. Experimental.
+   *
+   * @experimental
+   */
+  errorPropagation?: boolean;
 }
 
 /**
@@ -286,6 +294,7 @@ export function buildExecutionContext(
     fieldResolver,
     typeResolver,
     subscribeFieldResolver,
+    errorPropagation,
   } = args;
 
   let operation: OperationDefinitionNode | undefined;
@@ -347,6 +356,7 @@ export function buildExecutionContext(
     typeResolver: typeResolver ?? defaultTypeResolver,
     subscribeFieldResolver: subscribeFieldResolver ?? defaultFieldResolver,
     errors: [],
+    errorPropagation: errorPropagation ?? true,
   };
 }
 
@@ -585,6 +595,7 @@ export function buildResolveInfo(
     rootValue: exeContext.rootValue,
     operation: exeContext.operation,
     variableValues: exeContext.variableValues,
+    errorPropagation: exeContext.errorPropagation,
   };
 }
 
@@ -595,7 +606,7 @@ function handleFieldError(
 ): null {
   // If the field type is non-nullable, then it is resolved without any
   // protection from errors, however it still properly locates the error.
-  if (isNonNullType(returnType)) {
+  if (exeContext.errorPropagation && isNonNullType(returnType)) {
     throw error;
   }
 
@@ -639,78 +650,83 @@ function completeValue(
     throw result;
   }
 
-  // If field type is NonNull, complete for inner type, and throw field error
-  // if result is null.
+  let nonNull;
+  let semanticNull;
+  let nullableType;
   if (isNonNullType(returnType)) {
-    const completed = completeValue(
-      exeContext,
-      returnType.ofType,
-      fieldNodes,
-      info,
-      path,
-      result,
-    );
-    if (completed === null) {
-      throw new Error(
-        `Cannot return null for non-nullable field ${info.parentType.name}.${info.fieldName}.`,
-      );
-    }
-    return completed;
+    nonNull = true;
+    nullableType = returnType.ofType;
+  } else if (isSemanticNullableType(returnType)) {
+    semanticNull = true;
+    nullableType = returnType.ofType;
+  } else {
+    nullableType = returnType;
   }
 
-  // If result value is null or undefined then return null.
+  let completed;
   if (result == null) {
-    return null;
-  }
-
-  // If field type is List, complete each item in the list with the inner type
-  if (isListType(returnType)) {
-    return completeListValue(
+    // If result value is null or undefined then return null.
+    completed = null;
+  } else if (isListType(nullableType)) {
+    // If field type is List, complete each item in the list with the inner type
+    completed = completeListValue(
       exeContext,
-      returnType,
+      nullableType,
       fieldNodes,
       info,
       path,
       result,
     );
-  }
-
-  // If field type is a leaf type, Scalar or Enum, serialize to a valid value,
-  // returning null if serialization is not possible.
-  if (isLeafType(returnType)) {
-    return completeLeafValue(returnType, result);
-  }
-
-  // If field type is an abstract type, Interface or Union, determine the
-  // runtime Object type and complete for that type.
-  if (isAbstractType(returnType)) {
-    return completeAbstractValue(
+  } else if (isLeafType(nullableType)) {
+    // If field type is a leaf type, Scalar or Enum, serialize to a valid value,
+    // returning null if serialization is not possible.
+    completed = completeLeafValue(nullableType, result);
+  } else if (isAbstractType(nullableType)) {
+    // If field type is an abstract type, Interface or Union, determine the
+    // runtime Object type and complete for that type.
+    completed = completeAbstractValue(
       exeContext,
-      returnType,
+      nullableType,
       fieldNodes,
       info,
       path,
       result,
     );
-  }
-
-  // If field type is Object, execute and complete all sub-selections.
-  if (isObjectType(returnType)) {
-    return completeObjectValue(
+  } else if (isObjectType(nullableType)) {
+    // If field type is Object, execute and complete all sub-selections.
+    completed = completeObjectValue(
       exeContext,
-      returnType,
+      nullableType,
       fieldNodes,
       info,
       path,
       result,
     );
+  } else {
+    /* c8 ignore next 6 */
+    // Not reachable, all possible output types have been considered.
+    invariant(
+      false,
+      'Cannot complete value of unexpected output type: ' +
+        inspect(nullableType),
+    );
   }
-  /* c8 ignore next 6 */
-  // Not reachable, all possible output types have been considered.
-  invariant(
-    false,
-    'Cannot complete value of unexpected output type: ' + inspect(returnType),
-  );
+
+  if (completed === null) {
+    if (nonNull) {
+      throw new Error(
+        `Cannot return null for non-nullable field ${info.parentType.name}.${info.fieldName}.`,
+      );
+    }
+
+    if (!semanticNull && exeContext.schema.usingSemanticNullability) {
+      throw new Error(
+        `Cannot return null for semantic-non-nullable field ${info.parentType.name}.${info.fieldName}.`,
+      );
+    }
+  }
+
+  return completed;
 }
 
 /**