parse-stack-next 4.5.0

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

@@ -0,0 +1,158 @@
+# 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
+    # The `has_one` creates a one-to-one association with another Parse class.
+    # This association says that the other class in the association contains a
+    # foreign pointer column which references instances of this class. If your
+    # model contains a column that is a Parse pointer to another class, you should
+    # use `belongs_to` for that association instead.
+    #
+    # Defining a `has_one` property generates a helper query method to fetch a
+    # particular record from a foreign class. This is useful for setting up the
+    # inverse relationship accessors of a `belongs_to`. In the case of the
+    # `has_one` relationship, the `:field` option represents the name of the
+    # column of the foreign class where the Parse pointer is stored. By default,
+    # the lower-first camel case version of the Parse class name is used.
+    #
+    # In the example below, a `Band` has a local column named `manager` which has
+    # a pointer to a `Parse::User` (_:user_) record. This setups up the accessor for `Band`
+    # objects to access the band's manager.
+    #
+    # Since we know there is a column named `manager` in the `Band` class that
+    # points to a single `Parse::User`, you can setup the inverse association
+    # read accessor in the `Parse::User` class. Note, that to change the
+    # association, you need to modify the `manager` property on the band instance
+    # since it contains the `belongs_to` property.
+    #
+    #  # every band has a manager
+    #  class Band < Parse::Object
+    #    belongs_to :manager, as: :user
+    #  end
+    #
+    #  band = Band.first id: '12345'
+    #  # the user represented by this manager
+    #  user = band.manger
+    #
+    #  # every user manages a band
+    #  class Parse::User
+    #    # inverse relationship to `Band.belongs_to :manager`
+    #    has_one :band, field: :manager
+    #  end
+    #
+    #  user = Parse::User.first
+    #
+    #  user.band # similar to performing: Band.first(:manager => user)
+    #
+    #
+    # You may optionally use `has_one` with scopes, in order to fine tune the
+    # query result. Using the example above, you can customize the query with
+    # a scope that only fetches the association if the band is approved. If
+    # the association cannot be fetched, `nil` is returned.
+    #
+    #  # adding to previous example
+    #  class Band < Parse::Object
+    #    property :approved, :boolean
+    #    property :approved_date, :date
+    #  end
+    #
+    #  # every user manages a band
+    #  class Parse::User
+    #    has_one :recently_approved, ->{ where(order: :approved_date.desc) }, field: :manager, as: :band
+    #    has_one :band_by_status, ->(status) { where(approved: status) },  field: :manager, as: :band
+    #  end
+    #
+    #  # gets the band most recently approved
+    #  user.recently_approved
+    #  # equivalent: Band.first(manager: user, order: :approved_date.desc)
+    #
+    #  # fetch the managed band that is not approved
+    #  user.band_by_status(false)
+    #  # equivalent: Band.first(manager: user, approved: false)
+    #
+    # @see Parse::Associations::BelongsTo
+    # @see Parse::Associations::HasMany
+    module HasOne
+
+      # @!method self.has_one(key, scope = nil, opts = {})
+      # Creates a one-to-one association with another Parse model.
+      # @param [Symbol] key The singularized version of the foreign class and the name of the
+      #   *foreign* column in the foreign Parse table where the pointer is stored.
+      # @param [Proc] scope A proc that can customize the query by applying
+      #   additional constraints when fetching the associated record. Works similarly as
+      #   ActiveModel associations described in section {http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html Customizing the Query}
+      # @option opts [Symbol] :field override the name of the remote column
+      #  where the pointer is stored. By default this is inferred as
+      #  the columnized of the key parameter.
+      # @option opts [Symbol] :as override the inferred Parse::Object subclass.
+      #  By default this is inferred as the singularized camel case version of
+      #  the key parameter. This option allows you to override the Parse model used
+      #  to perform the query for the association, while allowing you to have a
+      #  different accessor name.
+      # @option opts [Boolean] scope_only Setting this option to `true`,
+      #  makes the association fetch based only on the scope provided and does
+      #  not use the local instance object as a foreign pointer in the query.
+      #  This allows for cases where another property of the local class, is
+      #  needed to match the resulting records in the association.
+      # @see String#columnize
+      # @see Associations::HasMany.has_many
+      # @return [Parse::Object] a Parse::Object subclass when using the accessor
+      #  when fetching the association.
+
+      # @!visibility private
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # @!visibility private
+      module ClassMethods
+
+        # has one are not property but instance scope methods
+        def has_one(key, scope = nil, **opts)
+          opts.reverse_merge!({ as: key, field: parse_class.columnize, scope_only: false })
+          klassName = opts[:as].to_parse_class
+          foreign_field = opts[:field].to_sym
+          _ivar = :"@_has_one_#{key}" # reserved for future caching
+
+          if self.method_defined?(key)
+            warn "Creating has_one :#{key} association. Will overwrite existing method #{self}##{key}."
+          end
+
+          define_method(key) do |*args, &block|
+            return nil if @id.nil?
+            query = Parse::Query.new(klassName, limit: 1)
+            query.where(foreign_field => self) unless opts[:scope_only] == true
+
+            if scope.is_a?(Proc)
+              # any method not part of Query, gets delegated to the instance object
+              instance = self
+              query.define_singleton_method(:method_missing) { |m, *args, &block| instance.send(m, *args, &block) }
+              query.define_singleton_method(:i) { instance }
+
+              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, &block|
+            #   self.first.send(m, *args, &block)
+            # end
+            return query.first if block.nil?
+            block.call(query.first)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext/object"
+require_relative "collection_proxy"
+
+module Parse
+  # A PointerCollectionProxy is a collection proxy that only allows Parse Pointers (Objects)
+  # to be part of the collection. This is done by typecasting the collection to a particular
+  # Parse class. Ex. An Artist may have several Song objects. Therefore an Artist could have a
+  # column :songs, that is an array (collection) of Song (Parse::Object subclass) objects.
+  class PointerCollectionProxy < CollectionProxy
+
+    # @!attribute [rw] collection
+    #  The internal backing store of the collection.
+    #  @note If you modify this directly, it is highly recommended that you
+    #   call {CollectionProxy#notify_will_change!} to notify the dirty tracking system.
+    #  @return [Array<Parse::Object>]
+    #  @see CollectionProxy#collection
+    def collection=(c)
+      notify_will_change!
+      @collection = c
+    end
+
+    # Add Parse::Objects to the collection.
+    # @overload add(parse_object)
+    #  Add a Parse::Object or Parse::Pointer to this collection.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to add
+    # @overload add(parse_objects)
+    #  Add an array of Parse::Objects or Parse::Pointers to this collection.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array to append.
+    # @return [Array<Parse::Object>] the collection
+    def add(*items)
+      notify_will_change! if items.count > 0
+      items.flatten.parse_objects.each do |item|
+        collection.push(item) if item.is_a?(Parse::Pointer)
+      end
+      @collection
+    end
+
+    # Removes Parse::Objects from the collection.
+    # @overload remove(parse_object)
+    #  Remove a Parse::Object or Parse::Pointer to this collection.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to remove
+    # @overload remove(parse_objects)
+    #  Remove an array of Parse::Objects or Parse::Pointers from this collection.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array of objects to remove.
+    # @return [Array<Parse::Object>] the collection
+    def remove(*items)
+      notify_will_change! if items.count > 0
+      items.flatten.parse_objects.each do |item|
+        collection.delete item
+      end
+      @collection
+    end
+
+    # Atomically add a set of Parse::Objects to this collection.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    # @see CollectionProxy#add!
+    # @see #add_unique!
+    def add!(*items)
+      super(items.flatten.parse_pointers)
+    end
+
+    # Atomically add a set of Parse::Objects to this collection for those not already
+    # in the collection.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    # @see CollectionProxy#add_unique!
+    # @see #add!
+    def add_unique!(*items)
+      super(items.flatten.parse_pointers)
+    end
+
+    # Atomically remove a set of Parse::Objects to this collection.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    # @see CollectionProxy#remove!
+    def remove!(*items)
+      super(items.flatten.parse_pointers)
+    end
+
+    # Force fetch the set of pointer objects in this collection.
+    # @see Array.fetch_objects!
+    def fetch!
+      collection.fetch_objects!
+    end
+
+    # Fetch the set of pointer objects in this collection.
+    # @see Array.fetch_objects
+    def fetch
+      collection.fetch_objects
+    end
+
+    # Encode the collection as JSON.
+    # By default, returns Parse::Pointers for backward compatibility when saving.
+    # Set `pointers_only: false` to get full hydrated objects for API responses.
+    # @param opts [Hash] options for serialization
+    # @option opts [Boolean] :pointers_only (true) When true (default), converts all
+    #   Parse objects to pointer format. Set to false to serialize full objects.
+    # @option opts [Boolean] :only_fetched (true) When true (default when pointers_only
+    #   is false), only serialize fields that were actually fetched. This prevents
+    #   autofetch from being triggered during serialization of partially hydrated objects.
+    # @example Default - pointers for storage
+    #   capture.assets.as_json
+    #   # => [{"__type"=>"Pointer", "className"=>"Asset", "objectId"=>"abc"}, ...]
+    # @example Full objects for API responses (only fetched fields, no autofetch)
+    #   capture.assets.as_json(pointers_only: false)
+    #   # => [{"objectId"=>"abc", "file"=>{...}, "caption"=>"...", ...}, ...]
+    def as_json(opts = nil)
+      opts ||= {}
+
+      # Normalize string keys to symbols to avoid conflicts with defaults
+      opts = opts.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+
+      # Check if pointers_only was explicitly set, otherwise default to true
+      pointers_only = opts.fetch(:pointers_only, true)
+
+      # Default to pointers_only: true for backward compatibility
+      # When pointers_only is false, default only_fetched to true to prevent
+      # autofetch during serialization of partially hydrated objects
+      defaults = { pointers_only: true }
+      unless pointers_only
+        defaults[:only_fetched] = true unless opts.key?(:only_fetched)
+      end
+      opts = defaults.merge(opts)
+      super(opts)
+    end
+  end
+end

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

@@ -0,0 +1,177 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext/object"
+require_relative "pointer_collection_proxy"
+
+module Parse
+  # The RelationCollectionProxy is similar to a PointerCollectionProxy except that
+  # there is no actual "array" object in Parse. Parse treats relation through an
+  # intermediary table (a.k.a. join table). Whenever a developer wants the
+  # contents of a collection, the foreign table needs to be queried instead.
+  # In this scenario, the parse_class: initializer argument should be passed in order to
+  # know which remote table needs to be queried in order to fetch the items of the collection.
+  #
+  # Unlike managing an array of Pointers, relations in Parse are done throug atomic operations,
+  # which have a specific API. The design of this proxy is to maintain two sets of lists,
+  # items to be added to the relation and a separate list of items to be removed from the
+  # relation.
+  #
+  # Because this relationship is based on queryable Parse table, we are also able to
+  # not just get all the items in a collection, but also provide additional constraints to
+  # get matching items within the relation collection.
+  #
+  # When creating a Relation proxy, all the delegate methods defined in the superclasses
+  # need to be implemented, in addition to a few others with the key parameter:
+  # _relation_query and _commit_relation_updates . :'key'_relation_query should return a
+  # Parse::Query object that is properly tied to the foreign table class related to this object column.
+  # Example, if an Artist has many Song objects, then the query to be returned by this method
+  # should be a Parse::Query for the class 'Song'.
+  # Because relation changes are separate from object changes, you can call save on a
+  # relation collection to save the current add and remove operations. Because the delegate needs
+  # to be informed of the changes being committed, it will be notified
+  # through :'key'_commit_relation_updates message. The delegate is also in charge of
+  # clearing out the change information for the collection if saved successfully.
+  # @see PointerCollectionProxy
+  class RelationCollectionProxy < PointerCollectionProxy
+    define_attribute_methods :additions, :removals
+    # @!attribute [r] removals
+    #  The objects that have been newly removed to this collection
+    # @return [Array<Parse::Object>]
+    # @!attribute [r] additions
+    #  The objects that have been newly added to this collection
+    # @return [Array<Parse::Object>]
+    attr_reader :additions, :removals
+
+    def initialize(collection = nil, delegate: nil, key: nil, parse_class: nil)
+      super
+      @additions = []
+      @removals = []
+    end
+
+    # You can get items within the collection relation filtered by a specific set
+    # of query constraints.
+    def all(constraints = {}, &block)
+      q = query({ limit: :max }.merge(constraints))
+      if block_given?
+        # if we have a query, then use the Proc with it (more efficient)
+        return q.present? ? q.results(&block) : collection.each(&block)
+      end
+      # if no block given, get all the results
+      q.present? ? q.results : collection
+    end
+
+    # Ask the delegate to return a query for this collection type
+    def query(constraints = {})
+      q = forward :"#{@key}_relation_query"
+
+      # Apply constraints if provided (excluding limit which is handled differently)
+      query_constraints = constraints.except(:limit)
+      if query_constraints.present?
+        q = q.where(query_constraints)
+      end
+
+      # Apply limit if specified
+      if constraints[:limit].present?
+        q = q.limit(constraints[:limit])
+      end
+
+      q
+    end
+
+    # Return a query with limit applied - allows chaining like relation.limit(5).all
+    def limit(count)
+      query(limit: count)
+    end
+
+    # Add Parse::Objects to the relation.
+    # @overload add(parse_object)
+    #  Add a Parse::Object or Parse::Pointer to this relation.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to add
+    # @overload add(parse_objects)
+    #  Add an array of Parse::Objects or Parse::Pointers to this relation.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array to append.
+    # @return [Array<Parse::Object>] the collection
+    def add(*items)
+      items = items.flatten.parse_objects
+      return @collection if items.empty?
+
+      notify_will_change!
+      additions_will_change!
+      removals_will_change!
+      # take all the items
+      items.each do |item|
+        @additions.push item
+        @collection.push item
+        #cleanup
+        @removals.delete item
+      end
+      @collection
+    end
+
+    # Removes Parse::Objects from the relation.
+    # @overload remove(parse_object)
+    #  Remove a Parse::Object or Parse::Pointer to this relation.
+    #  @param parse_object [Parse::Object,Parse::Pointer] the object to remove
+    # @overload remove(parse_objects)
+    #  Remove an array of Parse::Objects or Parse::Pointers from this relation.
+    #  @param parse_objects [Array<Parse::Object,Parse::Pointer>] the array of objects to remove.
+    # @return [Array<Parse::Object>] the collection
+    def remove(*items)
+      items = items.flatten.parse_objects
+      return @collection if items.empty?
+      notify_will_change!
+      additions_will_change!
+      removals_will_change!
+      items.each do |item|
+        @removals.push item
+        @collection.delete item
+        # remove it from any add operations
+        @additions.delete item
+      end
+      @collection
+    end
+
+    # Atomically add a set of Parse::Objects to this relation.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    def add!(*items)
+      return false unless @delegate.respond_to?(:op_add_relation!)
+      items = items.flatten.parse_pointers
+      @delegate.send :op_add_relation!, @key, items
+    end
+
+    # Atomically add a set of Parse::Objects to this relation.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    def add_unique!(*items)
+      return false unless @delegate.respond_to?(:op_add_relation!)
+      items = items.flatten.parse_pointers
+      @delegate.send :op_add_relation!, @key, items
+    end
+
+    # Atomically remove a set of Parse::Objects to this relation.
+    # This is done by making the API request directly with Parse server; the
+    # local object is not updated with changes.
+    def remove!(*items)
+      return false unless @delegate.respond_to?(:op_remove_relation!)
+      items = items.flatten.parse_pointers
+      @delegate.send :op_remove_relation!, @key, items
+    end
+
+    # Save the changes to the relation
+    def save
+      unless @removals.empty? && @additions.empty?
+        forward :"#{@key}_commit_relation_updates"
+      end
+    end
+
+    # @see #add
+    def <<(*list)
+      list.each { |d| add(d) }
+      @collection
+    end
+  end
+end

data/lib/parse/model/bytes.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object"
+require_relative "model"
+require "base64"
+
+module Parse
+
+  # Support for the Bytes type in Parse
+  class Bytes < Model
+    # The default attributes in a Parse Bytes hash.
+    ATTRIBUTES = { __type: :string, base64: :string }.freeze
+    # @return [String] the base64 string representing the content
+    attr_accessor :base64
+    # @return [TYPE_BYTES]
+    def self.parse_class; TYPE_BYTES; end
+    # @return [TYPE_BYTES]
+    def parse_class; self.class.parse_class; end
+
+    alias_method :__type, :parse_class
+
+    # initialize with a base64 string or a Bytes object
+    # @param bytes [String] The content as base64 string.
+    def initialize(bytes = "")
+      @base64 = (bytes.is_a?(Bytes) ? bytes.base64 : bytes).dup
+    end
+
+    # @!attribute attributes
+    # Supports for mass assignment of values and encoding to JSON.
+    # @return [ATTRIBUTES]
+    def attributes
+      ATTRIBUTES
+    end
+
+    # Base64 encode and set the instance contents
+    # @param str the string to encode
+    def encode(str)
+      @base64 = Base64.encode64(str)
+    end
+
+    # Get the content as decoded base64 bytes
+    def decoded
+      Base64.decode64(@base64 || "")
+    end
+
+    def attributes=(a)
+      if a.is_a?(String)
+        @bytes = a
+      elsif a.is_a?(Hash)
+        @bytes = a["base64"] || @bytes
+      end
+    end
+
+    # Two Parse::Bytes objects are equal if they have the same base64 signature
+    def ==(u)
+      return false unless u.is_a?(self.class)
+      @base64 == u.base64
+    end
+  end
+end