Server-Side GraphQL in Next.js

Directives & Enums

Scott Moss

Scott Moss

Superfilter AI
Server-Side GraphQL in Next.js

Check out a free preview of the full Server-Side GraphQL in Next.js course

The "Directives & Enums" Lesson is part of the full, Server-Side GraphQL in Next.js course featured in this preview video. Here's what you'd learn in this lesson:

Scott explains that directives are like middleware for fields or entities in a GraphQL schema. He demonstrates how to use the built-in "deprecated" directive to mark a field as deprecated and show a deprecation message in the GraphQL Explorer. He also mentions that custom directives can be created for various purposes, such as authentication.


Transcript from the "Directives & Enums" Lesson

>> Scott: So directives, I kinda just talked about it for a little bit. You'll probably almost never use these until you become like, I don't know, you just become really badass at GraphQL. You're just like, I'm just out here making custom directives because I can, sure, there's some pretty crazy stuff you can do here.

There's tons of plugins you can download, the best way I can describe it, is you can think about it as middleware for a field or an entity. Cuz you can put a directive on a field, you can also put it on a type as well. And it's basically middleware for that, it's a function that will run to hijack when that entity is either created, there's many life cycles.

So a directive allows you to tie into the life cycle of a field or an entity and do something when that life cycle is triggered. So, I wanna run this function, for instance, deprecated. If we were to add this, this is a built-in directive, what this would do is it would add a comment in the notes of the GraphQL explorer that we're using to let you know that it's deprecated, right?

So if I were to go look at the schema here and one of these fields are deprecated, it would probably tell me. So let's go that just so you can see what I'm talking about. Profile, let's just say at deprecated, I can spell, is that how you spell that?

>> Scott: Yeah, that is how you spell it. So you can give it a reason, you can put whatever you want there. So I'll say deprecated reason no more, right? I say that, I can go back to our username and pretty sure this is built-in, let's see.
>> Scott: I put single quotes, gotta put double quotes I do that all the time.

It's very strict, there we go. So now if I go back to our schema, I put that on the person.
>> Scott: Or no, it wasn't all perfect, it was on profile, right? There we go, and you see right here, deprecated. That's what that directive does it just tells you that this field is deprecated.

It's mostly for documentation, and there are some other built-in ones. Some of the ones that I've made that were useful and I'll talk a little more about it when it gets authentication where we're like directors for authentication. So in my schema, this is where it gets really powerful.

For a search result there are some things you want non-logged in people to be able to search for. But then there's some things you don't want them to be able to search for unless they're logged in, right? So for a profile, I say, all right, I'll let you search for a profile you can see their username and ID, but you can't see who the person is.

So this is all, and maybe I'll say, required true or something like that. So I'll make a directive that this field, if access through a query has to pass authentication, otherwise it can't be sent down right on a field level. So I can do a field level, I can do a query level, I can do a type level.

So you can get pretty granular with the things that you wanna show, and then I would have to go write the code to make this work. And it's not too crazy, we won't be writing custom directives today, cuz I think it is this a little more advanced, but this is probably one of the best use cases I've seen.

Just to note, directives are a type of entity and GraphQL that work on the schema, but also in the query. But those are two different types of directives, so you can do directives and the query as well. And I've seen some pretty cool ones, I've almost never really used them.

There's a few ones that some of them have, but I think some of the really cool ones that I've seen, were only see Lodash GraphQL, this one's pretty cool. You can do Lodash functions on a query. So if you never use Lodash, it's like helper methods that allow you to operate on arrays and objects, every filter.

I mean, some of the stuff is built into Javascript global now, but for the most part, it's quite useful. So you can run Lodash functions as directives inside your, query, which is quite impressive in my opinion. So this is a useful example of the power of what you can do with directives.

And there's tons of these out there, so you can get pretty creative. But for the most part it's like yeah, you could do this here. But I feel do I really wanna build an API that allows people to do that or should I just have it taken as an argument and write that in the code myself?

It really just depends on what use case you want and things like that.
>> Scott: Okay, any questions on directives?
>> Scott: Yes.
>> Speaker 2: How does GraphQL access these things that would seem to be outside the scope of querying a dB? Does it have some kind of callback hook?
>> Scott: Yeah, exactly, it does have some type of callback hook.

I've been kinda talking about it, but it's basically, you would have to write code that ties into the, there's life cycle methods of how a graphical schema is processed when it starts, when it's being validated, when a field is accessed. If you've ever worked on any type of language before or tried to build a language, there's something called an abstract syntax tree, it does pattern matching, right?

And it will figure out, okay, this is a node, this is a node, this is a node, this is a node, every language does this, And GraphQL is a language, and you can hook into that. You can say, cool, I want to run this function when a node or a node whose type is filled is accessed, run my function first, right?

So you can do that and that function can be a directive. So you can say run this directive first, but what actually ends up happening for some of those queries that I showed you, those queries are probably happening after the data is resolved, right? So it's after the data is resolved, run this directive, and then that directive uses that Lodash function to apply it to the data that was resolved.

Because you can tie into many stages of a hook inside of GraphQL. So I would imagine the Lodash one is probably tying into after that field or that query was resolved before they send the results back. Use this directives function to process the data and then send that back.

I'm pretty sure that's what's happening because it would need the data first. So yes, you can hook into different stages and different nodes in GraphQL and it's really, really, really powerful. Okay, and then there's some more built-in ones, but no one's really using directives like that, I'm gonna be honest.

They're powerful, but it's just like is it worth it? Who knows? Cool, the next one is input types. Input types are a description. We haven't talked about arguments yet, so maybe we'll talk about arguments. Right now, we'll talk about enums. So enums are exactly what they sound like, if you ever built a database or even use Typescript, an enum is just saying it's a string type, but it's gotta be one of these strings.

That's basically what an enum type is, right? So I can come here, I can say, I wanna make an enum. I'm gonna call this enum STATUSES, I guess. Typically, enums are all caps, but they don't have to be. And I can say one status is in progress, another status is done, another one is to do.

So I have statuses here and then now, let's make a new type guess just for the heck of it. I could say type a to-do and might have a status on it whose type is STATUSES, like that.
>> Scott: And it's basically the same as a database, same as any type language.

It's just saying it's gotta be one of these.

Learn Straight from the Experts Who Shape the Modern Web

  • In-depth Courses
  • Industry Leading Experts
  • Learning Paths
  • Live Interactive Workshops
Get Unlimited Access Now