SchemaBuilder

SchemaBuilder is the core class of Pothos. It can be used to build types, and merge them into a graphql.js Schema.

constructor<SchemaTypes>(options)

• typeParam: SchemaTypes: A type that describes the backing models for your schema
• options: SchemaBuilderOptions

SchemaTypes

type SchemaTypes {
  // Shape of the context arg in your resolvers
  Context?: {};
  // A map of Object type names to their backing models.
  Objects?: {};
  // A map of Input type names to their backing models.
  Inputs?: {};
  // A map of Interface type names to their backing models.
  Interfaces?: {};
  // Map of scalar names to Input and Output shapes.  Can be used to overwrite default scalar types,
  // or to add type information for custom scalars
  Scalars?: {
    [s: string]: {
      Input: unknown;
      Output: unknown;
    };
  };
  // When provided, fields will be nullable by default (requires corresponding change in builder options)
  DefaultFieldNullability?: true;
  // When provided, input fields and arguments will be required by default (requires corresponding change in builder options)
  DefaultInputFieldRequiredness?: true;
}

SchemaBuilderOptions

type SchemaBuilderOptions = {};

By default there are no options for SchemaBuilder, but plugins may contribute additional options

queryType(options, fields?)

creates the Query with a set of Query fields

• options: QueryTypeOptions
• fields?: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

QueryTypeOptions

type QueryTypeOptions = {
  description?: string;
  fields: FieldsFunction;
};

• description: A description of the current type
• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

queryFields(fields)

add a set of fields to the Query type.

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

queryField(name, field)

add a single field to the Query type.

• name: the name of the field
• field: a function that receives a FieldBuilder, and returns field ref. See FieldBuilder for more details.

mutationType(options, fields?)

creates the Mutation with a set of Mutation fields

• options: MutationTypeOptions
• fields?: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

MutationTypeOptions

type MutationTypeOptions = {
  description?: string;
  fields: FieldsFunction;
};

• description: A description of the current type
• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

mutationFields(fields)

add a set of fields to the Mutation type.

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

mutationField(name, field)

add a single field to the Mutation type.

• name: the name of the field
• field: a function that receives a FieldBuilder, and returns field ref. See FieldBuilder for more details.

subscriptionType(options, fields?)

creates the Subscription with a set of Subscription fields

• options: SubscriptionTypeOptions
• fields?: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

SubscriptionTypeOptions

type SubscriptionTypeOptions = {
  description?: string;
  fields: FieldsFunction;
};

• description: A description of the current type
• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

subscriptionFields(fields)

add a set of fields to the Subscription type.

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

subscriptionField(name, field)

add a single field to the Subscription type.

• name: the name of the field
• field: a function that receives a FieldBuilder, and returns field ref. See FieldBuilder for more details.

objectType(param, options, fields?)

• param: A key of the Objects property in SchemaTypes, a class, or a TypeRef created by builder.objectRef

• options: ObjectTypeOptions

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

ObjectTypeOptions

type ObjectTypeOptions = {
  description?: string;
  fields: FieldsFunction;
  interfaces?: Interfaces;
  isTypeOf: (obj: InterfaceShape) => boolean;
  name?: string;
};

• description: A description of the current type

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

• isTypeOf: Recomended when implementing interfaces. This is a method that will be used when determining if a value of an implemented interface is of the current type.

• interfaces: an array of interfaces implemented by this interface type. Items in this array should be an interface param. See param argument of interfaceType

• name: name of GraphQL type. Required when param is a class

objectFields(param, fields)

add a set of fields to the object type.

• param: A key of the Objects property in SchemaTypes, a class, or a TypeRef created by builder.objectRef

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

objectField(param, name, field)

add a single field to the object type.

• name: the name of the field

• param: A key of the Objects property in SchemaTypes, a class, or a TypeRef created by builder.objectRef

• field: a function that receives a FieldBuilder, and returns field ref. See FieldBuilder for more details.

objectRef<T>(name)

Creates a Ref object represent an object that has not been implemented. This can be useful for building certain types of plugins, or when building a modular schema where you don't want to define all types in SchemaTypes, or import the actual implementation of each object type you use.

• name: string, name of the type that this ref represents. Can be overwritten when implemented.
• T: a type param to define the backing shape for the type that this ref represents

interfaceType(param, options, fields?)

• param: A key of the Interfaces property in SchemaTypes, a class, or a TypeRef created by builder.interfaceRef

• options: InterfaceTypeOptions

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

InterfaceTypeOptions

type InterfaceTypeOptions = {
  description?: string;
  fields: FieldsFunction;
  interfaces?: Interfaces;
  name?: string;
};

• description: A description of the current type

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

• interfaces: an array of interfaces implemented by this interface type. Items in this array should be an interface param. See param argument of interfaceType

• name: name of GraphQL type. Required when param is a class

interfaceFields(param, fields)

add a set of fields to the interface type.

• param: A key of the Interfaces property in SchemaTypes, a class, or a TypeRef created by builder.interfaceRef

• fields: a function that receives a FieldBuilder, and returns an object of field names to field refs. See FieldBuilder for more details.

interfaceField(paran, name, field)

add a single field to the interface type.

• param: A key of the Interfaces property in SchemaTypes, a class, or a TypeRef created by builder.interfaceRef

• name: the name of the field

• field: a function that receives a FieldBuilder, and returns field ref. See FieldBuilder for more details.

interfaceRef<T>(name)

Creates a Ref object represent an interface that has not been implemented. This can be useful for building certain types of plugins, or when building a modular schema where you don't want to define all types in SchemaTypes, or import the actual implementation of each interface type you use.

• name: string, name of the type that this ref represents. Can be overwritten when implemented.
• T: a type param to define the backing shape for the type that this ref represents

unionType(name, options)

• name: A string
• options: UnionTypeOptions

UnionTypeOptions

type UnionTypeOptions = {
  description?: string;
  types: Member[] | (() => Member[]);
  resolveType: (parent: UnionShape, context) => MaybePromise<GraphQLObjectType | TypeName>;
};

• description: A description of the current type

• types: an array of object types included in the union type. Items in this array should be Object params. See param argument in builder.objectType.

• resolveType: A function called when resolving the type of a union value. parent will be a union of the backing models of the types provided in types. This function should return the name of one of the union member types.

enumType(param, options)

• param: A string name of the enum or a typescript enum
• options: EnumTypeOptions

EnumTypeOptions

type UnionTypeOptions = {
  description?: string;
  values?: Values;
  name?: striing;
};

• description: A description of the current type

• values: can be either an array of strings (you may need to use as const to get proper type names) or a GraphQLEnumValueConfigMap. values is only required when param is not an enum

• name: required when param is an enum

addScalarType(name, scalar, options)

• name: A key of the Interface property in SchemaTypes
• scalar: A GraphQLScalar

scalarType(name, options)

• name: A key of the Interface property in SchemaTypes
• options: ScalarTypeOptions

ScalarTypeOptions

description?: string;
// Serializes an internal value to include in a response.
serialize: GraphQLScalarSerializer<OutputShape>;
// Parses an externally provided value to use as an input.
parseValue?: GraphQLScalarValueParser<InputShape>;
// Parses an externally provided literal value to use as an input.
parseLiteral?: GraphQLScalarLiteralParser<InputShape>;
extensions?: Readonly<Record<string, unknown>>;

inputType(param, options)

• param: a string or InputRef created by builder.inputRef
• options: InputTypeOptions

InputTypeOptions

type InputTypeOptions = {
  description?: string;
  fields: InputShape;
};

• description: A description of the current type
• fields: a function that receives an InputFieldBuilder, and returns an object of field names to field definitions. See InputFieldBuilder for more details. If name is a key of the Input property in SchemaTypes, shape will show type errors for any fields that do not match the types provided in SchemaTypes.

inputRef<T>(name)

Creates a Ref object represent an input object that has not been implemented. This can be useful for defining recursive input types, for building certain types of plugins, or when building a modular schema where you don't want to define all types in SchemaTypes, or import the actual implementation of each input type you use.

• name: string, name of the type that this ref represents. Can be overwritten when implemented.
• T: a type param to define the backing shape for the type that this ref represents

args(fields)

Creates an arguments object which can be used as the args option in a field definition.

• fields: a function that receives an ArgBuilder, and returns an object of field names to field definitions. See ArgBuilder for more details.

toSchema(types)

Takes an array of types created by SchemaBuilder and returns a GraphQLSchema

SchemaBuilder.allowPluginReRegistration

SchemaBuilder.allowPluginReRegistration is a static boolean on the SchemaBuilder class that can be set to allow plugins to call registerPlugin multiple times. This is useful for hot-module reloading, but is false by default to catch any issues with duplicate versions of a plugin.