Inputs

GraphQL input types can be defined by placing a @gqlInput docblock directly before a:

• Type alias declaration
• Interface declaration

/**
 * Description of my input type
 * @gqlInput
 */
type MyInput = {
  name: string;
};

Playground

"""Description of my input type"""
input MyInput {
  name: String!
}

/** @gqlInput */
interface MyInput {
  name: string;
}

Playground

input MyInput {
  name: String!
}

Unlike with type or interface fields, every property of an input type is automatically included as part of the GraphQL definition. You do not need to annotate individual properties with @gqlField.

Deprecated fields

Individual optional fields can be marked as @deprecated in the GraphQL schema using the @deprecated JSDoc tag:

import { Int } from "grats";

/** @gqlInput */
type MyInput = {
  name: string;
  /** @deprecated Don't ask for age any more */
  age?: Int;
};

Playground

input MyInput {
  age: Int @deprecated(reason: "Don't ask for age any more")
  name: String!
}

Merged Interfaces

TypeScript merges interfaces if you define multiple interfaces with the same name in the same scope. For example, Node is a built-in interface that describes DOM nodes. So, if you define a Node interface in a file without any imports or exports (whose declarations are global), TypeScript will merge your interface with the built-in one.

To avoid ambiguity, Grats will error if you try to define a GraphQL input type using a merged TypeScript interface. To avoid this error you can define a new interface, with a unique name, and then rename it to the name you want to use in your schema.

caution

Grats can only detect merges between declarations in the files it reads. It does not read TypeScript's built-in declarations, like the DOM's Node, so it can't report when your interface merges with one of them.