RequestQueryBuilder Overview

Build complex REST API queries with a fluent, type-safe interface

Introduction

The RequestQueryBuilder class provides a fluent API for constructing complex query strings for NestJS CRUD operations. It supports filtering, sorting, pagination, field selection, and relation joining with a chainable, type-safe interface.

Installation

npm install @nestjsx/crud-request

Basic Usage

import { RequestQueryBuilder } from '@nestjsx/crud-request';

const queryString = RequestQueryBuilder.create()
  .select(['id', 'name', 'email'])
  .setFilter({ field: 'status', operator: '$eq', value: 'active' })
  .sortBy({ field: 'createdAt', order: 'DESC' })
  .setLimit(10)
  .query();

// Result: fields=id,name,email&filter=status||$eq||active&sort=createdAt,DESC&limit=10

Creating an Instance

There are two ways to create a RequestQueryBuilder instance:

Static Factory Method

const qb = RequestQueryBuilder.create();

Constructor

const qb = new RequestQueryBuilder();

Create from Parameters

You can initialize a query builder with all parameters at once:

const qb = RequestQueryBuilder.create({
  fields: ['id', 'name', 'email'],
  filter: { field: 'status', operator: '$eq', value: 'active' },
  sort: { field: 'createdAt', order: 'DESC' },
  limit: 10,
  page: 1
});

Key Features

Field Selection

Choose which fields to return in the response

Filtering

Filter records with various comparison operators

Sorting

Sort results by one or multiple fields

Pagination

Paginate results with limit/offset or page-based pagination

Relations

Join and select related entities

Search

Complex search with AND/OR conditions

Configuration

You can configure global options for all RequestQueryBuilder instances:

RequestQueryBuilder.setOptions({
  delim: '||',        // Delimiter for query parts
  delimStr: ',',      // Delimiter for array values
  paramNamesMap: {
    fields: ['fields', 'select'],
    filter: 'filter',
    sort: 'sort',
    limit: ['limit', 'per_page'],
    offset: 'offset',
    page: 'page',
    cache: 'cache',
    includeDeleted: 'include_deleted'
  }
});

delim · string · default: "||"

Delimiter used to separate parts of a query parameter (e.g., field||operator||value)

delimStr · string · default: ","

Delimiter used to separate array values (e.g., field1,field2,field3)

paramNamesMap · object

Map of parameter names used in the query string. Each key can be a string or array of strings.

Query Generation

After building your query, generate the query string:

const queryString = qb.query();           // URL-encoded
const rawQuery = qb.query(false);         // Not encoded

When search() is used, it takes precedence over filter and or conditions. The filter and or parameters will be ignored in the final query string.

Advanced Examples

Complex Filtering with OR Conditions

const qb = RequestQueryBuilder.create()
  .setFilter([{ field: 'status', operator: '$eq', value: 'active' }])
  .setOr([
    { field: 'priority', operator: '$eq', value: 'high' },
    { field: 'priority', operator: '$eq', value: 'urgent' }
  ])
  .query();

Joining Relations

const qb = RequestQueryBuilder.create()
  .setJoin({ field: 'profile' })
  .setJoin({ field: 'posts', select: ['id', 'title', 'createdAt'] })
  .query();

Search with Complex Conditions

const qb = RequestQueryBuilder.create()
  .search({
    name: { $cont: 'John' },
    $or: [
      { age: { $gte: 18 } },
      { verified: true }
    ]
  })
  .query();

Properties

queryObject · object

The internal object representation of the query before it’s converted to a string

queryString · string

The generated query string (available after calling query())

options · RequestQueryBuilderOptions

The current configuration options for the builder

Next Steps

Methods Reference

Explore all available methods and their signatures

Operators Reference

Learn about all query operators and how to use them