castle-her 1.0.1

data/lib/castle-her/model/parse.rb

@@ -0,0 +1,216 @@
+module Her
+  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(self.attributes, self.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.dup.symbolize_keys
+          filtered_attributes.merge!(embeded_params(attributes))
+          if her_api.options[:send_only_modified_attributes]
+            filtered_attributes = changes.symbolize_keys.keys.inject({}) do |hash, attribute|
+              hash[attribute] = filtered_attributes[attribute]
+              hash
+            end
+          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
+        # TODO: Handle has_one
+        def embeded_params(attributes)
+          associations[:has_many].select { |a| attributes.include?(a[:data_key])}.compact.inject({}) do |hash, association|
+            params = attributes[association[:data_key]].map(&:to_params)
+            next if params.empty?
+            if association[:class_name].constantize.include_root_in_json?
+              root = association[:class_name].constantize.root_element
+              hash[association[:data_key]] = params.map { |n| n[root] }
+            else
+              hash[association[:data_key]] = params
+            end
+            hash
+          end
+        end
+
+        # Return or change the value of `include_root_in_json`
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     include_root_in_json true
+        #   end
+        def include_root_in_json(value, options = {})
+          @_her_include_root_in_json = value
+          @_her_include_root_in_json_format = options[:format]
+        end
+
+        # Return or change the value of `parse_root_in_json`
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     parse_root_in_json true
+        #   end
+        #
+        #   class User
+        #     include Her::Model
+        #     parse_root_in_json true, format: :active_model_serializers
+        #   end
+        #
+        #   class User
+        #     include Her::Model
+        #     parse_root_in_json true, format: :json_api
+        #   end
+        def parse_root_in_json(value, options = {})
+          @_her_parse_root_in_json = value
+          @_her_parse_root_in_json_format = options[:format]
+        end
+
+        # Return or change the value of `request_new_object_on_build`
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     request_new_object_on_build true
+        #   end
+        def request_new_object_on_build(value = nil)
+          @_her_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 Her::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?
+            if json_api_format?
+              @_her_root_element ||= self.name.split("::").last.pluralize.underscore.to_sym
+            else
+              @_her_root_element ||= self.name.split("::").last.underscore.to_sym
+            end
+          else
+            @_her_root_element = value.to_sym
+          end
+        end
+
+        # @private
+        def root_element_included?(data)
+          data.keys.to_s.include? @_her_root_element.to_s
+        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 Her::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 Her::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?
+          @_her_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?
+          @_her_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?
+          @_her_request_new_object_on_build || (superclass.respond_to?(:request_new_object_on_build?) && superclass.request_new_object_on_build?)
+        end
+
+        # @private
+        def include_root_in_json?
+          @_her_include_root_in_json || (superclass.respond_to?(:include_root_in_json?) && superclass.include_root_in_json?)
+        end
+
+        # @private
+        def parse_root_in_json?
+          @_her_parse_root_in_json || (superclass.respond_to?(:parse_root_in_json?) && superclass.parse_root_in_json?)
+        end
+      end
+    end
+  end
+end

data/lib/castle-her/model/paths.rb

@@ -0,0 +1,126 @@
+module Her
+  module Model
+    module Paths
+      extend ActiveSupport::Concern
+      # Return a path based on the collection path and a resource data
+      #
+      # @example
+      #   class User
+      #     include Her::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 Her::Model
+        #    primary_key 'UserId'
+        #  end
+        #
+        # @param [Symbol] value
+        def primary_key(value = nil)
+          @_her_primary_key ||= begin
+            superclass.primary_key if superclass.respond_to?(:primary_key)
+          end
+
+          return @_her_primary_key unless value
+          @_her_primary_key = value.to_sym
+        end
+
+        # Defines a custom collection path for the resource
+        #
+        # @example
+        #  class User
+        #    include Her::Model
+        #    collection_path "/users"
+        #  end
+        def collection_path(path = nil)
+          if path.nil?
+            @_her_collection_path ||= root_element.to_s.pluralize
+          else
+            @_her_collection_path = path
+            @_her_resource_path = "#{path}/:id"
+          end
+        end
+
+        # Defines a custom resource path for the resource
+        #
+        # @example
+        #  class User
+        #    include Her::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 Her::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?
+            @_her_resource_path ||= "#{root_element.to_s.pluralize}/:id"
+          else
+            @_her_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].kind_of?(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(Her::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

data/lib/castle-her/model/relation.rb

@@ -0,0 +1,164 @@
+module Her
+  module Model
+    class Relation
+      # @private
+      attr_accessor :params
+
+      # @private
+      def initialize(parent)
+        @parent = parent
+        @params = {}
+      end
+
+      # @private
+      def apply_to(attributes)
+        @params.merge(attributes)
+      end
+
+      # Build a new resource
+      def build(attributes = {})
+        @parent.build(@params.merge(attributes))
+      end
+
+      # Add a query string parameter
+      #
+      # @example
+      #   @users = User.all
+      #   # Fetched via GET "/users"
+      #
+      # @example
+      #   @users = User.where(:approved => 1).all
+      #   # Fetched via GET "/users?approved=1"
+      def where(params = {})
+        return self if params.blank? && !@_fetch.nil?
+        self.clone.tap do |r|
+          r.params = r.params.merge(params)
+          r.clear_fetch_cache!
+        end
+      end
+      alias all where
+
+      # Bubble all methods to the fetched collection
+      #
+      # @private
+      def method_missing(method, *args, &blk)
+        fetch.send(method, *args, &blk)
+      end
+
+      # @private
+      def respond_to?(method, *args)
+        super || fetch.respond_to?(method, *args)
+      end
+
+      # @private
+      def nil?
+        fetch.nil?
+      end
+
+      # @private
+      def kind_of?(thing)
+        fetch.kind_of?(thing)
+      end
+
+      # Fetch a collection of resources
+      #
+      # @private
+      def fetch
+        @_fetch ||= begin
+          path = @parent.build_request_path(@params)
+          method = @parent.method_for(:find)
+          @parent.request(@params.merge(:_method => method, :_path => path)) do |parsed_data, response|
+            @parent.new_collection(parsed_data)
+          end
+        end
+      end
+
+      # Fetch specific resource(s) by their ID
+      #
+      # @example
+      #   @user = User.find(1)
+      #   # Fetched via GET "/users/1"
+      #
+      # @example
+      #   @users = User.find([1, 2])
+      #   # Fetched via GET "/users/1" and GET "/users/2"
+      def find(*ids)
+        params = @params.merge(ids.last.is_a?(Hash) ? ids.pop : {})
+        ids = Array(params[@parent.primary_key]) if params.key?(@parent.primary_key)
+
+        results = ids.flatten.compact.uniq.map do |id|
+          resource = nil
+          request_params = params.merge(
+            :_method => @parent.method_for(:find),
+            :_path => @parent.build_request_path(params.merge(@parent.primary_key => id))
+          )
+
+          @parent.request(request_params) do |parsed_data, response|
+            if response.success?
+              resource = @parent.new_from_parsed_data(parsed_data)
+              resource.instance_variable_set(:@changed_attributes, {})
+              resource.run_callbacks :find
+            else
+              return nil
+            end
+          end
+
+          resource
+        end
+
+        ids.length > 1 || ids.first.kind_of?(Array) ? results : results.first
+      end
+
+      # Create a resource and return it
+      #
+      # @example
+      #   @user = User.create(:fullname => "Tobias Fünke")
+      #   # Called via POST "/users/1" with `&fullname=Tobias+Fünke`
+      #
+      # @example
+      #   @user = User.where(:email => "tobias@bluth.com").create(:fullname => "Tobias Fünke")
+      #   # Called via POST "/users/1" with `&email=tobias@bluth.com&fullname=Tobias+Fünke`
+      def create(attributes = {})
+        attributes ||= {}
+        resource = @parent.new(@params.merge(attributes))
+        resource.save
+
+        resource
+      end
+
+      # Fetch a resource and create it if it's not found
+      #
+      # @example
+      #   @user = User.where(:email => "remi@example.com").find_or_create
+      #
+      #   # Returns the first item of the collection if present:
+      #   # GET "/users?email=remi@example.com"
+      #
+      #   # If collection is empty:
+      #   # POST /users with `email=remi@example.com`
+      def first_or_create(attributes = {})
+        fetch.first || create(attributes)
+      end
+
+      # Fetch a resource and build it if it's not found
+      #
+      # @example
+      #   @user = User.where(:email => "remi@example.com").find_or_initialize
+      #
+      #   # Returns the first item of the collection if present:
+      #   # GET "/users?email=remi@example.com"
+      #
+      #   # If collection is empty:
+      #   @user.email # => "remi@example.com"
+      #   @user.new? # => true
+      def first_or_initialize(attributes = {})
+        fetch.first || build(attributes)
+      end
+
+      # @private
+      def clear_fetch_cache!
+        instance_variable_set(:@_fetch, nil)
+      end
+    end
+  end
+end