SchemaBuilder

SchemaBuilder is the core class of Pothos. You use it to define every type in your schema, then call toSchema to produce a graphql-js GraphQLSchema. For a guided walk through configuring the builder, see SchemaBuilder in the fundamentals.

constructor<SchemaTypes>(options)

• typeParam SchemaTypes: a type describing the backing models, context, and defaults for your schema.
• options: SchemaBuilderOptions

SchemaTypes

type SchemaTypes = {
  // Shape of the `context` arg in your resolvers.
  Context?: object;
  // Shape of the `parent`/root value passed to root fields.
  Root?: object;
  // A map of Object type names to their backing models.
  Objects?: object;
  // A map of Input type names to their backing models.
  Inputs?: object;
  // A map of Interface type names to their backing models.
  Interfaces?: object;
  // Map of scalar names to Input and Output shapes. Use it to overwrite the
  // default scalar types, or to add type information for custom scalars.
  Scalars?: {
    [s: string]: {
      Input: unknown;
      Output: unknown;
    };
  };
  // When `false`, fields are non-nullable by default (requires the matching
  // `defaultFieldNullability` builder option).
  DefaultFieldNullability?: boolean;
  // When `true`, input fields and arguments are required by default (requires
  // the matching `defaultInputFieldRequiredness` builder option).
  DefaultInputFieldRequiredness?: boolean;
};

SchemaBuilderOptions

type SchemaBuilderOptions = {};

The core builder takes no options. Plugins contribute their own, such as plugins: [...] and each plugin's config block. See the individual plugin pages for what each adds.

queryType(options, fields?)

Creates the Query type with a set of fields.

• options: QueryTypeOptions
• fields?: a function that receives a FieldBuilder and returns a map of field names to field refs.

QueryTypeOptions

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

• description: a description of the Query type.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

queryFields(fields)

Adds a set of fields to the Query type.

• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

queryField(name, field)

Adds a single field to the Query type.

• name: the name of the field.
• field: a function that receives a FieldBuilder and returns a field ref.

mutationType(options, fields?)

Creates the Mutation type with a set of fields.

• options: MutationTypeOptions
• fields?: a function that receives a FieldBuilder and returns a map of field names to field refs.

MutationTypeOptions

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

• description: a description of the Mutation type.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

mutationFields(fields)

Adds a set of fields to the Mutation type.

• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

mutationField(name, field)

Adds a single field to the Mutation type.

• name: the name of the field.
• field: a function that receives a FieldBuilder and returns a field ref.

subscriptionType(options, fields?)

Creates the Subscription type with a set of fields.

• options: SubscriptionTypeOptions
• fields?: a function that receives a FieldBuilder and returns a map of field names to field refs.

SubscriptionTypeOptions

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

• description: a description of the Subscription type.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

subscriptionFields(fields)

Adds a set of fields to the Subscription type.

• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

subscriptionField(name, field)

Adds a single field to the Subscription type.

• name: the name of the field.
• field: a function that receives a FieldBuilder and returns a field ref.

objectType(param, options, fields?)

Defines an object type. param can be a class, an ObjectRef, or a SchemaTypes-registered name; see Object types for how the three forms differ.

• param: a key of the Objects property in SchemaTypes, a class, or an ObjectRef created by builder.objectRef.
• options: ObjectTypeOptions
• fields?: a function that receives a FieldBuilder and returns a map of field names to field refs.

ObjectTypeOptions

type ObjectTypeOptions = {
  description?: string;
  fields?: FieldsFunction;
  interfaces?: Interfaces;
  isTypeOf?: (obj, context, info) => boolean;
  name?: string;
  extensions?: Record<string, unknown>;
};

• description: a description of the type.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.
• isTypeOf: recommended when implementing interfaces. Called during execution to decide whether a value of an implemented interface is of this type.
• interfaces: an array of interfaces this type implements. Each item is an interface param (see the param argument of interfaceType).
• name: name of the GraphQL type. Required when param is a class.
• extensions: arbitrary extension metadata, read by directives and server plugins.

objectFields(param, fields)

Adds a set of fields to an object type.

• param: a key of the Objects property in SchemaTypes, a class, or an ObjectRef created by builder.objectRef.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

objectField(param, name, field)

Adds a single field to an object type.

• param: a key of the Objects property in SchemaTypes, a class, or an ObjectRef created by builder.objectRef.
• name: the name of the field.
• field: a function that receives a FieldBuilder and returns a field ref.

objectRef<T>(name)

Creates a reference to an object type before it is implemented. Use it to break circular references, to build modular schemas without registering every type on SchemaTypes, or when writing plugins.

• name: name of the type this ref represents. Can be overwritten when the ref is implemented.
• T: the backing model, the shape your resolvers return and Pothos hands back as parent.

The returned ref carries an implement method, so you can define fields directly: builder.objectRef<IRace>('Race').implement({ fields: ... }).

interfaceType(param, options, fields?)

Defines an interface type.

• param: a key of the Interfaces property in SchemaTypes, a class, or an InterfaceRef created by builder.interfaceRef.
• options: InterfaceTypeOptions
• fields?: a function that receives a FieldBuilder and returns a map of field names to field refs.

InterfaceTypeOptions

type InterfaceTypeOptions = {
  description?: string;
  fields?: FieldsFunction;
  interfaces?: Interfaces;
  resolveType?: (parent, context, info) => string;
  name?: string;
  extensions?: Record<string, unknown>;
};

• description: a description of the type.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.
• interfaces: an array of interfaces this interface extends. Each item is an interface param (see the param argument of interfaceType).
• resolveType: returns the name of the concrete type for a given value. An alternative to setting isTypeOf on each implementing object type.
• name: name of the GraphQL type. Required when param is a class.
• extensions: arbitrary extension metadata, read by directives and server plugins.

interfaceFields(param, fields)

Adds a set of fields to an interface type.

• param: a key of the Interfaces property in SchemaTypes, a class, or an InterfaceRef created by builder.interfaceRef.
• fields: a function that receives a FieldBuilder and returns a map of field names to field refs.

interfaceField(param, name, field)

Adds a single field to an interface type.

• param: a key of the Interfaces property in SchemaTypes, a class, or an InterfaceRef created by builder.interfaceRef.
• name: the name of the field.
• field: a function that receives a FieldBuilder and returns a field ref.

interfaceRef<T>(name)

Creates a reference to an interface type before it is implemented. Use it to break circular references, to build modular schemas, or when writing plugins.

• name: name of the type this ref represents. Can be overwritten when the ref is implemented.
• T: the backing model, the shape shared by every implementing type.

unionType(name, options)

Defines a union type.

• name: the name of the union.
• options: UnionTypeOptions

UnionTypeOptions

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

• description: a description of the type.
• types: the object types included in the union: an array, or a thunk returning one so members can be referenced before they are defined. Each item is an object param (see the param argument of objectType).
• resolveType: called when resolving the type of a union value. parent is a union of the backing models of the member types. Return the name of the matching member type. Optional if each member type sets isTypeOf, but supplying it here is the usual approach.
• extensions: arbitrary extension metadata, read by directives and server plugins.

enumType(param, options)

Defines an enum type.

• param: a string name for the enum, or a TypeScript enum.
• options: EnumTypeOptions

EnumTypeOptions

type EnumTypeOptions = {
  description?: string;
  values?: Values;
  name?: string;
  extensions?: Record<string, unknown>;
};

• description: a description of the type.
• values: either an array of strings (you may need as const to get precise value names) or a GraphQLEnumValueConfigMap. Required when param is not a TypeScript enum.
• name: required when param is a TypeScript enum.
• extensions: arbitrary extension metadata, read by directives and server plugins.

scalarType(name, options)

Defines a custom scalar.

• name: a key of the Scalars property in SchemaTypes.
• options: ScalarTypeOptions

ScalarTypeOptions

type 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>>;
};

addScalarType(name, scalar, options?)

Registers an existing GraphQLScalarType (for example, one from graphql-scalars) under a SchemaTypes name.

• name: a key of the Scalars property in SchemaTypes.
• scalar: a GraphQLScalarType.
• options?: the same options as scalarType, with serialize optional since the passed scalar already supplies one. Anything you set here overrides the scalar's own config.

inputType(param, options)

Defines an input object type.

• param: a string name, or an InputObjectRef created by builder.inputRef.
• options: InputTypeOptions

InputTypeOptions

type InputTypeOptions = {
  description?: string;
  fields: InputFieldsFunction;
  isOneOf?: boolean;
  extensions?: Record<string, unknown>;
};

• description: a description of the type.
• fields: a function that receives an InputFieldBuilder and returns a map of field names to field definitions. When param is a key of the Inputs property in SchemaTypes, the shape is type-checked against the registered backing model.
• isOneOf: marks the type as a @oneOf input, where exactly one field may be provided. All fields must be nullable.
• extensions: arbitrary extension metadata, read by directives and server plugins.

inputRef<T>(name)

Creates a reference to an input object type before it is implemented. Use it for recursive input types, for modular schemas, or when writing plugins.

• name: name of the type this ref represents. Can be overwritten when the ref is implemented.
• T: the backing shape of the input.

args(fields)

Creates a standalone arguments object you can reuse as the args option on a field definition.

• fields: a function that receives an ArgBuilder and returns a map of arg names to arg definitions.

toSchema(options?)

Builds and returns a GraphQLSchema from every type registered on the builder.

• options?: BuildSchemaOptions, carrying build-time options such as directives and extensions. Plugins add their own keys here.

SchemaBuilder.allowPluginReRegistration

A static boolean on the SchemaBuilder class. When true, a plugin may call registerPlugin more than once — useful for hot-module reloading. It defaults to false so duplicate copies of a plugin surface as an error rather than a silent conflict.