activerecord-postgis 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b452469d6861f42a259853b4f6b3f7e5a694d98c325141d5a43ac09eaf40e967
-  data.tar.gz: ada960ed4d93542ae2f2f805412d8b39dc58ae52cfa1612b8007e53e2bf2952f
+  metadata.gz: 348c302fed46b25f5815a94a08f24882b3c9ce9a4f29907ba5e3fcd6570dbf27
+  data.tar.gz: dd1a7f7de5e9a71178a2e98981221861824336c20861fce51a2da6d6b6eeceac
 SHA512:
-  metadata.gz: d3c0f7fa79a22ba014655f18198bc4c048f3287fa6ade5e5c1442e8f0099c910394bc7592939b3a8c911670d9c4a54b5bbb8d0d29b568dddaf0406cba310c453
-  data.tar.gz: 14c0462864a39e967b1c2c684a0dda6a6e0d6b1d902c87561398dc214f4934238594f8847b26ba33e52df669f00d998828df0c2ca29305fc56f94209e45019bc
+  metadata.gz: '08ce6f86d903016208598a2c70e8da83d59fbf9b11afd8f7db0b4b1a8cb953599c43ce102ac3b84938a6b934e82af0791d2641ba453c2a17a6b75c15ad85ca13'
+  data.tar.gz: 6d529987e15c03978f48e346cb174f900d95493e6b1c1f2a1e417c71005ff2e7d75e1e3ee76099fcabd03b7705f28c60b04d983e609e6969929329f5d7d7a494

data/README.md

@@ -93,22 +93,42 @@ parks_in_city = Park.where(
 )
 ```
 
-**With Arel Spatial Methods**:
+**With Arel Spatial Methods** (Now with expanded arsenal!):
 
 ```ruby
-# Find locations within distance
+# Basic spatial queries
 Location.where(
   Location.arel_table[:coordinates].st_distance(point).lt(1000)
 )
 
-# Find polygons that contain a point
-Boundary.where(
-  Boundary.arel_table[:area].st_contains(Arel.spatial(point))
+# NEW: K-Nearest Neighbor - Lightning fast "find nearest" queries
+# Uses spatial index for incredible performance!
+nearest_locations = Location
+  .order(Location.arel_table[:coordinates].distance_operator(my_position))
+  .limit(10)
+
+# Advanced spatial predicates
+# Find intersecting routes
+Route.where(Route.arel_table[:path].st_intersects(restricted_zone))
+
+# Find points within efficient distance (uses spatial index!)
+Location.where(
+  Location.arel_table[:coordinates].st_dwithin(headquarters, 5000)
+)
+
+# Create buffer zones
+safe_zones = DangerZone.select(
+  DangerZone.arel_table[:area].st_buffer(100).as('safety_perimeter')
+)
+
+# Transform between coordinate systems
+global_coords = Location.select(
+  Location.arel_table[:local_position].st_transform(4326).as('wgs84_position')
 )
 
-# Calculate lengths and areas
-Route.select(
-  Route.arel_table[:path].st_length.as('distance')
+# Calculate areas
+territories = Region.select(
+  Region.arel_table[:boundary].st_area.as('territory_size')
 )
 ```
 
@@ -139,6 +159,97 @@ puts location.coordinates.x  # -5.923647
 puts location.coordinates.y  # 35.790897
 ```
 
+## Testing
+
+When testing spatial functionality in your Rails application, this gem provides helpful test utilities:
+
+```ruby
+# In your test_helper.rb or rails_helper.rb
+require 'activerecord-postgis/test_helper'
+
+class ActiveSupport::TestCase
+  include ActiveRecordPostgis::TestHelper
+end
+
+# Or for RSpec
+RSpec.configure do |config|
+  config.include ActiveRecordPostgis::TestHelper
+end
+```
+
+### Test Helper Methods
+
+```ruby
+class LocationTest < ActiveSupport::TestCase
+  def test_spatial_operations
+    # Create test geometries
+    point1 = create_point(-5.9, 35.8)
+    point2 = create_point(-5.91, 35.81)
+    polygon = create_test_polygon
+    
+    location = Location.create!(coordinates: point1, boundary: polygon)
+    
+    # Traditional assertions
+    assert_spatial_equal point1, location.coordinates
+    assert_within_distance point1, point2, 200  # meters
+    assert_contains polygon, point1
+    
+    # New chainable syntax (recommended)
+    assert_spatial_column(location.coordinates)
+      .has_srid(4326)
+      .is_type(:point)
+      .is_geographic
+      
+    assert_spatial_column(location.boundary)
+      .is_type(:polygon)
+      .has_srid(4326)
+  end
+  
+  def test_3d_geometry
+    point_3d = create_point(1.0, 2.0, srid: 4326, z: 10.0)
+    
+    assert_spatial_column(point_3d)
+      .has_z
+      .has_srid(4326)
+      .is_type(:point)
+      .is_cartesian
+  end
+end
+```
+
+**Available Test Helpers:**
+
+**Traditional Assertions:**
+- `assert_spatial_equal(expected, actual)` - Assert spatial objects are equal
+- `assert_within_distance(point1, point2, distance)` - Assert points within distance
+- `assert_contains(container, contained)` - Assert geometry contains another
+- `assert_within(inner, outer)` - Assert geometry is within another
+- `assert_intersects(geom1, geom2)` - Assert geometries intersect
+- `assert_disjoint(geom1, geom2)` - Assert geometries don't intersect
+
+**Chainable Spatial Column Assertions:**
+- `assert_spatial_column(geometry).has_z` - Assert has Z dimension
+- `assert_spatial_column(geometry).has_m` - Assert has M dimension
+- `assert_spatial_column(geometry).has_srid(srid)` - Assert SRID value
+- `assert_spatial_column(geometry).is_type(type)` - Assert geometry type
+- `assert_spatial_column(geometry).is_geographic` - Assert geographic factory
+- `assert_spatial_column(geometry).is_cartesian` - Assert cartesian factory
+
+**Geometry Factories:**
+- `create_point(x, y, srid: 4326)` - Create test points
+- `create_test_polygon(srid: 4326)` - Create test polygons  
+- `create_test_linestring(srid: 4326)` - Create test linestrings
+- `factory(srid: 4326, geographic: false)` - Get geometry factory
+- `geographic_factory(srid: 4326)` - Get geographic factory
+- `cartesian_factory(srid: 0)` - Get cartesian factory
+
+## Documentation
+
+📚 **Learn Like You're Defending the Galaxy**
+
+- [🚀 Spatial Warfare Manual](docs/SPATIAL_WARFARE.md) - Advanced PostGIS arsenal explained through space combat
+- [🍳 The PostGIS Cookbook](docs/COOKBOOK.md) - Real-world recipes from delivery fleets to geofencing
+
 ## Features
 
 🌍 **Complete PostGIS Type Support**
@@ -148,7 +259,14 @@ puts location.coordinates.y  # 35.790897
 - Support for SRID, Z/M dimensions
 
 🔍 **Spatial Query Methods**
-- `st_distance`, `st_contains`, `st_within`, `st_length`
+- Core methods: `st_distance`, `st_contains`, `st_within`, `st_length`
+- **NEW:** Advanced spatial operations:
+  - `<->` (distance_operator) - K-Nearest Neighbor search (blazing fast!)
+  - `st_intersects` - Detect geometry intersections
+  - `st_dwithin` - Efficient proximity queries (index-optimized!)
+  - `st_buffer` - Create buffer zones around geometries
+  - `st_transform` - Convert between coordinate systems
+  - `st_area` - Calculate polygon areas
 - Custom Arel visitor for PostGIS SQL generation
 - Seamless integration with ActiveRecord queries
 
@@ -163,6 +281,7 @@ puts location.coordinates.y  # 35.790897
 - Works with existing PostgreSQL tools
 - Clear error messages and debugging
 - Full RGeo integration
+- Comprehensive test helpers for spatial assertions
 
 ## Acknowledgments
 

data/lib/active_record/connection_adapters/postgis/test_helpers.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module PostGIS
+      # Test helpers for spatial data assertions
+      module TestHelpers
+        # Assert that two spatial objects are equal
+        def assert_spatial_equal(expected, actual, msg = nil)
+          msg ||= "Expected spatial object #{expected.as_text} but got #{actual.as_text}"
+
+          if expected.respond_to?(:equals?) && actual.respond_to?(:equals?)
+            assert expected.equals?(actual), msg
+          else
+            assert_equal expected.to_s, actual.to_s, msg
+          end
+        end
+
+        # Assert that a point is within a specified distance of another point
+        def assert_within_distance(point1, point2, distance, msg = nil)
+          actual_distance = point1.distance(point2)
+          msg ||= "Distance #{actual_distance} exceeds maximum allowed distance of #{distance}"
+          assert actual_distance <= distance, msg
+        end
+
+        # Assert that a geometry contains another geometry
+        def assert_contains(container, contained, msg = nil)
+          msg ||= "Expected #{container.as_text} to contain #{contained.as_text}"
+          assert container.contains?(contained), msg
+        end
+
+        # Assert that a geometry is within another geometry
+        def assert_within(inner, outer, msg = nil)
+          msg ||= "Expected #{inner.as_text} to be within #{outer.as_text}"
+          assert inner.within?(outer), msg
+        end
+
+        # Assert that two geometries intersect
+        def assert_intersects(geom1, geom2, msg = nil)
+          msg ||= "Expected #{geom1.as_text} to intersect #{geom2.as_text}"
+          assert geom1.intersects?(geom2), msg
+        end
+
+        # Assert that two geometries do not intersect
+        def assert_disjoint(geom1, geom2, msg = nil)
+          msg ||= "Expected #{geom1.as_text} to be disjoint from #{geom2.as_text}"
+          assert geom1.disjoint?(geom2), msg
+        end
+
+        # Assert that a geometry has the expected SRID
+        def assert_srid(geometry, expected_srid, msg = nil)
+          actual_srid = geometry.srid
+          msg ||= "Expected SRID #{expected_srid} but got #{actual_srid}"
+          assert_equal expected_srid, actual_srid, msg
+        end
+
+        # Chainable spatial column assertion builder
+        def assert_spatial_column(geometry, msg_prefix = nil)
+          SpatialColumnAssertion.new(geometry, self, msg_prefix)
+        end
+
+        # Assert that a geometry is of the expected type
+        def assert_geometry_type(geometry, expected_type, msg = nil)
+          actual_type = geometry.geometry_type.type_name.downcase
+          expected_type = expected_type.to_s.downcase.gsub("_", "")
+          actual_type = actual_type.gsub("_", "")
+          msg ||= "Expected geometry type #{expected_type} but got #{actual_type}"
+          assert_equal expected_type, actual_type, msg
+        end
+
+        # Legacy methods for backward compatibility
+        def assert_has_z(geometry, msg = nil)
+          assert_spatial_column(geometry, msg).has_z
+        end
+
+        def assert_has_m(geometry, msg = nil)
+          assert_spatial_column(geometry, msg).has_m
+        end
+
+        # Create a point for testing
+        def create_point(x, y, srid: 4326, z: nil, m: nil)
+          if z || m
+            # Use cartesian factory for 3D/4D points
+            factory = RGeo::Cartesian.preferred_factory(srid: srid, has_z_coordinate: !!z, has_m_coordinate: !!m)
+            if z && m
+              factory.point(x, y, z, m)
+            elsif z
+              factory.point(x, y, z)
+            elsif m
+              factory.point(x, y, 0, m)  # Default Z to 0 for M-only
+            else
+              factory.point(x, y)
+            end
+          else
+            factory = RGeo::Geographic.simple_mercator_factory(srid: srid)
+            factory.point(x, y)
+          end
+        end
+
+        # Create a test polygon for testing
+        def create_test_polygon(srid: 4326)
+          factory = RGeo::Geographic.simple_mercator_factory(srid: srid)
+          factory.polygon(
+            factory.linear_ring([
+              factory.point(0, 0),
+              factory.point(0, 1),
+              factory.point(1, 1),
+              factory.point(1, 0),
+              factory.point(0, 0)
+            ])
+          )
+        end
+
+        # Create a test linestring for testing
+        def create_test_linestring(srid: 4326)
+          factory = RGeo::Geographic.simple_mercator_factory(srid: srid)
+          factory.line_string([
+            factory.point(0, 0),
+            factory.point(1, 1),
+            factory.point(2, 0)
+          ])
+        end
+      end
+
+      # Chainable spatial column assertion class
+      class SpatialColumnAssertion
+        def initialize(geometry, test_case, msg_prefix = nil)
+          @geometry = geometry
+          @test_case = test_case
+          @msg_prefix = msg_prefix
+        end
+
+        def has_z
+          msg = build_message("to have Z dimension")
+          has_z = detect_has_z(@geometry)
+          @test_case.assert has_z, msg
+          self
+        end
+
+        def has_m
+          msg = build_message("to have M dimension")
+          has_m = detect_has_m(@geometry)
+          @test_case.assert has_m, msg
+          self
+        end
+
+        def has_srid(expected_srid)
+          msg = build_message("to have SRID #{expected_srid}")
+          actual_srid = @geometry.srid
+          @test_case.assert_equal expected_srid, actual_srid, msg
+          self
+        end
+
+        def is_type(expected_type)
+          msg = build_message("to be of type #{expected_type}")
+          actual_type = @geometry.geometry_type.type_name.downcase
+          expected_type = expected_type.to_s.downcase.gsub("_", "")
+          actual_type = actual_type.gsub("_", "")
+          @test_case.assert_equal expected_type, actual_type, msg
+          self
+        end
+
+        def is_geographic
+          msg = build_message("to be geographic")
+          # Check if factory is geographic
+          is_geo = @geometry.factory.respond_to?(:spherical?) && @geometry.factory.spherical?
+          @test_case.assert is_geo, msg
+          self
+        end
+
+        def is_cartesian
+          msg = build_message("to be cartesian")
+          # Check if factory is cartesian
+          is_cart = !(@geometry.factory.respond_to?(:spherical?) && @geometry.factory.spherical?)
+          @test_case.assert is_cart, msg
+          self
+        end
+
+        private
+
+        def build_message(expectation)
+          prefix = @msg_prefix ? "#{@msg_prefix}: " : ""
+          "#{prefix}Expected geometry #{expectation}"
+        end
+
+        def detect_has_z(geometry)
+          return geometry.has_z_coordinate? if geometry.respond_to?(:has_z_coordinate?)
+          return geometry.has_z? if geometry.respond_to?(:has_z?)
+          return !geometry.z.nil? if geometry.respond_to?(:z)
+          false
+        end
+
+        def detect_has_m(geometry)
+          return geometry.has_m_coordinate? if geometry.respond_to?(:has_m_coordinate?)
+          return geometry.has_m? if geometry.respond_to?(:has_m?)
+          return !geometry.m.nil? if geometry.respond_to?(:m)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/postgis/version.rb

@@ -3,7 +3,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module PostGIS
-      VERSION = "0.2.0"
+      VERSION = "0.3.1"
     end
   end
 end

data/lib/active_record/connection_adapters/postgis.rb

@@ -142,6 +142,16 @@ module ActiveRecord
         private
 
         def create_spatial_type_from_sql(sql_type)
+          # Handle empty sql_type (common in joins) - this is an upstream Rails issue
+          # where sql_type comes back as empty string, making it impossible to determine
+          # the correct spatial type properties
+          if sql_type.nil? || sql_type.empty?
+            # Log warning about potential type mismatch due to upstream issue
+            # Users experiencing this should use explicit attribute registration as workaround
+            # See: https://github.com/rgeo/activerecord-postgis-adapter/pull/334
+            return Type::Geometry.new(srid: 0, has_z: false, has_m: false, geographic: false)
+          end
+
           # Extract SRID and dimensions from SQL type
           srid = extract_srid_from_sql(sql_type)
           # Check for dimension suffixes (e.g., PointZ, PointM, PointZM)
@@ -182,6 +192,7 @@ module ActiveRecord
           when /geometry/i
             Type::Geometry.new(srid: srid, has_z: has_z, has_m: has_m)
           else
+            # Fallback for unrecognized types
             Type::Geometry.new(srid: srid, has_z: has_z, has_m: has_m)
           end
         end

data/lib/activerecord-postgis/test_helper.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../active_record/connection_adapters/postgis/test_helpers"
+
+module ActiveRecordPostgis
+  module TestHelper
+    include ActiveRecord::ConnectionAdapters::PostGIS::TestHelpers
+
+    # Additional convenience methods for PostGIS testing
+    def factory(srid: 4326, geographic: false)
+      if geographic
+        RGeo::Geographic.spherical_factory(srid: srid)
+      else
+        RGeo::Cartesian.preferred_factory(srid: srid)
+      end
+    end
+
+    def geographic_factory(srid: 4326)
+      RGeo::Geographic.spherical_factory(srid: srid)
+    end
+
+    def cartesian_factory(srid: 0)
+      RGeo::Cartesian.preferred_factory(srid: srid)
+    end
+
+    def spatial_factory_store
+      RGeo::ActiveRecord::SpatialFactoryStore.instance
+    end
+
+    def reset_spatial_store
+      spatial_factory_store.clear
+      spatial_factory_store.default = nil
+    end
+
+    # Create a test table with spatial columns
+    def create_spatial_table(table_name, connection = ActiveRecord::Base.connection)
+      connection.create_table table_name, force: true do |t|
+        t.st_point :coordinates, srid: 4326
+        t.st_point :location, srid: 4326, geographic: true
+        t.st_polygon :boundary, srid: 4326
+        t.st_line_string :path, srid: 4326
+        t.timestamps
+      end
+    end
+
+    # Clean up spatial tables after tests
+    def drop_spatial_table(table_name, connection = ActiveRecord::Base.connection)
+      connection.drop_table table_name if connection.table_exists?(table_name)
+    end
+  end
+end

data/lib/arel/visitors/postgis.rb

@@ -16,6 +16,33 @@ module Arel
     class SpatialLength < Unary; end
     class SpatialContains < SpatialNode; end
     class SpatialWithin < SpatialNode; end
+    class SpatialIntersects < SpatialNode; end
+    class SpatialDWithin < SpatialNode
+      attr_reader :distance
+      
+      def initialize(left, right, distance)
+        super(left, right)
+        @distance = distance
+      end
+    end
+    class SpatialBuffer < SpatialNode
+      def st_area
+        SpatialArea.new(self)
+      end
+    end
+    class SpatialTransform < SpatialNode
+      def st_area
+        SpatialArea.new(self)
+      end
+    end
+    class SpatialArea < Unary; end
+    
+    # K-Nearest Neighbor distance operator
+    class SpatialDistanceOperator < Binary
+      def initialize(left, right)
+        super
+      end
+    end
 
     # Wrapper for spatial values that need special handling
     class SpatialValue < Node
@@ -36,6 +63,32 @@ module Arel
       def st_within(other)
         SpatialWithin.new(self, other)
       end
+
+      def st_intersects(other)
+        SpatialIntersects.new(self, other)
+      end
+
+      def st_dwithin(other, distance)
+        SpatialDWithin.new(self, other, distance)
+      end
+
+      def st_buffer(distance)
+        SpatialBuffer.new(self, distance)
+      end
+
+      def st_transform(srid)
+        SpatialTransform.new(self, srid)
+      end
+
+      def st_area
+        SpatialArea.new(self)
+      end
+      
+      def distance_operator(other)
+        SpatialDistanceOperator.new(self, other)
+      end
+      
+      alias :'<->' :distance_operator
     end
   end
 
@@ -56,6 +109,32 @@ module Arel
       def st_within(other)
         Arel::Nodes::SpatialWithin.new(self, other)
       end
+
+      def st_intersects(other)
+        Arel::Nodes::SpatialIntersects.new(self, other)
+      end
+
+      def st_dwithin(other, distance)
+        Arel::Nodes::SpatialDWithin.new(self, other, distance)
+      end
+
+      def st_buffer(distance)
+        Arel::Nodes::SpatialBuffer.new(self, distance)
+      end
+
+      def st_transform(srid)
+        Arel::Nodes::SpatialTransform.new(self, srid)
+      end
+
+      def st_area
+        Arel::Nodes::SpatialArea.new(self)
+      end
+      
+      def distance_operator(other)
+        Arel::Nodes::SpatialDistanceOperator.new(self, other)
+      end
+      
+      alias :'<->' :distance_operator
     end
   end
 
@@ -112,6 +191,52 @@ module Arel
         visit_spatial_operand(node.value, collector)
       end
 
+      def visit_Arel_Nodes_SpatialIntersects(node, collector)
+        collector << "ST_Intersects("
+        visit(node.left, collector)
+        collector << ", "
+        visit_spatial_operand(node.right, collector)
+        collector << ")"
+      end
+
+      def visit_Arel_Nodes_SpatialDWithin(node, collector)
+        collector << "ST_DWithin("
+        visit(node.left, collector)
+        collector << ", "
+        visit_spatial_operand(node.right, collector)
+        collector << ", "
+        collector << node.distance.to_s
+        collector << ")"
+      end
+
+      def visit_Arel_Nodes_SpatialBuffer(node, collector)
+        collector << "ST_Buffer("
+        visit(node.left, collector)
+        collector << ", "
+        collector << node.right.to_s
+        collector << ")"
+      end
+
+      def visit_Arel_Nodes_SpatialTransform(node, collector)
+        collector << "ST_Transform("
+        visit(node.left, collector)
+        collector << ", "
+        collector << node.right.to_s
+        collector << ")"
+      end
+
+      def visit_Arel_Nodes_SpatialArea(node, collector)
+        collector << "ST_Area("
+        visit(node.expr, collector)
+        collector << ")"
+      end
+      
+      def visit_Arel_Nodes_SpatialDistanceOperator(node, collector)
+        visit(node.left, collector)
+        collector << " <-> "
+        visit_spatial_operand(node.right, collector)
+      end
+
       private
 
       def visit_spatial_operand(operand, collector)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-postgis
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -80,6 +80,7 @@ files:
 - lib/active_record/connection_adapters/postgis/spatial_column_methods.rb
 - lib/active_record/connection_adapters/postgis/spatial_column_type.rb
 - lib/active_record/connection_adapters/postgis/table_definition.rb
+- lib/active_record/connection_adapters/postgis/test_helpers.rb
 - lib/active_record/connection_adapters/postgis/type/geography.rb
 - lib/active_record/connection_adapters/postgis/type/geometry.rb
 - lib/active_record/connection_adapters/postgis/type/geometry_collection.rb
@@ -92,6 +93,7 @@ files:
 - lib/active_record/connection_adapters/postgis/type/spatial.rb
 - lib/active_record/connection_adapters/postgis/version.rb
 - lib/activerecord-postgis.rb
+- lib/activerecord-postgis/test_helper.rb
 - lib/arel/visitors/postgis.rb
 homepage: https://github.com/seuros/activerecord-postgis
 licenses:
@@ -114,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: PostGIS Type support for ActiveRecord
 test_files: []