NestJS GraphQL Cursor Connections

GraphQL Cursor Connections specification implementation for NestJS. Provides a handling of cursor, offset, and hybrid (cursor + offset) pagination.

Contents

• Installation
• Usage
  • Connection Edge
  • Connection
  • Connection Arguments
  • Connection Page Info
  • Connection Builder
  • Connection Resolver
• Arguments Adjusting
• Pagination Algorithm
• Offset Pagination (Pager Mode)
• Dynamic Cursor (Sorting)
• Additional Fields
  • Connection Edge Additional Fields
  • Connection Additional Fields
• Fake Cursor Pagination
  • Fake Cursor Connection Builder
  • Fake Cursor Connection Resolver

Installation

1npm i nestjs-graphql-cursor-connections

Usage

Assume we have users assigned to groups, and we need to provide a list of users of a specific group ordered by email address using connections pagination pattern.

1import { Field, Int, ObjectType } from '@nestjs/graphql'
2
3@ObjectType()
4export class User {
5  @Field(() => Int)
6  public id!: number
7
8  @Field()
9  public email!: string
10
11  @Field()
12  public name!: string
13
14  @Field()
15  public groupId!: string
16}

type User {
  id: Int!
  email: String!
  name: String!
  groupId: String!
}

Connection Edge

Create a connection edge type extending the class returned by the ConnectionEdge() function passing the target GraphQL type to it.

1import { ObjectType } from '@nestjs/graphql'
2import { ConnectionEdge } from 'nestjs-graphql-cursor-connections'
3
4@ObjectType()
5export class UserConnectionEdge extends ConnectionEdge(User) {}

This will produce the following GraphQL type:

type UserConnectionEdge {
  cursor: String!
  node: User!
}

Connection

Create a connection type extending the class returned by the Connection() function passing the connection edge type to it.

1import { ObjectType } from '@nestjs/graphql'
2import { Connection } from 'nestjs-graphql-cursor-connections'
3
4@ObjectType()
5export class UserConnection extends Connection(UserConnectionEdge) {}

This will produce the following GraphQL type:

type UserConnection {
  edges: [UserConnectionEdge!]!
  pageInfo: PageInfo!
}

Connection Arguments

Create a connection arguments type extending the ConnectionArgs class and add any extra filtering/sorting arguments if needed. In our case we need a groupId argument to filter users.

1import { ArgsType, Field } from '@nestjs/graphql'
2import { IsNotEmpty } from 'class-validator'
3import { ConnectionArgs } from 'nestjs-graphql-cursor-connections'
4
5@ArgsType()
6export class UserConnectionArgs extends ConnectionArgs {
7  @Field()
8  @IsNotEmpty()
9  groupId!: string
10}

This will produce the following GraphQL arguments:

after: String
before: String
first: Int
last: Int
edgesPerPage: Int  # The number of edges to display per page (enables pager mode).
page: Int          # The number of a page to display (enables pager mode).
groupId: String!

Connection Page Info

Connection page info is already created and produces the following GraphQL type:

hasPreviousPage: Boolean!
hasNextPage: Boolean!
startCursor: String!
endCursor: String!
totalEdges: Int!   # Total number of edges after applying the cursors.
edgesPerPage: Int  # The number of edges displayed per page (in pager mode).
page: Int          # The number of displayed page (in pager mode).
totalPages: Int    # Total number of pages (in pager mode).

Connection Builder

Create a connection builder extending the ConnectionBuilder class and implement all of its abstract methods.

1import { ConnectionBuilder } from 'nestjs-graphql-cursor-connections'
2
3type UserCursorData = string
4
5export class UserConnectionBuilder extends ConnectionBuilder<
6  UserConnection, UserConnectionEdge, User, UserCursorData
7> {
8  /**
9   * Cursor data is a node field or a set of node fields that uniquely identify
10   * the node position in the list.
11   * Cursor data can be a number, a string, an array, or an object.
12   */
13  protected getCursorData(node: User): UserCursorData {
14    // In our case the cursor data is a string representing user's email address.
15    return node.email
16  }
17
18  /**
19   * Since the cursor is an input argument, the unpacked cursor data must be
20   * validated to be sure it can be safely used.
21   */
22  protected isValidCursorData(data: unknown): boolean {
23    return 'string' === typeof data && 0 < data.length
24  }
25
26  /**
27   * When cursor argument can not be unpacked or unpacked cursor data fails
28   * validation, the cursor argument can be ignored (return null), or an error
29   * can be thrown (return an error).
30   */
31  protected getCursorDataError(name: 'after' | 'before', value: string): null | Error {
32    return new Error(`Cursor argument '${name}' has invalid value '${value}'.`)
33  }
34}

Connection Resolver

Here is an example implementation of a query resolver. The implementation of a field resolver is similar.

1import { Args, Query, Resolver } from '@nestjs/graphql'
2
3@Resolver()
4export class UserGraphqlResolver {
5  public constructor(private readonly repository: UserRepository) {}
6
7  @Query(() => UserConnection, { nullable: true })
8  public async usersByGroup(@Args() args: UserConnectionArgs): Promise<null | UserConnection> {
9    const maxEdgesToReturn = 10
10    const connectionBuilder = new UserConnectionBuilder(args, maxEdgesToReturn)
11    const { groupId } = args
12    // Contains the unpacked cursor data (user email) or `undefined`.
13    const { after, before } = connectionBuilder
14    // The result of the count users query below.
15    // Can be cached to improve performance when no after/before arguments are used.
16    const totalEdges = await this.repository.countUsersByGroup(groupId, { after, before })
17    // Returns the result set bounds: start, end, skip (start), take (end - start).
18    const { skip, take } = connectionBuilder.getBounds(totalEdges)
19    // The result of the find users query below.
20    const users = await this.repository.findUsersByGroup(groupId, { after, before, skip, take })
21    return connectionBuilder.build(users, totalEdges)
22  }
23}

Count users query

1SELECT COUNT(*) FROM users
2WHERE groupId = :groupId AND email > :after AND email < :before;

Find users query

1SELECT * FROM users
2WHERE groupId = :groupId AND email > :after AND email < :before
3ORDER BY email ASC
4LIMIT :take OFFSET :skip;

Arguments Adjusting

If maxEdgesToReturn connection builder parameter is specified, and it is a positive integer, the first, last, and edgesPerPage arguments are being adjusted, so that the number of returned edges never exceeds the value of maxEdgesToReturn.

If maxEdgesToReturn connection builder parameter is omitted, the number of returned edges is not limited.

Pagination Algorithm

To determine what edges to return, the connection evaluates the after and before cursors to filter the edges, (then, if pager mode is enabled, splits the edges into pages and slices them to contain only the selected page), then evaluates first to slice the edges, then last to slice the edges.

Let's say we have a set of all edges:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

If after is set and exists (E), remove all edges before and including after edge:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

If before is set and exists (V), remove all edges after and including before edge:

_{A B C D E} F G H I J K L M N O P Q R S T U V W X Y Z

If edgesPerPage (10) or page (1) is set, split the edges into pages and slice them to contain only the selected page.

_{A B C D E} <F G H I J K L M N O> <P Q R S T U> _{V W X Y Z}

If first is set (8), and edges length greater than first, slice edges to be of length first by removing edges from the end.

_{A B C D E} F G H I J K L M N O _{P Q R S T U V W X Y Z}

If last is set (4), and edges length greater than last, slice edges to be of length last by removing edges from the start.

_{A B C D E} F G H I J K L M _{N O P Q R S T U V W X Y Z}

Edges to return:

_{A B C D E F G H I} J K L M _{N O P Q R S T U V W X Y Z}

Offset Pagination (Pager Mode)

To enable offset pagination (pager mode) provide the edgesPerPage and/or the page connection argument. If one of these arguments is omitted, the another one will use the default value: edgesPerPage defaults to the value of the maxEdgesToReturn connection builder parameter; page defaults to 1.

When pager mode is enabled, the connection page info will additionally contain the following fields:

• edgesPerPage: the number of edges displayed per page;
• page: the number of displayed page;
• totalPages: total number of pages.

Dynamic Cursor (Sorting)

There are cases where custom connection arguments can affect the cursor data generation. For example, sortBy argument.

Assume we need the ability to sort users by ID and email fields:

1export enum UsersSortBy {
2  Id = 'id',
3  Email = 'email',
4}

And we have the following connection arguments type:

1import { ArgsType, Field } from '@nestjs/graphql'
2import { IsEnum } from 'class-validator'
3import { ConnectionArgs } from 'nestjs-graphql-cursor-connections'
4
5@ArgsType()
6export class UserConnectionArgs extends ConnectionArgs {
7  @IsEnum(UsersSortBy)
8  @Field(() => UsersSortBy)
9  public readonly sortBy!: UsersSortBy
10}

Create a connection builder extending the ConnectionBuilder class and specifying UserConnectionArgs as the 5th generic argument. After this the sortBy argument can be accessed from this.args:

1import { ConnectionBuilder } from 'nestjs-graphql-cursor-connections'
2
3type UserCursorData = { id: number } | { email: string }
4
5export class UserConnectionBuilder extends ConnectionBuilder<
6  UserConnection,
7  UserConnectionEdge,
8  User,
9  UserCursorData,
10  UserConnectionArgs
11> {
12  protected getCursorData(node: User): UserCursorData {
13    switch (this.args.sortBy) {
14      case UsersSortBy.Id:
15        return { id: node.id }
16
17      case UsersSortBy.Email:
18        return { email: node.email }
19    }
20  }
21
22  protected isValidCursorData(data: unknown): boolean {
23    switch (this.args.sortBy) {
24      case UsersSortBy.Id:
25        // Check that the data is `{ id: number }`.
26        return this.isValidIdCursorData(data)
27
28      case UsersSortBy.Email:
29        // Check that the data is `{ email: string }`.
30        return this.isValidEmailCursorData(data)
31    }
32  }
33
34  protected getCursorDataError(name: 'after' | 'before', value: string): null | Error {
35    return new Error(`Cursor argument '${name}' has invalid value '${value}'.`)
36  }
37  ...
38}

Additional Fields

Connection Edge Additional Fields

Connection edge types may have additional fields related to the edge. There are two ways to provide additional fields:

• By creating a field resolver for a connection edge

1import { Parent, ResolveField, Resolver } from '@nestjs/graphql'
2
3@Resolver(() => UserConnectionEdge)
4export class UserConnectionEdgeResolver {
5  @ResolveField(() => Boolean)
6  public additionalField(@Parent() edge: UserConnectionEdge): Promise<boolean> {
7    return this.getAdditionalField(edge)
8  }
9  ...
10}

• By extending a connection edge type and overriding createConnectionEdge() method of the connection builder

1import { Field, ObjectType } from '@nestjs/graphql'
2import { ConnectionEdge } from 'nestjs-graphql-cursor-connections'
3
4@ObjectType()
5export class UserConnectionEdge extends ConnectionEdge(User) {
6  @Field()
7  additionalField!: boolean
8}

1import { ConnectionBuilder, ConnectionEdge } from 'nestjs-graphql-cursor-connections'
2
3export class UserConnectionBuilder extends ConnectionBuilder<...> {
4  ...
5  protected async createConnectionEdge(edge: ConnectionEdge<User>): Promise<UserConnectionEdge> {
6    const additionalField = await this.getAdditionalField(edge)
7    return { ...edge, additionalField }
8  }
9  ...
10}

In both cases the following GraphQL type will be produced:

type UserConnectionEdge {
  node: User!
  cursor: String!
  additionalField: Boolean!
}

Connection Additional Fields

Connection types may have additional fields related to the connection. There are two ways to provide additional fields:

• By creating a field resolver for a connection

1import { Parent, ResolveField, Resolver } from '@nestjs/graphql'
2
3@Resolver(() => UserConnection)
4export class UserConnectionResolver {
5  @ResolveField(() => Boolean)
6  public additionalField(@Parent() connection: UserConnection): Promise<boolean> {
7    return this.getAdditionalField(connection)
8  }
9  ...
10}

• By extending a connection type and overriding createConnection() method of the connection builder

1import { Field, ObjectType } from '@nestjs/graphql'
2import { Connection } from 'nestjs-graphql-cursor-connections'
3
4@ObjectType()
5export class UserConnection extends Connection(UserConnectionEdge) {
6  @Field()
7  additionalField!: boolean
8}

1import { Connection, ConnectionBuilder } from 'nestjs-graphql-cursor-connections'
2
3export class UserConnectionBuilder extends ConnectionBuilder<...> {
4  ...
5  protected async createConnection(connection: Connection<UserConnectionEdge>): Promise<UserConnection> {
6    const additionalField = await this.getAdditionalField(connection)
7    return { ...connection, additionalField }
8  }
9  ...
10}

In both cases the following GraphQL type will be produced:

type UserConnection {
  pageInfo: PageInfo!
  edges: [UserConnectionEdge!]!
  additionalField: Boolean!
}

Fake Cursor Pagination

In cases when node fields can not uniquely identify the node position in the list, there is no way to create a real cursor, and the only way to paginate through the list is to use offset pagination.

It is possible to hide the offset pagination behind the cursor pagination interface, assuming that cursor is a node position in the list – a fake cursor.

Create Connection Edge, Connection, and Connection Arguments.

Fake Cursor Connection Builder

Create a connection builder extending the FakeCursorConnectionBuilder class and implement all of its abstract methods.

1import { FakeCursorConnectionBuilder } from 'nestjs-graphql-cursor-connections'
2
3export class UserFakeCursorConnectionBuilder extends FakeCursorConnectionBuilder<
4  UserConnection, UserConnectionEdge, User
5> {
6  /**
7   * When cursor can not be unpacked or unpacked cursor data fails validation,
8   * the cursor argument can be ignored (return null), or an error can be thrown
9   * (return an error).
10   */
11  protected getCursorDataError(name: string, value: string): null | Error {
12    return new Error(`Cursor argument '${name}' has invalid value '${value}'.`)
13  }
14}

Fake Cursor Connection Resolver

Here is an example implementation of a query resolver. The implementation of a field resolver is similar.

1import { Args, Query, Resolver } from '@nestjs/graphql'
2
3@Resolver()
4export class UserGraphqlResolver {
5  public constructor(private readonly repository: UserRepository) {}
6
7  @Query(() => UserConnection, { nullable: true })
8  public async usersByGroup(@Args() args: UserConnectionArgs): Promise<null | UserConnection> {
9    const maxEdgesToReturn = 10
10    const connectionBuilder = new UserFakeCursorConnectionBuilder(args, maxEdgesToReturn)
11    const { groupId } = args
12    // The result of the count users query below.
13    // Can be cached to improve performance.
14    const totalEdges = await this.repository.countUsersByGroup(groupId)
15    // Returns the result set bounds: start, end, skip (start), take (end - start).
16    const { skip, take } = connectionBuilder.getBounds(totalEdges)
17    // The result of the find users query below.
18    const users = await this.repository.findUsersByGroup(groupId, { skip, take })
19    return connectionBuilder.build(users, totalEdges)
20  }
21}

Count users query

1SELECT COUNT(*) FROM users
2WHERE groupId = :groupId

Find users query

1SELECT * FROM users
2WHERE groupId = :groupId
3ORDER BY email ASC
4LIMIT :take OFFSET :skip;