filter-kit 2.0.0

package/README.md

@@ -0,0 +1,294 @@
+# mongoose-filter-kit
+
+[![npm version](https://img.shields.io/npm/v/mongoose-filter-kit.svg)](https://www.npmjs.com/package/mongoose-filter-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+
+A production-ready Mongoose query builder for REST APIs and admin panels. One function call builds a full MongoDB query with regex search, pagination, sorting, date-range filters, populate, field selection, and dynamic filters — all driven by URL query parameters.
+
+## Install
+
+```bash
+npm install mongoose-filter-kit
+```
+
+Mongoose 6.x or higher is required as a peer dependency:
+
+```bash
+npm install mongoose
+```
+
+## JavaScript Usage
+
+**CommonJS (Node.js `require`)**
+
+```javascript
+const { queryBuilder } = require('mongoose-filter-kit');
+const User = require('./models/User');
+
+app.get('/users', async (req, res) => {
+  const result = await queryBuilder({
+    model: User,
+    query: req.query,
+    searchFields: ['name', 'email'],
+    allowedFilters: ['role', 'status'],
+    customFilter: { isDeleted: false },
+  });
+  res.json(result);
+});
+```
+
+**ESM (`import`)**
+
+```javascript
+import { queryBuilder } from 'mongoose-filter-kit';
+import User from './models/User.js';
+
+app.get('/users', async (req, res) => {
+  const result = await queryBuilder({
+    model: User,
+    query: req.query,
+    searchFields: ['name', 'email'],
+    allowedFilters: ['role', 'status'],
+    customFilter: { isDeleted: false },
+  });
+  res.json(result);
+});
+```
+
+## Quick Start (TypeScript)
+
+```typescript
+import { queryBuilder } from 'mongoose-filter-kit';
+import User from './models/User';
+
+// Express handler
+app.get('/users', async (req, res) => {
+  const result = await queryBuilder({
+    model: User,
+    query: req.query,
+    searchFields: ['name', 'email'],
+    allowedFilters: ['role', 'status'],
+    defaultSort: 'createdAt',
+    defaultOrder: 'desc',
+    defaultLimit: 10,
+    maxLimit: 100,
+    populate: 'role',
+    dateField: 'createdAt',
+    customFilter: { isDeleted: false },
+  });
+
+  res.json(result);
+});
+```
+
+Sample response:
+
+```json
+{
+  "data": [
+    { "_id": "...", "name": "John Doe", "email": "john@example.com", "role": "admin" }
+  ],
+  "pagination": {
+    "total": 42,
+    "page": 1,
+    "limit": 10,
+    "pages": 5,
+    "hasNext": true,
+    "hasPrev": false
+  }
+}
+```
+
+## Options Reference
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `model` | `Model<T>` | **required** | The Mongoose model to query against. |
+| `query` | `Record<string, any>` | **required** | Parsed query string object (e.g. `req.query`). |
+| `searchFields` | `string[]` | `undefined` | Fields to regex-search when `?search=` is provided. |
+| `allowedFilters` | `string[]` | `undefined` | Extra query keys allowed as dynamic filters (in addition to schema paths). |
+| `defaultSort` | `string` | `'createdAt'` | Default sort field when `?sort=` is absent. |
+| `defaultOrder` | `'asc' \| 'desc'` | `'desc'` | Default sort direction when `?order=` is absent. |
+| `defaultLimit` | `number` | `10` | Default page size when `?limit=` is absent. |
+| `maxLimit` | `number` | `100` | Hard ceiling on page size — prevents abuse. |
+| `populate` | `string \| string[] \| PopulateOptions \| PopulateOptions[]` | `undefined` | Populate option used when `?populate=` is absent. |
+| `select` | `ProjectionType<T> \| string` | `undefined` | Field projection used when `?select=` is absent. |
+| `dateField` | `string` | `undefined` | Date field targeted by `?from=` / `?to=` filters. |
+| `lean` | `boolean` | `false` | Return plain JS objects instead of Mongoose documents. |
+| `customFilter` | `Record<string, any>` | `undefined` | Extra conditions always merged into the query via `$and`. |
+
+## Query Parameters Reference
+
+| Param | Type | Example | Description |
+|---|---|---|---|
+| `search` | `string` | `?search=john` | Case-insensitive regex search across all `searchFields`. Special regex chars are escaped automatically. |
+| `page` | `number` | `?page=2` | Page number (1-based, min 1). |
+| `limit` | `number` | `?limit=25` | Documents per page (clamped to `maxLimit`). |
+| `sort` | `string` | `?sort=name` | Field to sort by. |
+| `order` | `'asc' \| 'desc'` | `?order=asc` | Sort direction. |
+| `from` | `ISO 8601 date` | `?from=2024-01-01` | Start of date range on `dateField` (`$gte`). Invalid dates are silently ignored. |
+| `to` | `ISO 8601 date` | `?to=2024-12-31` | End of date range on `dateField` (`$lte`, adjusted to 23:59:59.999). Invalid dates are silently ignored. |
+| `populate` | `string` | `?populate=role,department` | Comma-separated paths to populate. Overrides the `populate` option. |
+| `select` | `string` | `?select=name,email` | Comma-separated fields to include. Overrides the `select` option. |
+| `<field>` | `string` | `?status=active` | Dynamic filter — passed through only if the key is in `allowedFilters` or exists as a schema path. Comma-separated values become `{ $in: [...] }`. The strings `'true'` / `'false'` are coerced to booleans. |
+
+## Examples
+
+### With Express
+
+```typescript
+import express from 'express';
+import mongoose from 'mongoose';
+import { queryBuilder } from 'mongoose-filter-kit';
+import Product from './models/Product';
+
+const app = express();
+
+app.get('/products', async (req, res, next) => {
+  try {
+    const result = await queryBuilder({
+      model: Product,
+      query: req.query,
+      searchFields: ['name', 'description', 'sku'],
+      allowedFilters: ['category', 'brand', 'inStock'],
+      defaultSort: 'createdAt',
+      defaultOrder: 'desc',
+      defaultLimit: 20,
+      maxLimit: 200,
+      dateField: 'createdAt',
+      populate: [{ path: 'category', select: 'name slug' }],
+      customFilter: { isActive: true },
+      lean: true,
+    });
+
+    res.json(result);
+  } catch (err) {
+    next(err);
+  }
+});
+```
+
+### With NestJS
+
+```typescript
+import { Controller, Get, Query } from '@nestjs/common';
+import { InjectModel } from '@nestjs/mongoose';
+import { Model } from 'mongoose';
+import { queryBuilder, QueryBuilderResult } from 'mongoose-filter-kit';
+import { User, UserDocument } from './user.schema';
+
+@Controller('users')
+export class UsersController {
+  constructor(
+    @InjectModel(User.name) private readonly userModel: Model<UserDocument>,
+  ) {}
+
+  @Get()
+  async findAll(@Query() query: Record<string, any>): Promise<QueryBuilderResult<UserDocument>> {
+    return queryBuilder({
+      model: this.userModel,
+      query,
+      searchFields: ['name', 'email'],
+      allowedFilters: ['role', 'status', 'department'],
+      defaultSort: 'createdAt',
+      defaultOrder: 'desc',
+      defaultLimit: 10,
+      maxLimit: 100,
+      populate: 'role',
+      dateField: 'createdAt',
+      customFilter: { isDeleted: false },
+    });
+  }
+}
+```
+
+### With Custom Filters and Populate Options
+
+```typescript
+const result = await queryBuilder({
+  model: Order,
+  query: req.query,
+  searchFields: ['orderNumber', 'customerName'],
+  allowedFilters: ['status', 'paymentMethod'],
+  defaultSort: 'placedAt',
+  defaultOrder: 'desc',
+  defaultLimit: 15,
+  maxLimit: 50,
+  dateField: 'placedAt',
+  populate: [
+    { path: 'customer', select: 'name email phone' },
+    { path: 'items.product', select: 'name sku price' },
+  ],
+  select: '-__v -internalNotes',
+  customFilter: { archived: false },
+  lean: true,
+});
+```
+
+### Combining Date Ranges and Boolean Filters
+
+```bash
+GET /orders?from=2024-01-01&to=2024-03-31&status=pending,processing&isPaid=false&page=1&limit=25
+```
+
+```typescript
+const result = await queryBuilder({
+  model: Order,
+  query: req.query,          // { from, to, status, isPaid, page, limit }
+  allowedFilters: ['isPaid'],
+  dateField: 'placedAt',
+  // status is also allowed because it exists on the schema
+});
+// Produces: { $and: [
+//   { placedAt: { $gte: ..., $lte: ... } },
+//   { status: { $in: ['pending', 'processing'] }, isPaid: false }
+// ]}
+```
+
+## How Dynamic Filters Work
+
+Dynamic filters let clients filter by any model field directly via the URL — but with a security gate to prevent arbitrary injection:
+
+1. **Reserved params are never treated as field filters** — `page`, `limit`, `sort`, `order`, `search`, `from`, `to`, `populate`, and `select` are always consumed by their dedicated handlers.
+
+2. **A field key is accepted only when:**
+   - It appears in your `allowedFilters` array, **or**
+   - It exists as a path in `model.schema.paths`.
+
+   Unknown keys with no schema definition are silently dropped.
+
+3. **Value coercions applied automatically:**
+   - `?status=active,inactive` → `{ status: { $in: ['active', 'inactive'] } }`
+   - `?isVerified=true` → `{ isVerified: true }` (boolean)
+   - `?isVerified=false` → `{ isVerified: false }` (boolean)
+   - Everything else is passed through as-is.
+
+4. **`customFilter` is always applied** — it cannot be overridden by query parameters. Use it for tenant isolation, soft-delete guards, or any condition that must always be present.
+
+## TypeScript Support
+
+Full types ship with the package — no `@types/` install needed. All types are exported:
+
+```typescript
+import {
+  queryBuilder,
+  QueryBuilderOptions,
+  QueryBuilderResult,
+  PaginationMeta,
+} from 'mongoose-filter-kit';
+```
+
+The main function is generic — pass your document type for full type inference:
+
+```typescript
+const result = await queryBuilder<UserDocument>({
+  model: User,
+  query: req.query,
+});
+// result.data is UserDocument[]
+```
+
+## License
+
+MIT

package/dist/cjs/filters/buildDateFilter.d.ts

@@ -0,0 +1,11 @@
+import { FilterQuery } from 'mongoose';
+/**
+ * Builds a MongoDB date-range filter for the specified field.
+ *
+ * - `from` maps to `$gte` (start of that day, as-is from the ISO string).
+ * - `to`   maps to `$lte` (end of that day — time set to 23:59:59.999).
+ * - Invalid date strings are silently ignored.
+ * - Returns `{}` when no dateField is provided or both dates are invalid.
+ */
+export declare function buildDateFilter(from: string | undefined, to: string | undefined, dateField: string | undefined): FilterQuery<any>;
+//# sourceMappingURL=buildDateFilter.d.ts.map

package/dist/cjs/filters/buildDateFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDateFilter.d.ts","sourceRoot":"","sources":["../../../src/filters/buildDateFilter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAWvC;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,WAAW,CAAC,GAAG,CAAC,CAqBlB"}

package/dist/cjs/filters/buildDateFilter.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDateFilter = buildDateFilter;
+/**
+ * Determines whether a given value produces a valid Date object.
+ */
+function isValidDate(value) {
+    if (!value || value.trim() === '')
+        return false;
+    const d = new Date(value);
+    return !isNaN(d.getTime());
+}
+/**
+ * Builds a MongoDB date-range filter for the specified field.
+ *
+ * - `from` maps to `$gte` (start of that day, as-is from the ISO string).
+ * - `to`   maps to `$lte` (end of that day — time set to 23:59:59.999).
+ * - Invalid date strings are silently ignored.
+ * - Returns `{}` when no dateField is provided or both dates are invalid.
+ */
+function buildDateFilter(from, to, dateField) {
+    if (!dateField)
+        return {};
+    const conditions = {};
+    if (from && isValidDate(from)) {
+        conditions['$gte'] = new Date(from);
+    }
+    if (to && isValidDate(to)) {
+        const toDate = new Date(to);
+        // Set to end of day so the entire `to` day is included
+        toDate.setHours(23, 59, 59, 999);
+        conditions['$lte'] = toDate;
+    }
+    if (Object.keys(conditions).length === 0) {
+        return {};
+    }
+    return { [dateField]: conditions };
+}
+//# sourceMappingURL=buildDateFilter.js.map

package/dist/cjs/filters/buildDateFilter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDateFilter.js","sourceRoot":"","sources":["../../../src/filters/buildDateFilter.ts"],"names":[],"mappings":";;AAmBA,0CAyBC;AA1CD;;GAEG;AACH,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAChD,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,eAAe,CAC7B,IAAwB,EACxB,EAAsB,EACtB,SAA6B;IAE7B,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,CAAC;IAE1B,MAAM,UAAU,GAAyB,EAAE,CAAC;IAE5C,IAAI,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5B,uDAAuD;QACvD,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACjC,UAAU,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAC9B,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC;AACrC,CAAC"}

package/dist/cjs/filters/buildDynamicFilters.d.ts

@@ -0,0 +1,3 @@
+import { FilterQuery, Model } from 'mongoose';
+export declare function buildDynamicFilters(query: Record<string, any>, allowedFilters: string[] | undefined, model: Model<any>): FilterQuery<any>;
+//# sourceMappingURL=buildDynamicFilters.d.ts.map

package/dist/cjs/filters/buildDynamicFilters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDynamicFilters.d.ts","sourceRoot":"","sources":["../../../src/filters/buildDynamicFilters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAiE9C,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,cAAc,EAAE,MAAM,EAAE,GAAG,SAAS,EACpC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,GAChB,WAAW,CAAC,GAAG,CAAC,CAyClB"}

package/dist/cjs/filters/buildDynamicFilters.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDynamicFilters = buildDynamicFilters;
+const RESERVED_PARAMS = new Set([
+    'page', 'limit', 'sort', 'order', 'search', 'from', 'to', 'populate', 'select',
+]);
+const OPERATOR_SUFFIXES = [
+    ['_exists', '$exists'],
+    ['_regex', '$regex'],
+    ['_nin', '$nin'],
+    ['_gte', '$gte'],
+    ['_lte', '$lte'],
+    ['_ne', '$ne'],
+    ['_in', '$in'],
+    ['_gt', '$gt'],
+    ['_lt', '$lt'],
+];
+function parseOperatorKey(key) {
+    for (const [suffix, op] of OPERATOR_SUFFIXES) {
+        if (key.endsWith(suffix) && key.length > suffix.length) {
+            return { field: key.slice(0, -suffix.length), op };
+        }
+    }
+    return null;
+}
+function coerceScalar(raw) {
+    const str = String(raw);
+    if (str === 'true')
+        return true;
+    if (str === 'false')
+        return false;
+    const n = Number(str);
+    return isNaN(n) ? str : n;
+}
+function coerceForOperator(raw, op) {
+    const str = String(raw);
+    switch (op) {
+        case '$gte':
+        case '$lte':
+        case '$gt':
+        case '$lt': {
+            const n = Number(str);
+            return isNaN(n) ? str : n;
+        }
+        case '$ne':
+            return coerceScalar(raw);
+        case '$in':
+        case '$nin':
+            return str.split(',').map((v) => coerceScalar(v.trim()));
+        case '$exists':
+            return str !== 'false';
+        case '$regex': {
+            try {
+                return new RegExp(str, 'i');
+            }
+            catch (_a) {
+                return null;
+            }
+        }
+        default:
+            return coerceScalar(raw);
+    }
+}
+function buildDynamicFilters(query, allowedFilters, model) {
+    const filter = {};
+    const allowed = new Set(allowedFilters !== null && allowedFilters !== void 0 ? allowedFilters : []);
+    const schemaPaths = model.schema.paths;
+    for (const key of Object.keys(query)) {
+        if (RESERVED_PARAMS.has(key))
+            continue;
+        const raw = query[key];
+        if (raw === undefined || raw === null || raw === '')
+            continue;
+        const parsed = parseOperatorKey(key);
+        if (parsed) {
+            const { field, op } = parsed;
+            const fieldAllowed = allowed.has(field) || field in schemaPaths;
+            if (!fieldAllowed)
+                continue;
+            const coerced = coerceForOperator(raw, op);
+            if (coerced === null)
+                continue;
+            if (typeof filter[field] !== 'object' || Array.isArray(filter[field])) {
+                filter[field] = {};
+            }
+            filter[field][op] = coerced;
+        }
+        else {
+            const keyAllowed = allowed.has(key) || key in schemaPaths;
+            if (!keyAllowed)
+                continue;
+            const value = String(raw);
+            if (value === 'true') {
+                filter[key] = true;
+                continue;
+            }
+            if (value === 'false') {
+                filter[key] = false;
+                continue;
+            }
+            if (value.includes(',')) {
+                filter[key] = { $in: value.split(',').map((v) => v.trim()) };
+                continue;
+            }
+            filter[key] = raw;
+        }
+    }
+    return filter;
+}
+//# sourceMappingURL=buildDynamicFilters.js.map

package/dist/cjs/filters/buildDynamicFilters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDynamicFilters.js","sourceRoot":"","sources":["../../../src/filters/buildDynamicFilters.ts"],"names":[],"mappings":"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"}

package/dist/cjs/filters/buildPagination.d.ts

@@ -0,0 +1,15 @@
+export interface PaginationParams {
+    page: number;
+    limit: number;
+    skip: number;
+}
+/**
+ * Parses and validates pagination query parameters.
+ *
+ * Rules:
+ * - `page` is clamped to a minimum of 1.
+ * - `limit` is clamped between 1 and `maxLimit` (inclusive).
+ * - Non-numeric or missing values fall back to the provided defaults.
+ */
+export declare function buildPagination(queryPage: string | undefined, queryLimit: string | undefined, defaultLimit: number, maxLimit: number): PaginationParams;
+//# sourceMappingURL=buildPagination.d.ts.map

package/dist/cjs/filters/buildPagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPagination.d.ts","sourceRoot":"","sources":["../../../src/filters/buildPagination.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,gBAAgB,CAgBlB"}

package/dist/cjs/filters/buildPagination.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPagination = buildPagination;
+/**
+ * Parses and validates pagination query parameters.
+ *
+ * Rules:
+ * - `page` is clamped to a minimum of 1.
+ * - `limit` is clamped between 1 and `maxLimit` (inclusive).
+ * - Non-numeric or missing values fall back to the provided defaults.
+ */
+function buildPagination(queryPage, queryLimit, defaultLimit, maxLimit) {
+    let page = parseInt(queryPage, 10);
+    let limit = parseInt(queryLimit, 10);
+    // Fall back to defaults for non-numeric inputs
+    if (isNaN(page))
+        page = 1;
+    if (isNaN(limit))
+        limit = defaultLimit;
+    // Enforce bounds
+    if (page < 1)
+        page = 1;
+    if (limit < 1)
+        limit = 1;
+    if (limit > maxLimit)
+        limit = maxLimit;
+    const skip = (page - 1) * limit;
+    return { page, limit, skip };
+}
+//# sourceMappingURL=buildPagination.js.map

package/dist/cjs/filters/buildPagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPagination.js","sourceRoot":"","sources":["../../../src/filters/buildPagination.ts"],"names":[],"mappings":";;AAcA,0CAqBC;AA7BD;;;;;;;GAOG;AACH,SAAgB,eAAe,CAC7B,SAA6B,EAC7B,UAA8B,EAC9B,YAAoB,EACpB,QAAgB;IAEhB,IAAI,IAAI,GAAG,QAAQ,CAAC,SAAmB,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,KAAK,GAAG,QAAQ,CAAC,UAAoB,EAAE,EAAE,CAAC,CAAC;IAE/C,+CAA+C;IAC/C,IAAI,KAAK,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,CAAC,CAAC;IAC1B,IAAI,KAAK,CAAC,KAAK,CAAC;QAAE,KAAK,GAAG,YAAY,CAAC;IAEvC,iBAAiB;IACjB,IAAI,IAAI,GAAG,CAAC;QAAE,IAAI,GAAG,CAAC,CAAC;IACvB,IAAI,KAAK,GAAG,CAAC;QAAE,KAAK,GAAG,CAAC,CAAC;IACzB,IAAI,KAAK,GAAG,QAAQ;QAAE,KAAK,GAAG,QAAQ,CAAC;IAEvC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;IAEhC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC/B,CAAC"}

package/dist/cjs/filters/buildPopulate.d.ts

@@ -0,0 +1,3 @@
+import { PopulateOptions } from 'mongoose';
+export declare function buildPopulate(queryPopulate: string | undefined, optionPopulate: string | string[] | PopulateOptions | PopulateOptions[] | undefined): PopulateOptions[];
+//# sourceMappingURL=buildPopulate.d.ts.map

package/dist/cjs/filters/buildPopulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPopulate.d.ts","sourceRoot":"","sources":["../../../src/filters/buildPopulate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAmB3C,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,eAAe,GAAG,eAAe,EAAE,GAAG,SAAS,GAClF,eAAe,EAAE,CA2BnB"}

package/dist/cjs/filters/buildPopulate.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPopulate = buildPopulate;
+function dotToPopulate(dotPath) {
+    const parts = dotPath
+        .trim()
+        .split('.')
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .slice(0, 4);
+    if (parts.length === 0)
+        throw new Error(`Invalid populate path: "${dotPath}"`);
+    let result = { path: parts[parts.length - 1] };
+    for (let i = parts.length - 2; i >= 0; i--) {
+        result = { path: parts[i], populate: result };
+    }
+    return result;
+}
+function buildPopulate(queryPopulate, optionPopulate) {
+    if (queryPopulate && queryPopulate.trim() !== '') {
+        return queryPopulate
+            .split(',')
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0)
+            .map(dotToPopulate);
+    }
+    if (optionPopulate === undefined || optionPopulate === null)
+        return [];
+    if (typeof optionPopulate === 'string') {
+        return optionPopulate.trim() === '' ? [] : [dotToPopulate(optionPopulate)];
+    }
+    if (Array.isArray(optionPopulate)) {
+        if (optionPopulate.length === 0)
+            return [];
+        if (typeof optionPopulate[0] === 'string') {
+            return optionPopulate
+                .map((p) => p.trim())
+                .filter((p) => p.length > 0)
+                .map(dotToPopulate);
+        }
+        return optionPopulate;
+    }
+    return [optionPopulate];
+}
+//# sourceMappingURL=buildPopulate.js.map

package/dist/cjs/filters/buildPopulate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPopulate.js","sourceRoot":"","sources":["../../../src/filters/buildPopulate.ts"],"names":[],"mappings":";;AAmBA,sCA8BC;AA/CD,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,KAAK,GAAG,OAAO;SAClB,IAAI,EAAE;SACN,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SAC3B,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEf,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,GAAG,CAAC,CAAC;IAE/E,IAAI,MAAM,GAAoB,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;IAChE,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,aAAa,CAC3B,aAAiC,EACjC,cAAmF;IAEnF,IAAI,aAAa,IAAI,aAAa,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,OAAO,aAAa;aACjB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;aACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;aAC3B,GAAG,CAAC,aAAa,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAEvE,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,cAAc,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAC3C,IAAI,OAAO,cAAc,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAQ,cAA2B;iBAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;iBACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;iBAC3B,GAAG,CAAC,aAAa,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,cAAmC,CAAC;IAC7C,CAAC;IAED,OAAO,CAAC,cAAiC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/cjs/filters/buildSearch.d.ts

@@ -0,0 +1,4 @@
+import { FilterQuery } from 'mongoose';
+import { SearchField } from '../types';
+export declare function buildSearch(search: string | undefined, searchFields: SearchField[] | undefined, searchMode?: 'or' | 'and'): FilterQuery<any>;
+//# sourceMappingURL=buildSearch.d.ts.map

package/dist/cjs/filters/buildSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildSearch.d.ts","sourceRoot":"","sources":["../../../src/filters/buildSearch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAgCvC,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,YAAY,EAAE,WAAW,EAAE,GAAG,SAAS,EACvC,UAAU,GAAE,IAAI,GAAG,KAAY,GAC9B,WAAW,CAAC,GAAG,CAAC,CA8BlB"}

package/dist/cjs/filters/buildSearch.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSearch = buildSearch;
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildFieldCondition(field, type, term) {
+    if (type === 'number') {
+        const num = Number(term);
+        if (isNaN(num))
+            return null;
+        return { [field]: { $eq: num } };
+    }
+    if (type === 'exact') {
+        return { [field]: term };
+    }
+    return { [field]: { $regex: new RegExp(escapeRegex(term), 'i') } };
+}
+function normaliseFields(searchFields) {
+    return searchFields.map((f) => {
+        var _a;
+        return typeof f === 'string'
+            ? { field: f, type: 'string' }
+            : { field: f.field, type: (_a = f.type) !== null && _a !== void 0 ? _a : 'string' };
+    });
+}
+function buildSearch(search, searchFields, searchMode = 'or') {
+    if (!search || !searchFields || searchFields.length === 0)
+        return {};
+    const trimmed = search.trim();
+    if (trimmed.length === 0)
+        return {};
+    const fields = normaliseFields(searchFields);
+    if (searchMode === 'and') {
+        const terms = trimmed.split(/\s+/).filter((t) => t.length > 0);
+        const andClauses = [];
+        for (const term of terms) {
+            const orConds = fields
+                .map((f) => buildFieldCondition(f.field, f.type, term))
+                .filter((c) => c !== null);
+            if (orConds.length > 0)
+                andClauses.push({ $or: orConds });
+        }
+        if (andClauses.length === 0)
+            return {};
+        if (andClauses.length === 1)
+            return andClauses[0];
+        return { $and: andClauses };
+    }
+    const orConds = fields
+        .map((f) => buildFieldCondition(f.field, f.type, trimmed))
+        .filter((c) => c !== null);
+    if (orConds.length === 0)
+        return {};
+    return { $or: orConds };
+}
+//# sourceMappingURL=buildSearch.js.map