Installing @nestjsx/crud-request

Installation and usage guide for the request query builder package

Installation

The request package can be installed independently or as part of the full CRUD framework:

npm

npm install @nestjsx/crud-request

yarn add @nestjsx/crud-request

pnpm add @nestjsx/crud-request

If you install @nestjsx/crud, this package is automatically included as a dependency. You only need to install it separately if you want to use the query builder in a standalone project.

Automatic Dependencies

The following packages are automatically installed:

• @nestjsx/util - Shared utility functions
• qs - Query string parsing and stringification

Usage in Frontend Applications

This package is particularly useful in frontend applications for building API queries:

Basic Setup

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

// Create a query builder instance
const qb = RequestQueryBuilder.create();

Building Simple Queries

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

// Simple search
const query = RequestQueryBuilder.create()
  .search({ name: 'John' })
  .query();

// Result: "?s={\"name\":\"John\"}"

Building Complex Queries

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

const query = RequestQueryBuilder.create()
  .search({
    status: 'active',
    role: 'admin'
  })
  .setFilter({
    field: 'age',
    operator: CondOperator.GREATER_THAN,
    value: 18
  })
  .sortBy([
    { field: 'createdAt', order: 'DESC' },
    { field: 'name', order: 'ASC' }
  ])
  .setLimit(20)
  .setPage(1)
  .setJoin({ field: 'profile' })
  .query();

// Use with your HTTP client
const response = await fetch(`/api/users${query}`);

Common Query Patterns

Pagination

const query = RequestQueryBuilder.create()
  .setLimit(10)
  .setPage(1)
  .query();

Sorting

const query = RequestQueryBuilder.create()
  .sortBy({ field: 'name', order: 'ASC' })
  .query();

Filtering

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

const query = RequestQueryBuilder.create()
  .setFilter({
    field: 'email',
    operator: CondOperator.CONTAINS,
    value: '@example.com'
  })
  .query();

Relations

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

Field Selection

const query = RequestQueryBuilder.create()
  .select(['id', 'name', 'email'])
  .query();

Usage in Backend Applications

Automatic Parsing

When using @nestjsx/crud, request parsing happens automatically:

import { Controller } from '@nestjs/common';
import { Crud, CrudRequest, ParsedRequest } from '@nestjsx/crud';

@Crud({
  model: { type: User }
})
@Controller('users')
export class UserController {
  constructor(public service: UserService) {}
  
  // Access parsed request in overridden methods
  @Override()
  getMany(@ParsedRequest() req: CrudRequest) {
    // req.parsed contains the parsed query
    return this.service.getMany(req);
  }
}

Manual Parsing

You can also parse queries manually:

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

const parser = RequestQueryParser.create();
const parsed = parser.parseQuery({
  fields: 'id,name,email',
  sort: 'name,ASC',
  limit: '10',
  page: '1'
});

Integration with HTTP Clients

Axios

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

const query = RequestQueryBuilder.create()
  .search({ status: 'active' })
  .query();

const response = await axios.get(`/api/users${query}`);

Fetch API

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

const query = RequestQueryBuilder.create()
  .setLimit(20)
  .query();

const response = await fetch(`/api/users${query}`);
const data = await response.json();

Angular HttpClient

import { HttpClient } from '@angular/common/http';
import { RequestQueryBuilder } from '@nestjsx/crud-request';

const query = RequestQueryBuilder.create()
  .sortBy({ field: 'name', order: 'ASC' })
  .query();

this.http.get(`/api/users${query}`).subscribe(data => {
  console.log(data);
});

TypeScript Support

The package includes full TypeScript definitions:

import { 
  RequestQueryBuilder,
  CondOperator,
  QueryFilter,
  QuerySort,
  QueryJoin 
} from '@nestjsx/crud-request';

// Type-safe filter
const filter: QueryFilter = {
  field: 'age',
  operator: CondOperator.GREATER_THAN,
  value: 18
};

// Type-safe sort
const sort: QuerySort = {
  field: 'name',
  order: 'ASC'
};

Available Operators

The package provides the following filter operators:

• EQUALS - Equal to
• NOT_EQUALS - Not equal to
• GREATER_THAN - Greater than
• LOWER_THAN - Less than
• GREATER_THAN_EQUALS - Greater than or equal
• LOWER_THAN_EQUALS - Less than or equal
• STARTS - Starts with
• ENDS - Ends with
• CONTAINS - Contains
• EXCLUDES - Excludes
• IN - In array
• NOT_IN - Not in array
• IS_NULL - Is null
• NOT_NULL - Is not null
• BETWEEN - Between values

Next Steps

Core Package

Learn about the core CRUD package

TypeORM Integration

Add TypeORM for database operations

Troubleshooting

Query String Too Long

If your query strings are getting too long, consider:

• Using POST requests for complex filters
• Implementing server-side saved filters
• Breaking down complex queries into multiple requests

TypeScript Errors

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}