feat: Implement support for @_optional and @_required on fields (#32

)

.changeset/fair-pillows-repair.md

@@ -0,0 +1,7 @@
+---
+'gql.tada': minor
+---
+
+Support `@_optional` and `@_required` directives on fields overriding the field types.
+When used, `@_required` can turn a nullable type into a non-nullable, and `@_optional`
+can turn non-nullable fields into nullable ones. (See [“Client-Controlled Nullability” in Graphcache for an example of a client implementing this.](https://formidable.com/open-source/urql/docs/graphcache/local-directives/#client-controlled-nullability))

src/__tests__/selection.test-d.ts

@@ -113,6 +113,29 @@ test('infers optional properties for @skip/@include', () => {
   expectTypeOf<expected>().toEqualTypeOf<actual>();
 });
 
+test('infers nullable field types for @required/@optional', () => {
+  type query = parseDocument</* GraphQL */ `
+    query {
+      todos {
+        id @optional
+        complete @required
+      }
+    }
+  `>;
+
+  type actual = getDocumentType<query, schema>;
+  type expected = {
+    todos:
+      | ({
+          id: string | number | null;
+          complete: boolean;
+        } | null)[]
+      | null;
+  };
+
+  expectTypeOf<expected>().toEqualTypeOf<actual>();
+});
+
 test('infers optional fragment for @defer', () => {
   type query = parseDocument</* GraphQL */ `
     query {

src/selection.ts

@@ -52,9 +52,25 @@ type unwrapType<
   SelectionSet extends { kind: Kind.SELECTION_SET } | undefined,
   Introspection extends IntrospectionLikeType,
   Fragments extends { [name: string]: any },
+  TypeDirective = void,
 > = Type extends IntrospectionNonNullTypeRef
-  ? _unwrapTypeRec<Type['ofType'], SelectionSet, Introspection, Fragments>
-  : null | _unwrapTypeRec<Type, SelectionSet, Introspection, Fragments>;
+  ? TypeDirective extends 'optional'
+    ? null | _unwrapTypeRec<Type['ofType'], SelectionSet, Introspection, Fragments>
+    : _unwrapTypeRec<Type['ofType'], SelectionSet, Introspection, Fragments>
+  : TypeDirective extends 'required'
+    ? _unwrapTypeRec<Type, SelectionSet, Introspection, Fragments>
+    : null | _unwrapTypeRec<Type, SelectionSet, Introspection, Fragments>;
+
+type getTypeDirective<Directives extends readonly unknown[] | undefined> =
+  Directives extends readonly [infer Directive, ...infer Rest]
+    ? Directive extends { kind: Kind.DIRECTIVE; name: any }
+      ? Directive['name']['value'] extends 'required' | '_required'
+        ? 'required'
+        : Directive['name']['value'] extends 'optional' | '_optional'
+          ? 'optional'
+          : getTypeDirective<Rest>
+      : getTypeDirective<Rest>
+    : void;
 
 type isOptionalRec<Directives extends readonly unknown[] | undefined> =
   Directives extends readonly [infer Directive, ...infer Rest]
@@ -146,7 +162,8 @@ type _getPossibleTypeSelectionRec<
                     Type['fields'][Node['name']['value']]['type'],
                     Node['selectionSet'],
                     Introspection,
-                    Fragments
+                    Fragments,
+                    getTypeDirective<Node['directives']>
                   >;
             }
           : {
@@ -156,7 +173,8 @@ type _getPossibleTypeSelectionRec<
                     Type['fields'][Node['name']['value']]['type'],
                     Node['selectionSet'],
                     Introspection,
-                    Fragments
+                    Fragments,
+                    getTypeDirective<Node['directives']>
                   >;
             }
         : {}) &