[relay-compiler] Type-safe updaters for TypeScript

[tobias-tengler]

TypeScript supports specifying different getter and setter types since 5.1, so I've updated the type generation logic around @updatable and @assignable to work with TypeScript.

I've also updated the notice on the website and made the documentation around type-safe updaters available externally (if this is not wanted, just revert 33612d2).

Companion PR for @types/relay-runtime: DefinitelyTyped/DefinitelyTyped#66013 (Merged)

Closes #4212 #3965

[captbaritone]

Thanks for working on this! I've left some comments, but overall I think this should be possible to land.

[captbaritone]

In Flow this object, and updatableFragmentSpreadAndRegularSpread_2_updatable_user$data above is inexact (...). I don't have a good sense of why, but presumably that means we need some TypeScript equivalent? Or maybe it can be removed from the Flow types?

https://flow.org/en/docs/types/objects/#exact-and-inexact-object-types

[tobias-tengler]

How would such an inexact type be typed in Typescript, would it just be a union of

original_obj & { [k: string]: unknown };

Might need more input from some TypeScript wizard before I add this...

[captbaritone]

Maybe we can first start with understanding why its inexact in Flow? What breaks if we make it inexact? Is this specific to updatable fragments, or are all fragment keys inexact in Flow?

Maybe the semantics of TypeScript are different and we don't actually need them to be inexact in TypeScript.

[tobias-tengler]

In other places inexact objects are used for fragments, if their MaskStatus is unmasked. I know too little about how fragments work to infer why it would be important to have the same characteristics when updating a fragment...

I tried tracing the git log for an explanation of why an InexactObject was being used, but haven't found anything. @rbalicki2 you seem to have added the code, do you perhaps remember why the InexactObject was being used?

[tobias-tengler]

@captbaritone I addressed everything that I could, please give it another look 🙏

[captbaritone]

@tobias-tengler Thanks for the quick turn around. Left a few more comments.

Have you tried running this with a real TypeScript project? Does it generate valid types that appear to work with a minimal example of using typesafe updaters? Would love to have validation that this works end to end.

[tobias-tengler]

@captbaritone I've built an example here.

While testing I noticed that the babel-plugin-relay doesn't behave correctly.
When having an @assignable fragment, the generated artifact will only export a validate function, not an importable node. babel-plugin-relay doesn't yet know about this, so it tries to replace the graphql tag with an import - which fails of course, since there's nothing to import.

I've fixed this in dbcc8bb. Do you think that is fine? Meta probably uses another transform, if this hasn't led to issues for you yet, right?

If we want to go forward like this, I can also submit a PR for Next.js to update their transform. vite-plugin-relay should be covered by the update to babel-plugin-relay.

Note: The example project is only runnable, since I moved the @assignable fragment to another file that isn't being referenced. I tried to import the locally built babel-plugin-relay, but failed miserably...

[tobias-tengler]

@captbaritone sorry for the ping, I'm sure you're very busy, but I don't want this to stall. Could you take a look at my above comments or point out another member of the Relay Team that could do so?

[captbaritone]

Thanks for the ping and sorry for the delay. I'll look in the morning!

[captbaritone]

This is great! Can we split the addition of hashes into its own PR? After that I can import.

[tobias-tengler]

@captbaritone I moved the addition of the node to the following PR: #4409

[tobias-tengler]

@captbaritone @alunyov bump 🙈

[facebook-github-bot]

@captbaritone has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator.

[facebook-github-bot]

@monicatang merged this pull request in 9c7b92a.

[michaelmcneilnet]

Will this be released soon? This is a very valuable fix for us.

[tobias-tengler]

I think the team is thinking about cutting a 15.1.0 release soon, see #4440
Should probably be a few weeks out. if you can't wait you can always use the relay-compiler@main tag.