Support named imports in graphql transformer

[squirly]

🙋 feature request

Some graphql tooling supports named imports. See examples below.

🤔 Expected Behavior

#import MyFragment1, MyFragment2 from './common.graphql'

query MyQuery {
  stuff {
    ...MyFragment1
    ...MyFragment2
  }
}

😯 Current Behavior

The import is ignored.

💁 Possible Solution

Use the plugable Document Loading from @graphql-toolkit/core. This supports custom file loaders that can interop with the Parcel loading logic.

This will require reworking the current implementation to do full AST parsing and combining of the GraphQL.

The AST would need to then be printed out and could also be minified, see stripIgnoredCharacters.

🔦 Context

I am using shared fragment files in various graphQL files. Other tooling that I am using does not allow unused fragments in a document.

💻 Examples

See https://github.com/ardatan/graphql-import#usage

[mischnic]

That would be a transformer that runs before the existings @parcel/transformer-graphql (which should in that case be renamed to something like @parcel/transformer-graphql-js) and essentially inlines the import (if I understand that feature correctly).

[squirly]

Interesting. I would be happy to make these changes.

Have a couple of questions before I get started:

• Renaming:
  • Should this rename or be a new package in Parcel? "transformer that runs before" and "be renamed to" are conflicting.
  • What are the reasons why this cannot be a part of the existing @parcel/transformer-graphql? It should be relatively easy to make it backwards compatible, and adds onto the existing import implementation.
• Inlining:
  • I believe it is a bit more complicated than inlining, which is the current behaviour in parcel ones, which uses an inline import: #import './IncludeMe.graphql'.
  • This new behaviour would need to extract and inline a part of the imported file, I think using the graphql AST parse would make the most sense for this.
  • Does this pose any issues with how Parcel transforms files?
• Minification (I may make a separate issue for this or not do it at all):
  • What kind of logic should be applied for minification? Is there some configuration that indicates the transformer should minify? Is this a completely separate step? Seems like "Optimizing" and "Transformers" are seperate. But minifying after the fact may be tricky.

[mischnic]

What are the reasons why this cannot be a part of the existing @parcel/transformer-graphql? It should be relatively easy to make it backwards compatible, and adds onto the existing import implementation.

Is this a standard graphql syntax? Then I'd say it's fine in @parcel/transformer-graphql

If not, maybe someone wants to use a different library with a different behaviour and the same syntax. In that case they would have to duplicate some of the code in @parcel/transformer-graphql (the gql to js part)

Does this pose any issues with how Parcel transforms files?

I didn't quite understand what you are referring to. But generally there are two mechanism in Parcel for "bundling":

1. a transformer just modifies the one asset and leaves the merging to a packager (done with JS, CSS, HTML
2. in case (1) is overkill (I would say this is the case here) or not possible (e.g. with the Less compiler or Pug or PostCSS plugins that need access to imported files) you can do everything in the transformer and tell Parcel via addIncludedFile that there are some files that Parcel doesn't yet know about and should be watched.

Does this answer your question?

Should this rename or be a new package in Parcel?

A new package (or not, see previous point). The existing package is called @parcel/transformer-graphql but that doesn't convey the meaning "to js", especially if we have multiple graphql-related packages.

What kind of logic should be applied for minification? Is there some configuration that indicates the transformer should minify?

If there are some specific options to enable optimizations, these can be applied based on options.minify or options.mode. So a Rust transformer might want to change the compiler optimization levels. Terser is run after the bundles are generated, so that it can do cross-asset optimizations.

[squirly]

Thanks for the excellent clarifications!

Sitting on this overnight I think I have a clearer proposal:

• @parcel/transformer-graphql-js:
  • Rename @parcel/transformer-graphql to @parcel/transformer-graphql-js
  • Remove the current import support, which is not and will not be included in the graphql spec.
  • Apply minification using stripIgnoredCharacters based on the options.minify or options.mode.
• @parcel/transformer-graphql-import:
  • Resolves graphql #import macros
  • Supports as compatible many syntaxes as feasible. I believe Document Loading from @graphql-toolkit/core will get this very close but will write some test cases to validate.
  • Support prefix /# *import/ (REGEX)
  • Suport import all:
    • #import './include-me.graphql'
    • #import * from './include-me.graphql'
  • Support partial import:
    • #import MyFragment1, MyFragment2 from './include-me.graphql'
  • We can split into multiple packages if there are incompatible import syntaxes.
  • Use addIncludedFile to signify files to watch.

Let me know if this makes sense and I can get started on this.

[mischnic]

I think we should just put everything into @parcel/transformer-graphql for now (unless there are two very popular but completely incompatible syntaxes). The import part can always be refactored out afterwards.

based on the options.minify or options.mode.

I think minify would make the most sense here.

I can get started on this.

👍

[squirly]

Further clarifications in: https://spectrum.chat/parcel/contributing/differentiation-of-assets-and-transformers~7d7deb5b-3d17-4d35-986d-d9b1a9c14149

[wbinnssmith]

Is this a part of the official GraphQL specification? If not, I'm not sure this should belong in the transformer maintained by Parcel.

[DeMoorJasper]

@wbinnssmith imports are not part of the graphql spec, but we did already support that in Parcel 1 so it seems fair to continue to support it in Parcel 2. Without imports graphql would be just a txt file and an inline transformer or fs.readfileSync would probably be the same.