> ## Documentation Index
> Fetch the complete documentation index at: https://nestjs-query.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Helpers

> The  package provides a number of helper functions to transform or apply queries to a list of items.

An example use case for these helpers would be to write a `QueryService` that wraps a store that does not support the query options natively (e.g. An in memory collection of objects such as a static array of objects).

All examples will be based on the following DTO definition.

```ts theme={null}
interface TestDTO {

  first?: string | null
  last?: string | null
  age?: number | null
  isVerified?: boolean | null
  created?: Date | null
}
```

## applyFilter[​](#applyfilter "Direct link to applyFilter")

The `applyFilter` helper applies a `Filter` to a single object or an array of objects.

### Arguments[​](#arguments "Direct link to Arguments")

* `dto: DTO|DTO[]`

  * If a single object a function that will test the dto against the filter, returning `true` when if it matches the filter.
  * If an array of objects is provided the array will be filtered returning a new array with all elements that match the filter.

* `filter: Filter<DTO>` - The filter to check the object\[s] against. See [`Filtering`](/concepts/queries#filtering)

### Example[​](#example "Direct link to Example")

```ts theme={null}
import { applyFilter } from `@ptc-org/nestjs-query-core`;

const dtos: TestDTO[] = [
  {first: 'Bob', last: 'Yukon'}
  {first: 'Alice', last: 'Yukon'}
  {first: 'Sally', last: 'Yukon'}
  {first: 'Zane', last: 'Yukon'}
]
const filtered = applyFilter(dtos, {first: {in: ['Bob', 'Sally']})
```

```ts theme={null}
const dto: TestDTO = {first: 'Bob', last: 'Yukon'};
applyFilter<TestDTO>(dto, {first: {in: ['Bob', 'Sally']}) // true
applyFilter<TestDTO>(dto, {first: {eq: ['Alice', 'Zane']}) // false
```

## applySort[​](#applysort "Direct link to applySort")

The `applySort` will sort an array of dtos.

<Info>
  Because `applySort` uses the native `Array#sort` method it may not exactly match the ordering you would expect from a database.
</Info>

<Warning>
  It is expected that your data types all match. For example if you have a number field that also has some numbers represented as
  strings the applySort method may not work as expected.
</Warning>

### Arguments[​](#arguments-1 "Direct link to Arguments")

* `dto: DTO[]` - The array of DTOs to sort.
* `sortFields: SortField<DTO>[]` - The sorting criteria. See [`Sorting`](/concepts/queries#sorting)

### Example[​](#example-1 "Direct link to Example")

```ts theme={null}
import { applySort, SortDirection, SortNulls } from `@ptc-org/nestjs-query-core`;

const dtos: TestDTO[] = [
  {first: 'Bob', last: 'Yukon'}
  {first: 'Alice', last: 'Yukon'}
  {first: null, last: 'Yukon'}
  {first: 'Sally', last: 'Yukon'}
  {last: 'Yukon'}
  {first: 'Zane', last: 'Yukon'}
]
const sorted = applySort(dtos, [
   { field: 'first', direction: SortDirection.DESC, nulls: SortNulls.NULLS_LAST },
])
```

The resulting sorted array would be.

```ts theme={null}
[
  {first: 'Zane', last: 'Yukon'}
  {first: 'Sally', last: 'Yukon'}
  {first: 'Bob', last: 'Yukon'}
  {first: 'Alice', last: 'Yukon'}
  {first: null, last: 'Yukon'}
  {last: 'Yukon'}
]
```

## applyPaging[​](#applypaging "Direct link to applyPaging")

The `applyPaging` method will apply a `limit` and/or `offset` to an array of dtos.

### Arguments[​](#arguments-2 "Direct link to Arguments")

* `dto: DTO[]` - The array of DTOs to page.
* `paging: Paging` - The paging arguments to apply. See [`Paging`](/concepts/queries#paging)

### Example[​](#example-2 "Direct link to Example")

```ts theme={null}
import { applyPaging } from `@ptc-org/nestjs-query-core`;

const dtos: TestDTO[] = [
  {first: 'Bob', last: 'Yukon'}
  {first: 'Alice', last: 'Yukon'}
  {first: 'Sally', last: 'Yukon'}
  {first: 'Zane', last: 'Yukon'}
]
const paged = applyPaging(dtos, {offset: 1, limit: 2})
```

The resulting paged dtos would be.

```ts theme={null}
[
  {first: 'Alice', last: 'Yukon'}
  {first: 'Sally', last: 'Yukon'}
]
```

## applyQuery[​](#applyquery "Direct link to applyQuery")

The `applyQuery` uses the `applyFilter`, `applySorting`, and `applyPaging` methods to apply a `Query` to an array of DTOs.

### Arguments[​](#arguments-3 "Direct link to Arguments")

* `dto: DTO[]` - The array of DTOs to page.
* `query: Query<DTO>` - The query to apply to the array of dtos. See [`Queries`](/concepts/queries)

### Example[​](#example-3 "Direct link to Example")

```ts theme={null}
import { applyQuery, SortDirection } from `@ptc-org/nestjs-query-core`;

const dtos: TestDTO[] = [
  {first: 'Bob', last: 'Yukon', isVerified: true}
  {first: 'Alice', last: 'Yukon', isVerified: false}
  {first: 'Sally', last: 'Yukon', isVerified: true}
  {first: 'Zane', last: 'Yukon', isVerified: true}
]
const queryResult = applyQuery(dtos, {
  filter: { isVerified: { is: true } },
  sorting: [{ field: 'first', direction: SortDirection.DESC }],
  paging: { offset: 1, limit: 2 }
})
```

The resulting array of dtos would be.

```ts theme={null}
[
  {first: 'Sally', last: 'Yukon', isVerified: true}
  {first: 'Bob', last: 'Yukon', isVerified: true}
]
```

## transformFilter[​](#transformfilter "Direct link to transformFilter")

The transformFilter is used to remap fields in a `Filter`. This method is commonly used when defining a custom [Assembler](/concepts/advanced/assemblers).

### Arguments[​](#arguments-4 "Direct link to Arguments")

* `filter: Filter<From>` - The filter you want to transform.
* `fieldMap: QueryFieldMap<From, To>` - A map of fields where the key is a key in the From type, and the value is a key in the to type.

### Example[​](#example-4 "Direct link to Example")

```ts theme={null}
import { transformFilter, QueryFieldMap, Filter } from `@ptc-org/nestjs-query-core`;

class TestEntity {

  firstName!: string;
  lastName!: string;
}
const fieldMap: QueryFieldMap<TestDTO, TestEntity> = {
  first: 'firstName',
  last: 'lastName',
};
const dtoFilter: Filter<TestDTO> = {
  first: { eq: 'foo' },
  last: { neq: 'bar' },
};
const transformed = transformFilter(dtoFilter, fieldMap);
```

The new filter would be

```ts theme={null}
{
  firstName: { eq: 'foo' },
  lastName: { neq: 'bar' },
}
```

## transformSort[​](#transformsort "Direct link to transformSort")

The `transformSort` is used to remap fields in an array of `SortField<DTO>[]`. This method is commonly used when defining a custom [Assembler](/concepts/advanced/assemblers).

### Arguments[​](#arguments-5 "Direct link to Arguments")

* `sortFields: SortField<From>[]` - The array of sorting criteria to transform.
* `fieldMap: QueryFieldMap<From, To>` - A map of fields where the key is a key in the From type, and the value is a key in the to type.

### Example[​](#example-5 "Direct link to Example")

```ts theme={null}
import { transformSort, QueryFieldMap, SortField, SortDirection } from `@ptc-org/nestjs-query-core`;

class TestEntity {

  firstName!: string;
  lastName!: string;
}
const fieldMap: QueryFieldMap<TestDTO, TestEntity> = {
  first: 'firstName',
  last: 'lastName',
};
const dtoSort: SortField<TestDTO>[] = [
  { field: 'first', direction: SortDirection.DESC },
  { field: 'last', direction: SortDirection.ASC },
];
const transformed = transformSort(dtoSort, fieldMap);
```

```ts theme={null}
;[
  { field: 'firstName', direction: SortDirection.DESC },
  { field: 'lastName', direction: SortDirection.ASC }
]
```

## transformQuery[​](#transformquery "Direct link to transformQuery")

The `transformQuery` method uses the `transformFilter` and `transformSort` methods to remap a `Query`. This method is commonly used when defining a custom [Assembler](/concepts/advanced/assemblers).

### Arguments[​](#arguments-6 "Direct link to Arguments")

* `sortFields: Query<From>` - The query to transform.
* `fieldMap: QueryFieldMap<From, To>` - A map of fields where the key is a key in the From type, and the value is a key in the to type.

### Example[​](#example-6 "Direct link to Example")

```ts theme={null}
import { transformQuery, QueryFieldMap, Query, SortDirection } from `@ptc-org/nestjs-query-core`;

class TestEntity {

  firstName!: string;
  lastName!: string;
}
const fieldMap: QueryFieldMap<TestDTO, TestEntity> = {
  first: 'firstName',
  last: 'lastName',
};
const dtoQuery: Query<TestDTO> = {
  filter: { first: { eq: 'foo' }, last: { neq: 'bar' } }
  sorting: [
    { field: 'first', direction: SortDirection.DESC },
    { field: 'last', direction: SortDirection.ASC },
  ]
};
const transformed =  transformQuery(dtoQuery, fieldMap);
```

The resulting query would be.

```ts theme={null}
{
  filter: { firstName: { eq: 'foo' }, lastName: { neq: 'bar' } }
  sorting: [
    { field: 'firstName', direction: SortDirection.DESC },
    { field: 'lastName', direction: SortDirection.ASC },
  ]
}
```

## getFilterComparisons[​](#getfiltercomparisons "Direct link to getFilterComparisons")

Used to search a filter get a list of comparison objects for a given key.

### Arguments[​](#arguments-7 "Direct link to Arguments")

* `filter: Filter<DTO>` - The filter to search.
* `key: keyof DTO` - The key in the DTO object to search for in the filter object.

### Example[​](#example-7 "Direct link to Example")

```ts theme={null}
import { Filter, getFilterComparisons } from `@ptc-org/nestjs-query-core`;

class TestDTO {

  age!: number;
  title!: string;
}
const filter: Filter<TestDTO> = {
  age: { gte: 10 },
  or: [{ title: { like: '%bar' } }, { title: { eq: 'foobar' } }],
};
const comparisons = getFilterComparisons(filter, 'title');
```

The resulting array would be

```ts theme={null}
;[{ like: '%bar' }, { eq: 'foobar' }]
```

## getFilterOmitting[​](#getfilteromitting "Direct link to getFilterOmitting")

Used to get a filter with a given key removed.

### Arguments[​](#arguments-8 "Direct link to Arguments")

* `filter: Filter<DTO>` - The filter containing the unwanted key.
* `key: keyof DTO` - The key in the DTO object to remove in the filter object.

### Example[​](#example-8 "Direct link to Example")

```ts theme={null}
import { Filter, getFilterOmitting } from `@ptc-org/nestjs-query-core`;

class TestDTO {

  age!: number;
  title!: string;
}
const filter: Filter<TestDTO> = {
  age: { gte: 10 },
  or: [{ title: { like: '%bar' } }, { title: { eq: 'foobar' } }],
};
const filterWithoutTitle = getFilterOmitting(filter, 'title');
```

The resulting filter would be

```ts theme={null}
{
  age: { gte: 10 },
}
```

[Edit this page](https://github.com/tripss/nestjs-query/edit/master/docs/utilities/query-helpers)