[Rough Draft] Document Relay Resolvers

[captbaritone]

trafficstars

For the last few years we've been experimenting with expanding Relay Resolvers to allow them to return client state that can change over time. We are now close to releasing this new capability as a stable part of Relay, and so these docs my initial stab at documenting their full feature set. I expect these docs will go through a few revisions before we land, so they still have a few "TODO"s scattered around in the docs (and in this PR).

Warning

These docs document the API we expect to ship. Today it still requires enabling both compiler and runtime feature flags, and using a special instance of the Relay Store. Additionally, some of the types and values what will be exported as top level exports of the relay-runtime module are not yet exported. Following these docs today is not expected to work Thanks for your patience!

TODO

List of work items still to be done for these docs:

• [ ] Ensure we expose the LiveState type from relay-runtime root
• [ ] Decide on canonical name for Live Resolvers ("live data?", "live resolvers?", "live fields?")
  • [ ] How does this align with "derived fields"
• [ ] Unify around name for "client schema". Client resolver schema? Client state schema?
  • [ ] This is confusing because we already have client schema extensions
• [ ] What about type exports for TypeScript?
  • [ ] LiveState
  • [ ] SuspenseSentinel
• [ ] Expose our live resolver batching method directly on Relay environment
• [ ] I think that we currently allow Resolver types to be @deprecated, but in documenting this, I realized that we the spec does not actually allow this.

[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]

@captbaritone merged this pull request in facebook/relay@51a82f698aab0c9ea89e62c2c3857cfe63838bda.