restorm 1.0.0

data/lib/restorm/model/orm.rb

@@ -0,0 +1,299 @@
+# coding: utf-8
+
+module Restorm
+  module Model
+    # This module adds ORM-like capabilities to the model
+    module ORM
+      extend ActiveSupport::Concern
+
+      # Return `true` if a resource was not saved yet
+      def new?
+        id.nil?
+      end
+      alias new_record? new?
+
+      # Return `true` if a resource is not `#new?`
+      def persisted?
+        !new?
+      end
+
+      # Return whether the object has been destroyed
+      def destroyed?
+        @destroyed == true
+      end
+
+      # Save a resource and return `false` if the response is not a successful one or
+      # if there are errors in the resource. Otherwise, return the newly updated resource
+      #
+      # @example Save a resource after fetching it
+      #   @user = User.find(1)
+      #   # Fetched via GET "/users/1"
+      #   @user.fullname = "Tobias Fünke"
+      #   @user.save
+      #   # Called via PUT "/users/1"
+      #
+      # @example Save a new resource by creating it
+      #   @user = User.new({ :fullname => "Tobias Fünke" })
+      #   @user.save
+      #   # Called via POST "/users"
+      def save
+        callback = new? ? :create : :update
+        method = self.class.method_for(callback)
+
+        run_callbacks :save do
+          run_callbacks callback do
+            self.class.request(to_params.merge(:_method => method, :_path => request_path)) do |parsed_data, response|
+              load_from_parsed_data(parsed_data)
+              return false if !response.success? || @response_errors.any?
+              changes_applied
+            end
+          end
+        end
+
+        self
+      end
+
+      # Similar to save(), except that ResourceInvalid is raised if the save fails
+      def save!
+        unless save
+          raise Restorm::Errors::ResourceInvalid, self
+        end
+        self
+      end
+
+      # Update a resource and return it
+      #
+      # @example
+      #   @user = User.find(1)
+      #   @user.update_attributes(:name => "Tobias Fünke")
+      #   # Called via PUT "/users/1"
+      def update_attributes(attributes)
+        assign_attributes(attributes) && save
+      end
+
+      # Destroy a resource
+      #
+      # @example
+      #   @user = User.find(1)
+      #   @user.destroy
+      #   # Called via DELETE "/users/1"
+      def destroy(params = {})
+        method = self.class.method_for(:destroy)
+        run_callbacks :destroy do
+          self.class.request(params.merge(:_method => method, :_path => request_path)) do |parsed_data, response|
+            load_from_parsed_data(parsed_data)
+            @destroyed = response.success?
+          end
+        end
+        self
+      end
+
+      # Initializes +attribute+ to zero if +nil+ and adds the value passed as
+      # +by+ (default is 1). The increment is performed directly on the
+      # underlying attribute, no setter is invoked. Only makes sense for
+      # number-based attributes. Returns +self+.
+      def increment(attribute, by = 1)
+        attributes[attribute] ||= 0
+        attributes[attribute] += by
+        self
+      end
+
+      # Wrapper around #increment that saves the resource. Saving is subjected
+      # to validation checks. Returns +self+.
+      def increment!(attribute, by = 1)
+        increment(attribute, by) && save
+        self
+      end
+
+      # Initializes +attribute+ to zero if +nil+ and substracts the value passed as
+      # +by+ (default is 1). The decrement is performed directly on the
+      # underlying attribute, no setter is invoked. Only makes sense for
+      # number-based attributes. Returns +self+.
+      def decrement(attribute, by = 1)
+        increment(attribute, -by)
+      end
+
+      # Wrapper around #decrement that saves the resource. Saving is subjected
+      # to validation checks. Returns +self+.
+      def decrement!(attribute, by = 1)
+        increment!(attribute, -by)
+      end
+
+      # Assigns to +attribute+ the boolean opposite of <tt>attribute?</tt>. So
+      # if the predicate returns +true+ the attribute will become +false+. This
+      # method toggles directly the underlying value without calling any setter.
+      # Returns +self+.
+      #
+      # @example
+      #   user = User.first
+      #   user.admin? # => false
+      #   user.toggle(:admin)
+      #   user.admin? # => true
+      def toggle(attribute)
+        attributes[attribute] = !public_send("#{attribute}?")
+        self
+      end
+
+      # Wrapper around #toggle that saves the resource. Saving is subjected to
+      # validation checks. Returns +true+ if the record could be saved.
+      def toggle!(attribute)
+        toggle(attribute) && save
+      end
+
+      # Refetches the resource
+      #
+      # This method finds the resource by its primary key (which could be
+      # assigned manually) and modifies the object in-place.
+      #
+      # @example
+      #   user = User.find(1)
+      #   # => #<User(users/1) id=1 name="Tobias Fünke">
+      #   user.name = "Oops"
+      #   user.reload # Fetched again via GET "/users/1"
+      #   # => #<User(users/1) id=1 name="Tobias Fünke">
+      def reload(options = nil)
+        fresh_object = self.class.find(id)
+        assign_attributes(fresh_object.attributes)
+        self
+      end
+
+      # Uses parsed response to assign attributes and metadata
+      #
+      # @private
+      def load_from_parsed_data(parsed_data)
+        data = parsed_data[:data]
+        assign_attributes(self.class.parse(data)) if data.any?
+        @metadata = parsed_data[:metadata]
+        @response_errors = parsed_data[:errors]
+      end
+
+      module ClassMethods
+        # Create a new chainable scope
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #
+        #     scope :admins, lambda { where(:admin => 1) }
+        #     scope :page, lambda { |page| where(:page => page) }
+        #   enc
+        #
+        #   User.admins # Called via GET "/users?admin=1"
+        #   User.page(2).all # Called via GET "/users?page=2"
+        def scope(name, code)
+          # Add the scope method to the class
+          (class << self; self end).send(:define_method, name) do |*args|
+            instance_exec(*args, &code)
+          end
+
+          # Add the scope method to the default/blank relation
+          scoped.define_singleton_method(name) { |*args| instance_exec(*args, &code) }
+        end
+
+        # @private
+        def scoped
+          @_restorm_default_scope || blank_relation
+        end
+
+        # Define the default scope for the model
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #
+        #     default_scope lambda { where(:admin => 1) }
+        #   enc
+        #
+        #   User.all # Called via GET "/users?admin=1"
+        #   User.new.admin # => 1
+        def default_scope(block = nil)
+          @_restorm_default_scope ||= (!respond_to?(:default_scope) && superclass.respond_to?(:default_scope)) ? superclass.default_scope : scoped
+          @_restorm_default_scope = @_restorm_default_scope.instance_exec(&block) unless block.nil?
+          @_restorm_default_scope
+        end
+
+        # Delegate the following methods to `scoped`
+        [:all, :where, :create, :build, :find, :find_by, :find_or_create_by,
+         :find_or_initialize_by, :first_or_create, :first_or_initialize].each do |method|
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{method}(*params)
+              scoped.send(#{method.to_sym.inspect}, *params)
+            end
+          RUBY
+        end
+
+        # Save an existing resource and return it
+        #
+        # @example
+        #   @user = User.save_existing(1, { :fullname => "Tobias Fünke" })
+        #   # Called via PUT "/users/1"
+        def save_existing(id, params)
+          save_existing!(id, params)
+        rescue Restorm::Errors::ResourceInvalid => e
+          e.resource
+        end
+
+        # Similar to .save_existing but raises ResourceInvalid if save fails
+        def save_existing!(id, params)
+          resource = new(params.merge(primary_key => id))
+          resource.save!
+          resource
+        end
+
+        # Destroy an existing resource
+        #
+        # @example
+        #   User.destroy_existing(1)
+        #   # Called via DELETE "/users/1"
+        def destroy_existing(id, params = {})
+          request(params.merge(:_method => method_for(:destroy), :_path => build_request_path(params.merge(primary_key => id)))) do |parsed_data, response|
+            data = parse(parsed_data[:data])
+            metadata = parsed_data[:metadata]
+            response_errors = parsed_data[:errors]
+            record = new(data.merge(:_destroyed => response.success?, :metadata => metadata))
+            record.response_errors = response_errors
+            record
+          end
+        end
+
+        # Return or change the HTTP method used to create or update records
+        #
+        # @param [Symbol, String] action The behavior in question (`:create` or `:update`)
+        # @param [Symbol, String] method The HTTP method to use (`'PUT'`, `:post`, etc.)
+        def method_for(action = nil, method = nil)
+          @method_for ||= (superclass.respond_to?(:method_for) ? superclass.method_for : {})
+          return @method_for if action.nil?
+
+          action = action.to_s.downcase.to_sym
+
+          return @method_for[action] if method.nil?
+          @method_for[action] = method.to_s.downcase.to_sym
+        end
+
+        # Build a new resource with the given attributes.
+        # If the request_new_object_on_build flag is set, the new object is requested via API.
+        def build(attributes = {})
+          params = attributes
+          return new(params) unless request_new_object_on_build?
+
+          path = build_request_path(params.merge(primary_key => 'new'))
+          method = method_for(:new)
+
+          resource = nil
+          request(params.merge(:_method => method, :_path => path)) do |parsed_data, response|
+            if response.success?
+              resource = new_from_parsed_data(parsed_data)
+            end
+          end
+          resource
+        end
+
+        # @private
+        def blank_relation
+          @blank_relation ||= superclass.blank_relation.clone.tap { |r| r.parent = self } if superclass.respond_to?(:blank_relation)
+          @blank_relation ||= Relation.new(self)
+        end
+      end
+    end
+  end
+end

data/lib/restorm/model/parse.rb

@@ -0,0 +1,223 @@
+module Restorm
+  module Model
+    # This module handles resource data parsing at the model level (after the parsing middleware)
+    module Parse
+      extend ActiveSupport::Concern
+
+      # Convert into a hash of request parameters, based on `include_root_in_json`.
+      #
+      # @example
+      #   @user.to_params
+      #   # => { :id => 1, :name => 'John Smith' }
+      def to_params
+        self.class.to_params(attributes, changes)
+      end
+
+      module ClassMethods
+        # Parse data before assigning it to a resource, based on `parse_root_in_json`.
+        #
+        # @param [Hash] data
+        # @private
+        def parse(data)
+          if parse_root_in_json? && root_element_included?(data)
+            if json_api_format?
+              data.fetch(parsed_root_element).first
+            else
+              data.fetch(parsed_root_element) { data }
+            end
+          else
+            data
+          end
+        end
+
+        # @private
+        def to_params(attributes, changes = {})
+          filtered_attributes = attributes.each_with_object({}) do |(key, value), memo|
+            case value
+            when Restorm::Model
+            when ActiveModel::Serialization
+              value = value.serializable_hash.symbolize_keys
+            end
+
+            memo[key.to_sym] = value
+          end
+
+          filtered_attributes.merge!(embeded_params(attributes))
+
+          if restorm_api.options[:send_only_modified_attributes]
+            filtered_attributes.slice! *changes.keys.map(&:to_sym)
+          end
+
+          if include_root_in_json?
+            if json_api_format?
+              { included_root_element => [filtered_attributes] }
+            else
+              { included_root_element => filtered_attributes }
+            end
+          else
+            filtered_attributes
+          end
+        end
+
+        # @private
+        def embeded_params(attributes)
+          associations.values.flatten.each_with_object({}) do |definition, hash|
+            value = case association = attributes[definition[:name]]
+                    when Restorm::Collection, Array
+                      association.map { |a| a.to_params }.reject(&:empty?)
+                    when Restorm::Model
+                      association.to_params
+                    end
+            hash[definition[:data_key]] = value if value.present?
+          end
+        end
+
+        # Return or change the value of `include_root_in_json`
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     include_root_in_json true
+        #   end
+        def include_root_in_json(value, options = {})
+          @_restorm_include_root_in_json = value
+          @_restorm_include_root_in_json_format = options[:format]
+        end
+
+        # Return or change the value of `parse_root_in_json`
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     parse_root_in_json true
+        #   end
+        #
+        #   class User
+        #     include Restorm::Model
+        #     parse_root_in_json true, format: :active_model_serializers
+        #   end
+        #
+        #   class User
+        #     include Restorm::Model
+        #     parse_root_in_json true, format: :json_api
+        #   end
+        def parse_root_in_json(value, options = {})
+          @_restorm_parse_root_in_json = value
+          @_restorm_parse_root_in_json_format = options[:format]
+        end
+
+        # Return or change the value of `request_new_object_on_build`
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     request_new_object_on_build true
+        #   end
+        def request_new_object_on_build(value = nil)
+          @_restorm_request_new_object_on_build = value
+        end
+
+        # Return or change the value of `root_element`. Always defaults to the base name of the class.
+        #
+        # @example
+        #   class User
+        #     include Restorm::Model
+        #     parse_root_in_json true
+        #     root_element :huh
+        #   end
+        #
+        #   user = User.find(1) # { :huh => { :id => 1, :name => "Tobias" } }
+        #   user.name # => "Tobias"
+        def root_element(value = nil)
+          if value.nil?
+            @_retorm_root_element ||= if json_api_format?
+                                     name.split("::").last.pluralize.underscore.to_sym
+                                   else
+                                     name.split("::").last.underscore.to_sym
+                                   end
+          else
+            @_restorm_root_element = value.to_sym
+          end
+        end
+
+        # @private
+        def root_element_included?(data)
+          element = data[parsed_root_element]
+          element.is_a?(Hash) || element.is_a?(Array)
+        end
+
+        # @private
+        def included_root_element
+          include_root_in_json? == true ? root_element : include_root_in_json?
+        end
+
+        # Extract an array from the request data
+        #
+        # @example
+        #   # with parse_root_in_json true, :format => :active_model_serializers
+        #   class User
+        #     include Restorm::Model
+        #     parse_root_in_json true, :format => :active_model_serializers
+        #   end
+        #
+        #   users = User.all # { :users => [ { :id => 1, :name => "Tobias" } ] }
+        #   users.first.name # => "Tobias"
+        #
+        #   # without parse_root_in_json
+        #   class User
+        #     include Restorm::Model
+        #   end
+        #
+        #   users = User.all # [ { :id => 1, :name => "Tobias" } ]
+        #   users.first.name # => "Tobias"
+        #
+        # @private
+        def extract_array(request_data)
+          if request_data[:data].is_a?(Hash) && (active_model_serializers_format? || json_api_format?)
+            request_data[:data][pluralized_parsed_root_element]
+          else
+            request_data[:data]
+          end
+        end
+
+        # @private
+        def pluralized_parsed_root_element
+          parsed_root_element.to_s.pluralize.to_sym
+        end
+
+        # @private
+        def parsed_root_element
+          parse_root_in_json? == true ? root_element : parse_root_in_json?
+        end
+
+        # @private
+        def active_model_serializers_format?
+          @_restorm_parse_root_in_json_format == :active_model_serializers || (superclass.respond_to?(:active_model_serializers_format?) && superclass.active_model_serializers_format?)
+        end
+
+        # @private
+        def json_api_format?
+          @_restorm_parse_root_in_json_format == :json_api || (superclass.respond_to?(:json_api_format?) && superclass.json_api_format?)
+        end
+
+        # @private
+        def request_new_object_on_build?
+          return @_restorm_request_new_object_on_build unless @_restorm_request_new_object_on_build.nil?
+          superclass.respond_to?(:request_new_object_on_build?) && superclass.request_new_object_on_build?
+        end
+
+        # @private
+        def include_root_in_json?
+          return @_restorm_include_root_in_json unless @_restorm_include_root_in_json.nil?
+          superclass.respond_to?(:include_root_in_json?) && superclass.include_root_in_json?
+        end
+
+        # @private
+        def parse_root_in_json?
+          return @_restorm_parse_root_in_json unless @_restorm_parse_root_in_json.nil?
+          superclass.respond_to?(:parse_root_in_json?) && superclass.parse_root_in_json?
+        end
+      end
+    end
+  end
+end

data/lib/restorm/model/paths.rb

@@ -0,0 +1,125 @@
+module Restorm
+  module Model
+    module Paths
+      extend ActiveSupport::Concern
+      # Return a path based on the collection path and a resource data
+      #
+      # @example
+      #   class User
+      #     include Restorm::Model
+      #     collection_path "/utilisateurs"
+      #   end
+      #
+      #   User.find(1) # Fetched via GET /utilisateurs/1
+      #
+      # @param [Hash] params An optional set of additional parameters for
+      #   path construction. These will not override attributes of the resource.
+      def request_path(params = {})
+        self.class.build_request_path(params.merge(attributes.dup))
+      end
+
+      module ClassMethods
+        # Define the primary key field that will be used to find and save records
+        #
+        # @example
+        #  class User
+        #    include Restorm::Model
+        #    primary_key 'UserId'
+        #  end
+        #
+        # @param [Symbol] value
+        def primary_key(value = nil)
+          @_restorm_primary_key ||= begin
+            superclass.primary_key if superclass.respond_to?(:primary_key)
+          end
+
+          return @_restorm_primary_key unless value
+          @_restorm_primary_key = value.to_sym
+        end
+
+        # Defines a custom collection path for the resource
+        #
+        # @example
+        #  class User
+        #    include Restorm::Model
+        #    collection_path "/users"
+        #  end
+        def collection_path(path = nil)
+          if path.nil?
+            @_restorm_collection_path ||= root_element.to_s.pluralize
+          else
+            @_restorm_collection_path = path
+            @_restorm_resource_path = "#{path}/:id"
+          end
+        end
+
+        # Defines a custom resource path for the resource
+        #
+        # @example
+        #  class User
+        #    include Restorm::Model
+        #    resource_path "/users/:id"
+        #  end
+        #
+        # Note that, if used in combination with resource_path, you may specify
+        # either the real primary key or the string ':id'. For example:
+        #
+        # @example
+        #  class User
+        #    include Restorm::Model
+        #    primary_key 'user_id'
+        #
+        #    # This works because we'll have a user_id attribute
+        #    resource_path '/users/:user_id'
+        #
+        #    # This works because we replace :id with :user_id
+        #    resource_path '/users/:id'
+        #  end
+        #
+        def resource_path(path = nil)
+          if path.nil?
+            @_restorm_resource_path ||= "#{root_element.to_s.pluralize}/:id"
+          else
+            @_restorm_resource_path = path
+          end
+        end
+
+        # Return a custom path based on the collection path and variable parameters
+        #
+        # @private
+        def build_request_path(path = nil, parameters = {})
+          parameters = parameters.try(:with_indifferent_access)
+
+          unless path.is_a?(String)
+            parameters = path.try(:with_indifferent_access) || parameters
+            path =
+              if parameters.include?(primary_key) && parameters[primary_key] && !parameters[primary_key].is_a?(Array)
+                resource_path.dup
+              else
+                collection_path.dup
+              end
+
+            # Replace :id with our actual primary key
+            path.gsub!(/(\A|\/):id(\Z|\/)/, "\\1:#{primary_key}\\2")
+          end
+
+          path.gsub(/:([\w_]+)/) do
+            # Look for :key or :_key, otherwise raise an exception
+            key = $1.to_sym
+            value = parameters.delete(key) || parameters.delete(:"_#{key}")
+            if value
+              Faraday::Utils.escape value
+            else
+              raise(Restorm::Errors::PathError.new("Missing :_#{$1} parameter to build the request path. Path is `#{path}`. Parameters are `#{parameters.symbolize_keys.inspect}`.", $1))
+            end
+          end
+        end
+
+        # @private
+        def build_request_path_from_string_or_symbol(path, params = {})
+          path.is_a?(Symbol) ? "#{build_request_path(params)}/#{path}" : path
+        end
+      end
+    end
+  end
+end