@emulienfou/nestjs-mikro-orm-paginate
TypeScript icon, indicating that this package has built-in type declarations

0.3.0 • Public • Published

A query package for convenient pagination, filtering and sorting implementation with MikroORM repositories in Nest.js.

Features

  • Pagination conforms to JSON:API
  • Sort by multiple fields
  • Sort by nulls first or last
  • Unpaged response (i.e., disabling pagination)
  • Various pagination behavior and constraints configuration
  • Filter using operators ($eq, $in, $nin, $gt, $gte, $lt, $lte, $ne, $not, $like, $re, $fulltext, $exists, $ilike, $overlap, $contains, $contained)

Limitations

  • Only work with Rest API
  • Only support MySQL, MariaDB, PostgreSQL and SQLite
  • Only support offset pagination

Guide

Prerequisites

  • >= Nest.js 8.0.0
  • >= MikroORM 5.0.0
  • >= Typescript 5.0.0

Installation

# With Yarn
yarn add @emulienfou/nestjs-mikro-orm-paginate
# With NPM
npm install @emulienfou/nestjs-mikro-orm-paginate
# With PNPM
pnpm add @emulienfou/nestjs-mikro-orm-paginate

Basic Usage

// articles.controller.ts
import { Controller, Get } from '@nestjs/common';
import { Paginate, PaginateResponse } from '@emulienfou/nestjs-mikro-orm-paginate';
import { ArticlesService } from './articles.service.ts';
import { ArticleDto } from './dtos/article.dto.ts';

@Controller('/articles')
export class ArticlesController {
  constructor(private articlesService: ArticlesService) {
  }

  @Get('/')
  getArticles(@Paginate() query: PaginateQuery): Promise<PaginateResponse<ArticlesDto>> {
    return this.articlesService.listArticles(query);
  }
}
// articles.service.ts
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@mikro-orm/nestjs';
import { EntityRepository } from '@mikro-orm/sqlite';
import { PaginateQuery, PaginateResponse, PageFactory } from '@emulienfou/nestjs-mikro-orm-paginate';
import { ArticleEntity } from './article.entity';
import { ArticleDto } from './dtos/article.dto.ts';

@Injectable()
export class ArticlesService {
  constructor(@InjectRepository(ArticleEntity) private articleRepository: EntityRepository<ArticleEntity>) {
  }

  async listArticles(query: PaginateQuery): Promise<PaginateResponse<ArticleDto>> {
    return await new PageFactory(query, this.articleRepository).create();
  }
}

With @Paginate, you can now provide the below query parameters to /articles:

  • page: the page number, starting from 1, e.g., ?page=1
  • limit: the page size, default to 10, e.g., ?limit=20
  • sort: the sort expression, e.g., ?sort=property[field1];direction[asc];nulls-first[true]
  • unpaged: whether to disable pagination, default to false, e.g., ?unpaged=true
  • filter:

Response Shape

An example of the response shape is shown as below:

{
  "data": [
    {
      "id": 1,
      "title": "Article 1",
      "content": "Content 1",
      "createdAt": "2021-08-01T00:00:00.000Z",
      "updatedAt": "2021-08-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "totalItems": 1,
    "currentPage": 1,
    "totalPages": 1,
    "itemsPerPage": 10,
    "offset": 0,
    "sort": [
      {
        "property": "id",
        "direction": "ASC",
        "nullsFirst": false
      }
    ],
    "unpaged": false,
    "filter": {}
  },
  "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"
  }
}

Swagger support

Use the @ApiPaginate decorator for swagger integration:

// articles.controller.ts
import { Controller, Get } from '@nestjs/common';
import { ApiPaginate, Paginate } from '@emulienfou/nestjs-mikro-orm-paginate';
import { ArticlesService } from './articles.service.ts';
import { ArticleDto } from './dtos/article.dto.ts';

@Controller('/articles')
export class ArticlesController {
  constructor(private articlesService: ArticlesService) {
  }

  @Get('/')
  @ApiPaginate({
    dto: ArticleDto,
  })
  getArticles(@Paginate() query: PaginateQuery): Promise<PaginateResponse<ArticlesDto>> {
    return this.articlesService.listArticles(query);
  }
}

Package Sidebar

Install

npm i @emulienfou/nestjs-mikro-orm-paginate

Weekly Downloads

3

Version

0.3.0

License

MIT

Unpacked Size

171 kB

Total Files

55

Last publish

Collaborators

  • emulienfou