parse-stack-next 4.5.0

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

@@ -0,0 +1,597 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "../pointer"
+require_relative "collection_proxy"
+require_relative "pointer_collection_proxy"
+require_relative "relation_collection_proxy"
+
+module Parse
+  module Associations
+
+    # 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
+    # {http://docs.parseplatform.org/js/guide/#relations 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.
+    # *Note:* 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 {http://docs.parseplatform.org/js/guide/#many-to-many 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://docs.parseplatform.org/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 using the methods below. Parse allows this by providing a specific atomic operation
+    # request. 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 }
+    #
+    # You can also perform queries against class entities to find related objects. Assume
+    # that users can like a band. The `Band` class can have a `likes` column that is
+    # a Parse relation to the {Parse::User} class containing the users who have liked a
+    # specific band.
+    #
+    #
+    #   class Band < Parse::Object
+    #     # likes is a Parse relation column of user objects.
+    #     has_many :likes, through: :relation, as: :user
+    #   end
+    #
+    # You can now find all {Parse::User} records who have liked a specific band. In the
+    # example below, the `:likes` key refers to the `likes` column defined in the `Band`
+    # collection which contains the set of user records.
+    #
+    #   band = Band.first # get a band
+    #
+    #   # find all users who have liked this band, where :likes is a column
+    #   # in the Band collection - NOT in the User collection.
+    #   users = Parse::User.all :likes.related_to => band
+    #
+    # You can also find all bands that a specific user has liked.
+    #
+    #   user = Parse::User.first
+    #
+    #   # find all bands where this user
+    #   # is in the `likes` column of the Band collection
+    #   bands_liked_by_user = Band.all :likes => user
+    #
+    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_writer :relations
+
+        def relations
+          @relations ||= {}
+        end
+
+        # Examples:
+        # has_many :fans, as: :users, through: :relation, field: "awesomeFans"
+        # has_many :songs
+        # has_many :likes, as: :users, through: :relation
+        # has_many :artists, field: "managedArtists"
+        # The first item in the has_many is the name of the local attribute. This will create
+        # several methods for accessing the relation type. By default, the remote column name
+        # relating to this attribute will be the lower-first-camelcase version of this key.
+        # Ex. a relation to :my_songs, would imply that the remote column name is "mySongs". This behavior
+        # can be overriden by using the field: option and passing the literal field name in the Parse table.
+        # This allows you to use a local attribute name while still having a different remote column name.
+        # Since these types of collections are of a particular "type", we will assume that the name of the
+        # key is the plural version of the name of the local camelized-named class. Ex. If the property is named :songs, then
+        # we will assume there is a local class name defined as 'Song'. This can be overriden by using the as: parameter.
+        # This allows you to name your local attribute differently to what the responsible class for this association.
+        # Ex. You could define a has_many :favorite_songs property that points to the User class by using the 'as: :songs'. This would
+        # imply that the instance object has a set of Song objects through the attribute :favorite_songs.
+        # By default, all associations are stored in 'through: :array' form. If you are working with a Parse Relation, you
+        # should specify the 'through: :relation' property instead. This will switch the internal storage mechanisms
+        # from using a PointerCollectionProxy to a RelationCollectionProxy.
+        def has_many_queried(key, scope = nil, **opts)
+          # key will be the name of the property
+          # the remote class is either key or as.
+          opts[:scope_only] ||= false
+          klassName = (opts[:as] || key).to_parse_class singularize: true
+          foreign_field = (opts[:field] || parse_class.columnize).to_sym
+
+          define_method(key) do |*args, &block|
+            return [] if @id.nil?
+            query = Parse::Query.new(klassName, limit: :max)
+
+            query.where(foreign_field => self) unless opts[:scope_only] == true
+
+            if scope.is_a?(Proc)
+              # magic, override the singleton method_missing with accessing object level methods
+              # that don't collide with Parse::Query instance. Still accessible under :i
+              instance = self
+              query.define_singleton_method(:method_missing) { |m, *args, &block| instance.send(m, *args, &block) }
+              query.define_singleton_method(:i) { instance }
+              # if the scope takes no arguments, assume arguments are additional conditions
+              if scope.arity.zero?
+                query.instance_exec(&scope)
+                query.conditions(*args) if args.present?
+              else
+                query.instance_exec(*args, &scope)
+              end
+              instance = nil # help clean up ruby gc
+            elsif args.present?
+              query.conditions(*args)
+            end
+
+            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) # 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
+              results.send(m, *args, &chained_block)
+            end
+
+            Parse::Query.apply_auto_introspection!(query)
+
+            return query if block.nil?
+            query.results(&block)
+          end
+        end
+
+        # Define a one-to-many or many-to-many association between the local model and a foreign class.
+        def has_many(key, scope = nil, **opts)
+          opts[:through] ||= :query
+
+          if opts[:through] == :query
+            return has_many_queried(key, scope, **opts)
+          end
+
+          # below this is the same
+          opts.reverse_merge!({
+            field: key.to_s.camelize(:lower),
+            required: false,
+            as: key,
+          })
+
+          klassName = opts[:as].to_parse_class singularize: true
+          parse_field = opts[:field].to_sym # name of the column (local or remote)
+          access_type = opts[:through].to_sym
+
+          ivar = :"@#{key}"
+          will_change_method = :"#{key}_will_change!"
+          set_attribute_method = :"#{key}_set_attribute!"
+
+          # verify that the user did not duplicate properties or defined different properties with the same name
+          if self.fields[key].present? && Parse::Properties::BASE_FIELD_MAP[key].nil?
+            warn "Has_many property #{self}##{key} already defined with type #{klassName}"
+            return false
+          end
+          if self.fields[parse_field].present?
+            warn "Alias has_many #{self}##{parse_field} conflicts with previously defined property."
+            return false
+          end
+          # validations
+          validates_presence_of(key) if opts[:required]
+
+          # default proxy class.
+          proxyKlass = Parse::PointerCollectionProxy
+
+          #if this is a relation type, use this proxy instead. Relations are stored
+          # in the relations hash. If a PointerCollectionProxy is used, we store those
+          # as we would normal properties.
+          if access_type == :relation
+            proxyKlass = Parse::RelationCollectionProxy
+            self.relations[key] = klassName
+          else
+            self.attributes.merge!(parse_field => :array)
+            # Add them to the list of fields in our class model
+            self.fields.merge!(key => :array, parse_field => :array)
+          end
+
+          self.field_map.merge!(key => parse_field)
+          # dirty tracking
+          define_attribute_methods key
+
+          # The first method to be defined is a getter.
+          define_method(key) do
+            val = instance_variable_get(ivar)
+            # if the value for this is nil and we are a pointer, or if this is a
+            # selectively fetched object and this field wasn't included, then autofetch
+            should_autofetch = val.nil? && (pointer? || (has_selective_keys? && !field_was_fetched?(key)))
+            if should_autofetch
+              # If autofetch is disabled and we're accessing an unfetched field on a
+              # selectively fetched object, raise an error to make the issue explicit
+              if autofetch_disabled? && has_selective_keys? && !field_was_fetched?(key)
+                raise Parse::UnfetchedFieldAccessError.new(key, self.class.name)
+              end
+              autofetch!(key)
+              val = instance_variable_get ivar
+            end
+
+            # if the result is not a collection proxy, then create a new one.
+            unless val.is_a?(Parse::PointerCollectionProxy)
+              results = []
+              #results = val.parse_objects if val.respond_to?(:parse_objects)
+              val = proxyKlass.new results, delegate: self, key: key
+              instance_variable_set(ivar, val)
+            end
+            val
+          end
+
+          # proxy setter that forwards with dirty tracking
+          define_method("#{key}=") do |val|
+            send set_attribute_method, val, true
+          end
+
+          # This will set the content of the proxy.
+          define_method(set_attribute_method) do |val, track = true|
+            # If it is a hash, with a __type of Relation, createa a new RelationCollectionProxy, regardless
+            # of what is defined because we must have gotten this from Parse.
+
+            # if val is nil or it is the delete operation, then set to empty array.
+            # this will create a new proxyKlass later on
+            if val.nil? || val == Parse::Properties::DELETE_OP
+              val = []
+            end
+
+            # Always trust the declared klassName — never the className the
+            # server (or attacker-controlled mass assignment) supplied.
+            # Prevents type-confusion attacks that would mark this relation
+            # proxy as a different parse_class than the model declared.
+            if val.is_a?(Hash) && val[Parse::Model::KEY_CLASS_NAME] &&
+               val[Parse::Model::KEY_CLASS_NAME] != klassName &&
+               %w[Relation].include?(val["__type"])
+              warn "[#{self.class}] has_many :#{key} expected className=#{klassName.inspect}, ignoring incoming className=#{val[Parse::Model::KEY_CLASS_NAME].inspect}"
+            end
+            if val.is_a?(Hash) && val["__type"] == "Relation"
+              relation_objects = val["objects"] || []
+              val = Parse::RelationCollectionProxy.new relation_objects, delegate: self, key: key, parse_class: klassName
+            elsif val.is_a?(Hash) && val["__op"] == "AddRelation" && val["objects"].present?
+              _collection = proxyKlass.new [], delegate: self, key: key, parse_class: klassName
+              _collection.loaded = true
+              _collection.add val["objects"].parse_objects(klassName)
+              val = _collection
+            elsif val.is_a?(Hash) && val["__op"] == "RemoveRelation" && val["objects"].present?
+              _collection = proxyKlass.new [], delegate: self, key: key, parse_class: klassName
+              _collection.loaded = true
+              _collection.remove val["objects"].parse_objects(klassName)
+              val = _collection
+            elsif val.is_a?(Array)
+              # Otherwise create a new collection based on what the user
+              # defined; always coerce array elements to the declared class.
+              val = proxyKlass.new val.parse_objects(klassName), delegate: self, key: key, parse_class: klassName
+            end
+
+            # send dirty tracking if set
+            if track == true
+              prepare_for_dirty_tracking!(key)
+              send will_change_method unless val == instance_variable_get(ivar)
+            end
+            # TODO: Only allow empty proxy collection class as a value or nil.
+            if val.is_a?(Parse::CollectionProxy)
+              instance_variable_set(ivar, val)
+            else
+              warn "[#{self.class}] Invalid value #{val} for :has_many field #{key}. Should be an Array or a CollectionProxy"
+            end
+          end
+
+          data_type = opts[:through]
+          # if the type is a relation association, add these methods to the delegate
+          #   that will be used when creating the collection proxies. See Collection proxies
+          #   for more information.
+          if data_type == :relation
+            # return a query given the foreign table class name.
+            define_method("#{key}_relation_query") do
+              Parse::Query.new(klassName, key.to_sym.related_to => self.pointer, limit: :max)
+            end
+            # fetch the contents of the relation
+            define_method("#{key}_fetch!") do
+              q = self.send :"#{key}_relation_query"
+              q.results || []
+            end
+          end
+
+          # if the remote field name and the local field name are the same
+          # don't create alias methods
+          return if parse_field.to_sym == key.to_sym
+
+          if self.method_defined?(parse_field) == false
+            alias_method parse_field, key
+            alias_method "#{parse_field}=", "#{key}="
+            alias_method "#{parse_field}_set_attribute!", set_attribute_method
+          elsif parse_field.to_sym != :objectId
+            warn "Alias has_many method #{self}##{parse_field} already defined."
+          end
+        end # has_many_array
+      end #ClassMethods
+
+      # 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
+
+      # 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|
+          next unless relations[key.to_sym].present? && send(key).changed?
+          remote_field = self.field_map[key.to_sym] || key
+          h[remote_field] = send key # we still need to send a proxy collection
+        end
+        h
+      end
+
+      # @return [Boolean] true if there are pending relational changes for
+      def relation_changes?
+        changed.any? { |key| relations[key.to_sym] }
+      end
+    end # HasMany
+  end #Associations
+end # Parse