Pré-requisito NestJS

Requisitos para usar o nestjs-rest-query numa aplicação NestJS com TypeORM, Drizzle ou Prisma.

Antes de instalar a biblioteca, confirme que seu projeto NestJS já atende aos requisitos abaixo.

Aplicação NestJS

Requisito	Versão	Observação
NestJS	`^11.0.0`	`@nestjs/common` e `@nestjs/core` precisam estar presentes. A `12.x` não está na faixa.

Runtime

Requisito	Versão
Node.js	`>= 22`

O Node 24.x é o alvo principal: é nele que a matriz de bancos roda. O job geral da CI também roda 22.x.

Estes pacotes precisam existir no seu projeto — eles não vêm embutidos na biblioteca. Os quatro peers de ORM/Swagger são declarados opcionais, e o entrypoint raiz não carrega nenhum deles: import ... from 'nestjs-rest-query' nunca puxa um ORM.

Pacote	Faixa	Obrigatório
`@nestjs/common`	`^11.0.0`	Sim
`@nestjs/core`	`^11.0.0`	Sim
`reflect-metadata`	`^0.2.0`	Sim
`typeorm`	`^0.3.26 \|\| ^1.0.0`	Um dos adapters
`drizzle-orm`	`>=1.0.0-rc.4 <1.0.0`	Um dos adapters
`@prisma/client`	`^6.19.0 \|\| ^7.0.0`	Um dos adapters
`@nestjs/swagger`	`^11.0.0`	Opcional

Drizzle 0.45.x não é suportado

A faixa de drizzle-orm é fechada nos release candidates contra os quais a matriz de paridade foi medida. Um projeto em 0.45.x permanece na linha 2.x desta biblioteca; subir o Drizzle é obrigatório, não opcional, e quebra quatro coisas — veja a página do adapter Drizzle.

O @nestjs/swagger só é necessário para gerar documentação OpenAPI com @ApiDynamicQuery e para testar filtros pela Swagger UI. Sem ele, o decorator continua registrando as regras do endpoint; apenas não emite parâmetro OpenAPI nenhum. Veja Swagger.

Bancos de dados

A paridade é prometida sobre um perfil certificado de banco, publicado em test/profiles/: PostgreSQL 18, MySQL 8.4 LTS e SQL Server 2022, com collation por ponto de código nas colunas de texto portáveis. collectProfileFacts() e checkPortabilityProfile() são exportados para você verificar o próprio banco contra ele, e forRoot({ portability: { enforce: true } }) transforma uma divergência em recusa em vez de surpresa.

O SQLite é o dialeto de referência, não uma célula da matriz: ele prova que o compilador de cada adapter implementa a semântica do plano. É nele que roda o 01-starter-app.

Duas famílias de coluna que seu schema precisa ganhar

Nenhuma das duas é configuração; as duas são DDL que a sua aplicação preenche.

Colunas dobradas. search, ilike e notIlike nunca emitem ILIKE nem o mode: 'insensitive' do Prisma. Eles comparam uma coluna pré-normalizada com um termo normalizado pela mesma função, e é isso que faz a mesma requisição devolver as mesmas linhas independentemente da collation do servidor. Um campo usado por search sem foldedField faz o defineQueryRules recusar-se a construir — a aplicação não sobe.
Colunas de ordem portável. uuid e enum não ordenam igual nas três famílias de banco, então a v3 ordena por um portableOrderField que você declara. Uma chave primária uuid precisa de uma em toda requisição, porque o desempate da paginação é sempre aplicado sobre a chave primária.

As duas estão detalhadas em Regras de whitelist do endpoint.

Adapters suportados

O adapter não é configurado globalmente. Ele é decidido pela source que você passa ao execute(), e cada fábrica de source vive no seu próprio subpath.

TypeORM

typeormSource(repository), de nestjs-rest-query/typeorm.

TypeORM configurado com pelo menos um banco, e entidades declaradas com os decorators do TypeORM.
As colunas companheiras seguem uma convenção aqui, sobre o path da propriedade da entidade: <campo>_folded e <campo>_order. O resolver marca automaticamente como interna qualquer propriedade terminada em _folded ou _order.
O nome do model é derivado, não escolhido: metadata.name.replace(/Entity$/, '').toLowerCase().
buildSchemaRegistry(repository) consegue derivar o registry lógico inteiro da metadata das entidades — mas só onde existe um Repository vivo.

Drizzle

drizzleSource({ db, dialect, table, relations }) mais drizzleDatabase({ client, dialect }), os dois de nestjs-rest-query/drizzle.

Drizzle 1.0.0-rc.4 ou posterior dentro da faixa, num driver suportado.
O adapter não lê o seu pgTable. Você declara um descritor lógico com createDrizzleTable({ name, model, columns }) e as relações por path pontuado.
O dialeto é argumento obrigatório, porque qual método de execução chamar (all() ou execute()) sai do dialeto declarado, nunca da inspeção do objeto.

Prisma

prismaSource({ client, model, manifest }), de nestjs-rest-query/prisma.

Um Prisma Client gerado, passado direto — sem cast, sem fachada própria.
Um manifesto escrito à mão com createPrismaManifest, ligando cada model ao delegate do client e declarando o provider.
Em sqlite e sqlserver, cinco operadores (like, notLike, ilike, notIlike, search) são recusados; veja a página do adapter Prisma.