Nestjs/prisma-querybuilder

Como instalar?

• npm i nestjs-prisma-querybuilder

No seu app.module inclua o Querybuilder aos providers:

• PrismaService é o seu service, para ver como criar ele leia a documentação @nestjs/prisma;

  // app.module
  import { Querybuilder } from 'nestjs-prisma-querybuilder';
  
  providers: [PrismaService, QuerybuilderService, Querybuilder],

  
  

• QuerybuilderService vai ser o service que será usado nos seus métodos;

  import { BadRequestException, Inject, Injectable } from '@nestjs/common';
  import { REQUEST } from '@nestjs/core';
  import { Prisma } from '@prisma/client';
  import { Querybuilder, QueryResponse } from 'nestjs-prisma-querybuilder';
  import { Request } from 'express';
  import { PrismaService } from 'src/prisma.service';
  
  @Injectable()
  export class QuerybuilderService {
    constructor(@Inject(REQUEST) private readonly request: Request, private readonly querybuilder: Querybuilder, private readonly prisma: PrismaService) {}
  
    /**
     *
     * @param model nome do model no schema.prisma;
     * @param primaryKey nome da chave primaria deste model no prisma.schema;
     * @param where objeto para where de acordo com as regras do prisma;
     * @param mergeWhere define se o where informado no parâmetro anterior será unido ou substituirá um possivel where vindo da query;
     * @param justPaginate remove qualquer 'select' e 'populate' da query;
     * @param setHeaders define se será adicionado os headers 'count' e 'page' na resposta;
     * @param depth limita o numero de 'niveis' que a query vai lhe permitir fazer (filter/populate). default is '_5_'
     * @param forbiddenFields campos que serão removidos de qualquer select/filter/populate/sort
     */
    async query({
      model,
      depth,
      where,
      mergeWhere,
      justPaginate,
      forbiddenFields,
      primaryKey = 'id',
      setHeaders = true
    }: {
      model: Prisma.ModelName;
      where?: any;
      depth?: number;
      primaryKey?: string;
      mergeWhere?: boolean;
      setHeaders?: boolean;
      justPaginate?: boolean;
      forbiddenFields?: string[];
    }): Promise<Partial<QueryResponse>> {
      return this.querybuilder
        .query(primaryKey, depth, setHeaders, forbiddenFields)
        .then(async (query) => {
          if (where) query.where = mergeWhere ? { ...query.where, ...where } : where;
  
          if (setHeaders) {
            const count = await this.prisma[model].count({ where: query.where });
  
            this.request.res.setHeader('count', count);
          }
  
          if (onlyPaginate) {
            delete query.include;
            delete query.select;
          }
  
          return { ...query };
        })
        .catch((err) => {
          if (err.response?.message) throw new BadRequestException(err.response?.message);
  
          throw new BadRequestException('Internal error processing your query string, check your parameters');
        });
    }
  }

Optional: Você pode adicionar uma validação adicional para o parametro model, mas essa validação vai variar de acordo com o seu database;

• Exemplo com SQLite

  if (!this.tables?.length) this.tables = await this.prisma.$queryRaw`SELECT name FROM sqlite_schema WHERE type ='table' AND name NOT LIKE 'sqlite_%';`;
  
  if (!this.tables.find((v) => v.name === model)) throw new BadRequestException('Invalid model');

Como usar?

Você pode usar essa interface para tornar suas queries mais fácies no frontend -- Nestjs prisma querybuilder interface

• Adicione o Querybuilder no seu service:

  // service
  constructor(private readonly prisma: PrismaService, private readonly qb: QuerybuilderService) {}

• Configurando seu método:

  • o método query vai montar a query baseada no @Query(), mas o mesmo é pego direto do REQUEST, não sendo necessário passar como parâmetro;
  • o método query já vai adicionar no Response.headers a propriedade count que vai ter o total de objetos encontrados (usado para paginação);
  • o método query recebe uma string com o nome referente ao model, isso vai ser usado para fazer o count;
  
  

    async UserExemple() {
      const query = await this.qb.query('User');
  
      return this.prisma.user.findMany(query);
    }

Parametros disponiveis:

• models de exemplo:

  model User {
    id    Int     @id @default(autoincrement())
    email String  @unique
    name  String?
    posts Post[]
  
    @@map("users")
  }
  
  model Post {
    id        Int      @id @default(autoincrement())
    title     String
    published Boolean? @default(false)
    author    User?    @relation(fields: [authorId], references: [id])
    authorId  Int?
  
    content Content[]
  
    @@map("posts")
  }
  
  model Content {
    id   Int    @id @default(autoincrement())
    text String
  
    post   Post @relation(fields: [postId], references: [id])
    postId Int
  
    @@map("contents")
  }

• Page e Limit

  • Por padrão a páginação está sempre habilitada e se não enviado page e limit na query, vai ser retornado página 1 com 10 itens;
  • Nos headers da response haverá a propriedade count com o total de itens a serem paginados;
  • http://localhost:3000/posts?page=2&limit=10

• Sort

  • Para montar o sort são necessário enviar duas propriedades field e criteria;
  • criteria é um enum com [‘asc’, ‘desc’];
  • field é o campo pelo qual a ordenação vai ser aplicada;
  • http://localhost:3000/posts?sort[criteria]=asc&sort[field]=title

• Distinct

  • Todas as propriedades devem ser separadas por espaço em branco, virgula ou ponto e virgula;
  • Para montar o distinct é necessário enviar apenas os valores;
  • http://localhost:3000/posts?distinct=title published

• Select

  • Todas as propriedades devem ser separadas por espaço em branco, virgula ou ponto e virgula;

  • Por padrão se não for enviado nenhum select qualquer busca só irá retornar a propriedade id

  • Se for necessário pegar todo o objeto é possível usar select=all,

  • Exceção: ao dar select em um relacionamento será retornado todo o objeto do relacionamento, para usar o select em um relacionamento use o populate, para buscar somente o id de um relacionamento é possível usar a coluna authorId

  • http://localhost:3000/posts?select=id title,published;authorId

  • Para excluir campos no retorno, você pode utilizar um DTO na resposta do prisma antes de devolve-lá ao usuário OU usar o parametro 'forbiddenFields' no método query ;

    • Exemplo uma senha de usuário ou informações de tokens;
    • Ao usar forbiddenFields select 'all' será ignorado;

• Populate

  • Populate é um array que permite dar select nos campos dos relacionamentos, é composto por 2 parametros, path e select;
  • path é a referencia para qual relacionamento será populado;
  • select são os campos que irão serem retornados;
    • select=all não é suportado no populate
  • primaryKey nome da chave primaria do relacionamento (opcional) (default: 'id');
  • Podem ser feitos todos os populates necessários usando o índice do array para ligar o path ao select;
  • http://localhost:3000/posts?populate[0][path]=author&populate[0][select]=name email

• Filter

  • Pode ser usado para filtrar a consulta com os parâmetros desejados;
  • path é a referencia para qual propriedade irá aplicar o filtro;
  • value é o valor pelo qual vai ser filtrado;
  • filterGroup Pode ser usado para montar o where usando os operadores [‘AND’, ‘OR’, ‘NOT’] ou nenhum operador (opcional);
    • opções: ['and', 'or, 'not’]
  • operator pode ser usado para personalizar a consulta (opcional);
    • recebe os tipos ['contains', 'endsWith', 'startsWith', 'equals', 'gt', 'gte', 'in', 'lt', 'lte', 'not', 'notIn', 'hasEvery', 'hasSome', 'has', 'isEmpty']
    • hasEvery, hasSome e notIn recebe uma unica string separando os valores por um espaço em branco
      • ?filter[0][path]=name&filter[0][operator]=hasSome&filter[0][value]=foo bar ula
  • insensitive pode ser usado para personalizar a consulta (opcional);
    • recebe os tipos: ['true', 'false'] - default: 'false'
    • (confira as regras do prisma para mais informações - Prisma: Database collation and case sensitivity)
  • type é usado caso o valor do filter NÃO seja do tipo 'string'
    • recebe os tipos: ['string', 'boolean', 'number', 'date' , 'object'] - default: 'string'
      • 'object' recebe os valores: ['null', 'undefined']
  • filter é um array, podendo ser adicionados vários filtros de acordo com a necessidade da consulta;
  • consulta simples
    • http://localhost:3000/posts?filter[0][path]=title&filter[0][value]=querybuilder&filter[1][path]=published&filter[1][value]=false
    • http://localhost:3000/posts?filter[1][path]=published&filter[1][value]=false&filter[1][type]=boolean
    • http://localhost:3000/posts?filter[0][path]=title&filter[0][value]=querybuilder&filter[0][filterGroup]=and&filter[1][path]=published&filter[1][value]=falsefilter[1][filterGroup]=and