jsonapi-serializable 0.1.1.beta4 → 0.1.1

data/lib/jsonapi/serializable/renderer.rb

@@ -13,9 +13,9 @@ module JSONAPI
         @options    = options.dup
         @klass      = @options.delete(:class)
         @namespace  = @options.delete(:namespace)
-        @inferer    = @options.delete(:inferer)
+        @inferrer   = @options.delete(:inferrer)
         @exposures  = @options.delete(:expose) || {}
-        @exposures[:_resource_inferer] = namespace_inferer || @inferer
+        @exposures[:_resource_inferrer] = namespace_inferrer || @inferrer
       end
 
       def render
@@ -24,18 +24,21 @@ module JSONAPI
 
       private
 
+      # @api private
       def jsonapi_params
         @options
       end
 
+      # @api private
       def jsonapi_resources
-        toplevel_inferer = @klass || @inferer
+        toplevel_inferrer = @klass || @inferrer
         JSONAPI::Serializable::ResourceBuilder.build(@objects,
                                                      @exposures,
-                                                     toplevel_inferer)
+                                                     toplevel_inferrer)
       end
 
-      def namespace_inferer
+      # @api private
+      def namespace_inferrer
         return nil unless @namespace
         proc do |klass|
           names = klass.name.split('::')
@@ -61,10 +64,12 @@ module JSONAPI
 
       private
 
+      # @api private
       def jsonapi_params
         @options
       end
 
+      # @api private
       def jsonapi_errors
         @errors
       end

data/lib/jsonapi/serializable/resource/attributes.rb

@@ -0,0 +1,73 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      # Mixin to handle resource attributes.
+      module Attributes
+        def self.prepended(klass)
+          super
+          klass.class_eval do
+            extend DSL
+            class << self
+              attr_accessor :attribute_blocks
+            end
+            self.attribute_blocks = {}
+          end
+        end
+
+        def initialize(*)
+          super
+          @_attributes = {}
+        end
+
+        # @see JSONAPI::Serializable::Resource#as_jsonapi
+        def as_jsonapi(fields: nil, include: [])
+          super.tap do |hash|
+            attrs =
+              requested_attributes(fields).each_with_object({}) do |(k, v), h|
+                h[k] = instance_eval(&v)
+              end
+            hash[:attributes] = attrs if attrs.any?
+          end
+        end
+
+        # @api private
+        def requested_attributes(fields)
+          self.class.attribute_blocks
+              .select { |k, _| fields.nil? || fields.include?(k) }
+        end
+
+        # DSL methods for declaring attributes.
+        module DSL
+          def inherited(klass)
+            super
+            klass.attribute_blocks = attribute_blocks.dup
+          end
+
+          # Declare an attribute for this resource.
+          #
+          # @param [Symbol] name The key of the attribute.
+          # @yieldreturn [Hash, String, nil] The block to compute the value.
+          #
+          # @example
+          #   attribute(:name) { @object.name }
+          def attribute(name, _options = {}, &block)
+            block ||= proc { @object.public_send(name) }
+            attribute_blocks[name.to_sym] = block
+          end
+
+          # Declare a list of attributes for this resource.
+          #
+          # @param [Array] *args The attributes keys.
+          #
+          # @example
+          #   attributes :title, :body, :date
+          def attributes(*args)
+            args.each do |attr|
+              attribute(attr)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/conditional_fields.rb

@@ -0,0 +1,82 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      # Extension for handling conditional fields in serializable resources.
+      #
+      # @usage
+      #   class SerializableUser < JSONAPI::Serializable::Resource
+      #     prepend JSONAPI::Serializable::Resource::ConditionalFields
+      #
+      #     attribute :email, if: -> { @current_user.admin? }
+      #     has_many :friends, unless: -> { @object.private_profile? }
+      #   end
+      #
+      module ConditionalFields
+        def self.prepended(klass)
+          klass.class_eval do
+            extend ClassMethods
+            class << self
+              attr_accessor :condition_blocks
+            end
+            self.condition_blocks ||= {}
+          end
+        end
+
+        # DSL extensions for conditional fields.
+        module ClassMethods
+          def inherited(klass)
+            super
+            klass.condition_blocks = condition_blocks.dup
+          end
+
+          # Handle the `if` and `unless` options for attributes.
+          #
+          # @example
+          #   attribute :email, if: -> { @current_user.admin? }
+          #
+          def attribute(name, options = {}, &block)
+            super
+            _register_condition(name, options)
+          end
+
+          # Handle the `if` and `unless` options for relationships (has_one,
+          #   belongs_to, has_many).
+          #
+          # @example
+          #   has_many :friends, unless: -> { @object.private_profile? }
+          #
+          def relationship(name, options = {}, &block)
+            super
+            _register_condition(name, options)
+          end
+
+          # @api private
+          def _register_condition(name, options)
+            condition_blocks[name.to_sym] =
+              if options.key?(:if)
+                options[:if]
+              elsif options.key?(:unless)
+                proc { !instance_exec(&options[:unless]) }
+              end
+          end
+        end
+
+        # @api private
+        def requested_attributes(fields)
+          super.select { |k, _| _conditionally_included?(k) }
+        end
+
+        # @api private
+        def requested_relationships(fields)
+          super.select { |k, _| _conditionally_included?(k) }
+        end
+
+        # @api private
+        def _conditionally_included?(field)
+          condition = self.class.condition_blocks[field]
+          condition.nil? || instance_exec(&condition)
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/id.rb

@@ -0,0 +1,48 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      # Mixin to handle resource id.
+      module Id
+        def self.prepended(klass)
+          super
+          klass.class_eval do
+            extend DSL
+            class << self
+              attr_accessor :id_block
+            end
+          end
+        end
+
+        def initialize(*)
+          super
+          @_id = instance_eval(&self.class.id_block).to_s
+        end
+
+        # @see JSONAPI::Serializable::Resource#as_jsonapi
+        def as_jsonapi(*)
+          super.tap do |hash|
+            hash[:id] = @_id
+          end
+        end
+
+        # DSL methods for declaring the resource id.
+        module DSL
+          def inherited(klass)
+            super
+            klass.id_block = id_block
+          end
+
+          # Declare the JSON API id of this resource.
+          #
+          # @yieldreturn [String] The id of the resource.
+          #
+          # @example
+          #   id { @user.id.to_s }
+          def id(&block)
+            self.id_block = block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/key_transform.rb

@@ -0,0 +1,51 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      # Extension for handling automatic key transformations of
+      #   attributes/relationships.
+      #
+      # @usage
+      #   class SerializableUser < JSONAPI::Serializable::Resource
+      #     prepend JSONAPI::Serializable::Resource::KeyTransform
+      #     self.key_transform = proc { |key| key.camelize }
+      #
+      #     attribute :user_name
+      #     has_many :close_friends
+      #   end
+      #   # => will modify the serialized keys to `UserName` and `CloseFriends`.
+      module KeyTransform
+        def self.prepended(klass)
+          klass.class_eval do
+            extend ClassMethods
+            class << self
+              attr_accessor :key_transform
+            end
+          end
+        end
+
+        # DSL extensions for automatic key transformations.
+        module ClassMethods
+          def inherited(klass)
+            super
+            klass.key_transform = key_transform
+          end
+
+          # Handles automatic key transformation for attributes.
+          def attribute(name, options = {}, &block)
+            block ||= proc { @object.public_send(name) }
+            super(key_transform.call(name), options, &block)
+          end
+
+          # Handles automatic key transformation for relationships.
+          def relationship(name, options = {}, &block)
+            rel_block = proc do
+              data(options[:class]) { @object.public_send(name) }
+              instance_eval(&block) unless block.nil?
+            end
+            super(key_transform.call(name), options, &rel_block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/links.rb

@@ -0,0 +1,67 @@
+require 'jsonapi/serializable/link'
+
+module JSONAPI
+  module Serializable
+    class Resource
+      # Mixin for handling resource links.
+      module Links
+        def self.prepended(klass)
+          super
+          klass.class_eval do
+            extend DSL
+            class << self
+              attr_accessor :link_blocks
+            end
+            self.link_blocks = {}
+          end
+        end
+
+        def initialize(*)
+          super
+          @_links = self.class.link_blocks.each_with_object({}) do |(k, v), h|
+            h[k] = Link.as_jsonapi(@_exposures, &v)
+          end
+        end
+
+        # @see JSONAPI::Serializable::Resource#as_jsonapi
+        def as_jsonapi(*)
+          super.tap do |hash|
+            hash[:links] = @_links if @_links.any?
+          end
+        end
+
+        # DSL methods for declaring resource links.
+        module DSL
+          def inherited(klass)
+            super
+            klass.link_blocks = link_blocks.dup
+          end
+
+          # Declare a link for this resource. The properties of the link are set
+          #   by providing a block in which the DSL methods of
+          #   +JSONAPI::Serializable::Link+ are called, or the value of the link
+          #   is returned directly.
+          # @see JSONAPI::Serialiable::Link
+          #
+          # @param [Symbol] name The key of the link.
+          # @yieldreturn [Hash, String, nil] The block to compute the value, if
+          #   any.
+          #
+          # @example
+          #   link(:self) do
+          #     "http://api.example.com/users/#{@user.id}"
+          #   end
+          #
+          # @example
+          #    link(:self) do
+          #      href "http://api.example.com/users/#{@user.id}"
+          #      meta is_self: true
+          #    end
+          def link(name, &block)
+            link_blocks[name] = block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/meta.rb

@@ -0,0 +1,62 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      # Mixin for handling resource meta.
+      module Meta
+        def self.prepended(klass)
+          super
+          klass.class_eval do
+            extend DSL
+            class << self
+              attr_accessor :meta_val, :meta_block
+            end
+          end
+        end
+
+        def initialize(*)
+          super
+          @_meta = if self.class.meta_block
+                     instance_eval(&self.class.meta_block)
+                   else
+                     self.class.meta_val
+                   end
+        end
+
+        # @see JSONAPI::Serializable::Resource#as_jsonapi
+        def as_jsonapi(*)
+          super.tap do |hash|
+            hash[:meta] = @_meta unless @_meta.nil?
+          end
+        end
+
+        # DSL methods for declaring resource meta.
+        module DSL
+          def inherited(klass)
+            super
+            klass.meta_val   = meta_val
+            klass.meta_block = meta_block
+          end
+
+          # @overload meta(value)
+          #   Declare the meta information for this resource.
+          #   @param [Hash] value The meta information hash.
+          #
+          #   @example
+          #     meta key: value
+          #
+          # @overload meta(&block)
+          #   Declare the meta information for this resource.
+          #   @yieldreturn [String] The meta information hash.
+          #   @example
+          #     meta do
+          #       { key: value }
+          #     end
+          def meta(value = nil, &block)
+            self.meta_val = value
+            self.meta_block = block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/relationships.rb

@@ -0,0 +1,95 @@
+require 'jsonapi/serializable/relationship'
+
+module JSONAPI
+  module Serializable
+    class Resource
+      # Mixin to handle resource relationships.
+      module Relationships
+        def self.prepended(klass)
+          super
+          klass.class_eval do
+            extend DSL
+            class << self
+              attr_accessor :relationship_blocks
+            end
+            self.relationship_blocks = {}
+          end
+        end
+
+        def initialize(*)
+          super
+          @_relationships = self.class.relationship_blocks
+                                .each_with_object({}) do |(k, v), h|
+            h[k] = Relationship.new(@_exposures, &v)
+          end
+        end
+
+        # @see JSONAPI::Serializable::Resource#as_jsonapi
+        def as_jsonapi(fields: nil, include: [])
+          super.tap do |hash|
+            rels = requested_relationships(fields)
+                   .each_with_object({}) do |(k, v), h|
+              h[k] = v.as_jsonapi(include.include?(k))
+            end
+            hash[:relationships] = rels if rels.any?
+          end
+        end
+
+        # @api private
+        def requested_relationships(fields)
+          @_relationships
+            .select { |k, _| fields.nil? || fields.include?(k) }
+        end
+
+        # DSL methods for declaring relationships.
+        module DSL
+          def inherited(klass)
+            super
+            klass.relationship_blocks = relationship_blocks.dup
+          end
+
+          # Declare a relationship for this resource. The properties of the
+          #   relationship are set by providing a block in which the DSL methods
+          #   of +JSONAPI::Serializable::Relationship+ are called.
+          # @see JSONAPI::Serializable::Relationship
+          #
+          # @param [Symbol] name The key of the relationship.
+          #
+          # @example
+          #   relationship :posts do
+          #     resources { @user.posts.map { |p| PostResource.new(post: p) } }
+          #   end
+          #
+          # @example
+          #   relationship :author do
+          #     resources do
+          #       @post.author && UserResource.new(user: @post.author)
+          #     end
+          #     data do
+          #       { type: 'users', id: @post.author_id }
+          #     end
+          #     link(:self) do
+          #       "http://api.example.com/posts/#{@post.id}/relationships/author"
+          #     end
+          #     link(:related) do
+          #       "http://api.example.com/posts/#{@post.id}/author"
+          #     end
+          #     meta do
+          #       { author_online: @post.author.online? }
+          #     end
+          #   end
+          def relationship(name, options = {}, &block)
+            rel_block = proc do
+              data(options[:class]) { @object.public_send(name) }
+              instance_eval(&block) unless block.nil?
+            end
+            relationship_blocks[name.to_sym] = rel_block
+          end
+          alias has_many   relationship
+          alias has_one    relationship
+          alias belongs_to relationship
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/type.rb

@@ -0,0 +1,47 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      # Mixin to handle resource type.
+      module Type
+        def self.prepended(klass)
+          super
+          klass.class_eval do
+            extend DSL
+            class << self
+              attr_accessor :type_val
+            end
+          end
+        end
+
+        def initialize(*)
+          super
+          @_type = self.class.type_val || :unknown
+        end
+
+        # @see JSONAPI::Serializable::Resource#as_jsonapi
+        def as_jsonapi(*)
+          super.tap do |hash|
+            hash[:type] = @_type
+          end
+        end
+
+        # DSL methods for declaring the resource type.
+        module DSL
+          def inherited(klass)
+            super
+            klass.type_val = type_val
+          end
+
+          # Declare the JSON API type of this resource.
+          # @param [String] value The value of the type.
+          #
+          # @example
+          #   type 'users'
+          def type(value)
+            self.type_val = value.to_sym
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource.rb

@@ -1,12 +1,45 @@
-require 'jsonapi/serializable/abstract_resource'
-require 'jsonapi/serializable/resource_dsl'
+require 'jsonapi/serializable/resource/id'
+require 'jsonapi/serializable/resource/type'
+require 'jsonapi/serializable/resource/meta'
+require 'jsonapi/serializable/resource/links'
+require 'jsonapi/serializable/resource/attributes'
+require 'jsonapi/serializable/resource/relationships'
 
 module JSONAPI
   module Serializable
-    class Resource < AbstractResource
-      include ResourceDSL
+    class Resource
+      prepend Id
+      prepend Type
+      prepend Meta
+      prepend Links
+      prepend Attributes
+      prepend Relationships
 
+      # Default the value of id.
       id { @object.public_send(:id).to_s }
+
+      def initialize(exposures = {})
+        exposures.each { |k, v| instance_variable_set("@#{k}", v) }
+        @_exposures = exposures
+      end
+
+      def as_jsonapi(*)
+        {}
+      end
+
+      def jsonapi_type
+        @_type
+      end
+
+      def jsonapi_id
+        @_id
+      end
+
+      def jsonapi_related(include)
+        @_relationships
+          .select { |k, _| include.include?(k) }
+          .each_with_object({}) { |(k, v), h| h[k] = v.related_resources }
+      end
     end
   end
 end

data/lib/jsonapi/serializable/resource_builder.rb

@@ -37,10 +37,12 @@ module JSONAPI
 
       private
 
+      # @api private
       def serializable_params
         @expose.merge(object: @object)
       end
 
+      # @api private
       # rubocop:disable Metrics/MethodLength
       def serializable_class
         klass =
@@ -58,6 +60,7 @@ module JSONAPI
       end
       # rubocop:enable Metrics/MethodLength
 
+      # @api private
       def reify_class(klass)
         if klass.is_a?(Class)
           klass