New Intersection Type

[yaacovCR]

As an alternative to "unions implementing interfaces" (graphql/graphql-spec#939), a new intersection type could be introduced that models the same behavior.

Spec PR: graphql/graphql-spec#941
Implementation PR: graphql/graphql-js#3550

Example Behavior

# SomeIntersection includes TypeA and TypeB below because only they declare implementation of SomeInterface
intersection SomeIntersection = SomeUnion & SomeInterface  

# AnotherIntersection only includes TypeC below because only TypeC declares implementation of AnotherInterface
intersection AnotherIntersection = AnotherUnion & AnotherInterface

union SomeUnion = TypeA | TypeB
union AnotherUnion = TypeA | TypeB | TypeC

interface SomeInterface {
  someField: String
}

interface AnotherInterface {
  anotherField: String
}

type TypeA implements SomeInterface {
  someField: String
}
type TypeB implements SomeInterface  {
  someField: String
  anotherField: String
}
type TypeC implements SomeInterface & AnotherInterface {
  someField: String
  anotherField: String
}

# to remove TypeA and TypeB from SomeIntersection
extend type intersection SomeIntersection = AnotherInterface

# to add TypeC to SomeUnion and transitively to SomeIntersection
extend type SomeUnion = TypeC 

# to add TypeB to AnotherIntersection and
# if above changes were also made, to add back TypeB to SomeIntersection
extend type TypeB implements AnotherInterface 

Motivation

intersection "implementing" interface

# generic types
interface Node {
  id: ID!
}

interface Connection {
  pageInfo: PageInfo!
  edges: [Edge]
}

interface Edge {
  cursor: String
  node: Node
}

type PageInfo {
  hasPreviousPage: Boolean
  hasNextPage: Boolean
  startCursor: String
  endCursor: String
}

# schema-specific types
interface Pet {
  id: ID!
  name: String
}

type Cat implements Pet & Node {
  id: ID!
  name: String
}

type Dog implements Pet & Node {
  id: ID!
  name: String
}

union HousePet = Cat | Dog

intersection HousePetNode = HousePet & Pet & Node

# house-pet-specific types
type HousePetEdge implements Edge {
  cursor: String
  node: HousePetNode # <<< This is unlocked by this PR
}

type HousePetConnection implements Connection {
  pageInfo: PageInfo!
  edges: [HousePetEdge]
}

# query
type Query {
  housePets: HousePetConnection
}

intersection "implementing" interface AND narrowing unions

# generic types
interface Node {
  id: ID!
}

interface Connection {
  pageInfo: PageInfo!
  edges: [Edge]
}

interface Edge {
  cursor: String
  node: Node
}

type PageInfo {
  hasPreviousPage: Boolean
  hasNextPage: Boolean
  startCursor: String
  endCursor: String
}

# schema-specific types
interface Pet {
  id: ID!
  name: String
}

type Cat implements Pet & Node {
  id: ID!
  name: String
}

type Dog implements Pet & Node {
  id: ID!
  name: String
}

type Fish implements Pet & Node {
  id: ID!
  name: String
}

type Lion implements Pet & Node {
  id: ID!
  name: String
}

union HousePet = Cat | Dog | Fish
union PetWithFur = Cat | Dog | Lion

intersection HousePetWithFurNode = HousePet & PetWithFur & Pet & Node

# house-pet-specific types
type HousePetWithFurEdge implements Edge {
  cursor: String
  node: HousePetWithFurNode  # <<< This is unlocked by this PR
}

type HousePetWithFurNodeConnection implements Connection {
  pageInfo: PageInfo!
  edges: [HousePetWithFurEdge]
}

# query
type Query {
  housePetsWithFur: HousePetWithFurNodeConnection
}

Tradeoffs between intersections and simply allowing unions to declare "implementation" of interfaces

1. What would happen if you wanted to add a type to your union that doesn't implement the interface? If we directly allow unions to implement interfaces, you couldn't do that without making some other change. You would basically be forced to (1) make the union no longer implement the interface, a breaking change, or (2) add a new, different union without the type that doesn't implement the interface. If we use intersections, you could add whatever types you wanted to the original union without fear.
2. With intersections, you can also create new unions that are intersections of the previous existing unions. I doubt anyone is clamoring for that, but you sure could do that.
3. This points the way toward higher-order abstract types in general. Working on this showed me that we could eventually allow unions to include abstract member types, which would potentially solve union does not allow sub-union or covariance graphql-spec#711

What are some of the downsides?

1. It's more complex than the unions implement interfaces solution.
2. Changing intersections by adding or subtracting abstract types can cause queries to break, so they are not so mutable. I'm not sure how bad that it is in practice. Adding abstract types can cause object types to no longer fulfill the intersection if they fulfilled the prior set but not the new abstract type. Removing an interface is breaking for the same reason that removing an interface from a type is breaking -- I think it's because it could break the type system, but not queries, but it's still a kind of breaking.

Open questions

1. If intersection types include interfaces that implement interfaces, should the ancestor interfaces be required to be listed explicitly within the intersection? (My answer: yes, just like with interfaces.)
2. Should intersection types be allow to include other intersection types? (My answer: no, the "child" intersection types should just be listed explicitly within the "parent.")
3. Should one be allowed to query fields directly on the intersection? (My answer: no, intersections that define no union members will have no fields guarantees, so for consistency fragments on intersections should never be allowed.)
4. What should be considered a "breaking change" with regard to an intersection? (My answer: anything that could remove an object type from the intersection or could remove an interface from the intersection.)

Example and further discussion for question 1

interface ParentInterface {
  someField: String
}

interface ChildInterface implements ParentInterface {
  someField String
}

type TypeA implements ParentInterface & ChildInterface {
  someField: String
}

type TypeB implements ParentInterface & ChildInterface {
  someField: String
}

union MyUnion = TypeA | TypeB

Should we allow:

intersection MyIntersection = MyUnion & ChildInterface

vs. requiring

intersection MyIntersection = MyUnion & ParentInterface & ChildInterface

As we can see for above, ancestor interfaces are already required for readability reasons on object and interface types. The same argument could be made here -- and I would tend to agree with it! Note that the spec/implementation PRs now implements this requirement.

Example and further discussion for question 2

interface SomeInterface {
  someField: String
}

type AnotherInterface {
  anotherField: String
}

type TypeA implements SomeInterface & AnotherInterface {
  someField: String
  anotherField: String
}

type TypeB implements AnotherInterface {
  anotherField: String
}

union MyUnion = TypeA | TypeB

intersection SomeIntersection = MyUnion & SomeInterface
intersection AnotherIntersection = MyUnion & AnotherInterface

Should we allow:

intersection IntersectingIntersection = SomeIntersection & AnotherIntersection

Or require:

intersection SomeIntersection = MyUnion & SomeInterface & AnotherInterface

One could argue that similarly to the required verbosity for interfaces, we should require intersections to explicitly list all of their members and not include any other intersections. The spec/PR now implements this requirement.

Example and further discussion for question 3

interface Pet {
  name: String
}

type Dog implements Pet {
  name: String
}

type Cat implements Pet {
  name: String
}

union DogOrCat = Dog | Cat

intersection DogOrCatPet = DogOrCat & Pet

type Query {
  dogOrCatPets: [DogOrCatPet]  
}

Should we allow:

{
  dogOrCatPets {
    name
  }
}

or require:

{
  dogOrCatPets {
    ... on Pet {
      name
    }
  }
}

An argument in favor of allowing the former is that for this particular intersection, name is always defined, so this should be fine. An argument against allowing could be just from theory => the intersection itself does not define any fields, it just does so transitively through the interface it includes, so it is "wrong" to allow querying on the type. Because some intersections may contain only unions and not have any fields, it might be simpler to "teach" intersections as being more similar to unions, and never allow querying for fields directly on the intersection. I lean against allowing it, but not strongly.

Example and further discussion for question 4

interface Named {
  name: String
}

interface AnotherInterface {
  anotherField: String
}

type Dog implements Named {
  name: String
}

union LandPet = Dog | Cat

intersection NamedLandPet= LandPet & Named

Intersection changes could break all sorts of queries. Adding another union or interface MAY remove types, if any of the previously included types are not in the newly added union or do not implement the newly added interface. For example, adding AnotherInterface to the intersection would cause all types to be dropped. Removing an interface could also break a type, for the same reason that removing an interface from an object type is breaking. Removing the last union causes all types to drop from the intersection.

Intersections are therefore to some degree more immutable than other types. The current implementation of this PR assumes that includes removal or addition of ANY constraining types within the results of findBreakingChanges. This could be pared back, as adding constraining types may not cause additional object types to drop if the new types are more expansive than the old. Removing a union should only cause types to drop if it is the last remaining union (at least as long as unions can only containing object types and not interfaces).

[rivantsov]

For example, adding AnotherInterface to the intersection would cause all types to be dropped.

well, this is insane then. So if I (human) looking at an Intersection definition, and I have to figure out what is there, at the end, what fields would be available for selection, I will have to go through the lists of types and interfaces, manually track who implements what and do all types implement all interfaces etc, So instead of helping me, human, it actually makes it much more difficult for me

The union-with-interfaces approach actually makes more sense. A union with a bunch of types and an interface makes it explicit for me (reader), that at least these fields are available in every one of the types, you do not have to go thru all types and verify it yourself.

[yaacovCR]

I think the most common use case would be SomeUnion & SomeInterface which is pretty much just as unclear to the reader as SomeInterface.

Meaning, if you have a field that returns SomeInterface, you are presuming that some types in the type system implement SomeInterface. The most common use case for the intersection would be if that you know that you do not want the field to return all possible types that implement SomeInterface, but rather just want a subset of those known types. I can't think of a use case for more complicated scenarios, and I agree that I think more complicated scenarios could quickly get more difficult to reason about.

[rivantsov]

... pretty much just as unclear to the reader as SomeInterface

I do not understand it at all, what is unclear about an interface?

you do not want the field to return all possible types that implement SomeInterface

who is YOU? the server side developer, designing and implementing GraphQL API and writing up its schema? He is then in full charge of implementation, and can ensure only those types are returned by the field resolver
If YOU is a client developer, reading the schema file, then for a field returning interface - it is not relevant, it is not his (client's) business what type it was that actually carried the fields to the output. It is implementation details (private stuff) and is not a public business. That's the whole point of using an interface! So the actual types are NOT visible to clients in response, only sets of fields

[yaacovCR]

... pretty much just as unclear to the reader as SomeInterface

I do not understand it at all, what is unclear about an interface?

I was referring to how you pointed out that in order to for the human reader looking at a schema to know what types are within an intersection, one has to do some legwork. The same is true about an interfaces to some degree. The human reader has to look elsewhere in the schema. In fact, in the typical example of a simple SomeUnion & SomeInterface, it might be quicker for a human to know what is within the intersection, as if there are only a few types within SomeUnion, one only has to check those types to see if they implement SomeInterface whereas to know what is a possible type of SomeInterface on its own, you would have to scan through all the types within the schema. I imagine you would point out that you weren't talking about the simple case, you were talking about a more complex case, and I suppose we could debate whether the difficulties with the more complex cases should limit introduction of this type.

you do not want the field to return all possible types that implement SomeInterface

who is YOU? the server side developer, designing and implementing GraphQL API and writing up its schema? He is then in full charge of implementation, and can ensure only those types are returned by the field resolver If YOU is a client developer, reading the schema file, then for a field returning interface - it is not relevant, it is not his (client's) business what type it was that actually carried the fields to the output. It is implementation details (private stuff) and is not a public business. That's the whole point of using an interface! So the actual types are NOT visible to clients in response, only sets of fields

The schema is a shared construct/contract between the client and the server. It is possibly introspectable, almost always (always?) at least with the __typename meta field, and so it may be beneficial to actually list that only a subset of the schema's types are possible to be returned.

Take for example, a schema with a root type pets returning a list of base Interface type called Pet, i.e. [Pet]:

Once the client knows that the Pet interface is implemented by types called Cat and Fish, and assuming a name field on Pet, clients may construct a query as so:

pets {
  name
  ... on Cat {
    meows
  }
  ... on Fish {
    hasWhiskers
  }
}

What is the schema evolved to include a root query field called furryPets that never returned Fish but only returned items of type Cat (or Dog), etc?

One could introduce a new interface FurryPet that was the same as Pet and have only Cat and Dog implement it. Then the client would know never to introduce the Fish fragment on the query, it would fail validation. Or, one could introduce a union called FurryPet that included only the furry pets. If one introduced the union, and once wanted to make explicit that the union implemented an interface, one would either have to introduce that terminology as a constraint, or introduce the Introspection type.

[yaacovCR]

Meaning, the types returned are meant to be visible to the client, so they can correctly then request the fields they need on those types. Even when using interfaces, the set of possible types returned are also important, as the query can be enriched with additional fields that are type specific, aside from the fields on the interface.

[yaacovCR]

Finally, thanks especially for the async feedback here prior to the WG meeting, it's very helpful and appreciated.

[rivantsov]

you're welcome

On one statement only:

to know what is a possible type of SomeInterface on its own, you would have to scan through all the types within the schema.

you do NOT need know who implements interface, normally. Maybe just out of curiosity.
In fact, it might be that there are NO types implementing interface in the schema. Just quickly checked with the spec, seems like it is not required that interface implemented by any type.
But still, not implemented interface can be returned by a field - I do not see why not. At runtime the server returns set of field values in json; how it is produced is server's private business

[rivantsov]

quick question - is there any similar concept to Intersection, in any programming languages? Because for other things like interfaces, we can fall back on our pre-existing knowledge in programming. Here I am afraid there's nothing to fallback on? is this why I am so confused and still not getting the concept?

[yaacovCR]

https://en.m.wikipedia.org/wiki/Intersection_type

[rivantsov]

no, that does not make it as an example of Intersection in other languages; it is a syntactic sugar, just named Intersection.
In TypeScript - just a shortcut to define what is in fact method overloading.
In c# - the article references a discussion about introducing unions and intersections, had been going since 2019, does not look like going anywhere. But it is again mostly a syntax sugar, shortcut, shorter way to write what you can already do. Like catch block:

catch(SomeException|OtherException|ThirdExc ex)

or making things like
if (x is ISomeInterface&IOtherInterface) ...

They do not declare it as distinct type reusable elsewhere. Just a shorter way for multiple catch blocks or 'is' statements

[yaacovCR]

I am relying personally on my experience with TS, where intersections and unions are both valid operations on types. In GraphQL we (currently!) represent each type operation as a separate type, although that's a bit misleading, as unions are the only currently existing type operation. But, from my understanding, the intersection type I am introducing here matches what TS can do for output types as well. I see that the introductory text is unfortunately more about inputs, but I believe the same is true about outputs, although please correct me if I am wrong. I am looking forward to input from others in the WG who I am sure are more experienced with a wider array of languages where intersections are or are not used.

[yaacovCR]

Summary:

Motivation:

# generic types
interface Node {
  id: ID!
}

interface Connection {
  pageInfo: PageInfo!
  edges: [Edge]
}

interface Edge {
  cursor: String
  node: Node
}

type PageInfo {
  hasPreviousPage: Boolean
  hasNextPage: Boolean
  startCursor: String
  endCursor: String
}

# schema-specific types
interface Pet {
  id: ID!
  name: String
}

type Cat implements Pet & Node {
  id: ID!
  name: String
}

type Dog implements Pet & Node {
  id: ID!
  name: String
}

# house-pet-specific types
type HousePetEdge implements Edge {
  cursor: String
  node: HousePetNode  # <<< how can we define HousePetNode to allow this?
}

______ HousePetNode = __________

type HousePetConnection implements Connection {
  pageInfo: PageInfo!
  edges: [HousePetEdge]
}

# query
type Query {
  housePets: HousePetConnection
}

Use regular unions

If we define HousePetNode as union HousePetNode = Dog | Cat, since Dog and Cat both implement Node, we could have the type system simply deduce that the HousePetEdge type indeed implement Edge.

Pro: simple.
Con: if an additional type is introduced to HousePet that does not implement Node, this would somewhat surprisingly break HousePetEdge

Use unions with additional constraint

If we define HousePetNode as union HousePetNode implements Pet & Node = Dog | Cat, we have explicitly constrained the union. Now the type system explicitly knows that HousePetEdge type implements Edge.

Pro: One cannot introduce a type to HousePetNode that does not implement Node!
Con:

1. implements keyword is a bit misleading, as it is the member types that implement the interface
2. One cannot introduce a type to HousePetNode that does not implement Node, same as the pro, so if there does indeed for some reason exist such a type, we may end up needing a simple HousePet type as well, see below where we need both types.

Use intersections

If we define HousePetNode as intersection HousePetNode = HousePet & Pet & Node and HousePet as HousePet = Dog | Cat, we have explicitly constrained the union with a new type. Now the type system explicitly knows that HousePetEdge type implements Edge.

Pro:

1. One cannot introduce a type to HousePetNode that does not implement Node!
2. If one does, it would go into HousePet and not into HousePetNode. Nothing is broken.
   Con:
3. we have added a new type and all the complexity that comes with it

Use duplicate interfaces

We can define HousePetNode as interface HousePetNode implements Node { node: ID } and add the HousePetNode interface to the list of interfaces for Dog and Cat.

Pro:

1. No additional syntax.
   Con:
2. We have weakened the expressivity of the type system compared to the other solutions, as this solution does not scale well if we have a multitude of identical interfaces.

[yaacovCR]

Summary of discussion from WG https://github.com/graphql/graphql-wg/blob/main/agendas/2022/2022-05-05.md :

union HousePet implements Node was overwhelmingly felt to be best because it is (1) expressive (2) concise (3) less complex (4) will lead to early validation error, which overall would be most valuable. Intersections were felt to be powerful tools that would then propagate a small number of breaking changes to a large number of dangerous and --more importantly-- possibly silent errors!

The action item will then be to move forward as possible with graphql/graphql-spec#939 . Immediate next steps is to refine the implementation at graphql/graphql-js#3527 with further checking for all the necessary validation and test changes.