Complexity plugin

This plugin allows you to define complexity of fields and limit the maximum complexity, depth, and breadth of queries.

Usage

Install

npm install --save @pothos/plugin-complexity

Setup

import SchemaBuilder from '@pothos/core';
import ComplexityPlugin from '@pothos/plugin-complexity';

const builder = new SchemaBuilder({
  plugins: [ComplexityPlugin],
});

Configure defaults and limits

To limit query complexity you can specify a maximum complexity either in the builder setup, or when building the schema:

const builder = new SchemaBuilder({
  plugins: [ComplexityPlugin],

  complexity: {
    defaultComplexity: 1,
    defaultListMultiplier: 10,
    limit: {
      complexity: 500,
      depth: 10,
      breadth: 50,
    },
  },
});
// or
const schema = builder.toSchema({
  complexity: {
    limit: {
      complexity: 500,
      depth: 10,
      breadth: 50,
    },
  },
});

Options

• fieldComplexity: (optional, (args, ctx, field) => { field: number, multiplier: number } | number): default complexity calculation for fields. defaultComplexity and defaultListMultiplier will not be used if this is set.
• defaultComplexity: (optional number) defines the default complexity for every field in the schema
• defaultListMultiplier: (optional number) defines a default complexity multiplier for a list fields sub selections
• limit: Defines limits for queries. For request-specific limits, pass a function such as limit: (ctx) => ({ complexity: 500, depth: 10, breadth: 50 }).
  • complexity: defines the maximum complexity allowed for queries
  • depth: defines the maximum depth of selections in a query
  • breadth: defines the maximum total selections in a query
• complexityError: (optional function) defines the error to throw when the query complexity exceeds the limit. The function is passed the errorKind (depth, breadth, or complexity), the result (with the depth, breadth, complexity, and max values), and a GraphQL info object. It should return (or throw) an error, or an error message as a string

How complexity is calculated

Complexity is calculated before resolving any root level fields (query, mutation, subscription), and is based purely on the shape of the query before execution begins.

The complexity of a query is the sum of the complexity of each selected field. If a field has sub-selections, the complexity of its sub-selections are multiplied by a fields multiplier, and then added to the fields own complexity. The default multiplier for fields is 1, and 10 for list fields. This multiplier is meant to represent the n+1 complexity of list fields.

Example

The following query has a complexity of 131 (assuming we are using the default options), a depth of 3, and a breadth of 5:

query {
  posts {
    # complexity = 131 (posts + 10 * (2 + 11))
    author {
      # complexity = 2 (author + 1 * name)
      name # complexity = 1, depth: 3
    }
    comments {
      # complexity = 11 (comments + 10 * comment)
      comment # complexity = 1, depth: 3
    }
  }
}

Defining complexity of a field

The following alternatives assume a Post object ref and a loadPosts(limit) function returning that model's records. Set a fixed cost with a number:

builder.queryFields((t) => ({
  posts: t.field({
    type: [Post],
    complexity: 20,
    resolve: () => loadPosts(20),
  }),
}));

The complexity option can also set the multiplier for a field:

builder.queryFields((t) => ({
  posts: t.field({
    type: [Post],
    complexity: { field: 5, multiplier: 20 },
    resolve: () => loadPosts(20),
  }),
}));

A fields complexity can also be based on the fields arguments, or the context value:

builder.queryFields((t) => ({
  posts: t.field({
    type: [Post],
    args: {
      limit: t.arg.int(),
    },
    // base multiplier on how many posts are being requested
    complexity: (args, ctx) => ({ field: 5, multiplier: Math.max(0, args.limit ?? 5) }),
    resolve: (parent, args) => {
      const limit = Math.max(0, args.limit ?? 5);
      return loadPosts(limit);
    },
  }),
}));

Example: a bounded list

This configuration caps query cost at 20, depth at 3, and breadth at 5:

const builder = new SchemaBuilder({
  plugins: [ComplexityPlugin],
  complexity: {
    defaultComplexity: 1,
    defaultListMultiplier: 10,
    limit: { complexity: 20, depth: 3, breadth: 5 },
  },
});

For a Post object with a title field, the list's base cost is 5 and its limit argument sets the multiplier. Here, posts is an array of records and resolverCalls is a counter used to observe whether the resolver is invoked:

posts: t.field({
  type: [Post],
  args: { limit: t.arg.int({ defaultValue: 2 }) },
  complexity: (args) => ({ field: 5, multiplier: Math.max(0, args.limit ?? 2) }),
  resolve: (_parent, args) => {
    resolverCalls += 1;
    return posts.slice(0, Math.max(0, args.limit ?? 2));
  },
}),

The selection { posts(limit: 2) { title } } costs 5 + 2 × 1 = 7. A limit of 16 costs 21, so the budget rejects that query before invoking the resolver. A limit of 15 costs exactly 20 and is accepted. The multiplier follows the requested limit even when fewer records exist; query cost estimates the operation rather than measuring the records actually returned.

Utilities

complexityFromQuery(query, options)

Returns the query complexity for a given GraphQL query.

import { complexityFromQuery } from '@pothos/plugin-complexity';

const complexity = complexityFromQuery(query, {
  schema: schema,
  // Complexity can be calculated based on the context and arguments,
  // so you may need to provide valid values for the context and arguments.
  // Both are optional, and will default to empty objects.
  ctx: {},
  variables: {},
});

createComplexityRule(options)

Use this validation rule with GraphQL's specifiedRules to enforce maxComplexity, maxDepth, or maxBreadth during validation. Supply the request's context and raw variableValues; operation variable defaults and input defaults are applied before complexity callbacks run.

Pass operationName when the request selects a named operation. Only that operation is measured, and an unknown name or invalid variables for it produce validation errors. Without operationName, all operations whose variables can be coerced are measured independently. In a multi-operation document, variable errors for other possible operations are left to GraphQL execution to report for the selected operation. A single operation's variable errors are reported during validation.

import { type GraphQLSchema, parse, specifiedRules, validate } from 'graphql';
import { createComplexityRule } from '@pothos/plugin-complexity';

function validateRequest(
  schema: GraphQLSchema,
  query: string,
  context: object,
  variableValues: Record<string, unknown>,
  operationName?: string,
) {
  return validate(schema, parse(query), [
    ...specifiedRules,
    createComplexityRule({ context, variableValues, operationName, maxComplexity: 500 }),
  ]);
}

These validation results depend on the request's variables, context, and operation name. Do not reuse them across requests based only on the query text. complexityFromQuery also applies variable defaults and throws for invalid variables; it measures the first operation in the document.