Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add implementation guide #2

Closed
wants to merge 1 commit into from
Closed

Conversation

andimarek
Copy link
Collaborator

@andimarek andimarek commented Jun 25, 2020

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 eapache mentioned this pull request Jul 6, 2020
@eapache
Copy link
Member

eapache commented Jul 6, 2020

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.

}
```

## Result Coercion: Serialize or not
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@andimarek
Copy link
Collaborator Author

@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
Copy link
Member

eapache commented Jul 7, 2020

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?


https://www.graphql.de/blog/scalars-in-depth/

https://www.apollographql.com/docs/graphql-tools/scalars/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link is outdated :)

@andimarek
Copy link
Collaborator Author

andimarek commented Jul 7, 2020

@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?

Base automatically changed from master to main February 3, 2021 05:12
@andimarek
Copy link
Collaborator Author

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

@andimarek andimarek closed this Oct 15, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants