A flexible query parser that transforms URL query parameters into MongoDB queries. It supports filtering, sorting, pagination, field population, and complex logical operations.

## Basic Usage

The parser converts URL query parameters into a MongoDB-compatible query object with the following structure:

```typescript
{
  filters: Record<string, any>;   // MongoDB query conditions
  populate: any[];               // Population configurations
  sort: Record<string, 1 | -1>; // Sort configurations
  skip: number;                 // Number of documents to skip
  limit: number;                // Maximum number of documents to return
}
```

## Filter Operators

The parser supports the following filter operators:

| Operator | Description                    | MongoDB Equivalent | Example                          |
| -------- | ------------------------------ | ------------------ | -------------------------------- |
| eq       | Equals                         | $eq                | `name[eq]=John`                  |
| ne       | Not equals                     | $ne                | `age[ne]=25`                     |
| gt       | Greater than                   | $gt                | `age[gt]=18`                     |
| gte      | Greater than or equals         | $gte               | `age[gte]=18`                    |
| lt       | Less than                      | $lt                | `price[lt]=100`                  |
| lte      | Less than or equals            | $lte               | `price[lte]=100`                 |
| starts   | Starts with (case insensitive) | $regex             | `email[starts]=john`             |
| ends     | Ends with (case insensitive)   | $regex             | `email[ends]=gmail.com`          |
| cont     | Contains (case insensitive)    | $regex             | `name[cont]=oh`                  |
| excl     | Excludes (case insensitive)    | $not               | `name[excl]=test`                |
| in       | In array                       | $in                | `status[in]=active,pending`      |
| notin    | Not in array                   | $nin               | `status[notin]=deleted,archived` |
| isnull   | Field is null/undefined        | $exists: false     | `deletedAt[isnull]=true`         |
| notnull  | Field is not null/undefined    | $exists: true      | `email[notnull]=true`            |
| between  | Value is between (inclusive)   | $gte, $lte         | `age[between]=18,25`             |

### Examples

```
# Find users aged 18 or older
/users?age[gte]=18

# Find users with gmail addresses
/users?email[ends]=gmail.com

# Find users with specific statuses
/users?status[in]=active,pending

# Find users aged between 18 and 25
/users?age[between]=18,25
```

## Logical Operators

You can combine multiple conditions on the same field using logical operators (AND/OR).

### Syntax
Add `_op=and` or `_op=or` to specify the logical operator for a field's conditions.

- Default behavior (without _op) is OR
- Use `fieldname_op=and` for AND operations
- Use `fieldname_op=or` for OR operations (explicit)

### Examples

```
# Emails that start with 'john' AND end with 'gmail.com'
/users?email[starts]=john&email[ends]=gmail.com

# Emails that start with 'john' OR end with 'gmail.com'
/users?email[starts]=john&email[ends]=gmail.com&email_op=or

# Mix AND/OR operations on different fields
/users?email[starts]=john&email[ends]=gmail.com&email_op=and&status[in]=active,pending&status_op=or
```

## Sorting

Sort results by one or more fields.

### Syntax
- Use `sort=field` for ascending order
- Use `sort=-field` for descending order
- Combine multiple fields with commas

### Examples

```
# Sort by name ascending
/users?sort=name

# Sort by created date descending
/users?sort=-createdAt

# Sort by status ascending, then created date descending
/users?sort=status,-createdAt
```

## Pagination

Control the number of results and their offset.

### Parameters
- `skip`: Number of documents to skip
- `limit`: Maximum number of documents to return

### Examples

```
# Get the first 10 results
/users?limit=10

# Get 10 results, starting from the 20th document
/users?skip=20&limit=10
```

## Population

Populate references to other collections with various options for controlling the populated data.

### Basic Population

```
# Populate a single reference
/users?populate=posts

# Populate multiple references
/users?populate=posts,comments

# Populate nested references
/users?populate=posts.author,posts.comments
```

### Advanced Population Options

#### Select Specific Fields
Choose which fields to include in populated documents:
```
/users?populate.posts.select=title,content,author
```

#### Filter Populated Documents
Apply filters to populated documents:
```
/users?populate.posts.status[eq]=published
```

#### Sort Populated Documents
Sort populated documents:
```
/users?populate.posts.sort=-createdAt
```

#### Combine Population Options
```
/users?populate.posts.select=title,content&populate.posts.status[eq]=published&populate.posts.sort=-createdAt
```

## Complete Examples

Here are some complete examples combining multiple features:

### Example 1: Complex User Query
```
/users?
  name[starts]=john&
  email[ends]=gmail.com&
  email_op=and&
  age[between]=25,35&
  status[in]=active,premium&
  sort=-createdAt&
  limit=10&
  populate=posts,comments
```

This query will:
- Find users whose name starts with "john"
- AND whose email ends with "gmail.com"
- AND whose age is between 25 and 35
- AND whose status is either active or premium
- Sort results by creation date (newest first)
- Limit to 10 results
- Populate posts and comments

### Example 2: Advanced Post Query with Population
```
/posts?
  title[cont]=javascript&
  status[eq]=published&
  tags[in]=tutorial,nodejs&
  populate.author.select=name,email&
  populate.comments.status[eq]=approved&
  populate.comments.sort=-createdAt&
  sort=-views,title&
  skip=20&
  limit=10
```

This query will:
- Find posts containing "javascript" in the title
- That are published
- Tagged with either "tutorial" or "nodejs"
- Populate author (only name and email)
- Populate approved comments (sorted by creation date)
- Sort results by views (descending) and title (ascending)
- Skip first 20 results
- Limit to 10 results