crud-query-parser

This library parses query parameters from HTTP requests and converts them to database queries, allowing advanced filtering, column selection, pagination and relation joining.

Features

• Modular architecture, can be extended as needed
• Flexible request manipulation and filtering
• Supports the @nestjsx/crud query parameter syntax
• TypeORM support
• Sequelize support
• MongoDB and Mongoose support
• DynamoDB support
• JS arrays support
• Framework-agnostic
  • Supports NestJS, NextJS, Express, Fastify, h3, tinyhttp, http package and many more

Install

npm install crud-query-parser

Usage

flowchart LR
    A(RequestParser) --> B(Filters) --> C(QueryAdapter)

Loading

You have to pick a request parser and a query adapter.

const parser = new CrudRequestParser();
const adapter = new TypeOrmQueryAdapter();
const userRepository = AppDataSource.getRepository(UserEntity); // TypeORM repository

// ...

// The request query object
// This object will likely come from the HTTP request
const requestQuery = { ... };

// Parses the query into a CrudRequest object
let crudRequest = parser.parse(requestQuery);

// Apply filters
// crudRequest = filterRelations(crudRequest, ['posts']);
// crudRequest = ensureLimit(crudRequest, 25, 100);

// Using the query adapter, you can run the query through your ORM by using the CrudRequest
const result = await adapter.getMany(userRepository.createQueryBuilder(), crudRequest); // GetManyResult<UserEntity>

// The result object has properties like data, page, total
console.log(result);

Request parsers

CRUD Request

The CRUD Request parser is an implementation of the @nestjsx/crud query params format.

import { CrudRequestParser } from 'crud-query-parser/parsers/crud';

const parser = new CrudRequestParser();

// Then, you have to pass a query string object to it
// const crudRequest = parser.parse(request.query);

Read more about the CRUD Request parser.

Database adapters

TypeORM

This adapter works with TypeORM 0.3.x and 0.2.x

import { TypeOrmQueryAdapter } from 'crud-query-parser/adapters/typeorm';

const adapter = new TypeOrmQueryAdapter();

// Then, you can pass a query builder to it:
// const result = await adapter.getMany(repository.createQueryBuilder(), crudRequest);

Read more about the TypeORM adapter.

Sequelize

This adapter works with Sequelize 6

import { SequelizeQueryAdapter } from 'crud-query-parser/adapters/sequelize';

const adapter = new SequelizeQueryAdapter();

// Then, you can pass a FindOptions to it:
// const result = await adapter.getMany({}, crudRequest);

Read more about the Sequelize adapter.

DynamoDB

This adapter requires @aws-sdk/client-dynamodb and @aws-sdk/util-dynamodb 3.x.x

import { DynamoDBQueryAdapter } from 'crud-query-parser/adapters/dynamodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

const adapter = new DynamoDBQueryAdapter({
  client: new DynamoDBClient(),
  tableName: 'posts',
  partitionKey: 'id',
});

// Then, you can pass a partial Query/Scan input to it:
// const result = await adapter.getMany({}, crudRequest);

Read more about the DynamoDB adapter.

MongoDB

import { MongoDBQueryAdapter } from 'crud-query-parser/adapters/mongodb';

const adapter = new MongoDBQueryAdapter();

// Then, you can pass a collection to it:
// const result = await adapter.getMany(collection, crudRequest);

Read more about the MongoDB adapter.

Mongoose

import { MongooseQueryAdapter } from 'crud-query-parser/adapters/mongodb';

const adapter = new MongooseQueryAdapter();

// Then, you can pass a Query to it:
// const result = await adapter.getMany(Model.find(), crudRequest);

Read more about the Mongoose adapter.

Array

This adapter can filter, sort and map plain JS arrays.

import { ArrayQueryAdapter } from 'crud-query-parser/adapters/array';

const adapter = new ArrayQueryAdapter();

// Then, you can pass an array of entities to it:
// const result = await adapter.getMany([], crudRequest);

Read more about the array adapter.

Frameworks

crud-query-parser is framework-agnostic. You can pass any query parameters object to the parser and it should work out-of-the-box. We have a few examples for the frameworks listed below:

• NestJS
• NextJS
• Express
• Fastify
• h3
• tinyhttp
• Node.js http

We also have special integrations to improve DX:

NestJS Integration

The NestJS Integration has decorators that automatically parses the request. It also has built-in OpenAPI support.

import { Crud, ParseCrudRequest } from 'crud-query-parser/helpers/nestjs';
import { CrudRequestParser } from 'crud-query-parser/parsers/crud';

@Controller('users')
export class UserController {

  @Get()
  @Crud(CrudRequestParser) // <- You specify which parser to use
  public async getMany(@ParseCrudRequest() crudRequest: CrudRequest) { // <- The request query will be automatically parsed
    // ...
  }

}

Read more about the NestJS Integration.

Express Integration

The Express Integration has a middleware that automatically parses and memoizes the request.

import { crud } from 'crud-query-parser/helpers/express';
import { CrudRequestParser } from 'crud-query-parser/parsers/crud';

app.use(crud(CrudRequestParser)); // <- You specify which parser to use

app.get('/users', (req, res) => {
  const crudRequest = req.getCrudRequest(); // <- The request will be automatically parsed and memoized

  // ...
});

Read more about the Express Integration.

Filters

You may need to filter what the user can or cannot query. You are free to modify the CrudRequest object however you like.

There are a few filters provided by the library, which are listed below.

Enforce a "where" condition

This filter will add the condition on top of all other where conditions

import { ensureCondition, ensureEqCondition } from 'crud-query-parser/filters';

// ...

crudRequest = ensureCondition(crudRequest, {
  field: ['isActive'],
  operator: CrudRequestWhereOperator.EQ,
  value: true,
});

// Alternatively, a shorthand for equals conditions:
crudRequest = ensureEqCondition(crudRequest, {
  isActive: true,
});

Ensure page limit

This filter will ensure that the requested limit does not go above the maximum. It also sets a default value whenever the limit is omitted.

import { ensureLimit } from 'crud-query-parser/filters';

// ...

const defaultLimit = 25;
const maxLimit = 100;

crudRequest = ensureLimit(crudRequest, defaultLimit, maxLimit);

Filter property access

This filter removes any property from the request that is not in the allowlist. It removes unallowed properties from the select fields, where conditions, relations and sorting.

import { filterProperties } from 'crud-query-parser/filters';

// ...

crudRequest = filterProperties(crudRequest, [
  'id',
  'name',
  'posts',
  'posts.id',
  'posts.name',
]);

Filter relations

This filter removes any relation from the request that is not in the allowlist. It's the same as the filterProperties but only filters relations.

import { filterRelations } from 'crud-query-parser/filters';

// ...

crudRequest = filterRelations(crudRequest, ['posts']);