parse-stack 1.5.1 → 1.5.2

data/lib/parse/model/associations/collection_proxy.rb

@@ -7,34 +7,56 @@ require 'active_support/inflector'
 require 'active_support/core_ext/object'
 require_relative '../pointer'
 
-# A collection proxy is a special type of array wrapper that will allow us to
-# notify the parent object about changes to the array. We use a delegate pattern
-# to send notifications to the parent whenever the content of the internal array changes.
-# The main requirement to using the proxy is to provide the list of initial items if any,
-# the owner to be notified and the name of the attribute 'key'. With that, anytime the array
-# will change, we will notify the delegate by sending :'key'_will_change! . The proxy can also
-# be lazy when fetching the contents of the collection. Whenever the collection is accessed and
-# the list is in a "not loaded" state (empty and loaded == false), we will send :'key_fetch!' to the delegate in order to
-# populate the collection.
-module Parse
 
+module Parse
+    # We use a delegate pattern to send notifications to the parent whenever the content of the internal array changes.
+    # The main requirement to using the proxy is to provide the list of initial items if any,
+    # the owner to be notified and the name of the attribute 'key'. With that, anytime the array
+    # will change, we will notify the delegate by sending :'key'_will_change! . The proxy can also
+    # be lazy when fetching the contents of the collection. Whenever the collection is accessed and
+    # the list is in a "not loaded" state (empty and loaded == false), we will send :'key_fetch!' to the delegate in order to
+    # populate the collection.
+
+    # A CollectionProxy is a special type of array wrapper that notifies a delegate
+    # object about changes to the array in order to perform dirty tracking. This is
+    # used for all Array properties in Parse::Objects.
     class CollectionProxy
       include ::ActiveModel::Model
       include ::ActiveModel::Dirty
       include ::Enumerable
-      attr_accessor :collection, :delegate, :loaded
+      # @!attribute [rw] collection
+      #  The internal backing store of the collection.
+      #  @return [Array]
+
+      # @!attribute [r] delegate
+      #  The object to be notified of changes to the collection.
+      #  @return [Object]
+
+      # @!attribute [rw] loaded
+      #  @return [Boolean] true/false whether the collection has been loaded.
+
+      # @!attribute [r] parse_class
+      #  For some subclasses, this helps typecast the items in the collection.
+      #  @return [String]
+
+      # @!attribute [r] key
+      #  the name of the property key to use when sending notifications for _will_change! and _fetch!
+      #  @return [String]
+
+      attr_accessor :collection, :delegate, :loaded, :parse_class
       attr_reader :delegate, :key
-      attr_accessor :parse_class
+
       # This is to use dirty tracking within the proxy
       define_attribute_methods :collection
-      include Enumerable
-
-      # To initialize a collection, you need to pass the following named parameters
-      # collection - the initial items to add to the collection.
-      # :delegate - the owner of the object that will receive the notifications.
-      # :key - the name of the key to use when sending notifications for _will_change! and _fetch!
-      # :parse_class - what Parse class type are the items of the collection.
-      # This is used to typecast the objects in the array to a particular Parse Object type.
+
+      # Create a new CollectionProxy instance.
+      # @param collection [Array] the initial items to add to the collection.
+      # @param delegate [Object] the owner of the object that will receive the notifications.
+      # @param key [Symbol] the name of the key to use when sending notifications for _will_change! and _fetch!
+      # @param parse_class [String] (Optional) the Parse class type are the items of the collection.
+      #   This is used to typecast the objects in the array to a particular Parse Object type.
+      # @see PointerCollectionProxy
+      # @see RelationCollectionProxy
       def initialize(collection = nil, delegate: nil, key: nil, parse_class: nil)
         @delegate = delegate
         @key = key.to_sym if key.present?
@@ -43,21 +65,27 @@ module Parse
         @parse_class = parse_class
       end
 
+      # true if the collection has been loaded
       def loaded?
         @loaded
       end
 
-      # helper method to forward a message to the delegate
+      # Forward a method call to the delegate.
+      # @param method [Symbol] the name of the method to forward
+      # @param params [Object] method parameters
+      # @return [Object] the return value from the forwarded method.
       def forward(method, params = nil)
         return unless @delegate.present? && @delegate.respond_to?(method)
         params.nil? ? @delegate.send(method) : @delegate.send(method, params)
       end
 
+      # Reset the state of the collection.
       def reset!
         @loaded = false
         clear
       end
 
+      # @return [Boolean] true if two collection proxies have similar items.
       def ==(other_list)
         if other_list.is_a?(Array)
           return @collection == other_list
@@ -66,25 +94,32 @@ module Parse
         end
       end
 
+      # Reload and restore the collection to its original set of items.
       def reload!
         reset!
         collection #force reload
       end
 
+      # clear all items in the collection
       def clear
         @collection.clear
       end
 
-      def to_ary
+      # @return [Array]
+      def to_a
         collection.to_a
-      end; alias_method :to_a, :to_ary
+      end; alias_method :to_ary, :to_a
 
+      # @!attribute [rw] collection
+      #  Set the internal collection of items without dirty tracking or
+      #  change notifications.
       def set_collection!(list)
         @collection = list
       end
 
-      # lazy loading of a collection. If empty and not loaded, then forward _fetch!
-      # to the delegate
+      # @!attribute [rw] collection
+      #  The internal backing store of the collection.
+      # @return [Array] contents of the collection.
       def collection
         if @collection.empty? && @loaded == false
           @collection = forward( :"#{@key}_fetch!" ) || @collection || []
@@ -99,7 +134,8 @@ module Parse
         @collection = c
       end
 
-      # Method to add items to the collection.
+      # Add items to the collection
+      # @param items [Array] items to add
       def add(*items)
         notify_will_change! if items.count > 0
         items.each do |item|
@@ -109,6 +145,7 @@ module Parse
       end; alias_method :push, :add
 
       # Remove items from the collection
+      # @param items [Array] items to remove
       def remove(*items)
         notify_will_change! if items.count > 0
         items.each do |item|
@@ -117,24 +154,37 @@ module Parse
         @collection
       end; alias_method :delete, :remove
 
+      # Atomically adds all items from the array.
+      # This request is sent directly to the Parse backend.
+      # @param items [Array] items to uniquely add
+      # @see #add_unique!
       def add!(*items)
         return false unless @delegate.respond_to?(:op_add!)
         @delegate.send :op_add!, @key, items.flatten
         reset!
       end
 
+      # Atomically adds all items from the array that are not already part of the collection.
+      # This request is sent directly to the Parse backend.
+      # @param items [Array] items to uniquely add
+      # @see #add!
       def add_unique!(*items)
         return false unless @delegate.respond_to?(:op_add_unique!)
         @delegate.send :op_add_unique!, @key, items.flatten
         reset!
       end
 
+      # Atomically deletes all items from the array. This request is sent
+      # directly to the Parse backend.
+      # @param items [Array] items to remove
       def remove!(*items)
         return false unless @delegate.respond_to?(:op_remove!)
         @delegate.send :op_remove!, @key, items.flatten
         reset!
       end
 
+      # Atomically deletes all items in the array, and marks the field as `undefined` directly
+      # with the Parse server. This request is sent directly to the Parse backend.
       def destroy!
         return false unless @delegate.respond_to?(:op_destroy!)
         @delegate.send :op_destroy!, @key
@@ -143,30 +193,39 @@ module Parse
         reset!
       end
 
+      # Locally restores previous attributes (not from the persistent store)
       def rollback!
         restore_attributes
       end
 
+      # clears all dirty tracked information.
       def clear_changes!
         clear_changes_information
       end
 
+      # mark that collection changes where applied, which clears dirty tracking.
       def changes_applied!
         changes_applied
       end
 
+      # @param args [Hash] arguments to pass to Array#first.
+      # @return [Object] the first item in the collection
       def first(*args)
         collection.first(*args)
       end
 
+      # @return [Object] the second item in the collection
       def second
         collection.second
       end
 
+      # @param args [Hash] arguments to pass to Array#last.
+      # @return [Object] the last item in the collection
       def last(*args)
         collection.last(*args)
       end
 
+      # @return [Integer] number of items in the collection.
       def count
         collection.count
       end
@@ -175,24 +234,25 @@ module Parse
         collection.as_json(args)
       end
 
+      # true if the collection is empty.
       def empty?
         collection.empty?
       end
 
-      # append items to the array
+      # Append items to the collection
       def <<(*list)
         if list.count > 0
           notify_will_change!
           list.flatten.each { |e| collection.push(e) }
         end
       end
-      # we call our own dirty tracking and also forward the call
+
+      # Notifies the delegate that the collection changed.
       def notify_will_change!
         collection_will_change!
         forward "#{@key}_will_change!"
       end
 
-      # supported iterator
       def each
         return collection.enum_for(:each) unless block_given?
         collection.each &Proc.new

data/lib/parse/model/associations/has_many.rb

@@ -10,29 +10,291 @@ module Parse
 
   module Associations
 
-    # This module provides has_many functionality to defining Parse::Object classes.
-    # There are two main types of a has_many association - array and relation.
-    # A has_many array relation, uses a PointerCollectionProxy to store a list of Parse::Object (or pointers)
-    # that are stored in the column of the local table. This means we expect a the remote Parse table to contain
-    # a column of type array which would contain a set of hash-like Pointers.
-    # In the relation case, the object's Parse table has a column, but it points to a separate
-    # relational table (join table) which maps both the local class and the foreign class. In this case
-    # the type of the column is of "Relation" with a specific class name. This then means that it contains a set of
-    # object Ids that we will treat as being part of the foreign table.
-    # Ex. If a Artist defines a has_many relation to a Song class through a column called 'favoriteSongs'.
-    # Then the Parse type of the favoriteSongs column, contained in the Artist table,
-    # would be Relation<Song>. Any objectIds listed in that relation would then
-    # be Song object Ids.
-    # One thing to note is that when querying relations, the foreign table is the one that needs to be
-    # queried in order to retrive the associated object to the local object. For example,
-    # if an Artist has a relation to many Song objects, and we wanted to get the list of songs
-    # this artist is related to, we would query the Song table passing the specific artist record
-    # we are constraining to.
+    # Parse has many ways to implement one-to-many and many-to-many
+    # associations: `Array`, `Parse Relation` or through a `Query`. How you decide
+    # to implement your associations, will affect how `has_many` works in
+    # Parse-Stack. Parse natively supports one-to-many and many-to-many
+    # relationships using `Array` and `Relations`, as described in
+    # {https://parseplatform.github.io/docs/js/guide/#relational-data Parse Relational Data}.
+    # Both of these methods require you define a specific column type in your
+    # Parse table that will be used to store information about the association.
+    #
+    # In addition to `Array` and `Relation`, Parse-Stack also implements the
+    # standard `has_many` behavior prevalent in other frameworks through a query
+    # where the associated class contains a foreign pointer to the local class,
+    # usually the inverse of a `belongs_to`. This requires that the associated
+    # class has a defined column that contains a pointer the refers to the
+    # defining class.
+    #
+    # *Query-Approach*
+    #
+    # In this `Query` implementation, a `has_many` association for a Parse class
+    # requires that another Parse class will have a foreign pointer that refers
+    # to instances of this class. This is the standard way that `has_many`
+    # relationships work in most databases systems. This is usually the case when
+    # you have a class that has a `belongs_to` relationship to instances of the
+    # local class.
+    #
+    # In the example below, many songs belong to a specific artist. We set this
+    # association by setting {Associations::BelongsTo.belongs_to :belongs_to} relationship from `Song` to `Artist`.
+    # Knowing there is a column in `Song` that points to instances of an `Artist`,
+    # we can setup a `has_many` association to `Song` instances in the `Artist`
+    # class. Doing so will generate a helper query method on the `Artist` instance
+    # objects.
+    #
+    #  class Song < Parse::Object
+    #    property :released, :date
+    #    # this class will have a pointer column to an Artist
+    #    belongs_to :artist
+    #  end
+    #
+    #  class Artist < Parse::Object
+    #    has_many :songs
+    #  end
+    #
+    #  artist = Artist.first
+    #
+    #  artist.songs # => [all songs belonging to artist]
+    #  # equivalent: Song.all(artist: artist)
+    #
+    #  # filter also by release date
+    #  artist.songs(:released.after => 1.year.ago)
+    #  # equivalent: Song.all(artist: artist, :released.after => 1.year.ago)
+    #
+    # In order to modify the associated objects (ex. `songs`), you must modify
+    # their corresponding `belongs_to` field (in this case `song.artist`), to
+    # another record and save it.
+    #
+    # Options for `has_many` using the `Query` approach are `:as` and `:field`. The
+    # `:as` option behaves similarly to the {Associations::BelongsTo.belongs_to :belongs_to} counterpart. The
+    # `:field` option can be used to override the derived column name located
+    # in the foreign class. The default value for `:field` is the columnized
+    # version of the Parse subclass `parse_class` method.
+    #
+    #  class Parse::User
+    #    # since the foreign column name is :agent
+    #    has_many :artists, field: :agent
+    #  end
+    #
+    #  class Artist < Parse::Object
+    #    belongs_to :manager, as: :user, field: :agent
+    #  end
+    #
+    #  artist.manager # => Parse::User object
+    #
+    #  user.artists # => [artists where :agent column is user]
+    #
+    #
+    # When using this approach, you may also employ the use of scopes to filter the particular data from the `has_many` association.
+    #
+    #  class Artist
+    #    has_many :songs, ->(timeframe) { where(:created_at.after => timeframe) }
+    #  end
+    #
+    #  artist.songs(6.months.ago)
+    #  # => [artist's songs created in the last 6 months]
+    #
+    # You may also call property methods in your scopes related to the instance.
+    # You also have access to the instance object for the local class
+    # through a special "*i*" method in the scope.
+    #
+    #  class Concert
+    #    property :city
+    #    belongs_to :artist
+    #  end
+    #
+    #  class Artist
+    #    property :hometown
+    #    has_many :local_concerts, -> { where(:city => hometown) }, as: :concerts
+    #  end
+    #
+    #  # assume
+    #  artist.hometown = "San Diego"
+    #
+    #  # artist's concerts in their hometown of 'San Diego'
+    #  artist.local_concerts
+    #  # equivalent: Concert.all(artist: artist, city: artist.hometown)
+    #
+    # You may also omit the association completely, as rely on the scope to fetch the
+    # associated records. This makes the `has_many` work as a macro query setting the :scope_only
+    # option to true:
+    #
+    #  class Author < Parse::Object
+    #    property :name
+    #    has_many :posts, ->{ where :tags.in => name.downcase }, scope_only: true
+    #  end
+    #
+    #  class Post < Parse::Object
+    #    property :tags, :array
+    #  end
+    #
+    #  author.posts # => Posts where author's name is a tag
+    #  # equivalent: Post.all( :tags.in => artist.name.downcase )
+    #
+    # *Array-Approach*
+    #
+    # In the `Array` implemenatation, you can designate a column to be of `Array`
+    # type that contains a list of Parse pointers. Parse-Stack supports this by
+    # passing the option `through: :array` to the `has_many` method. If you use
+    # this approach, it is recommended that this is used for associations where
+    # the quantity is less than 100 in order to maintain query and fetch
+    # performance. You would be in charge of maintaining the array with the proper
+    # list of Parse pointers that are associated to the object. Parse-Stack does
+    # help by wrapping the array in a {Parse::PointerCollectionProxy} which provides dirty tracking.
+    #
+    #  class Artist < Parse::Object
+    #  end
+    #
+    #  class Band < Parse::Object
+    #    has_many :artists, through: :array
+    #  end
+    #
+    #  artist = Artist.first
+    #
+    #  # find all bands that contain this artist
+    #  bands = Band.all( :artists.in => [artist.pointer] )
+    #
+    #  band = bands.first
+    #  band.artists # => [array of Artist pointers]
+    #
+    #  # remove artists
+    #  band.artists.remove artist
+    #
+    #  # add artist
+    #  band.artists.add artist
+    #
+    #  # save changes
+    #  band.save
+    #
+    # *ParseRelation-Approach*
+    #
+    # Other than the use of arrays, Parse supports native one-to-many and many-to-many
+    # associations through what is referred to as a {https://parseplatform.github.io/docs/js/guide/#many-to-many-relationships Parse Relation}.
+    # This is implemented by defining a column to be of type `Relation` which
+    # refers to a foreign class. Parse-Stack supports this by passing the
+    # `through: :relation` option to the `has_many` method. Designating a column
+    # as a Parse relation to another class type, will create a one-way intermediate
+    # "join-list" between the local class and the foreign class. One important
+    # distinction of this compared to other types of data stores (ex. PostgresSQL) is that:
+    #
+    # *1*. The inverse relationship association is not available automatically. Therefore, having a column of `artists` in a `Band` class that relates to members of the band (as `Artist` class), does not automatically make a set of `Band` records available to `Artist` records for which they have been related. If you need to maintain both the inverse relationship between a foreign class to its associations, you will need to manually manage that by adding two Parse relation columns in each class, or by creating a separate class (ex. `ArtistBands`) that is used as a join table.
+    #
+    # *2*. Querying the relation is actually performed against the implicit join table, not the local one.
+    #
+    # *3*. Applying query constraints for a set of records within a relation is performed against the foreign table class, not the class having the relational column.
+    #
+    # The Parse documentation provides more details on associations, see {http://parseplatform.github.io/docs/ios/guide/#relations Parse Relations Guide}.
+    # Parse-Stack will handle the work for (2) and (3) automatically.
+    #
+    # In the example below, a `Band` can have thousands of `Fans`. We setup a
+    # `Relation<Fan>` column in the `Band` class that references the `Fan` class.
+    # Parse-Stack provides methods to manage the relationship under the {Parse::RelationCollectionProxy}
+    # class.
+    #
+    #  class Fan < Parse::Object
+    #    # .. lots of properties ...
+    #    property :location, :geopoint
+    #  end
+    #
+    #  class Band < Parse::Object
+    #    has_many :fans, through: :relation 
+    #  end
+    #
+    #  band = Band.first
+    #
+    #   # the number of fans in the relation
+    #  band.fans.count
+    #
+    #  # get the first object in relation
+    #  fan = bands.fans.first # => Parse::User object
+    #
+    #  # use `add` or `remove` to modify relations
+    #  band.fans.add user
+    #  bands.fans.remove user
+    #
+    #  # updates the relation as well as changes to `band`
+    #  band.fans.save
+    #
+    #  # Find 50 fans who are near San Diego, CA
+    #  downtown = Parse::GeoPoint.new(32.82, -117.23)
+    #  fans = band.fans.all :location.near => downtown
+    #
+    # You can perform atomic additions and removals of objects from `has_many`
+    # relations. Parse allows this by providing a specific atomic operation
+    # request. You can use the methods below to perform these types of atomic
+    # operations. The operation is performed directly on Parse server
+    # and not on your instance object.
+    #
+    #  # atomically add/remove
+    #  band.artists.add! objects  # { __op: :AddUnique }
+    #  band.artists.remove! objects  # { __op: :AddUnique }
+    #
+    #  # atomically add unique Artist
+    #  band.artists.add_unique! objects  # { __op: :AddUnique }
+    #
+    #  # atomically add/remove relations
+    #  band.fans.add! users # { __op: :Add }
+    #  band.fans.remove! users # { __op: :Remove }
+    #
+    #  # atomically perform a delete operation on this field name
+    #  # this should set it as `undefined`.
+    #  band.op_destroy!("category") # { __op: :Delete }
+    #
     module HasMany
+
+      # @!attribute [rw] self.relations
+      #  A hash mapping of all has_many associations that use the ParseRelation implementation.
+      #  @return [Hash]
+
+      # Define a one-to-many or many-to-many association between the local model and a foreign class.
+      # Options for `has_many` are the same as the {Associations::BelongsTo.belongs_to} counterpart with
+      # support for `:required`, `:as` and `:field`. It has additional options.
+      #
+      # @!method self.has_many(key, scope = nil, opts = {})
+      # @param [Symbol] key The pluralized version of the foreign class. Using the :query method,
+      #  this implies the name of the foreign column that a pointer to this record.
+      #  Using the :array or :relation method, this implies the name of the local
+      #  column that contains either an array of Parse::Pointers in the case of :array,
+      #  or the Parse Relation, in the case of :relation.
+      # @param [Proc] scope Only applicable using :query. A proc that can customize the query by applying
+      #   additional constraints when fetching the associated records. Works similarly as
+      #   ActiveModel associations described in section {http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html Customizing the Query}
+      # @option opts [Symbol] :through The type of implementation to use: :query (default), :array or :relation.
+      #  If set to `:array`, it defines the column in Parse as being an array of
+      #  Parse pointer objects and will be managed locally using a {Parse::PointerCollectionProxy}.
+      #  If set to `:relation`, it defines a column of type Parse Relation with
+      #  the foreign class and will be managed locally using a {Parse::RelationCollectionProxy}.
+      #  If set to `:query`, no storage is required on the local class as the
+      #  associated records will be fetched using a Parse query.
+      # @option opts [Symbol] :field override the name of the remote column to use when fetching the association.
+      #  When using through :query, this is the column name of the remote column
+      #  of the foreign class that will be used for matching. When using :array,
+      #  this is the name of the remote column of the local class that contains
+      #  an array of pointers to the foreign class. When using :relation, this
+      #  is the name of the remote column of the local class that contains the Parse Relation.
+      # @option opts [Symbol] :as override the inferred Parse::Object subclass of the association.
+      #  By default this is inferred as the singularized camel case version of
+      #  the key parameter. This option allows you to override the typecast of
+      #  foreign Parse model of the association, while allowing you to have a
+      #  different accessor name.
+      # @example
+      #  has_many :fans, as: :users, through: :relation, field: "awesomeFans"
+      #  has_many :songs
+      #  has_many :likes, as: :users, through: :relation
+      #  has_many :artists, field: "managedArtists"
+      #
+      # @return [Array<Parse::Object>] if through :query
+      # @return [PointerCollectionProxy] if through :array
+      # @return [RelationCollectionProxy] if through :relation
+      # @see PointerCollectionProxy
+      # @see RelationCollectionProxy
+
+      # @!visibility private
       def self.included(base)
         base.extend(ClassMethods)
       end
 
+      # @!visibility private
       module ClassMethods
         attr_accessor :relations
         def relations
@@ -89,17 +351,24 @@ module Parse
               query.conditions(*args)
             end
 
-            query.define_singleton_method(:method_missing) do |m, *args, &block|
+            query.define_singleton_method(:method_missing) do |m, *args, &chained_block|
               klass = Parse::Model.find_class klassName
+
               if klass.present? && klass.respond_to?(m)
-                klass_scope = klass.send(m, *args, &block)
-                return klass_scope.is_a?(Parse::Query) ?
-                    self.add_constraints( klass_scope.constraints ) :
-                    klass_scope
+
+                klass_scope = klass.send(m, *args) # blocks only passed to final result set
+                return klass_scope unless klass_scope.is_a?(Parse::Query)
+                # merge constraints
+                add_constraints( klass_scope.constraints )
+                # if a block was passed, execute the query, otherwise return the query
+                return chained_block.present? ? results(&chained_block) : self
               end
-              self.results.send(m, *args, &block)
+              results.send(m, *args, &chained_block)
             end
 
+            query.define_singleton_method(:to_s) { self.results.to_s }
+            query.define_singleton_method(:inspect) { self.results.to_a.inspect }
+
             return query if block.nil?
             query.results(&block)
           end
@@ -255,13 +524,16 @@ module Parse
         end # has_many_array
       end #ClassMethods
 
-      # provides a hash list of all relations to this class.
+      # A hash list of all has_many associations that use a Parse Relation.
+      # @return [Hash]
+      # @see Associations::HasMany.relations
       def relations
         self.class.relations
       end
 
-      # returns a hash of all the relation changes that have been performed on this
-      # instance.
+      # A hash of all the relation changes that have been performed on this
+      #  instance. This is only used when the association uses Parse Relations.
+      # @return [Hash]
       def relation_updates
         h = {}
         changed.each do |key|
@@ -272,7 +544,8 @@ module Parse
         h
       end
 
-      # true if this object has any relation changes
+      # @return [Boolean] true if there are pending relational changes for
+      #  associations defined using Parse Relations.
       def relation_changes?
         changed.any? { |key| relations[key.to_sym] }
       end