castle-her 1.0.1

data/lib/castle-her/middleware/first_level_parse_json.rb

@@ -0,0 +1,36 @@
+module Her
+  module Middleware
+    # This middleware treat the received first-level JSON structure as the resource data.
+    class FirstLevelParseJSON < ParseJSON
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      # @private
+      def parse(body)
+        json = parse_json(body)
+        errors = json.delete(:errors) || {}
+        metadata = json.delete(:metadata) || {}
+        {
+          :data => json,
+          :errors => errors,
+          :metadata => metadata
+        }
+      end
+
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      # @private
+      def on_complete(env)
+        env[:body] = case env[:status]
+        when 204
+          parse('{}')
+        else
+          parse(env[:body])
+        end
+      end
+    end
+  end
+end

data/lib/castle-her/middleware/json_api_parser.rb

@@ -0,0 +1,36 @@
+module Her
+  module Middleware
+    # This middleware expects the resource/collection data to be contained in the `data`
+    # key of the JSON object
+    class JsonApiParser < ParseJSON
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      # @private
+      def parse(body)
+        json = parse_json(body)
+
+        {
+          :data => json[:data] || {},
+          :errors => json[:errors] || [],
+          :metadata => json[:meta] || {},
+        }
+      end
+
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      # @private
+      def on_complete(env)
+        env[:body] = case env[:status]
+        when 204
+          parse('{}')
+        else
+          parse(env[:body])
+        end
+      end
+    end
+  end
+end

data/lib/castle-her/middleware/parse_json.rb

@@ -0,0 +1,21 @@
+module Her
+  module Middleware
+    class ParseJSON < Faraday::Response::Middleware
+      # @private
+      def parse_json(body = nil)
+        body = '{}' if body.blank?
+        message = "Response from the API must behave like a Hash or an Array (last JSON response was #{body.inspect})"
+
+        json = begin
+          MultiJson.load(body, :symbolize_keys => true)
+        rescue MultiJson::LoadError
+          raise Her::Errors::ParseError, message
+        end
+
+        raise Her::Errors::ParseError, message unless json.is_a?(Hash) or json.is_a?(Array)
+
+        json
+      end
+    end
+  end
+end

data/lib/castle-her/middleware/second_level_parse_json.rb

@@ -0,0 +1,36 @@
+module Her
+  module Middleware
+    # This middleware expects the resource/collection data to be contained in the `data`
+    # key of the JSON object
+    class SecondLevelParseJSON < ParseJSON
+      # Parse the response body
+      #
+      # @param [String] body The response body
+      # @return [Mixed] the parsed response
+      # @private
+      def parse(body)
+        json = parse_json(body)
+
+        {
+          :data => json[:data],
+          :errors => json[:errors],
+          :metadata => json[:metadata]
+        }
+      end
+
+      # This method is triggered when the response has been received. It modifies
+      # the value of `env[:body]`.
+      #
+      # @param [Hash] env The response environment
+      # @private
+      def on_complete(env)
+        env[:body] = case env[:status]
+        when 204
+          parse('{}')
+        else
+          parse(env[:body])
+        end
+      end
+    end
+  end
+end

data/lib/castle-her/model.rb

@@ -0,0 +1,75 @@
+require "castle-her/model/base"
+require "castle-her/model/deprecated_methods"
+require "castle-her/model/http"
+require "castle-her/model/attributes"
+require "castle-her/model/relation"
+require "castle-her/model/orm"
+require "castle-her/model/parse"
+require "castle-her/model/associations"
+require "castle-her/model/introspection"
+require "castle-her/model/paths"
+require "castle-her/model/nested_attributes"
+require "active_model"
+
+module Her
+  # This module is the main element of Her. After creating a Her::API object,
+  # include this module in your models to get a few magic methods defined in them.
+  #
+  # @example
+  #   class User
+  #     include Her::Model
+  #   end
+  #
+  #   @user = User.new(:name => "Rémi")
+  #   @user.save
+  module Model
+    extend ActiveSupport::Concern
+
+    # Her modules
+    include Her::Model::Base
+    include Her::Model::DeprecatedMethods
+    include Her::Model::Attributes
+    include Her::Model::ORM
+    include Her::Model::HTTP
+    include Her::Model::Parse
+    include Her::Model::Introspection
+    include Her::Model::Paths
+    include Her::Model::Associations
+    include Her::Model::NestedAttributes
+
+    # Supported ActiveModel modules
+    include ActiveModel::AttributeMethods
+    include ActiveModel::Validations
+    include ActiveModel::Validations::Callbacks
+    include ActiveModel::Conversion
+    include ActiveModel::Dirty
+
+    # Class methods
+    included do
+      # Assign the default API
+      use_api Her::API.default_api
+      method_for :create, :post
+      method_for :update, :put
+      method_for :find, :get
+      method_for :destroy, :delete
+      method_for :new, :get
+
+      # Define the default primary key
+      primary_key :id
+
+      # Define default storage accessors for errors and metadata
+      store_response_errors :response_errors
+      store_metadata :metadata
+
+      # Include ActiveModel naming methods
+      extend ActiveModel::Translation
+
+      # Configure ActiveModel callbacks
+      extend ActiveModel::Callbacks
+      define_model_callbacks :create, :update, :save, :find, :destroy, :initialize
+
+      # Define matchers for attr? and attr= methods
+      define_attribute_method_matchers
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+require "castle-her/model/associations/association"
+require "castle-her/model/associations/association_proxy"
+require "castle-her/model/associations/belongs_to_association"
+require "castle-her/model/associations/has_many_association"
+require "castle-her/model/associations/has_one_association"
+
+module Her
+  module Model
+    # This module adds associations to models
+    module Associations
+      extend ActiveSupport::Concern
+
+      # Returns true if the model has a association_name association, false otherwise.
+      #
+      # @private
+      def has_association?(association_name)
+        associations = self.class.associations.values.flatten.map { |r| r[:name] }
+        associations.include?(association_name)
+      end
+
+      # Returns the resource/collection corresponding to the association_name association.
+      #
+      # @private
+      def get_association(association_name)
+        send(association_name) if has_association?(association_name)
+      end
+
+      module ClassMethods
+        # Return @_her_associations, lazily initialized with copy of the
+        # superclass' her_associations, or an empty hash.
+        #
+        # @private
+        def associations
+          @_her_associations ||= begin
+            superclass.respond_to?(:associations) ? superclass.associations.dup : Hash.new { |h,k| h[k] = [] }
+          end
+        end
+
+        # @private
+        def association_names
+          associations.inject([]) { |memo, (name, details)| memo << details }.flatten.map { |a| a[:name] }
+        end
+
+        # @private
+        def association_keys
+          associations.inject([]) { |memo, (name, details)| memo << details }.flatten.map { |a| a[:data_key] }
+        end
+
+        # Parse associations data after initializing a new object
+        #
+        # @private
+        def parse_associations(data)
+          associations.each_pair do |type, definitions|
+            definitions.each do |association|
+              association_class = "her/model/associations/#{type}_association".classify.constantize
+              data.merge! association_class.parse(association, self, data)
+            end
+          end
+
+          data
+        end
+
+        # Define an *has_many* association.
+        #
+        # @param [Symbol] name The name of the method added to resources
+        # @param [Hash] opts Options
+        # @option opts [String] :class_name The name of the class to map objects to
+        # @option opts [Symbol] :data_key The attribute where the data is stored
+        # @option opts [Path] :path The relative path where to fetch the data (defaults to `/{name}`)
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_many :articles
+        #   end
+        #
+        #   class Article
+        #     include Her::Model
+        #   end
+        #
+        #   @user = User.find(1)
+        #   @user.articles # => [#<Article(articles/2) id=2 title="Hello world.">]
+        #   # Fetched via GET "/users/1/articles"
+        def has_many(name, opts={})
+          Her::Model::Associations::HasManyAssociation.attach(self, name, opts)
+        end
+
+        # Define an *has_one* association.
+        #
+        # @param [Symbol] name The name of the method added to resources
+        # @param [Hash] opts Options
+        # @option opts [String] :class_name The name of the class to map objects to
+        # @option opts [Symbol] :data_key The attribute where the data is stored
+        # @option opts [Path] :path The relative path where to fetch the data (defaults to `/{name}`)
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_one :organization
+        #   end
+        #
+        #   class Organization
+        #     include Her::Model
+        #   end
+        #
+        #   @user = User.find(1)
+        #   @user.organization # => #<Organization(organizations/2) id=2 name="Foobar Inc.">
+        #   # Fetched via GET "/users/1/organization"
+        def has_one(name, opts={})
+          Her::Model::Associations::HasOneAssociation.attach(self, name, opts)
+        end
+
+        # Define a *belongs_to* association.
+        #
+        # @param [Symbol] name The name of the method added to resources
+        # @param [Hash] opts Options
+        # @option opts [String] :class_name The name of the class to map objects to
+        # @option opts [Symbol] :data_key The attribute where the data is stored
+        # @option opts [Path] :path The relative path where to fetch the data (defaults to `/{class_name}.pluralize/{id}`)
+        # @option opts [Symbol] :foreign_key The foreign key used to build the `:id` part of the path (defaults to `{name}_id`)
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     belongs_to :team, :class_name => "Group"
+        #   end
+        #
+        #   class Group
+        #     include Her::Model
+        #   end
+        #
+        #   @user = User.find(1) # => #<User(users/1) id=1 team_id=2 name="Tobias">
+        #   @user.team # => #<Team(teams/2) id=2 name="Developers">
+        #   # Fetched via GET "/teams/2"
+        def belongs_to(name, opts={})
+          Her::Model::Associations::BelongsToAssociation.attach(self, name, opts)
+        end
+      end
+    end
+  end
+end

data/lib/castle-her/model/associations/association.rb

@@ -0,0 +1,103 @@
+module Her
+  module Model
+    module Associations
+      class Association
+        # @private
+        attr_accessor :params
+
+        # @private
+        def initialize(parent, opts = {})
+          @parent = parent
+          @opts = opts
+          @params = {}
+
+          @klass = @parent.class.her_nearby_class(@opts[:class_name])
+          @name = @opts[:name]
+        end
+
+        # @private
+        def self.proxy(parent, opts = {})
+          AssociationProxy.new new(parent, opts)
+        end
+
+        # @private
+        def self.parse_single(association, klass, data)
+          data_key = association[:data_key]
+          return {} unless data[data_key]
+
+          klass = klass.her_nearby_class(association[:class_name])
+          if data[data_key].kind_of?(klass)
+            { association[:name] => data[data_key] }
+          else
+            { association[:name] => klass.new(klass.parse(data[data_key])) }
+          end
+        end
+
+        # @private
+        def assign_single_nested_attributes(attributes)
+          if @parent.attributes[@name].blank?
+            @parent.attributes[@name] = @klass.new(@klass.parse(attributes))
+          else
+            @parent.attributes[@name].assign_attributes(attributes)
+          end
+        end
+
+        # @private
+        def fetch(opts = {})
+          attribute_value = @parent.attributes[@name]
+          return @opts[:default].try(:dup) if @parent.attributes.include?(@name) && (attribute_value.nil? || !attribute_value.nil? && attribute_value.empty?) && @params.empty?
+
+          return @cached_result unless @params.any? || @cached_result.nil?
+          return @parent.attributes[@name] unless @params.any? || @parent.attributes[@name].blank?
+
+          path = build_association_path lambda { "#{@parent.request_path(@params)}#{@opts[:path]}" }
+          @klass.get(path, @params).tap do |result|
+            @cached_result = result unless @params.any?
+          end
+        end
+
+        # @private
+        def build_association_path(code)
+          begin
+            instance_exec(&code)
+          rescue Her::Errors::PathError
+            return nil
+          end
+        end
+
+        # Add query parameters to the HTTP request performed to fetch the data
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_many :comments
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments.where(:approved => 1) # Fetched via GET "/users/1/comments?approved=1
+        def where(params = {})
+          return self if params.blank? && @parent.attributes[@name].blank?
+          AssociationProxy.new self.clone.tap { |a| a.params = a.params.merge(params) }
+        end
+        alias all where
+
+        # Fetches the data specified by id
+        #
+        # @example
+        #   class User
+        #     include Her::Model
+        #     has_many :comments
+        #   end
+        #
+        #   user = User.find(1)
+        #   user.comments.find(3) # Fetched via GET "/users/1/comments/3
+        def find(id)
+          return nil if id.blank?
+          path = build_association_path lambda { "#{@parent.request_path(@params)}#{@opts[:path]}/#{id}" }
+          @klass.get_resource(path, @params)
+        end
+
+      end
+    end
+  end
+end