Skip to main content

Deprecated

GraphQL supports marking fields, input fields, arguments and enum values as @deprecated with an optional reason. These directives are used by tools like Graphiql and editor integrations to provide context to developers.

Grats supports this feature by using the @deprecated JSDoc tag. This tag can be used on fields, enum variants, and arguments. If the tag is followed by text, that text is used as the reason for the deprecation.

Field example​

/** @gqlType */
class User {
  /**
   * @gqlField
   * @deprecated Please use myNewField instead.
   */
  oldField: string;

  /** @gqlField */
  newField: string;
}
Playground

Would extract:

type User {
  newField: String
  oldField: String @deprecated(reason: "Please use myNewField instead.")
}

Overlap with TypeScript's @deprecated​

TypeScript also has special treatment of constructs with the @deprecated in their JSDoc docblock. Specifically, it will render uses of them as struckthrough and greyed out in the editor. In general this overlap is a feature, since deprecated fields should also generally not be used internally. However, if you wish to deprecate a field/argument/etc. in you schema, but not in your code, you can define a new method/function specifically for GraphQL which wraps the non-deprecated version. For example:

/** @gqlType */
class User {
  // Not deprecated!
  name: string;

  /**
   * @gqlField name
   * @deprecated Not supported externally any more
   */
  graphQLName(): string {
    return this.name;
  }
}
Playground