parse-stack 1.5.2 → 1.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4da68d2d9e3ed4e2607a9fadaae3cd833755492d
-  data.tar.gz: a0ebd3622b1daedde1396993ad5f777522c3ecb1
+  metadata.gz: 54b0162fed5af5493439188b14b21db3eb1c7ff9
+  data.tar.gz: 17f07ddd2e7a79157f54769c46cee32b4aa03b97
 SHA512:
-  metadata.gz: ecf353df19d8b5c24acf57d472d9e1a166e055e1f8648f596b2d9b78e8755855fc623e4347ff656891a6ba64ad137a3e61bdb1be9435e9719ac4f833eb53d689
-  data.tar.gz: 06ba25aaa84702d56dc87a030aec5c99ea4858686b38ff9bfe261bc2128ca50dc6969652632033e5153e8eb6c906d8ccd9dc3023282fc4972af7206eaac86a92
+  metadata.gz: 93ae12440065bd3aeb3563457048bda7b60b07b08d2169381676d1638ea7acf364f3c9c1d033a741883bc21537f3decd8508bc83968a8ce326fae8004c60c5bd
+  data.tar.gz: cd29ad6665369388220d1599aa375323bbf872e6054541a34a660ebd71b206ddb87a3b8252391b6564c7fe2a0d4481d776ee910efef2509e772c30170469e867

data/Changes.md

@@ -1,5 +1,10 @@
 ## Parse-Stack Changelog
 
+### 1.5.3
+- Several fixes and performance improvements.
+- Major revisions to documentation.
+- Support for increment! and decrement! for Integer and Float properties.
+
 ### 1.5.2
 - FIXES #16: Constraints to `count` were not properly handled.
 - FIXES #15: Incorrect call to `request_password_reset`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack (1.5.2)
+    parse-stack (1.5.3)
       active_model_serializers (>= 0.9, < 1)
       activemodel (>= 4.2.1, < 6)
       activesupport (>= 4.2.1, < 6)

data/README.md

@@ -1,9 +1,11 @@
-# Parse-Stack - The Parse Server Ruby Client and ORM
-Parse-Stack is a [Parse Server](https://github.com/ParsePlatform/parse-server) REST API Client and ORM framework for ruby. It provides a client adapter, a query engine, an object relational mapper (ORM) and a Cloud Code Webhooks rack application.
+# Parse-Stack - The Parse Server Ruby SDK
+Parse-Stack is a [Parse Server](https://github.com/ParsePlatform/parse-server) SDK and ORM framework for Ruby. It provides a client adapter, a query engine, an object relational mapper (ORM) and a Cloud Code Webhooks rack application.
 
 ### Code Status
 [![Gem Version](https://badge.fury.io/rb/parse-stack.svg)](https://badge.fury.io/rb/parse-stack)
 [![Build Status](https://travis-ci.org/modernistik/parse-stack.svg?branch=master)](https://travis-ci.org/modernistik/parse-stack)
+[![API Reference](http://img.shields.io/badge/api-docs-blue.svg)](http://www.rubydoc.info/github/modernistik/parse-stack)
+[![Source Code](https://img.shields.io/badge/github-code-orange.svg)](https://github.com/modernistik/parse-stack)
 
 ## Installation
 
@@ -59,7 +61,7 @@ For a more details on the rails integration see [Parse-Stack Rails Example](http
     - [Signup](#signup)
       - [Third-Party Services](#third-party-services)
     - [Login and Sessions](#login-and-sessions)
-    - [Linking and Unlinking Users](#linking-and-unlinking-users)
+    - [Linking and Unlinking](#linking-and-unlinking)
     - [Request Password Reset](#request-password-reset)
 - [Modeling and Subclassing](#modeling-and-subclassing)
   - [Defining Properties](#defining-properties)
@@ -85,12 +87,13 @@ For a more details on the rails integration see [Parse-Stack Rails Example](http
       - [Parse Relation](#parse-relation)
       - [Options](#options-1)
         - [`:through`](#through)
+        - [`:scope_only`](#scope_only)
 - [Creating, Saving and Deleting Records](#creating-saving-and-deleting-records)
   - [Create](#create)
   - [Saving](#saving)
     - [Raising an exception when save fails](#raising-an-exception-when-save-fails)
   - [Modifying Associations](#modifying-associations)
-  - [Batch Save Requests](#batch-save-requests)
+  - [Batch Requests](#batch-requests)
   - [Magic `save_all`](#magic-save_all)
   - [Deleting](#deleting)
 - [Fetching, Finding and Counting Records](#fetching-finding-and-counting-records)
@@ -150,7 +153,7 @@ For a more details on the rails integration see [Parse-Stack Rails Example](http
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Overview
-Parse-Stack is a full stack framework that utilizes several ideas behind [DataMapper](http://datamapper.org/docs/find.html) and [ActiveModel](https://github.com/rails/rails/tree/master/activemodel) to manage and maintain larger scale ruby applications and tools that utilize the Parse Platform. If you are familiar with these technologies, the framework should feel familiar to you.
+Parse-Stack is a full stack framework that utilizes several ideas behind [DataMapper](http://datamapper.org/docs/find.html) and [ActiveModel](https://github.com/rails/rails/tree/master/activemodel) to manage and maintain larger scale ruby applications and tools that utilize the [Parse Server Platform](https://github.com/ParsePlatform/parse-server). If you are familiar with these technologies, the framework should feel familiar to you.
 
 ```ruby
 
@@ -223,7 +226,7 @@ result = Parse.call_function :myFunctionName, {param: value}
 The architecture of `Parse::Stack` is broken into four main components.
 
 ### Parse::Client
-This class is the core and low level API for the Parse SDK REST interface that is used by the other components. It can manage multiple sessions, which means you can have multiple client instances pointing to different Parse Applications at the same time. It handles sending raw requests as well as providing Request/Response objects for all API handlers. The connection engine is Faraday, which means it is open to add any additional middleware for features you'd like to implement.
+This class is the core and low level API for the Parse Server REST interface that is used by the other components. It can manage multiple sessions, which means you can have multiple client instances pointing to different Parse Server applications at the same time. It handles sending raw requests as well as providing Request/Response objects for all API handlers. The connection engine is Faraday, which means it is open to add any additional middleware for features you'd like to implement.
 
 ### Parse::Query
 This class implements the [Parse REST Querying](http://parseplatform.github.io/docs/rest/guide/#queries) interface in the [DataMapper finder syntax style](http://datamapper.org/docs/find.html). It compiles a set of query constraints and utilizes `Parse::Client` to send the request and provide the raw results. This class can be used without the need to define models.
@@ -261,6 +264,7 @@ To connect to a Parse server, you will need a minimum of an `application_id`, an
 ```ruby
   Parse.setup app_id: "YOUR_APP_ID",
               api_key: "YOUR_API_KEY",
+              master_key: "YOUR_MASTER_KEY", # optional
               server_url: 'https://api.parse.com/1/' #default
 ```
 
@@ -275,18 +279,18 @@ If you wish to add additional connection middleware to the stack, you may do so
   end
 ```
 
-Calling `setup` will create the default `Parse::Client` session object that will be used for all models and requests in the stack. You may retrive this client by calling the class `session()` method. It is possible to create different client connections and have different models point to different Parse applications and endpoints at the same time.
+Calling `setup` will create the default `Parse::Client` session object that will be used for all models and requests in the stack. You may retrive this client by calling the class `client` method. It is possible to create different client connections and have different models point to different Parse applications and endpoints at the same time.
 
 ```ruby
-  default_client = Parse::Client.client(:default)
-                   # alias Parse::Client.client
+  default_client = Parse.client
+                   # alias Parse::Client.client(:default)
 ```
 
 ### Connection Options
 There are additional connection options that you may pass the setup method when creating a `Parse::Client`.
 
 #### `:server_url`
-The server url of your Parse Server if you are not using the hosted Parse.com service. By default it will use `PARSE_SERVER_URL` environment variable available or fall back to `https://api.parse.com/1/` if not specified.
+The server url of your Parse Server if you are not using the hosted Parse service. By default it will use `PARSE_SERVER_URL` environment variable available or fall back to `https://api.parse.com/1/` if not specified.
 
 #### `:app_id`
 The Parse application id. By default it will use `PARSE_APP_ID` environment variable if not specified.
@@ -520,19 +524,7 @@ All `Parse::Object` subclasses have an `acl` property by default. With this prop
 For more information about Parse record ACLs, see the documentation at  [Security](https://parseplatform.github.io/docs/rest/guide/#security)
 
 ### Parse::Session
-This class represents the data and columns contained in the standard Parse `_Session` collection. You may add additional properties and methods to this class. It is defined as follows:
-
-```ruby
-class Parse::Session < Parse::Object
-  property :created_with, :object
-  property :expires_at, :date
-  property :installation_id
-  property :restricted, :boolean
-  property :session_token
-
-  belongs_to :user
-end
-```
+This class represents the data and columns contained in the standard Parse `_Session` collection. You may add additional properties and methods to this class. See [Session API Reference](http://www.rubydoc.info/github/modernistik/parse-stack/Parse/Session).
 
 You can get a specific `Parse::Session` given a session_token by using the `session` method. You can also find the user tied to a specific Parse session or session token with `Parse::User.session`.
 
@@ -547,52 +539,13 @@ user = Parse::User.session(token)
 ```
 
 ### Parse::Installation
-This class represents the data and columns contained in the standard Parse `_Installation` collection. You may add additional properties and methods to this class. It is defined as follows:
-
-```ruby
-class Parse::Installation < Parse::Object
-  property :gcm_sender_id, :string, field: :GCMSenderId
-  property :app_identifier
-  property :app_name
-  property :app_version
-  property :badge, :integer
-  property :channels, :array
-  property :device_token
-  property :device_token_last_modified, :integer
-  property :device_type
-  property :installation_id
-  property :locale_identifier
-  property :parse_version
-  property :push_type
-  property :time_zone
-end
-```
+This class represents the data and columns contained in the standard Parse `_Installation` collection. You may add additional properties and methods to this class. See [Installation API Reference](http://www.rubydoc.info/github/modernistik/parse-stack/Parse/Installation).
 
 ### Parse::Role
-This class represents the data and columns contained in the standard Parse `_Role` collection. You may add additional properties and methods to this class. It is defined as follows:
-
-```ruby
-class Parse::Role < Parse::Object
-  property :name
-
-  has_many :roles, through: :relation
-  has_many :users, through: :relation
-end
-```
+This class represents the data and columns contained in the standard Parse `_Role` collection. You may add additional properties and methods to this class. See [Roles API Reference](http://www.rubydoc.info/github/modernistik/parse-stack/Parse/Role).
 
 ### Parse::User
-This class represents the data and columns contained in the standard Parse `_User` collection. You may add additional properties and methods to this class. It is defined as follows:
-
-```ruby
-class Parse::User < Parse::Object
-  property :auth_data, :object
-  property :email
-  property :username
-
-end
-```
-
-While `:password` is a property on the User class, which will generally be empty whenever fetching User records.
+This class represents the data and columns contained in the standard Parse `_User` collection. You may add additional properties and methods to this class. See [User API Reference](http://www.rubydoc.info/github/modernistik/parse-stack/Parse/User).
 
 #### Signup
 You can signup new users in two ways. You can either use a class method `Parse::User.signup` to create a new user with the minimum fields of username, password and email, or create a `Parse::User` object can call the `signup!` method. If signup fails, it will raise the corresponding exception.
@@ -661,8 +614,8 @@ user = Parse::User.session(session_token)
 user.logout # deletes the corresponding session
 ```
 
-#### Linking and Unlinking Users
-You can signup or login uses with third-party services like Facebook and Twitter as described in: [Linking and Unlinking Users](https://parseplatform.github.io/docs/rest/guide/#linking). To do this, you must first get the corresponding authentication data for the specific service, and then apply it to the user using the linking and unlinking methods. Each method returns true or false if the action was successful. For a listing of supported third-party authentication services, see [OAuth](https://github.com/ParsePlatform/parse-server/wiki/OAuth).
+#### Linking and Unlinking
+You can link or unlink user accounts with third-party services like Facebook and Twitter as described in: [Linking and Unlinking Users](https://parseplatform.github.io/docs/rest/guide/#linking). To do this, you must first get the corresponding authentication data for the specific service, and then apply it to the user using the linking and unlinking methods. Each method returns true or false if the action was successful. For a listing of supported third-party authentication services, see [OAuth](https://github.com/ParsePlatform/parse-server/wiki/OAuth).
 
 ```ruby
 
@@ -712,8 +665,8 @@ end
 Properties are considered a literal-type of association. This means that a defined local property maps directly to a column name for that remote Parse class which contain the value. **All properties are implicitly formatted to map to a lower-first camelcase version in Parse (remote).** Therefore a local property defined as `like_count`, would be mapped to the remote column of `likeCount` automatically. The only special behavior to this rule is the `:id` property which maps to `objectId` in Parse. This implicit conversion mapping is the default behavior, but can be changed on a per-property basis. All Parse data types are supported and all Parse::Object subclasses already provide definitions for `:id` (objectId), `:created_at` (createdAt), `:updated_at` (updatedAt) and `:acl` (ACL) properties.
 
 - **:string** (_default_) - a generic string. Can be used as an enum field, see [Enum](#enum).
-- **:integer** (alias **:int**) - basic number.
-- **:float** - a floating numeric value.
+- **:integer** (alias **:int**) - basic number. Will also generate atomic `_increment!` helper method.
+- **:float** - a floating numeric value. Will also generate atomic `_increment!` helper method.
 - **:boolean** (alias **:bool**) - true/false value. This will also generate a class scope helper. See [Query Scopes](#query-scopes).
 - **:date** - a Parse date type. See [Parse::Date](#parsedate).
 - **:array** - a heterogeneous list with dirty tracking. See [Parse::CollectionProxy](https://github.com/modernistik/parse-stack/blob/master/lib/parse/model/associations/collection_proxy.rb).
@@ -724,7 +677,11 @@ Properties are considered a literal-type of association. This means that a defin
 
 For completeness, the `:id` and `:acl` data types are also defined in order to handle the Parse `objectId` field and the `ACL` object. Those are special and should not be used in your class (unless you know what you are doing). New data types can be implemented through the internal `typecast` interface. **TODO: discuss `typecast` interface in the future**
 
-In addition, `:boolean` data types create a special method that uses the `?` convention. As an example, if you have a property named `approved`, the normal getter `obj.approved` can return true, false or nil based on the value in Parse. However with the `obj.approved?` method, it will return true if it set to true, false for any other value.
+When declaring a `:boolean` data type, it will also create a special method that uses the `?` convention. As an example, if you have a property named `approved`, the normal getter `obj.approved` can return true, false or nil based on the value in Parse. However with the `obj.approved?` method, it will return true if it set to true, false for any other value.
+
+When declaring an `:integer` or `:float` type, it will also create a special method that performs
+an atomic increment of that field through the `_increment!` and `_decrement!` methods. If you have
+defined a property named `like_count` for one of these numeric types, which would create the normal getter/setter `obj.like_count`; you can now also call `obj.like_count_increment!` or `obj.like_count_decrement!` to perform the atomic operations (done server side) on this field. You may also pass an amount as an argument to these helper methods such as `obj.like_count_increment!(3)`.
 
 Using the example above, we can add the base properties to our classes.
 
@@ -1341,12 +1298,12 @@ The save operation can handle both creating and updating existing objects. If yo
 By default, we return `true` or `false` for save and destroy operations. If you prefer to have `Parse::Object` raise an exception instead, you can tell to do so either globally or on a per-model basis. When a save fails, it will raise a `Parse::SaveFailureError`.
 
 ```ruby
-	Parse::Model.raise_on_save_failure = true # globally across all models
-	Song.raise_on_save_failure = true          # per-model
-
-  # or per-instance raise on failure
-  song.save!
+ # globally across all models
+ Parse::Model.raise_on_save_failure = true
+ Song.raise_on_save_failure = true  # per-model
 
+ # or per-instance raise on failure
+ song.save!
 ```
 
 When enabled, if an error is returned by Parse due to saving or destroying a record, due to your `before_save` or `before_delete` validation cloud code triggers, `Parse::Object` will return the a `Parse::SaveFailureError` exception type. This exception has an instance method of `#object` which contains the object that failed to save.
@@ -1412,8 +1369,8 @@ The `has_many` Parse Relation associations are handled similarly as in the array
 
 ```
 
-### Batch Save Requests
-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.*
+### Batch Requests
+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. The objects do not have to be of the same collection in order to be supported in the batch request. *Note: Parse does not allow batch saving Parse::User objects.*
 
 ```ruby
 songs = Songs.first 1000 #first 1000 songs
@@ -1423,6 +1380,9 @@ end
 
 # will batch save 50 items at a time until all are saved.
 songs.save
+
+# you can also destroy a set of objects
+songs.destroy
 ```
 
 ### Magic `save_all`
@@ -2199,7 +2159,7 @@ You can register webhooks to handle the different object triggers: `:before_save
 
 For any `after_*` hook, return values are not needed since Parse does not utilize them. You may also register as many `after_save` or `after_delete` handlers as you prefer, all of them will be called.
 
-`before_save` and `before_delete` hooks have special functionality. When the `error!` method is called by the provided block, the framework will return the correct error response to Parse with value provided. Returning an error will prevent Parse from saving the object in the case of `before_save` and will prevent Parse from deleting the object when in a `before_delete`. In addition, for a `before_save`, the last value returned by the block will be the value returned in the success response. If the block returns nil or an `empty?` value, it will return `true` as the default response. You can also return a JSON object in a hash format to override the values that will be saved. However, we recommend modifying the `parse_object` provided since it has dirty tracking, and then returning that same object. This will automatically call your model specific `before_save` callbacks and send the proper payload back to Parse. For more details, see [Cloud Code BeforeSave Webhooks](https://parse.com/docs/cloudcode/guide#cloud-code-advanced-beforesave-webhooks)
+`before_save` and `before_delete` hooks have special functionality. When the `error!` method is called by the provided block, the framework will return the correct error response to Parse with value provided. Returning an error will prevent Parse from saving the object in the case of `before_save` and will prevent Parse from deleting the object when in a `before_delete`. In addition, for a `before_save`, the last value returned by the block will be the value returned in the success response. If the block returns nil or an `empty?` value, it will return `true` as the default response. You can also return a JSON object in a hash format to override the values that will be saved. However, we recommend modifying the `parse_object` provided since it has dirty tracking, and then returning that same object. This will automatically call your model specific `before_save` callbacks and send the proper payload back to Parse. For more details, see [Cloud Code BeforeSave Webhooks](http://parseplatform.github.io/docs/cloudcode/guide/#cloud-code-advanced-beforesave-webhooks)
 
 ```ruby
 # recommended way
@@ -2290,7 +2250,7 @@ However, we have predefined a few rake tasks you can use in your application. Ju
 Then you can see the tasks available by typing `rake -T`.
 
 ## Parse REST API Client
-While in most cases you do not have to work with `Parse::Client` directly, you can still utilize it for any raw requests that are not supported by the framework. We provide support for most of the [Parse REST API](https://parse.com/docs/rest/guide#quick-reference) endpoints as helper methods, however you can use the `request()` method to make your own API requests. Parse::Client will handle header authentication, request/response generation and caching.
+While in most cases you do not have to work with `Parse::Client` directly, you can still utilize it for any raw requests that are not supported by the framework. We provide support for most of the [Parse REST API](http://parseplatform.github.io/docs/rest/guide/#quick-reference) endpoints as helper methods, however you can use the `request()` method to make your own API requests. Parse::Client will handle header authentication, request/response generation and caching.
 
 ```ruby
 client = Parse::Client.new(application_id: <string>, api_key: <string>) do |conn|
@@ -2326,7 +2286,7 @@ If you are already have setup a client that is being used by your defined models
 - **master_key**: The master secret key for the application. If this is provided, `api_key` may be unnecessary.
 - **logging**: A boolean value to add additional logging messages.
 - **cache**: A [Moneta](https://github.com/minad/moneta) cache store that can be used to cache API requests. We recommend use a cache store that supports native expires like [Redis](http://redis.io). For more information see `Parse::Middleware::Caching`. Disabled by default.
-- **expires**: When used with the `cache` option, sets the expiration time of cached API responses. The default is [3 seconds](https://parse.com/docs/cloudcode/guide#cloud-code-timeouts).
+- **expires**: When used with the `cache` option, sets the expiration time of cached API responses. The default is 3 seconds.
 - **adapter**: The connection adapter to use. Defaults to `Faraday.default_adapter`.
 
 ### Request Caching

data/lib/parse/api/all.rb

@@ -14,3 +14,10 @@ require_relative "push"
 require_relative "schemas"
 require_relative "sessions"
 require_relative "users"
+
+module Parse
+  # The module containing most of the REST API requests supported by Parse Server.
+  # Defines all the Parse REST API endpoints.
+  module API
+  end
+end

data/lib/parse/api/analytics.rb

@@ -4,10 +4,15 @@
 module Parse
 
   module API
+    # Defines the Analytics interface for the Parse REST API
     module Analytics
-      # Sends analytics data
-      def send_analytics(event_name, data = {})
-        request :post, "events/#{event_name}", body: data
+
+      # Send analytics data.
+      # @param event_name [String] the name of the event.
+      # @param metrics [Hash] the metrics to attach to event.
+      # @see https://parseplatform.github.io/docs/rest/guide/#analytics-app-open-analytics Parse Analytics
+      def send_analytics(event_name, metrics = {})
+        request :post, "events/#{event_name}", body: metrics
       end
 
     end

data/lib/parse/api/apps.rb

@@ -4,25 +4,53 @@
 module Parse
 
   module API
-
+    # Defines the Apps interface for the Parse REST API
     module Apps
 
       APPS_PATH = "apps"
+
+      # Fetch the application keys.
+      # @param appid [String] the application id.
+      # @param email [String] your hosted Parse account email.
+      # @param password [String] your hosted Parse account password.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @note Only supported by the hosted Parse platform and not the open source Parse-Server.
+      # @return [Parse::Response]
       def fetch_app_keys(appid, email, password, headers: {})
         headers.merge!( { Parse::Protocol::EMAIL => email, Parse::Protocol::PASSWORD => password } )
         request :get, "#{APPS_PATH}/#{appid}", headers: headers
       end
 
+      # Fetch the applications.
+      # @param email [String] your hosted Parse account email.
+      # @param password [String] your hosted Parse account password.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @note Only supported by the hosted Parse platform and not the open source Parse-Server.
+      # @return [Parse::Response]
       def fetch_apps(email, password, headers: {})
         headers.merge!( { Parse::Protocol::EMAIL => email, Parse::Protocol::PASSWORD => password } )
         request :get, APPS_PATH, headers: headers
       end
 
+      # Create a new application in the hosted Parse Platform.
+      # @param body [Hash] parameters for creating the app.
+      # @param email [String] your hosted Parse account email.
+      # @param password [String] your hosted Parse account password.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @note Only supported by the hosted Parse platform and not the open source Parse-Server.
+      # @return [Parse::Response]
       def create_app(body, email, password, headers: {})
         headers.merge!( { Parse::Protocol::EMAIL => email, Parse::Protocol::PASSWORD => password } )
         request :post, APPS_PATH, body: body, headers: headers
       end
 
+      # @param appid [String] the application id.
+      # @param body [Hash] parameters to update the app.
+      # @param email [String] your hosted Parse account email.
+      # @param password [String] your hosted Parse account password.
+      # @param headers [Hash] additional HTTP headers to send with the request.
+      # @note Only supported by the hosted Parse platform and not the open source Parse-Server.
+      # @return [Parse::Response]
       def update_app(appid, body, email, password, headers: {})
         headers.merge!( { Parse::Protocol::EMAIL => email, Parse::Protocol::PASSWORD => password } )
         request :put, "#{APPS_PATH}/#{appid}", body: body, headers: headers

data/lib/parse/api/batch.rb

@@ -4,140 +4,25 @@
 require 'parallel'
 require 'active_support'
 require 'active_support/core_ext'
-class Array
-
-  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
-
-  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
 
 module Parse
 
-  def self.batch(reqs = nil)
-    BatchOperation.new(reqs)
-  end
-
-  class BatchOperation
-
-    attr_accessor :requests, :responses
-    include Enumerable
-
-    def client
-      @client ||= Parse::Client.client
-    end
-
-    def initialize(reqs = nil)
-      @requests = []
-      @responses = []
-      reqs = [reqs] unless reqs.is_a?(Enumerable)
-      reqs.each { |r| add(r) } if reqs.is_a?(Enumerable)
-    end
-
-    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
-
-    # make Batching interoperable with object methods. This allows adding a batch
-    # to another batch.
-    def change_requests
-      @requests
-    end
-
-    def each
-      return enum_for(:each) unless block_given?
-      @requests.each(&Proc.new)
-      self
-    end
-
-    def as_json(*args)
-      { requests:  requests }.as_json
-    end
-
-    def count
-      @requests.count
-    end
-
-    def clear!
-      @requests.clear
-    end
-
-    def success?
-      return false if @responses.empty?
-      @responses.compact.all?(&:success?)
-    end
-
-    def error?
-      return false if @responses.empty?
-      ! success?
-    end
-    # Note that N requests sent in a batch will still count toward
-    # your request limit as N requests.
-    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
-
   module API
-    #object fetch methods
-
+    # Defines the Batch interface for the Parse REST API
+    # @see Parse::BatchOperation
+    # @see Array.destroy
+    # @see Array.save
     module Batch
+      # @note You cannot use batch_requests with {Parse::User} instances that need to
+      #  be created.
+      # @overload batch_request(requests)
+      #  Perform a set of {Parse::Request} instances as a batch operation.
+      #  @param requests [Array<Parse::Request>] the set of requests to batch.
+      # @overload batch_request(operation)
+      #  Submit a batch operation.
+      #  @param operation [Parse::BatchOperation] the batch operation.
+      # @return [Array<Parse::Response>] if successful, a set of responses for each operation in the batch.
+      # @return [Parse::Response] if an error occurred, the error response.
       def batch_request(batch_operations)
         unless batch_operations.is_a?(Parse::BatchOperation)
           batch_operations = Parse::BatchOperation.new batch_operations

data/lib/parse/api/cloud_functions.rb

@@ -4,12 +4,21 @@
 module Parse
 
   module API
+    # Defines the CloudCode interface for the Parse REST API
     module CloudFunctions
 
+      # Call a cloud function.
+      # @param name [String] the name of the cloud function.
+      # @param body [Hash] the parameters to forward to the function.
+      # @return [Parse::Response]
       def call_function(name, body = {})
         request :post, "functions/#{name}", body: body
       end
 
+      # Trigger a job.
+      # @param name [String] the name of the job to trigger.
+      # @param body [Hash] the parameters to forward to the job.
+      # @return [Parse::Response]
       def trigger_job(name, body = {})
         request :post, "jobs/#{name}", body: body
       end

data/lib/parse/api/config.rb

@@ -4,15 +4,21 @@
 module Parse
 
   module API
-    #object fetch methods
+    # Defines the Config interface for the Parse REST API
     module Config
+      # @return [Hash] the cached config hash for the client.
       attr_accessor :config
       CONFIG_PATH = "config"
+
+      # @return [Hash] force fetch the application configuration hash.
       def config!
         @config = nil
         self.config
       end
 
+      # Return the configuration hash for the configured application for this client.
+      # This method caches the configuration after the first time it is fetched.
+      # @return [Hash] force fetch the application configuration hash.
       def config
         if @config.nil?
           response = request :get, CONFIG_PATH
@@ -23,6 +29,9 @@ module Parse
         @config
       end
 
+      # Update the application configuration
+      # @param params [Hash] the hash of key value pairs.
+      # @return [Boolean] true if the configuration was successfully updated.
       def update_config(params)
         body = { params: params }
         response = request :put, CONFIG_PATH, body: body

data/lib/parse/api/files.rb

@@ -7,10 +7,15 @@ require 'active_support/core_ext'
 module Parse
 
   module API
-    #object fetch methods
+    # Defines the Parse Files interface for the Parse REST API
     module Files
       FILES_PATH = "files"
-      # /1/classes/<className>	POST	Creating Objects
+
+      # Upload and create a Parse file.
+      # @param fileName [String] the basename of the file.
+      # @param data [Hash] the data related to this file.
+      # @param content_type [String] the mime-type of the file.
+      # @return [Parse::Response]
       def create_file(fileName, data = {}, content_type = nil)
         headers = {}
         headers.merge!( { Parse::Protocol::CONTENT_TYPE => content_type.to_s } ) if content_type.present?