Installation

npm install nestjs-paginate

Usage

Example

Endpoint

http://localhost:3000/cats?limit=5&page=2&sortBy=color:DESC&search=i&filter.age=$gte:3&select=id,name,color,age

Result

{"data": [    {"id":4,"name":"George","color":"white","age":3    },    {"id":5,"name":"Leche","color":"white","age":6    },    {"id":2,"name":"Garfield","color":"ginger","age":4    },    {"id":1,"name":"Milo","color":"brown","age":5    },    {"id":3,"name":"Kitty","color":"black","age":3    }  ],"meta": {"itemsPerPage":5,"totalItems":12,"currentPage":2,"totalPages":3,"sortBy": [["color","DESC"]],"search":"i","filter": {"age":"$gte:3"    }  },"links": {"first":"http://localhost:3000/cats?limit=5&page=1&sortBy=color:DESC&search=i&filter.age=$gte:3","previous":"http://localhost:3000/cats?limit=5&page=1&sortBy=color:DESC&search=i&filter.age=$gte:3","current":"http://localhost:3000/cats?limit=5&page=2&sortBy=color:DESC&search=i&filter.age=$gte:3","next":"http://localhost:3000/cats?limit=5&page=3&sortBy=color:DESC&search=i&filter.age=$gte:3","last":"http://localhost:3000/cats?limit=5&page=3&sortBy=color:DESC&search=i&filter.age=$gte:3"  }}

Code

import{Controller,Injectable,Get}from'@nestjs/common'import{InjectRepository}from'@nestjs/typeorm'import{FilterOperator,FilterSuffix,Paginate,PaginateQuery,paginate,Paginated}from'nestjs-paginate'import{Repository,Entity,PrimaryGeneratedColumn,Column}from'typeorm'@Entity()exportclassCatEntity{  @PrimaryGeneratedColumn()id:number  @Column('text')name:string  @Column('text')color:string  @Column('int')age:number  @Column({nullable:true})lastVetVisit:Date|null  @CreateDateColumn()createdAt:string}@Injectable()exportclassCatsService{constructor(    @InjectRepository(CatEntity)privatereadonlycatsRepository:Repository<CatEntity>){}publicfindAll(query:PaginateQuery):Promise<Paginated<CatEntity>>{returnpaginate(query,this.catsRepository,{sortableColumns:['id','name','color','age'],nullSort:'last',defaultSortBy:[['id','DESC']],searchableColumns:['name','color','age'],select:['id','name','color','age','lastVetVisit'],filterableColumns:{name:[FilterOperator.EQ,FilterSuffix.NOT],age:true,},})}}@Controller('cats')exportclassCatsController{constructor(privatereadonlycatsService:CatsService){}  @Get()publicfindAll(@Paginate()query:PaginateQuery):Promise<Paginated<CatEntity>>{returnthis.catsService.findAll(query)}}

Config

constpaginateConfig:PaginateConfig<CatEntity>{/**   * Required: true (must have a minimum of one column)   * Type: (keyof CatEntity)[]   * Description: These are the columns that are valid to be sorted by.   */sortableColumns:['id','name','color'],/**   * Required: false   * Type: 'first' | 'last'   * Description: Define whether to put null values at the beginning   * or end of the result set.   */nullSort:'last',/**   * Required: false   * Type: [keyof CatEntity, 'ASC' | 'DESC'][]   * Default: [[sortableColumns[0], 'ASC]]   * Description: The order to display the sorted entities.   */defaultSortBy:[['name','DESC']],/**   * Required: false   * Type: (keyof CatEntity)[]   * Description: These columns will be searched through when using the search query   * param. Limit search scope further by using `searchBy` query param.   */searchableColumns:['name','color'],/**   * Required: false   * Type: (keyof CatEntity)[]   * Default: None   * Description: TypeORM partial selection. Limit selection further by using `select` query param.   * https://typeorm.io/select-query-builder#partial-selection   * Note: You must include the primary key in the selection.   */select:['id','name','color'],/**   * Required: false   * Type: number   * Default: 100   * Description: The maximum amount of entities to return per page.   * Set it to 0, in conjunction with limit=0 on query param, to disable pagination.   */maxLimit:20,/**   * Required: false   * Type: number   * Default: 20   */defaultLimit:50,/**   * Required: false   * Type: TypeORM find options   * Default: None   * https://typeorm.io/#/find-optionsfind-options.md   */where:{color:'ginger'},/**   * Required: false   * Type: { [key in CatEntity]?: FilterOperator[] } - Operators based on TypeORM find operators   * Default: None   * https://typeorm.io/#/find-options/advanced-options   */filterableColumns:{age:[FilterOperator.EQ,FilterOperator.IN]},/**   * Required: false   * Type: RelationColumn<CatEntity>   * Description: Indicates what relations of entity should be loaded.   */relations:[],/**   * Required: false   * Type: boolean   * Default: false   * Description: Load eager relations using TypeORM's eager property.   * Only works if `relations` is not defined.   */loadEagerRelations:true,/**   * Required: false   * Type: boolean   * Description: Disables the global condition of "non-deleted" for the entity with delete date columns.   * https://typeorm.io/select-query-builder#querying-deleted-rows   */withDeleted:false,/**   * Required: false   * Type: string   * Description: Allow user to choose between limit/offset and take/skip.   * Default: PaginationType.TAKE_AND_SKIP   *   * However, using limit/offset can cause problems with relations.   */paginationType:PaginationType.LIMIT_AND_OFFSET,/**   * Required: false   * Type: boolean   * Default: false   * Description: Generate relative paths in the resource links.   */relativePath:true,/**   * Required: false   * Type: string   * Description: Overrides the origin of absolute resource links if set.   */origin:'http://cats.example',}

Usage with Query Builder

Example

constqueryBuilder=repo.createQueryBuilder('cats').leftJoinAndSelect('cats.owner','owner').where('cats.owner = :ownerId',{ ownerId})constresult=awaitpaginate<CatEntity>(query,queryBuilder,config)

Usage with Relations

Example

Endpoint

http://localhost:3000/cats?filter.toys.name=$in:Mouse,String

Code

constconfig:PaginateConfig<CatEntity>={relations:['toys'],sortableColumns:['id','name','toys.name'],filterableColumns:{'toys.name':[FilterOperator.IN],},}constresult=awaitpaginate<CatEntity>(query,catRepo,config)

constconfig:PaginateConfig<CatEntity>={sortableColumns:['id','name','toys.(size.height)','toys.(size.width)'],searchableColumns:['name'],relations:['toys'],}

Usage with Nested Relations

Example

Endpoint

http://localhost:3000/cats?filter.home.pillows.color=pink

Code

constconfig:PaginateConfig<CatEntity>={relations:{home:{pillows:true}},sortableColumns:['id','name','home.pillows.color'],searchableColumns:['name','home.pillows.color'],filterableColumns:{'home.pillows.color':[FilterOperator.EQ],},}constresult=awaitpaginate<CatEntity>(query,catRepo,config)

Usage with Eager Loading

Example

Code

@Entity()exportclassCatEntity{// ...  @OneToMany(()=>CatToyEntity,(catToy)=>catToy.cat,{eager:true,})toys:CatToyEntity[]}constconfig:PaginateConfig<CatEntity>={loadEagerRelations:true,sortableColumns:['id','name','toys.name'],filterableColumns:{'toys.name':[FilterOperator.IN],},}constresult=awaitpaginate<CatEntity>(query,catRepo,config)

Filters

Examples

Code

constconfig:PaginateConfig<CatEntity>={// ...filterableColumns:{// Enable individual operators on a columnid:[FilterOperator.EQ,FilterSuffix.NOT],// Enable all operators on a columnage:true,},}

Multi Filters

Examples

Swagger

  @Get()  @ApiOkPaginatedResponse(UserDto,USER_PAGINATION_CONFIG,)  @ApiPaginationQuery(USER_PAGINATION_CONFIG)asyncfindAll(    @Paginate()query:PaginateQuery,):Promise<Paginated<UserEntity>>{}

  @Get()  @PaginatedSwaggerDocs(UserDto,USER_PAGINATION_CONFIG)asyncfindAll(    @Paginate()query:PaginateQuery,):Promise<Paginated<UserEntity>>{}

Troubleshooting