Semantic nullability document directive

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,220 @@
+import { expect } from 'chai';
+import { describe, it } from 'mocha';
+
+import { GraphQLError } from '../../error/GraphQLError';
+
+import type { ExecutableDefinitionNode, FieldNode } from '../../language/ast';
+import { parse } from '../../language/parser';
+
+import {
+  GraphQLNonNull,
+  GraphQLObjectType,
+  GraphQLSemanticNonNull,
+  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: new GraphQLSemanticNonNull(GraphQLString) },
+      c: { type: new GraphQLNonNull(GraphQLString) },
+      d: { type: new GraphQLSemanticNonNull(DeepDataType) },
+    }),
+  });
+
+  it('SemanticNonNull throws error on null without error', async () => {
+    const data = {
+      a: () => 'Apple',
+      b: () => null,
+      c: () => 'Cookie',
+    };
+
+    const document = parse(`
+        query {
+          b
+        }
+      `);
+
+    const result = await execute({
+      schema: new GraphQLSchema({ query: DataType }),
+      document,
+      rootValue: data,
+    });
+
+    const executable = document.definitions?.values().next()
+      .value as ExecutableDefinitionNode;
+    const selectionSet = executable.selectionSet.selections
+      .values()
+      .next().value;
+
+    expect(result).to.deep.equal({
+      data: {
+        b: null,
+      },
+      errors: [
+        new GraphQLError(
+          'Cannot return null for semantic-non-nullable field DataType.b.',
+          {
+            nodes: selectionSet,
+            path: ['b'],
+          },
+        ),
+      ],
+    });
+  });
+
+  it('SemanticNonNull succeeds on null with error', async () => {
+    const data = {
+      a: () => 'Apple',
+      b: () => {
+        throw new Error('Something went wrong');
+      },
+      c: () => 'Cookie',
+    };
+
+    const document = parse(`
+        query {
+          b
+        }
+      `);
+
+    const executable = document.definitions?.values().next()
+      .value as ExecutableDefinitionNode;
+    const selectionSet = executable.selectionSet.selections
+      .values()
+      .next().value;
+
+    const result = await execute({
+      schema: new GraphQLSchema({ query: DataType }),
+      document,
+      rootValue: data,
+    });
+
+    expect(result).to.deep.equal({
+      data: {
+        b: null,
+      },
+      errors: [
+        new GraphQLError('Something went wrong', {
+          nodes: selectionSet,
+          path: ['b'],
+        }),
+      ],
+    });
+  });
+
+  it('SemanticNonNull halts null propagation', async () => {
+    const deepData = {
+      f: () => null,
+    };
+
+    const data = {
+      a: () => 'Apple',
+      b: () => null,
+      c: () => 'Cookie',
+      d: () => deepData,
+    };
+
+    const document = parse(`
+        query {
+          d {
+            f
+          }
+        }
+      `);
+
+    const result = await execute({
+      schema: new GraphQLSchema({ query: DataType }),
+      document,
+      rootValue: data,
+    });
+
+    const executable = document.definitions?.values().next()
+      .value as ExecutableDefinitionNode;
+    const dSelectionSet = executable.selectionSet.selections.values().next()
+      .value as FieldNode;
+    const fSelectionSet = dSelectionSet.selectionSet?.selections
+      .values()
+      .next().value;
+
+    expect(result).to.deep.equal({
+      data: {
+        d: null,
+      },
+      errors: [
+        new GraphQLError(
+          'Cannot return null for non-nullable field DeepDataType.f.',
+          {
+            nodes: fSelectionSet,
+            path: ['d', 'f'],
+          },
+        ),
+      ],
+    });
+  });
+
+  it('SemanticNullable allows null values', async () => {
+    const data = {
+      a: () => null,
+      b: () => null,
+      c: () => 'Cookie',
+    };
+
+    const document = parse(`
+        query {
+          a
+        }
+      `);
+
+    const result = await execute({
+      schema: new GraphQLSchema({ query: DataType }),
+      document,
+      rootValue: data,
+    });
+
+    expect(result).to.deep.equal({
+      data: {
+        a: null,
+      },
+    });
+  });
+
+  it('SemanticNullable allows non-null values', async () => {
+    const data = {
+      a: () => 'Apple',
+      b: () => null,
+      c: () => 'Cookie',
+    };
+
+    const document = parse(`
+        query {
+          a
+        }
+      `);
+
+    const result = await execute({
+      schema: new GraphQLSchema({ query: DataType }),
+      document,
+      rootValue: data,
+    });
+
+    expect(result).to.deep.equal({
+      data: {
+        a: 'Apple',
+      },
+    });
+  });
+});

src/execution/execute.ts

@@ -43,6 +43,8 @@ import {
   isListType,
   isNonNullType,
   isObjectType,
+  isSemanticNonNullType,
+  isSemanticNullableType,
 } from '../type/definition';
 import {
   SchemaMetaFieldDef,
@@ -115,6 +117,7 @@ export interface ExecutionContext {
   typeResolver: GraphQLTypeResolver<any, any>;
   subscribeFieldResolver: GraphQLFieldResolver<any, any>;
   errors: Array<GraphQLError>;
+  errorPropagation: boolean;
 }
 
 /**
@@ -152,6 +155,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 +295,7 @@ export function buildExecutionContext(
     fieldResolver,
     typeResolver,
     subscribeFieldResolver,
+    errorPropagation,
   } = args;
 
   let operation: OperationDefinitionNode | undefined;
@@ -347,6 +357,7 @@ export function buildExecutionContext(
     typeResolver: typeResolver ?? defaultTypeResolver,
     subscribeFieldResolver: subscribeFieldResolver ?? defaultFieldResolver,
     errors: [],
+    errorPropagation: errorPropagation ?? true,
   };
 }
 
@@ -585,6 +596,7 @@ export function buildResolveInfo(
     rootValue: exeContext.rootValue,
     operation: exeContext.operation,
     variableValues: exeContext.variableValues,
+    errorPropagation: exeContext.errorPropagation,
   };
 }
 
@@ -595,7 +607,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;
   }
 
@@ -658,6 +670,37 @@ function completeValue(
     return completed;
   }
 
+  // If field type is SemanticNonNull, complete for inner type, and throw field error
+  // if result is null and an error doesn't exist.
+  if (isSemanticNonNullType(returnType)) {
+    const completed = completeValue(
+      exeContext,
+      returnType.ofType,
+      fieldNodes,
+      info,
+      path,
+      result,
+    );
+    if (completed === null) {
+      throw new Error(
+        `Cannot return null for semantic-non-nullable field ${info.parentType.name}.${info.fieldName}.`,
+      );
+    }
+    return completed;
+  }
+
+  // If field type is SemanticNullable, complete for inner type
+  if (isSemanticNullableType(returnType)) {
+    return completeValue(
+      exeContext,
+      returnType.ofType,
+      fieldNodes,
+      info,
+      path,
+      result,
+    );
+  }
+
   // If result value is null or undefined then return null.
   if (result == null) {
     return null;

src/graphql.ts

@@ -66,6 +66,12 @@ export interface GraphQLArgs {
   operationName?: Maybe<string>;
   fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
   typeResolver?: Maybe<GraphQLTypeResolver<any, any>>;
+  /**
+   * Set to `false` to disable error propagation. Experimental.
+   *
+   * @experimental
+   */
+  errorPropagation?: boolean;
 }
 
 export function graphql(args: GraphQLArgs): Promise<ExecutionResult> {
@@ -106,6 +112,7 @@ function graphqlImpl(args: GraphQLArgs): PromiseOrValue<ExecutionResult> {
     operationName,
     fieldResolver,
     typeResolver,
+    errorPropagation,
   } = args;
 
   // Validate Schema
@@ -138,5 +145,6 @@ function graphqlImpl(args: GraphQLArgs): PromiseOrValue<ExecutionResult> {
     operationName,
     fieldResolver,
     typeResolver,
+    errorPropagation,
   });
 }