mongoid-geospatial 7.1.0 → 7.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88d807a8e7011846e353f18fc6812fb55e578f371464c202fa726976c7fec6e6
-  data.tar.gz: 32f5124231bfe558a9a591520c90dda408f76995faa2030e67c39bee1e9f7b23
+  metadata.gz: 59aa6c29ce76d2edc2c6ba8b30492c713e552b31ad728abe8a43743464576681
+  data.tar.gz: d62f1d2814b6e0faa93f1d5d2fc16371d30d37e97d72e5eada5a647bae6e9aab
 SHA512:
-  metadata.gz: f8beb1650724d7b54d7a2a35d2376597144d9290360f2571da28681ef11d3e3e0792bf562f0c904f762b0abaf09d43b9f8c8f1747cb4d7753a5f187a6c6d04c5
-  data.tar.gz: b457c28c88ab87968e76eeb00afca6e376e37cf2432df230fc88260ab44b9984c9cd11708deba53eb19fa4a19d27175d63042c5b142762707fe3bd1019107652
+  metadata.gz: fa331e0ce250edf23904a8390442a6cdf831f98d89110f3e5c803b801f80660087444839b1607ac868a31b9aa2dfdeb17d0910294dc83727a281e0fa875b3eff
+  data.tar.gz: 1c0b907249ce2ac189bb8f00551dede0b15c59d9c72f218de23c4c746f370060953d065c77c79cb61c209a81607003cfcfdea197ca6893dcc81521b9a5f258c3

data/README.md

@@ -46,6 +46,14 @@ class Place
 end
 ```
 
+A pin named `geom` on a 2dsphere index is one include:
+
+```ruby
+include Mongoid::Geospatial::Geom   # field :geom, type: Point, sphere: true
+# or a named one:
+geom :pick_up
+```
+
 Generate indexes on MongoDB via rake:
 
 ```
@@ -94,6 +102,15 @@ If you need a hash
 cafe.location.to_hsh   # => { x: -74.026667, y: 40.703056 }
 ```
 
+Commonly used
+
+```ruby
+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
+```
+
 If you are using GeoRuby or RGeo
 
 ```ruby
@@ -108,7 +125,7 @@ This lib uses #x and #y everywhere.
 It's shorter than lat or lng or another variation that also confuses.
 A point is a 2D mathematical notation, longitude/latitude is when you use that notation to map an sphere. In other words: all longitudes are 'xs' where not all 'xs' are longitudes.
 
-Distance and other geometrical calculations are delegated to the external library of your choice. More info about using RGeo or GeoRuby below. Some built in helpers for mongoid queries:
+Distance is `Point#distance` (haversine, km). Projections and heavier geometry still go to RGeo or GeoRuby. Some built in helpers for mongoid queries:
 
 ```ruby
 # Returns middle point + radius
@@ -215,7 +232,41 @@ Bar.near_sphere(location: person.house)
 Bar.where(:location.near_sphere => person.house)
 ```
 
-### nearby
+### nearby / within
+
+```ruby
+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` 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
+distance order Mongo put there. Walk the criteria instead — `.to_a.first` —
+or use `geo_near`, which returns the distance as a field you can sort on.
 
 You can add a `spatial_scope` on your models. So you can query:
 
@@ -253,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`:
@@ -282,6 +335,20 @@ Bar.within_polygon(location: [[[x,y],...[x,y]]])
 Bar.within_polygon(location: street.bbox)
 ```
 
+- within_circle / within_spherical_circle
+
+Mongoid ships `within_polygon` and `within_box` and stopped there; this gem
+registers the two circle shapes, which is what `radius` and `radius_sphere`
+have been building arguments for all along.
+
+```ruby
+Bar.where(:location.within_spherical_circle => cafe.location.radius_sphere(5, :km))
+Bar.where(:location.within_circle => cafe.location.radius(0.05))  # degrees, flat
+```
+
+`$centerSphere` reads radians (`radius_sphere` hands it those); `$center`
+reads the coordinate system's own units — degrees on a legacy pair.
+
 - intersects_line
 - intersects_point
 - intersects_polygon
@@ -295,7 +362,7 @@ external library corresponding object.
 
 ### Use RGeo?
 
-https://github.com/dazuma/rgeo
+<https://github.com/dazuma/rgeo>
 
 RGeo is a Ruby wrapper for Proj/GEOS.
 It's perfect when you need to work with complex calculations and projections.
@@ -303,7 +370,7 @@ It'll require more stuff installed to compile/work.
 
 ### Use GeoRuby?
 
-https://github.com/nofxx/georuby
+<https://github.com/nofxx/georuby>
 
 GeoRuby is a pure Ruby Geometry Library.
 It's perfect if you want simple calculations and/or keep your stack in pure ruby.

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

@@ -4,9 +4,16 @@ module Mongoid
   module Geospatial
     # Point
     #
-    class Point
+    class Point # rubocop:disable Metrics/ClassLength
       include Enumerable
+
       attr_accessor :x, :y, :z
+      alias lng x
+      alias lon x
+      alias lat y
+      alias lng= x=
+      alias lon= x=
+      alias lat= y=
 
       def initialize(lon, lat, alt = nil)
         @x = lon
@@ -25,9 +32,12 @@ module Mongoid
       end
       alias to_a mongoize
       alias to_xy mongoize
+      alias to_lng_lat mongoize
 
       def [](args)
-        mongoize[args]
+        raise ArgumentError, "Invalid point: #{inspect}" unless (pair = mongoize)
+
+        pair[args]
       end
 
       def each
@@ -35,24 +45,15 @@ module Mongoid
         yield y
       end
 
-      #
-      # Point representation as a Hash
-      # Optional param: custom keys.
-      #
-      # @return [Hash] with { lng_key => x, lat_key => y }
-      #
-      def to_hsh(xkey = :x, ykey = :y)
-        { xkey => x, ykey => y }
-      end
-      alias to_hash to_hsh
-
       #
       # Helper for [self, radius]
       #
       # @return [Array] with [self, radius]
       #
       def radius(r = 1) # rubocop:disable Naming/MethodParameterName
-        [mongoize, r]
+        return nil unless (pair = mongoize)
+
+        [pair, r]
       end
 
       #
@@ -63,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
 
       #
@@ -88,6 +89,26 @@ module Mongoid
         "#{x}, #{y}"
       end
 
+      #
+      # Point representation as a Hash
+      # Optional param: custom keys.
+      #
+      # @return [Hash] with { lng_key => x, lat_key => y }
+      #
+      def to_hsh(xkey = :x, ykey = :y)
+        { xkey => x, ykey => y }
+      end
+      alias to_hash to_hsh
+
+      #
+      # Point representation more commonly used
+      # Latitude, Longitude
+      #
+      # @return [Hash] with { latitude: y, longitude: x }
+      def to_lat_lon
+        { latitude: y, longitude: x }
+      end
+
       #
       # Point definition as GeoJSON
       #
@@ -113,32 +134,21 @@ module Mongoid
       end
 
       #
-      # Distance calculation methods. Thinking about not using it
-      # One needs to choose and external lib. GeoRuby or RGeo
-      #
-      # Return the distance between the 2D points (ie taking care
-      # only of the x and y coordinates), assuming the points are
-      # in projected coordinates. Euclidian distance in whatever
-      # unit the x and y ordinates are.
-      # def euclidian_distance(point)
-      #   Math.sqrt((point.x - x)**2 + (point.y - y)**2)
-      # end
-
-      # # Spherical distance in meters, using 'Haversine' formula.
-      # # with a radius of 6471000m
-      # # Assumes x is the lon and y the lat, in degrees (Changed
-      # in version 1.1).
-      # # The user has to make sure using this distance makes sense
-      # (ie she should be in latlon coordinates)
-      # def spherical_distance(point,r=6370997.0)
-      #   dlat = (point.lat - lat) * DEG2RAD / 2
-      #   dlon = (point.lon - lon) * DEG2RAD / 2
-
-      #   a = Math.sin(dlat)**2 + Math.cos(lat * DEG2RAD) *
-      #         Math.cos(point.lat * DEG2RAD) * Math.sin(dlon)**2
-      #   c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a))
-      #   r * c
-      # end
+      # Crow-flies distance. Haversine, Mongo's earth radius (6371 km).
+      # RGeo/GeoRuby still win for projections; this is ETA and "how far".
+      #
+      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&.size == 2
+
+        dlat = (xy[1] - y) * RAD_PER_DEG
+        dlon = (xy[0] - x) * RAD_PER_DEG
+        a = (Math.sin(dlat / 2)**2) +
+            (Math.cos(y * RAD_PER_DEG) * Math.cos(xy[1] * RAD_PER_DEG) *
+             (Math.sin(dlon / 2)**2))
+        c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+        Mongoid::Geospatial.earth_radius[unit] * c
+      end
 
       class << self
         #
@@ -189,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
 
         #
@@ -222,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/geom.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Geospatial
+    #
+    # The pin, named `geom`, on a 2dsphere index.
+    #
+    module Geom
+      extend ActiveSupport::Concern
+
+      included do
+        include Mongoid::Geospatial
+
+        geom
+      end
+
+      def located?
+        geom.present?
+      end
+    end
+  end
+end

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/keys.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+#
+# `$geoWithin` with a circle. Mongoid ships `within_polygon` and `within_box`
+# and stopped there — the two circle shapes left with Origin, and `Point#radius`
+# / `#radius_sphere` have been building their argument ever since.
+#
+#   Bar.where(:location.within_circle => elvis.location.radius(0.05))
+#   Bar.where(:location.within_spherical_circle => elvis.location.radius_sphere(5, :km))
+#
+# `$center` reads its radius in the coordinate system's own units (degrees, for
+# a legacy pair); `$centerSphere` reads radians, which is what `radius_sphere`
+# returns. Guarded: if Mongoid ever registers these, its own wins.
+#
+%i[within_circle within_spherical_circle].each do |name|
+  next if Symbol.method_defined?(name)
+
+  operator = name == :within_circle ? '$center' : '$centerSphere'
+  Symbol.add_key(name, :override, '$geoWithin', operator)
+end

data/lib/mongoid/geospatial/version.rb

@@ -3,6 +3,6 @@
 module Mongoid
   # Mongoid Geospatial version
   module Geospatial
-    VERSION = '7.1.0'
+    VERSION = '7.3.0'
   end
 end

data/lib/mongoid/geospatial.rb

@@ -5,6 +5,8 @@ require 'active_support/concern' # Explicitly require for `extend ActiveSupport:
 require 'mongoid/geospatial/helpers/spatial'
 require 'mongoid/geospatial/helpers/sphere'
 require 'mongoid/geospatial/helpers/delegate'
+require 'mongoid/geospatial/helpers/geom'
+require 'mongoid/geospatial/keys'
 
 module Mongoid
   #
@@ -69,6 +71,55 @@ module Mongoid
       require 'mongoid/geospatial/wrappers/georuby'
     end
 
+    #
+    # A [lng, lat] pair, or nothing. `Point.mongoize` is lenient — it reads
+    # "nowhere" as [0.0] — and a half pair is a query Mongo cannot answer.
+    #
+    def self.mongoize_point!(geom)
+      coords = Point.mongoize(geom)
+      unless coords.is_a?(Array) && coords.size == 2 && coords.all?(Numeric)
+        raise ArgumentError, "Invalid coordinates: #{geom.inspect}"
+      end
+
+      coords
+    end
+
+    #
+    # 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!(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
     module ClassMethods
       #
@@ -78,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
 
@@ -89,9 +140,26 @@ 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`.
+      #
+      def geom(name = :geom)
+        field name, type: Point, sphere: true
+      end
 
       #
       # # Queries
@@ -201,28 +269,59 @@ module Mongoid
       #
       # @param coordinates [Array, Mongoid::Geospatial::Point] The coordinates (e.g., [lon, lat])
       #   or a Point object to find documents near to.
-      # @param _options [Hash] Optional hash for future extensions (currently unused).
+      # @param km [Numeric, nil] Optional cap in kilometres.
       #
       # @return [Mongoid::Criteria] A criteria object for the query.
       #
       # Example:
       #   Bar.nearby([10, 20])
-      #   Alarm.nearby(my_point_object)
+      #   Alarm.nearby(my_point_object, km: 30)
       #
-      def nearby(coordinates, _options = {})
-        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]
+        criteria.where(pin.send(sphere ? :near_sphere : :near) => coordinates)
+      end
 
-        raise "Could not find field definition for spatial field: #{field_name_sym}" unless field_definition
+      #
+      # 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
 
-        query_operator = field_definition.options[:sphere] ? :near_sphere : :near
+        [sym, fields.fetch(sym.to_s).options[:sphere] ? true : false]
+      end
 
-        criteria.where(field_name_sym.send(query_operator) => coordinates)
+      #
+      # Documents within +km+ of +geom+, nearest first. Spherical either way:
+      # the field's index decides the dialect, see .near_selector.
+      #
+      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,
@@ -252,10 +351,12 @@ module Mongoid
       #     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.
+      # @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.
       #
@@ -268,20 +369,26 @@ 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 = {})
-        mongoized_coords = Mongoid::Geospatial::Point.mongoize(coordinates)
-
-        raise ArgumentError, "Invalid coordinates provided: #{coordinates.inspect}" unless mongoized_coords
+        mongoized_coords = Mongoid::Geospatial.mongoize_point!(coordinates)
 
         # User-provided options. Work with a copy.
         user_options = options.dup
         limit_value = user_options.delete(:limit) # Handled by a separate pipeline stage
 
+        # `km:` is metres on the wire, and metres only holds for a GeoJSON
+        # `near` on a sphere. A legacy pair would read `maxDistance` in radians.
+        if (km = user_options.delete(:km))
+          user_options[:maxDistance] = km.to_f * 1_000
+          user_options[:spherical] = true
+          mongoized_coords = { 'type' => 'Point', 'coordinates' => mongoized_coords }
+        end
+
         # Core $geoNear parameters derived from method arguments, these are not overrideable by user_options.
         geo_near_core_params = {
           key: field_name.to_s,
@@ -297,10 +404,8 @@ module Mongoid
         # Merge user options over defaults, then ensure core parameters are set.
         geo_near_stage_options = geo_near_defaultable_params.merge(user_options).merge(geo_near_core_params)
 
-        # Ensure :spherical is a strict boolean (true/false).
-        # If user_options provided :spherical, it's already set. If not, the default is used.
-        # This line ensures the final value is strictly true or false, not just truthy/falsy.
-        geo_near_stage_options[:spherical] = !geo_near_stage_options[:spherical].nil?
+        # $geoNear wants a strict boolean, and honours the caller's choice.
+        geo_near_stage_options[:spherical] = geo_near_stage_options[:spherical] ? true : false
 
         # Note on performance:
         # $geoNear is an aggregation pipeline stage. For simple proximity queries,
@@ -315,15 +420,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.1.0
+  version: 7.3.0
 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:
@@ -45,8 +45,10 @@ files:
 - lib/mongoid/geospatial/fields/polygon.rb
 - lib/mongoid/geospatial/geometry_field.rb
 - lib/mongoid/geospatial/helpers/delegate.rb
+- lib/mongoid/geospatial/helpers/geom.rb
 - lib/mongoid/geospatial/helpers/spatial.rb
 - lib/mongoid/geospatial/helpers/sphere.rb
+- lib/mongoid/geospatial/keys.rb
 - lib/mongoid/geospatial/version.rb
 - lib/mongoid/geospatial/wrappers/georuby.rb
 - lib/mongoid/geospatial/wrappers/rgeo.rb