Custom directive

We might need to customise our schema by decorating parts of it or operations to add new reusable features to these elements. To do that, we can use a GraphQL concept called Directive.

A GraphQL directive is a special syntax used to provide additional information to the GraphQL execution engine about how to process a query, mutation, or schema definition. Directives can be used to modify the behaviour of fields, arguments, or types in your schema.

A custom directive is composed of 2 parts:

schema definitions
transformer

Schema Definition

Let's explore the custom directive creation process by creating a directive to redact some fields value, hiding a phone number or an email.

First of all, we must define the schema

const schema = `
    directive @redact(find: String) on FIELD_DEFINITION
    
    type Document {
      excerpt: String! @redact(find: "email")
      text: String! @redact(find: "phone")
    }

    type Query {
      documents: [Document] 
    }`;

To define a custom directive, we must use the directive keyword, followed by its name prefixed by a @, the arguments (if any), and the locations where it can be applied.

directive @redact(find: String) on FIELD_DEFINITION

According to the graphql specs the directive can be applied in multiple locations. See the list on the GraphQL spec page.

Transformer

Every directive needs its transformer. A transformer is a function that takes an existing schema and applies the modifications to the schema and resolvers.

To simplify the process of creating a transformer, we use the mapSchema function from the @graphql-tools library. In this example we are refering to graphqltools 8.3.20

The mapSchema function applies each callback function to the corresponding type definition in the schema, creating a new schema with the modified type definitions. The function also provides access to the field resolvers of each object type, allowing you to alter the behaviour of the fields in the schema.

const { mapSchema, getDirective, MapperKind } = require("@graphql-tools/utils");

// Define the regexp
const PHONE_REGEXP = /(?:\+?\d{2}[ -]?\d{3}[ -]?\d{5}|\d{4})/g;
const EMAIL_REGEXP = /([^\s@])+@[^\s@]+\.[^\s@]+/g;

const redactionSchemaTransformer = schema =>
  mapSchema(schema, {
    // When parsing the schema we find a FIELD
    [MapperKind.FIELD]: fieldConfig => {
      // Get the directive information
      const redactDirective = getDirective(schema, fieldConfig, "redact")?.[0];
      if (redactDirective) {
        // Extract the find attribute from the directive, this attribute will
        // be used to chose which replace strategy adopt
        const { find } = redactDirective;
        // Create a new resolver
        fieldConfig.resolve = async (obj, _args, _ctx, info) => {
          // Extract the value of the property we want redact
          // getting the field name from the info parameter.
          const value = obj[info.fieldName];

          // Apply the redaction strategy and return the result
          switch (find) {
            case "email":
              return value.replace(EMAIL_REGEXP, "****@*****.***");
            case "phone":
              return value.replace(PHONE_REGEXP, m => "*".repeat(m.length));
            default:
              return value;
          }
        };
      }
    },
  });

As you can see in the new resolver function as props, we receive the current object, the arguments, the context and the info.

Using the field name exposed by the info object, we get the field value from the obj object, object that contains lots of helpful informations like

fieldNodes
returnType
parentType
operation

Generate executable schema

To make our custom directive work, we must first create an executable schema required by the mapSchema function to change the resolvers' behaviour.

const executableSchema = makeExecutableSchema({
  typeDefs: schema,
  resolvers,
});

Apply transformations to the executable schema

Now it is time to transform our schema.

const newSchema = redactionSchemaTransformer(executableSchema);

and to register mercurius inside fastify

app.register(mercurius, {
  schema: newSchema,
  graphiql: true,
});

Example

We have a runnable example on "example/custom-directive.js"

Federation and Custom Directives

Because schemas involved in GraphQL federation may use special syntax (e.g. extends) and custom directives (e.g. @key) that are not available in non-federated schemas, there are some extra steps that need to be run to generate the executable schema using the @mercuriusjs/federation library.

When mercurius applies schemaTransforms, the internal mapSchema recreates every GraphQLObjectType. Since resolveReference is a non-standard runtime property set by federation, it gets lost in this process. The @mercuriusjs/federation library provides the federationSchemaTransformer utility to preserve resolveReference functions during schema transformations.

To see how this works, we will go through another example where we create a custom directive to uppercase the value of a field in a federated environment.

Schema Definition

The schema definition is equal to the one used in the previous example. We add the @upper directive and we decorate the name field with it.

const schema = `
  directive @upper on FIELD_DEFINITION

  extend type Query {
    me: User
  }

  type User @key(fields: "id") {
    id: ID!
    name: String @upper
    username: String
  }`;

Transformer

The transformer follows the same approach used in the previous example. We declare the uppercase transform function and apply it to the field resolver if they have the @upper directive.

const { mapSchema, getDirective, MapperKind } = require("@graphql-tools/utils");
const { defaultFieldResolver } = require("graphql");

function upperDirectiveTransformer(schema) {
  return mapSchema(schema, {
    [MapperKind.FIELD]: (fieldConfig) => {
      const upperDirective = getDirective(schema, fieldConfig, "upper")?.[0];
      if (upperDirective) {
        const { resolve = defaultFieldResolver } = fieldConfig;
        fieldConfig.resolve = async function (obj, args, ctx, info) {
          const result = await resolve(obj, args, ctx, info);
          return typeof result === "string" ? result.toUpperCase() : result;
        };
        return fieldConfig;
      }
    },
  });
}

Register the schema

There are two ways to use custom directives with federation.

Option 1: Using mercuriusFederationPlugin (recommended)

The simplest approach is to use mercuriusFederationPlugin from @mercuriusjs/federation. The plugin automatically wraps transformers with federationSchemaTransformer, so resolveReference functions are preserved without any extra steps.

const { mercuriusFederationPlugin } = require("@mercuriusjs/federation");

app.register(mercuriusFederationPlugin, {
  schema,
  resolvers,
  schemaTransforms: [upperDirectiveTransformer],
});

Option 2: Using buildFederationSchema with mercurius

If you need more control over the schema building process, you can use buildFederationSchema together with mercurius directly. In this case, you must wrap your transformers with federationSchemaTransformer to preserve resolveReference functions.

const mercurius = require("mercurius");
const {
  buildFederationSchema,
  federationSchemaTransformer,
} = require("@mercuriusjs/federation");

app.register(mercurius, {
  schema: buildFederationSchema(schema),
  resolvers,
  schemaTransforms: federationSchemaTransformer([upperDirectiveTransformer]),
});

Warning: Without federationSchemaTransformer, resolveReference is lost during schema transformation and _entities queries will return null for entity fields:
js
// ⚠️ This will NOT work correctly — resolveReference is lost!
app.register(mercurius, {
  schema: buildFederationSchema(schema),
  resolvers,
  schemaTransforms: [upperDirectiveTransformer],
});

Example

We have a runnable example in the Federation repo that you can find here examples/withCustomDirectives.js.