Interface & Union Types

GraphQL union & interface types are both ways to allow a GraphQL field to return one of a set of object types.

The difference between the two is that interface types declare a common set of fields that must be implemented by the object types that implement the interface, while union types declare a set of object types and those objects don’t have to share any fields.

Interface Types

In @graphql-ts/schema, you can define interface types using the g.interface function and then use the interfaces option on object types to declare that the object type implements the interface:

schema.ts

const Entity = g.interface()({
  name: "Entity",
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
});

type UserSource = { __typename: "User"; id: string; name: string };
const User = g.object<UserSource>()({
  name: "User",
  interfaces: [Entity],
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
});

type OrganisationSource = {
  __typename: "Organisation";
  id: string;
  name: string;
};
const Organisation = g.object<OrganisationSource>()({
  name: "Organisation",
  interfaces: [Entity],
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
    members: g.field({ type: g.list(User), resolve: () => [] }),
  },
});

schema.graphql

interface Entity {
  id: ID!
  name: String!
}

type User implements Entity {
  id: ID!
  name: String!
}

type Organisation implements Entity {
  id: ID!
  name: String!
  members: [User]
}

type Query {
  entity(id: ID!): Entity
}

query.graphql

query {
  entity(id: "123") {
    id
    name
    ... on Organisation {
      members {
        id
      }
    }
  }
}

Union Types

Union types are defined using the g.union function:

schema.ts

type UserSource = { __typename: "User"; id: string; name: string };
const User = g.object<UserSource>()({
  name: "User",
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
});

type PostSource = { __typename: "Post"; id: string; title: string };
const Post = g.object<PostSource>()({
  name: "Post",
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    title: g.field({ type: g.nonNull(g.String) }),
  },
});

const SearchResult = g.union({
  name: "SearchResult",
  types: [User, Post],
});

schema.graphql

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

union SearchResult = User | Post

type User {
  id: ID!
  name: String!
}

type Post {
  id: ID!
  title: String!
}

query.graphql

query {
  search(query: "graphql") {
    __typename
    ... on User {
      id
      name
    }
    ... on Post {
      id
      title
    }
  }
}

resolveType and isTypeOf

In the examples above, we have included __typename fields on the source objects. By default GraphQL.js uses __typename to determine what concrete object type is being returned when returning a union or interface type.

There are also two other options:

• resolveType on a interface/union types, this accepts a source type and returns the object type name that it corresponds to
• isTypeOf on object types, this accepts a source type and returns a boolean indicating if the object type is the correct type for the source type

You can use either one, you don’t need to use both.

const Entity = g.interface<{ entityType: string }>()({
  name: "Entity",
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
  resolveType(source) {
    return source.entityType;
  },
});

type UserSource = { entityType: "User"; id: string; name: string };

const User = g.object<UserSource>()({
  name: "User",
  interfaces: [Entity],
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
});

const Entity = g.interface()({
  name: "Entity",
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
});

type UserSource = { entityType: "User"; id: string; name: string };
const User = g.object<UserSource>()({
  name: "User",
  interfaces: [Entity],
  fields: {
    id: g.field({ type: g.nonNull(g.ID) }),
    name: g.field({ type: g.nonNull(g.String) }),
  },
  isTypeOf(source) {
    return source.entityType === "User";
  },
});

Note

@graphql-ts/schema isn’t able to provide strong validation to ensure that you’re providing a __typename/correctly implementing resolveType/isTypeOf functions so be careful to ensure you’ve implemented it correctly.