@preloadable support

[tomgasson]

Placeholder PR to check plans, before I proceed with the implementation.

My understanding of @preloadable:

• Created when you use the @preloadable directive on an Query
• Generates a <Query>$Parameters.js file, which exports {kind: "PreloadableConcreteRequest", params: PARAMS} where PARAMS is the exact same as the params in the operation, of type PreloadableConcreteRequest<Operation$variables, Operation$data, Operation$rawResponse>
• When you load the JS code for the entrypoint, that naturally brings the Query's full artifact (via the consumer using it in usePreloadedQuery)
• The Query artifact additionally calls PreloadableQueryRegistry.set(node.params.id, node). This is used to unblock the usage of the query when the full metadata is loaded.

Questions:

• Should the preloadable artifacts be generated as part of the build phase, or commit phase?
  • Commit:
    • Similar to how it's done in generate_extra_artifacts at Meta currently
    • I'd create them just before generate_extra_artifacts_fn is called in commit_project, as ArtifactContent::Generic items
  • Build:
    • Means producing them in build_project->generate_artifacts
    • Allows creating a ArtifactContent::PreloadableOperation and re-uses the artifact ArtifactContent::as_bytes mechanism and much of the other code in that space
• Should the type PreloadableConcreteRequest remain in the react-relay package? The compiler doesn't have other references to react-relay. I can introduce a mechanism in ArtifactGeneratedTypes to collect and organise imports & sources together or move PreloadableConcreteRequest into relay-runtime
• Meta generates virtual id files (named <Operation>_facebookRelayOperation). What's this for? Is this needed in OSS?
• Has there been any consideration of the Query artifact importing the params from the PCR (as a JSModuleDependency) rather than duplicating them?
• Are there other aspects I haven't captured here? Can you confirm that Meta doesn't have additional static-resource processes necessary here that I'm missing?

I'd appreciate any pointers you can share from Meta's impl of generate_extra_artifacts / generate_virtual_id_file_name

cc @voideanvalue

[alunyov]

Sorry for dropping the ball on this PR.

Should the preloadable artifacts be generated as part of the build phase, or commit phase?
Commit:

I think this would be the most feasible path forward, and compatible with what we have internally. This is most likley would be much easier to land, because it won't interfere with the existing codegen we have internally, where the @preloadable artifacts created as part of generate_extra_artifacts. We may reconsider this in the future, and make @preloadable a "real" artifact.

Should the type PreloadableConcreteRequest remain in the react-relay package? The compiler doesn't have other references to react-relay

I think it is fine to move it to relay-runtime and re-export it react-relay. The OSS version of the codegen then can use relay-runtime import.

Meta generates virtual id files (named _facebookRelayOperation). What's this for? Is this needed in OSS?

It is internal optimization that tightly coupled with the way the query persisting work on WWW. I don't think I can think of a good abstraction for that in OSS, we probably may skip this. We also don't use that in React Native, for example.

Has there been any consideration of the Query artifact importing the params from the PCR (as a JSModuleDependency) rather than duplicating them?

I think this is just happened - the duplication of these parameters, and now, to change that we need to update many-many artifacts - a complex rollout without a clear benefit.

Are there other aspects I haven't captured here? Can you confirm that Meta doesn't have additional static-resource processes necessary here that I'm missing?

Overall, the summary and the PR implementation is correct. TL;DR - @preloadable can generate a file with minimal information to fetch the query (query text or query id) - this artifact can be used with preloading/router infra (in entry points) to start fetching the query earlier without loading the full query AST for the normalization.

[tomgasson]

Awesome - thanks for all that info. I'll refresh this implementation onto master and iterate from there

[tobias-tengler]

@tomgasson @alunyov I'm currently playing with EntryPoints and really wanted to test out @preloadable, so I started another PR where I have iterated on your initial implementation @tomgasson to also add TypeScript support: #4515

I'm also going to move the PreloadableConcreteRequest<T> type to @types/relay-runtime as discussed in this thread.

@tomgasson If you want to to be attributed further, just let me know. I can add you as Co-Author on my commits :)

[tomgasson]

@tobias-tengler Nice! Happy for you to take this on. I don't need attribution, just after the outcomes 😄

[sibelius]

should we close this?

related work #4515