@classytic/mongokit 3.1.4 → 3.1.6

package/README.md

@@ -14,7 +14,7 @@
 - **Event-driven** - Pre/post hooks for all operations
 - **12 built-in plugins** - Caching, soft delete, validation, audit logs, and more
 - **TypeScript first** - Full type safety with discriminated unions
-- **194 passing tests** - Battle-tested and production-ready
+- **410+ passing tests** - Battle-tested and production-ready
 
 ## Installation
 
@@ -476,6 +476,16 @@ GET /users?sort=-createdAt,name
 
 # Search (requires text index)
 GET /users?search=john
+
+# Simple populate
+GET /posts?populate=author,category
+
+# Advanced populate with options
+GET /posts?populate[author][select]=name,email
+GET /posts?populate[author][match][active]=true
+GET /posts?populate[comments][limit]=10
+GET /posts?populate[comments][sort]=-createdAt
+GET /posts?populate[author][populate][department][select]=name  # Nested
 ```
 
 **Security features:**
@@ -483,6 +493,54 @@ GET /users?search=john
 - ReDoS protection for regex patterns
 - Max filter depth enforcement
 - Collection allowlists for lookups
+- Populate path sanitization (blocks `$where`, `__proto__`, etc.)
+- Max populate depth limit (default: 5)
+
+### Advanced Populate Options
+
+QueryParser supports Mongoose populate options via URL query parameters:
+
+```typescript
+import { QueryParser } from '@classytic/mongokit';
+
+const parser = new QueryParser();
+
+// Parse URL: /posts?populate[author][select]=name,email&populate[author][match][active]=true
+const parsed = parser.parse(req.query);
+
+// Use with Repository
+const posts = await postRepo.getAll(
+  { filters: parsed.filters, page: parsed.page, limit: parsed.limit },
+  { populateOptions: parsed.populateOptions }
+);
+```
+
+**Supported populate options:**
+
+| Option | URL Syntax | Description |
+|--------|------------|-------------|
+| `select` | `populate[path][select]=field1,field2` | Fields to include (space-separated in Mongoose) |
+| `match` | `populate[path][match][field]=value` | Filter populated documents |
+| `limit` | `populate[path][limit]=10` | Limit number of populated docs |
+| `sort` | `populate[path][sort]=-createdAt` | Sort populated documents |
+| `populate` | `populate[path][populate][nested][select]=field` | Nested populate (max depth: 5) |
+
+**Example - Complex populate:**
+
+```typescript
+// URL: /posts?populate[author][select]=name,avatar&populate[comments][limit]=5&populate[comments][sort]=-createdAt&populate[comments][match][approved]=true
+
+const parsed = parser.parse(req.query);
+// parsed.populateOptions = [
+//   { path: 'author', select: 'name avatar' },
+//   { path: 'comments', match: { approved: true }, options: { limit: 5, sort: { createdAt: -1 } } }
+// ]
+
+// Simple string populate still works
+// URL: /posts?populate=author,category
+// parsed.populate = 'author,category'
+// parsed.populateOptions = undefined
+```
 
 ### JSON Schema Generation
 

package/dist/index.d.ts

@@ -777,6 +777,7 @@ declare class Repository<TDoc = AnyDocument> {
     getById(id: string | ObjectId, options?: {
         select?: SelectSpec;
         populate?: PopulateSpec;
+        populateOptions?: PopulateOptions[];
         lean?: boolean;
         session?: ClientSession;
         throwOnNotFound?: boolean;
@@ -789,6 +790,7 @@ declare class Repository<TDoc = AnyDocument> {
     getByQuery(query: Record<string, unknown>, options?: {
         select?: SelectSpec;
         populate?: PopulateSpec;
+        populateOptions?: PopulateOptions[];
         lean?: boolean;
         session?: ClientSession;
         throwOnNotFound?: boolean;
@@ -830,9 +832,12 @@ declare class Repository<TDoc = AnyDocument> {
         };
         limit?: number;
         search?: string;
+        /** Advanced populate options (from QueryParser or Arc's BaseController) */
+        populateOptions?: PopulateOptions[];
     }, options?: {
         select?: SelectSpec;
         populate?: PopulateSpec;
+        populateOptions?: PopulateOptions[];
         lean?: boolean;
         session?: ClientSession;
         skipCache?: boolean;
@@ -1069,14 +1074,46 @@ declare class Repository<TDoc = AnyDocument> {
 
 type SortSpec = Record<string, 1 | -1>;
 type FilterQuery = Record<string, unknown>;
+/**
+ * Mongoose-compatible populate option
+ * Supports advanced populate with select, match, limit, sort, and nested populate
+ *
+ * @example
+ * ```typescript
+ * // URL: ?populate[author][select]=name,email&populate[author][match][active]=true
+ * // Generates: { path: 'author', select: 'name email', match: { active: true } }
+ * ```
+ */
+interface PopulateOption {
+    /** Field path to populate */
+    path: string;
+    /** Fields to select (space-separated) */
+    select?: string;
+    /** Filter conditions for populated documents */
+    match?: Record<string, unknown>;
+    /** Query options (limit, sort, skip) */
+    options?: {
+        limit?: number;
+        sort?: SortSpec;
+        skip?: number;
+    };
+    /** Nested populate configuration */
+    populate?: PopulateOption;
+}
 /** Parsed query result with optional lookup configuration */
 interface ParsedQuery {
     /** MongoDB filter query */
     filters: FilterQuery;
     /** Sort specification */
     sort?: SortSpec;
-    /** Fields to populate (ObjectId-based) */
+    /** Fields to populate (simple comma-separated string) */
     populate?: string;
+    /**
+     * Advanced populate options (Mongoose-compatible)
+     * When this is set, `populate` will be undefined
+     * @example [{ path: 'author', select: 'name email' }]
+     */
+    populateOptions?: PopulateOption[];
     /** Page number for offset pagination */
     page?: number;
     /** Cursor for keyset pagination */
@@ -1092,6 +1129,8 @@ interface ParsedQuery {
     /** Select/project fields */
     select?: Record<string, 0 | 1>;
 }
+/** Search mode for query parser */
+type SearchMode = 'text' | 'regex';
 interface QueryParserOptions {
     /** Maximum allowed regex pattern length (default: 500) */
     maxRegexLength?: number;
@@ -1107,6 +1146,18 @@ interface QueryParserOptions {
     enableLookups?: boolean;
     /** Enable aggregation parsing (default: false - requires explicit opt-in) */
     enableAggregations?: boolean;
+    /**
+     * Search mode (default: 'text')
+     * - 'text': Uses MongoDB $text search (requires text index)
+     * - 'regex': Uses $or with $regex across searchFields (no index required)
+     */
+    searchMode?: SearchMode;
+    /**
+     * Fields to search when searchMode is 'regex'
+     * Required when searchMode is 'regex'
+     * @example ['name', 'description', 'sku', 'tags']
+     */
+    searchFields?: string[];
 }
 /**
  * Modern Query Parser
@@ -1187,6 +1238,27 @@ declare class QueryParser {
      * ```
      */
     private _parseSelect;
+    /**
+     * Parse populate parameter - handles both simple string and advanced object format
+     *
+     * @example
+     * ```typescript
+     * // Simple: ?populate=author,category
+     * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+     *
+     * // Advanced: ?populate[author][select]=name,email
+     * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+     * ```
+     */
+    private _parsePopulate;
+    /**
+     * Parse a single populate configuration
+     */
+    private _parseSinglePopulate;
+    /**
+     * Convert populate match values (handles boolean strings, etc.)
+     */
+    private _convertPopulateMatch;
     /**
      * Parse filter parameters
      */
@@ -1209,6 +1281,20 @@ declare class QueryParser {
      */
     private _sanitizeMatchConfig;
     private _sanitizeSearch;
+    /**
+     * Build regex-based multi-field search filters
+     * Creates an $or query with case-insensitive regex across all searchFields
+     *
+     * @example
+     * // searchFields: ['name', 'description', 'sku']
+     * // search: 'azure'
+     * // Returns: [
+     * //   { name: { $regex: /azure/i } },
+     * //   { description: { $regex: /azure/i } },
+     * //   { sku: { $regex: /azure/i } }
+     * // ]
+     */
+    private _buildRegexSearch;
     private _convertValue;
     private _parseOr;
     private _enhanceWithBetween;
@@ -1228,4 +1314,4 @@ declare class QueryParser {
  */
 declare function createRepository<TDoc>(Model: mongoose.Model<TDoc, any, any, any>, plugins?: PluginType[], paginationConfig?: PaginationConfig, options?: RepositoryOptions): Repository<TDoc>;
 
-export { AggregatePaginationResult, AggregationBuilder, AnyDocument, type FilterQuery, HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, KeysetPaginationResult, LookupBuilder, LookupOptions, ObjectId, OffsetPaginationResult, PaginationConfig, PaginationEngine, PaginationResult, type ParsedQuery, PluginType, PopulateSpec, QueryParser, type QueryParserOptions, Repository, RepositoryContext, RepositoryOptions, SelectSpec, SortSpec$2 as SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };
+export { AggregatePaginationResult, AggregationBuilder, AnyDocument, type FilterQuery, HttpError, type IController, type IControllerResponse, type IRequestContext, type IResponseFormatter, KeysetPaginationResult, LookupBuilder, LookupOptions, ObjectId, OffsetPaginationResult, PaginationConfig, PaginationEngine, PaginationResult, type ParsedQuery, PluginType, type PopulateOption, PopulateSpec, QueryParser, type QueryParserOptions, Repository, RepositoryContext, RepositoryOptions, type SearchMode, SelectSpec, SortSpec$2 as SortSpec, UpdateOptions, WithTransactionOptions, createRepository, Repository as default };

package/dist/index.js

@@ -756,7 +756,8 @@ var Repository = class {
    * Get document by ID
    */
   async getById(id, options = {}) {
-    const context = await this._buildContext("getById", { id, ...options });
+    const populateSpec = options.populateOptions || options.populate;
+    const context = await this._buildContext("getById", { id, ...options, populate: populateSpec });
     if (context._cacheHit) {
       return context._cachedResult;
     }
@@ -768,7 +769,8 @@ var Repository = class {
    * Get single document by query
    */
   async getByQuery(query, options = {}) {
-    const context = await this._buildContext("getByQuery", { query, ...options });
+    const populateSpec = options.populateOptions || options.populate;
+    const context = await this._buildContext("getByQuery", { query, ...options, populate: populateSpec });
     if (context._cacheHit) {
       return context._cachedResult;
     }
@@ -815,11 +817,12 @@ var Repository = class {
     const limit = params.limit || params.pagination?.limit || this._pagination.config.defaultLimit;
     let query = { ...filters };
     if (search) query.$text = { $search: search };
+    const populateSpec = options.populateOptions || params.populateOptions || context.populate || options.populate;
     const paginationOptions = {
       filters: query,
       sort: this._parseSort(sort),
       limit,
-      populate: this._parsePopulate(context.populate || options.populate),
+      populate: this._parsePopulate(populateSpec),
       select: context.select || options.select,
       lean: context.lean ?? options.lean ?? true,
       session: options.session
@@ -1194,8 +1197,14 @@ var QueryParser = class {
       maxLimit: options.maxLimit ?? 1e3,
       additionalDangerousOperators: options.additionalDangerousOperators ?? [],
       enableLookups: options.enableLookups ?? true,
-      enableAggregations: options.enableAggregations ?? false
+      enableAggregations: options.enableAggregations ?? false,
+      searchMode: options.searchMode ?? "text",
+      searchFields: options.searchFields
     };
+    if (this.options.searchMode === "regex" && (!this.options.searchFields || this.options.searchFields.length === 0)) {
+      console.warn('[mongokit] searchMode "regex" requires searchFields to be specified. Falling back to "text" mode.');
+      this.options.searchMode = "text";
+    }
     this.dangerousOperators = [
       "$where",
       "$function",
@@ -1236,13 +1245,34 @@ var QueryParser = class {
       console.warn(`[mongokit] Limit ${parsedLimit} exceeds maximum ${this.options.maxLimit}, capping to max`);
       parsedLimit = this.options.maxLimit;
     }
+    const sanitizedSearch = this._sanitizeSearch(search);
+    const { simplePopulate, populateOptions } = this._parsePopulate(populate);
     const parsed = {
       filters: this._parseFilters(filters),
       limit: parsedLimit,
       sort: this._parseSort(sort),
-      populate,
-      search: this._sanitizeSearch(search)
+      populate: simplePopulate,
+      populateOptions,
+      search: sanitizedSearch
     };
+    if (sanitizedSearch && this.options.searchMode === "regex" && this.options.searchFields) {
+      const regexSearchFilters = this._buildRegexSearch(sanitizedSearch);
+      if (regexSearchFilters) {
+        if (parsed.filters.$or) {
+          parsed.filters = {
+            ...parsed.filters,
+            $and: [
+              { $or: parsed.filters.$or },
+              { $or: regexSearchFilters }
+            ]
+          };
+          delete parsed.filters.$or;
+        } else {
+          parsed.filters.$or = regexSearchFilters;
+        }
+        parsed.search = void 0;
+      }
+    }
     if (select) {
       parsed.select = this._parseSelect(select);
     }
@@ -1261,7 +1291,16 @@ var QueryParser = class {
     }
     const orGroup = this._parseOr(query);
     if (orGroup) {
-      parsed.filters = { ...parsed.filters, $or: orGroup };
+      if (parsed.filters.$or) {
+        const existingOr = parsed.filters.$or;
+        delete parsed.filters.$or;
+        parsed.filters.$and = [
+          { $or: existingOr },
+          { $or: orGroup }
+        ];
+      } else {
+        parsed.filters.$or = orGroup;
+      }
     }
     parsed.filters = this._enhanceWithBetween(parsed.filters);
     return parsed;
@@ -1411,6 +1450,117 @@ var QueryParser = class {
     return void 0;
   }
   // ============================================================
+  // POPULATE PARSING
+  // ============================================================
+  /**
+   * Parse populate parameter - handles both simple string and advanced object format
+   *
+   * @example
+   * ```typescript
+   * // Simple: ?populate=author,category
+   * // Returns: { simplePopulate: 'author,category', populateOptions: undefined }
+   *
+   * // Advanced: ?populate[author][select]=name,email
+   * // Returns: { simplePopulate: undefined, populateOptions: [{ path: 'author', select: 'name email' }] }
+   * ```
+   */
+  _parsePopulate(populate) {
+    if (!populate) {
+      return {};
+    }
+    if (typeof populate === "string") {
+      return { simplePopulate: populate };
+    }
+    if (typeof populate === "object" && populate !== null) {
+      const populateObj = populate;
+      if (Object.keys(populateObj).length === 0) {
+        return {};
+      }
+      const populateOptions = [];
+      for (const [path, config] of Object.entries(populateObj)) {
+        if (path.startsWith("$") || this.dangerousOperators.includes(path)) {
+          console.warn(`[mongokit] Blocked dangerous populate path: ${path}`);
+          continue;
+        }
+        const option = this._parseSinglePopulate(path, config);
+        if (option) {
+          populateOptions.push(option);
+        }
+      }
+      return populateOptions.length > 0 ? { populateOptions } : {};
+    }
+    return {};
+  }
+  /**
+   * Parse a single populate configuration
+   */
+  _parseSinglePopulate(path, config, depth = 0) {
+    if (depth > 5) {
+      console.warn(`[mongokit] Populate depth exceeds maximum (5), truncating at path: ${path}`);
+      return { path };
+    }
+    if (typeof config === "string") {
+      if (config === "true" || config === "1") {
+        return { path };
+      }
+      return { path, select: config.split(",").join(" ") };
+    }
+    if (typeof config === "object" && config !== null) {
+      const opts = config;
+      const option = { path };
+      if (opts.select && typeof opts.select === "string") {
+        option.select = opts.select.split(",").map((s) => s.trim()).join(" ");
+      }
+      if (opts.match && typeof opts.match === "object") {
+        option.match = this._convertPopulateMatch(opts.match);
+      }
+      if (opts.limit !== void 0) {
+        const limit = parseInt(String(opts.limit), 10);
+        if (!isNaN(limit) && limit > 0) {
+          option.options = option.options || {};
+          option.options.limit = limit;
+        }
+      }
+      if (opts.sort && typeof opts.sort === "string") {
+        const sortSpec = this._parseSort(opts.sort);
+        if (sortSpec) {
+          option.options = option.options || {};
+          option.options.sort = sortSpec;
+        }
+      }
+      if (opts.skip !== void 0) {
+        const skip = parseInt(String(opts.skip), 10);
+        if (!isNaN(skip) && skip >= 0) {
+          option.options = option.options || {};
+          option.options.skip = skip;
+        }
+      }
+      if (opts.populate && typeof opts.populate === "object") {
+        const nestedPopulate = opts.populate;
+        const nestedEntries = Object.entries(nestedPopulate);
+        if (nestedEntries.length > 0) {
+          const [nestedPath, nestedConfig] = nestedEntries[0];
+          const nestedOption = this._parseSinglePopulate(nestedPath, nestedConfig, depth + 1);
+          if (nestedOption) {
+            option.populate = nestedOption;
+          }
+        }
+      }
+      return option;
+    }
+    return null;
+  }
+  /**
+   * Convert populate match values (handles boolean strings, etc.)
+   */
+  _convertPopulateMatch(match) {
+    const converted = {};
+    for (const [key, value] of Object.entries(match)) {
+      converted[key] = this._convertValue(value);
+    }
+    return converted;
+  }
+  // ============================================================
   // FILTER PARSING (Enhanced from original)
   // ============================================================
   /**
@@ -1428,7 +1578,7 @@ var QueryParser = class {
         console.warn(`[mongokit] Blocked dangerous operator: ${key}`);
         continue;
       }
-      if (["page", "limit", "sort", "populate", "search", "select", "lean", "includeDeleted", "lookup", "aggregate"].includes(key)) {
+      if (["page", "limit", "sort", "populate", "search", "select", "lean", "includeDeleted", "lookup", "aggregate", "or", "OR", "$or"].includes(key)) {
         continue;
       }
       const operatorMatch = key.match(/^(.+)\[(.+)\]$/);
@@ -1618,6 +1768,35 @@ var QueryParser = class {
     }
     return searchStr;
   }
+  /**
+   * Build regex-based multi-field search filters
+   * Creates an $or query with case-insensitive regex across all searchFields
+   *
+   * @example
+   * // searchFields: ['name', 'description', 'sku']
+   * // search: 'azure'
+   * // Returns: [
+   * //   { name: { $regex: /azure/i } },
+   * //   { description: { $regex: /azure/i } },
+   * //   { sku: { $regex: /azure/i } }
+   * // ]
+   */
+  _buildRegexSearch(searchTerm) {
+    if (!this.options.searchFields || this.options.searchFields.length === 0) {
+      return null;
+    }
+    const safeRegex = this._createSafeRegex(searchTerm, "i");
+    if (!safeRegex) {
+      return null;
+    }
+    const orConditions = [];
+    for (const field of this.options.searchFields) {
+      orConditions.push({
+        [field]: { $regex: safeRegex }
+      });
+    }
+    return orConditions.length > 0 ? orConditions : null;
+  }
   _convertValue(value) {
     if (value === null || value === void 0) return value;
     if (Array.isArray(value)) return value.map((v) => this._convertValue(v));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "description": "Production-grade MongoDB repositories with zero dependencies - smart pagination, events, and plugins",
   "type": "module",
   "sideEffects": false,