mongoid-geospatial 7.2.0 → 7.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bc532f8201a1c7c0f43c63d051a073dd5658ab8ffa561ea852e14a0fcf1c243
-  data.tar.gz: 9af8f1e4e1ef5f2514e3214f5e0bc66c0f56fbb7e9a1cbdf3fd152e89b11cbad
+  metadata.gz: 9437e8d6af695bcba5f39208f8219019da404fc51b863c4fb7940567183c5c9f
+  data.tar.gz: 2a3ca5f675cd58c204462b7122b84341c63cee8222f3372a014d1ed3096f82f0
 SHA512:
-  metadata.gz: 154e488426770257945cd93d36138d238d5b1bf75e308b62b568ba897f9835f921faf26d50f14e71c9f3f43f0ce9be761586f228a788819a0ed7f2662274fbc3
-  data.tar.gz: 1fbd1713b7121edc2bc8f171a5cf66f63befc5668369d1f833d0be1d0783844bb41ffdf62e618172324e15bb2cfb4e905a3cd91896ec9b7d28a46142a06b6769
+  metadata.gz: 82fe874fb74ab68457b2e9c56c202bd94ff6c71626832fa0a514d8ce7741282bff68d7c08601806c72e56bf4364d5173f3cdfdaca47b005c86f698f0601d9697
+  data.tar.gz: fb2a788d4559688612083fddb24ef77d632d0d18b58aa5f3a6216ca58d6c6220a88180db3b009f4697fda2aa0cb95a43d3ef2d11ccc6e0d8a4f8003cc320227c

data/README.md

@@ -105,7 +105,7 @@ cafe.location.to_hsh   # => { x: -74.026667, y: 40.703056 }
 Commonly used
 
 ```ruby
-cafe.location.to_lat_lon   # => { lat: 40.703056, lon: -74.026667 }
+cafe.location.to_lat_lon   # => { latitude: 40.703056, longitude: -74.026667 }
 cafe.location.lat          # => 40.703056
 cafe.location.lng          # => -74.026667
 cafe.location.distance(other) # => km, haversine
@@ -238,10 +238,30 @@ Bar.where(:location.near_sphere => person.house)
 Bar.nearby(person.house)
 Bar.nearby(person.house, km: 30)
 Bar.within(person.house, 30)          # same question, km required
+Bar.nearest(person.house, 30)         # the closest one, or nil
+Ride.within(here, 5, field: :drop_up) # two pins? name the one you mean
 City.where(:geom.near_sphere => Mongoid::Geospatial.near_query(geom, 50))
 ```
 
-`within` is `$nearSphere` + `$maxDistance` in metres. Nearest first, chainable.
+`within` caps by km, nearest first, chainable — on either index. `$nearSphere`
+speaks two dialects and **the field's index picks which**, so the km never moves:
+
+```
+   sphere: true    { loc: { $nearSphere: { $geometry: {..}, $maxDistance: <metres> } } }
+   spatial: true   { loc: { $nearSphere: [x, y],            $maxDistance: <radians> } }
+                                                                          km / 6371
+```
+
+Hand the server the wrong one and it answers `NoQueryExecutionPlans` — not a
+wrong count, a raise.
+
+**`within(..).first` is not the nearest one.** Mongoid's `#first` and `#last`
+sort by `_id` whenever the criteria carries no sort of its own, and that `_id`
+sort replaces the distance order `$near` put there. It reads as working every
+time the closest document happens to be the oldest. Walk the criteria
+(`.to_a.first`) or ask `nearest`. `Mongoid::Geospatial.near_selector(field, point, km,
+sphere: <bool>)` is the one place both shapes are built; `near_query` is the
+2dsphere half of it, for a query you write by hand.
 
 **Don't call `#first` or `#last` on a `$near` criteria.** Mongoid sorts by
 `_id` when a criteria carries no sort of its own, and that replaces the
@@ -284,12 +304,14 @@ Place.geo_near(:location, [10, 20],
                query: { category: 'restaurant' }, # Optional: filter documents before geoNear
                limit: 10)
 
-# Iterate over results
-Place.geo_near(:location, [10, 20], spherical: true).each do |place|
-  # 'place.distance' will be available if distanceField was 'distance' (the default)
-  # or 'place.dist_calculated' if distanceField was 'dist.calculated'
-  puts "#{place.name} is #{place.distance || place.dist_calculated} meters away."
+# Iterate over results — HASHES, not documents. Nothing is instantiated:
+# $geoNear adds fields a model has no field for.
+Place.geo_near(:location, [10, 20], spherical: true).each do |doc|
+  puts "#{doc['name']} is #{doc['distance']} meters away."
 end
+
+# Want models? ask for them at the call site:
+Place.geo_near(:location, [10, 20]).map { |attrs| Place.instantiate(attrs) }
 ```
 
 Key features and options for `geo_near`:

data/lib/mongoid/geospatial/config/point.rb

@@ -10,8 +10,8 @@ module Mongoid
 
         def reset!
           # Now self.x and self.y refer to the public module accessors
-          self.x = Mongoid::Geospatial.lng_symbols
-          self.y = Mongoid::Geospatial.lat_symbols
+          self.x = Mongoid::Geospatial.lng_symbols.dup
+          self.y = Mongoid::Geospatial.lat_symbols.dup
         end
 
         # Initialize the configuration

data/lib/mongoid/geospatial/fields/point.rb

@@ -35,7 +35,9 @@ module Mongoid
       alias to_lng_lat mongoize
 
       def [](args)
-        mongoize[args]
+        raise ArgumentError, "Invalid point: #{inspect}" unless (pair = mongoize)
+
+        pair[args]
       end
 
       def each
@@ -49,7 +51,9 @@ module Mongoid
       # @return [Array] with [self, radius]
       #
       def radius(r = 1) # rubocop:disable Naming/MethodParameterName
-        [mongoize, r]
+        return nil unless (pair = mongoize)
+
+        [pair, r]
       end
 
       #
@@ -60,7 +64,7 @@ module Mongoid
       # @return [Array] with [self, radius / earth radius]
       #
       def radius_sphere(r = 1, unit = :km) # rubocop:disable Naming/MethodParameterName
-        radius r.to_f / Mongoid::Geospatial.earth_radius[unit]
+        radius r.to_f / Mongoid::Geospatial.earth_radius.fetch(unit)
       end
 
       #
@@ -135,7 +139,7 @@ module Mongoid
       #
       def distance(other, unit = :km) # rubocop:disable Metrics/AbcSize
         xy = other.is_a?(Point) ? [other.x, other.y] : self.class.mongoize(other)
-        raise ArgumentError, "Invalid point: #{other.inspect}" unless xy
+        raise ArgumentError, "Invalid point: #{other.inspect}" unless xy&.size == 2
 
         dlat = (xy[1] - y) * RAD_PER_DEG
         dlon = (xy[0] - x) * RAD_PER_DEG
@@ -195,7 +199,7 @@ module Mongoid
         def from_string(str)
           return nil if str.empty?
 
-          str.split(/,|\s/).reject(&:empty?).map(&:to_f)
+          from_array(str.split(/,|\s/).reject(&:empty?))
         end
 
         #
@@ -228,6 +232,9 @@ module Mongoid
         # @return (Array)
         #
         def from_hash(hsh)
+          coords = hsh[:coordinates] || hsh['coordinates']
+          return from_array(coords) if coords
+
           raise 'Hash must have at least 2 items' if hsh.size < 2
 
           [from_hash_x(hsh), from_hash_y(hsh)]

data/lib/mongoid/geospatial/geometry_field.rb

@@ -19,16 +19,10 @@ module Mongoid
       # @return [Array] containing 2 points
       #
       def bounding_box
-        max_x = -Float::MAX
-        min_x = Float::MAX
-        max_y = -Float::MAX
-        min_y = Float::MAX
-        each do |point|
-          max_y = point[1] if point[1] > max_y
-          min_y = point[1] if point[1] < min_y
-          max_x = point[0] if point[0] > max_x
-          min_x = point[0] if point[0] < min_x
-        end
+        return nil if empty?
+
+        min_x, max_x = map { |point| point[0] }.minmax
+        min_y, max_y = map { |point| point[1] }.minmax
         [[min_x, min_y], [max_x, max_y]]
       end
       alias bbox bounding_box
@@ -43,7 +37,9 @@ module Mongoid
       # @return [Array] containing 5 points
       #
       def geom_box
-        xl, yl = bounding_box
+        return nil unless (box = bounding_box)
+
+        xl, yl = box
         [xl, [xl[0], yl[1]], yl, [yl[0], xl[1]], xl]
       end
 
@@ -54,7 +50,9 @@ module Mongoid
       # @return [Array] containing 1 point [x,y]
       #
       def center_point
-        min, max = *bbox
+        return nil unless (box = bbox)
+
+        min, max = *box
         [(min[0] + max[0]) / 2.0, (min[1] + max[1]) / 2.0]
       end
       alias center center_point
@@ -66,7 +64,9 @@ module Mongoid
       # @return [Array]  [point, r] point and radius in mongoid format
       #
       def radius(r = 1) # rubocop:disable Naming/MethodParameterName
-        [center, r]
+        return nil unless (mid = center)
+
+        [mid, r]
       end
 
       #
@@ -78,7 +78,7 @@ module Mongoid
       # @return [Array]
       #
       def radius_sphere(r = 1, unit = :km) # rubocop:disable Naming/MethodParameterName
-        radius r.to_f / Mongoid::Geospatial.earth_radius[unit]
+        radius r.to_f / Mongoid::Geospatial.earth_radius.fetch(unit)
       end
 
       class << self

data/lib/mongoid/geospatial/helpers/spatial.rb

@@ -10,7 +10,6 @@ Mongoid::Fields.option :spatial do |model, field, _options|
 
   model.class_eval do
     spatial_fields << field.name.to_sym
-    spatial_fields_indexed << field.name.to_sym
 
     # Create 2D index
     spatial_index field.name

data/lib/mongoid/geospatial/helpers/sphere.rb

@@ -10,7 +10,6 @@ Mongoid::Fields.option :sphere do |model, field, _options|
 
   model.class_eval do
     spatial_fields << field.name.to_sym
-    spatial_fields_indexed << field.name.to_sym
 
     # Create 2Dsphere index
     spherical_index field.name

data/lib/mongoid/geospatial/version.rb

@@ -3,6 +3,6 @@
 module Mongoid
   # Mongoid Geospatial version
   module Geospatial
-    VERSION = '7.2.0'
+    VERSION = '7.3.1'
   end
 end

data/lib/mongoid/geospatial.rb

@@ -85,11 +85,39 @@ module Mongoid
     end
 
     #
-    # Selector for `$nearSphere` with a km cap. Metres on the wire.
+    # A cap Mongo can measure: a positive number of kilometres.
+    #
+    def self.km!(km) # rubocop:disable Naming/MethodParameterName
+      raise ArgumentError, "Invalid km: #{km.inspect}" unless km.is_a?(Numeric) && km.positive?
+
+      km
+    end
+
+    #
+    # `$nearSphere` value with a km cap, GeoJSON. Metres on the wire.
+    # This is the 2dsphere shape — see #near_selector for the other one.
     #
     def self.near_query(geom, km) # rubocop:disable Naming/MethodParameterName
       { '$geometry' => { 'type' => 'Point', 'coordinates' => mongoize_point!(geom) },
-        '$maxDistance' => km * 1_000 }
+        '$maxDistance' => km!(km) * 1_000 }
+    end
+
+    #
+    # The whole `{ field => ... }` selector for "within +km+", for either index.
+    #
+    # `$nearSphere` speaks two dialects and the index picks which:
+    #
+    #   2dsphere   { loc: { $nearSphere: { $geometry: {...}, $maxDistance: <m> } } }
+    #   2d         { loc: { $nearSphere: [x, y],             $maxDistance: <rad> } }
+    #
+    # Hand the wrong one over and the server answers `NoQueryExecutionPlans`,
+    # not a wrong count — so ask the field which it is before building.
+    #
+    def self.near_selector(field, geom, km, sphere: true) # rubocop:disable Naming/MethodParameterName
+      return { field => { '$nearSphere' => near_query(geom, km) } } if sphere
+
+      { field => { '$nearSphere' => mongoize_point!(geom),
+                   '$maxDistance' => km!(km) / EARTH_RADIUS_KM.to_f } }
     end
 
     # Methods applied to Document's class
@@ -101,7 +129,7 @@ module Mongoid
       # @param options [Hash] Additional options for the index.
       #
       def spatial_index(name, options = {})
-        spatial_fields_indexed << name
+        remember_indexed(name)
         index({ name => '2d' }, options)
       end
 
@@ -112,11 +140,20 @@ module Mongoid
       # @param options [Hash] Additional options for the index.
       #
       def spherical_index(name, options = {})
-        spatial_fields_indexed << name
+        remember_indexed(name)
         index({ name => '2dsphere' }, options)
       end
       alias sphere_index spherical_index
 
+      #
+      # One field, one entry, always a Symbol — a field may carry both a 2d
+      # and a 2dsphere index, and `spatial: true` calls this on its way in too.
+      #
+      def remember_indexed(name)
+        sym = name.to_sym
+        spatial_fields_indexed << sym unless spatial_fields_indexed.include?(sym)
+      end
+
       #
       # A Point on a 2dsphere index. Default name is `geom`.
       #
@@ -232,7 +269,7 @@ module Mongoid
       #
       # @param coordinates [Array, Mongoid::Geospatial::Point] The coordinates (e.g., [lon, lat])
       #   or a Point object to find documents near to.
-      # @param km [Numeric, nil] Optional cap in kilometres (`$maxDistance` in metres).
+      # @param km [Numeric, nil] Optional cap in kilometres.
       #
       # @return [Mongoid::Criteria] A criteria object for the query.
       #
@@ -240,33 +277,51 @@ module Mongoid
       #   Bar.nearby([10, 20])
       #   Alarm.nearby(my_point_object, km: 30)
       #
-      def nearby(coordinates, km: nil, **_opts) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Naming/MethodParameterName
-        if spatial_fields.empty?
-          raise "No spatial fields defined for #{name} to use with .nearby. " \
-                "Mark a field with 'spatial: true' or 'sphere: true'."
-        end
+      def nearby(coordinates, km: nil, field: nil) # rubocop:disable Naming/MethodParameterName
+        pin, sphere = spatial_field(field)
+        return criteria.where(Mongoid::Geospatial.near_selector(pin, coordinates, km, sphere: sphere)) if km
 
-        field_name_sym = spatial_fields.first.to_sym
-        field_definition = fields[field_name_sym.to_s]
-
-        raise "Could not find field definition for spatial field: #{field_name_sym}" unless field_definition
+        criteria.where(pin.send(sphere ? :near_sphere : :near) => coordinates)
+      end
 
-        if km
-          # GeoJSON `$maxDistance` is metres. `$near` on a 2d index is radians.
-          query = Mongoid::Geospatial.near_query(coordinates, km)
-          criteria.where(field_name_sym.near_sphere => query)
-        else
-          query_operator = field_definition.options[:sphere] ? :near_sphere : :near
-          criteria.where(field_name_sym.send(query_operator) => coordinates)
+      #
+      # The pin `.nearby`, `.within` and `.nearest` read, and whether it is on
+      # a sphere. Handed nothing, the first spatial field — a model with two
+      # pins (`geom :pick_up`, `geom :drop_up`) has to name the one it means.
+      #
+      # @return [Array] [field name as a Symbol, sphere?]
+      #
+      def spatial_field(field = nil)
+        sym = (field || spatial_fields.first)&.to_sym
+        unless sym && spatial_fields.include?(sym)
+          raise ArgumentError, "#{name} has no spatial field #{sym.inspect} — it has #{spatial_fields.inspect}. " \
+                               "Mark one with 'spatial: true' or 'sphere: true'."
         end
+
+        [sym, fields.fetch(sym.to_s).options[:sphere] ? true : false]
       end
 
       #
-      # Documents within +km+ of +geom+, nearest first.
-      # `$nearSphere` + `$maxDistance` in metres.
+      # Documents within +km+ of +geom+, nearest first. Spherical either way:
+      # the field's index decides the dialect, see .near_selector.
       #
-      def within(geom, km) # rubocop:disable Naming/MethodParameterName
-        nearby(geom, km: km)
+      def within(geom, km, field: nil) # rubocop:disable Naming/MethodParameterName
+        nearby(geom, km: Mongoid::Geospatial.km!(km), field: field)
+      end
+
+      #
+      # The single closest document within +km+, or nil.
+      #
+      #   `within(geom, km).first`   NOT the nearest one
+      #   `nearest(geom, km)`        the nearest one
+      #
+      # Mongoid's #first and #last sort by `_id` when the criteria carries no
+      # sort of its own (contextual/mongo.rb, `view.sort || { _id: 1 }`), and
+      # that _id sort replaces the distance order `$near` put there. It reads
+      # as working every time the closest document happens to be the oldest.
+      #
+      def nearest(geom, km, field: nil) # rubocop:disable Naming/MethodParameterName
+        within(geom, km, field: field).limit(1).to_a.first
       end
 
       # Performs a $geoNear aggregation pipeline stage to find documents near a point,
@@ -289,17 +344,20 @@ module Mongoid
       #     For spherical queries, specify distance in meters. For 2d queries, in the same units as coordinates.
       #   - `:minDistance` [Numeric] The minimum distance. (MongoDB 2.6+)
       #   - `:query` [Hash] Limits the results to the documents that match the query.
-      #   - `:limit` [Integer] The maximum number of documents to return (applied as a separate `$limit` pipeline stage).
-      #   - `:distanceMultiplier` [Numeric] A factor to multiply all distances returned by the query.
-      #   - `:includeLocs` [String] Specifies the name of the output field that identifies the location used to calculate the distance.
-      #     This is useful when the queried field contains multiple locations (e.g., an array of points) or complex GeoJSON
-      #     geometries (e.g., a Polygon), as it shows which specific point was used for the distance calculation.
-      #     Example: `includeLocs: 'matchedPoint'` would add a `matchedPoint` field to each output document.
-      #
-      # @return [Array<Mongoid::Document>] An array of instantiated Mongoid documents.
-      #   Each document will include its original fields plus any fields added by the `$geoNear` stage,
-      #   such as the field specified by `:distanceField` (e.g., `document.distance`) and `:includeLocs`.
-      #   These additional fields are accessible as dynamic attributes on the model instances.
+      #   - `:limit` [Integer] The maximum number of documents to return
+      #     (applied as a separate `$limit` pipeline stage).
+      #   - `:distanceMultiplier` [Numeric] A factor to multiply all distances by.
+      #   - `:includeLocs` [String] Output field naming WHICH location the distance
+      #     was measured to — the one that matters when the queried field holds
+      #     several points, or a Polygon. `includeLocs: 'matchedPoint'` adds a
+      #     `matchedPoint` field to each output document.
+      #
+      # @return [Mongo::Collection::View::Aggregation] The raw pipeline result — it
+      #   yields `BSON::Document` hashes, NOT model instances, so read a field with
+      #   `doc['name']` and the distance with `doc['distance']` (or whatever
+      #   `:distanceField` was set to). Nothing is instantiated: `$geoNear` adds fields
+      #   a document does not have, and a Point field comes back as a raw pair.
+      #   Need models? `.map { |attrs| Model.instantiate(attrs) }` at the call site.
       #
       # @raise [ArgumentError] If coordinates cannot be mongoized.
       #
@@ -312,9 +370,9 @@ module Mongoid
       #                  query: { category: 'restaurant' },
       #                  limit: 10)
       #
-      #   # Iterate over results
-      #   Place.geo_near(:location, [10, 20], spherical: true).each do |place|
-      #     puts "#{place.name} is #{place.distance} meters away." # Assumes distanceField is 'distance'
+      #   # Iterate over results — hashes, not documents
+      #   Place.geo_near(:location, [10, 20], spherical: true).each do |doc|
+      #     puts "#{doc['name']} is #{doc['distance']} meters away."
       #   end
       #
       def geo_near(field_name, coordinates, options = {})
@@ -363,15 +421,7 @@ module Mongoid
         # Add $limit stage if limit_value was provided
         pipeline << { '$limit' => limit_value.to_i } if limit_value
 
-        # Execute the aggregation pipeline
         collection.aggregate(pipeline)
-
-        # Don't instantiate results here.
-        # aggregated_results = collection.aggregate(pipeline)
-        # Map the raw Hash results from aggregation to Mongoid model instances.
-        # Mongoid's #instantiate method correctly handles creating model objects
-        # and assigning attributes, including dynamic ones like the distanceField.
-        # aggregated_results.map { |attrs| instantiate(attrs) }
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mongoid-geospatial
 version: !ruby/object:Gem::Version
-  version: 7.2.0
+  version: 7.3.1
 platform: ruby
 authors:
 - Ryan Ong
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: 7.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: 7.0.0
 description: Mongoid Extension that simplifies MongoDB casting and operations on spatial
   Ruby objects.
 email: