Refactor to use FlattenableFilter pattern - keep geometry validation in spatial module

Co-authored-by: anidotnet <[email protected]>

Author: Copilot

packages/nitrite/lib/src/collection/operations/find_optimizer.dart

@@ -17,8 +17,8 @@ class FindOptimizer {
 
   FindPlan _createFilterPlan(
       Iterable<IndexDescriptor> indexDescriptors, Filter filter) {
-    if (filter is AndFilter) {
-      var filters = _flattenAndFilter(filter);
+    if (filter is FlattenableFilter) {
+      var filters = _flattenFilter(filter);
       return _createAndPlan(indexDescriptors, filters);
     } else if (filter is OrFilter) {
       return _createOrPlan(indexDescriptors, filter.filters);
@@ -28,11 +28,11 @@ class FindOptimizer {
     }
   }
 
-  List<Filter> _flattenAndFilter(AndFilter andFilter) {
+  List<Filter> _flattenFilter(FlattenableFilter flattenableFilter) {
     var flattenedFilters = <Filter>[];
-    for (var filter in andFilter.filters) {
-      if (filter is AndFilter) {
-        flattenedFilters.addAll(_flattenAndFilter(filter));
+    for (var filter in flattenableFilter.getFilters()) {
+      if (filter is FlattenableFilter) {
+        flattenedFilters.addAll(_flattenFilter(filter));
       } else {
         flattenedFilters.add(filter);
       }
@@ -241,13 +241,6 @@ class FindOptimizer {
         if (filter != findPlan.byIdFilter) {
           columnScanFilters.add(filter);
         }
-      } else if (filter is IndexOnlyFilter &&
-          filter.needsPostIndexValidation()) {
-        // Some index-only filters (like spatial filters) need post-index validation
-        // because the index can return false positives. For example, R-Tree spatial
-        // indexes store only bounding boxes, so they may return documents whose
-        // bounding boxes overlap but actual geometries don't intersect.
-        columnScanFilters.add(filter);
       }
     }
 

packages/nitrite/lib/src/filters/filter.dart

@@ -175,6 +175,16 @@ abstract class Filter {
   }
 }
 
+/// Represents a filter which can be flattened or consists of multiple constituent filters.
+///
+/// This interface allows filters to be decomposed into multiple sub-filters during query
+/// optimization. For example, spatial filters can be split into an index scan filter 
+/// (for bounding box checks) and a validation filter (for actual geometry checks).
+abstract class FlattenableFilter {
+  /// Returns the list of constituent filters that make up this filter.
+  List<Filter> getFilters();
+}
+
 /// An abstract class representing a filter for Nitrite database.
 abstract class NitriteFilter extends Filter {
   /// Gets the [NitriteConfig] instance.
@@ -330,17 +340,6 @@ abstract class IndexOnlyFilter extends ComparableFilter {
 
   /// Checks if `other` filter can be grouped together with this filter.
   bool canBeGrouped(IndexOnlyFilter other);
-
-  /// Indicates whether this filter requires post-index validation.
-  /// 
-  /// Some index-only filters (like spatial filters) use the index for
-  /// preliminary filtering but need a second pass to validate the actual
-  /// condition. For example, R-Tree spatial indexes store only bounding boxes,
-  /// so they may return false positives that need to be filtered out.
-  /// 
-  /// Returns `true` if this filter needs to be applied again after index scan
-  /// to validate results. Defaults to `false`.
-  bool needsPostIndexValidation() => false;
 }
 
 /// @nodoc

packages/nitrite/lib/src/filters/filter_impl.dart

@@ -70,7 +70,7 @@ class OrFilter extends LogicalFilter {
 }
 
 /// @nodoc
-class AndFilter extends LogicalFilter {
+class AndFilter extends LogicalFilter implements FlattenableFilter {
   AndFilter(List<Filter> filters) : super(filters) {
     for (int i = 1; i < filters.length; i++) {
       if (filters[i] is TextFilter) {
@@ -91,6 +91,9 @@ class AndFilter extends LogicalFilter {
     return true;
   }
 
+  @override
+  List<Filter> getFilters() => filters;
+
   @override
   String toString() {
     StringBuffer buffer = StringBuffer();

packages/nitrite_spatial/lib/src/filter.dart

@@ -17,11 +17,30 @@ abstract class SpatialFilter extends IndexOnlyFilter {
 
   @override
   bool apply(Document doc) {
-    // This method validates the actual geometry intersection/containment
-    // after the R-Tree index has filtered candidates based on bounding boxes.
-    // The R-Tree only stores bounding boxes, so it can return false positives.
-    // This second-stage check ensures we only return documents whose geometries
-    // actually satisfy the spatial relationship.
+    return false;
+  }
+
+  @override
+  String supportedIndexType() {
+    return spatialIndex;
+  }
+
+  @override
+  bool canBeGrouped(IndexOnlyFilter other) {
+    return other is SpatialFilter && other.field == field;
+  }
+}
+
+/// A non-index filter that validates actual geometry relationships.
+/// This filter is used as the second stage of spatial filtering after
+/// the R-Tree index has filtered candidates based on bounding boxes.
+class _GeometryValidationFilter extends FieldBasedFilter {
+  final bool Function(Geometry, Geometry) _validator;
+
+  _GeometryValidationFilter(super.field, super.value, this._validator);
+
+  @override
+  bool apply(Document doc) {
     var fieldValue = doc.get(field);
     if (fieldValue == null) {
       return false;
@@ -42,28 +61,12 @@ abstract class SpatialFilter extends IndexOnlyFilter {
       return false;
     }
 
-    return applyGeometryFilter(documentGeometry!);
-  }
-
-  /// Subclasses must implement this to define the specific spatial relationship check
-  bool applyGeometryFilter(Geometry documentGeometry);
-
-  @override
-  String supportedIndexType() {
-    return spatialIndex;
+    return _validator(documentGeometry!, value as Geometry);
   }
-
-  @override
-  bool canBeGrouped(IndexOnlyFilter other) {
-    return other is SpatialFilter && other.field == field;
-  }
-
-  @override
-  bool needsPostIndexValidation() => true;
 }
 
 ///@nodoc
-class WithinFilter extends SpatialFilter {
+class WithinFilter extends SpatialFilter implements FlattenableFilter {
   WithinFilter(super.field, super.value);
 
   @override
@@ -73,9 +76,16 @@ class WithinFilter extends SpatialFilter {
   }
 
   @override
-  bool applyGeometryFilter(Geometry documentGeometry) {
-    // Check if the document geometry is within the filter geometry
-    return documentGeometry.within(value);
+  List<Filter> getFilters() {
+    // Return two filters: one for index scan (this), one for validation
+    return [
+      this,
+      _GeometryValidationFilter(
+        field,
+        value,
+        (docGeom, filterGeom) => docGeom.within(filterGeom),
+      ),
+    ];
   }
 
   @override
@@ -85,7 +95,7 @@ class WithinFilter extends SpatialFilter {
 }
 
 ///@nodoc
-class IntersectsFilter extends SpatialFilter {
+class IntersectsFilter extends SpatialFilter implements FlattenableFilter {
   IntersectsFilter(super.field, super.value);
 
   @override
@@ -95,9 +105,16 @@ class IntersectsFilter extends SpatialFilter {
   }
 
   @override
-  bool applyGeometryFilter(Geometry documentGeometry) {
-    // Check if the document geometry intersects the filter geometry
-    return documentGeometry.intersects(value);
+  List<Filter> getFilters() {
+    // Return two filters: one for index scan (this), one for validation
+    return [
+      this,
+      _GeometryValidationFilter(
+        field,
+        value,
+        (docGeom, filterGeom) => docGeom.intersects(filterGeom),
+      ),
+    ];
   }
 
   @override