shamu 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7dbbdb9cc8883493b91766988eafe575fdc6d7b4
-  data.tar.gz: c4c2e75d33b28dd7759d656d60c5b1dd444a3dc7
+  metadata.gz: 607eb630404b0977965af426db12d63821be992c
+  data.tar.gz: 70638f256144a1b3b20984b5bb3950aee54cc76e
 SHA512:
-  metadata.gz: ff33cde446d56d6a4d0930f0cd74d00b9a893af315bf2dcdcfb70f0289f33d53cdcfa93c229df4672c54947d1ec409cd8fb195913607be34b8432d972fc49b8d
-  data.tar.gz: e47d92497b0485d0cb356550d932aacce2f2a8a47177b2f3e51f7ff960ed2d990301f00a176751ca4b4ff9861edbcaa784de6da7bacad103b4f92a1be907de12
+  metadata.gz: 365c41405a527220f21112099997ddf023c1c7bfc8b93ddc1cdf7e6275302c103adf2bf79266a2a22661e576d095ed6899f49cda35a2293907ad28b7b18ed40c
+  data.tar.gz: 6d657880be0470a380ba0c1a31718bf4877866c940a07e5c6780cd7c550c31db8a7992730bd3340e24cff610c9c1ac24e4723580f1a005c1674aa06f547b128f

data/Gemfile

@@ -6,6 +6,7 @@ gemspec
 group :test do
   gem "activerecord", "~> 4.2.5"
   gem "actionpack", "~> 4.2.5"
+  gem "responders", "~> 2.1.2"
   gem "kaminari", "~> 0.16.3", require: false
 
   gem "byebug"

data/lib/shamu/entities/entity.rb

@@ -70,6 +70,9 @@ module Shamu
       include Shamu::Attributes::Equality
       include Shamu::ToModelIdExtension::Models
 
+      extend ActiveModel::Naming
+      include ActiveModel::Conversion
+
       # @!attribute
       # @return [Object] id of the entity.
       #

data/lib/shamu/json_api/base_builder.rb

@@ -4,69 +4,29 @@ module Shamu
     # Used by a {Serilaizer} to write fields and relationships
     class BaseBuilder
 
-      # ============================================================================
-      # @!group Attributes
-      #
-
-      # @!attribute
-      # @return [Context] the JSON serialization context.
-        attr_reader :context
-
-      #
-      # @!endgroup Attributes
-
-
       # @param [Context] context the current serialization context.
       def initialize( context )
         @context = context
         @output = {}
       end
 
-      # Write a resource linkage info.
-      #
-      # @param [String] type of the resource.
-      # @param [Object] id of the resource.
-      # @return [void]
-      def identifier( type, id = nil )
-        output[:type] = type.to_s
-        output[:id]   = id.to_s
-      end
-
-      # Write a link  to another resource.
-      #
-      # @param [String,Symbol] name of the link.
-      # @param [String] url
-      # @param [Hash] meta optional additional meta information.
-      # @return [void]
-      def link( name, url, meta: nil )
-        links = ( output[:links] ||= {} )
-
-        if meta # rubocop:disable Style/ConditionalAssignment
-          links[ name.to_sym ] = { href: url, meta: meta }
-        else
-          links[ name.to_sym ] = url
-        end
-      end
-
-      # Add a meta field.
-      # @param [String,Symbol] name of the meta field.
-      # @param [Object] vlaue that can be converted to a JSON primitive type.
-      # @return [void]
-      def meta( name, value )
-        meta = ( output[:meta] ||= {} )
-        meta[ name.to_sym ] = value
-      end
+      include BuilderMethods::Link
+      include BuilderMethods::Meta
 
       # @return [Hash] the results output as JSON safe hash.
       def compile
-        fail JsonApi::IncompleteResourceError unless output[:type]
         output
       end
 
       private
 
-        attr_reader :output
+        # @!attribute
+        # @return [Hash] output hash.
+          attr_reader :output
 
+        # @!attribute
+        # @return [Context] the JSON serialization context.
+          attr_reader :context
     end
   end
 end

data/lib/shamu/json_api/builder_methods/identifier.rb

@@ -0,0 +1,34 @@
+module Shamu
+  module JsonApi
+    module BuilderMethods
+      module Identifier
+        # Write a resource linkage info.
+        #
+        # @param [String] type of the resource.
+        # @param [Object] id of the resource.
+        # @return [self]
+        def identifier( type, id = nil )
+          output[:type] = @type = type.to_s
+          output[:id]   = id.to_s
+
+          self
+        end
+
+        # (see BaseBuilder#compile)
+        def compile
+          require_identifier!
+          super
+        end
+
+        private
+
+          attr_reader :type
+
+          def require_identifier!
+            fail IncompleteResourceError unless type
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/json_api/builder_methods/link.rb

@@ -0,0 +1,25 @@
+module Shamu
+  module JsonApi
+    module BuilderMethods
+      module Link
+        # Write a link  to another resource.
+        #
+        # @param [String,Symbol] name of the link.
+        # @param [String] url
+        # @param [Hash] meta optional additional meta information.
+        # @return [self]
+        def link( name, url, meta: nil )
+          links = ( output[:links] ||= {} )
+
+          if meta # rubocop:disable Style/ConditionalAssignment
+            links[ name.to_sym ] = { href: url, meta: meta }
+          else
+            links[ name.to_sym ] = url
+          end
+
+          self
+        end
+      end
+    end
+  end
+end

data/lib/shamu/json_api/builder_methods/meta.rb

@@ -0,0 +1,18 @@
+module Shamu
+  module JsonApi
+    module BuilderMethods
+      module Meta
+        # Add a meta field.
+        # @param [String,Symbol] name of the meta field.
+        # @param [Object] vlaue that can be converted to a JSON primitive type.
+        # @return [self]
+        def meta( name, value )
+          meta = ( output[:meta] ||= {} )
+          meta[ name.to_sym ] = value
+
+          self
+        end
+      end
+    end
+  end
+end

data/lib/shamu/json_api/builder_methods.rb

@@ -0,0 +1,9 @@
+module Shamu
+  module JsonApi
+    module BuilderMethods
+      require "shamu/json_api/builder_methods/link"
+      require "shamu/json_api/builder_methods/meta"
+      require "shamu/json_api/builder_methods/identifier"
+    end
+  end
+end

data/lib/shamu/json_api/context.rb

@@ -30,9 +30,9 @@ module Shamu
       # obtained by calling {#find_presenter}.
       #
       # @param [Object] resource to be serialized.
-      # @param [Presenter] presenter to use to serialize the object. If
-      #     not provided a default {Presenter} will be chosen.
-      # @return [resource]
+      # @param [Class] presenter tpresenter {Presenter} class to use to
+      #     serialize the `resource`. If not provided a default {Presenter} will
+      #     be chosen.
       # @yield (builder)
       # @yieldparam [ResourceBuilder] builder to write embedded resource to.
       def include_resource( resource, presenter = nil, &block )
@@ -84,7 +84,7 @@ module Shamu
       # - Fails with a {NoPresenter} error if a presenter cannot be found.
       #
       # @param [Object] resource to present.
-      # @return [Presenter]
+      # @return [Class] the {Presenter} class to use.
       # @raise [NoPresenter] if a presenter cannot be found.
       def find_presenter( resource )
         presenter   = presenters[ resource.class ]
@@ -92,7 +92,7 @@ module Shamu
 
         fail NoPresenter.new( resource, namespaces ) unless presenter
 
-        presenter.is_a?( Class ) ? presenter.new : presenter
+        presenter
       end
 
 

data/lib/shamu/json_api/error.rb

@@ -10,7 +10,6 @@ module Shamu
         def translation_scope
           super.dup.insert( 1, :json_api )
         end
-
     end
 
     # Raised if an {ResourceBuilder#identifier} was not built.
@@ -20,12 +19,6 @@ module Shamu
       end
     end
 
-    class IdentifierRequiredError < Error
-      def initialize( message = :identifier_required )
-        super
-      end
-    end
-
     class NoPresenter < Error
       def initialize( resource, namespaces )
         super translate( :no_presenter, class: resource.class, namespaces: namespaces )

data/lib/shamu/json_api/error_builder.rb

@@ -7,65 +7,76 @@ module Shamu
     class ErrorBuilder
 
       def initialize
-        @output = { id: SecureRandom.uuid }
+        @output = {}
       end
 
+      include BuilderMethods::Link
+      include BuilderMethods::Meta
+
       # @param [String] id unique id for this occurrence of the error.
+      # @return [self]
       def id( id )
         output[:id] = id
-      end
-
-      # Summary of the error.
-      # @param [Integer] http_status code.
-      # @param [String,Symbol] code application specific code for the error.
-      # @param [String] human friendly title for the error.
-      def summary( http_status, code = nil, title = nil )
-        code ||= ::Rack::Util::HTTP_STATUS_CODES[ code ].to_s.underscore
-
-        output[:status] = http_status.to_s
-        output[:code]   = code.to_s
-        output[:title]  = title || code.to_s.titleize
+        self
       end
 
       # Summarize an exception as an error.
       # @param [Exception] exception
-      # @param [Integer] http_status code. Default 400.
-      def exception( exception, http_status = nil )
-        http_status ||= 500
-
+      # @return [self]
+      def exception( exception )
         name = exception.class.name.demodulize.gsub( /Error$/, "" )
-        summary http_status, name.underscore, name.titleize
+        code name.underscore
+        title name.titleize
         detail exception.message
+
+        self
+      end
+
+      # Set an HTTP status code related to the error.
+      # @param [Symbol,Integer] status code.
+      # @return [self]
+      def http_status( status )
+        status = ::Rack::Utils.status_code( status ) if status.is_a? Symbol
+        output[:status] = status.to_s
+        self
+      end
+
+      # Set an application specific error code.
+      # @return [self]
+      def code( code )
+        output[:code] = code.to_s
+        self
+      end
+
+      # Set a short human readable title of the error.
+      # @return [self]
+      def title( title )
+        output[:title] = title.to_s
+        self
       end
 
       # @return [String] message details about the error.
+      # @return [self]
       def detail( message )
         output[:detail] = message
+        self
       end
 
-      # Write a link to error information.
-      #
-      # @param [String,Symbol] name of the link.
-      # @param [String] url
-      # @param [Hash] meta optional additional meta information.
-      # @return [void]
-      def link( name, url, meta: nil )
-        links = ( output[:links] ||= {} )
-
-        if meta # rubocop:disable Style/ConditionalAssignment
-          links[ name.to_sym ] = { href: url, meta: meta }
-        else
-          links[ name.to_sym ] = url
-        end
+      # JSON pointer to the associated document in the request that was the
+      # source of the pointer.
+      # @return [self]
+      def pointer( pointer )
+        output[:source] ||= {}
+        output[:source][:pointer] = pointer
+        self
       end
 
-      # Add a meta field.
-      # @param [String,Symbol] name of the meta field.
-      # @param [Object] value that can be converted to a JSON primitive type.
-      # @return [void]
-      def meta( name, value )
-        meta = ( output[:meta] ||= {} )
-        meta[ name.to_sym ] = value
+      # The name of the parameter that caused the error.
+      # @return [self]
+      def parameter( name )
+        output[:source] ||= {}
+        output[:source][:parameter] = name
+        self
       end
 
       # @return [Hash] the results output as JSON safe hash.

data/lib/shamu/json_api/presenter.rb

@@ -1,18 +1,50 @@
 module Shamu
   module JsonApi
 
-    # Present an object to a JSON API {ResourceBuilder builder}.
+    # Presenters are responsible for projecting an {Entities::Entity} or PORO
+    # to a well-formatted JSON API {ResourceBuilder builder} response.
+    #
+    # {Presenter} delegates all of the {ResourceBuilder} methods for convenient
+    # syntax.
+    #
+    # ```
+    # class UserPresenter < ApplicationPresenter
+    #   def present
+    #     identifier :user, resource.id
+    #
+    #     attributes name: resource.name,
+    #                email: resource.email
+    #
+    #     relationship( :address ) do |rel|
+    #       rel.identifier :address, resource.address_id
+    #       rel.link :related, user_address_url( resource, resource.address_id )
+    #     end
+    #   end
+    # end
+    # ```
     class Presenter
 
+      # @param [Object] resource to presenter.
+      # @param [ResourceBuilder] builder used to build the JSON API response.
+      def initialize( resource, builder )
+        @resource = resource
+        @builder  = builder
+      end
+
       # Serialize the `resource` to the `builder`.
       #
-      # @param [Object] resource to present.
-      # @param [ResourceBuilder] builder to write to.
       # @return [void]
-      def present( resource, builder )
+      def present
         fail NotImplementedError
       end
 
+      private
+
+        delegate :relationship, :attribute, :attributes, :link, :identifier, :meta, to: :builder
+
+        attr_reader :resource
+        attr_reader :builder
+
     end
   end
 end

data/lib/shamu/json_api/relationship_builder.rb

@@ -6,11 +6,25 @@ module Shamu
     # Build a relationship from one resource to another.
     class RelationshipBuilder < BaseBuilder
 
+
       # (see Context#include_resource)
-      def include_resource( resource, serializer = nil, &block )
-        context.include_resource resource, serializer, &block
+      def include_resource( resource, presenter = nil, &block )
+        context.include_resource resource, presenter, &block
       end
 
+      include BuilderMethods::Identifier
+
+      # Write a resource linkage info.
+      #
+      # @param [String] type of the resource.
+      # @param [Object] id of the resource.
+      # @return [void]
+      def identifier( type, id = nil )
+        output[:data] ||= {}
+        output[:data][:type] = @type = type.to_s
+        output[:data][:id]   = id.to_s
+        self
+      end
     end
   end
 end

data/lib/shamu/json_api/resource_builder.rb

@@ -6,6 +6,8 @@ module Shamu
     # Used by a {Serilaizer} to write fields and relationships
     class ResourceBuilder < BaseBuilder
 
+      include BuilderMethods::Identifier
+
       # @overload attribute( attributes )
       #   @param [Hash] attributes to write.
       # @overload attribute( name, value )
@@ -26,6 +28,7 @@ module Shamu
           end
         end
       end
+      alias_method :attributes, :attribute
 
       # Build a relationship reference.
       #
@@ -54,21 +57,8 @@ module Shamu
         relationships[ name.to_sym ] = builder.compile
       end
 
-      # (see BaseBuilder#identifier)
-      def identifier( * )
-        super.tap do
-          @type = output[:type]
-        end
-      end
-
       private
 
-        attr_reader :type
-
-        def require_identifier!
-          fail IdentifierRequiredError unless @type
-        end
-
         def add_attribute( name, value )
           return unless context.include_field?( type, name )
 

data/lib/shamu/json_api/response.rb

@@ -34,31 +34,50 @@ module Shamu
         self
       end
 
-      # @overload error( exception, http_status = nil )
+      # @overload error( exception )
       #   @param (see ErrorBuilder#exception)
       # @overload error( &block )
       #   @yield (builder)
       #   @yieldparam [ErrorBuilder] builder used to describe the error.
       #
       # @return [self]
-      def error( exception = nil, http_status = nil, &block )
+      def error( error = nil, &block )
         builder = ErrorBuilder.new
 
-        if block_given?
-          yield builder
-        elsif exception.is_a?( Exception )
-          builder.exception( exception, http_status )
-        else
-          http_status ||= 500
-          builder.summary http_status, http_status.to_s, exception
+        if error.is_a?( Exception )
+          builder.exception( error )
+        elsif error
+          builder.title error
         end
 
+        yield builder if block_given?
+
         errors = ( output[:errors] ||= [] )
         errors << builder.compile
 
         self
       end
 
+      # Write ActiveModel validation errors to the response.
+      #
+      # @param [Hash<Symbol,String>] errors map of attributes to errors.
+      # @yield ( builder, attr, message )
+      # @yieldparam [ErrorBuilder] builder the builder for this error message.
+      # @yieldparam [String] attr the attribute with a validation error.
+      # @yieldparam [String] message the error message.
+      # @return [self]
+      def validation_errors( errors, &block )
+        errors.each do |attr, message|
+          error message do |builder|
+            path = "/data"
+            path << "/attributes/#{ attr }" unless attr == :base
+            builder.pointer path
+
+            yield builder, attr, message if block_given?
+          end
+        end
+      end
+
       # (see BaseBuilder#compile)
       def compile
         @compiled ||= begin
@@ -95,17 +114,15 @@ module Shamu
         to_json
       end
 
-      # Responses don't have identifiers
-      undef :identifier
-
       private
 
         def build_resource( resource, presenter, &block )
           presenter = context.find_presenter( resource ) if !presenter && !block_given?
+          builder   = ResourceBuilder.new( context )
 
-          builder = ResourceBuilder.new( context )
           if presenter
-            presenter.present( resource, builder )
+            instance = presenter.new( resource, builder )
+            instance.present
           else
             yield builder
           end

data/lib/shamu/json_api.rb

@@ -1,7 +1,11 @@
 module Shamu
   # {include:file:lib/shamu/json_api/README.md}
   module JsonApi
+
+    MIME_TYPE = "application/vnd.api+json".freeze
+
     require "shamu/json_api/context"
+    require "shamu/json_api/builder_methods"
     require "shamu/json_api/relationship_builder"
     require "shamu/json_api/resource_builder"
     require "shamu/json_api/response"

data/lib/shamu/locale/en.yml

@@ -29,5 +29,4 @@ en:
     json_api:
       errors:
         incomplete_resource: "`identifier` was not called to define the type and id of the resource."
-        identifier_resource: "`identifier` must be called before defining any fields."
         no_presenter: No presenter available for %{class} objects. Looked in %{namespaces}.