graphql - 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.

http://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.

Answer 1

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.