parse-stack-next 4.5.0

data/lib/parse/model/geojson.rb

@@ -0,0 +1,271 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "model"
+require_relative "geopoint"
+
+module Parse
+  # GeoJSON-native geometry wrappers for types that Parse Server's schema
+  # does NOT model directly but that MongoDB's `2dsphere` index supports
+  # natively. These classes are designed for callers that go through the
+  # mongo-direct surface (`Parse::MongoDB`) or Atlas Search, where stored
+  # geometry can be richer than the `GeoPoint` / `Polygon` types Parse
+  # Server exposes.
+  #
+  # **Axis order.** Unlike {Parse::GeoPoint} and {Parse::Polygon}, which
+  # store coordinates in Parse-native `[latitude, longitude]` order to
+  # match the REST wire format, every class under `Parse::GeoJSON` stores
+  # coordinates in GeoJSON-native `[longitude, latitude]` order. The
+  # namespace itself is the axis-order signal — pick the namespace based
+  # on which side of the boundary you're working on.
+  #
+  # **Storage.** These geometries live in `:object` Parse columns. Parse
+  # Server treats the value as an opaque hash on read and write; MongoDB
+  # will happily index it on a `2dsphere` index regardless of whether
+  # Parse Server's schema knows the type exists.
+  module GeoJSON
+    # Base class for GeoJSON geometry wrappers. Subclasses define `TYPE`
+    # and `#valid_coordinates?` and inherit the round-trip plumbing.
+    class Geometry < Parse::Model
+      # @return [Array] the raw coordinates array, in GeoJSON nesting and
+      #   `[longitude, latitude]` axis order. Shape varies by subclass.
+      attr_reader :coordinates
+
+      # @return [String] the GeoJSON `type` discriminator (`"Point"`,
+      #   `"LineString"`, `"Polygon"`, `"MultiPolygon"`, etc.).
+      def self.geojson_type
+        const_get(:TYPE)
+      end
+
+      def geojson_type
+        self.class.geojson_type
+      end
+
+      # The initializer accepts either a GeoJSON Hash (`{type:, coordinates:}`),
+      # a plain coordinates Array, or another instance of the same class.
+      def initialize(value = nil)
+        @coordinates = []
+        self.coordinates = value unless value.nil?
+      end
+
+      def coordinates=(value)
+        coords =
+          case value
+          when self.class
+            deep_copy_array(value.coordinates)
+          when Hash
+            hash = value.respond_to?(:symbolize_keys) ? value.symbolize_keys : value
+            type = hash[:type] || hash["type"]
+            if type && type.to_s != self.class.geojson_type
+              raise ArgumentError, "[#{self.class}] expected GeoJSON type " \
+                                   "#{self.class.geojson_type.inspect}, got #{type.inspect}."
+            end
+            normalize(hash[:coordinates] || hash["coordinates"] || [])
+          when Array
+            normalize(value)
+          else
+            raise ArgumentError, "[#{self.class}] cannot build from #{value.class}: " \
+                                 "expected GeoJSON Hash, coordinates Array, or another #{self.class}."
+          end
+        @coordinates = coords
+        validate!
+        @coordinates
+      end
+
+      # @return [Hash] the standard GeoJSON `{type:, coordinates:}` hash.
+      def to_geojson
+        { "type" => geojson_type, "coordinates" => deep_copy_array(@coordinates) }
+      end
+      alias_method :as_json, :to_geojson
+
+      # @return [String] the JSON form, suitable for direct shipment to
+      #   any GeoJSON-aware consumer.
+      def to_json(*args)
+        to_geojson.to_json(*args)
+      end
+
+      def ==(other)
+        return false unless other.is_a?(self.class)
+        @coordinates == other.coordinates
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@coordinates.inspect}>"
+      end
+
+      # @!visibility private
+      def initialize_copy(other)
+        super
+        @coordinates = deep_copy_array(other.coordinates)
+      end
+
+      # Build any GeoJSON geometry from its wire-format Hash. Dispatches to
+      # the matching subclass based on the `type` field.
+      # @example
+      #   Parse::GeoJSON::Geometry.from_geojson(line_string_hash) # => Parse::GeoJSON::LineString
+      # @return [Parse::GeoJSON::Geometry]
+      def self.from_geojson(hash)
+        raise ArgumentError, "[Parse::GeoJSON::Geometry] expected a Hash." unless hash.is_a?(Hash)
+        h = hash.respond_to?(:symbolize_keys) ? hash.symbolize_keys : hash
+        type = (h[:type] || h["type"]).to_s
+        klass = TYPE_REGISTRY[type]
+        raise ArgumentError, "[Parse::GeoJSON::Geometry] unsupported GeoJSON type #{type.inspect}." if klass.nil?
+        klass.new(h)
+      end
+
+      private
+
+      def deep_copy_array(arr)
+        arr.map { |entry| entry.is_a?(Array) ? deep_copy_array(entry) : entry }
+      end
+
+      def normalize(_value)
+        raise NotImplementedError, "subclass must implement #normalize"
+      end
+
+      def validate!
+        # subclasses may override
+      end
+    end
+
+    # `LineString` — an ordered sequence of `[longitude, latitude]` points
+    # describing a path. The most common applications are GPS tracks,
+    # delivery routes, road segments, and trail centerlines.
+    #
+    # GeoJSON requires ≥ 2 points; this class warns when the constraint
+    # is violated rather than raising, matching {Parse::GeoPoint} /
+    # {Parse::Polygon} validation style.
+    #
+    # @example
+    #   Parse::GeoJSON::LineString.new [[-122.4, 37.7], [-122.39, 37.78]]
+    class LineString < Geometry
+      TYPE = "LineString"
+      MIN_POINTS = 2
+
+      # @return [Array<Parse::GeoPoint>] the path as Parse::GeoPoint objects
+      #   (axis-swapped back to Parse's `[lat, lng]`).
+      def geo_points
+        @coordinates.map { |(lng, lat)| Parse::GeoPoint.new(lat, lng) }
+      end
+
+      private
+
+      def normalize(value)
+        raise ArgumentError, "[Parse::GeoJSON::LineString] coordinates must be an Array." unless value.is_a?(Array)
+        value.map do |pair|
+          case pair
+          when Parse::GeoPoint
+            finite_lnglat!(pair.longitude.to_f, pair.latitude.to_f)
+          when Array
+            unless pair.length == 2 && pair[0].is_a?(Numeric) && pair[1].is_a?(Numeric)
+              raise ArgumentError, "[Parse::GeoJSON::LineString] each coordinate must be a [lng, lat] numeric pair."
+            end
+            finite_lnglat!(pair[0].to_f, pair[1].to_f)
+          else
+            raise ArgumentError, "[Parse::GeoJSON::LineString] unsupported coordinate entry #{pair.inspect}."
+          end
+        end
+      end
+
+      # Reject NaN / Infinity at the door. `Float::NAN.is_a?(Numeric)`
+      # is true so the earlier type check is insufficient; persisting
+      # a line with NaN errors mid-pipeline at `2dsphere` index rebuild
+      # time.
+      def finite_lnglat!(lng, lat)
+        unless lng.finite? && lat.finite?
+          raise ArgumentError, "[Parse::GeoJSON::LineString] coordinates must be finite numerics; got [#{lng}, #{lat}]."
+        end
+        [lng, lat]
+      end
+
+      def validate!
+        return if @coordinates.empty?
+        if @coordinates.length < MIN_POINTS
+          warn "[Parse::GeoJSON::LineString] requires at least #{MIN_POINTS} points; got #{@coordinates.length}."
+        end
+      end
+    end
+
+    # `MultiPolygon` — an Array of Polygons, each Polygon an Array of
+    # linear rings, each ring an Array of `[lng, lat]` pairs. The canonical
+    # use case is administrative or territorial regions made up of
+    # disjoint pieces (Hawaii, Indonesia, multi-island service areas,
+    # postal-code clusters).
+    #
+    # GeoJSON nesting depth is 4: `coordinates[polygon][ring][point][lng_or_lat]`.
+    # Each ring must contain ≥ 4 points and be explicitly closed.
+    #
+    # @example
+    #   Parse::GeoJSON::MultiPolygon.new [
+    #     [[[ 0, 0], [ 1, 0], [ 1, 1], [ 0, 1], [ 0, 0]]],
+    #     [[[ 5, 5], [ 6, 5], [ 6, 6], [ 5, 6], [ 5, 5]]],
+    #   ]
+    class MultiPolygon < Geometry
+      TYPE = "MultiPolygon"
+      MIN_RING_POINTS = 4
+
+      # @return [Array<Parse::Polygon>] each member polygon as a
+      #   {Parse::Polygon} (with axis swap back to Parse's `[lat, lng]`).
+      #   Inner rings (holes) are dropped because {Parse::Polygon} does
+      #   not support them.
+      def polygons
+        @coordinates.map do |rings|
+          outer = rings.first
+          Parse::Polygon.new(outer.map { |(lng, lat)| [lat.to_f, lng.to_f] })
+        end
+      end
+
+      private
+
+      def normalize(value)
+        raise ArgumentError, "[Parse::GeoJSON::MultiPolygon] coordinates must be an Array." unless value.is_a?(Array)
+        value.map do |polygon|
+          unless polygon.is_a?(Array)
+            raise ArgumentError, "[Parse::GeoJSON::MultiPolygon] each polygon must be an Array of rings."
+          end
+          polygon.map do |ring|
+            unless ring.is_a?(Array)
+              raise ArgumentError, "[Parse::GeoJSON::MultiPolygon] each ring must be an Array of [lng, lat] pairs."
+            end
+            ring.map do |pair|
+              unless pair.is_a?(Array) && pair.length == 2 &&
+                     pair[0].is_a?(Numeric) && pair[1].is_a?(Numeric)
+                raise ArgumentError, "[Parse::GeoJSON::MultiPolygon] each coordinate must be a [lng, lat] numeric pair."
+              end
+              # Reject NaN / Infinity; see LineString#finite_lnglat!
+              # for the same rationale.
+              lng = pair[0].to_f
+              lat = pair[1].to_f
+              unless lng.finite? && lat.finite?
+                raise ArgumentError, "[Parse::GeoJSON::MultiPolygon] coordinates must be finite " \
+                                     "numerics; got [#{lng}, #{lat}]."
+              end
+              [lng, lat]
+            end
+          end
+        end
+      end
+
+      def validate!
+        @coordinates.each_with_index do |polygon, i|
+          polygon.each_with_index do |ring, j|
+            next if ring.empty?
+            if ring.length < MIN_RING_POINTS
+              warn "[Parse::GeoJSON::MultiPolygon] polygon[#{i}].ring[#{j}] has #{ring.length} points; " \
+                   "GeoJSON requires at least #{MIN_RING_POINTS}."
+            elsif ring.first != ring.last
+              warn "[Parse::GeoJSON::MultiPolygon] polygon[#{i}].ring[#{j}] is not closed (first != last)."
+            end
+          end
+        end
+      end
+    end
+
+    # Dispatch table for {Geometry.from_geojson}. Kept here at the end so
+    # subclasses are registered after their constants are defined.
+    Geometry::TYPE_REGISTRY = {
+      "LineString" => LineString,
+      "MultiPolygon" => MultiPolygon,
+    }.freeze
+  end
+end

data/lib/parse/model/geopoint.rb

@@ -0,0 +1,261 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Parse
+
+  # This class manages the GeoPoint data type that Parse provides to support
+  # geo-queries. To define a GeoPoint property, use the `:geopoint` data type.
+  # Please note that latitudes should not be between -90.0 and 90.0, and
+  # longitudes should be between -180.0 and 180.0.
+  # @example
+  #   class PlaceObject < Parse::Object
+  #     property :location, :geopoint
+  #   end
+  #
+  #   san_diego = Parse::GeoPoint.new(32.8233, -117.6542)
+  #   los_angeles = Parse::GeoPoint.new [34.0192341, -118.970792]
+  #   san_diego == los_angeles # false
+  #
+  #   place = PlaceObject.new
+  #   place.location = san_diego
+  #   place.save
+  #
+  class GeoPoint < Model
+    # The default attributes in a Parse GeoPoint hash.
+    ATTRIBUTES = { __type: :string, latitude: :float, longitude: :float }.freeze
+
+    # @return [Float] latitude value between -90.0 and 90.0
+    attr_reader :latitude
+    # @return [Float] longitude value between -180.0 and 180.0
+    attr_reader :longitude
+    # The key field for latitude
+    FIELD_LAT = "latitude".freeze
+    # The key field for longitude
+    FIELD_LNG = "longitude".freeze
+
+    # The minimum latitude value.
+    LAT_MIN = -90.0
+    # The maximum latitude value.
+    LAT_MAX = 90.0
+    # The minimum longitude value.
+    LNG_MIN = -180.0
+    # The maximum longitude value.
+    LNG_MAX = 180.0
+
+    alias_method :lat, :latitude
+    alias_method :lng, :longitude
+    # @return [Model::TYPE_GEOPOINT]
+    def self.parse_class; TYPE_GEOPOINT; end
+    # @return [Model::TYPE_GEOPOINT]
+    def parse_class; self.class.parse_class; end
+
+    alias_method :__type, :parse_class
+
+    # The initializer can create a GeoPoint with a hash, array or values.
+    # @example
+    #  san_diego = Parse::GeoPoint.new(32.8233, -117.6542)
+    #  san_diego = Parse::GeoPoint.new [32.8233, -117.6542]
+    #  san_diego = Parse::GeoPoint.new { latitude: 32.8233, longitude: -117.6542}
+    #
+    # @param latitude [Numeric] The latitude value between LAT_MIN and LAT_MAX.
+    # @param longitude [Numeric] The longitude value between LNG_MIN and LNG_MAX.
+    def initialize(latitude = nil, longitude = nil)
+      @latitude = @longitude = 0.0
+      if latitude.is_a?(Hash) || latitude.is_a?(Array)
+        self.attributes = latitude
+      elsif latitude.is_a?(Numeric) && longitude.is_a?(Numeric)
+        @latitude = latitude
+        @longitude = longitude
+      elsif latitude.is_a?(GeoPoint)
+        @latitude = latitude.latitude
+        @longitude = latitude.longitude
+      end
+
+      _validate_point
+    end
+
+    # @!visibility private
+    def _validate_point
+      unless @latitude.nil? || @latitude.between?(LAT_MIN, LAT_MAX)
+        warn "[Parse::GeoPoint] Latitude (#{@latitude}) is not between #{LAT_MIN}, #{LAT_MAX}!"
+        warn "Attempting to use GeoPoint’s with latitudes outside these ranges will raise an exception in a future release."
+      end
+
+      unless @longitude.nil? || @longitude.between?(LNG_MIN, LNG_MAX)
+        warn "[Parse::GeoPoint] Longitude (#{@longitude}) is not between #{LNG_MIN}, #{LNG_MAX}!"
+        warn "Attempting to use GeoPoint’s with longitude outside these ranges will raise an exception in a future release."
+      end
+    end
+
+    # @return [Hash] attributes for a Parse GeoPoint.
+    def attributes
+      ATTRIBUTES
+    end
+
+    # Helper method for performing geo-queries with radial miles constraints
+    # @return [Array] containing [lat,lng,miles]
+    def max_miles(m)
+      m = 0 if m.nil?
+      [@latitude, @longitude, m]
+    end
+
+    # Helper method for performing geo-queries with a radial kilometer
+    # constraint. Used with `:field.near => gp.max_kilometers(N)` to compile
+    # a `$nearSphere` + `$maxDistanceInKilometers` query against Parse Server.
+    # @return [Array] containing `[lat, lng, kilometers, :km]`
+    def max_kilometers(km)
+      km = 0 if km.nil?
+      [@latitude, @longitude, km, :km]
+    end
+    alias_method :max_km, :max_kilometers
+
+    # Helper method for performing geo-queries with a radial radians
+    # constraint. Used with `:field.near => gp.max_radians(R)` to compile
+    # a `$nearSphere` + `$maxDistance` query against Parse Server (raw
+    # `$maxDistance` is measured in radians). Convert from miles/km by
+    # dividing by mean-Earth-radius (~3958.8 miles or ~6371 km).
+    # @return [Array] containing `[lat, lng, radians, :radians]`
+    def max_radians(rad)
+      rad = 0 if rad.nil?
+      [@latitude, @longitude, rad, :radians]
+    end
+
+    def latitude=(l)
+      @latitude = l
+      _validate_point
+    end
+
+    def longitude=(l)
+      @longitude = l
+      _validate_point
+    end
+
+    # Setting lat and lng for an GeoPoint can be done using a hash with the attributes set
+    # or with an array of two items where the first is the lat and the second is the lng (ex. [32.22,-118.81])
+    def attributes=(h)
+      if h.is_a?(Hash)
+        h = h.symbolize_keys
+        @latitude = h[:latitude].to_f || h[:lat].to_f || @latitude
+        @longitude = h[:longitude].to_f || h[:lng].to_f || @longitude
+      elsif h.is_a?(Array) && h.count == 2
+        @latitude = h.first.to_f
+        @longitude = h.last.to_f
+      end
+      _validate_point
+    end
+
+    # @return [Boolean] true if two geopoints are equal based on lat and lng.
+    def ==(g)
+      return false unless g.is_a?(GeoPoint)
+      @latitude == g.latitude && @longitude == g.longitude
+    end
+
+    # Helper method for reducing the precision of a geopoint.
+    # @param precision [Integer] The number of floating digits to keep.
+    # @return [GeoPoint] Reduces the precision of a geopoint.
+    def estimated(precision = 2)
+      Parse::GeoPoint.new(@latitude.to_f.round(precision), @longitude.round(precision))
+    end
+
+    # Returns a tuple containing latitude and longitude
+    # @return [Array]
+    def to_a
+      [@latitude, @longitude]
+    end
+
+    # GeoJSON (RFC 7946) representation of this point. GeoJSON requires
+    # `[longitude, latitude]` axis order — the inverse of Parse's wire
+    # format — so this method performs the swap. Useful when handing the
+    # value to Leaflet/Mapbox/PostGIS, or when constructing literals for
+    # MongoDB-direct geo queries (which use GeoJSON internally).
+    # @example
+    #   geopoint.to_geojson
+    #   # => {"type" => "Point", "coordinates" => [-117.6542, 32.8233]}
+    # @return [Hash] a GeoJSON `Point` geometry object.
+    def to_geojson
+      { "type" => "Point", "coordinates" => [@longitude, @latitude] }
+    end
+
+    # Build a {Parse::GeoPoint} from a GeoJSON `Point` geometry object.
+    # Accepts either symbol or string keys and the standard
+    # `[longitude, latitude]` axis order; performs the swap to Parse's
+    # `[latitude, longitude]` internal storage.
+    # @example
+    #   Parse::GeoPoint.from_geojson("type" => "Point", "coordinates" => [-117.6542, 32.8233])
+    # @param geojson [Hash] a GeoJSON Point geometry object.
+    # @return [Parse::GeoPoint]
+    # @raise [ArgumentError] if the input is not a valid GeoJSON Point.
+    def self.from_geojson(geojson)
+      raise ArgumentError, "[Parse::GeoPoint] from_geojson expects a Hash." unless geojson.is_a?(Hash)
+      hash = geojson.respond_to?(:symbolize_keys) ? geojson.symbolize_keys : geojson
+      type = hash[:type] || hash["type"]
+      coords = hash[:coordinates] || hash["coordinates"]
+      # Mirror Parse::Polygon.from_geojson: require both coordinates to
+      # be finite Numerics. Without this check, non-numeric entries
+      # (`"evil"`, `{"$where": "..."}`, `nil`) silently coerce to 0.0
+      # via `.to_f`, producing a null-island point that matches
+      # ACL-relevant proximity queries unintentionally. NaN / Infinity
+      # similarly produce silent geo bugs and 2dsphere index errors.
+      unless type.to_s == "Point" && coords.is_a?(Array) && coords.length == 2 &&
+             coords[0].is_a?(Numeric) && coords[1].is_a?(Numeric) &&
+             coords[0].finite? && coords[1].finite?
+        raise ArgumentError, "[Parse::GeoPoint] from_geojson expects a GeoJSON Point with " \
+                             "two finite numeric coordinates."
+      end
+      Parse::GeoPoint.new(coords[1].to_f, coords[0].to_f)
+    end
+
+    # @!visibility private
+    def inspect
+      "#<GeoPoint [#{@latitude},#{@longitude}]>"
+    end
+
+    # Calculate the distance in miles to another GeoPoint using Haversine.
+    # You may also call this method with a latitude and longitude.
+    # @example
+    #   point.distance_in_miles(geotpoint)
+    #   point.distance_in_miles(lat, lng)
+    #
+    # @param geopoint [GeoPoint]
+    # @param lng [Float] Longitude assuming that the first parameter
+    # is longitude instead of a GeoPoint.
+    # @return [Float] number of miles between geopoints.
+    # @see #distance_in_km
+    def distance_in_miles(geopoint, lng = nil)
+      distance_in_km(geopoint, lng) * 0.621371
+    end
+
+    # Calculate the distance in kilometers to another GeoPoint using Haversine
+    # method. You may also call this method with a latitude and longitude.
+    # @example
+    #   point.distance_in_km(geotpoint)
+    #   point.distance_in_km(lat, lng)
+    #
+    # @param geopoint [GeoPoint]
+    # @param lng [Float] Longitude assuming that the first parameter is a latitude instead of a GeoPoint.
+    # @return [Float] number of miles between geopoints.
+    # @see #distance_in_miles
+    def distance_in_km(geopoint, lng = nil)
+      unless geopoint.is_a?(Parse::GeoPoint)
+        geopoint = Parse::GeoPoint.new(geopoint, lng)
+      end
+
+      dtor = Math::PI / 180
+      r = 6378.14
+      r_lat1 = self.latitude * dtor
+      r_lng1 = self.longitude * dtor
+      r_lat2 = geopoint.latitude * dtor
+      r_lng2 = geopoint.longitude * dtor
+
+      delta_lat = r_lat1 - r_lat2
+      delta_lng = r_lng1 - r_lng2
+
+      a = (Math::sin(delta_lat / 2.0) ** 2).to_f + (Math::cos(r_lat1) * Math::cos(r_lat2) * (Math::sin(delta_lng / 2.0) ** 2))
+      c = 2.0 * Math::atan2(Math::sqrt(a), Math::sqrt(1.0 - a))
+      d = r * c
+      d
+    end
+  end
+end