Directive Annotations

You can annotate constructs in your Grats GraphQL schema with GraphQL directives using the @gqlAnnotate docblock tag.

/**
 * @gqlQueryField
 * @gqlAnnotate myDirective
 */
export function greet(): string {
  return "Hello";
}

Directive annotations can also accept arguments using GraphQL syntax for arguments:

/**
 * @gqlQueryField
 * @gqlAnnotate myDirective(someArg: "Some String")
 */
export function greet(): string {
  return "Hello";
}

note

The GraphQL directive @deprecated is unique in that it is a built-in GraphQL directive and has a built-in TypeScript equivalent in the form of the @deprecated docblock tag. Because of this, TypeScript @deprecated docblock tags are automatically converted into GraphQL @deprecated directives.

Directive Validation

While the GraphQL Spec does not actually specify that arguments passed to directives used in the schema should be validated against the types specified in that directive's declaration, Grats adds its own validation to ensure that arguments used in @gqlAnnotate are typechecked against their directive declaration.

Schema Directive Annotations at Runtime

Directive annotations added to your schema will be included in Grats' generated .graphql file. For directives meant to be consumed by clients or other infrastructure, this should be sufficient.

For directives which are intended to be used during execution, they must be included in the graphql-js class GraphQLSchema which Grats generates. Unfortunately GraphQLSchema does not support a first-class mechanism for including directive annotations. To work around this, Grats includes directives under as part of the relevant GraphQL class' extensions object namespaced under a grats key.

const foo = {
  extensions: {
    grats: {
      directives: [
        {
          name: "myDirective",
          args: { someArg: "Some Value" },
        },
      ],
    },
  },
};

You can find an example of this in action in the production-app example where we define a field directive @cost which implements API rate limiting.