parse-stack 1.5.2 → 1.5.3

data/lib/parse/api/hooks.rb

@@ -5,58 +5,101 @@ module Parse
 
 
   module API
+    # Defines the Parse webhooks interface for the Parse REST API
     module Hooks
       HOOKS_PREFIX = "hooks/"
+      # The allowed set of Parse triggers.
       TRIGGER_NAMES = [:beforeSave, :afterSave, :beforeDelete, :afterDelete].freeze
+
+      # @!visibility private
       def _verify_trigger(triggerName)
         triggerName = triggerName.to_s.camelize(:lower).to_sym
         raise ArgumentError, "Invalid trigger name #{triggerName}" unless TRIGGER_NAMES.include?(triggerName)
         triggerName
       end
 
+      # Fetch all defined cloud code functions.
+      # @return [Parse::Response]
       def functions
         request :get, "#{HOOKS_PREFIX}functions"
       end
 
+      # Fetch information about a specific registered cloud function.
+      # @param functionName [String] the name of the cloud code function.
+      # @return [Parse::Response]
       def fetch_function(functionName)
         request :get, "#{HOOKS_PREFIX}functions/#{functionName}"
       end
 
+      # Register a cloud code webhook function pointing to a endpoint url.
+      # @param functionName [String] the name of the cloud code function.
+      # @param url [String] the url endpoint for this cloud code function.
+      # @return [Parse::Response]
       def create_function(functionName, url)
         request :post, "#{HOOKS_PREFIX}functions", body: {functionName: functionName, url: url}
       end
 
+      # Updated the endpoint url for a registered cloud code webhook function.
+      # @param functionName [String] the name of the cloud code function.
+      # @param url [String] the new url endpoint for this cloud code function.
+      # @return [Parse::Response]
       def update_function(functionName, url)
-        # interesting trick. If you add _method => "PUT" to the JSON body,
+        # If you add _method => "PUT" to the JSON body,
         # and send it as a POST request and parse will accept it as a PUT.
-        # They must do this because it is easier to send POST with Ajax.
         request :put, "#{HOOKS_PREFIX}functions/#{functionName}", body: { url: url }
       end
 
+      # Remove a registered cloud code webhook function.
+      # @param functionName [String] the name of the cloud code function.
+      # @return [Parse::Response]
       def delete_function(functionName)
         request :put, "#{HOOKS_PREFIX}functions/#{functionName}", body: { __op: "Delete" }
       end
 
+      # Get the set of registered triggers.
+      # @return [Parse::Response]
       def triggers
         request :get, "#{HOOKS_PREFIX}triggers"
       end
 
+      # Fetch information about a registered webhook trigger.
+      # @param triggerName [String] the name of the trigger. (ex. beforeSave, afterSave)
+      # @param className [String] the name of the Parse collection for the trigger.
+      # @return [Parse::Response]
+      # @see TRIGGER_NAMES
       def fetch_trigger(triggerName, className)
         triggerName = _verify_trigger(triggerName)
         request :get, "#{HOOKS_PREFIX}triggers/#{className}/#{triggerName}"
       end
 
+      # Register a new cloud code webhook trigger with an endpoint url.
+      # @param triggerName [String] the name of the trigger. (ex. beforeSave, afterSave)
+      # @param className [String] the name of the Parse collection for the trigger.
+      # @param url [String] the url endpoint for this webhook trigger.
+      # @return [Parse::Response]
+      # @see Parse::API::Hooks::TRIGGER_NAMES
       def create_trigger(triggerName, className, url)
         triggerName = _verify_trigger(triggerName)
         body = {className: className, triggerName: triggerName, url: url }
         request :post, "#{HOOKS_PREFIX}triggers", body: body
       end
 
+      # Updated the registered endpoint for this cloud code webhook trigger.
+      # @param triggerName [String] the name of the trigger. (ex. beforeSave, afterSave)
+      # @param className [String] the name of the Parse collection for the trigger.
+      # @param url [String] the new url endpoint for this webhook trigger.
+      # @return [Parse::Response]
+      # @see Parse::API::Hooks::TRIGGER_NAMES
       def update_trigger(triggerName, className, url)
         triggerName = _verify_trigger(triggerName)
         request :put, "#{HOOKS_PREFIX}triggers/#{className}/#{triggerName}", body: { url: url }
       end
 
+      # Remove a registered cloud code webhook trigger.
+      # @param triggerName [String] the name of the trigger. (ex. beforeSave, afterSave)
+      # @param className [String] the name of the Parse collection for the trigger.
+      # @return [Parse::Response]
+      # @see Parse::API::Hooks::TRIGGER_NAMES
       def delete_trigger(triggerName, className)
         triggerName = _verify_trigger(triggerName)
         request :put, "#{HOOKS_PREFIX}triggers/#{className}/#{triggerName}", body: { __op: "Delete" }

data/lib/parse/api/objects.rb

@@ -9,19 +9,25 @@ module Parse
   module API
     # REST API methods for fetching CRUD operations on Parse objects.
     module Objects
-
+      # The class prefix for fetching objects.
       CLASS_PATH_PREFIX = "classes/"
+      # The class prefix mapping for fetching objects.
       PREFIX_MAP = { installation: "installations", _installation: "installations",
         user: "users", _user: "users",
         role: "roles", _role: "roles",
         session: "sessions", _session: "sessions"
       }.freeze
 
+      # @!visibility private
       def self.included(base)
         base.extend(ClassMethods)
       end
 
       module ClassMethods
+        # Get the API path for this class.
+        # @param className [String] the name of the Parse collection.
+        # @param id [String] optional objectId to add at the end of the path.
+        # @return [String] the API uri path
         def uri_path(className, id = nil)
           if className.is_a?(Parse::Pointer)
             id = className.id
@@ -37,39 +43,70 @@ module Parse
 
       end
 
+      # Get the API path for this class.
+      # @param className [String] the name of the Parse collection.
+      # @param id [String] optional objectId to add at the end of the path.
+      # @return [String] the API uri path
       def uri_path(className, id = nil)
         self.class.uri_path(className, id)
       end
 
-      # /1/classes/<className>	POST	Creating Objects
+      # Create an object in a collection.
+      # @param className [String] the name of the Parse collection.
+      # @param body [Hash] the body of the request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def create_object(className, body = {}, headers: {}, **opts)
         response = request :post, uri_path(className) , body: body, headers: headers, opts: opts
         response.parse_class = className if response.present?
         response
       end
 
-      # /1/classes/<className>/<objectId>	DELETE	Deleting Objects
+      # Delete an object in a collection.
+      # @param className [String] the name of the Parse collection.
+      # @param id [String] The objectId of the record in the collection.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def delete_object(className, id, headers: {}, **opts)
         response = request :delete, uri_path(className, id), headers: headers, opts: opts
         response.parse_class = className if response.present?
         response
       end
 
-      # /1/classes/<className>/<objectId>	GET	Retrieving Objects
+      # Fetch a specific object from a collection.
+      # @param className [String] the name of the Parse collection.
+      # @param id [String] The objectId of the record in the collection.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def fetch_object(className, id, headers: {}, **opts)
         response = request :get, uri_path(className, id), headers: headers, opts: opts
         response.parse_class = className if response.present?
         response
       end
 
-      # /1/classes/<className>	GET	Queries
+      # Fetch a set of matching objects for a query.
+      # @param className [String] the name of the Parse collection.
+      # @param query [Hash] The set of query constraints.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      # @see Parse::Query
       def find_objects(className, query = {}, headers: {}, **opts)
         response = request :get, uri_path(className), query: query, headers: headers, opts: opts
         response.parse_class = className if response.present?
         response
       end
 
-      # /1/classes/<className>/<objectId>	PUT	Updating Objects
+      # Update an object in a collection.
+      # @param className [String] the name of the Parse collection.
+      # @param id [String] The objectId of the record in the collection.
+      # @param body [Hash] The key value pairs to update.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def update_object(className, id, body = {}, headers: {}, **opts)
         response = request :put, uri_path(className,id) , body: body, headers: headers, opts: opts
         response.parse_class = className if response.present?

data/lib/parse/api/push.rb

@@ -4,9 +4,14 @@
 module Parse
 
   module API
-    #object fetch methods
+    # Defines the Parse Push notification service interface for the Parse REST API
     module Push
       PUSH_PATH = "push"
+
+      # Update the schema for a collection.
+      # @param payload [Hash] the paylod for the Push notification.
+      # @return [Parse::Response]
+      # @see https://parseplatform.github.io/docs/rest/guide/#sending-pushes Sending Pushes
       def push(payload = {})
         request :post, PUSH_PATH, body: payload.as_json
       end

data/lib/parse/api/schemas.rb

@@ -4,17 +4,31 @@
 module Parse
 
   module API
-    #object fetch methods
+    # Defines the Schema interface for the Parse REST API
     module Schema
       SCHEMAS_PATH = "schemas"
+
+      # Get the schema for a collection.
+      # @param className [String] the name of the remote Parse collection.
+      # @return [Parse::Response]
       def schema(className)
         request :get, "#{SCHEMAS_PATH}/#{className}"
       end
 
+      # Create a new collection with the specific schema.
+      # @param className [String] the name of the remote Parse collection.
+      # @param schema [Hash] the schema hash. This is a specific format specified by
+      #  Parse.
+      # @return [Parse::Response]
       def create_schema(className, schema)
         request :post, "#{SCHEMAS_PATH}/#{className}", body: schema
       end
 
+      # Update the schema for a collection.
+      # @param className [String] the name of the remote Parse collection.
+      # @param schema [Hash] the schema hash. This is a specific format specified by
+      #  Parse.
+      # @return [Parse::Response]
       def update_schema(className, schema)
         request :put, "#{SCHEMAS_PATH}/#{className}", body: schema
       end

data/lib/parse/api/sessions.rb

@@ -4,9 +4,14 @@
 module Parse
 
   module API
+    # Defines the Session class interface for the Parse REST API
     module Sessions
       SESSION_PATH_PREFIX = "sessions"
 
+      # Fetch a session record for a given session token.
+      # @param session_token [String] an active session token.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
       def fetch_session(session_token, **opts)
         opts.merge!({use_master_key: false, cache: false})
         headers = {Parse::Protocol::SESSION_TOKEN => session_token}

data/lib/parse/api/users.rb

@@ -6,24 +6,38 @@ require 'open-uri'
 module Parse
 
   module API
+    # Defines the User class interface for the Parse REST API
     module Users
-      # Note that Parse::Objects mainly use the objects.rb API since we can
-      # detect class names to proper URI handlers
+
       USER_PATH_PREFIX = "users"
       LOGOUT_PATH = "logout"
       LOGIN_PATH = "login"
       REQUEST_PASSWORD_RESET = "requestPasswordReset"
 
+      # Fetch a {Parse::User} for a given objectId.
+      # @param id [String] the user objectid
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def fetch_user(id, headers: {}, **opts)
         request :get, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
       end
 
+      # Find users matching a set of constraints.
+      # @param query [Hash] query parameters.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def find_users(query = {}, headers: {}, **opts)
         response = request :get, USER_PATH_PREFIX, query: query, headers: headers, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
         response
       end
 
+      # Find user matching this active session token.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def current_user(session_token, headers: {}, **opts)
         headers.merge!({Parse::Protocol::SESSION_TOKEN => session_token})
         response = request :get, "#{USER_PATH_PREFIX}/me", headers: headers, opts: opts
@@ -31,6 +45,11 @@ module Parse
         response
       end
 
+      # Create a new user.
+      # @param body [Hash] a hash of values related to your _User schema.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def create_user(body, headers: {}, **opts)
         headers.merge!({ Parse::Protocol::REVOCABLE_SESSION => '1'})
         if opts[:session_token].present?
@@ -41,27 +60,56 @@ module Parse
         response
       end
 
+      # Update a {Parse::User} record given an objectId.
+      # @param id [String] the Parse user objectId.
+      # @param body [Hash] the body of the API request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def update_user(id, body = {}, headers: {}, **opts)
         response = request :put, "#{USER_PATH_PREFIX}/#{id}", body: body, opts: opts
         response.parse_class = Parse::Model::CLASS_USER
         response
       end
 
-      # deleting or unlinking is done by setting the authData of the service name to nil
+      # Set the authentication service OAUth data for a user. Deleting or unlinking
+      # is done by setting the authData of the service name to nil.
+      # @param id [String] the Parse user objectId.
+      # @param service_name [Symbol] the name of the OAuth service.
+      # @param auth_data [Hash] the hash data related to the third-party service.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def set_service_auth_data(id, service_name, auth_data, headers: {}, **opts)
         body = { authData: { service_name => auth_data } }
         update_user(id, body, opts)
       end
 
+      # Delete a {Parse::User} record given an objectId.
+      # @param id [String] the Parse user objectId.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
       def delete_user(id, headers: {}, **opts)
         request :delete, "#{USER_PATH_PREFIX}/#{id}", headers: headers, opts: opts
       end
 
-      def request_password_reset(email, **opts)
+      # Request a password reset for a registered email.
+      # @param email [String] the Parse user email.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @return [Parse::Response]
+      def request_password_reset(email,  headers: {}, **opts)
         body = {email: email}
-        request :post, REQUEST_PASSWORD_RESET, body: body, opts: opts
+        request :post, REQUEST_PASSWORD_RESET, body: body, opts: opts, headers: headers
       end
 
+      # Login a user.
+      # @param username [String] the Parse user username.
+      # @param password [String] the Parse user's associated password.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
       def login(username, password, headers: {}, **opts)
         # Probably pass Installation-ID as header
         query = { username: username, password: password }
@@ -72,6 +120,11 @@ module Parse
         response
       end
 
+      # Logout a user by deleting the associated session.
+      # @param session_token [String] the Parse user session token to delete.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
       def logout(session_token, headers: {}, **opts)
         headers.merge!({ Parse::Protocol::SESSION_TOKEN => session_token})
         opts.merge!({use_master_key: false, session_token: session_token})
@@ -79,6 +132,12 @@ module Parse
       end
 
       # Signup a user given a username, password and, optionally, their email.
+      # @param username [String] the Parse user username.
+      # @param password [String] the Parse user's associated password.
+      # @param email [String] the desired Parse user's email.
+      # @param body [Hash] additional property values to pass when creating the user record.
+      # @param opts [Hash] additional options to pass to the {Parse::Client} request.
+      # @return [Parse::Response]
       def signup(username, password, email = nil, body: {}, **opts)
         body = body.merge({ username: username, password: password })
         body[:email] = email || body[:email]

data/lib/parse/client/authentication.rb

@@ -7,22 +7,37 @@ require 'active_support'
 require 'active_support/core_ext'
 
 require_relative 'protocol'
-# All Parse requests require authentication with specific header values.
-# This middleware takes all outgoing requests and adds the proper header values
-# base on the client configuration.
+
 module Parse
 
   module Middleware
-
+    # This middleware handles sending the proper authentication headers to the
+    # Parse REST API endpoint.
     class Authentication < Faraday::Middleware
       include Parse::Protocol
-      DISABLE_MASTER_KEY = "X-Disable-Parse-Master-Key"
+      DISABLE_MASTER_KEY = "X-Disable-Parse-Master-Key".freeze
+      # @return [String] the application id for this Parse endpoint.
       attr_accessor :application_id
+      # @return [String] the REST API Key for this Parse endpoint.
       attr_accessor :api_key
+      # The Master key API Key for this Parse endpoint. This is optional. If
+      # provided, it will be sent in every request.
+      # @return [String]
       attr_accessor :master_key
-      # The options hash should contain the proper keys to be added to the request.
-      def initialize(app, options = {})
-        super(app)
+
+      #
+      # @param adapter [Faraday::Adapter] An instance of the Faraday adapter
+      #  used for the connection. Defaults Faraday::Adapter::NetHttp.
+      # @param options [Hash] the options containing Parse authentication data.
+      # @option options [String] :application_id the application id.
+      # @option options [String] :api_key the REST API key.
+      # @option options [String] :master_key the Master Key for this application.
+      #  If it is set, it will be sent on every request unless this middleware sees
+      #  {DISABLE_MASTER_KEY} as an entry in the headers section.
+      # @option options [String] :content_type the content type format header. Defaults to
+      #  {Parse::Protocol::CONTENT_TYPE_FORMAT}.
+      def initialize(adapter, options = {})
+        super(adapter)
         @application_id = options[:application_id]
         @api_key = options[:api_key]
         @master_key = options[:master_key]
@@ -30,10 +45,12 @@ module Parse
       end
 
       # we dup the call for thread-safety
+      # @!visibility private
       def call(env)
         dup.call!(env)
       end
 
+      # @!visibility private
       def call!(env)
           # We add the main Parse protocol headers
           headers = {}

data/lib/parse/client/batch.rb

@@ -0,0 +1,206 @@
+
+require_relative 'request'
+require_relative 'response'
+
+
+module Parse
+  # Create a new batch operation.
+  # @param reqs [Array<Parse::Request>] a set of requests to batch.
+  # @return [BatchOperation] a new {BatchOperation} with the given change requests.
+  def self.batch(reqs = nil)
+    BatchOperation.new(reqs)
+  end
+
+  # This class provides a standard way to submit, manage and process batch operations
+  # for Parse::Objects and associations.
+  #
+  # Batch requests are supported implicitly and intelligently through an
+  # extension of array. When an array of Parse::Object subclasses is saved,
+  # Parse-Stack will batch all possible save operations for the objects in the
+  # array that have changed. It will also batch save 50 at a time until all items
+  # in the array are saved. Note: Parse does not allow batch saving Parse::User objects.
+  #
+  #  songs = Songs.first 1000 #first 1000 songs
+  #  songs.each do |song|
+  #   # ... modify song ...
+  #  end
+  #
+  #  # will batch save 50 items at a time until all are saved.
+  #  songs.save
+  #
+  # The objects do not have to be of the same collection in order to be supported in the
+  # batch request.
+  # @see Array.save
+  # @see Array.destroy
+  class BatchOperation
+
+    attr_accessor :requests, :responses
+    include Enumerable
+
+    # @return [Parse::Client] the client to be used for the request.
+    def client
+      @client ||= Parse::Client.client
+    end
+
+    # @param reqs [Array<Parse::Request>] an array of requests.
+    def initialize(reqs = nil)
+      @requests = []
+      @responses = []
+      reqs = [reqs] unless reqs.is_a?(Enumerable)
+      reqs.each { |r| add(r) } if reqs.is_a?(Enumerable)
+    end
+
+    # Add an additional request to this batch.
+    # @overload add(req)
+    #  @param req [Parse::Request] the request to append.
+    #  @return [Array<Parse::Request>] the set of requests.
+    # @overload add(batch)
+    #  @param req [Parse::BatchOperation] add all the requests from this batch operation.
+    #  @return [Array<Parse::Request>] the set of requests.
+    def add(req)
+      if req.respond_to?(:change_requests)
+        requests = req.change_requests.select { |r| r.is_a?(Parse::Request) }
+        @requests += requests
+      elsif req.is_a?(Array)
+        requests = req.select { |r| r.is_a?(Parse::Request) }
+        @requests += requests
+      elsif req.is_a?(BatchOperation)
+        @requests += req.requests if req.is_a?(BatchOperation)
+      else
+        @requests.push(req) if req.is_a?(Parse::Request)
+      end
+      @requests
+    end
+
+    # This method is for interoperability with Parse::Object instances.
+    # @see Parse::Object#change_requests
+    def change_requests
+      @requests
+    end
+
+    # @return [Array]
+    def each
+      return enum_for(:each) unless block_given?
+      @requests.each(&Proc.new)
+    end
+
+    # @return [Hash] a formatted payload for the batch request.
+    def as_json(*args)
+      { requests:  requests }.as_json
+    end
+
+    # @return [Integer] the number of requests in the batch.
+    def count
+      @requests.count
+    end
+
+    # Remove all requests in this batch.
+    # @return [Array]
+    def clear!
+      @requests.clear
+    end
+
+    # @return [Boolean] true if the request was successful.
+    def success?
+      return false if @responses.empty?
+      @responses.compact.all?(&:success?)
+    end
+
+    # @return [Boolean] true if the request had an error.
+    def error?
+      return false if @responses.empty?
+      ! success?
+    end
+
+    # Submit the batch operation in chunks until they are all complete. In general,
+    # Parse limits requests in each batch to 50 and it is possible that a {BatchOperation}
+    # instance contains more than 50 requests. This method will slice up the array of
+    # request and send them based on the `segment` amount until they have all been submitted.
+    # @param segment [Integer] the number of requests to send in each batch. Default 50.
+    # @return [Array<Parse::Response>] the corresponding set of responses for
+    #  each request in the batch.
+    def submit(segment = 50)
+      @responses = []
+      @requests.uniq!(&:signature)
+      @requests.each_slice(segment) do |slice|
+        @responses << client.batch_request( BatchOperation.new(slice) )
+        #throttle
+        # sleep (slice.count.to_f / MAX_REQ_SEC.to_f )
+      end
+      @responses.flatten!
+      #puts "Requests: #{@requests.count} == Response: #{@responses.count}"
+      @requests.zip(@responses).each(&Proc.new) if block_given?
+      @responses
+    end
+    alias_method :save, :submit
+
+
+  end
+end
+
+class Array
+
+  # Submit a batch request for deleting a set of Parse::Objects.
+  # @example
+  #  # assume Post and Author are Parse models
+  #  author = Author.first
+  #  posts = Post.all author: author
+  #  posts.destroy # batch destroy request
+  # @return [Parse::BatchOperation] the batch operation performed.
+  # @see Parse::BatchOperation
+  def destroy
+    batch = Parse::BatchOperation.new
+    each do |o|
+      next unless o.respond_to?(:destroy_request)
+      r = o.destroy_request
+      batch.add(r) unless r.nil?
+    end
+    batch.submit
+    batch
+  end
+
+  # Submit a batch request for deleting a set of Parse::Objects.
+  # Batch requests are supported implicitly and intelligently through an
+  # extension of array. When an array of Parse::Object subclasses is saved,
+  # Parse-Stack will batch all possible save operations for the objects in the
+  # array that have changed. It will also batch save 50 at a time until all items
+  # in the array are saved. Note: Parse does not allow batch saving Parse::User objects.
+  # @note The objects of the array to be saved do not all have to be of the same collection.
+  # @param merge [Boolean] whether to merge the updated changes to the series of
+  #  objects back to the original ones submitted. If you don't need the original objects
+  #  to be updated with the changes, set this to false for improved performance.
+  # @param force [Boolean] Do not skip objects that do not have pending changes (dirty tracking).
+  # @example
+  #  # assume Post and Author are Parse models
+  #  author = Author.first
+  #  posts = Post.first 100
+  #  posts.each { |post| post.author = author }
+  #  posts.save # batch save
+  # @return [Parse::BatchOperation] the batch operation performed.
+  # @see Parse::BatchOperation
+  def save(merge: true, force: false)
+    batch = Parse::BatchOperation.new
+    objects = {}
+    each do |o|
+      next unless o.is_a?(Parse::Object)
+      objects[o.object_id] = o
+      batch.add o.change_requests(force)
+    end
+    if merge == false
+      batch.submit
+      return batch
+    end
+    #rebind updates
+    batch.submit do |request, response|
+      next unless request.tag.present? && response.present? && response.success?
+      o = objects[request.tag]
+      next unless o.is_a?(Parse::Object)
+      result = response.result
+      o.id = result['objectId'] if o.id.blank?
+      o.set_attributes!(result)
+      o.clear_changes!
+    end
+    batch
+  end #save!
+
+end