jsonapi-serializable 0.1.3 → 0.2.1

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

@@ -0,0 +1,173 @@
+module JSONAPI
+  module Serializable
+    class Resource
+      module DSL
+        def self.extended(klass)
+          class << klass
+            attr_accessor :id_block, :type_val, :type_block, :attribute_blocks,
+                          :relationship_blocks, :relationship_options,
+                          :link_blocks, :meta_val, :meta_block
+          end
+
+          klass.attribute_blocks = {}
+          klass.relationship_blocks  = {}
+          klass.relationship_options = {}
+          klass.link_blocks = {}
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def inherited(klass)
+          klass.id_block   = id_block
+          klass.type_val   = type_val
+          klass.type_block = type_block
+          klass.attribute_blocks     = attribute_blocks.dup
+          klass.relationship_blocks  = relationship_blocks.dup
+          klass.relationship_options = relationship_options.dup
+          klass.link_blocks = link_blocks.dup
+          klass.meta_val    = meta_val
+          klass.meta_block  = meta_block
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # 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
+
+        # @overload type(value)
+        #   Declare the JSON API type of this resource.
+        #   @param [String] value The value of the type.
+        #
+        #   @example
+        #     type 'users'
+        #
+        # @overload type(&block)
+        #   Declare the JSON API type of this resource.
+        #   @yieldreturn [String] The value of the type.
+        #
+        #   @example
+        #     type { @object.type }
+        def type(value = nil, &block)
+          self.type_val   = value.to_sym if value
+          self.type_block = block
+        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
+
+        # 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
+
+        # @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
+
+        # 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.
+        # @param [Hash] options The options for 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 { @object.public_send(name) }
+            instance_eval(&block) unless block.nil?
+          end
+          relationship_blocks[name.to_sym]  = rel_block
+          relationship_options[name.to_sym] = options
+        end
+
+        alias has_many relationship
+        alias has_one relationship
+        alias belongs_to relationship
+      end
+    end
+  end
+end

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

@@ -4,10 +4,10 @@ module JSONAPI
       # Extension for handling automatic key formatting of
       #   attributes/relationships.
       #
-      # @usage
+      # @example
       #   class SerializableUser < JSONAPI::Serializable::Resource
-      #     prepend JSONAPI::Serializable::Resource::KeyFormat
-      #     self.key_format = proc { |key| key.camelize }
+      #     extend JSONAPI::Serializable::Resource::KeyFormat
+      #     key_format -> (key) { key.camelize }
       #
       #     attribute :user_name
       #     has_many :close_friends
@@ -15,42 +15,60 @@ module JSONAPI
       #   # => will modify the serialized keys to `UserName` and `CloseFriends`.
       module KeyFormat
         def self.prepended(klass)
+          warn <<-EOT
+  DERPRECATION WARNING (called from #{caller_locations(1...2).first}):
+  Prepending `#{name}' is deprecated and will be removed in future releases. Use `Object#extend' instead.
+  EOT
+
+          klass.extend self
+        end
+
+        def self.extended(klass)
           klass.class_eval do
-            extend DSL
             class << self
-              attr_accessor :key_format
+              attr_accessor :_key_formatter
             end
           end
         end
 
-        # DSL extensions for automatic key formatting.
-        module DSL
-          def inherited(klass)
-            super
-            klass.key_format = key_format
-          end
+        def inherited(klass)
+          super
+          klass._key_formatter = _key_formatter
+        end
 
-          # Handles automatic key formatting for attributes.
-          def attribute(name, options = {}, &block)
-            block ||= proc { @object.public_send(name) }
-            super(key_format.call(name), options, &block)
-          end
+        # Set the callable responsible for formatting keys, either directly, or
+        #   via a block.
+        #
+        # @example
+        #   key_format -> (key) { key.capitalize }
+        #
+        # @example
+        #   key_format { |key| key.capitalize }
+        #
+        def key_format(callable = nil, &block)
+          self._key_formatter = callable || block
+        end
 
-          # Handles automatic key formatting 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_format.call(name), options, &rel_block)
-          end
+        # Handles automatic key formatting for attributes.
+        def attribute(name, options = {}, &block)
+          block ||= proc { @object.public_send(name) }
+          super(_key_formatter.call(name), options, &block)
+        end
 
-          # NOTE(beauby): Re-aliasing those is necessary for the
-          #   overridden `#relationship` method to be called.
-          alias has_many   relationship
-          alias has_one    relationship
-          alias belongs_to relationship
+        # Handles automatic key formatting for relationships.
+        def relationship(name, options = {}, &block)
+          rel_block = proc do
+            data { @object.public_send(name) }
+            instance_eval(&block) unless block.nil?
+          end
+          super(_key_formatter.call(name), options, &rel_block)
         end
+
+        # NOTE(beauby): Re-aliasing those is necessary for the
+        #   overridden `#relationship` method to be called.
+        alias has_many   relationship
+        alias has_one    relationship
+        alias belongs_to relationship
       end
     end
   end

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

@@ -0,0 +1,62 @@
+require 'jsonapi/serializable/link'
+require 'jsonapi/serializable/resource/relationship/dsl'
+
+module JSONAPI
+  module Serializable
+    class Resource
+      class Relationship
+        include DSL
+
+        def initialize(exposures = {}, options = {}, &block)
+          exposures.each { |k, v| instance_variable_set("@#{k}", v) }
+          @_exposures = exposures
+          @_options   = options
+          @_links     = {}
+          instance_eval(&block)
+        end
+
+        def as_jsonapi(included)
+          {}.tap do |hash|
+            hash[:links] = @_links             if @_links.any?
+            hash[:data]  = linkage_data        if included || @_include_linkage
+            hash[:meta]  = @_meta              unless @_meta.nil?
+            hash[:meta]  = { included: false } if hash.empty?
+          end
+        end
+
+        # @api private
+        def related_resources
+          @_related_resources ||= Array(resources)
+        end
+
+        # @api private
+        def links
+          @_links
+        end
+
+        # @api private
+        def meta
+          @_meta
+        end
+
+        # @api private
+        def resources
+          @_resources ||= @_resources_block.call
+        end
+
+        private
+
+        # @api private
+        def linkage_data
+          return @_linkage_block.call if @_linkage_block
+
+          linkage_data = related_resources.map do |res|
+            { type: res.jsonapi_type, id: res.jsonapi_id }
+          end
+
+          resources.respond_to?(:each) ? linkage_data : linkage_data.first
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource/relationship/dsl.rb

@@ -0,0 +1,103 @@
+require 'jsonapi/serializable/resource_builder'
+
+module JSONAPI
+  module Serializable
+    class Resource
+      class Relationship
+        module DSL
+          # Declare the related resources for this relationship.
+          # @yieldreturn The related resources for this relationship.
+          #   If it is nil, an object implementing the Serializable::Resource
+          #   interface, an empty array, or an array of objects implementing the
+          #   Serializable::Resource interface, then it is used as is.
+          #   Otherwise an appropriate Serializable::Resource subclass is
+          #   inferred from the object(s)' namespace/class, the `class`
+          #   relationship option, and the @_resource_builder.
+          #
+          # @example
+          #   data do
+          #     @user.posts.map { |p| PostResource.new(post: p) }
+          #   end
+          #
+          # @example
+          #   data do
+          #     @post.author && UserResource.new(user: @user.author)
+          #   end
+          #
+          # @example
+          #   data do
+          #     @user.posts
+          #   end
+          # end
+          def data
+            # NOTE(beauby): Lazify computation since it is only needed when
+            #   the corresponding relationship is included.
+            @_resources_block = proc do
+              @_resource_builder.build(yield, @_exposures, @_options[:class])
+            end
+          end
+
+          # @overload linkage(options = {}, &block)
+          #   Explicitly declare linkage data.
+          #   @yieldreturn The resource linkage.
+          #
+          #   @example
+          #     linkage do
+          #       @object.posts.map { |p| { id: p.id.to_s, type: 'posts' } }
+          #     end
+          #
+          # @overload linkage(options = {})
+          #   Forces standard linkage even if relationship not included.
+          #
+          #   @example
+          #     linkage always: true
+          def linkage(always: false, &block)
+            @_include_linkage = always
+            @_linkage_block = block
+          end
+
+          # @overload meta(value)
+          #   Declare the meta information for this relationship.
+          #   @param [Hash] value The meta information hash.
+          #
+          #   @example
+          #     meta paginated: true
+          #
+          # @overload meta(&block)
+          #   Declare the meta information for this relationship.
+          #   @yieldreturn [Hash] The meta information hash.
+          #
+          #   @example
+          #     meta do
+          #       { paginated: true }
+          #     end
+          def meta(value = nil)
+            @_meta = value || yield
+          end
+
+          # Declare a link for this relationship. The properties of the link are set
+          #   by providing a block in which the DSL methods of
+          #   +JSONAPI::Serializable::Link+ are called.
+          # @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}/relationships/posts"
+          #   end
+          #
+          # @example
+          #    link(:related) do
+          #      href "http://api.example.com/users/#{@user.id}/posts"
+          #      meta authorization_needed: true
+          #    end
+          def link(name, &block)
+            @_links[name] = Link.as_jsonapi(@_exposures, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/resource_builder.rb

@@ -1,74 +1,54 @@
 module JSONAPI
   module Serializable
     class ResourceBuilder
-      DEFAULT_RESOURCE_INFERER = lambda do |object_klass_name|
-        names = object_klass_name.split('::'.freeze)
-        klass_name = names.pop
-        namespace = names.join('::'.freeze)
-
-        klass_name = [namespace, "Serializable#{klass_name}"]
-                     .reject(&:nil?)
-                     .reject(&:empty?)
-                     .join('::'.freeze)
+      # @api private
+      def initialize(inferrer = nil)
+        @inferrer = inferrer
+        @lookup_cache = {}
 
-        Object.const_get(klass_name)
+        freeze
       end
 
-      def self.build(objects, expose, klass)
+      # @api private
+      def build(objects, expose, klass = nil)
         return objects if objects.nil? ||
                           Array(objects).first.respond_to?(:as_jsonapi)
 
         if objects.respond_to?(:to_ary)
-          Array(objects).map { |obj| new(obj, expose, klass).resource }
+          Array(objects).map { |obj| _build(obj, expose, klass) }
         else
-          new(objects, expose, klass).resource
+          _build(objects, expose, klass)
         end
       end
 
-      attr_reader :resource
-
-      def initialize(object, expose, klass)
-        @object   = object
-        @expose   = expose || {}
-        @klass    = klass
-        @resource = serializable_class.new(serializable_params)
-        freeze
-      end
-
       private
 
       # @api private
-      def serializable_params
-        @expose.merge(object: @object)
+      def _build(object, expose, klass)
+        serializable_class(object.class.name, klass)
+          .new(expose.merge(object: object))
       end
 
       # @api private
-      # rubocop:disable Metrics/MethodLength
-      def serializable_class
-        klass =
-          if @klass.respond_to?(:call)
-            @klass.call(@object.class.name)
-          elsif @klass.is_a?(Hash)
-            @klass[@object.class.name.to_sym]
-          elsif @klass.nil?
-            DEFAULT_RESOURCE_INFERER.call(@object.class.name)
-          else
-            @klass
-          end
+      def serializable_class(object_class_name, klass)
+        klass = klass[object_class_name.to_sym] if klass.is_a?(Hash)
 
-        reify_class(klass)
+        @lookup_cache[[object_class_name, klass.to_s]] ||=
+          reify_class(klass || @inferrer.call(object_class_name))
       end
-      # rubocop:enable Metrics/MethodLength
 
       # @api private
       def reify_class(klass)
         if klass.is_a?(Class)
           klass
-        elsif klass.is_a?(String)
-          Object.const_get(klass)
+        elsif klass.is_a?(String) || klass.is_a?(Symbol)
+          begin
+            Object.const_get(klass)
+          rescue NameError
+            raise NameError, "Undefined serializable class #{klass}"
+          end
         else
-          # TODO(beauby): Raise meaningful exception.
-          raise
+          raise ArgumentError, "Invalid serializable class #{klass}"
         end
       end
     end