add implementation guide

[andimarek]

This is just mdx. It was originally written for gatsby, but being mostly just markdown it can be easily ported to whatever the build/publish system it.

This PR is for discussing the content.

A rendered version of it can be found here: https://www.graphql-scalars.com/scalars-guide

[eapache]

I understand the distinction between Literal and Value coercion you're trying to make, but ultimately I think they're the same thing. It's just that a literal can only be one of the graphql AST types (string, int, etc) whereas a variable value can be of any type supported by the transport.

In other words, I don't think it should be possible to specify a scalar which treats string literals differently from string variables.

[eapache]

Should this go under implementation guidelines? It is an implementation thing.

[andimarek]

@eapache Maybe I was not perfectly clear but the Ast for a custom Scalar can be arbitrary as long as it is valid Syntax.
For example 12133242323523523 is not a valid value for Int but it is valid syntax and therefore can be used as input for a custom Scalar BigInt for example. But it has to valid syntax (=can be represented as Ast).

Value Coercion can take "anything" that is meaningful for the custom Scalar and is very much implementation specific to the programming language. The guideline here is: all values that makes sense and can be converted/interpreted without surprises or pitfalls.

In a Specification for a custom Scalar you have to be very clear around the syntax that the Scalar should accept because it is cross implementation valid. For the Value Coercion you can only give very general recommendations. For example for DateTime I would recommend not to accept values which also have time zones associated with it because time zones to offset is maybe not the conversion you want. But even this is just a recommendation and a specific implementation in Ruby might choose to ignore it.

Hope that make sense.

[eapache]

For example 12133242323523523 is not a valid value for Int but it is valid syntax and therefore can be used as input for a custom Scalar BigInt for example

Ah that makes sense. But since Value Coercion can take anything, Literal Coercion is still basically just a subset of Value Coercion?

[ardatan]

This link is outdated :)

[andimarek]

@eapache Only in the sense that both feed into to the resolver as arguments. Sure, you are free to decide to implement them very similar or maybe even in one method, but there are fundamental differences:

Literal Coercion is clearly defined in the Scalars spec and must be implemented as defined.

Value Coercion is not defined in the Scalars spec as it is implementation specific. You will change it more often: for example when JavaScript introduces a new OffsetDateTime object (made up example) parseValue should accept this as input.

Regarding the implementation of both methods: one big difference is that for complex Ast inputs you need to take care of variable references for literal coercion.

For example: {currency: "EUR", value: $moneyValue} is a complex Ast referencing a variable and your parseLiteral needs to resolve it. (See here for a more details)

in terms of function signature (pseudo code):

parseLiteral(input: AstValue, variableValues: Map<string,Any>): Any

parseValue(input: Any): Any

Does this make the differences more clear?

[andimarek]

This is outdated and will be replaced with a new setup and implementation guide