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

Support generation of the prelude.graphql based on graphql-js #344

Merged
merged 1 commit into from
Jan 28, 2025

Conversation

StevenACoffman
Copy link
Collaborator

@StevenACoffman StevenACoffman commented Jan 28, 2025

Updating this parser to match revisions to the GraphQL Spec is currently very manual (and error prone), so I (and some awesome contributors!) don't do it often.

New versions of the GraphQL Spec are released infrequently, if ever. However, more commonly the graphql-js reference implementation is updated to include draft GraphQL spec changes and is the new defacto GraphQL standard. (Maybe that's what they meant by client-driven development? 😆 )

In order to update this parser to support new GraphQL Spec versions (and drafts), a contributor needs to export from graphql-js:

$ cd ./validator/imported
# update to latest
$ rm graphql-js-commit.log && ./export.sh

# re-generate with known revision
$ ./export.sh

They would then need to manually update the validator/prelude.graphql file, validator/schema.go file, and possibly other files relevant to those specific changes like ./validator/rules/, etc.

One part of the manual prelude.graphql update process was copying the draft spec spec for introspection from here: https://spec.graphql.org/draft/#sec-Schema-Introspection.Schema-Introspection-Schema

@CodingContraption went through this and helpfully described the prelude.graphql update process:

After that, I did notice that the oneOf directive was introduced, which I manually added as well.

One thing I did notice is that the graphql-js/src/utilities/__tests__/printSchema-test.ts file appears to test printing a full introspection schema, which is effectively the same to the prelude.graphql save for some changes to docs & missing the builtin scalars. Perhaps that could be something to leverage?

@CodingContraption has since updated the prelude.graphql update process to be less manual, and I've made this PR based on their work that they describe like this:

I've tinkered a bit with the export.js script, and I did manage to generate a prelude.graphql file using graphql-js, but I did still have to append hardcoded text for the builtin scalars & the @defer directive to achieve parity with the current prelude.graphql file.

This change is a huge win for the entire community! Updating a GraphQL parser to incorporate any new revisions is a very intimidating prospect for most folks, and this now makes it fully automatic for some spec changes. For more invasive spec changes, it makes the process a lot less error prone and much quicker to get to exactly where the real work needs to happen.

It also sets us up for possible future improvements, like getting the prelude.graphql portions for @defer and the basic scalars to be generated from graphql-js (... somehow?).

I also want to acknowledge that this change further builds on the prior work of @Code-Hex @vvakame and others in #181 and before.

Also worth mentioning, the most recent update #342 still required a manual update process to gqlgen 99designs/gqlgen#3507

@coveralls
Copy link

Coverage Status

coverage: 87.576% (+0.06%) from 87.519%
when pulling 715dc9b on CodingContraption:master
into 28ef20a on vektah:master.

@StevenACoffman StevenACoffman merged commit 23ba15b into vektah:master Jan 28, 2025
5 checks passed
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