Check out a free preview of the full Advanced GraphQL, v2 course:
The "Directives" Lesson is part of the full, Advanced GraphQL, v2 course featured in this preview video. Here's what you'd learn in this lesson:

Scott defines directives as identifiers that enable adding logic to metadata, schemas, queries or mutations, and demonstrates how to use the @deprecated directive. Directives give control down to the field level on TypeDefs, eliminate post processing on clients after a query, and are extendable. "

Get Unlimited Access Now

Transcript from the "Directives" Lesson

[00:00:00]
>> Creating flexibility with directives. So, what are directives? Basically, directives are things that allow you to add logic and metadata to your Schemas, Queries, Mutations, fields, types, pretty much anything. Directives can act like middleware for your schemas or even post-processing hooks for your queries Mutations. And that's because you can use directives in two different places.

[00:00:24] You can use them on the Schema level, you can also use directives on the client side. So on the query and mutation level, there's many types of directives and within those types, you can use them on different types of nodes, fields, object types, inomes, inputs, arguments, whatever you want, you can add a directive.

[00:00:48] What it's gonna do, I don't know, it's up to you. People get really silly with these directive sometimes, I don't know. You could probably get really creative, you think about it. I know we made our directive that basically does all of our analytic tracking. So we can add a directive on any field and our report to our analytics for us.

[00:01:04] So we don't have to hard code analytics tracking, we just put a directive on it, just works. Why is directives? So, fine-grain control down to the field level on your type definitions.. So, basically like I said, you can say, I want an instrument, this fields, with this logic and only this field and I don't wanna have to go in the resolver and write the code for it, or maybe I have three different fields that I wanna do it for and I don't have to write them in every single resolver, and I could use the approach that we did today where we wrap the resolver in another function and then does something and then calls the resolver.

[00:01:39] You can do that, but then you got to do that for every resolver. So there are ways around it, but directors kind of get rid of that where you write at once and then you forget, you don't have to worry about it and you just declare them in the Schema.

[00:01:51] You eliminate the the post processing on your clients at the Query. So for client's side directives, they're useful for eliminating like, okay, now that I got my Query back there's still something I have to do to this, I need to transform this date to be this format, or I need to change this field to this or whatever I like.

[00:02:13] Directives can help with that. So you don't have to do some post processing, and you don't have to update your server to handle it for you because it's a client specific use case, so it's kind of the middleman. And they're very extendable, you can use directors with other directors, you can have multiple directors talking to, in like in line, in order, doing multiple things, and like I said, because you can add them pretty much any node that you want, they are very very extendable.

[00:02:45] And there's libraries, multiple libraries of directives that you can download and just add and use them, so that's pretty cool. And yeah, extremely be powerful if you haven't figured that out, just some pretty crazy stuff. So now, I want us to follow along about me, actually using some of the directives that are built in on a client's side, and then some of the directives that are built in on the Schema cyber walk through, using some of them and you can understand how they work.

[00:03:16] So, what I'll do is let's just start on the server side here. I'll keep going with this. So, one directive that I know is, that comes embedded in graph ql spec is a directive called Deprecated. So for instance, if I wanted, if I were getting ready to remove a field, right?

[00:03:39] You might, like friends, if I want to get rid of this error field here on the user, I could just do this, [LAUGH] It's gone now, look at that, it's magic. But the client's gonna break but's using that field, right? It's a client's using that field your all app's broken now because it's depending on that field, and now they gotta change their Queries.

[00:03:55] So their Queries also remove that field. So, they came up with a directive called deprecate. That basically is going to instrument this field inside your tooling. It's going to show different things on the request to let anyone know that, hey, this field is no longer supported. It's still gonna get a value back until we decide to remove it, if we ever remove it, but it's never gonna get updated again and it probably doesn't do what you think it does anymore.

[00:04:24] And in fact, you gotta use this field instead, so that's what this is. So, this syntax is using an @ sign. You use the @ sign like that, and then you put the name of the directive, and you always put it basically to the right of the node that you're using.

[00:04:41] So in this case, we're using a directive on a field, so it's to the right of the field, you wouldn't put it before the type, you wouldn't put it here, you will put it after the type. If this directive was going to be on a type, we will put on after the name of the type, like deprecate, like that, [INAUDIBLE] Go after the name.

[00:04:59] But in this case it's after a field, so we wanna put it there. So you do deprecated, we can start this thing, server starts up, go to our playground, refresh this thing, and if I try to get me right there automatically, the user error is deprecated, no longer supported.

[00:05:19] You can see that error there, it's a warning. It's not an error cuz I can still do it. My resolver is just still there, and it's still working. But this is letting you know, hey, it's errors, deprecated, and you can see you get this error here saying, hey, I mean well, we're throwing errors, that's why we get this errors.

[00:05:36] So that's how you know it's still resolving, that field actually throws an error. It's not erroring because it's deprecated, that's confusing. Let me make that distinction. The errors field Throws an error, which is why we see that error, not because it's deprecated. So, if like, let me get rid of that, let me do this.

[00:05:58] That make more sense. It's still gonna return the value, it's not gonna throw an error, but it's gonna let you know that is deprecated. And if you were to look at the docs, you could also see on a user type, right here, deprecated, no longer supported error string.

[00:06:15] So, this directive is adding Metadata to our Schema and Has support for something called deprecated fields. It's hooking into that support, and it's just instrumenting the scheme of like, hey, add this to the deprecated filter, deprecated true. That's basically what it's doing, on the Schema level. So it's instrumenting it on the Schema level, so you get that nice little thing here like that.

[00:06:39] Any questions on that syntax for directives on the Schema level?
>> If you deprecate something, you still have to keep all of the resolvers around, why [INAUDIBLE] Correct?
>> If it's in your type def, deprecate or not, you gotta keep the resolvers for it.
>> Okay, so that is all that adds Metadata?

[00:06:58]
>> All it does is it adds Metadata. What people do is they do it to buy time, right? So, I guess it depends on your API, if your API is public facing, it's probably to buy time, like, hey customers, we're gonna migrate from this field to this field now, and we're deprecating it for whatever.

[00:07:12] And I'm pretty sure it takes an argument like this, or I think you can do like a reason, let's see. Because I said so, let's see. Yeah, I guess that is it. So if you do like that, you can see the reason right there because I said so.

[00:07:33] So, you can, yeah, most people do it to buy time, like, hey customers, we're gonna transition from this field in three months, so it's gonna be deprecated. You got three months to change, but it's like an internal thing. You might deprecate it and completely remove the resolver for it and just like, you just should not use it, so, screw you.

[00:07:50] So it really depends on what you're doing, but our solution's just leave it forever, they'll just leave it forever and what they'll do and their reason they'll say something like, use They'll say like, use the other field that we made, right? So they usually deprecate a field not because they're getting rid of it, it's because they're replacing it with something else, and that's supported.

[00:08:13] That's usually what deprecation is for. It's like, hey, it's not that we're getting rid of it, it's just that we replaced it with something else. So, Yeah, and their arguments on directors follow the same rules as arguments on other fields. So, you have to name them, you have to get them a scholar or an input