Introduction#

A very common need for APIs is to filter a list through different conditions.

Filters receive query parameters to determine which conditions to apply, and the current request queryBuilder onto which apply them.

They are registered using decorators on either an @Entity or a property.

Built-ins#

There are 2 basic filters built-in, both extending the AbstractFilter :

SearchFilter, used with the @Search decorator, allows you to search using a StrategyType
PaginationFilter, used with the @Pagination decorator, allows you to paginate and order the results

Filter	Decorator	Specific options	Default options getter
AbstractFilter	none	all/allShallow/allNested	none
SearchFilter	@Search	defaultWhereStrategy	getSearchFilterDefaultConfig
PaginationFilter	@Pagination	defaultOrderBys / defaultOrderDirection / defaultRetrievedItemsLimit	getPaginationFilterDefaultConfig

If neither of them satisfies your need, you can always make your own custom filter by extending the AbstractFilter.

Enabling properties#

You will need to explicitly enable the properties you want to be filterable, else the corresponding query parameters will be ignored.

With the AbstractFilter class, you can quickly define which properties will be filterable. To do so, you need to set its options (DefaultFilterOptions) accordingly or/and by passing an array of property paths (FilterProperty).

By passing a dot delimited string, you can filter on a (deeply?) nested relation property

Allowing a set of properties#

Using the DefaultFilterOptions, you can allow every properties of a specific kind to be filtered.

#ts
1type DefaultFilterOptions = {
2    /** Make all property paths filtereable by default */
3    all?: boolean;
4    /** Make all (not nested) properties filterable by default */
5    allShallow?: boolean;
6    /** Make all nested property paths filtereable by default */
7    allNested?: boolean;
8};

An example with the @Search filter would look like this :

#ts
1@Search({ all: true })

Explicitly allow properties#

You can directly pass an array of FilterProperty, which is an array of property/nested property path.

#ts
1@Search(["id", "firstName", "role.identifier"])

Using both#

#ts
1@Search(["id", "firstName"], { allNested: true })

Metadata#

You can retrieve the RouteFiltersMeta registered by an filter decorator (such as @Search, @Pagination or @OrderBy) by using the getRouteFiltersMeta function.

Examples

SearchFilter