Design

Type System

The type system that powers most of the Pothos type checking has 2 components. The first is the SchemaTypes type param passed into the SchemaBuilder. This allows a shared set of types to be reused throughout the schema, and is responsible for providing type information for shared types like the Context object, and any Object, Interface, or Scalar types that you want to reference by name (as a string). Having all type information in a single object can be convenient at times, but with large schemas, can become unwieldy.

To support a number of additional use cases, including Unions and Enums, large schemas, and plugins that extract type information from other sources (eg the Prisma, or the simple-objects plugin), Pothos has another way of passing around type information. This system uses Ref objects whose TypeScript types carry the backing shapes they represent. Every builder method for creating a type or a field returns a Ref object.

Using Ref objects allows us to separate the type information from the implementation, and allows for a more modular design. For example, builder.objectRef<{ id: string }>('User') declares the backing shape before fields are defined with implement. The ref carries that shape at compile time and identifies the GraphQL type at runtime; it does not validate resolver values at runtime. See Objects and Circular References for examples.