Consolidate Input Union discussions

[binaryseed]

Over the years there have been many discussions around the topic of Input Unions in GraphQL. To help further the effort, we have begun building a single RFC document. The goal of this document is to consolidate all related ideas to help move the proposal forward.

• https://github.com/graphql/graphql-spec/blob/master/rfcs/InputUnion.md

To help this effort, I'd like @leebyron to consider commenting on & closing all related open Issues / PRs in favor of the main RFC document, which will contain & reference all of these previous discussions.

• Polymorphic input types Polymorphic input types #114 @luisobo
• RFC: inputUnion type RFC: inputUnion type #395 @tgriesser
• Input polymorphism Input polymorphism #415 @jayhasyee
• [RFC] GraphQL Input Union type [RFC] GraphQL Input Union type #488 @frikille
• [RFC] Input Objects accepting exactly @onefield [RFC] Input Objects accepting exactly @oneField #586 @benjie

@leebyron @IvanGoncharov

[dendrochronology]

Thanks for all your hard work in consolidating this @binaryseed, @benjie, et al!

To whom can I send virtual beers so this gets on the working group's agenda? 🍻

[benjie]

Thanks for the support and offer @dendrochronology; we discuss this frequently at working groups so it’s definitely already on our agenda :) We’re aiming to have the RFC doc updated by the next WG to enable participants to have a more informed discussion. It seems that there is no perfect solution (at least we haven’t found one yet!) so now it’s time to weigh up the different proposals and find out which trade-offs we can/can’t live with, which ones are the easiest to implement cross-platform, and which features we need/want/don’t care about.

[binaryseed]

@leebyron Would you mind taking a look at this?!

[IvanGoncharov]

@binaryseed Terribly sorry for the delay.
I closed all the issues and will review all pending PRs to RFC tomorrow.
Anything else I can do before closing this issue?

[akomm]

I refer to this answer, I do not want to continue in the closed topic.

@benjie I have more and more the feeling, that the current graphql enumeration should have been more powerful in terms of its allowed values and work similar to how the proposed oneField works. Basically like the enums you have in rust (or similar languages ...).

The advantage is clear, you do not need an artificial discriminator. Neither on the input, nor output side. The option (=field) is the discriminator by itself.

It might be considered something long-term, maybe for graphql v2, as an enum replacement. Short/mid-termn oneField would be as close as possible to it - technically for the client almost the same and easy to migrate.

[benjie]

@akomm Thanks for the feedback :) One issue that @oneField doesn't allow for that GraphQL interfaces do allow for is spreading a shared fragment (e.g. an interface fragment) over a mixture of types. For example if you had products in a supermarket you might have:

interface Product {
  name: String!
  priceInCents: Int!
}
type Clothing implements Product {
  # ...
  size: String
}
type Food implements Product {
  # ...
  calories: Int
}
type Cleaning implements Product { ... }

type Query {
  search(query: String): [Product]
}

you might issue this request:

{
  search(query: "cream") {
    __typename
    ... on Product { name priceInCents }
    ... on Clothing { size }
  }
}

This allows you to display a common search interface for all your products displaying name and price; but for certain "supported" products you could enhance the display with extra metadata - e.g. size for clothing or calories for food. I'm not sure how you'd achieve this in the @oneField solution.

I think @oneField could have worked instead of unions; however the difference between unions and interfaces may have been odd. Ultimately I think we've got a fine solutions for output types (especially with the enhancements to interfaces that are currently being merged) but input types are a different beast and have different needs IMO.

[akomm]

@benjie is it really simpler in a practical situation? I think not only the query should be considered, but also working with the result on the client. The advantage in your example is that you get the data as a flat collection. But you also have to discriminate by a string value on __typename. With oneField you would do the same via the field. In both cases when you render data you will have some sort of delegation of the refined/discriminated type on the client side. Something like renderClothing, renderCleaning or let's say in react <Clothing /> and <Cleaning />. The difference here would be how you pass the data:

if (result.clothing) {
  return <Clothing data={result.clothing} />;
}
if (result.cleaning) {
  return <Cleaning data={result.cleaning} />;
}

vs.

switch (result.__typename) {
  case 'Clothing':
    return <Clothing data={result} />;
  case 'Cleaning':
    return <Cleaning data={result} />;
}

For this to properly type-check with typescript, the typing extracted from introspection must provide the __typename as a string literal union of all possible type names that implement the interface. I am not sure if that is possible via introspection. I will check it out asap. But for example the current implementation of relay-compiler with typescript language plugin does only expose the __typename as a string.

Comparison type emission for both interface & oneField:

interface Product {}
interface Clothing extends Product {}
interface Food extends Product {}
interface Cleaning extends Product {}
// This is needed for oneField
type Result = 
  | {clothing: Clothing}
  | {cleaning: Cleaning}
  | {food: Food}
// vs __typename that uses string literal union based on type names
type Result = 
  | ({__typename: 'Clothing'} & Clothing)
  | ({__typename: 'Cleaning'} & Cleaning)
  | ({__typename: 'Food'} & Food)

Actually, with strict setting the oneField one would not work. You would have to define it either like this:

type Result =
  | ({clothing: Clothing} & {cleaning?: undefined, food?: undefined})
  | ({cleaning: Cleaning} & {clothing?: undefined, food?: undefined})
  | ({food: Food} & {cleaning?: undefined, clothing?: undefined})

With ever growing list... Or alternative, make assertions, which is very ugly and can be done different ways, I do not even try it here... :)

As for the query. I would like to compare how you could do both with more data fetched to make clear, where the difference is:

query ProductSearchQuery {
  search {
    clothing {
      ...ProductData
      size
    }
    cleaning {
      ...ProductData
    }
    food {
      ...ProductData
      calories
    }
  }
}
fragment ProductData on Product {
  name
  priceIncents
}

vs

query ProductSearchQuery {
  search {
    __typename
    ... on Product {
      name
      priceIncents
    }
    ... on Clothing { 
      size 
    }
    ... on Food { 
      calories
    }
  }
}

But this is just the js/ts side of the client. There are obviously other languages to be considered where the picture might be a different one...

[benjie]

You raise an interesting point: should @oneField exclude the other fields entirely rather than returning nulls? I'd always imagined it returning nulls, but perhaps omitting the fields in the same way the @skip directive would makes sense. Then your type is just type Result = {clothing: Clothing} | {cleaning: Cleaning} | {food: Food} even in more strongly-typed languages than TypeScript.

Note that the Product interface could be implemented by hundreds of types, and you may only have special treatment for a few of them (Clothing, Food). With my code you can add more types to the Product interface later and without having to update your client or change the query your application will continue to work because it can rely on name and priceInCents always being present, even on types it didn't know about when it was released. This is one of the superpowers of interfaces.

[akomm]

The issue with the typing in TS with fully strict setting is, that you can not check for the variants. The keys can only be checked against when they are explicitly defined, even if the only possible value is null or undefined.

interface Product {}
interface Clothing extends Product {}
interface Food extends Product {}
interface Cleaning extends Product {}
// This is needed for oneField
type Result =
  | {clothing: Clothing}
  | {cleaning: Cleaning}
  | {food: Food}
 
function render(result: Result) {
  // TS2339: Property 'clothing' does not exist on type 'Result'.
  // Property 'clothing' does not exist on type '{ cleaning: Cleaning; }'.
  if (result.clothing) {} 
}

You would have to make assertions/type-guards for every product type.