[Rough Draft] Document Relay Resolvers #4547
Conversation
| @@ -70,7 +70,7 @@ Flow users will now get types inferred from `graphql` literals with more Relay A | |||
|
|
|||
| ### Relay Resolver improvements | |||
|
|
|||
| A significant portion of our development effort since our last release has gone into improving [Relay Resolvers](https://relay.dev/docs/guides/relay-resolvers) (a mechanism for exposing derived data in the graph). It is worth noting that Relay Resolvers are still experimental and API changes might occur in the future. | |||
| A significant portion of our development effort since our last release has gone into improving [Relay Resolvers](https://relay.dev/api-reference/relay-resolvers/introduction/) (a mechanism for exposing derived data in the graph). It is worth noting that Relay Resolvers are still experimental and API changes might occur in the future. | |||
There was a problem hiding this comment.
Is the last sentence still applicable after we release them as stable? Maybe we can remove the "Relay Resolvers are still experimental" bit
There was a problem hiding this comment.
I think it's okay for a blog post to be a point in time artifact. That said, maybe I can add and an "update" section.
|
|
||
| ## Syntax | ||
|
|
||
| When defining a field string after `@RelayResolver` is a GraphQL `TypeName` followed by a dot followed by the field |
There was a problem hiding this comment.
Nit - Suggestion for clarity (IMO)
| When defining a field string after `@RelayResolver` is a GraphQL `TypeName` followed by a dot followed by the field | |
| Relay resolvers are marked via docblocks above a resolver function. | |
| `@RelayResolver` is the tag to indicate the start of any relay resolver definition. | |
| To define a field on a GraphQL model type `TypeName`, add `TypeName` followed by a dot followed by the field |
…eference that focuses on the actual APIs
|
@captbaritone has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator. |
| export function counter(): LiveState<number> { | ||
| return { | ||
| read: () => store.getState().counter, | ||
| subscribe: (cb) => { |
There was a problem hiding this comment.
A more descriptive name (like "callback") or a typehint would do wonders here. cb is a bit opaque.
There was a problem hiding this comment.
Good point. Thanks for pointing that out. Will fix.
| * @RelayResolver ProfilePicture | ||
| * @weak | ||
| */ | ||
| export type ProfilePicture = { url: string, height: number, width: numbe }; |
There was a problem hiding this comment.
Small typo here should be width: number
|
|
||
| ### Defining a “strong” type | ||
|
|
||
| Strong types ar defined by a docblock followed by an exported function whose name matches the type's name, and which accepts an ID as its first argument and returns an instance of the type’s model [TODO link]. Resolvers that define edges to this type will simply need to return the ID of the object, rather than deriving the model themselves. |
There was a problem hiding this comment.
is it right that the model resolver can only accept one argument (the id argument)? Seems to be the case when I tried it. IIUC, instead of "first" argument we can say "only"?
| ``` | ||
|
|
||
| :::note | ||
| Relay will takes care of efficiently recomputing resolvers when any of their inputs (in this case the model instance) change, so you don’t need to worry about memoizing your resolver function. |
There was a problem hiding this comment.
| Relay will takes care of efficiently recomputing resolvers when any of their inputs (in this case the model instance) change, so you don’t need to worry about memoizing your resolver function. | |
| Relay will take care of efficiently recomputing resolvers when any of their inputs (in this case the model instance) change, so you don’t need to worry about memoizing your resolver function. |
| } | ||
| ``` | ||
|
|
||
| See the [Weak Types](../../guides/relay-resolvers/defining-types.md#Defining a “weak” type) guide for more information including how to define an edge to a weak type. |
|
@captbaritone merged this pull request in 51a82f6. |
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-runtimemodule 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:
LiveStatetype fromrelay-runtimeroot