parse-stack 1.5.2 → 1.5.3

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

@@ -4,15 +4,62 @@
 require_relative '../../query'
 
 module Parse
-
+  # Defines the querying methods applied to a Parse::Object.
   module Querying
 
-    def self.included(base)
-        base.extend(ClassMethods)
-    end
-
-    module ClassMethods
-
+      # This feature is a small subset of the
+      # {http://guides.rubyonrails.org/active_record_querying.html#scopes
+      # ActiveRecord named scopes} feature. Scoping allows you to specify
+      # commonly-used queries which can be referenced as class method calls and
+      # are chainable with other scopes. You can use every {Parse::Query}
+      # method previously covered such as `where`, `includes` and `limit`.
+      #
+      #  class Article < Parse::Object
+      #    property :published, :boolean
+      #    scope :published, -> { query(published: true) }
+      #  end
+      #
+      # This is the same as defining your own class method for the query.
+      #
+      #  class Article < Parse::Object
+      #    def self.published
+      #      query(published: true)
+      #    end
+      #  end
+      #
+      # You can also chain scopes and pass parameters. In addition, boolean and
+      # enumerated properties have automatically generated scopes for you to use.
+      #
+      #  class Article < Parse::Object
+      #    scope :published, -> { query(published: true) }
+      #
+      #    property :comment_count, :integer
+      #    property :category
+      #    property :approved, :boolean
+      #
+      #    scope :published_and_commented, -> { published.where :comment_count.gt => 0 }
+      #    scope :popular_topics, ->(name) { published_and_commented.where category: name }
+      #  end
+      #
+      #  # simple scope
+      #  Article.published # => where published is true
+      #
+      #  # chained scope
+      #  Article.published_and_commented # published is true and comment_count > 0
+      #
+      #  # scope with parameters
+      #  Article.popular_topic("music") # => popular music articles
+      #  # equivalent: where(published: true, :comment_count.gt => 0, category: name)
+      #
+      #  # automatically generated scope
+      #  Article.approved(category: "tour") # => where approved: true, category: 'tour'
+      #
+      # If you would like to turn off automatic scope generation for property types,
+      # set the option `:scope` to false when declaring the property.
+      # @param name [Symbol] the name of the scope.
+      # @param body [Proc] the proc related to the scope.
+      # @raise ArgumentError if body parameter does not respond to `call`
+      # @return [Symbol] the name of the singleton method created.
       def scope(name, body)
         unless body.respond_to?(:call)
           raise ArgumentError, 'The scope body needs to be callable.'
@@ -60,33 +107,59 @@ module Parse
       end
 
 
-      # This query method helper returns a Query object tied to a parse class.
-      # The parse class should be the name of the one that will be sent in the query
-      # request pointing to the remote table.
-
+      # Creates a new {Parse::Query} with the given constraints for this class.
+      # @example
+      #  # assume Post < Parse::Object
+      #  query = Post.query(:updated_at.before => DateTime.now)
+      # @return [Parse::Query] a new query with the given constraints for this
+      #  Parse::Object subclass.
       def query(constraints = {})
         Parse::Query.new self.parse_class, constraints
       end; alias_method :where, :query
 
-      def literal_where(clauses = {})
-        query.where(clauses)
+      # @param conditions (see Parse::Query#where)
+      # @return (see Parse::Query#where)
+      # @see Parse::Query#where
+      def literal_where(conditions = {})
+        query.where(conditions)
       end
 
-      # Most common method to use when querying a class. This takes a hash of constraints
-      # and conditions and returns the results.
-
-      def all(constraints = {})
-        constraints = {limit: :max}.merge(constraints)
+      # Fetch all matching objects in this collection matching the constraints.
+      # This will be the most common way when querying Parse objects for a subclass.
+      # When no block is passed, all objects are returned. Using a block is more memory
+      # efficient as matching objects are fetched in batches and discarded after the iteration
+      # is completed.
+      # @param constraints [Hash] a set of {Parse::Query} constraints.
+      # @yield a block to iterate with each matching object.
+      # @example
+      #
+      #  songs = Song.all( ... expressions ...) # => array of Parse::Objects
+      #  # memory efficient for large amounts of records.
+      #  Song.all( ... expressions ...) do |song|
+      #      # ... do something with song..
+      #  end
+      #
+      # @return [Array<Parse::Object>] an array of matching objects. If a block is passed,
+      #  an empty array is returned.
+      def all(constraints = {limit: :max})
+        constraints = constraints.reverse_merge({limit: :max})
         prepared_query = query(constraints)
         return prepared_query.results(&Proc.new) if block_given?
         prepared_query.results
       end
 
-      # returns the first item matching the constraint. If constraint parameter is numeric,
-      # then we treat it as a count.
-      # Ex. Object.first( :name => "Anthony" ) (returns single object)
-      # Ex. Object.first(3) # first 3 objects (array of 3 objects)
-
+      # Returns the first item matching the constraint.
+      # @overload first(count = 1)
+      #  @param count [Interger] The number of items to return.
+      #  @example
+      #   Object.first(2) # => an array of the first 2 objects in the collection.
+      #  @return [Parse::Object] if count == 1
+      #  @return [Array<Parse::Object>] if count > 1
+      # @overload first(constraints = {})
+      #  @param constraints [Hash] a set of {Parse::Query} constraints.
+      #  @example
+      #   Object.first( :name => "Anthony" )
+      #  @return [Parse::Object] the first matching object.
       def first(constraints = {})
         fetch_count = 1
         if constraints.is_a?(Numeric)
@@ -99,12 +172,20 @@ module Parse
         return res.first fetch_count
       end
 
-      # creates a count request (which is more performant when counting objects)
-      
+      # Creates a count request which is more performant when counting objects.
+      # @example
+      #  # number of songs with a like count greater than 20.
+      #  count = Song.count( :like_count.gt => 20 )
+      # @param constraints (see #all)
+      # @return [Interger] the number of records matching the query.
+      # @see Parse::Query#count
       def count(constraints = {})
         query(constraints).count
       end
 
+      # Find objects matching the constraint ordered by the descending created_at date.
+      # @param constraints (see #all)
+      # @return [Array<Parse::Object>]
       def newest(constraints = {})
         constraints.merge!(order: :created_at.desc)
         _q = query(constraints)
@@ -112,6 +193,9 @@ module Parse
         _q
       end
 
+      # Find objects matching the constraint ordered by the ascending created_at date.
+      # @param constraints (see #all)
+      # @return [Array<Parse::Object>]
       def oldest(constraints = {})
         constraints.merge!(order: :created_at.asc)
         _q = query(constraints)
@@ -119,18 +203,20 @@ module Parse
         _q
       end
 
-      # Find objects based on objectIds. The result is a list (or single item) of the
-      # objects that were successfully found.
-      # Example:
-      # Object.find "<objectId>"
-      # Object.find "<objectId>", "<objectId>"....
-      # Object.find ["<objectId>", "<objectId>"]
-      # Additional named parameters:
-      # type: - :parrallel by default - makes all find requests in parallel vs serial.
-      #         :batch - makes a single query request for all objects with a "contained in" query.
-      # compact: - true by default, removes any nil values from the array as it is potential
-      # that an object with a specified ID does not exist.
-
+      # Find objects for a given objectId in this collection.The result is a list
+      # (or single item) of the objects that were successfully found.
+      # @example
+      #  Object.find "<objectId>"
+      #  Object.find "<objectId>", "<objectId>"....
+      #  Object.find ["<objectId>", "<objectId>"]
+      # @param parse_ids [String] the objectId to find.
+      # @param type [Symbol] the fetching methodology to use if more than one id was passed.
+      #  - *:parallel* : Utilizes parrallel HTTP requests to fetch all objects requested.
+      #  - *:batch* : This uses a batch fetch request using a contained_in clause.
+      # @param compact [Boolean] whether to remove nil items from the returned array for objects
+      #  that were not found.
+      # @return [Parse::Object] if only one id was provided as a parameter.
+      # @return [Array<Parse::Object>] if more than one id was provided as a parameter.
       def find(*parse_ids, type: :parallel, compact: true)
         # flatten the list of Object ids.
         parse_ids.flatten!
@@ -160,8 +246,6 @@ module Parse
         as_array ? results : results.first
       end; alias_method :get, :find
 
-    end # ClassMethods
-
   end # Querying
 
 

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

@@ -4,24 +4,12 @@
 require_relative "properties"
 
 module Parse
-  # Upgrade all
-  def self.auto_upgrade!
-    klassModels = Parse::Object.descendants
-    klassModels.sort_by { |c| c.parse_class }.each do |klass|
-      yield(klass) if block_given?
-      klass.auto_upgrade!
-    end
-  end
-
+  # Defines the Schema methods applied to a Parse::Object.
   module Schema
 
-    def self.included(base)
-      base.extend(ClassMethods)
-    end
-
-    module ClassMethods
-
-      # returns the schema of the defined class in the Parse JSON format.
+      # Generate a Parse-server compatible schema hash for performing changes to the
+      # structure of the remote collection.
+      # @return [Hash] the schema for this Parse::Object subclass.
       def schema
         sch = { className: parse_class, fields: {} }
         #first go through all the attributes
@@ -54,25 +42,36 @@ module Parse
         sch
       end
 
-      # updates the remote schema using Parse::Client
+      # Update the remote schema for this Parse collection.
+      # @param schema_updates [Hash] the changes to be made to the schema.
+      # @return [Parse::Response]
       def update_schema(schema_updates = nil)
         schema_updates ||= schema
         client.update_schema parse_class, schema_updates
       end
 
+      # Create a new collection for this model with the schema defined by the local
+      # model.
+      # @return [Parse::Response]
+      # @see Schema.schema
       def create_schema
         client.create_schema parse_class, schema
       end
 
-      # fetches the current schema of this table.
+      # Fetche the current schema for this collection from Parse server.
+      # @return [Parse::Response]
       def fetch_schema
         client.schema parse_class
       end
 
-      # A class method for non-destructive auto upgrading a remote schema based on the properties
-      # and relations you have defined. If the table doesn't exist, we create the schema
-      # from scratch - otherwise we fetched the current schema, calculate the differences
-      # and add the missing columns. WE DO NOT REMOVE any columns.
+      # A class method for non-destructive auto upgrading a remote schema based
+      # on the properties and relations you have defined in your local model. If
+      # the collection doesn't exist, we create the schema. If the collection already
+      # exists, the current schema is fetched, and only add the additional fields
+      # that are missing.
+      # @note No columns or fields are removed, this is a safe non-destructive upgrade.
+      # @return [Parse::Response] if the remote schema was modified.
+      # @return [Boolean] if no changes were made to the schema, it returns true.
       def auto_upgrade!
         response = fetch_schema
         if response.success?
@@ -86,18 +85,9 @@ module Parse
           end
           return true if current_schema[:fields].empty?
           return update_schema( current_schema )
-        else
-          return create_schema
         end
-        #fetch_schema.success? ? update_schema : create_schema
+        create_schema
       end
-    #def diff(h2);self.dup.delete_if { |k, v| h2[k] == v }.merge(h2.dup.delete_if { |k, v| self.has_key?(k) }); end;
-
-    end
-
-    def schema
-      self.class.schema
-    end
 
   end
 end

data/lib/parse/model/object.rb

@@ -21,6 +21,7 @@ require_relative "date"
 require_relative "acl"
 require_relative "push"
 require_relative 'core/actions'
+require_relative 'core/fetching'
 require_relative 'core/querying'
 require_relative "core/schema"
 require_relative "core/properties"
@@ -32,7 +33,17 @@ require_relative "associations/has_many"
 module Parse
   # @return [Array] an array of registered Parse::Object subclasses.
   def self.registered_classes
-      Parse::Object.descendants.map { |m| m.parse_class }.uniq
+      Parse::Object.descendants.map(&:parse_class).uniq
+  end
+
+  # Perform a non-destructive upgrade of all your Parse schemas in the backend
+  # based on the property definitions of your local {Parse::Object} subclasses.
+  def self.auto_upgrade!
+    klassModels = Parse::Object.descendants
+    klassModels.sort_by(&:parse_class).each do |klass|
+      yield(klass) if block_given?
+      klass.auto_upgrade!
+    end
   end
 
   # This is the core class for all app specific Parse table subclasses. This class
@@ -53,10 +64,8 @@ module Parse
   # Properties:
   #
   # All columns in a Parse object are considered a type of property (ex. string, numbers, arrays, etc)
-  # except in two cases - Pointers and Relations. For the list of basic supported data types, please see the
-  # Properties module variable Parse::Properties::TYPES . When defining a property,
-  # dynamic methods are created that take advantage of all the ActiveModel
-  # plugins (dirty tracking, callbacks, json, etc).
+  # except in two cases - Pointers and Relations. For a detailed discussion of properties, see
+  # The {https://github.com/modernistik/parse-stack#defining-properties Defining Properties} section.
   #
   # Associations:
   #
@@ -74,27 +83,18 @@ module Parse
   # without requiring an explicit intermediary Parse table or class. This feature
   # is also implemented using the `:has_many` method but passing the option of `:relation`.
   #
-  #
-  # Querying:
-  # The querying module provides all the general methods to be able to find and query a specific
-  # Parse table.
-  #
-  # Fetching:
-  # The fetching modules supports fetching data from Parse (depending on the state of the object),
-  # and providing some autofetching features when traversing relational objects and properties.
-  #
-  # Schema:
-  # The schema module provides methods to modify the Parse table remotely to either add or create
-  # any locally define properties in ruby and have those be reflected in the Parse application.
+  # @see Associations::BelongsTo
+  # @see Associations::HasOne
+  # @see Associations::HasMany
   class Object < Pointer
     include Properties
     include Associations::HasOne
     include Associations::BelongsTo
     include Associations::HasMany
-    include Querying
+    extend Querying
+    extend Schema
     include Fetching
     include Actions
-    include Schema
     BASE_OBJECT_CLASS = "Parse::Object".freeze
 
     # @return [Model::TYPE_OBJECT]
@@ -145,7 +145,7 @@ module Parse
 
       attr_accessor :disable_serialized_string_date, :parse_class, :acl
 
-      # @!attribute [rw] disable_serialized_string_date
+      # @!attribute disable_serialized_string_date
       #  Disables returning a serialized string date properties when encoding to JSON.
       #  This affects created_at and updated_at fields in order to be backwards compatible with old SDKs.
       #  @return [Boolean]
@@ -191,6 +191,12 @@ module Parse
     end
     alias_method :className, :parse_class
 
+    # @return [Hash] the schema structure for this Parse collection from the server.
+    # @see Parse::Schema
+    def schema
+      self.class.schema
+    end
+
     # @return [Hash] a json-hash representing this object.
     def as_json(*args)
       pointer? ? pointer : super(*args)

data/lib/parse/model/pointer.rb

@@ -65,6 +65,7 @@ module Parse
     #
     # @see Parse::Object
     class Pointer < Model
+      # Attributes of a Pointer.
       ATTRIBUTES = { __type: :string, className: :string, objectId: :string}.freeze
       # @return [String] the name of the Parse class for this pointer.
       attr_accessor :parse_class

data/lib/parse/query/constraint.rb

@@ -3,23 +3,35 @@
 
 require_relative 'operation'
 require 'time'
-# Constraints are the heart of the Parse::Query system.
-# Each constraint is made up of an Operation and a value (the right side
-# of an operator). Constraints are responsible for making their specific
-# Parse hash format required when sending Queries to Parse. All constraints can
-# be combined by merging different constraints (since they are multiple hashes)
-# and some constraints may have higher precedence than others (ex. equality is higher
-# precedence than an "in" query).
-# All constraints should inherit from Parse::Constraint and should
-# register their specific Operation method (ex. :eq or :lte)
-# For more information about the query design pattern from DataMapper
-# that inspired this, see http://datamapper.org/docs/find.html
+
 module Parse
+  # Constraints are the heart of the Parse::Query system.
+  # Each constraint is made up of an Operation and a value (the right side
+  # of an operator). Constraints are responsible for making their specific
+  # Parse hash format required when sending Queries to Parse. All constraints can
+  # be combined by merging different constraints (since they are multiple hashes)
+  # and some constraints may have higher precedence than others (ex. equality is higher
+  # precedence than an "in" query).
+  # All constraints should inherit from Parse::Constraint and should
+  # register their specific Operation method (ex. :eq or :lte)
+  # For more information about the query design pattern from DataMapper
+  # that inspired this, see http://datamapper.org/docs/find.html
   class Constraint
 
+    # @!attribute operation
+    # The operation tied to this constraint.
+    # @return [Parse::Operation]
+
+    # @!attribute value
+    # The value to be applied to this constraint.
+    # @return [Parse::Operation]
+
     attr_accessor :operation, :value
-    # A constraint needs an operation and a value.
-    # You may also pass a block to modify the operation if needed
+
+    # Create a new constraint.
+    # @param operation [Parse::Operation] the operation for this constraint.
+    # @param value [Object] the value to attach to this constraint.
+    # @yield You may also pass a block to modify the operation or value.
     def initialize(operation, value)
       # if the first parameter is not an Operation, but it is a symbol
       # it most likely is just the field name, so let's assume they want
@@ -34,16 +46,22 @@ module Parse
     end
 
     class << self
+      # @!attribute key
       # The class attributes keep track of the Parse key (special Parse
       # text symbol representing this operation. Ex. local method could be called
       # .ex, where the Parse Query operation that should be sent out is "$exists")
       # in this case, key should be set to "$exists"
+      # @return [Symbol]
       attr_accessor :key
+
+      # @!attribute precedence
       # Precedence defines the priority of this operation when merging.
       # The higher the more priority it will receive.
+      # @return [Integer]
       attr_accessor :precedence
 
-      # Class access to store the default symbol operand action
+      # @!attribute operand
+      # @return [Symbol] the operand for this constraint.
       attr_accessor :operand
 
       # Creates a new constraint given an operation and value.
@@ -55,24 +73,33 @@ module Parse
         operation.constraint(value)
       end
 
-      # method to set the keyword for this Constaint (subclasses)
-      def contraint_keyword(k)
-        @key = k
+      # Set the keyword for this Constaint. Subclasses should use this method.
+      # @param keyword [Symbol]
+      # @return (see key)
+      def contraint_keyword(keyword)
+        @key = keyword
       end
 
-      def precedence(v = nil)
+      # Set the default precedence for this constraint.
+      # @param priority [Integer] a higher priority has higher precedence
+      # @return [Integer]
+      def precedence(priority = nil)
         @precedence = 0 if @precedence.nil?
-        @precedence = v unless v.nil?
+        @precedence = priority unless priority.nil?
         @precedence
       end
 
-      # All subclasses should register their operation and themselves
-      # as the handler.
+      # Register the given operand for this Parse::Constraint subclass.
+      # @note All subclasses should register their operation and themselves.
+      # @param op [Symbol] the operand
+      # @param klass [Parse::Constraint] a subclass of Parse::Constraint
+      # @return (see Parse::Operation.register)
       def register(op, klass = self)
         self.operand ||= op
         Operation.register op, klass
       end
 
+      # @return [Object] a formatted value based on the data type.
       def formatted_value(value)
         d = value
         d = { __type: "Date", iso: d.utc.iso8601(3) } if d.respond_to?(:utc)
@@ -91,21 +118,28 @@ module Parse
 
     end
 
+    # @return [Integer] the precedence of this constraint
     def precedence
       self.class.precedence
     end
 
+    # @return [Symbol] the Parse keyword for this constraint.
     def key
       self.class.key
     end
 
+    # @!attribute operand
+    # @return [Symbol] the operand for the operation.
     def operand
       @operation.operand unless @operation.nil?
     end
+
     def operand=(o)
       @operation.operand = o unless @operation.nil?
     end
 
+    # @!attribute operator
+    # @return [Symbol] the operator for the operation.
     def operator
       @operation.operator unless @operation.nil?
     end
@@ -114,33 +148,37 @@ module Parse
       @operation.operator = o unless @operation.nil?
     end
 
+    # @!visibility private
     def inspect
       "<#{self.class} #{operator.to_s}(#{operand.inspect}, `#{value}`)>"
     end
 
+    # Calls build internally
+    # @return [Hash]
     def as_json(*args)
       build
     end
 
-    # subclasses should override the build method depending on how they
-    # need to construct the Parse formatted query hash
-    # The default case below is for supporting equality.
-    # Before the final value is set int he hash, we call formatted_value in case
-    # we need to format the value for particular data types.
+    # Builds the JSON hash representation of this constraint for a Parse query.
+    # This method should be overriden by subclasses. The default implementation
+    # implements buildling the equality constraint.
+    # @return [Hash]
     def build
       return { @operation.operand => formatted_value } if @operation.operator == :eq || key.nil?
       { @operation.operand => { key => formatted_value } }
     end
 
+    # @return [String] string representation of this constraint.
     def to_s
       inspect
     end
 
-    # This method formats the value based on some specific data types.
+    # @return [Object] formatted value based on the specific data type.
     def formatted_value
       self.class.formatted_value(@value)
     end
 
+    # Registers the default constraint of equality
     register :eq, Constraint
     precedence 100
   end

data/lib/parse/query/constraints.rb

@@ -11,9 +11,6 @@ require_relative 'constraint'
 # For more information about the query design pattern from DataMapper
 # that inspired this, see http://datamapper.org/docs/find.html
 
-
-
-
 module Parse
   # Error for when there is a problem with the input passed to a constraint.
   class ConstraintError < StandardError; end;