parse-stack 1.0.0

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

@@ -0,0 +1,121 @@
+require_relative '../pointer'
+require_relative 'collection_proxy'
+require_relative 'pointer_collection_proxy'
+require_relative 'relation_collection_proxy'
+
+# BelongsTo relation is the simplies association in which the local
+# table constains a column that points to a foreign table record using
+# a given Parse Pointer. The key of the property is implied to be the
+# name of the class/parse table that contains the foreign associated record.
+# All belongs to relationship column types have the special data type of :pointer.
+module Parse
+  module Associations
+
+    module BelongsTo
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        attr_accessor :references
+        # We can keep references to all "belong_to" properties
+        def references
+          @references ||= {}
+        end
+
+        # belongs_to :featured_song, as: :song, field: :featuredSong, through: :reference
+        # belongs_to :artist
+        # belongs_to :manager, as: :user
+        # These items are added as attributes with the special data type of :pointer
+        def belongs_to(key, opts = {})
+          opts = {as: key, field: key.to_s.camelize(:lower), required: false}.merge(opts)
+          className = opts[:as].to_parse_class
+          parse_field = opts[:field].to_sym
+          if self.fields[key].present? && Parse::Properties::BASE_FIELD_MAP[key].nil?
+            raise Parse::Properties::DefinitionError, "Belongs relation #{self}##{key} already defined with type #{className}"
+          end
+          if self.fields[parse_field].present?
+            raise Parse::Properties::DefinitionError, "Alias belongs_to #{self}##{parse_field} conflicts with previously defined property."
+          end
+          # store this attribute in the attributes hash with the proper remote column name.
+          # we know the type is pointer.
+          self.attributes.merge!( parse_field => :pointer )
+          # Add them to our list of pointer references
+          self.references.merge!( parse_field => className )
+          # Add them to the list of fields in our class model
+          self.fields.merge!( key => :pointer, parse_field => :pointer )
+          # Mapping between local attribute name and the remote column name
+          self.field_map.merge!( key => parse_field )
+
+          # used for dirty tracking
+          define_attribute_methods key
+
+          # validations
+          validates_presence_of(key) if opts[:required]
+
+          # We generate the getter method
+          define_method(key) do
+            ivar = :"@#{key}"
+            val = instance_variable_get ivar
+            # We provide autofetch functionality. If the value is nil and the
+            # current Parse::Object is a pointer, then let's auto fetch it
+            if val.nil? && pointer?
+              autofetch!(key)
+              val = instance_variable_get ivar
+            end
+
+            # if for some reason we retrieved either from store or fetching a
+            # hash, lets try to buid a Pointer of that type.
+
+            if val.is_a?(Hash) && ( val["__type"].freeze == "Pointer".freeze ||  val["__type"].freeze == "Object".freeze )
+              val = Parse::Object.build val, ( val["className"] || className )
+              instance_variable_set ivar, val
+            end
+            val
+          end
+
+          define_method("#{key}?") do
+            self.send(key).is_a?(Parse::Pointer)
+          end
+
+          # A proxy setter method that has dirty tracking enabled.
+          define_method("#{key}=") do |val|
+            send "#{key}_set_attribute!", val, true
+          end
+
+          # We only support pointers, either by object or by transforming a hash.
+          define_method("#{key}_set_attribute!") do |val, track = true|
+            if val.is_a?(Hash) && ( val["__type"].freeze == "Pointer".freeze ||  val["__type"].freeze == "Object".freeze )
+              val = Parse::Object.build val, ( val["className"] || className )
+            end
+            if track == true
+              send :"#{key}_will_change!" unless val == instance_variable_get( :"@#{key}" )
+            end
+            # Never set an object that is not a Parse::Pointer
+            if val.nil? || val.is_a?(Parse::Pointer)
+              instance_variable_set(:"@#{key}", val)
+            else
+              warn "[#{self.class}] Invalid value #{val} set for belongs_to field #{key}"
+            end
+
+          end
+          # don't create method aliases if the fields are the same
+          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!", "#{key}_set_attribute!"
+          elsif parse_field.to_sym != :objectId
+            warn "Alias belongs_to method #{self}##{parse_field} already defined."
+          end
+
+        end
+
+      end # ClassMethod
+
+    end #BelongsTo
+  end #Associations
+
+end

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

@@ -0,0 +1,202 @@
+require 'active_model'
+require 'active_support'
+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
+
+    class CollectionProxy
+      include ::ActiveModel::Model
+      include ::ActiveModel::Dirty
+
+      attr_accessor :collection, :delegate, :loaded
+      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.
+      def initialize(collection = nil, delegate: nil, key: nil, parse_class: nil)
+        @delegate = delegate
+        @key = key.to_sym if key.present?
+        @collection = collection.is_a?(Array) ? collection : []
+        @loaded = @collection.count > 0
+        @parse_class = parse_class
+      end
+
+      def loaded?
+        @loaded
+      end
+
+      # helper method to forward a message to the delegate
+      def forward(method, params = nil)
+        return unless @delegate.present? && @delegate.respond_to?(method)
+        params.nil? ? @delegate.send(method) : @delegate.send(method, params)
+      end
+
+      def reset!
+        @loaded = false
+        clear
+      end
+
+      def ==(other_list)
+        if other_list.is_a?(Array)
+          return @collection == other_list
+        elsif other_list.is_a?(Parse::CollectionProxy)
+          return @collection == other_list.instance_variable_get(:@collection)
+        end
+      end
+
+      def reload!
+        reset!
+        collection #force reload
+      end
+
+      def clear
+        @collection.clear
+      end
+
+      def to_ary
+        collection.to_a
+      end; alias_method :to_a, :to_ary
+
+      # lazy loading of a collection. If empty and not loaded, then forward _fetch!
+      # to the delegate
+      def collection
+        if @collection.empty? && @loaded == false
+          @collection = forward( :"#{@key}_fetch!" ) || @collection || []
+          @loaded = true
+        end
+
+        @collection
+      end
+
+      def collection=(c)
+        notify_will_change!
+        @collection = c
+      end
+
+      # Method to add items to the collection.
+      def add(*items)
+        notify_will_change! if items.count > 0
+        items.each do |item|
+          collection.push item
+        end
+        @collection
+      end; alias_method :push, :add
+      
+      # Remove items from the collection
+      def remove(*items)
+        notify_will_change! if items.count > 0
+        items.each do |item|
+          collection.delete item
+        end
+        @collection
+      end; alias_method :delete, :remove
+      
+      def add!(*items)
+        return false unless @delegate.respond_to?(:op_add!)
+        @delegate.send :op_add!, @key, items
+        reset!
+      end
+      
+      def add_unique!(*items)
+        return false unless @delegate.respond_to?(:op_add_unique!)
+        @delegate.send :op_add_unique!, @key, items
+        reset!
+      end
+      
+      def remove!(*items)
+        return false unless @delegate.respond_to?(:op_remove!)
+        @delegate.send :op_remove!, @key, items
+        reset!
+      end
+      
+      def destroy!
+        return false unless @delegate.respond_to?(:op_destroy!)
+        @delegate.send :op_destroy!, @key
+        collection_will_change!
+        @collection.clear
+        reset!
+      end
+
+      def rollback!
+        restore_attributes
+      end
+
+      def clear_changes!
+        clear_changes_information
+      end
+
+      def changes_applied!
+        changes_applied
+      end
+
+      def first(*args)
+        collection.first(*args)
+      end
+
+      def second
+        collection.second
+      end
+
+      def last(*args)
+        collection.last(*args)
+      end
+
+      def count
+        collection.count
+      end
+
+      def as_json(*args)
+        collection.as_json(args)
+      end
+
+      def empty?
+        collection.empty?
+      end
+
+      # append items to the array
+      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
+      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
+      end
+
+      def inspect
+        "#<#{self.class} changed?=#{changed?} @collection=#{@collection.inspect} >"
+      end
+
+    end
+
+
+
+  end

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

@@ -0,0 +1,218 @@
+require_relative '../pointer'
+require_relative 'collection_proxy'
+require_relative 'pointer_collection_proxy'
+require_relative 'relation_collection_proxy'
+
+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.
+    module HasMany
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        attr_accessor :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(key, opts = {})
+          opts = {through: :array,
+                  field: key.to_s.camelize(:lower),
+                  required: false,
+                  as: key}.merge(opts)
+
+          klassName = opts[:as].to_parse_class
+          parse_field = opts[:field].to_sym
+          access_type = opts[:through].to_sym
+          # 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?
+            raise Parse::Properties::DefinitionError, "Has_many property #{self}##{key} already defined with type #{klassName}"
+          end
+          if self.fields[parse_field].present?
+            raise Parse::Properties::DefinitionError, "Alias has_many #{self}##{parse_field} conflicts with previously defined property."
+          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
+            ivar = :"@#{key}"
+            val = instance_variable_get(ivar)
+            # if the value for this is nil and we are a pointer, then autofetch
+            if val.nil? && pointer?
+              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 "#{key}_set_attribute!", val, true
+          end
+
+          # This will set the content of the proxy.
+          define_method("#{key}_set_attribute!") 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.
+            val = [] if val.nil?
+
+            if val.is_a?(Hash) && val["__type"] == "Relation"
+              relation_objects = val["objects"] || []
+              val = Parse::RelationCollectionProxy.new relation_objects, delegate: self, key: key, parse_class: (val["className"] || klassName)
+            elsif val.is_a?(Hash) && val["__op"] == "AddRelation" && val["objects"].present?
+              _collection = proxyKlass.new [], delegate: self, key: key, parse_class: (val["className"] || klassName)
+              _collection.loaded = true
+              _collection.add val["objects"].parse_objects
+              val = _collection
+            elsif val.is_a?(Hash) && val["__op"] == "RemoveRelation" && val["objects"].present?
+              _collection = proxyKlass.new [], delegate: self, key: key, parse_class: (val["className"] || klassName)
+              _collection.loaded = true
+              _collection.remove val["objects"].parse_objects
+              val = _collection
+            elsif val.is_a?(Array)
+              # Otherwise create a new collection based on what the user defined.
+              val = proxyKlass.new val.parse_objects, delegate: self, key: key, parse_class: klassName
+            end
+
+            # send dirty tracking if set
+            if track == true
+              send :"#{key}_will_change!" unless val == instance_variable_get( :"@#{key}" )
+            end
+            # TODO: Only allow empty proxy collection class as a value or nil.
+            if val.is_a?(Parse::CollectionProxy)
+              instance_variable_set(:"@#{key}", 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!", "#{key}_set_attribute!"
+          elsif parse_field.to_sym != :objectId
+            warn "Alias has_many method #{self}##{parse_field} already defined."
+          end
+
+
+        end # has_many_array
+      end #ClassMethods
+
+      # provides a hash list of all relations to this class.
+      def relations
+        self.class.relations
+      end
+
+      # returns a has of all the relation changes that have been performed on this
+      # instance.
+      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
+        end
+        h
+      end
+
+      # true if this object has any relation changes
+      def relation_changes?
+        changed.any? { |key| relations[key.to_sym] }
+      end
+
+    end # HasMany
+  end #Associations
+
+
+end # Parse