parse-stack 1.5.2 → 1.5.3

data/lib/parse/query/operation.rb

@@ -4,59 +4,70 @@
 require 'active_support'
 require 'active_support/inflector'
 
-# The base operation class used in generating queries.
-# An Operation contains an operand (field) and the
-# operator (ex. equals, greater than, etc)
-# Each unique operation type needs a handler that is responsible
-# for creating a Constraint with a given value.
-# When creating a new operation, you need to register the operation
-# method and the class that will be the handler.
+
 module Parse
+
+  # An operation is the core part of {Parse::Constraint} when performing
+  # queries. It contains an operand (the Parse field) and an operator (the Parse
+  # operation). These combined with a value, provide you with a constraint.
+  #
+  # All operation registrations add methods to the Symbol class.
   class Operation
-    attr_accessor :operand, :operator
+
+    # @!attribute operand
+    # The field in Parse for this operation.
+    # @return [Symbol]
+    attr_accessor :operand
+
+    # @!attribute operator
+    # The type of Parse operation.
+    # @return [Symbol]
+    attr_accessor :operator
+
     class << self
+      # @return [Hash] a hash containing all supported Parse operations mapped
+      # to their {Parse::Constraint} subclass.
       attr_accessor :operators
+
       def operators
         @operators ||= {}
       end
     end
-    # a valid Operation has a handler, operand and operator.
+
+    # Whether this operation is defined properly.
     def valid?
       ! (@operand.nil? || @operator.nil? || handler.nil?)
     end
 
-    # returns the constraint class designed to handle this operator
+    # @return [Parse::Constraint] the constraint class designed to handle
+    #  this operator.
     def handler
       Operation.operators[@operator] unless @operator.nil?
     end
 
+    # Create a new operation.
+    # @param field [Symbol] the name of the Parse field
+    # @param op [Symbol] the operator name (ex. :eq, :lt)
     def initialize(field, op)
       self.operand = field.to_sym
       self.operand = :objectId if operand == :id
       self.operator = op.to_sym
     end
 
+    # @!visibility private
     def inspect
       "#{operator.inspect}(#{operand.inspect})"
     end
 
-    # create a new constraint based on the handler that had
+    # Create a new constraint based on the handler that had
     # been registered with this operation.
+    # @param value [Object] a value to pass to the constraint subclass.
+    # @return [Parse::Constraint] a constraint with this operation and value.
     def constraint(value = nil)
       handler.new(self, value)
     end
 
-    # have a way to register an operation type.
-    # Example:
-    # register :eq, MyEqualityHandlerClass
-    # the above registered the equality operator which we define to be
-    # a new method on the Symbol class ('eq'), which when passed a value
-    # we will forward the request to the MyEqualityHandlerClass, so that
-    # for a field called 'name', we can do
-    #
-    # :name.eq (returns operation)
-    # :name.eq(value) # returns constraint provided by the handler
-    #
+    # Register a new symbol operator method mapped to a specific {Parse::Constraint}.
     def self.register(op, klass)
         Operation.operators[op.to_sym] = klass
         Symbol.send :define_method, op do |value = nil|

data/lib/parse/query/ordering.rb

@@ -20,12 +20,15 @@ module Parse
     class Order
       # The Parse operators to indicate ordering direction.
       ORDERING = {asc: '', desc: '-'}.freeze
+
       # @!attribute [rw] field
-      #   @return [Symbol] the name of the field
+      # @return [Symbol] the name of the field
+      attr_accessor :field
+      
       # @!attribute [rw] direction
-      #   The direction of the sorting. This is either `:asc` or `:desc`.
-      #   @return [Symbol]
-      attr_accessor :field, :direction
+      # The direction of the sorting. This is either `:asc` or `:desc`.
+      # @return [Symbol]
+      attr_accessor :direction
 
       def initialize(field, order = :asc)
         @field = field.to_sym || :objectId
@@ -36,16 +39,18 @@ module Parse
         @field = f.to_sym
       end
 
-      # get the Parse keyword for ordering.
+      # @return [String] the sort direction
       def polarity
         ORDERING[@direction] || ORDERING[:asc]
       end # polarity
 
+      # @return [String] the ordering as a string
       def to_s
         "" if @field.nil?
          polarity + @field.to_s
       end
 
+      # @!visibility private
       def inspect
         "#{@direction.to_s}(#{@field.inspect})"
       end

data/lib/parse/stack/generators/rails.rb

@@ -6,12 +6,14 @@ require 'parse/stack/tasks'
 require 'rails/generators'
 require 'rails/generators/named_base'
 
+# Module namespace to show up in the generators list for Rails.
 module ParseStack
-
+    # Adds support for rails when installing Parse::Stack to a Rails project.
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("../templates", __FILE__)
 
       desc "This generator creates an initializer file at config/initializers"
+      # @!visibility private
       def generate_initializer
         copy_file "parse.rb", "config/initializers/parse.rb"
         copy_file "model_user.rb", File.join("app/models", "user.rb")
@@ -22,12 +24,14 @@ module ParseStack
       end
     end
 
+    # @!visibility private
     class ModelGenerator < Rails::Generators::NamedBase
       source_root File.expand_path(__dir__ + "/templates")
       desc "Creates a Parse::Object model subclass."
       argument :attributes, type: :array, default: [], banner: "field:type field:type"
       check_class_collision
 
+      # @!visibility private
       def create_model_file
         @allowed_types = Parse::Properties::TYPES - [:acl, :id, :relation]
         template "model.erb", File.join("app/models", class_path, "#{file_name}.rb")

data/lib/parse/stack/generators/templates/model_installation.rb

@@ -1,5 +1,5 @@
 
-
+# The Parse _Installation collection
 class Parse::Installation < Parse::Object
   # See: https://github.com/modernistik/parse-stack#parseinstallation
   # add additional properties here

data/lib/parse/stack/generators/templates/model_role.rb

@@ -1,5 +1,5 @@
 
-
+# The Parse _Role collection
 class Parse::Role < Parse::Object
   # See: https://github.com/modernistik/parse-stack#parserole
   # add additional properties here

data/lib/parse/stack/generators/templates/model_session.rb

@@ -1,6 +1,6 @@
 
-
-class Parse::Role < Parse::Object
+# The Parse _Session collection
+class Parse::Session < Parse::Object
   # See: https://github.com/modernistik/parse-stack#parsesession
   # add additional properties here
 end

data/lib/parse/stack/generators/templates/model_user.rb

@@ -1,5 +1,5 @@
 
-# See: https://github.com/modernistik/parse-stack#parseuser
+# The Parse _User collection
 class Parse::User < Parse::Object
   # add additional properties
 

data/lib/parse/stack/generators/templates/parse.rb

@@ -2,7 +2,6 @@ require 'parse/stack'
 
 # Set your specific Parse keys in your ENV. For all connection options, see
 # https://github.com/modernistik/parse-stack#connection-setup
-
 Parse.setup app_id: ENV['PARSE_APP_ID'],
            api_key: ENV['PARSE_API_KEY'],
         master_key: ENV['PARSE_MASTER_KEY'],

data/lib/parse/stack/railtie.rb

@@ -3,6 +3,7 @@
 
 module Parse
   module Stack
+    # Support for adding rake tasks to a Rails project.
     class Railtie < ::Rails::Railtie
 
       rake_tasks do

data/lib/parse/stack/tasks.rb

@@ -11,14 +11,16 @@ require 'rake/dsl_definition'
 module Parse
 
   module Stack
-
+    # Loads and installs all Parse::Stack related tasks in a rake file.
     def self.load_tasks
       Parse::Stack::Tasks.new.install_tasks
     end
 
+    # Defines all the related Rails tasks for Parse.
     class Tasks
       include Rake::DSL if defined? Rake::DSL
 
+      # Installs the rake tasks.
       def install_tasks
 
         if defined?(::Rails)

data/lib/parse/stack/version.rb

@@ -3,7 +3,9 @@
 
 module Parse
   # @author Anthony Persaud
+  # The Parse Server SDK for Ruby
   module Stack
-    VERSION = "1.5.2"
+    # The current version.
+    VERSION = "1.5.3"
   end
 end

data/lib/parse/webhooks/registration.rb

@@ -8,11 +8,11 @@ require 'active_support/core_ext/string'
 require 'active_support/core_ext'
 
 module Parse
-
+  # Interface to the CloudCode webhooks API.
   module Webhook
-
+    # Module to support registering Parse CloudCode webhooks.
     module Registration
-
+      # The set of allowed trigger types.
       ALLOWED_HOOKS = Parse::API::Hooks::TRIGGER_NAMES + [:function]
 
       # removes all registered webhook functions with Parse Server.

data/lib/parse/webhooks.rb

@@ -18,6 +18,18 @@ module Parse
 
   class Object
 
+    # Register a webhook function for this subclass.
+    # @example
+    #  class Post < Parse::Object
+    #
+    #   webhook_function :helloWorld do
+    #      # ... do something when this function is called ...
+    #   end
+    #  end
+    # @param functionName [String] the literal name of the function to be registered with the server.
+    # @yield (see Parse::Object.webhook)
+    # @param block (see Parse::Object.webhook)
+    # @return (see Parse::Object.webhook)
     def self.webhook_function(functionName, block = nil)
       if block_given?
         Parse::Webhooks.route(:function, functionName, &Proc.new)
@@ -28,6 +40,20 @@ module Parse
       end
     end
 
+    # Register a webhook trigger or function for this subclass.
+    # @example
+    #  class Post < Parse::Object
+    #
+    #   webhook :before_save do
+    #      # ... do something ...
+    #     parse_object
+    #   end
+    #
+    #  end
+    # @param type (see Parse::Webhooks.route)
+    # @yield the body of the function to be evaluated in the scope of a {Parse::Payload} instance.
+    # @param block [Symbol] the name of the method to call, if no block is passed.
+    # @return (see Parse::Webhooks.route)
     def self.webhook(type, block = nil)
 
       if type == :function
@@ -50,28 +76,51 @@ module Parse
   end
 
   class Payload
+    # This method will intentionally raise a {WebhookErrorResponse}, which when used inside
+    # of a registered cloud code webhook function or trigger, will halt processing
+    # and return the proper error response code back to the Parse server.
+    # @param msg [String] the error message
+    # @raise WebhookErrorResponse
+    # @return [WebhookErrorResponse]
     def error!(msg = "")
       raise WebhookErrorResponse, msg
     end
   end
 
+  # The error to be raised in registered trigger or function webhook blocks that
+  # will trigger the Parse::Webhooks application to return the proper error response.
   class WebhookErrorResponse < StandardError; end;
+  # A Rack-based application middlware to handle incoming Parse cloud code webhook
+  # requests.
   class Webhooks
-
-    def self.reload!(args = {})
-
-    end
-
     include Client::Connectable
     extend Webhook::Registration
-
     HTTP_PARSE_WEBHOOK = "HTTP_X_PARSE_WEBHOOK_KEY"
     HTTP_PARSE_APPLICATION_ID = "HTTP_X_PARSE_APPLICATION_ID"
     CONTENT_TYPE = "application/json"
+
+    # @!attribute key
+    # The Parse Webhook Key to be used for authenticating webhook requests.
+    # By default this is taken from the PARSE_WEBHOOK_KEY environment variable if
+    # present.
+    # @return [String]
     attr_accessor :key
+
     class << self
+
+      # Allows support for web frameworks that support auto-reloading of source.
+      # @!visibility private
+      def reload!(args = {})
+      end
+
+      # @return [Boolean] whether to print additional logging information. You may also
+      #  set this to `:debug` for additional verbosity.
       attr_accessor :logging
 
+      # A hash-like structure composing of all the registered webhook
+      # triggers and functions. These are `:before_save`, `:after_save`,
+      # `:before_delete`, `:after_delete` or `:function`.
+      # @return [OpenStruct]
       def routes
         @routes ||= OpenStruct.new( {
           before_save: {}, after_save: {},
@@ -79,6 +128,15 @@ module Parse
           })
       end
 
+      # Internally registers a route for a specific webhook trigger or function.
+      # @param type [Symbol] The type of cloud code webhook to register. This can be any
+      #  of the supported routes. These are `:before_save`, `:after_save`,
+      # `:before_delete`, `:after_delete` or `:function`.
+      # @param className [String] if `type` is not `:function`, then this registers
+      #  a trigger for the given className. Otherwise, className is treated to be the function
+      #  name to register with Parse server.
+      # @yield the block that will handle of the webhook trigger or function.
+      # @return (see routes)
       def route(type, className, block = nil)
         type = type.to_s.underscore.to_sym #support camelcase
         if type != :function && className.respond_to?(:parse_class)
@@ -98,9 +156,12 @@ module Parse
         else
           routes[type][className] = block
         end
-        #puts "Webhook: #{type} -> #{className}..."
+        @routes
       end
 
+      # Run a locally registered webhook function. This bypasses calling a
+      # function through Parse-Server if the method handler is registered locally.
+      # @return [Object] the result of the function.
       def run_function(name, params)
         payload = Payload.new
         payload.function_name = name
@@ -108,6 +169,12 @@ module Parse
         call_route(:function, name, payload)
       end
 
+      # Calls the set of registered webhook trigger blocks or the specific function block.
+      # This method is usually called when an incoming request from Parse Server is received.
+      # @param type (see route)
+      # @param className (see route)
+      # @param payload [Parse::Payload] the payload object received from the server.
+      # @return [Object] the result of the trigger or function.
       def call_route(type, className, payload = nil)
         type = type.to_s.underscore.to_sym #support camelcase
         className = className.parse_class if className.respond_to?(:parse_class)
@@ -138,10 +205,16 @@ module Parse
         result
       end
 
+      # Generates a success response for Parse Server.
+      # @param data [Object] the data to send back with the success.
+      # @return [Hash] a success data payload
       def success(data = true)
         { success: data }.to_json
       end
 
+      # Generates an error response for Parse Server.
+      # @param data [Object] the data to send back with the error.
+      # @return [Hash] a error data payload
       def error(data = false)
         { error: data }.to_json
       end
@@ -150,6 +223,14 @@ module Parse
         @key ||= ENV['PARSE_WEBHOOK_KEY']
       end
 
+      # Standard Rack call method. This method processes an incoming cloud code
+      # webhook request from Parse Server, validates it and executes any registered handlers for it.
+      # The result of the handler for the matching webhook request is sent back to
+      # Parse Server. If the handler raises a {Parse::WebhookErrorResponse},
+      # it will return the proper error response.
+      # @param env [Hash] the environment hash in a Rack request.
+      # @return [Object] the value of calling `finish` on the Rack::Response object.
+      # @todo Create a call! method that takes a dup of this env.
       def call(env)
 
         request = Rack::Request.new env

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.5.3
 platform: ruby
 authors:
 - Anthony Persaud
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-27 00:00:00.000000000 Z
+date: 2016-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -199,6 +199,7 @@ files:
 - lib/parse/api/users.rb
 - lib/parse/client.rb
 - lib/parse/client/authentication.rb
+- lib/parse/client/batch.rb
 - lib/parse/client/body_builder.rb
 - lib/parse/client/caching.rb
 - lib/parse/client/protocol.rb
@@ -217,6 +218,7 @@ files:
 - lib/parse/model/classes/session.rb
 - lib/parse/model/classes/user.rb
 - lib/parse/model/core/actions.rb
+- lib/parse/model/core/fetching.rb
 - lib/parse/model/core/properties.rb
 - lib/parse/model/core/querying.rb
 - lib/parse/model/core/schema.rb
@@ -275,7 +277,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.6
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Parse-Server Ruby Client and Relational Mapper