nest-typeorm-query-parser v0.0.4
Summary
comment: <> (- Examples(#examples))
comment: <> (- Explain the Resources(#explain-the-resources))
comment: <> ( - Queries with @MongoQuery() | @MongoQueryParser()(#queries-with-mongoquery--mongoqueryparser))
comment: <> ( - Pagination(#pagination))
comment: <> ( - Ordering(#ordering))
comment: <> ( - Select(#select))
comment: <> ( - Filters(#filters))
comment: <> ( - Simple Filters(#simple-filters))
comment: <> ( - Partial Filters(#partial-filters))
comment: <> ( - Comparison Filters(#comparison-filters))
comment: <> ( - Element Filters(#element-filters))
comment: <> ( - AND | OR Filters(#and--or-filters))
comment: <> ( - Populate(#populate))
comment: <> (- Observations(#observations))
comment: <> (- Practical Examples(#practical-examples))
comment: <> (- Upcoming Features(#upcoming-features))
Prerequisites
As the name of the library suggests, it was built to work together with the NestJS framework.
Installing
Use the follow command:
npm i --save nest-typeorm-query-parser
Usage
There are two ways to use the parsers available in this library: as a ParamDecorator or as a MethodDecorator.
If you want to use it as a ParamDecorator, just add the tag referring to the Parser to be used as a method parameter. Example:
import { Get } from '@nestjs/common';
import { Controller } from '@nestjs/common';
import { ResourceService } from './resource.service';
import { TypeOrmQuery, TypeOrmQueryModel } from 'nest-typeorm-query-parser';
@Controller('resources')
export class ResourceController {
constructor(private readonly _service: ResourceService) {}
@Get()
public find(@TypeOrmQuery() query: TypeOrmQueryModel) {
return this._service.find(query);
}
}It can also be used as a MethodDecorator. Just use the tag referring to the Parser to be used as the method decorator. Example:
import { Injectable } from '@nestjs/common';
import { TypeOrmQueryParser, TypeOrmQueryModel } from 'nest-typeorm-query-parser';
@Injectable()
export class ResourceService {
@TypeOrmQueryParser()
public find(query: TypeOrmQueryModel) {
return [];
}
}NOTE: When using the library as a MethodDecorator, you can receive other arguments in the method in question, but the query has to be passed as the first argument of the function, so that the treatment is done properly.
comment: <> (## Examples)
comment: <> (##### Request: http://localhost:3000/resources)
comment: <> (##### Query:)
comment: <> (`json)
comment: <> ({)
comment: <> ( "limit": 100,)
comment: <> ( "skip": 0,)
comment: <> ( "select": {},)
comment: <> ( "sort": {},)
comment: <> ( "populate": [],)
comment: <> ( "filter": {})
comment: <> (})
comment: <> (`)
comment: <> (##### Request: http://localhost:3000/resources?limit=10&page=2&select=_id,name,age&sort=-created_at&age=gt:30)
comment: <> (##### Query:)
comment: <> (`json)
comment: <> ({)
comment: <> ( "limit": 10,)
comment: <> ( "skip": 10,)
comment: <> ( "select": {)
comment: <> ( "_id": 1,)
comment: <> ( "name": 1,)
comment: <> ( "age": 1)
comment: <> ( },)
comment: <> ( "sort": {)
comment: <> ( "created_at": -1)
comment: <> ( },)
comment: <> ( "populate": [],)
comment: <> ( "filter": {)
comment: <> ( "age": {)
comment: <> ( "$gt": 30)
comment: <> ( })
comment: <> ( })
comment: <> (})
comment: <> (`)
comment: <> (comment: <> (## Explain the Resources))
comment: <> (comment: <> (## Queries with @MongoQuery() | @MongoQueryParser()))
comment: <> (comment: <> (### Pagination))
comment: <> (comment: <> (The paging feature is very useful for clients who will consume your API. It is through this feature that applications))
comment: <> (comment: <> (can define the data limit in a query, as well as define which page to be displayed. Each time a page of an application))
comment: <> (comment: <> (is selected, it means that some resources have been displaced (data offset or skip data).))
comment: <> (comment: <> (There is a mathematical rule that relates page number to resource offset. Basically:))
comment: <> (comment: <> (offset = (page - 1) * limit, where page > 0.))
comment: <> (comment: <> (This means that for a limit of 10 elements per page:))
comment: <> (comment: <> (- To access page 1, the offset will be equal to = (1 - 1) * 10, so offset = 0))
comment: <> (comment: <> (- To access page 2, the offset will be equal to = (2 - 1) * 10, so offset = 10))
comment: <> (comment: <> (- To access page 3, the offset will be equal to = (3 - 1) * 10, so offset = 20))
comment: <> (comment: <> (And so on.))
comment: <> (comment: <> (With this library, it is possible to use pagination with the page parameter, or using the skip manually. By default,))
comment: <> (comment: <> (the limit value is 100 and skip value is 0.))
comment: <> (comment: <> (Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?limit=10&page=3))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "limit": 10,))
comment: <> (comment: <> ( "skip": 20))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?limit=10&skip=20))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "limit": 10,))
comment: <> (comment: <> ( "skip": 20))
comment: <> (comment: <> (### Ordering))
comment: <> (comment: <> (To work with ordering, you need to specify one or more sorting parameters, and whether you want the sorting to be))
comment: <> (comment: <> (ascending or descending. For ascending ordering, just put the name of the ordering parameter. For descending ordering,))
comment: <> (comment: <> (you need to put a "-" symbol before the name of the ordering parameter. Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?sort=created_at))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "sort": {))
comment: <> (comment: <> ( "created_at": 1))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?sort=-created_at))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "sort": {))
comment: <> (comment: <> ( "created_at": -1))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?sort=-age,name))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "sort": {))
comment: <> (comment: <> ( "age": -1,))
comment: <> (comment: <> ( "name": 1))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (In multiple-parameter ordering, the first ordering parameter has higher priority than the second, and so on. In the))
comment: <> (comment: <> (example above, the ordering will be given primarily by the age parameter, in descending order. If there are two or))
comment: <> (comment: <> (more objects with the same value in age, then those objects will be sorted by name in ascending order.))
comment: <> (comment: <> (### Select))
comment: <> (comment: <> (With this library, you can choose which parameters should be returned by the API. However, Mongo has a peculiarity: you))
comment: <> (comment: <> (can also specify which parameters you don't want to be returned. The logic is similar to ordering: to specify which))
comment: <> (comment: <> (parameters are to be returned, simply enter the parameter name; and to specify which parameters should not be returned,))
comment: <> (comment: <> (just place a "-" symbol before the parameter.))
comment: <> (comment: <> (Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?select=_id,name,age))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "select": {))
comment: <> (comment: <> ( "_id": 1,))
comment: <> (comment: <> ( "name": 1,))
comment: <> (comment: <> ( "age": 1))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?select=-_id,-created_at,-updated_at))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "select": {))
comment: <> (comment: <> ( "_id": 0,))
comment: <> (comment: <> ( "created_at": 0,))
comment: <> (comment: <> ( "updated_at": 0))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (It is interesting to use one or the other in your queries, as one is complementary to the other. If you want almost all))
comment: <> (comment: <> (parameters except a few, use the option to ignore parameters. If you want some parameters, and ignore the others, use))
comment: <> (comment: <> (the option to select the ones you want.))
comment: <> (comment: <> (### Filters))
comment: <> (comment: <> (Now let's go to the most complex part of the library: the filters. There are several ways to apply filters in this))
comment: <> (comment: <> (library, so I'm going to break this topic down into subtopics for every possible filter approach.))
comment: <> (comment: <> (#### Simple Filters))
comment: <> (comment: <> (Simple filters are equality filters. Basically it's set key=value. All filter parameters are defined as string, so there))
comment: <> (comment: <> (are some validations that are done on these values.))
comment: <> (comment: <> (1. If the value is a string number, it is transformed into a number, either integer or float/double (up to 16 decimal))
comment: <> (comment: <> ( places);))
comment: <> (comment: <> (2. If the value is in yyyy-MM-dd format or yyyy-MM-ddThh:mm:ss.sZ format, it is transformed into a Date object;))
comment: <> (comment: <> (3. If the value is 'true' or 'false', it is transformed into a boolean value, according to your value;))
comment: <> (comment: <> (4. Otherwise, the value is considered as a string.))
comment: <> (comment: <> (Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?name=John%20Doe&age=31&birth_date=1990-01-01))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "name": "John Doe",))
comment: <> (comment: <> ( "age": 31,))
comment: <> (comment: <> ( "birth_date": 1990-01-01T00:00:00.000Z))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (#### MultiLevel Filters))
comment: <> (comment: <> (You can specify multilevel filters. This means that, if you have an object that has a field that is another object, you))
comment: <> (comment: <> (can perform a search with filters through the parameters of the internal object. Example:))
comment: <> (comment: <> (##### Object))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "_id": "613532a350857c1c8d1d10d9",))
comment: <> (comment: <> ( "name": "Filippo Nyles",))
comment: <> (comment: <> ( "age": 28,))
comment: <> (comment: <> ( "current_job": {))
comment: <> (comment: <> ( "title": "Budget/Accounting Analyst III",))
comment: <> (comment: <> ( "salary": 4776.8))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?current_job.title=Budget/Accounting%20Analyst%20III))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "current_job.title": "Budget/Accounting Analyst III"))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (#### Partial Filters))
comment: <> (comment: <> (Partial filters are a way to search a string type value for a part of the value. There are three ways to use partial))
comment: <> (comment: <> (filters. Making an analogy with javascript, it would be like using the startsWith, endsWith and includes methods,))
comment: <> (comment: <> (where:))
comment: <> (comment: <> (- startsWith: search for a string-type value that starts with a given substring. To do this, just add a "*" at the))
comment: <> (comment: <> ( beginning of the substring.))
comment: <> (comment: <> (- endsWith: search for a string-type value that ends with a given substring. To do this, just add a "*" at the end of))
comment: <> (comment: <> ( the substring.))
comment: <> (comment: <> (- includes: search for a string value that contains a specific substring. To do this, just add a "*" at the beginning))
comment: <> (comment: <> ( and end of the substring.))
comment: <> (comment: <> (Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?name=Lu&email=gmail.com&job=Developer))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`JSON))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "name": {))
comment: <> (comment: <> ( "$regex": "^Lu",))
comment: <> (comment: <> ( "$options": "i"))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( "email": {))
comment: <> (comment: <> ( "$regex": "gmail.com$",))
comment: <> (comment: <> ( "$options": "i"))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( "job": {))
comment: <> (comment: <> ( "$regex": "Developer",))
comment: <> (comment: <> ( "$options": "i"))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (#### Comparison Filters))
comment: <> (comment: <> (Comparison operators are specific filtering options to check whether a parameter has a value. It is possible to check))
comment: <> (comment: <> (not only equality, but other mathematical operators, such as: ">", ">=", "<", "<=", "!=". In addition, you can use))
comment: <> (comment: <> (comparison operators to check whether an element is in an array.))
comment: <> (comment: <> (According to the mongodb documentation(https://docs.mongodb.com/manual/reference/operator/query-comparison/), the))
comment: <> (comment: <> (available comparison operators are:))
comment: <> (comment: <> (- $eq: Matches values that are equal to a specified value.))
comment: <> (comment: <> (- $gt: Matches values that are greater than a specified value.))
comment: <> (comment: <> (- $gte: Matches values that are greater than or equal to a specified value.))
comment: <> (comment: <> (- $in: Matches any of the values specified in an array.))
comment: <> (comment: <> (- $lt: Matches values that are less than a specified value.))
comment: <> (comment: <> (- $lte: Matches values that are less than or equal to a specified value.))
comment: <> (comment: <> (- $ne: Matches all values that are not equal to a specified value.))
comment: <> (comment: <> (- $nin: Matches none of the values specified in an array.))
comment: <> (comment: <> (To use these operators, just pass the comparator tag without the "$" symbol. Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?age=gt:30))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`JSON))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "age": {))
comment: <> (comment: <> ( "$gt": 30))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (I won't put an example with all operators here, but you can test arithmetic comparison operators on parameters with))
comment: <> (comment: <> (values of type string or number, or test the operators of $in and $nin on parameters of type array.))
comment: <> (comment: <> (#### Element Filters))
comment: <> (comment: <> (Element filters are filters used to deal with parameters that make up the entity's schema. There are two types of))
comment: <> (comment: <> (element filter possibilities:))
comment: <> (comment: <> (- $exists: returns elements that have or do not have a specific field))
comment: <> (comment: <> (- $type: returns elements whose field has a specific type.))
comment: <> (comment: <> (Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?created_at=exists:true&updated_at=exists:false&jobs=type:array))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`JSON))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "created_at": {))
comment: <> (comment: <> ( "$exists": true))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( "updated_at": {))
comment: <> (comment: <> ( "$exists": false))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( "jobs": {))
comment: <> (comment: <> ( "$type": "array"))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (The $exists filter only works with true or false values. If a different value is entered, the filter will be))
comment: <> (comment: <> (ignored.))
comment: <> (comment: <> (The same goes for the $type filter, which only works with valid type values defined in))
comment: <> (comment: <> (the mongodb documentation(https://docs.mongodb.com/manual/reference/operator/query/type/#mongodb-query-op.-type); ())
comment: <> (comment: <> (except deprecated ones):))
comment: <> (comment: <> (`JSON))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "validTypes": [))
comment: <> (comment: <> ( "double",))
comment: <> (comment: <> ( "string",))
comment: <> (comment: <> ( "object",))
comment: <> (comment: <> ( "array",))
comment: <> (comment: <> ( "binData",))
comment: <> (comment: <> ( "objectId",))
comment: <> (comment: <> ( "bool",))
comment: <> (comment: <> ( "date",))
comment: <> (comment: <> ( "null",))
comment: <> (comment: <> ( "regex",))
comment: <> (comment: <> ( "javascript",))
comment: <> (comment: <> ( "int",))
comment: <> (comment: <> ( "timestamp",))
comment: <> (comment: <> ( "long",))
comment: <> (comment: <> ( "decimal",))
comment: <> (comment: <> ( "minKey",))
comment: <> (comment: <> ( "maxKey"))
comment: <> (comment: <> ( ]))
comment: <> (comment: <> (#### AND | OR filters))
comment: <> (comment: <> (Finally, it is possible to use filters with AND | OR operator. The usage logic follows the arithmetic rule.))
comment: <> (comment: <> (To use the AND operator, you must pass the same value twice in a query. Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?age=gt:30&age=lt:50))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`JSON))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "$and": [))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "age": {))
comment: <> (comment: <> ( "$gt": 30))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "age": {))
comment: <> (comment: <> ( "$lt": 50))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( ]))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (To use the OR operator, you must enter the values separated by a comma. Example:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?age=30,50))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`JSON))
comment: <> (comment: <> ( "filter": {))
comment: <> (comment: <> ( "$or": [))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "age": 30))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "age": 50))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( ]))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (### Populate))
comment: <> (comment: <> (If any collection uses references to other objects, in some operations it is interesting to return this information))
comment: <> (comment: <> (populated in the object in a single request. For this, the library supports the populate feature.))
comment: <> (comment: <> (There are three ways to add the populate parameter to the query string:))
comment: <> (comment: <> (- Specifying only the field to be populated:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?populate=jobs))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "populate": {))
comment: <> (comment: <> ( "path": "jobs"))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (- Specifying the field to be populated and which fields should be returned:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?populate=jobs;title,salary))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "populate": {))
comment: <> (comment: <> ( "path": "jobs",))
comment: <> (comment: <> ( "select": {))
comment: <> (comment: <> ( "title": 1,))
comment: <> (comment: <> ( "salary": 1))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (- Specifying the field to be populated, which fields should be returned and a resource filter (useful parameter when the))
comment: <> (comment: <> ( populated field is a list):))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?populate=jobs;title,salary;salary=gt:3000))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "populate": {))
comment: <> (comment: <> ( "path": "job",))
comment: <> (comment: <> ( "select": {))
comment: <> (comment: <> ( "title": 1,))
comment: <> (comment: <> ( "salary": 1))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( "match": {))
comment: <> (comment: <> ( "salary": {))
comment: <> (comment: <> ( "$gt": 3000))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( }))
comment: <> (comment: <> (- Specifying more than one field to be populated:))
comment: <> (comment: <> (##### Request: http://localhost:3000/resources?populate=jobs&populate=currentJob))
comment: <> (comment: <> (##### Query:))
comment: <> (comment: <> (`json))
comment: <> (comment: <> ( "populate": [))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "path": "jobs"))
comment: <> (comment: <> ( },))
comment: <> (comment: <> ( {))
comment: <> (comment: <> ( "path": "currentJob"))
comment: <> (comment: <> ( }))
comment: <> (comment: <> ( ]))
comment: <> (comment: <> (There are some rules to consider in populate. The populate must be specified as follows:))
comment: <> (comment: <> (populate=field;select;filter. Soon:))
comment: <> (comment: <> (1. If you specify only the field to be populated, all field parameters will be returned, and if it is an array, all))
comment: <> (comment: <> ( array elements will be returned;))
comment: <> (comment: <> (2. If you want to specify which parameters are to be returned from the populated field, you need to specify which fields))
comment: <> (comment: <> ( are to be returned;))
comment: <> (comment: <> (3. If you want to filter the populated parameters, you need to specify the parameters that should be returned. If you))
comment: <> (comment: <> ( want to return all object parameters, the select parameter must be informed as all.))
comment: <> (comment: <> ( Example: populate=jobs;all;salary=gt:3000))
Usage
More details about usage as soon as possible.
Rules
- For pagination, you should use
limit,skipandpageonly; - For ordination, you should use
sortonly; - Parameters never contain characters that don't fit the regex
/[^A-z0-9_.]/g; - Filter values never contain characters that don't fit the regex
/[^\w\s@.-:]/g;
comment: <> (- For select, you should use select only;)
comment: <> (- For populate, you should use populateonly;)
comment: <> (- Anything other than limit, skip, page, sort, select and populate will be considered a filter;)
Observations
This library is generic. This means that it handles the query based on the query object itself. Therefore, it is not possible to control events such as filter parameters with types incompatible with the types defined in the base. Use proper queries for your API, to prevent implementation errors from being thrown into your app.
Practical Examples
Check out how the configuration of the library in an API works in practice in this project.
License
Distributed under the Apache License 2.0. See LICENSE for more information.
Authors
- Lucas Rocha - Initial Work.
