@dudousxd/nestjs-filter

Core package for nestjs-filter -- declarative, ORM-agnostic filter classes for NestJS.

Provides BaseFilter, FilterRunner, decorators (@Filterable, @FilterFor, @ApplyFilter), FilterModule, exception handling, and testing utilities.

Install

pnpm add @dudousxd/nestjs-filter

You also need an ORM adapter package:

# MikroORM
pnpm add @dudousxd/nestjs-filter-mikro-orm

# TypeORM
pnpm add @dudousxd/nestjs-filter-typeorm

Quick Start

import { Injectable } from '@nestjs/common';
import { Filterable, FilterFor, BaseFilter, FilterModule, ApplyFilter } from '@dudousxd/nestjs-filter';

// 1. Define a filter
@Injectable()
@Filterable({ entity: User })
class UserFilter extends BaseFilter<QueryBuilder> {
  @FilterFor('name')
  applyName(value: string) {
    this.$query.andWhere({ name: value });
  }
}

// 2. Register
@Module({
  imports: [
    FilterModule.forRoot({ inputNormalizer: 'camelCase' }),
    FilterModule.forFeature([UserFilter]),
  ],
})
class AppModule {}

// 3. Use in controller
@Controller('users')
class UsersController {
  @Get()
  list(@ApplyFilter(UserFilter) qb: QueryBuilder) {
    return qb.getResultList();
  }
}

API Reference

Decorators

• @Filterable({ entity, allowed?, blocked? }) -- Class decorator. Associates a filter with an entity. allowed whitelists keys; blocked blacklists them. A blacklisted key is barred from filtering entirely: it is skipped in structured dispatch and dropped from where column filters (matching clauses are ignored with a warning, at any depth, rather than rejected). The runtime blacklistMethod(key) behaves the same; whitelistMethod/allowed grant dispatch access and do not constrain where.
• @FilterFor(inputKey?) -- Method decorator. Maps an input key to the method. Defaults to the method name if omitted.
• @ApplyFilter(FilterClass, options?) -- Parameter decorator. Resolves input from the request, runs the filter, and injects the QueryBuilder. Options: source ('auto'|'query'|'body'|Function), dto, resolve (dynamic filter selection).

Classes

• BaseFilter<TQuery> -- Abstract base class. Provides $query, $input, $context, $adapter via AsyncLocalStorage. Optional setup() hook.
• FilterRunner -- Injectable service. apply(FilterClass, input, qb, context?) runs a filter programmatically.
• FilterModule -- forRoot(options?) registers global infrastructure. forFeature(filters) registers filter classes.

Exceptions

• FilterException -- Abstract base.
• FilterNotRegisteredException -- Filter class not in DI container.
• FilterMissingEntityException -- Missing @Filterable({ entity }).
• FilterStateUnavailableException -- Accessing $query outside FilterRunner.apply().
• UnknownFilterKeyException -- Unknown key when onUnknownKey: 'throw'.
• FilterValidationException -- class-validator validation failed.
• FilterMethodException -- A filter method (or setup()) threw an error.

Exception Filter

• FilterExceptionFilter -- Catches FilterValidationException and returns { statusCode: 400, message, errors }.

Client-facing messages (this one and the runner's 400s) are translated through @nestjs/i18n when the app registers it (optional peer, >= 0.0.3 < 1.0), as filter.* keys; merge @dudousxd/nestjs-filter/i18n/en.json / pt-BR.json into your catalogs. Missing keys stay in English. See the Controllers guide ("Translated messages").

Testing (from @dudousxd/nestjs-filter/testing)

• FilterTestingModule -- forRoot(options?) and forFeature(filters). Defaults to validation: 'off'.
• makeMockQueryBuilder<E>() -- Proxy-based mock QB that records all calls. Access via qb.calls.

Types

• FilterInput<F> -- Extracts the input shape from a filter class.
• FilterContext -- { req?, user?, raw? }.
• FilterModuleOptions -- { inputNormalizer?, dropId?, onUnknownKey?, validation? }.
• ApplyFilterOptions -- { source?, dto?, resolve? }.
• InputSource -- 'auto' | 'query' | 'body' | ((req) => Record<string, unknown>).

Configuration

See the root README for full documentation.