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.

`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 = {
  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 | (() => 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 = {
  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 = {
  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 = {
  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

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

`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 schema definition AST node.

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.

SchemaBuilder

On this page