Support `@required` and `@optional` directives

[aaronadamsCA]

Is your feature request related to a problem? Please describe.

I'd like to add built-in support for any method that could generate the following TypeScript types from a schema for use by a client:

export type MyInput = {
  a?: InputMaybe<Scalars['String']['input']>;
  b?: Scalars['String']['input'];
  c: InputMaybe<Scalars['String']['input']>;
  d: Scalars['String']['input'];
};

Describe the solution you'd like

The best proposal I've seen uses @required and @optional input directives, as described in graphql/graphql-spec#872:

"""
This input is optional, not nullable.
If the client insists on sending an explicit null value, the behavior is undefined.
"""
directive @optional on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

"""
This input is nullable, not optional.
If the client insists on omitting the input value, the behavior is undefined.
"""
directive @required on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

input MyInput {
  a: String
  b: String @optional
  c: String @required
  d: String!
}

This addresses a very common concern, and since it only uses directives, it's completely forward- and backward-compatible and doesn't require any changes to the GraphQL spec.

My suggestion is to support the above with a new TypeScript plugin option:

export default {
  generates: {
    "path/to/file": {
      config: {
        directiveArgumentAndInputFieldNarrowing: {
          nonNullable: "optional",
          nonOptional: "required",
        },
      },
    },
  },
} satisfies CodegenConfig;

Describe alternatives you've considered

No response

Any additional important details?

If we could agree on the right approach, I'd be happy to try implementing this myself.

[eddeee888]

Hi @aaronadamsCA,

Usually we don't support non-spec standards until it is championed, researched and implemented into the core lib. 🙂
Otherwise, we'd end up with a lot of options that could cause confusion to other users.

[aaronadamsCA]

That makes perfect sense! That's why I made this a very general feature request; I just used that proposal to explain my specific use case. After all, you or someone else might have a better way to solve it—maybe even within the existing config APIs.

I modelled my suggestion on the existing directiveArgumentAndInputFieldMappings option, which lets a directive change an input field's scalar:

export default {
  generates: {
    "path/to/file": {
      config: {
        directiveArgumentAndInputFieldMappings: {
          AsNumber: 'number',
          AsComplex: './my-models#Complex',
          }
      },
    },
  },
} satisfies CodegenConfig;

So my suggestion is a very similar option to let a directive change an input field's (key) optionality or (value) nullability.

[eddeee888]

Interesting, TIL about directiveArgumentAndInputFieldMappings 👀 (It was created before I onboarded the Codegen team)

There are a few things about how @optional and @required would work for client vs server use cases - as Codegen can be used for both:

1. For client use case, would this only change the type? For example, if @optional is used, would users be able to force through a null value using something like as any?
2. For server use case, would this only change the type, or are there runtime validation happening in either the directive/the resolvers?