Introduction
GraphQL is one of the most fantastic tools presented in the software world in the last few years. In fact, that’s for many reasons: its strongly typed schema, avoiding overfetching or underfetching, a handy tool for both server and client-side, composing multi API (Stitching), and the great community.
Actually, Directives are among the most powerful features of GraphQL that enable you to enhance and extend your API.
What are Directives?
The directive is a function that decorates a portion of GraphQL schema to extend its functionality. For example @UpperCase()
in the following example:
type User {
name: String! @UpperCase
}
Simply, this @UpperCase
directive as its name implies would uppercase the user name and then return it.
Directives Types
There are two types of directives:
- Schema Directives.
- Query Directives.
Let’s know the differences between them from the built-in directives.
Till now, there are four approved built-in directives:
-
@deprecated(reason: String)
which marks a portion of the schema as deprecated for an optional reason (Schema Directive).
type User { fullName: String name: String @deprecated(reason: "Use `fullName` instead") }
-
@specifiedBy(url: String!)
which provides a scalar specification URL for specifying the behavior of custom scalar types (Schema Directive).
scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
-
@skip(if: Boolean!)
if it is true, the GraphQL server would ignore the field and wouldn’t resolve it (Query Directive).
query getUsers($shouldSkipName: Boolean!) { name @skip(if: $shouldSkipName) }
-
@include(if: Boolean!)
if it is false, the GraphQL server would ignore the field and wouldn’t resolve it (Query Directive).
query getUsers($shouldIncludeName: Boolean!) { name @include(if: $shouldIncludeName) }
From the previous examples, you may notice that:
- The Schema Directives are defined in the schema itself and run while building it, and they are used by the schema designer.
- The Query Directives are used in the query and run while resolving it, and they are used by the end-user.
Query Directives vs Field Argument
From the previous examples, you may ask why should we use directives while we can perform the uppercasing logic in the resolver itself depending on a field argument? This question will lead us to clarify the pros and cons of each other.
Unfortunately, different GraphQL servers, clients, and tools deal with GraphQL directives differently and support them to a different extent which makes conflict among them.
For example, Relay doesn’t set into account using the Query Directive when querying the same field from the cache.
Take a look at the following example. This query runs for the first time then cached:
query getPost(id: 1) {
title # Hello World
}
Run the same query for the second time after caching but with the @UpperCase
directive:
query getPost(id: 1) {
title @UpperCase # Hello World
}
The second query should return ‘HELLO WORLD’ however, Relay returns the same response as the first query which is existed in the cache even though we use the @UpperCase
directive which is completely ignored.
From the previous example, you note that depending on Query Directives is inconsistent due to the different handling from the GraphQL providers, as a result, GraphQL Tools discourages using the Query Directives:
In general, however, schema authors should consider using field arguments wherever possible instead of query directives.
On the other hand, using directives has some advantages:
- Your code will be cleaner by improving its reusability, readability, and modularity which respects the DRY Principle.
- Respecting the Single Responsibility Principle.
- If you want your clients to extend your GraphQL API with new functionalities without touching your code, you can depend on directives to fulfill this task.
So to summarize this point, to be on the safe side, as GraphQL Tools advises, you should use the field arguments instead of Query Directives. So the previous example should be:
query getPost(id: 1) {
title(format: UPPERCASE) # HELLO WORLD
}
Or you can use the Query Directives only if you know what are you doing!
Directives Use Cases
Basically, there are many possibilities for using custom directives. Let’s create some of them as practical examples and apply them on the same query post
.
You can find the complete code 👉 here.
First of all, we will define this schema:
type Post {
id: Int!
uuid: ID!
userId: Int!
title: String!
body: String!
createdAt: String!
}
type Query {
post: Post
}
-
Let’s implement the upper-case directive and let’s call it
@upper
:Firstly, we need to define the directive location.
directive @upper on FIELD_DEFINITION # This means, this directive can be applied on any field defined on any type (like `title`)
Secondly, we need to define the directive transformer function that is responsible to apply the directive logic on every field having this directive.
function upperDirectiveTransformer(schema, directiveName) { return mapSchema(schema, { [MapperKind.OBJECT_FIELD]: (fieldConfig) => { // `OBJECT_FIELD` is the mapperkind while `FIELD_DEFINITION` is location name in schema // Check whether this field has the specified directive const upperDirective = getDirective(schema, fieldConfig, directiveName)?.[0]; if (upperDirective) { // Get this field's original resolver // If the original resolver is not given, then a default resolve behavior is used const { resolve = defaultFieldResolver } = fieldConfig; // Replace the original resolver with a function that *first* calls // the original resolver, then converts its result to upper case fieldConfig.resolve = async function (source, args, context, info) { const result = await resolve(source, args, context, info); // Calling the original resolver if (typeof result === 'string') return result.toUpperCase(); // Uppercasing the result return result; }; return fieldConfig; } } }); }
Thirdly, we need to transform the schema by applying the directive logic.
schema = upperDirectiveTransformer(schema, 'upper');
Fourthly, we can apply it to the
title
field as follows:
title: String! @upper
That’s it, now you can use the
@upper
directive at any string field. -
Let’s implement a directive that loads this post from a third-party API, and let’s call it
@rest(url: String!)
Let’s move on with the same steps
directive @rest(url: String!) on FIELD_DEFINITION
function restDirectiveTransformer(schema, directiveName) { return mapSchema(schema, { [MapperKind.OBJECT_FIELD]: (fieldConfig) => { const restDirective = getDirective(schema, fieldConfig, directiveName)?.[0]; if (restDirective) { const { url } = restDirective; // Get the directive param const { resolve = defaultFieldResolver } = fieldConfig; fieldConfig.resolve = async function (source, args, context, info) { let { data } = await axios.get(url); // Use axios to get the post from a third-party // Inject the post in `args` to be able to return it from the resolver (You can apply your logic as you want) return await resolve(source, { ...args, post: data }, context, info); }; return fieldConfig; } } }); }
async post(_, args) { return args.post; // Injected into `args` by the `@rest` directive }
schema = restDirectiveTransformer(schema, 'rest');
Now we can apply it to the
post
query as follows:
type Query { post: Post @rest(url: "https://jsonplaceholder.typicode.com/posts/1") }
-
Let’s implement another directive to optionally format the date of the post
createdAt
field and call it@date(format: String = "mm/dd/yyyy")
:
directive @date(format: String = "mm/dd/yyyy") on FIELD_DEFINITION # Set a default format if not provided
function dateDirectiveTransformer(schema, directiveName) { return mapSchema(schema, { [MapperKind.OBJECT_FIELD]: (fieldConfig) => { const dateDirective = getDirective(schema, fieldConfig, directiveName)?.[0]; if (dateDirective) { const { resolve = defaultFieldResolver } = fieldConfig; const { format } = dateDirective; // Get the directive param fieldConfig.resolve = async function (source, args, context, info) { const result = await resolve(source, args, context, info); if (!result) return null; try { return dateFormat(result, format); } catch { throw new ApolloError('Invalid Format!'); } }; return fieldConfig; } } }); }
schema = dateDirectiveTransformer(schema, 'date');
Now, we can apply this directive to the
createdAt
field as follows:
createdAt: String! @date(format: "dddd, mmmm d, yyyy")
-
Let’s implement a directive to authorize the access to this post, let’s call it
@auth(role: String!)
:
directive @auth(role: String!) on FIELD_DEFINITION
function authDirectiveTransformer(schema, directiveName) { return mapSchema(schema, { [MapperKind.OBJECT_FIELD]: (fieldConfig) => { const authDirective = getDirective(schema, fieldConfig, directiveName)?.[0]; if (authDirective) { const { resolve = defaultFieldResolver } = fieldConfig; const { role } = authDirective; // Get the directive param fieldConfig.resolve = async function (source, args, context, info) { // Check the authorization before calling the resolver itself if (role !== 'ADMIN') throw new ApolloError('Unauthorized!'); return await resolve(source, args, context, info); }; return fieldConfig; } } }); }
schema = authDirectiveTransformer(schema, 'auth');
That’s it, now the directive is ready to apply:
type Query { post: Post @auth(role: "ADMIN") }
Try to check on
OPERATOR
instead to validate the directive effect. -
If we want to auto-generate a UUID for the post, we can create the
@uuid
directive:
directive @uuid(field: String!) on OBJECT
You may notice that we used
OBJECT
instead ofFIELD_DEFINITION
because this directive will be applied on GraphQL Types likePost
type.
function uuidDirectiveTransformer(schema, directiveName) { return mapSchema(schema, { // The mapper for OBJECT is OBJECT_TYPE [MapperKind.OBJECT_TYPE]: (type) => { const uuidDirective = getDirective(schema, type, directiveName)?.[0]; if (uuidDirective) { const { field } = uuidDirective; // Get the directive param const config = type.toConfig(); config.fields[field].resolve = () => crypto.randomUUID(); return new GraphQLObjectType(config); } } }); }
schema = uuidDirectiveTransformer(schema, 'uuid');
Then we can apply it to the
Post
type as follows:
type Post @uuid(field: "uuid") { ... }
-
Also, we can implement a directive to validate a string length like post’s
body
field. Let’s call it@length(min: Int, max: Int)
:
directive @length(min: Int, max: Int) on FIELD_DEFINITION
function lengthDirectiveTransformer(schema, directiveName) { return mapSchema(schema, { [MapperKind.OBJECT_FIELD]: (fieldConfig) => { const lengthDirective = getDirective(schema, fieldConfig, directiveName)?.[0]; if (lengthDirective) { const { resolve = defaultFieldResolver } = fieldConfig; const { min, max } = lengthDirective; fieldConfig.resolve = async function (source, args, context, info) { const result = await resolve(source, args, context, info); if (min !== undefined && typeof result === 'string' && result.length < min) { throw new ApolloError( `The field ${fieldConfig.astNode.name.value} should contain at least ${min} characters` ); } if (max !== undefined && typeof result === 'string' && result.length > max) { throw new ApolloError( `The field ${fieldConfig.astNode.name.value} shouldn't exceed the max length (${max})` ); } return result; }; return fieldConfig; } } }); }
schema = lengthDirectiveTransformer(schema, 'length');
Now, apply it
body: String! @length(min: 10)
Try to set
min: 1000
to check the validation.
Conclusion
Simply put, Directives are a very great tool that can be used to enhance your GraphQL API. In this article, we implemented some use cases of directives only to show you the power of directives, and consequentially, you can implement your own ones that fit your own situation.
Top comments (0)