yaks 0.4.2 → 0.4.3

data/lib/yaks/default_policy.rb

@@ -2,17 +2,29 @@ module Yaks
   class DefaultPolicy
     include Util
 
+    # Default policy options.
     DEFAULTS = {
-      rel_template: "rel:src={src}&dest={dest}",
+      rel_template: "rel:{rel}",
       namespace: Kernel
     }
 
+    # @!attribute [r] options
+    #   @return [Hash]
     attr_reader :options
 
+    # @param [Hash] options
+    # @return [Yaks::DefaultPolicy]
     def initialize(options = {})
       @options = DEFAULTS.merge(options)
     end
 
+    # @param [Object] model
+    # @return [Yaks::CollectionMapper, Yaks::Mapper]
+    #   or a subclass of Yaks::Mapper of some sort.
+    #
+    # @raise [NameError] only occurs when the model
+    #   is anything but a collection.
+    #
     def derive_mapper_from_object(model)
       if model.respond_to? :to_ary
         if m = model.first
@@ -26,30 +38,36 @@ module Yaks
           return @options[:namespace].const_get(:CollectionMapper)
         rescue NameError
         end
-        Yaks::CollectionMapper
+        CollectionMapper
       else
         name = model.class.name.split('::').last
         @options[:namespace].const_get(name + 'Mapper')
       end
     end
 
+    # @param [Class] mapper_class
+    # @return [String]
     def derive_type_from_mapper_class(mapper_class)
       underscore(mapper_class.name.split('::').last.sub(/Mapper$/, ''))
     end
 
+    # @param [Yaks::Mapper::Association] association
+    # @return [Class] of subclass Yaks::Mapper
+    # @raise [NameError]
     def derive_mapper_from_association(association)
       @options[:namespace].const_get("#{camelize(association.singular_name)}Mapper")
     end
 
-    def derive_rel_from_association(mapper, association)
-      expand_rel( derive_type_from_mapper_class(mapper.class), association.name )
+    # @param [Yaks::Mapper::Association] association
+    # @return [String]
+    def derive_rel_from_association(association)
+      expand_rel( association.name )
     end
 
-    def expand_rel(src_name, dest_name)
-      URITemplate.new(@options[:rel_template]).expand(
-        src: src_name,
-        dest: dest_name
-      )
+    # @param [String] relname
+    # @return [String]
+    def expand_rel(relname)
+      URITemplate.new(@options[:rel_template]).expand(rel: relname)
     end
   end
 end

data/lib/yaks/{serializer → format}/collection_json.rb

@@ -1,10 +1,12 @@
 module Yaks
-  class Serializer
+  class Format
     class CollectionJson < self
-      Serializer.register self, :collection_json, 'application/vnd.collection+json'
+      Format.register self, :collection_json, 'application/vnd.collection+json'
 
       include FP
 
+      # @param [Yaks:Resource] resource
+      # @return [Hash]
       def serialize_resource(resource)
         result = {
           version: "1.0",
@@ -14,6 +16,8 @@ module Yaks
         {collection: result}
       end
 
+      # @param [Yaks::Resource] resource
+      # @return [Array]
       def serialize_items(resource)
         resource.map do |item|
           attrs = item.attributes.map do |name, value|
@@ -26,7 +30,7 @@ module Yaks
           result[:href] = item.self_link.uri if item.self_link
           item.links.each do |link|
             next if link.rel == :self
-            result[:links] ||= []
+            result[:links] = [] unless result.key?(:links)
             result[:links] << {rel: link.rel, href: link.uri}
             result[:links].last[:name] = link.name if link.name
           end

data/lib/yaks/{serializer → format}/hal.rb

@@ -1,12 +1,14 @@
 # -*- coding: utf-8 -*-
 
 module Yaks
-  class Serializer
+  class Format
     class Hal < self
-      Serializer.register self, :hal, 'application/hal+json'
+      Format.register self, :hal, 'application/hal+json'
 
       protected
 
+      # @param [Yaks::Resource] resource
+      # @return [Hash]
       def serialize_resource(resource)
         # The HAL spec doesn't say explicitly how to deal missing values,
         # looking at client behavior (Hyperagent) it seems safer to return an empty
@@ -19,14 +21,18 @@ module Yaks
         result
       end
 
+      # @param [Array] links
+      # @return [Hash]
       def serialize_links(links)
         links.reduce({}, &method(:serialize_link))
       end
 
+      # @param [Hash] memo
+      # @param [Yaks::Resource::Link]
+      # @return [Hash]
       def serialize_link(memo, link)
         hal_link = {href: link.uri}
-        hal_link.merge!(link.options.reject{|k,_| k==:templated})
-        hal_link.merge!(templated: true) if link.templated?
+        hal_link.merge!(link.options)
 
         memo[link.rel] = if singular?(link.rel)
                            hal_link
@@ -36,10 +42,14 @@ module Yaks
         memo
       end
 
+      # @param [String] rel
+      # @return [Boolean]
       def singular?(rel)
         !options.fetch(:plural_links) { [] }.include?(rel)
       end
 
+      # @param [Array] subresources
+      # @return [Hash]
       def serialize_embedded(subresources)
         subresources.each_with_object({}) do |(rel, resources), memo|
           memo[rel] = if resources.collection?

data/lib/yaks/{serializer → format}/json_api.rb

@@ -1,12 +1,14 @@
 # -*- coding: utf-8 -*-
 
 module Yaks
-  class Serializer
+  class Format
     class JsonApi < self
-      Serializer.register self, :json_api, 'application/vnd.api+json'
+      Format.register self, :json_api, 'application/vnd.api+json'
 
       include FP
 
+      # @param [Yaks::Resource] resource
+      # @return [Hash]
       def call(resource)
         main_collection = resource.map(&method(:serialize_resource))
 
@@ -18,6 +20,8 @@ module Yaks
         end
       end
 
+      # @param [Yaks::Resource] resource
+      # @return [Hash]
       def serialize_resource(resource)
         result = resource.attributes
 
@@ -32,24 +36,34 @@ module Yaks
         result
       end
 
+      # @param [Yaks::Resource] subresource
+      # @return [Hash]
       def serialize_links(subresources)
-        subresources.each_with_object({}) do |(name, resource), hsh|
+        subresources.each_with_object({}) do |(_name, resource), hsh|
           next if resource.is_a? NullResource
           key = resource.collection? ? pluralize(resource.type) : resource.type
           hsh[key] = serialize_link(resource)
         end
       end
 
+      # @param [Yaks::Resource] resource
+      # @return [Array, String]
       def serialize_link(resource)
         resource.collection? ? resource.map(&send_with_args(:[], :id)) : resource[:id]
       end
 
+      # @param [Hash] subresources
+      # @param [Hash] hsh
+      # @return [Hash]
       def serialize_linked_subresources(subresources, hsh)
-        subresources.each_with_object(hsh) do |(name, resources), hsh|
+        subresources.values.each do |resources|
           serialize_linked_resources(resources, hsh)
         end
       end
 
+      # @param [Array] resources
+      # @param [Hash] linked
+      # @return [Hash]
       def serialize_linked_resources(resources, linked)
         resources.each_with_object(linked) do |resource, memo|
           serialize_subresource(resource, memo)
@@ -57,6 +71,10 @@ module Yaks
       end
 
       # {shows => [{id: 3, name: 'foo'}]}
+      #
+      # @param [Yaks::Resource] resource
+      # @param [Hash] linked
+      # @return [Hash]
       def serialize_subresource(resource, linked)
         key = pluralize(resource.type)
         set = linked.fetch(key) { Set.new }

data/lib/yaks/{serializer.rb → format.rb}

@@ -1,5 +1,5 @@
 module Yaks
-  class Serializer
+  class Format
     extend Forwardable
     include Util
 
@@ -9,7 +9,7 @@ module Yaks
     protected :links, :attributes, :subresources, :options
 
     def initialize(options = {})
-      @options  = YAKS_DEFAULT_OPTIONS.merge(options)
+      @options = options
     end
 
     def call(resource)
@@ -19,15 +19,15 @@ module Yaks
 
     class << self
       def register(klass, name, mime_type)
-        @serializers ||= {}
-        @serializers[name] = klass
+        @formats ||= {}
+        @formats[name] = klass
 
         @mime_types  ||= {}
         @mime_types[mime_type] = [name, klass]
       end
 
       def by_name(name)
-        @serializers.fetch(name)
+        @formats.fetch(name)
       end
 
       def by_mime_type(mime_type)

data/lib/yaks/fp/hash_updatable.rb

@@ -0,0 +1,17 @@
+module Yaks
+  module FP
+
+    class HashUpdatable < Module
+      def initialize(*attributes)
+        define_method :update do |updates|
+          self.class.new(
+            attributes.each_with_object({}) {|attr, hsh|
+              hsh[attr] = updates.fetch(attr) { send(attr) }
+            }
+          )
+        end
+      end
+    end
+
+  end
+end

data/lib/yaks/fp/updatable.rb

@@ -0,0 +1,15 @@
+module Yaks
+  module FP
+
+    class Updatable < Module
+      def initialize(*attributes)
+        define_method :update do |updates|
+          self.class.new(
+            *attributes.map {|attr| updates.fetch(attr) { send(attr) }}
+          )
+        end
+      end
+    end
+
+  end
+end

data/lib/yaks/mapper/association.rb

@@ -1,38 +1,41 @@
 module Yaks
   class Mapper
     class Association
-      include Equalizer.new(:name, :mapper, :rel)
+      include Equalizer.new(:name, :child_mapper, :rel, :href, :link_if)
+      include Util
 
-      attr_reader :name, :mapper, :rel, :collection_mapper
+      attr_reader :name, :child_mapper, :rel, :href, :link_if
 
-      def initialize(name, mapper, rel, collection_mapper)
-        @name, @mapper, @rel, @collection_mapper =
-          name, mapper, rel, collection_mapper
+      def initialize(options)
+        @name          = options.fetch(:name)
+        @child_mapper  = options.fetch(:mapper, Undefined)
+        @rel           = options.fetch(:rel, Undefined)
+
+        @href          = options.fetch(:href, Undefined)
+        @link_if       = options.fetch(:link_if, Undefined)
       end
 
-      # @param [#call] lookup
-      #   A callable that can retrieve an association by its name
-      # @return Array[rel, resource]
-      #   Returns the rel (registered type or URI) + the associated, mapped resource
-      def create_subresource(parent_mapper, lookup, context)
-        [
-          map_rel(parent_mapper, context.fetch(:policy)),
-          map_resource(lookup[name], context)
-        ]
+      def add_to_resource(resource, parent_mapper, context)
+        AssociationMapper.new(parent_mapper, self, context).call(resource)
       end
 
-      def map_rel(parent_mapper, policy)
-        return @rel unless @rel.equal?(Undefined)
-        policy.derive_rel_from_association(parent_mapper, self)
+      def render_as_link?(parent_mapper)
+        href != Undefined && link_if != Undefined && Resolve(link_if, parent_mapper)
       end
 
-      def association_mapper(policy)
-        return @mapper unless @mapper.equal?(Undefined)
-        policy.derive_mapper_from_association(self)
+      def map_rel(policy)
+        return rel unless rel.equal?(Undefined)
+        policy.derive_rel_from_association(self)
       end
 
       # @abstract
-      def map_resource(object, context)
+      def map_resource(_object, _context)
+      end
+
+      # support for HasOne and HasMany
+      def resolve_association_mapper(policy)
+        return child_mapper unless child_mapper.equal?(Undefined)
+        policy.derive_mapper_from_association(self)
       end
 
     end

data/lib/yaks/mapper/association_mapper.rb

@@ -0,0 +1,42 @@
+module Yaks
+  class Mapper
+    class AssociationMapper
+      attr_reader :parent_mapper, :context, :rel, :association
+
+      def initialize(parent_mapper, association, context)
+        @parent_mapper = parent_mapper
+        @association   = association
+        @context       = context.merge(
+          mapper_stack: context[:mapper_stack] + [parent_mapper]
+        )
+        @rel           = association.map_rel(policy)
+      end
+
+      def policy
+        context.fetch(:policy)
+      end
+
+      def call(resource)
+        if association.render_as_link?(parent_mapper)
+          add_link(resource)
+        else
+          add_subresource(resource)
+        end
+      end
+
+      def add_link(resource)
+        Link.new(rel, association.href, {})
+          .add_to_resource(resource, parent_mapper, nil)
+        # Yaks::Mapper::Link doesn't do anything with the context, making it
+        # hard to test that we pass it a context. Passing nil for now, until
+        # this is actually needed and can be tested.
+      end
+
+      def add_subresource(resource)
+        object      = parent_mapper.load_association(association.name)
+        subresource = association.map_resource(object, context)
+        resource.add_subresource(rel, subresource)
+      end
+    end
+  end
+end

data/lib/yaks/mapper/attribute.rb

@@ -0,0 +1,17 @@
+module Yaks
+  class Mapper
+    class Attribute
+      include Equalizer.new(:name)
+
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def add_to_resource(resource, mapper, _context)
+        resource.update_attributes(name => mapper.load_attribute(name))
+      end
+    end
+  end
+end

data/lib/yaks/mapper/class_methods.rb

@@ -12,7 +12,6 @@ module Yaks
         :attributes,
         :link,
         :profile,
-        # :embed,
         :has_one,
         :has_many
       ]

data/lib/yaks/mapper/config.rb

@@ -2,6 +2,7 @@ module Yaks
   class Mapper
     class Config
       include Equalizer.new(:type, :attributes, :links, :associations)
+      include FP::Updatable.new(:type, :attributes, :links, :associations)
 
       attr_reader :links, :associations
 
@@ -12,31 +13,22 @@ module Yaks
         @associations = associations
       end
 
-      def updated(updates)
-        self.class.new(
-          updates.fetch(:type)         { type         },
-          updates.fetch(:attributes)   { attributes   },
-          updates.fetch(:links)        { links        },
-          updates.fetch(:associations) { associations }
-        )
-      end
-
       def type(type = Undefined)
         return @type if type.equal?(Undefined)
-        updated(type: type)
+        update(type: type)
       end
 
       def attributes(*attrs)
         return @attributes if attrs.empty?
-        updated(
-          attributes: @attributes + attrs
-        )
+        update(attributes: @attributes + attrs.map(&Attribute.method(:new)))
       end
 
       def link(rel, template, options = {})
-        updated(
-          links: @links + [Link.new(rel, template, options)]
-        )
+        update(links: @links + [Link.new(rel, template, options)])
+      end
+
+      def add_association(type, name, options)
+        update(associations: @associations + [type.new(options.merge(name: name))])
       end
 
       def has_one(name, options = {})
@@ -47,18 +39,6 @@ module Yaks
         add_association(HasMany, name, options)
       end
 
-      def add_association(type, name, options)
-        updated(
-          associations: @associations + [
-            type.new(
-              name,
-              options.fetch(:mapper)            { Undefined },
-              options.fetch(:rel)               { Undefined },
-              options.fetch(:collection_mapper) { Undefined },
-            )
-          ]
-        )
-      end
     end
   end
 end

data/lib/yaks/mapper/has_many.rb

@@ -3,11 +3,16 @@ module Yaks
     class HasMany < Association
       include Util
 
+      def initialize(options)
+        super
+        @collection_mapper = options.fetch(:collection_mapper, Undefined)
+      end
+
       def map_resource(collection, context)
         return NullResource.new(collection: true) if collection.nil?
-        policy        = context.fetch(:policy)
-        member_mapper = association_mapper(policy)
-        context       = context.merge(member_mapper: member_mapper)
+        policy      = context.fetch(:policy)
+        item_mapper = resolve_association_mapper(policy)
+        context     = context.merge(item_mapper: item_mapper)
         collection_mapper(collection, policy).new(context).call(collection)
       end
 

data/lib/yaks/mapper/has_one.rb

@@ -2,7 +2,7 @@ module Yaks
   class Mapper
     class HasOne < Association
       def map_resource(object, context)
-        association_mapper(context.fetch(:policy))
+        resolve_association_mapper(context.fetch(:policy))
           .new(context)
           .call(object)
       end

data/lib/yaks/mapper/link.rb

@@ -30,8 +30,10 @@ module Yaks
 
       def_delegators :uri_template, :expand_partial
 
-      def initialize(rel, template, options)
-        @rel, @template, @options = rel, template, options
+      def add_to_resource(resource, mapper, _context)
+        resource_link = map_to_resource_link(mapper)
+        return resource unless resource_link
+        resource.add_link(resource_link)
       end
 
       def rel?(rel)
@@ -43,13 +45,15 @@ module Yaks
         !options.fetch(:expand) { true }.equal? true
       end
 
-      # Does this link need expansion, full or partially
-      def expand?
-        options.fetch(:expand) { true }
-      end
-
       def template_variables
-        options.fetch(:expand) { uri_template.variables }.map(&:to_sym)
+        case options.fetch(:expand) { true }
+        when true
+          uri_template.variables
+        when false
+          []
+        else
+          options[:expand]
+        end.map(&:to_sym)
       end
 
       def expansion_mapping(lookup)
@@ -72,11 +76,7 @@ module Yaks
       def expand_with(lookup)
         return lookup[template] if template.is_a? Symbol
 
-        if expand?
-          expand_partial(expansion_mapping(lookup)).to_s
-        else
-          template
-        end
+        expand_partial(expansion_mapping(lookup)).to_s
       end
 
       def resource_link_options(mapper)

data/lib/yaks/mapper.rb

@@ -26,39 +26,24 @@ module Yaks
       context.fetch(:mapper_stack)
     end
 
-    def call(object)
-      @object = object
-
-      return NullResource.new if object.nil?
-
-      Resource.new(
-        type:         mapper_name,
-        attributes:   map_attributes,
-        links:        map_links,
-        subresources: map_subresources
-      )
+    def self.mapper_name(policy)
+      config.type || policy.derive_type_from_mapper_class(self)
     end
 
-    def map_attributes
-      filter(attributes).each_with_object({}) do |attr, memo|
-        memo[attr] = load_attribute(attr)
-      end
+    def mapper_name
+      self.class.mapper_name(policy)
     end
 
-    def map_links
-      links.map(&send_with_args(:map_to_resource_link, self)).compact
-    end
+    def call(object)
+      @object = object
+
+      return NullResource.new if object.nil?
 
-    def map_subresources
-      attributes   = filter(associations.map(&:name))
-      associations = associations().select{|assoc| attributes.include? assoc.name }
-      associations.each_with_object({}) do |association, memo|
-        rel, subresource = association.create_subresource(
-          self,
-          method(:load_association),
-          context.merge(mapper_stack: mapper_stack + [self])
-        )
-        memo[rel] = subresource
+      [ :map_attributes,
+        :map_links,
+        :map_subresources
+      ].inject(Resource.new(type: mapper_name)) do |resource, method|
+        send(method, resource)
       end
     end
 
@@ -67,13 +52,24 @@ module Yaks
     end
     alias load_association load_attribute
 
-    def filter(attrs)
-      attrs
+    private
+
+    def map_attributes(resource)
+      attributes.inject(resource) do |resource, attribute|
+        attribute.add_to_resource(resource, self, context)
+      end
     end
 
-    def mapper_name
-      config.type || policy.derive_type_from_mapper_class(self.class)
+    def map_links(resource)
+      links.inject(resource) do |resource, mapper_link|
+        mapper_link.add_to_resource(resource, self, context)
+      end
     end
 
+    def map_subresources(resource)
+      associations.inject(resource) do |resource, association|
+        association.add_to_resource( resource, self, context)
+      end
+    end
   end
 end

data/lib/yaks/null_resource.rb

@@ -1,5 +1,6 @@
 module Yaks
   class NullResource
+    include Equalizer.new(:collection?)
     include Enumerable
 
     def initialize(opts = {})