herr 0.7.3

data/lib/her/model/deprecated_methods.rb

@@ -0,0 +1,61 @@
+module Her
+  module Model
+    # @private
+    module DeprecatedMethods
+      extend ActiveSupport::Concern
+
+      def self.deprecate!(old, new, object, *args)
+        line = begin
+          raise StandardError
+        rescue StandardError => e
+          e.backtrace[2]
+        end
+
+        warn "#{line} - The `#{old}` method is deprecated and may be removed soon. Please update your code with `#{new}` instead."
+        object.send(new, *args)
+      end
+
+      def data(*args)
+        Her::Model::DeprecatedMethods.deprecate! :data, :attributes, self, *args
+      end
+
+      def data=(*args)
+        Her::Model::DeprecatedMethods.deprecate! :data=, :attributes=, self, *args
+      end
+
+      def update_attributes(*args)
+        Her::Model::DeprecatedMethods.deprecate! :update_attributes, :assign_attributes, self, *args
+      end
+
+      def assign_data(*args)
+        Her::Model::DeprecatedMethods.deprecate! :assign_data, :assign_attributes, self, *args
+      end
+
+      def has_data?(*args)
+        Her::Model::DeprecatedMethods.deprecate! :has_data?, :has_attribute?, self, *args
+      end
+
+      def get_data(*args)
+        Her::Model::DeprecatedMethods.deprecate! :get_data, :get_attribute, self, *args
+      end
+
+      module ClassMethods
+        def has_relationship?(*args)
+          Her::Model::DeprecatedMethods.deprecate! :has_relationship?, :has_association?, self, *args
+        end
+
+        def get_relationship(*args)
+          Her::Model::DeprecatedMethods.deprecate! :get_relationship, :get_association, self, *args
+        end
+
+        def relationships(*args)
+          Her::Model::DeprecatedMethods.deprecate! :relationships, :associations, self, *args
+        end
+
+        def her_api(*args)
+          Her::Model::DeprecatedMethods.deprecate! :her_api, :use_api, self, *args
+        end
+      end
+    end
+  end
+end

data/lib/her/model/http.rb

@@ -0,0 +1,114 @@
+module Her
+  module Model
+    # This module interacts with Her::API to fetch HTTP data
+    module HTTP
+      extend ActiveSupport::Concern
+      METHODS = [:get, :post, :put, :patch, :delete]
+
+      # For each HTTP method, define these class methods:
+      #
+      # - <method>(path, params)
+      # - <method>_raw(path, params, &block)
+      # - <method>_collection(path, params, &block)
+      # - <method>_resource(path, params, &block)
+      # - custom_<method>(*paths)
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #     custom_get :active
+      #   end
+      #
+      #   User.get(:popular) # GET "/users/popular"
+      #   User.active # GET "/users/active"
+      module ClassMethods
+        # Change which API the model will use to make its HTTP requests
+        #
+        # @example
+        #   secondary_api = Her::API.new :url => "https://api.example" do |connection|
+        #     connection.use Faraday::Request::UrlEncoded
+        #     connection.use Her::Middleware::DefaultParseJSON
+        #   end
+        #
+        #   class User
+        #     include Her::Model
+        #     use_api secondary_api
+        #   end
+        def use_api(value = nil)
+          @_her_use_api ||= begin
+            superclass.use_api if superclass.respond_to?(:use_api)
+          end
+
+          unless value
+            return (@_her_use_api.respond_to? :call) ? @_her_use_api.call : @_her_use_api
+          end
+
+          @_her_use_api = value
+        end
+
+        alias her_api use_api
+        alias uses_api use_api
+
+        # Main request wrapper around Her::API. Used to make custom request to the API.
+        #
+        # @private
+        def request(params={})
+          request = her_api.request(params)
+
+          if block_given?
+            yield request[:parsed_data], request[:response]
+          else
+            { :parsed_data => request[:parsed_data], :response => request[:response] }
+          end
+        end
+
+        METHODS.each do |method|
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{method}(path, params={})
+              path = build_request_path_from_string_or_symbol(path, params)
+              params = to_params(params) unless #{method.to_sym.inspect} == :get
+              send(:'#{method}_raw', path, params) do |parsed_data, response|
+                if parsed_data[:data].is_a?(Array) || active_model_serializers_format? || json_api_format?
+                  new_collection(parsed_data)
+                else
+                  new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:metadata], :_errors => parsed_data[:errors])
+                end
+              end
+            end
+
+            def #{method}_raw(path, params={}, &block)
+              path = build_request_path_from_string_or_symbol(path, params)
+              request(params.merge(:_method => #{method.to_sym.inspect}, :_path => path), &block)
+            end
+
+            def #{method}_collection(path, params={})
+              path = build_request_path_from_string_or_symbol(path, params)
+              send(:'#{method}_raw', build_request_path_from_string_or_symbol(path, params), params) do |parsed_data, response|
+                new_collection(parsed_data)
+              end
+            end
+
+            def #{method}_resource(path, params={})
+              path = build_request_path_from_string_or_symbol(path, params)
+              send(:"#{method}_raw", path, params) do |parsed_data, response|
+                new(parse(parsed_data[:data]).merge :_metadata => parsed_data[:metadata], :_errors => parsed_data[:errors])
+              end
+            end
+
+            def custom_#{method}(*paths)
+              metaclass = (class << self; self; end)
+              opts = paths.last.is_a?(Hash) ? paths.pop : Hash.new
+
+              paths.each do |path|
+                metaclass.send(:define_method, path) do |*params|
+                  params = params.first || Hash.new
+                  send(#{method.to_sym.inspect}, path, params)
+                end
+              end
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/her/model/introspection.rb

@@ -0,0 +1,65 @@
+module Her
+  module Model
+    module Introspection
+      extend ActiveSupport::Concern
+      # Inspect an element, returns it for introspection.
+      #
+      # @example
+      #   class User
+      #     include Her::Model
+      #   end
+      #
+      #   @user = User.find(1)
+      #   p @user # => #<User(/users/1) id=1 name="Tobias Fünke">
+      def inspect
+        resource_path = begin
+          request_path
+        rescue Her::Errors::PathError => e
+          "<unknown path, missing `#{e.missing_parameter}`>"
+        end
+
+        "#<#{self.class}(#{resource_path}) #{attributes.keys.map { |k| "#{k}=#{attribute_for_inspect(send(k))}" }.join(" ")}>"
+      end
+
+      private
+      def attribute_for_inspect(value)
+        if value.is_a?(String) && value.length > 50
+          "#{value[0..50]}...".inspect
+        elsif value.is_a?(Date) || value.is_a?(Time)
+          %("#{value}")
+        else
+          value.inspect
+        end
+      end
+
+      # @private
+      module ClassMethods
+        # Finds a class at the same level as this one or at the global level.
+        #
+        # @private
+        def her_nearby_class(name)
+          her_sibling_class(name) || name.constantize rescue nil
+        end
+
+        protected
+        # Looks for a class at the same level as this one with the given name.
+        #
+        # @private
+        def her_sibling_class(name)
+          if mod = self.her_containing_module
+            @_her_sibling_class ||= Hash.new { Hash.new }
+            @_her_sibling_class[mod][name] ||= "#{mod.name}::#{name}".constantize rescue nil
+          end
+        end
+
+        # If available, returns the containing Module for this class.
+        #
+        # @private
+        def her_containing_module
+          return unless self.name =~ /::/
+          self.name.split("::")[0..-2].join("::").constantize
+        end
+      end
+    end
+  end
+end

data/lib/her/model/nested_attributes.rb

@@ -0,0 +1,45 @@
+module Her
+  module Model
+    module NestedAttributes
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Allow nested attributes for an association
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #
+        #     has_one :role
+        #     accepts_nested_attributes_for :role
+        #   end
+        #
+        #   class Role
+        #     include Her::Model
+        #   end
+        #
+        #   user = User.new(name: "Tobias", role_attributes: { title: "moderator" })
+        #   user.role # => #<Role title="moderator">
+        def accepts_nested_attributes_for(*associations)
+          allowed_association_names = association_names
+
+          associations.each do |association_name|
+            unless allowed_association_names.include?(association_name)
+              raise Her::Errors::AssociationUnknownError.new("Unknown association name :#{association_name}")
+            end
+
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              if method_defined?(:#{association_name}_attributes=)
+                remove_method(:#{association_name}_attributes=)
+              end
+
+              def #{association_name}_attributes=(attributes)
+                self.#{association_name}.assign_nested_attributes(attributes)
+              end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/her/model/orm.rb

@@ -0,0 +1,205 @@
+module Her
+  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
+
+      # 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 callback do
+          run_callbacks :save do
+            params = to_params
+            self.class.request(to_params.merge(:_method => method, :_path => request_path)) do |parsed_data, response|
+              assign_attributes(self.class.parse(parsed_data[:data])) if parsed_data[:data].any?
+              @metadata = parsed_data[:metadata]
+              @response_errors = parsed_data[:errors]
+
+              return false if !response.success? || @response_errors.any?
+              if self.changed_attributes.present?
+                @previously_changed = self.changed_attributes.clone
+                self.changed_attributes.clear
+              end
+            end
+          end
+        end
+
+        self
+      end
+
+      # Similar to save(), except that ResourceInvalid is raised if the save fails
+      def save!
+        if !self.save
+          raise Her::Errors::ResourceInvalid, self
+        end
+        self
+      end
+
+      # Destroy a resource
+      #
+      # @example
+      #   @user = User.find(1)
+      #   @user.destroy
+      #   # Called via DELETE "/users/1"
+      def destroy
+        method = self.class.method_for(:destroy)
+        run_callbacks :destroy do
+          self.class.request(:_method => method, :_path => request_path) do |parsed_data, response|
+            assign_attributes(self.class.parse(parsed_data[:data])) if parsed_data[:data].any?
+            @metadata = parsed_data[:metadata]
+            @response_errors = parsed_data[:errors]
+            @destroyed = true
+          end
+        end
+        self
+      end
+
+      module ClassMethods
+        # Create a new chainable scope
+        #
+        # @example
+        #   class User
+        #     include Her::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 Relation class
+          Relation.instance_eval do
+            define_method(name) { |*args| instance_exec(*args, &code) }
+          end
+        end
+
+        # @private
+        def scoped
+          @_her_default_scope || blank_relation
+        end
+
+        # Define the default scope for the model
+        #
+        # @example
+        #   class User
+        #     include Her::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)
+          @_her_default_scope ||= (!respond_to?(:default_scope) && superclass.respond_to?(:default_scope)) ? superclass.default_scope : scoped
+          @_her_default_scope = @_her_default_scope.instance_exec(&block) unless block.nil?
+          @_her_default_scope
+        end
+
+        # Delegate the following methods to `scoped`
+        [:all, :where, :create, :build, :find, :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)
+          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|
+            new(parse(parsed_data[:data]).merge(:_destroyed => true))
+          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 self.new(params) unless self.request_new_object_on_build?
+
+          path = self.build_request_path(params.merge(self.primary_key => 'new'))
+          method = self.method_for(:new)
+
+          resource = nil
+          self.request(params.merge(:_method => method, :_path => path)) do |parsed_data, response|
+            if response.success?
+              resource = self.new_from_parsed_data(parsed_data)
+            end
+          end
+          resource
+        end
+
+        private
+        # @private
+        def blank_relation
+          @blank_relation ||= Relation.new(self)
+        end
+      end
+    end
+  end
+end