Pagination (class-validator)

A class-validator DTO for the core connection arguments: validates them and keeps cursor and offset modes mutually exclusive, so you can return clean 400s.

npm i @azhulin/pagination-class-validator

Peer dependencies: class-validator, reflect-metadata.

ConnectionArgsDto

Use it standalone, or extend it with your own filtering/sorting arguments:

import { ConnectionArgsDto } from '@azhulin/pagination-class-validator'
import { IsNotEmpty } from 'class-validator'

export class UserConnectionArgsDto extends ConnectionArgsDto {
  @IsNotEmpty()
  public readonly groupId!: string
}

Rules applied:

| Field | Rules | |--------------------|--------------------------------------------| | after, before | optional, URL-safe base64, min length 1 | | first, last | optional integer, ≥ 0 (Relay allows 0) | | page, pageSize | optional integer, ≥ 1 |

Plus mode exclusivity: any cursor argument (after/before/first/last) set alongside any offset argument (page/pageSize) fails validation. first + last together is allowed (Relay "last of first").

import { validate } from 'class-validator'
import { plainToInstance } from 'class-transformer'

const dto = plainToInstance(ConnectionArgsDto, { page: 1, after: 'eyJpZCI6MX0' })
await validate(dto) // → 2 errors: `page` and `after` can't be combined

ConnectionArgsDto layers @IsOptional over BaseConnectionArgsDto, which holds the same value constraints and mode exclusivity but no optionality policy. Extend BaseConnectionArgsDto instead when you need a stricter policy (e.g. reject null) while reusing those constraints.

MutuallyExclusive

The decorator behind the mode check, exported for reuse — fails validation when the decorated property is set alongside any of the given siblings:

import { MutuallyExclusive } from '@azhulin/pagination-class-validator'

class Filter {
  @MutuallyExclusive(['ids'])
  public readonly query?: string // rejected if `ids` is also set

  public readonly ids?: string[]
}

License

MIT © 2022–2026 Alex Zhulin