mongoose-dynamic-querybuilder

mongoose-dynamic-querybuilder

A utility library for building dynamic queries with Mongoose, featuring enhanced capabilities such as dynamic searching, exclusion of fields, and additional filtering.

Installation

Install using npm:

npm i mongoose-dynamic-querybuilder

Or using Yarn:

yarn add mongoose-dynamic-querybuilder

Usage

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 userQuery = new QueryBuilder(User.find({}), req.query);

const [data, totalData] = await Promise.all([
  userQuery
    .filter()
    .extraFilter({ role: { $ne: "admin" } })
    .search(["email", "username", "profile.fullname"])
    .sort()
    .paginate()
    .fields()
    .exclude("password")
    .applyExclusions().modelQuery,
  userQuery.countTotal(),
]);

API

Constructor

• new QueryBuilder(query, queryParams)
  • query: A Mongoose query instance.
  • queryParams: An object containing query parameters.

Methods

• .filter(): Apply filters based on queryParams for fields not directly involved in searching or sorting.
• .search(fields): Perform a dynamic search on specified fields.
• .sort(): Apply sorting based on queryParams.
• .paginate(): Paginate the results according to queryParams.
• .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.

Examples

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
  

Changelog

• 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

What's New?

• 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.