jsm-utilities/dist/node/data/db/aggregation.utilities.v2.d.ts

A utilities library.

import { DateFilterOptions, FilterConfig, GeoFilter, NumberFilterOptions, StringFilterOptions } from "./query.utilities.v2";
export interface MatchStage {
    $match: Record<string, any>;
}
export interface AggregateFilterResult<T extends Record<string, any> = Record<string, any>> {
    pipeline: MatchStage[];
}
/**
 * Fluent aggregation filter builder for creating MongoDB $match pipeline stages with method chaining.
 *
 * This class provides a chainable interface for building aggregation pipeline $match stages.
 *
 * @template F - Field names type constraint (extends string)
 *
 * @example
 * ```typescript
 * const builder = createAggregateFilterBuilder<UserFields>()
 *   .string('name', 'john', { mode: 'contains' })
 *   .number('age', { min: 18, max: 65 })
 *   .boolean('isActive', true)
 *   .dateRange('createdAt', [startDate, endDate]);
 *
 * const { pipeline } = builder.build();
 * ```
 *
 * @since 2.0.0
 */
export declare class AggregateFilterBuilder<F extends string> {
    private pipeline;
    private tempMatch;
    separateMatches: boolean;
    constructor(separateMatches?: boolean);
    private addMatchStage;
    /**
     * Adds a string filter to the aggregation pipeline.
     */
    string(field: F | F[], value: any, options?: StringFilterOptions): this;
    /**
     * Adds a number filter to the aggregation pipeline.
     */
    number(field: F | F[], value: any, options?: NumberFilterOptions): this;
    /**
     * Adds a date range filter to the aggregation pipeline.
     */
    dateRange(field: F, value: any, options?: DateFilterOptions): this;
    /**
     * Adds a boolean filter to the aggregation pipeline.
     */
    boolean(field: F, value: any, omit?: boolean): this;
    /**
     * Adds an array filter to the aggregation pipeline.
     */
    array(field: F, value: any, options?: {
        omit?: boolean;
        matchAll?: boolean;
        size?: number;
    }): this;
    /**
     * Adds a geospatial filter to the aggregation pipeline.
     */
    geo(field: F, geoFilter: GeoFilter): this;
    /**
     * Adds a text search filter to the aggregation pipeline.
     */
    textSearch(searchText: string, options?: {
        language?: string;
        caseSensitive?: boolean;
        diacriticSensitive?: boolean;
    }): this;
    /**
     * Applies multiple filters using a configuration object.
     */
    configurable(filters: Record<string, any>, config: FilterConfig): this;
    /**
     * Applies a custom filter function for advanced filtering scenarios.
     */
    custom(filterFn: (pipeline: MatchStage[]) => AggregateFilterResult): this;
    /**
     * Builds and returns the final aggregation pipeline result.
     */
    build(): AggregateFilterResult['pipeline'];
    /**
     * Gets the current aggregation pipeline.
     */
    getPipeline(): MatchStage[];
    /**
     * Resets the builder to a new initial state with empty pipeline.
     */
    reset(): this;
    /**
     * Creates a clone of the current builder with the same state.
     */
    clone(): AggregateFilterBuilder<F>;
}
/**
 * Factory function to create a new AggregateFilterBuilder instance with fluent interface.
 *
 * @template F - Union type of allowed field names for type safety
 * @template T - Document type (typically a Mongoose Document)
 *
 * @returns A new AggregateFilterBuilder instance ready for method chaining
 *
 * @example
 * ```typescript
 * // Basic usage
 * const builder = createAggregateFilterBuilder<UserFields>()
 *   .string('name', 'john')
 *   .number('age', 25, { operator: 'gte' })
 *   .boolean('active', true);
 *
 * const { pipeline } = builder.build();
 *
 * // With typed field names
 * type UserFields = 'name' | 'email' | 'age' | 'active';
 * const typedBuilder = createAggregateFilterBuilder<UserFields>()
 *   .string('name', 'john') // ✅ Type-safe
 *   .number('invalidField', 123); // ❌ TypeScript error
 *
 * // Usage with Mongoose
 * const results = await Model.aggregate([
 *   ...pipeline,
 *   // Additional stages
 * ]);
 * ```
 */
export declare const createAggregateFilterBuilder: <F extends string = string>() => AggregateFilterBuilder<F>;