Regras de permissões do endpoint

Filtros e operadores

Formato: filter[campo][operador]=valor

O campo deve estar listado em filters do RulesConfig do endpoint — campos não autorizados geram 400 Bad Request.

Operadores disponíveis

Operadores com comportamento especial

in e notIn — o valor é uma lista CSV. Cada item é tratado como elemento separado:

filter[status][in]=active,pending
filter[status][notIn]=deleted,banned

between — dois valores separados por vírgula, aplicados como BETWEEN val1 AND val2:

filter[createdAt][between]=2024-01-01,2024-12-31
filter[price][between]=10,99

isNull — true gera IS NULL, false gera IS NOT NULL. Não há operador separado isNotNull:

filter[deletedAt][isNull]=true
filter[photoUrl][isNull]=false

ilike — usa LOWER() para garantir portabilidade entre PostgreSQL, MySQL e SQLite. Para PostgreSQL com grandes volumes, considere criar um índice funcional LOWER(campo) para melhor desempenho:

filter[name][ilike]=joao

Restringindo operadores globalmente

Por padrão todos os operadores são permitidos. Para restringir, configure operators.allowed no forRoot:

DynamicQueryBuilderModule.forRoot({
  operators: {
    allowed: ['eq', 'ne', 'like', 'in'],
  },
});

Operadores fora da lista lançam BadRequestException.

Restringindo operadores por endpoint

Se uma rota definir operators dentro do seu RulesConfig, essa whitelist específica do endpoint sobrescreve a configuração global do forRoot apenas naquela rota.

const rules: RulesConfig = {
  filters: ['name', 'status'],
  operators: {
    allowed: ['eq', 'like'],
  },
};

Use isso quando um endpoint precisar de uma whitelist mais restrita que o restante da aplicação. Um objeto vazio no endpoint, operators: {}, significa "permitir todos os operadores" para aquela rota, mesmo que a configuração global esteja restrita.

Sorts

Formato: sort=campo,-outro (prefixo - para desc, sem prefixo para asc)

O campo deve estar listado em sorts do RulesConfig.

Fields

Formato: fields=id,name,email

Restringe as colunas retornadas pela query (SELECT). Quando omitido, todas as colunas da entidade são retornadas.

O campo deve estar listado em fields do RulesConfig; a resposta fica limitada à whitelist de campos declarada.

Includes

Formato: includes=company,roles

Carrega relações pelo adapter configurado. Cada relação precisa estar listada em includes do RulesConfig — relações não autorizadas geram 400 Bad Request.

Não há eager load implícito: includes só são aplicados quando o parâmetro includes estiver presente na query string.

Paginação

Os defaults e o máximo de perPage são configuráveis via forRoot:

DynamicQueryBuilderModule.forRoot({
  pagination: {
    defaultPerPage: 20,
    maxPerPage: 200,
  },
});

Resposta com paginação ativa

{
  "data": [...],
  "page": 1,
  "perPage": 10,
  "total": 42,
  "lastPage": 5
}

Resposta com paginate=false

{
  "data": [...]
}