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 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
}

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.
• .getFiltersList(fields, models): Retrieve distinct values for specified fields and additional related model information if provided.
• .getFilters(): Get the accumulated filters for the query.

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.
• Enhanced method for applying exclusions.
• Added support for retrieving distinct values for specified fields and related model information.

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.
• Enhanced Filters: Added support for retrieving distinct values for specified fields and related model information.