[Epic] Client fields that return IDs

[rbalicki2]

• Client fields currently are scalars, in the sense that you cannot use {}, as in my_client_field { ... }.
• Client fields should be able to return IDs, in which case, you would be able to do best_friend_client_field { name }
• This needs additional thought:
  • How do we enable lazy fetching? As in, we calculate best_friend_client_field, and then execute the operation node(id: $bestFriendId) { ... on User { name } }
  • Do we want to force the user to opt into this? (As in the @waterfall directive in Relay?)
• The syntax I'm thinking of is pointer Type.fieldName to Type { ... }

[rbalicki2]

an open question: if we're going to use these for graphql type refinment (which IMO is a good idea and is the right abstraction), then the (auto-generated) pointer would look like this, if it were user written:

# note the optional User type here... "to User", not "to User!"
iso(`pointer Node.asUser to User {
  __typename
  id
}`)(({data}) => {
  if (data.__typename === 'User') {
    return data.id;
  }
})

Given this, it would be natural for us to treat asFoo as a loadable field (ish), i.e. when it is read, it must be passed to useClientSideDefer, then the data is fetched with a separate request.

That's fine! It's a good v1! It's something we should implement anyway. But we need some way to indicate that this field can be merged into the parent (via ... on User). So, probably, there will be two types of pointers: mergable and non-mergable. All user-written pointers will be non-mergable (because, how would we know what to do?) (Maybe when there is a server component, all pointers can be mergable!)

The user should be able to unmerge a mergable pointer, e.g. with an @annotation on the pointer selection.

---

That field results in a query like

query node(id: $idThatIsTheResultOfCallingNodeasUser) {
   ...WhateverOtherFields
}

[rbalicki2]

I think we can probably implement user-generated pointers separately from non-user generated pointers, even though they use the same infra. With that in mind, the following are some ideas for subtasks here:

Tasks for both generated pointers (i.e. inline fragments) and user-defined pointers:

• add schema.client_pointers: Vec<ClientPointer>. FieldType should have a new variant: ClientPointer. Add ClientPointerId.
• modify validation to allow ensure client pointers always have selection sets
• modify validation to ensure that client pointers are selected correctly (same rules as fields)
• generate a reader AST node for client pointers (where it is read)
• generate a Type/PointerName/resolver_reader.ts (Node/asUser/resolver_reader.ts) file, or something, that includes the reader AST and the resolver. For auto-generated pointers, the resolver will be inlined, otherwise, it will be imported.
• merge into the normalization AST the pointer's reader AST (i.e. __typename and id presumably)
• generate a "refetch query" for the selection set underneath the client pointer
• modify read.ts to treat the client link as a loadable field. (For generated pointers, the loadable field will have all of the data present already, so calling useClientSideDefer will avoid going to network, and we will immediately have the data)

Tasks for generated pointers

• emulate add_fields_to_subtypes, and add client pointers to subtypes. These can have names asConcreteTypeName, I suppose.
• ☝️ the resolver_reader.ts will have to have a function inlined
• merge into the normalization AST the merged pointer and its selection set, i.e. something like ... on User { subfields }. (Merged selection sets already support inline fragments! Woohoo!)

Tasks for user defined pointers

• add syntax support for pointer iso definitions
• add support to babel
• add client fields to iso.ts
• add types to constrain the function passed to the pointer iso literal, i.e. ensure that it returns an ID (at first, that will just be a string! See Client pointers: make ID types generic #206 for future direction)

It's a lot of work, but IMO each task is doable!!!! Let's get this show on the road!!!!

[rbalicki2]

On hold, in favor of #230