rust_queries_core/

lazy.rs

//! Lazy query implementation using iterators.
//!
//! This module provides lazy evaluation of queries, deferring execution
//! until results are actually consumed.

use key_paths_core::KeyPaths;
use std::marker::PhantomData;
use std::time::SystemTime;

#[cfg(feature = "datetime")]
use chrono::{DateTime, TimeZone};

/// A lazy query builder that uses iterators for deferred execution.
///
/// Unlike the standard `Query`, `LazyQuery` doesn't execute until you call
/// a terminal operation like `.collect()`, `.count()`, or `.first()`.
///
/// # Benefits
///
/// - **Deferred execution**: No work until results needed
/// - **Iterator fusion**: Rust optimizes chained operations
/// - **Early termination**: `.take()` stops as soon as enough items found
/// - **Composable**: Build complex queries by composition
/// - **Logical operators**: Support AND/OR filter composition
///
/// # Example
///
/// ```ignore
/// // Nothing executes yet
/// let query = LazyQuery::new(&products)
///     .where_(Product::price(), |&p| p < 100.0)
///     .where_(Product::stock(), |&s| s > 0);
///
/// // Execution happens here
/// let results: Vec<_> = query.collect();
/// 
/// // With AND/OR operators
/// let query = LazyQuery::new(&products)
///     .where_(Product::price(), |&p| p < 100.0)
///     .and(Product::stock(), |&s| s > 0)
///     .or(Product::category(), |c| c == "Premium");
/// ```
pub struct LazyQuery<'a, T: 'static, I>
where
    I: Iterator<Item = &'a T>,
{
    iter: I,
    filter_groups: Vec<FilterGroup<'a, T>>,
    _phantom: PhantomData<&'a T>,
}

/// Represents a group of filters with a logical operator
enum FilterGroup<'a, T: 'static> {
    And(Vec<Box<dyn Fn(&T) -> bool + 'a>>),
    Or(Vec<Box<dyn Fn(&T) -> bool + 'a>>),
}

impl<'a, T: 'static> FilterGroup<'a, T> {
    fn evaluate(&self, item: &T) -> bool {
        match self {
            FilterGroup::And(filters) => filters.iter().all(|f| f(item)),
            FilterGroup::Or(filters) => filters.iter().any(|f| f(item)),
        }
    }
}

impl<'a, T: 'static> LazyQuery<'a, T, std::slice::Iter<'a, T>> {
    /// Creates a new lazy query from a slice.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let query = LazyQuery::new(&products);
    /// ```
    pub fn new(data: &'a [T]) -> Self {
        Self {
            iter: data.iter(),
            filter_groups: Vec::new(),
            _phantom: PhantomData,
        }
    }
}

impl<'a, T: 'static, I> LazyQuery<'a, T, I>
where
    I: Iterator<Item = &'a T>,
{
    /// Creates a new lazy query from an iterator.
    ///
    /// This is useful for creating LazyQuery instances from custom iterators
    /// or for implementing extension traits.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let iter = vec![1, 2, 3].iter();
    /// let query = LazyQuery::from_iter(iter);
    /// ```
    pub fn from_iter(iter: I) -> Self {
        Self {
            iter,
            filter_groups: Vec::new(),
            _phantom: PhantomData,
        }
    }
    
    /// Applies all filter groups to the iterator
    /// 
    /// Filter groups are evaluated as follows:
    /// - AND groups: all filters in the group must pass
    /// - OR groups: at least one filter in the group must pass
    /// - Between groups: if there are both AND and OR groups, items must satisfy
    ///   either all AND groups OR at least one OR group (if OR groups exist)
    fn apply_filters(self) -> impl Iterator<Item = &'a T> + 'a
    where
        I: 'a,
    {
        let filter_groups = self.filter_groups;
        let (and_groups, or_groups): (Vec<_>, Vec<_>) = filter_groups
            .into_iter()
            .partition(|group| matches!(group, FilterGroup::And(_)));
        
        self.iter.filter(move |item| {
            match (and_groups.is_empty(), or_groups.is_empty()) {
                // Only AND groups: all must pass
                (false, true) => and_groups.iter().all(|group| group.evaluate(item)),
                // Only OR groups: at least one must pass
                (true, false) => or_groups.iter().any(|group| group.evaluate(item)),
                // Both AND and OR groups: (all AND pass) OR (any OR pass)
                (false, false) => {
                    let all_and_pass = and_groups.iter().all(|group| group.evaluate(item));
                    let any_or_pass = or_groups.iter().any(|group| group.evaluate(item));
                    all_and_pass || any_or_pass
                }
                // No filters: everything passes
                (true, true) => true,
            }
        })
    }
}

impl<'a, T: 'static, I> LazyQuery<'a, T, I>
where
    I: Iterator<Item = &'a T> + 'a,
{
    /// Adds a filter predicate (lazy - not executed yet).
    /// Multiple `where_` calls are implicitly ANDed together, unless the last group is an OR group,
    /// in which case `where_` adds to the OR group.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let query = LazyQuery::new(&products)
    ///     .where_(Product::price(), |&p| p < 100.0);
    /// ```
    pub fn where_<F, P>(mut self, path: KeyPaths<T, F>, predicate: P) -> Self
    where
        F: 'static,
        P: Fn(&F) -> bool + 'a,
    {
        let filter = Box::new(move |item: &T| {
                path.get(item).map_or(false, |val| predicate(val))
        });
        
        // If the last group is an OR group, add to it; otherwise create/add to AND group
        match self.filter_groups.last_mut() {
            Some(FilterGroup::Or(filters)) => {
                // Add to existing OR group
                filters.push(filter);
            }
            Some(FilterGroup::And(filters)) => {
                // Add to existing AND group
                filters.push(filter);
            }
            None => {
                // Create new AND group
                self.filter_groups.push(FilterGroup::And(vec![filter]));
            }
        }
        
        self
    }
    
    /// Adds a filter with AND logic (explicit AND operator).
    /// This is equivalent to `where_` but makes the AND relationship explicit.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let query = LazyQuery::new(&products)
    ///     .where_(Product::price(), |&p| p < 100.0)
    ///     .and(Product::stock(), |&s| s > 0);
    /// ```
    pub fn and<F, P>(mut self, path: KeyPaths<T, F>, predicate: P) -> Self
    where
        F: 'static,
        P: Fn(&F) -> bool + 'a,
    {
        let filter = Box::new(move |item: &T| {
            path.get(item).map_or(false, |val| predicate(val))
        });
        
        match self.filter_groups.last_mut() {
            Some(FilterGroup::And(filters)) => {
                filters.push(filter);
            }
            _ => {
                self.filter_groups.push(FilterGroup::And(vec![filter]));
            }
        }
        
        self
    }
    
    /// Adds a filter with OR logic (explicit OR operator).
    /// Items matching this filter OR any filters in the current OR group will pass.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let query = LazyQuery::new(&products)
    ///     .where_(Product::price(), |&p| p < 100.0)
    ///     .or(Product::category(), |c| c == "Premium");
    /// ```
    pub fn or<F, P>(mut self, path: KeyPaths<T, F>, predicate: P) -> Self
    where
        F: 'static,
        P: Fn(&F) -> bool + 'a,
    {
        let filter = Box::new(move |item: &T| {
            path.get(item).map_or(false, |val| predicate(val))
        });
        
        match self.filter_groups.last_mut() {
            Some(FilterGroup::Or(filters)) => {
                filters.push(filter);
            }
            _ => {
                self.filter_groups.push(FilterGroup::Or(vec![filter]));
            }
        }
        
        self
    }

    /// Maps each item through a transformation (lazy).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let prices = LazyQuery::new(&products)
    ///     .map_items(|p| p.price)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn map_items<F, O>(self, f: F) -> impl Iterator<Item = O> + 'a
    where
        F: Fn(&'a T) -> O + 'a,
        I: 'a,
    {
        self.apply_filters().map(f)
    }

    /// Selects/projects a field value (lazy).
    ///
    /// Returns iterator over cloned field values.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let names: Vec<String> = LazyQuery::new(&products)
    ///     .select_lazy(Product::name())
    ///     .collect();
    /// ```
    pub fn select_lazy<F>(self, path: KeyPaths<T, F>) -> impl Iterator<Item = F> + 'a
    where
        F: Clone + 'static,
        I: 'a,
    {
        self.apply_filters().filter_map(move |item| path.get(item).cloned())
    }

    /// Takes at most `n` items (lazy).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let first_10: Vec<_> = LazyQuery::new(&products)
    ///     .take_lazy(10)
    ///     .collect();
    /// ```
    pub fn take_lazy(self, n: usize) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        I: 'a,
    {
        LazyQuery {
            iter: self.iter.take(n),
            filter_groups: self.filter_groups,
            _phantom: PhantomData,
        }
    }

    /// Skips `n` items (lazy).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let page_2: Vec<_> = LazyQuery::new(&products)
    ///     .skip_lazy(10)
    ///     .take_lazy(10)
    ///     .collect();
    /// ```
    pub fn skip_lazy(self, n: usize) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        I: 'a,
    {
        LazyQuery {
            iter: self.iter.skip(n),
            filter_groups: self.filter_groups,
            _phantom: PhantomData,
        }
    }

    /// Collects all items into a vector (terminal operation - executes query).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let results: Vec<&Product> = query.collect();
    /// ```
    pub fn collect(self) -> Vec<&'a T>
    where
        I: 'a,
    {
        self.apply_filters().collect()
    }

    /// Gets the first item (terminal operation - executes until first match).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let first = query.first();
    /// ```
    pub fn first(self) -> Option<&'a T>
    where
        I: 'a,
    {
        self.apply_filters().next()
    }

    /// Counts items (terminal operation - executes query).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let count = query.count();
    /// ```
    pub fn count(self) -> usize
    where
        I: 'a,
    {
        self.apply_filters().count()
    }

    /// Checks if any items match (terminal operation - short-circuits).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let exists = query.any();
    /// ```
    pub fn any(self) -> bool
    where
        I: 'a,
    {
        self.apply_filters().next().is_some()
    }

    /// Executes a function for each item (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// query.for_each(|item| println!("{:?}", item));
    /// ```
    pub fn for_each<F>(self, f: F)
    where
        F: FnMut(&'a T),
    {
        self.apply_filters().for_each(f)
    }

    /// Folds the iterator (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let sum = query.fold(0.0, |acc, item| acc + item.price);
    /// ```
    pub fn fold<B, F>(self, init: B, f: F) -> B
    where
        F: FnMut(B, &'a T) -> B,
    {
        self.apply_filters().fold(init, f)
    }

    /// Finds an item matching a predicate (terminal - short-circuits).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let found = query.find(|item| item.id == 42);
    /// ```
    pub fn find<P>(self, predicate: P) -> Option<&'a T>
    where
        P: FnMut(&&'a T) -> bool,
        I: 'a,
    {
        self.apply_filters().find(predicate)
    }

    /// Checks if all items match a predicate (terminal - short-circuits).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let all_positive = query.all_match(|item| item.value > 0);
    /// ```
    pub fn all_match<P>(self, mut predicate: P) -> bool
    where
        P: FnMut(&'a T) -> bool,
        I: 'a,
    {
        self.apply_filters().all(move |item| predicate(item))
    }

    /// Collects all items into a vector (terminal operation - executes query).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let results: Vec<&Product> = query.all();
    /// ```
    pub fn all(self) -> Vec<&'a T>
    where
        I: 'a,
    {
        self.apply_filters().collect()
    }

    /// Converts to a standard iterator for further chaining.
    ///
    /// # Example
    ///
    /// ```ignore
    /// let custom: Vec<_> = query
    ///     .into_iter()
    ///     .map(|item| item.custom_transform())
    ///     .filter(|x| x.is_valid())
    ///     .collect();
    /// ```
    pub fn into_iter(self) -> I {
        self.iter
    }
}

// Aggregation operations
impl<'a, T: 'static, I> LazyQuery<'a, T, I>
where
    I: Iterator<Item = &'a T> + 'a,
{
    /// Computes sum of a field (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let total: f64 = LazyQuery::new(&products)
    ///     .sum_by(Product::price());
    /// ```
    pub fn sum_by<F>(self, path: KeyPaths<T, F>) -> F
    where
        F: Clone + std::ops::Add<Output = F> + Default + 'static,
        I: 'a,
    {
        self.apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .fold(F::default(), |acc, val| acc + val)
    }

    /// Computes average of a float field (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let avg = LazyQuery::new(&products)
    ///     .avg_by(Product::price());
    /// ```
    pub fn avg_by(self, path: KeyPaths<T, f64>) -> Option<f64>
    where
        I: 'a,
    {
        let items: Vec<f64> = self
            .apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .collect();

        if items.is_empty() {
            None
        } else {
            Some(items.iter().sum::<f64>() / items.len() as f64)
        }
    }

    /// Finds minimum value of a field (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let min = LazyQuery::new(&products)
    ///     .min_by(Product::price());
    /// ```
    pub fn min_by<F>(self, path: KeyPaths<T, F>) -> Option<F>
    where
        F: Ord + Clone + 'static,
        I: 'a,
    {
        self.apply_filters().filter_map(move |item| path.get(item).cloned()).min()
    }

    /// Finds maximum value of a field (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let max = LazyQuery::new(&products)
    ///     .max_by(Product::price());
    /// ```
    pub fn max_by<F>(self, path: KeyPaths<T, F>) -> Option<F>
    where
        F: Ord + Clone + 'static,
        I: 'a,
    {
        self.apply_filters().filter_map(move |item| path.get(item).cloned()).max()
    }

    /// Finds minimum float value (terminal operation).
    pub fn min_by_float(self, path: KeyPaths<T, f64>) -> Option<f64>
    where
        I: 'a,
    {
        self.apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .min_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
    }

    /// Finds maximum float value (terminal operation).
    pub fn max_by_float(self, path: KeyPaths<T, f64>) -> Option<f64>
    where
        I: 'a,
    {
        self.apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .max_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
    }

    // DateTime operations for SystemTime (lazy)
    /// Filter by SystemTime being after a reference time (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the SystemTime field
    /// * `reference` - The reference time to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let recent = LazyQuery::new(&events)
    ///     .where_after_systemtime(Event::timestamp(), cutoff_time)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_after_systemtime(self, path: KeyPaths<T, SystemTime>, reference: SystemTime) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        self.where_(path, move |time| time > &reference)
    }

    /// Filter by SystemTime being before a reference time (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the SystemTime field
    /// * `reference` - The reference time to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let old = LazyQuery::new(&events)
    ///     .where_before_systemtime(Event::timestamp(), cutoff_time)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_before_systemtime(self, path: KeyPaths<T, SystemTime>, reference: SystemTime) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        self.where_(path, move |time| time < &reference)
    }

    /// Filter by SystemTime being between two times (inclusive, lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the SystemTime field
    /// * `start` - The start time
    /// * `end` - The end time
    ///
    /// # Example
    ///
    /// ```ignore
    /// let range = LazyQuery::new(&events)
    ///     .where_between_systemtime(Event::timestamp(), start, end)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_between_systemtime(
        self,
        path: KeyPaths<T, SystemTime>,
        start: SystemTime,
        end: SystemTime,
    ) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        self.where_(path, move |time| time >= &start && time <= &end)
    }
}

// DateTime operations with chrono (only available with datetime feature, lazy)
#[cfg(feature = "datetime")]
impl<'a, T: 'static, I> LazyQuery<'a, T, I>
where
    I: Iterator<Item = &'a T> + 'a,
{
    /// Filter by DateTime being after a reference time (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `reference` - The reference time to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let recent = LazyQuery::new(&events)
    ///     .where_after(Event::timestamp(), cutoff_time)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_after<Tz>(self, path: KeyPaths<T, DateTime<Tz>>, reference: DateTime<Tz>) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        self.where_(path, move |time| time > &reference)
    }

    /// Filter by DateTime being before a reference time (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `reference` - The reference time to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let old = LazyQuery::new(&events)
    ///     .where_before(Event::timestamp(), cutoff_time)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_before<Tz>(self, path: KeyPaths<T, DateTime<Tz>>, reference: DateTime<Tz>) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        self.where_(path, move |time| time < &reference)
    }

    /// Filter by DateTime being between two times (inclusive, lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `start` - The start time
    /// * `end` - The end time
    ///
    /// # Example
    ///
    /// ```ignore
    /// let range = LazyQuery::new(&events)
    ///     .where_between(Event::timestamp(), start, end)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_between<Tz>(
        self,
        path: KeyPaths<T, DateTime<Tz>>,
        start: DateTime<Tz>,
        end: DateTime<Tz>,
    ) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        self.where_(path, move |time| time >= &start && time <= &end)
    }

    /// Filter by DateTime being today (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `now` - The current DateTime to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let today = LazyQuery::new(&events)
    ///     .where_today(Event::timestamp(), Utc::now())
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_today<Tz>(self, path: KeyPaths<T, DateTime<Tz>>, now: DateTime<Tz>) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        self.where_(path, move |time| {
            time.date_naive() == now.date_naive()
        })
    }

    /// Filter by DateTime year (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `year` - The year to filter by
    ///
    /// # Example
    ///
    /// ```ignore
    /// let this_year = LazyQuery::new(&events)
    ///     .where_year(Event::timestamp(), 2024)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_year<Tz>(self, path: KeyPaths<T, DateTime<Tz>>, year: i32) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        use chrono::Datelike;
        self.where_(path, move |time| time.year() == year)
    }

    /// Filter by DateTime month (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `month` - The month to filter by (1-12)
    ///
    /// # Example
    ///
    /// ```ignore
    /// let december = LazyQuery::new(&events)
    ///     .where_month(Event::timestamp(), 12)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_month<Tz>(self, path: KeyPaths<T, DateTime<Tz>>, month: u32) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        use chrono::Datelike;
        self.where_(path, move |time| time.month() == month)
    }

    /// Filter by DateTime day (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    /// * `day` - The day to filter by (1-31)
    ///
    /// # Example
    ///
    /// ```ignore
    /// let first = LazyQuery::new(&events)
    ///     .where_day(Event::timestamp(), 1)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_day<Tz>(self, path: KeyPaths<T, DateTime<Tz>>, day: u32) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        use chrono::Datelike;
        self.where_(path, move |time| time.day() == day)
    }

    /// Filter by weekend dates (Saturday and Sunday, lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    ///
    /// # Example
    ///
    /// ```ignore
    /// let weekend_events = LazyQuery::new(&events)
    ///     .where_weekend(Event::timestamp())
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_weekend<Tz>(self, path: KeyPaths<T, DateTime<Tz>>) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        use chrono::Datelike;
        self.where_(path, |time| {
            let weekday = time.weekday().num_days_from_monday();
            weekday >= 5
        })
    }

    /// Filter by weekday dates (Monday through Friday, lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    ///
    /// # Example
    ///
    /// ```ignore
    /// let weekday_events = LazyQuery::new(&events)
    ///     .where_weekday(Event::timestamp())
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_weekday<Tz>(self, path: KeyPaths<T, DateTime<Tz>>) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        use chrono::Datelike;
        self.where_(path, |time| {
            let weekday = time.weekday().num_days_from_monday();
            weekday < 5
        })
    }

    /// Filter by business hours (9 AM - 5 PM, lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the DateTime field
    ///
    /// # Example
    ///
    /// ```ignore
    /// let business_hours = LazyQuery::new(&events)
    ///     .where_business_hours(Event::timestamp())
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_business_hours<Tz>(self, path: KeyPaths<T, DateTime<Tz>>) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a>
    where
        Tz: TimeZone + 'static,
        Tz::Offset: std::fmt::Display,
    {
        use chrono::Timelike;
        self.where_(path, |time| {
            let hour = time.hour();
            hour >= 9 && hour < 17
        })
    }
}

// i64 DateTime Aggregators (Unix timestamps in milliseconds)
impl<'a, T: 'static, I> LazyQuery<'a, T, I>
where
    I: Iterator<Item = &'a T> + 'a,
{
    /// Finds minimum i64 timestamp value (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let earliest = LazyQuery::new(&events)
    ///     .min_timestamp(Event::created_at_r());
    /// ```
    pub fn min_timestamp(self, path: KeyPaths<T, i64>) -> Option<i64>
    where
        I: 'a,
    {
        self.apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .min()
    }

    /// Finds maximum i64 timestamp value (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let latest = LazyQuery::new(&events)
    ///     .max_timestamp(Event::created_at_r());
    /// ```
    pub fn max_timestamp(self, path: KeyPaths<T, i64>) -> Option<i64>
    where
        I: 'a,
    {
        self.apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .max()
    }

    /// Computes average of i64 timestamp values (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let avg = LazyQuery::new(&events)
    ///     .avg_timestamp(Event::created_at_r());
    /// ```
    pub fn avg_timestamp(self, path: KeyPaths<T, i64>) -> Option<i64>
    where
        I: 'a,
    {
        let items: Vec<i64> = self
            .apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .collect();

        if items.is_empty() {
            None
        } else {
            Some(items.iter().sum::<i64>() / items.len() as i64)
        }
    }

    /// Computes sum of i64 timestamp values (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let total = LazyQuery::new(&events)
    ///     .sum_timestamp(Event::created_at_r());
    /// ```
    pub fn sum_timestamp(self, path: KeyPaths<T, i64>) -> i64
    where
        I: 'a,
    {
        self.apply_filters()
            .filter_map(move |item| path.get(item).cloned())
            .sum()
    }

    /// Counts i64 timestamp values (terminal operation).
    ///
    /// # Example
    ///
    /// ```ignore
    /// let count = LazyQuery::new(&events)
    ///     .count_timestamp(Event::created_at_r());
    /// ```
    pub fn count_timestamp(self, path: KeyPaths<T, i64>) -> usize
    where
        I: 'a,
    {
        self.apply_filters()
            .filter(move |item| path.get(item).is_some())
            .count()
    }

    /// Filter by i64 timestamp being after a reference time (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `reference` - The reference timestamp to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let recent = LazyQuery::new(&events)
    ///     .where_after_timestamp(Event::created_at_r(), cutoff_time)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_after_timestamp(self, path: KeyPaths<T, i64>, reference: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        self.where_(path, move |timestamp| timestamp > &reference)
    }

    /// Filter by i64 timestamp being before a reference time (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `reference` - The reference timestamp to compare against
    ///
    /// # Example
    ///
    /// ```ignore
    /// let old = LazyQuery::new(&events)
    ///     .where_before_timestamp(Event::created_at_r(), cutoff_time)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_before_timestamp(self, path: KeyPaths<T, i64>, reference: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        self.where_(path, move |timestamp| timestamp < &reference)
    }

    /// Filter by i64 timestamp being between two times (inclusive, lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `start` - The start timestamp
    /// * `end` - The end timestamp
    ///
    /// # Example
    ///
    /// ```ignore
    /// let range = LazyQuery::new(&events)
    ///     .where_between_timestamp(Event::created_at_r(), start, end)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_between_timestamp(
        self,
        path: KeyPaths<T, i64>,
        start: i64,
        end: i64,
    ) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        self.where_(path, move |timestamp| timestamp >= &start && timestamp <= &end)
    }

    /// Filter by i64 timestamp being within the last N days (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `days` - Number of days to look back
    ///
    /// # Example
    ///
    /// ```ignore
    /// let recent = LazyQuery::new(&events)
    ///     .where_last_days_timestamp(Event::created_at_r(), 30)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_last_days_timestamp(self, path: KeyPaths<T, i64>, days: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        let now = chrono::Utc::now().timestamp_millis();
        let cutoff = now - (days * 24 * 60 * 60 * 1000); // Convert days to milliseconds
        self.where_after_timestamp(path, cutoff)
    }

    /// Filter by i64 timestamp being within the next N days (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `days` - Number of days to look forward
    ///
    /// # Example
    ///
    /// ```ignore
    /// let upcoming = LazyQuery::new(&events)
    ///     .where_next_days_timestamp(Event::scheduled_at_r(), 7)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_next_days_timestamp(self, path: KeyPaths<T, i64>, days: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        let now = chrono::Utc::now().timestamp_millis();
        let cutoff = now + (days * 24 * 60 * 60 * 1000); // Convert days to milliseconds
        self.where_before_timestamp(path, cutoff)
    }

    /// Filter by i64 timestamp being within the last N hours (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `hours` - Number of hours to look back
    ///
    /// # Example
    ///
    /// ```ignore
    /// let recent = LazyQuery::new(&events)
    ///     .where_last_hours_timestamp(Event::created_at_r(), 24)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_last_hours_timestamp(self, path: KeyPaths<T, i64>, hours: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        let now = chrono::Utc::now().timestamp_millis();
        let cutoff = now - (hours * 60 * 60 * 1000); // Convert hours to milliseconds
        self.where_after_timestamp(path, cutoff)
    }

    /// Filter by i64 timestamp being within the next N hours (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `hours` - Number of hours to look forward
    ///
    /// # Example
    ///
    /// ```ignore
    /// let upcoming = LazyQuery::new(&events)
    ///     .where_next_hours_timestamp(Event::scheduled_at_r(), 2)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_next_hours_timestamp(self, path: KeyPaths<T, i64>, hours: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        let now = chrono::Utc::now().timestamp_millis();
        let cutoff = now + (hours * 60 * 60 * 1000); // Convert hours to milliseconds
        self.where_before_timestamp(path, cutoff)
    }

    /// Filter by i64 timestamp being within the last N minutes (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `minutes` - Number of minutes to look back
    ///
    /// # Example
    ///
    /// ```ignore
    /// let recent = LazyQuery::new(&events)
    ///     .where_last_minutes_timestamp(Event::created_at_r(), 60)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_last_minutes_timestamp(self, path: KeyPaths<T, i64>, minutes: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        let now = chrono::Utc::now().timestamp_millis();
        let cutoff = now - (minutes * 60 * 1000); // Convert minutes to milliseconds
        self.where_after_timestamp(path, cutoff)
    }

    /// Filter by i64 timestamp being within the next N minutes (lazy).
    ///
    /// # Arguments
    ///
    /// * `path` - The key-path to the i64 timestamp field
    /// * `minutes` - Number of minutes to look forward
    ///
    /// # Example
    ///
    /// ```ignore
    /// let upcoming = LazyQuery::new(&events)
    ///     .where_next_minutes_timestamp(Event::scheduled_at_r(), 30)
    ///     .collect::<Vec<_>>();
    /// ```
    pub fn where_next_minutes_timestamp(self, path: KeyPaths<T, i64>, minutes: i64) -> LazyQuery<'a, T, impl Iterator<Item = &'a T> + 'a> {
        let now = chrono::Utc::now().timestamp_millis();
        let cutoff = now + (minutes * 60 * 1000); // Convert minutes to milliseconds
        self.where_before_timestamp(path, cutoff)
    }
}

// Enable using LazyQuery in for loops
// Note: This consumes the query and applies all filters
impl<'a, T: 'static, I> IntoIterator for LazyQuery<'a, T, I>
where
    I: Iterator<Item = &'a T> + 'a,
{
    type Item = &'a T;
    type IntoIter = Box<dyn Iterator<Item = &'a T> + 'a>;

    fn into_iter(self) -> Self::IntoIter {
        Box::new(self.apply_filters())
    }
}

#[cfg(test)]
mod tests {
    use crate::ext::QueryableExt;
    use crate::lazy::LazyQuery;
    use key_paths_derive::Keypath;

    #[derive(Debug, Clone, PartialEq, Keypath)]
    struct Product {
        id: u32,
        name: String,
        price: f64,
        category: String,
        stock: u32,
        rating: f64,
    }

    fn create_test_products() -> Vec<Product> {
        vec![
            Product {
                id: 1,
                name: "Laptop".to_string(),
                price: 999.99,
                category: "Electronics".to_string(),
                stock: 5,
                rating: 4.5,
            },
            Product {
                id: 2,
                name: "Mouse".to_string(),
                price: 29.99,
                category: "Electronics".to_string(),
                stock: 50,
                rating: 4.0,
            },
            Product {
                id: 3,
                name: "Keyboard".to_string(),
                price: 79.99,
                category: "Electronics".to_string(),
                stock: 30,
                rating: 4.8,
            },
            Product {
                id: 4,
                name: "Monitor".to_string(),
                price: 299.99,
                category: "Electronics".to_string(),
                stock: 12,
                rating: 4.2,
            },
            Product {
                id: 5,
                name: "Desk Chair".to_string(),
                price: 199.99,
                category: "Furniture".to_string(),
                stock: 8,
                rating: 4.7,
            },
            Product {
                id: 6,
                name: "Premium Laptop".to_string(),
                price: 1999.99,
                category: "Electronics".to_string(),
                stock: 3,
                rating: 4.9,
            },
        ]
    }

    #[test]
    fn test_where_implicit_and() {
        let products = create_test_products();
        
        // Multiple where_ calls should be ANDed together
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 100.0)
            .where_(Product::stock(), |&s| s > 10)
            .collect();
        
        // Should find: Mouse (29.99, stock 50) and Keyboard (79.99, stock 30)
        assert_eq!(results.len(), 2);
        assert!(results.iter().any(|p| p.name == "Mouse"));
        assert!(results.iter().any(|p| p.name == "Keyboard"));
    }

    #[test]
    fn test_explicit_and() {
        let products = create_test_products();
        
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 100.0)
            .and(Product::stock(), |&s| s > 10)
            .collect();
        
        // Should find: Mouse and Keyboard
        assert_eq!(results.len(), 2);
        assert!(results.iter().any(|p| p.name == "Mouse"));
        assert!(results.iter().any(|p| p.name == "Keyboard"));
    }

    #[test]
    fn test_or_operator() {
        let products = create_test_products();
        
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 50.0)
            .or(Product::category(), |c| c == "Furniture")
            .collect();
        
        // Should find: Mouse (price < 50) and Desk Chair (Furniture)
        assert_eq!(results.len(), 2);
        assert!(results.iter().any(|p| p.name == "Mouse"));
        assert!(results.iter().any(|p| p.name == "Desk Chair"));
    }

    #[test]
    fn test_complex_and_or_composition() {
        let products = create_test_products();
        
        // (price < 100 AND stock > 10) OR (category == "Furniture")
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 100.0)
            .and(Product::stock(), |&s| s > 10)
            .or(Product::category(), |c| c == "Furniture")
            .collect();
        
        // Should find: Mouse, Keyboard (from AND group), and Desk Chair (from OR group)
        assert_eq!(results.len(), 3);
        assert!(results.iter().any(|p| p.name == "Mouse"));
        assert!(results.iter().any(|p| p.name == "Keyboard"));
        assert!(results.iter().any(|p| p.name == "Desk Chair"));
    }

    #[test]
    fn test_multiple_and_conditions() {
        let products = create_test_products();
        
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 200.0)
            .and(Product::stock(), |&s| s > 5)
            .and(Product::rating(), |&r| r > 4.5)
            .collect();
        
        // Should find: Keyboard (79.99, stock 30, rating 4.8) and Desk Chair (199.99, stock 8, rating 4.7)
        assert_eq!(results.len(), 2);
        assert!(results.iter().any(|p| p.name == "Keyboard"));
        assert!(results.iter().any(|p| p.name == "Desk Chair"));
    }

    #[test]
    fn test_multiple_or_conditions() {
        let products = create_test_products();
        
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p > 500.0)
            .or(Product::category(), |c| c == "Furniture")
            .or(Product::rating(), |&r| r > 4.8)
            .collect();
        
        // Should find: Laptop (price > 500), Desk Chair (Furniture), Premium Laptop (rating > 4.8)
        assert_eq!(results.len(), 3);
        assert!(results.iter().any(|p| p.name == "Laptop"));
        assert!(results.iter().any(|p| p.name == "Desk Chair"));
        assert!(results.iter().any(|p| p.name == "Premium Laptop"));
    }

    #[test]
    fn test_and_then_or_then_where() {
        let products = create_test_products();
        
        // where().and().or().where() - the second where should add to OR group
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 100.0)
            .and(Product::stock(), |&s| s > 10)
            .or(Product::category(), |c| c == "Furniture")
            .where_(Product::rating(), |&r| r > 4.0)  // This should add to OR group
            .collect();
        
        // Logic: (price < 100 AND stock > 10) OR (category == "Furniture" OR rating > 4.0)
        // Since rating > 4.0 is true for almost all, this should find most products
        assert!(results.len() >= 3);
    }

    #[test]
    fn test_empty_results() {
        let products = create_test_products();
        
        // Impossible condition
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 0.0)
            .collect();
        
        assert_eq!(results.len(), 0);
    }

    #[test]
    fn test_all_results() {
        let products = create_test_products();
        
        // Condition that matches all
        let results: Vec<_> = products
            .lazy_query()
            .where_(Product::price(), |&p| p > 0.0)
            .collect();
        
        assert_eq!(results.len(), products.len());
    }

    #[test]
    fn test_or_with_no_previous_and() {
        let products = create_test_products();
        
        // Starting with OR (no previous AND group)
        let results: Vec<_> = products
            .lazy_query()
            .or(Product::category(), |c| c == "Furniture")
            .collect();
        
        // Should find Desk Chair
        assert_eq!(results.len(), 1);
        assert!(results[0].name == "Desk Chair");
    }

    #[test]
    fn test_count_with_and_or() {
        let products = create_test_products();
        
        let count = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 100.0)
            .and(Product::stock(), |&s| s > 10)
            .count();
        
        assert_eq!(count, 2);
    }

    #[test]
    fn test_first_with_and_or() {
        let products = create_test_products();
        
        let first = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 100.0)
            .and(Product::stock(), |&s| s > 10)
            .first();
        
        assert!(first.is_some());
        assert!(first.unwrap().price < 100.0);
        assert!(first.unwrap().stock > 10);
    }

    #[test]
    fn test_any_with_and_or() {
        let products = create_test_products();
        
        let has_match = products
            .lazy_query()
            .where_(Product::price(), |&p| p < 50.0)
            .or(Product::category(), |c| c == "Furniture")
            .any();
        
        assert!(has_match);
    }
}