Is it possible to have directives that augment the generated types when using the typescript plugin?

[jkepps]

Hi everyone,

I'm trying to find the best practice for generating precise TypeScript types for our input fields, as we have two distinct and conflicting use cases: filtering and mutations.

1. The Filtering Use Case (Optional but Non-Nullable)

For query inputs used in filtering, we want fields to be optional, but if a value is provided, it should never be null. For example, a filter condition like { sku: null } isn't compatible for certain fields for the query input for our ORM. The desired behavior is for the field to either be a valid value or be omitted entirely.

I would love to enforce this at the type level. The ideal approach (I think) would be to use a directive in the schema:

directive @nonNullable on INPUT_FIELD_DEFINITION

input ProductFilterInput {
  # If provided, sku must be a string, not null.
  sku: String @nonNullable

  # If provided, inStock must be a boolean, not null.
  inStock: Boolean @nonNullable
}

This would ideally generate a strict TypeScript type where null is not permitted:

// Desired generated type for filtering
export type ProductFilterInput = {
  sku?: string;
  inStock?: boolean;
};

2. The Mutation Use Case (Optional and Nullable)

At the same time, we need to preserve the standard behavior for our mutation inputs. In mutations, sending null is a critical feature that allows clients to clear or unset a value in the database.

input UpdateUserInput {
  # This field can be explicitly set to null to clear the user's bio.
  bio: String
}

This requires the default, less strict generated type:

// Desired generated type for mutations
export type UpdateUserInput = {
  bio?: string | null;
};

The Core Problem

Because of these two conflicting requirements, updating the global configuration inputMaybeValue: 'T | undefined' is not a feasible solution. It would correctly handle our filtering inputs but would break the ability for our mutation inputs to accept null.

This leads me to believe a directive-based approach is the correct path, as it provides the field-level granularity we need.

My question is: Is there a current configuration option within the @graphql-codegen/typescript plugin that allows for this kind of directive-based type augmentation? Specifically, is there a way to map my @nonNullable directive to a {T} | undefined type for any field it's applied to?

If a direct configuration for this doesn't exist, I'd be very interested to understand if this is an intentional design choice. Is the recommended path to implement a more complex solution with custom mappers, or are there other patterns for solving this common problem?

Thanks for any guidance or best practices you can share!

[eddeee888]

Hi @jkepps , thanks for bringing up this interesting use case.

TLDR; we currently don't have a way to change types based on custom directives (with some exceptions).

For scenario 1, I'm curious if you'd do a check in your server to handle null before passing it on to the ORM?

Enforcing input type may work for one client, but there are some scenarios to consider:

• if the list of your client grows, each client needs to set up the same codegen config.
• a random client may still send null. So it still may be safer for the server to handle null anyways. To me, this would be the best practice

Scenario 2 seems like the typical nullability use case 👍

---

If a direct configuration for this doesn't exist, I'd be very interested to understand if this is an intentional design choice

To keep Codegen light and maintainable, we generally implement type based on GraphQL spec, or certain directives such as @semanticNonNull (to support upcoming nullability changes) and Apollo's @unmask (to support the migration workflow for lots of users). In this instance, I wonder if @nonNullable is something that's commonly used in the wider community, or specific to your use case?

Slight tangent is about the naming of @nonNullable directive: I usually refer fields with ! as "non-nullable" i.e. must not be undefined or null 🙂

[jkepps]

Thanks for the reply @eddeee888!

a random client may still send null. So it still may be safer for the server to handle null anyways. To me, this would be the best practice

Yes I had this thought as well and I think its the most compelling argument against augmenting the types in a way that doesn't actually reflect the reality of the graphql spec and what is still going to be allowed to be sent in the request. A directive would enable you to augment the way a null value is handled (i.e. throwing an error in the directive implementation logic), but I can still see why explicitly going against the graphql spec like that may not be ideal.

That leads me to wonder though, I can see a plausible use case in a more general case where you are using a directive that may impact the type of the field. Not necessarily for null or optional values, but possibly in some conditional logic of the directive definition there's a possibility for different types to be returned. Is that a use case that is supported? Or is it general discouraged to create directives with that sort of behavior? Considering we have @skip and @include in the spec, this general case must be accounted for in some way, but I don't see any way in the codegen documentation to generate types for similar, albeit custom, directives where the field type may depend on some conditional logic.

[eddeee888]

That leads me to wonder though, I can see a plausible use case in a more general case where you are using a directive that may impact the type of the field. Not necessarily for null or optional values, but possibly in some conditional logic of the directive definition there's a possibility for different types to be returned. Is that a use case that is supported? Or is it general discouraged to create directives with that sort of behavior? Considering we have @Skip and @include in the spec, this general case must be accounted for in some way, but I don't see any way in the codegen documentation to generate types for similar, albeit custom, directives where the field type may depend on some conditional logic.

The use case most similar to this is nullability.errorHandlingClient where the nullability of a field depends on the @semanticNonNull directive .
I've also found an older issue where the team thought custom directives like these are anti-pattern, and advised to use scalar instead #8071