parse-stack 1.5.1 → 1.5.2

data/lib/parse/model/core/schema.rb

@@ -2,10 +2,9 @@
 # frozen_string_literal: true
 
 require_relative "properties"
-# This class adds methods to Parse::Objects in order to create a JSON Parse schema
-# in order to support table creation and table alterations.
-module Parse
 
+module Parse
+  # Upgrade all
   def self.auto_upgrade!
     klassModels = Parse::Object.descendants
     klassModels.sort_by { |c| c.parse_class }.each do |klass|

data/lib/parse/model/date.rb

@@ -13,38 +13,42 @@ require 'active_support/core_ext/time/calculations'
 require 'active_model_serializers'
 require_relative 'model'
 
-# Parse has a specific date format. One of the supported types is a date string in
-# ISO 8601 format (including milliseconds). The other is a hash object that contains
-# the similar information. When sending data to Parse, we need to use the hash object,
-# but when receiving data from Parse, we may either get the string version or the hash version.
-# To make things easier to use in ruby, th Parse::Date class inherits from the DateTime class.
-# This will allow us to use all the great ActiveSupport methods for date (ex. 3.days.ago) while
-# providing our own encoding for sending to Parse.
 module Parse
+  # This class manages dates in the special JSON format it requires for
+  # properties of type _:date_. One important note with dates, is that 'created_at' and 'updated_at'
+  # columns do not follow this convention all the time. Depending on the
+  # Cloud Code SDK, they can be the Parse ISO hash date format or the `iso8601`
+  # string format. By default, these are serialized as `iso8601` when sent as
+  # responses to Parse for backwards compatibility with some clients. To use
+  # the Parse ISO hash format for these fields instead, set
+  # `Parse::Object.disable_serialized_string_date = true`.
   class Date < ::DateTime
     ATTRIBUTES = {  __type: :string, iso: :string }.freeze
     include ::ActiveModel::Model
     include ::ActiveModel::Serializers::JSON
+
+    # @return [Parse::Model::TYPE_DATE]
     def self.parse_class; Parse::Model::TYPE_DATE; end;
+    # @return [Parse::Model::TYPE_DATE]
     def parse_class; self.class.parse_class; end;
     alias_method :__type, :parse_class
 
-    # called when encoding to JSON.
+    # @return [Hash]
     def attributes
       ATTRIBUTES
     end
 
-    # this method is defined because it is used by JSON encoding
+    # @return [String] the ISO8601 time string including milliseconds
     def iso
-      to_time.utc.iso8601(3) #include milliseconds
+      to_time.utc.iso8601(3)
     end
 
   end
 end
 
-# To enable conversion of other date class objects, we will add a mixin to turn
-# Time and DateTime objects to Parse::Date objects
+
 class Time
+  # @return [Parse::Date] Converts object to Parse::Date
   def parse_date
     Parse::Date.parse iso8601(3)
   end
@@ -52,6 +56,7 @@ class Time
 end
 
 class DateTime
+  # @return [Parse::Date] Converts object to Parse::Date
   def parse_date
     Parse::Date.parse iso8601(3)
   end
@@ -59,6 +64,7 @@ end
 
 module ActiveSupport
   class TimeWithZone
+    # @return [Parse::Date] Converts object to Parse::Date
     def parse_date
       Parse::Date.parse iso8601(3)
     end

data/lib/parse/model/file.rb

@@ -5,30 +5,61 @@ require 'active_support'
 require 'active_support/core_ext/object'
 require_relative "model"
 require 'open-uri'
-# Parse File objects are the only non Parse::Object subclass that has a save method.
-# In general, a Parse File needs content and a specific mime-type to be created. When it is saved, it
-# is sent to AWS/S3 to be saved (by Parse), and the result is a new URL pointing to that file.
-# This however is return as a type of File pointer object (hash format)
-# It only has two fields, the absolute URL of the file and the basename of the file.
-# The contents and mime_type are only present when creating a new file locally and are not
-# stored as part of the parse pointer.
-module Parse
 
+module Parse
+    # This class represents a Parse file pointer. `Parse::File` has helper
+    # methods to upload Parse files directly to Parse and manage file
+    # associations with your classes.
+    # @example
+    #  file = File.open("file_path.jpg")
+    #  contents = file.read
+    #  file = Parse::File.new("myimage.jpg", contents , "image/jpeg")
+    #  file.saved? # => false
+    #  file.save
+    #
+    #  file.url # https://files.parsetfss.com/....
+    #
+    #  # or create and upload a remote file (auto-detected mime type)
+    #  file = Parse::File.create(some_url)
+    #
+    #
+    # @note The default MIME type for all files is _image/jpeg_. This can be default
+    #       can be changed by setting a value to `Parse::File.default_mime_type`.
     class File < Model
       ATTRIBUTES = {  __type: :string, name: :string, url: :string }.freeze
-      attr_accessor :name, :url
-      attr_accessor :contents, :mime_type
+      # @return [String] the name of the file including extension (if any)
+      attr_accessor :name
+      # @return [String] the url resource of the file.
+      attr_accessor :url
+
+      # You may set the contents of the file.
+      attr_accessor :contents
+
+      # @return [String] the mime-type of the file whe
+      attr_accessor :mime_type
+      # @return [Model::TYPE_FILE]
       def self.parse_class; TYPE_FILE; end;
+      # @return [Model::TYPE_FILE]
       def parse_class; self.class.parse_class; end;
       alias_method :__type, :parse_class
       FIELD_NAME = "name"
       FIELD_URL = "url"
       class << self
+
         attr_accessor :default_mime_type
 
+        attr_accessor :force_ssl
+
+        # @return [String] The default mime type for created instances. Default: _'image/jpeg'_
         def default_mime_type
           @default_mime_type ||= "image/jpeg"
         end
+
+        # @return [Boolean] When set to true, it will make all calls to File#url
+        def force_ssl
+          @force_ssl ||= false
+        end
+
       end
       # The initializer to create a new file supports different inputs.
       # If the first paramter is a string which starts with 'http', we then download
@@ -36,6 +67,9 @@ module Parse
       # If the first parameter is a hash, we assume it might be the Parse File hash format which contains url and name fields only.
       # If the first paramter is a Parse::File, then we copy fields over
       # Otherwise, creating a new file requires a name, the actual contents (usually from a File.open("local.jpg").read ) and the mime-type
+      # @param name [String]
+      # @param contents [Object]
+      # @param mime_type [String] Default see default_mime_type
       def initialize(name, contents = nil, mime_type = nil)
         mime_type ||= Parse::File.default_mime_type
 
@@ -65,6 +99,8 @@ module Parse
       end
 
       # This creates a new Parse File Object with from a URL, saves it and returns it
+      # @param url [String] A url which will be used to create the file and automatically save it.
+      # @return [Parse::File] A newly saved file based on contents of _url_
       def self.create(url)
         url = url.url if url.is_a?(Parse::File)
         file = self.new(url)
@@ -72,16 +108,28 @@ module Parse
         file
       end
 
-      # A File object is considered saved if the basename of the URL and the name parameters are equal and
-      # the name of the file begins with 'tfss'
+      # A File object is considered saved if the basename of the URL and the name parameters are equal
+      # @return [Boolean] true if this file has already been saved.
       def saved?
-        @url.present? && @name.present? && @name == File.basename(@url) && @name.start_with?("tfss")
+        @url.present? && @name.present? && @name == File.basename(@url)
+      end
+
+      # Returns the url string for this Parse::File pointer. If the *force_ssl* option is
+      # set to true, it will make sure it returns a secure url.
+      # @return [String] the url string for the file.
+      def url
+        if @url.present? && Parse::File.force_ssl && @url.starts_with?('http://')
+          return @url.sub('http://', 'https://')
+        end
+        @url
       end
 
+      # @return [Hash]
       def attributes
         ATTRIBUTES
       end
 
+      # @return [Boolean] Two files are equal if they have the same url
       def ==(u)
         return false unless u.is_a?(self.class)
         @url == u.url
@@ -97,7 +145,11 @@ module Parse
         end
       end
 
-      # This is a proxy to the ruby ::File.basename method
+      # A proxy method for ::File.basename
+      # @param file_name [String]
+      # @param suffix [String]
+      # @return [String] File.basename(file_name)
+      # @see ::File.basename
       def self.basename(file_name, suffix = nil)
        if suffix.nil?
          ::File.basename(file_name)
@@ -106,7 +158,8 @@ module Parse
        end
       end
 
-      # save (create) the file if it has all the proper fields. You cannot update Parse Files.
+      # Save the file by uploading it to Parse and creating a file pointer.
+      # @return [Boolean] true if successfully uploaded and saved.
       def save
         unless saved? || @contents.nil? || @name.nil?
           response = client.create_file(@name, @contents, @mime_type)
@@ -119,10 +172,13 @@ module Parse
         saved?
       end
 
+      # @!visibility private
       def inspect
         "<Parse::File @name='#{@name}' @mime_type='#{@mime_type}' @contents=#{@contents.nil?} @url='#{@url}'>"
       end
 
+      # @return [String] the url
+      # @see #url
       def to_s
         @url
       end
@@ -133,13 +189,15 @@ end
 
 
 class Hash
-  # {"name"=>"tfss-cat.jpg", "url"=>"http://files.parsetfss.com/bcf638bb-3db0-4042-b846-7840b345b0d6/tfss-cat.jpg"}
-  # This is a helper method that determines whether a hash looks like a Parse::File hash
+  # Determines if the hash contains Parse File json metadata fields. This is determined whether
+  # the key `__type` exists and is of type `__File` and whether the `name` field matches the File.basename
+  # of the `url` field.
+  #
+  # @return [Boolean] True if this hash contains Parse file metadata.
   def parse_file?
     url = self[Parse::File::FIELD_URL]
     name = self[Parse::File::FIELD_NAME]
     (count == 2 || self["__type"] == Parse::File.parse_class) &&
-    url.present? && name.present? &&
-    name == ::File.basename(url) && name.start_with?("tfss")
+    url.present? && name.present? && name == ::File.basename(url)
   end
 end

data/lib/parse/model/geopoint.rb

@@ -5,31 +5,54 @@ require_relative "model"
 
 module Parse
 
-  # A basic geo location object in Parse. It represents a location on a map through a
-  # latitude and longitue.
+  # 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
     ATTRIBUTES = {  __type: :string, latitude: :float, longitude: :float }.freeze
-    attr_accessor :latitude, :longitude
+
+    # @return [Float] latitude value between -90.0 and 90.0
+    attr_accessor :latitude
+    # @return [Float] longitude value between -180.0 and 180.0
+    attr_accessor :longitude
     FIELD_LAT = "latitude"
     FIELD_LNG = "longitude"
-    # Latitude should not be -90.0 or 90.0.
-    # Longitude should not be -180.0 or 180.0.
+
     LAT_MIN = -90.0
     LAT_MAX = 90.0
     LNG_MIN = -180.0
     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
-    # To create a GeoPoint, you can either pass a hash (ex. {latitude: 32, longitue: -117})
-    # or an array (ex. [32,-117]) as the first parameter.
-    # You may also pass a GeoPoint object or both a lat/lng pair (Ex. GeoPoint.new(32, -117) )
-    # Points should not equal or exceed the extreme ends of the ranges.
-
-    # Attempting to use GeoPoint’s with latitude and/or longitude outside these ranges will cause an error.
 
+    # 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)
@@ -45,6 +68,7 @@ module Parse
       _validate_point
     end
 
+    # @!visibility private
     def _validate_point
 
       unless @latitude.nil? || @latitude.between?(LAT_MIN, LAT_MAX)
@@ -59,10 +83,13 @@ module Parse
 
     end
 
+    # @return [Hash]
     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]
@@ -92,24 +119,55 @@ module Parse
       _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
 
+    # @!visibility private
     def inspect
       "#<GeoPoint [#{@latitude},#{@longitude}]>"
     end
 
-    # either GeoPoint, array or lat,lng
+    # 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)

data/lib/parse/model/model.rb

@@ -8,10 +8,18 @@ require 'active_support/core_ext/object'
 require 'active_model_serializers'
 require_relative '../client'
 
-# This is the base model for all Parse object-type classes.
-
 module Parse
+  # Find a corresponding Parse::Object subclass for this string or symbol
+  # @param className [String] The name of the Parse class as string (ex. "_User")
+  # @return [Class] The proper subclass matching the className.
+  def self.classify(className)
+    Parse::Model.find_class className.to_parse_class
+  end
 
+  # The core model of all Parse-Stack classes. This class works by providing a
+  # baseline for all subclass objects to support ActiveModel features such as
+  # serialization, dirty tracking, callbacks, etc.
+  # @see ActiveModel
   class Model
 
     include Client::Connectable # allows easy default Parse::Client access
@@ -22,7 +30,6 @@ module Parse
     extend  ::ActiveModel::Callbacks # callback support on save, update, delete, etc.
     extend  ::ActiveModel::Naming # provides the methods for getting class names from Model classes
 
-    # General Parse constants
     ID = "id".freeze
     OBJECT_ID   = 'objectId'.freeze
     KEY_CLASS_NAME  = 'className'.freeze
@@ -48,15 +55,40 @@ module Parse
     # which Parse::Object subclass is responsible for handling this Parse table class.
     # we use @@model_cache to cache the results of the algorithm since we do this frequently
     # when encoding and decoding objects.
+    # @!visibility private
     @@model_cache = {}
+
+    # If set to true, a call to first_or_create will automatically save the object.
+    # @return [Boolean]
     def self.autosave_on_create
       @@autosave_on_create ||= false
     end
+
     def self.autosave_on_create=(bool)
       @@autosave_on_create = bool
     end
 
     class << self
+      # By default, we return `true` or `false` for save and destroy operations.
+      # If you prefer to have `Parse::Object` raise an exception instead, you
+      # can tell to do so either globally or on a per-model basis. When a save
+      # fails, it will raise a `Parse::SaveFailureError`.
+      #
+      # @example
+      #   Parse::Model.raise_on_save_failure = true # globally across all models
+      #   Song.raise_on_save_failure = true          # per-model
+      #
+      #   # or per-instance raise on failure
+      #   song.save!
+      #
+      # When enabled, if an error is returned by Parse due to saving or
+      # destroying a record, due to your `before_save` or `before_delete`
+      # validation cloud code triggers, `Parse::Object` will return the a
+      # `Parse::SaveFailureError` exception type. This exception has an
+      # instance method of `#object` which contains the object that failed to save.
+      #
+      # @return [Boolean]
+      attr_accessor :raise_on_save_failure
 
       def raise_on_save_failure
         @global_raise_on_save_failure ||= false
@@ -67,8 +99,23 @@ module Parse
 
     end
 
-    # class method to find the responsible ruby Parse::Object subclass that handles
-    # the provided parse class (str).
+    # Find a Parse::Model subclass matching this type or Pares collection name.
+    # This helper method is useful to find the corresponding class ruby Parse::Object subclass that handles
+    # the provided parse class.
+    #
+    # @example
+    #  Parse::Model.find_class('_User') # => Parse::User
+    #  Parse::Model.find_class('_Date') # => Parse::Date
+    #  Parse::Model.find_class('Installation') # => Parse::Installation
+    #
+    #  class Artist < Parse::Object
+    #    parse_class "Musician"
+    #  end
+    #
+    #  Parse::Model.find_class("Musician") # => Artist
+    #
+    # @param str [String] the class name
+    # @return [Parse::Object] a Parse::Object subclass or a specific Parse type.
     def self.find_class(str)
       return Parse::File if str == TYPE_FILE
       return Parse::GeoPoint if str == TYPE_GEOPOINT
@@ -92,14 +139,39 @@ end
 
 
 class String
-  # short helper method to provide lower-first-camelcase
+  # This method returns a camel-cased version of the string with the first letter
+  # of the string in lower case. This is the standard naming convention for Parse columns
+  # and property fields. This has special exception to the string "id", which returns
+  # "objectId". This is the default name filtering method for all defined properties and
+  # query keys in Parse::Query.
+  #
+  # @example
+  #  "my_field".columnize # => "myField"
+  #  "MyDataColumn".columnize # => "myDataColumn"
+  #  "id".columnize # => "objectId" (special)
+  #
+  # @return [String]
+  # @see Parse::Query.field_formatter
   def columnize
      return Parse::Model::OBJECT_ID if self == Parse::Model::ID
      u = '_'.freeze
      (first == u ? sub(u,'') : self).camelize(:lower)
   end
 
-  #users for properties: ex. :users -> "_User" or :songs -> Song
+  # Convert a string to a Parse class name. This method tries to find a
+  # responsible Parse::Object subclass that potentially matches the given string.
+  # If no match is found, it returns the camelized version of the string. This method
+  # is used internally for matching association attributes to registered
+  # Parse::Object subclasses. The method can also singularize the name before
+  # performing conversion.
+  #
+  # @example
+  #  "users".to_parse_class(singularize: true) # => "_User"
+  #  "users".to_parse_class # => "Users"
+  #  "song_data".to_parse_class # => "SongData"
+  #
+  # @param singularize [Boolean] whether the string should be singularized first before performing conversion.
+  # @return [String] the matching Parse class for this string.
   def to_parse_class(singularize: false)
     final_class = singularize ? self.singularize.camelize : self.camelize
     klass = Parse::Model.find_class(final_class) || Parse::Model.find_class(self)
@@ -110,19 +182,23 @@ class String
 end
 
 class Symbol
-  # for compatibility
+  # @return [String] a lower-first-camelcased version of the symbol
+  # @see String#columnize
   def columnize
     to_s.columnize.to_sym
   end
 
+  # @see String#singularize
   def singularize
     to_s.singularize
   end
 
+  # @see String#camelize
   def camelize
     to_s.camelize
   end
 
+  # @see String#to_parse_class
   def to_parse_class(singularize: false)
     to_s.to_parse_class(singularize: singularize)
   end