SchemaBuilder

SchemaBuilder is the core class of Pothos. It can be used to build types, and merge them into a graphql.js Schema. The signatures below summarize the API; placeholder types such as FieldsFunction stand for types inferred from your schema. See the Schema Builder guide for configuration examples. The optional astNode properties attach AST metadata for schema tooling.

`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?: object;
  // Shape of the root value passed to root field resolvers
  Root?: object;
  // Select v3 compatibility defaults when needed
  Defaults?: 'v3' | 'v4';
  // 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.  Can be used to overwrite default scalar types,
  // or to add type information for custom scalars
  Scalars?: {
    [s: string]: {
      Input: unknown;
      Output: unknown;
    };
  };
  // When set to false, fields will be NonNullable by default (requires corresponding change in builder options)
  DefaultFieldNullability?: false;
  // When provided, input fields and arguments will be required by default (requires corresponding change in builder options)
  DefaultInputFieldRequiredness?: true;
}

SchemaBuilderOptions

type SchemaBuilderOptions = {
  plugins?: PluginName[];
  defaultFieldNullability?: boolean;
  defaultInputFieldRequiredness?: boolean;
  defaults?: 'v3' | 'v4';
};

Plugins may contribute additional options. When changing a default, set both the corresponding SchemaTypes entry and runtime option. Fields are nullable and inputs optional by default in v4. See Changing Default Nullability.

`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 = {
  astNode?: ObjectTypeDefinitionNode;
  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 = {
  astNode?: ObjectTypeDefinitionNode;
  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 = {
  astNode?: ObjectTypeDefinitionNode;
  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 = {
  astNode?: ObjectTypeDefinitionNode;
  description?: string;
  fields?: FieldsFunction;
  interfaces?: Interfaces | (() => Interfaces);
  isTypeOf?: (obj: unknown, context, info) => boolean | Promise<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: Recommended 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 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 representing 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 = {
  astNode?: InterfaceTypeDefinitionNode;
  description?: string;
  resolveType?: (parent: InterfaceShape, context, info, abstractType) =>
    MaybePromise<ObjectParam | string | null | undefined>;
  fields?: FieldsFunction;
  interfaces?: 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 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

resolveType returns an implementing object ref, registered class, or GraphQL type name. If omitted, GraphQL uses __typename or object isTypeOf checks. See Interfaces.

`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(param, 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 representing 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 = {
  astNode?: UnionTypeDefinitionNode;
  description?: string;
  types: Member[] | (() => Member[]);
  resolveType?: (parent: UnionShape, context, info, abstractType) =>
    MaybePromise<Member | string | null | undefined>;
};

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. Return a member ref, its registered class, or its GraphQL type name. If omitted, GraphQL uses __typename or member isTypeOf checks. See Unions.

`enumType(param, options)`

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

`EnumTypeOptions`

type EnumTypeOptions = {
  astNode?: EnumTypeDefinitionNode;
  description?: string;
  values?: Values;
  name?: string;
};

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

When values is a map, each entry accepts these options:

type EnumValueConfig = {
  value?: string | number;
  description?: string;
  deprecationReason?: string;
  extensions?: Readonly<Record<string, unknown>>;
  astNode?: EnumValueDefinitionNode;
};

`addScalarType(name, scalar, options?)`

name: A key of the Scalars property in SchemaTypes
scalar: A GraphQLScalarType
options: optional scalar options that override the supplied scalar configuration.

`scalarType(name, options)`

name: A key of the Scalars property in SchemaTypes
options: ScalarTypeOptions

ScalarTypeOptions

type ScalarTypeOptions = {
  astNode?: ScalarTypeDefinitionNode;
  description?: string;
  // Serializes an internal value to include in a response.
  serialize?: (value: OutputShape) => unknown;
  // 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>;
  // GraphQL.js 17+ coercion hooks
  coerceOutputValue?: (value: OutputShape) => unknown;
  coerceInputValue?: GraphQLScalarValueParser<InputShape>;
  coerceInputLiteral?: (node: ConstValueNode) => InputShape | null | undefined;
  valueToLiteral?: (value: unknown) => ConstValueNode | undefined;
  extensions?: Readonly<Record<string, unknown>>;
};

For portable scalar definitions, provide serialize, parseValue, and parseLiteral. GraphQL.js 17 also supports coerceOutputValue, coerceInputValue, coerceInputLiteral, and valueToLiteral. These hooks have version-specific requirements; see Scalars.

`inputType(param, options)`

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

`InputTypeOptions`

type InputTypeOptions = {
  astNode?: InputObjectTypeDefinitionNode;
  description?: string;
  fields: InputFieldsFunction;
  isOneOf?: boolean;
};

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 param is a key of the Inputs property in SchemaTypes, shape will show type errors for any fields that do not match the types provided in SchemaTypes.
isOneOf: defines a OneOf input object on supported GraphQL.js versions. See Input Objects. A OneOf input accepts exactly one non-null field; its fields must be optional and have no defaults. Use a GraphQL.js version with OneOf support.

`inputRef<T>(name)`

Creates a Ref object representing 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.

AST metadata

Type definitions, output fields, input fields, arguments, and enum values accept an optional astNode from graphql. Use the matching definition-node type shown in the option summaries; for example, an object type takes an ObjectTypeDefinitionNode, while an enum value takes an EnumValueDefinitionNode. Pothos attaches the node to the corresponding GraphQL.js schema element for tools that read AST metadata. Continue to define fields, values, and resolver behavior through the Pothos options; attaching a node does not build those definitions from SDL.

For applied directive metadata, see Directives. GraphQL.js printSchema does not preserve applied custom directives; see Printing Schemas when choosing an output format for downstream tools.

`toSchema(options?)`

Builds a GraphQLSchema from the types registered on the builder. The optional object accepts:

directives: custom GraphQLDirective instances to include in the schema.
extensions: schema metadata.
sortSchema: defaults to true; set to false to skip lexicographic sorting.
astNode: a SchemaDefinitionNode from graphql; see AST metadata.

Plugins may contribute build-time options. Calling toSchema again creates a new schema and new plugin instances.

`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.

On this page