/**
 * Aggregation Functions for TONL Query API
 *
 * Provides aggregation capabilities like count, sum, avg, min, max, groupBy
 * for use with query results.
 *
 * @example
 * ```typescript
 * const users = doc.query("users[*]");
 * const result = aggregate(users)
 *   .count()                    // 42
 *   .sum("age")                 // 1250
 *   .avg("age")                 // 29.76
 *   .groupBy("country")         // { TR: [...], US: [...] }
 * ```
 */
/**
 * Statistical result from aggregation operations
 */
export interface StatisticsResult {
    /** Number of values */
    count: number;
    /** Sum of all values */
    sum: number;
    /** Average value (mean) */
    avg: number;
    /** Minimum value, or undefined if empty */
    min: number | undefined;
    /** Maximum value, or undefined if empty */
    max: number | undefined;
    /** Variance of the dataset */
    variance: number;
    /** Standard deviation */
    stdDev: number;
}
/**
 * Options for aggregation operations
 */
export interface AggregationOptions {
    /**
     * Whether to ignore null/undefined values in calculations
     * @default true
     */
    ignoreNull?: boolean;
    /**
     * Whether to treat non-numeric values as 0 in numeric aggregations
     * @default false
     */
    coerceNumbers?: boolean;
    /**
     * Custom comparator for min/max operations
     */
    comparator?: (a: any, b: any) => number;
}
/**
 * Result wrapper for aggregation operations
 * Provides a fluent interface for chaining aggregations
 */
export declare class AggregationResult<T> {
    private items;
    private options;
    constructor(items: T[], options?: AggregationOptions);
    /**
     * Get the underlying items array
     */
    toArray(): T[];
    /**
     * Count the number of items
     *
     * @example
     * ```typescript
     * aggregate(users).count()  // 42
     * ```
     */
    count(): number;
    /**
     * Sum numeric values
     *
     * @param field - Optional field name for object arrays
     * @returns Sum of values
     *
     * @example
     * ```typescript
     * aggregate([1, 2, 3]).sum()           // 6
     * aggregate(orders).sum("total")       // 1500.50
     * ```
     */
    sum(field?: string): number;
    /**
     * Calculate average of numeric values
     *
     * @param field - Optional field name for object arrays
     * @returns Average value or NaN if empty
     *
     * @example
     * ```typescript
     * aggregate([1, 2, 3]).avg()           // 2
     * aggregate(products).avg("price")     // 29.99
     * ```
     */
    avg(field?: string): number;
    /**
     * Find minimum value
     *
     * @param field - Optional field name for object arrays
     * @returns Minimum value or undefined if empty
     *
     * @example
     * ```typescript
     * aggregate([3, 1, 2]).min()           // 1
     * aggregate(products).min("price")     // 9.99
     * ```
     */
    min(field?: string): T | number | undefined;
    /**
     * Find maximum value
     *
     * @param field - Optional field name for object arrays
     * @returns Maximum value or undefined if empty
     *
     * @example
     * ```typescript
     * aggregate([1, 3, 2]).max()           // 3
     * aggregate(products).max("price")     // 99.99
     * ```
     */
    max(field?: string): T | number | undefined;
    /**
     * Group items by a field value
     *
     * @param field - Field name to group by
     * @returns Object with group keys and arrays of items
     *
     * @example
     * ```typescript
     * aggregate(users).groupBy("country")
     * // { "TR": [user1, user2], "US": [user3] }
     *
     * aggregate(orders).groupBy("status")
     * // { "pending": [...], "completed": [...] }
     * ```
     */
    groupBy<K extends string>(field: K): Record<string, T[]>;
    /**
     * Get distinct values
     *
     * @param field - Optional field name for object arrays
     * @returns Array of unique values
     *
     * @example
     * ```typescript
     * aggregate([1, 2, 2, 3, 3, 3]).distinct()  // [1, 2, 3]
     * aggregate(users).distinct("country")      // ["TR", "US", "DE"]
     * ```
     */
    distinct(field?: string): unknown[];
    /**
     * Get first item
     *
     * @returns First item or undefined
     */
    first(): T | undefined;
    /**
     * Get last item
     *
     * @returns Last item or undefined
     */
    last(): T | undefined;
    /**
     * Get item at specific index
     *
     * @param index - Array index (supports negative for end-relative)
     * @returns Item at index or undefined
     */
    at(index: number): T | undefined;
    /**
     * Take first N items
     *
     * @param n - Number of items to take
     * @returns New AggregationResult with first N items
     */
    take(n: number): AggregationResult<T>;
    /**
     * Skip first N items
     *
     * @param n - Number of items to skip
     * @returns New AggregationResult without first N items
     */
    skip(n: number): AggregationResult<T>;
    /**
     * Sort items
     *
     * @param field - Field name to sort by
     * @param order - Sort order ('asc' or 'desc')
     * @returns New sorted AggregationResult
     *
     * @example
     * ```typescript
     * aggregate(users).orderBy("age")            // ascending
     * aggregate(users).orderBy("age", "desc")    // descending
     * ```
     */
    orderBy(field: string, order?: 'asc' | 'desc'): AggregationResult<T>;
    /**
     * Filter items
     *
     * @param predicate - Filter function
     * @returns New filtered AggregationResult
     */
    filter(predicate: (item: T, index: number) => boolean): AggregationResult<T>;
    /**
     * Map items to new values
     *
     * @param mapper - Transform function
     * @returns New AggregationResult with mapped items
     */
    map<U>(mapper: (item: T, index: number) => U): AggregationResult<U>;
    /**
     * Reduce items to single value
     *
     * @param reducer - Reducer function
     * @param initial - Initial value
     * @returns Reduced value
     */
    reduce<U>(reducer: (acc: U, item: T, index: number) => U, initial: U): U;
    /**
     * Check if any item matches predicate
     *
     * @param predicate - Test function
     * @returns True if any item matches
     */
    some(predicate: (item: T) => boolean): boolean;
    /**
     * Check if all items match predicate
     *
     * @param predicate - Test function
     * @returns True if all items match
     */
    every(predicate: (item: T) => boolean): boolean;
    /**
     * Calculate statistics for numeric field
     *
     * @param field - Optional field name
     * @returns Statistics object with count, sum, avg, min, max, variance, stdDev
     */
    stats(field?: string): StatisticsResult;
    /**
     * Partition items into groups based on predicate
     *
     * @param predicate - Test function
     * @returns Tuple of [matching, nonMatching] arrays
     */
    partition(predicate: (item: T) => boolean): [T[], T[]];
    /**
     * Flatten nested arrays
     *
     * @param depth - Maximum depth to flatten (default: 1)
     * @returns Flattened AggregationResult
     */
    flatten(depth?: number): AggregationResult<unknown>;
    /**
     * Get frequency count for values
     *
     * @param field - Optional field name
     * @returns Object with values and their counts
     */
    frequency(field?: string): Record<string, number>;
    /**
     * Calculate percentile value
     *
     * @param percentile - Percentile (0-100)
     * @param field - Optional field name
     * @returns Percentile value
     */
    percentile(percentile: number, field?: string): number | undefined;
    /**
     * Calculate median value
     *
     * @param field - Optional field name
     * @returns Median value
     */
    median(field?: string): number | undefined;
    /**
     * Extract a field value from an item
     *
     * SECURITY: Validates property names to prevent prototype pollution
     *
     * @throws {SecurityError} If field contains dangerous property names
     */
    private getFieldValue;
    /**
     * Extract values from items (with optional field)
     */
    private extractValues;
    /**
     * Extract numeric values from items
     */
    private extractNumericValues;
}
/**
 * Create an aggregation wrapper for query results
 *
 * @param items - Array of items to aggregate
 * @param options - Aggregation options
 * @returns AggregationResult instance
 *
 * @example
 * ```typescript
 * const users = doc.query("users[*]");
 *
 * // Count
 * aggregate(users).count()  // 42
 *
 * // Sum a field
 * aggregate(orders).sum("total")  // 15420.50
 *
 * // Average
 * aggregate(products).avg("price")  // 29.99
 *
 * // Group by
 * aggregate(users).groupBy("country")
 * // { "TR": [...], "US": [...] }
 *
 * // Chained operations
 * aggregate(users)
 *   .filter(u => u.active)
 *   .orderBy("age", "desc")
 *   .take(10)
 *   .toArray()
 * ```
 */
export declare function aggregate<T>(items: T[], options?: AggregationOptions): AggregationResult<T>;
/**
 * Shorthand aggregation functions for quick operations
 */
export declare const agg: {
    /**
     * Count items in array
     */
    count: <T>(items: T[]) => number;
    /**
     * Sum numeric values
     */
    sum: <T>(items: T[], field?: string) => number;
    /**
     * Calculate average
     */
    avg: <T>(items: T[], field?: string) => number;
    /**
     * Find minimum
     */
    min: <T>(items: T[], field?: string) => T | number | undefined;
    /**
     * Find maximum
     */
    max: <T>(items: T[], field?: string) => T | number | undefined;
    /**
     * Group by field
     */
    groupBy: <T, K extends string>(items: T[], field: K) => Record<string, T[]>;
    /**
     * Get distinct values
     */
    distinct: <T>(items: T[], field?: string) => unknown[];
    /**
     * Calculate statistics
     */
    stats: <T>(items: T[], field?: string) => StatisticsResult;
    /**
     * Get frequency distribution
     */
    frequency: <T>(items: T[], field?: string) => Record<string, number>;
    /**
     * Calculate median
     */
    median: <T>(items: T[], field?: string) => number | undefined;
    /**
     * Calculate percentile
     */
    percentile: <T>(items: T[], p: number, field?: string) => number | undefined;
};
//# sourceMappingURL=aggregators.d.ts.map