A utility library for building dynamic queries with Mongoose, featuring enhanced capabilities such as dynamic searching, exclusion of fields, and additional filtering.
Install using npm:
npm i mongoose-dynamic-querybuilder
Or using Yarn:
yarn add mongoose-dynamic-querybuilder
Here's how you can use the QueryBuilder
with a Mongoose model:
import QueryBuilder from "mongoose-dynamic-querybuilder";
// Initialize QueryBuilder with a Mongoose query and request query parameters
const getAllBooks = async (req: any) => {
const booksQuery = new QueryBuilder(Book.find({}), req.query)
await booksQuery
.filter()
.extraFilter({ isDeleted: { $ne: true } })
.search(['name.en', 'name.hi', 'name.local'])
.sort()
.paginate()
.fields()
.exclude('soldCount')
.applyExclusions()
const [books, totalBooks, filters] = await Promise.all([
booksQuery.modelQuery
.populate('categories', 'name name_en name_hi image description')
.populate('publisher', 'name profileImage')
.populate('author', 'name profileImage'),
booksQuery.countTotal(),
booksQuery.getFiltersList(
['categories', 'author', 'publisher', 'language'],
{
categories: Category,
author: User,
publisher: User,
language: null, // if string field make it null
}
),
])
filters.price = booksQuery.getFilters().price
}
-
new QueryBuilder(query, queryParams)
-
query
: A Mongoose query instance. -
queryParams
: An object containing query parameters.
-
-
.filter()
: Apply filters based onqueryParams
for fields not directly involved in searching or sorting. -
.search(fields)
: Perform a dynamic search on specified fields. -
.sort()
: Apply sorting based onqueryParams
. -
.paginate()
: Paginate the results according toqueryParams
. -
.fields()
: Select which fields to return in the query results. -
.exclude(fields)
: Specify fields to exclude from the results. -
.applyExclusions()
: Apply exclusions set by.exclude()
. -
.extraFilter(...filters)
: Apply additional custom filters. -
.modelQuery
: Get the final Mongoose query object. -
.countTotal()
: Count the total number of documents considering all applied filters, without pagination. -
.getFiltersList(fields, models)
: Retrieve distinct values for specified fields and additional related model information if provided. -
.getFilters()
: Get the accumulated filters for the query.
Here are a few example API calls:
-
Search by Term:
GET http://localhost:5000/api/v1/users?searchTerm=nahid
-
Pagination:
GET http://localhost:5000/api/v1/users?page=1&limit=10
-
Select Specific Fields:
GET http://localhost:5000/api/v1/users?fields=password,email
-
Sort in Descending Order:
GET http://localhost:5000/api/v1/users?sort=-username
- Added support for dynamic search on specific fields.
- Added support for selecting specific fields to be returned in the query.
- Added support for counting the total number of documents with all filters without pagination.
- Added support for search with ObjectId.
- Added support for search with boolean.
- Enhanced method for applying exclusions.
- Added support for retrieving distinct values for specified fields and related model information.
- Dynamic Search: Added support for dynamic search on specific fields including those containing ObjectId values and booleans.
- Field Selection and Exclusion: Enhanced functionality to select specific fields and exclude others in the query results.
-
Custom Filters: Added capability to apply additional custom filters with the new
.extraFilter()
method. - Accurate Document Counting: Improved counting method that reflects all applied filters without including paginated results.
- Enhanced Filters: Added support for retrieving distinct values for specified fields and related model information.