@hsa-technologies-00/hsa-query-builder

A powerful and flexible MongoDB query builder for Mongoose, designed to simplify the creation of complex queries. This package supports advanced filtering, searching, pagination, sorting, and more, with full TypeScript support.

Features

Dynamic Query Building: Easily build MongoDB queries using a simple and intuitive API.
Advanced Filtering: Supports MongoDB operators like $gt, $lt, $in, $regex, and more.
Dot Notation Support: Filter nested objects using dot notation (e.g., customer.address.city).
Search Functionality: Perform case-insensitive searches across multiple fields.
Pagination & Sorting: Built-in support for pagination, limiting, selecting fields, and sorting.
TypeScript Support: Fully typed for better developer experience and type safety.

Installation

Install the package using npm:

npm install @hsa-technologies-00/hsa-query-builder

Or using yarn:

yarn add @hsa-technologies-00/hsa-query-builder

Usage

Basic Example

import { MongoQuery } from '@hsa-technologies-00/hsa-query-builder';

const queryParams = {
  search: 'John',
  age_gt: 25,
  'customer.address.city': 'New York',
  page: 2,
  limit: 20,
  select: 'name,age',
  sort: 'age,-name',
};

const filter = new MongoQuery(queryParams, {
  searchFields: ['name', 'email'],
}).build();

const query = filter.getFilterQuery();
const options = filter.getQueryOptions();

console.log('Filter Query:', query);
console.log('Query Options:', options);

Output

Filter Query: {
  $or: [
    { name: { $regex: 'John', $options: 'i' } },
    { email: { $regex: 'John', $options: 'i' } }
  ],
  age: { $gt: 25 },
  customer: { address: { city: 'New York' } }
}

Query Options: {
  page: 2,
  limit: 20,
  select: 'name age',
  sort: 'age -name'
}

API Documentation

`MongoQuery`

Constructor

new MongoQuery(queryParams: QueryParams, options?: MongoQueryOptions)

queryParams: An object containing query parameters (e.g., search, age_gt, page, limit, etc.).
options: Optional configuration object with the following properties:
- searchFields: An array of fields to search (e.g., ["name", "email"]).

Methods

build(): Builds the filter query and query options.
getFilterQuery(): Returns the MongoDB filter query.
getQueryOptions(): Returns the query options (e.g., page, limit, select, sort).

Supported Operators

The following MongoDB operators are supported:

Operator	MongoDB Equivalent	Example Usage
`or`	`$or`	`{ age_or: [20, 25] }`
`gt`	`$gt`	`{ age_gt: 25 }`
`gte`	`$gte`	`{ age_gte: 25 }`
`lt`	`$lt`	`{ age_lt: 30 }`
`lte`	`$lte`	`{ age_lte: 30 }`
`in`	`$in`	`{ age_in: [20, 25] }`
`nin`	`$nin`	`{ age_nin: [20, 25]}`
`ne`	`$ne`	`{ age_ne: 25 }`
`equals`	`$eq`	`{ age_equals: 25 }`
`regex`	`$regex`	`{ name_regex: "John"}`
`elemMatch`	`$elemMatch`	`{ tags_elemMatch: { $in: ["tech"] } }`
`all`	`$all`	`{ tags_all: ["tech", "mongodb"] }`

Dot Notation Support

You can filter nested objects using dot notation. For example:

const queryParams = {
  'customer.address.city': 'New York',
};

This will generate the following MongoDB query:

{
  customer: {
    address: {
      city: 'New York';
    }
  }
}

Search Functionality

To perform a case-insensitive search across multiple fields, use the search parameter and specify the searchFields option:

const queryParams = {
  search: 'John',
};

const filter = new MongoQuery(queryParams, {
  searchFields: ['name', 'email'],
}).build();

This will generate the following MongoDB query:

{
  $or: [{ name: { $regex: 'John', $options: 'i' } }, { email: { $regex: 'John', $options: 'i' } }];
}

Pagination & Sorting

The following query parameters are supported for pagination and sorting:

page: The page number (default: 1).
limit: The number of items per page (default: 10).
select: Fields to include or exclude (e.g., name,age).
sort: Sorting criteria (e.g., age,-name for ascending by age and descending by name).

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository.
Create a new branch (git checkout -b feature/YourFeature).
Commit your changes (git commit -m 'Add some feature').
Push to the branch (git push origin feature/YourFeature).
Open a pull request.

License

This project is licensed under the MIT License.

Author

Md Harun Or Rashid
- Email: harun.ru.cse@gmail.com
- Website: https://harun-dev.vercel.app

Support

If you find this package useful, please consider giving it a ⭐️ on GitHub.

Enjoy building MongoDB queries with ease! 🚀