what’s the difference between parseValue and parseLiteral in GraphQLScalarType

Question

Looking through the GraphQL documentation for custom scalar types (I’m trying to create my own date type) I’m not sure what the difference between parseValue and parseLiteral are.

https://graphql.org/graphql-js/type/#graphqlscalartype

The documentation doesn’t seem to include any descriptions of what the functions are supposed to do.

Can someone let me know what the requirements are? I’m assuming that serialize must serialize the scalar to a string. Is that correct? I’m assuming that parseLiteral is a deserialization of that string to the type? In my case a Date type. However, in the examples – serialize and parseValue are the same function – which suggests it’s not a simple deserialization method.

Tan Duong 1,4031 gold badge17 silver badges28 bronze badges · Accepted Answer · 2018-11-09 13:06:50Z

The serialize method would be called when the value of the type is going to be sent to the client as a response. Since the values on the output is in the form of JSON, the return value of serialize could be anything. Could be string, number, array, object …

The other two methods (parseValue and parseLiteral) are to read input.

In GraphQL there are two ways of reading input from client, one is inline in the query, like:

query {
    allUsers(first:10) {
        id
    }
}

where 10 is the inline value for first argument. Since the input language for GraphQL is not exactly JSON, the value (here 10) is being parsed and converted to AST (Abstract Syntax Tree). In this case, parseLiteral comes to play. It inputs the AST and returns the parsed value of the type. Types could be as complex as JSON and parseLiteral could traverse the AST and return JSON.

The other way of reading input from clients is through variables:

query ($howMany: YourCustomType) {
  users(first: $howMany) {
    id
  }
}

variables:

{
  "howMany": {
    "thisMany": 10
  }
}

Since the variables are pure JSON, you don’t need AST here, you already have JSON. That’s where parseValue comes to play. It gets the input as JSON and returns whatever the query resolver should use.

function parseValue(value) {
    let first = value.thisMany;
    return first;
}

So, you could have different presentation when you read from variables than when you read values inline, but conceptually, they should be the same in terms of presentation. However since the “type” of input is different (inline is GraphQL and variable is JSON), the parsing algorithm could be different. That’s why if you define it as input type, you need to provide two separate methods to read them.

@thisdotvoid to be honest i don’t remember, i think i read the source code since i was interested! you can find some good stuff here: graphql.org/graphql-js/type — Apr 14, 2018 at 22:43
Hey @Aс┤Н╔к╩А any idea why PaseLiteral gets called twice? — Dec 17, 2018 at 10:50
@Hannan I don’t know, maybe it’s related to your code? or perhaps there’s a good reason for that. You’re welcome to create a new stackoverflow question, someone might beable to help! 🙂 — Dec 18, 2018 at 18:02
Excellent explanation I’ve ever read! Really appreciate your findings — Jul 10, 2019 at 1:44

what’s the difference between parseValue and parseLiteral in GraphQLScalarType