yaks 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b888259337e9fa643458e613fda2f50e561a72e
-  data.tar.gz: e6ff86a9a5d402b857041f1a676b81f6324078d7
+  metadata.gz: f8ee4f04ef31bd3c1e944ee723c910bf37dd97b8
+  data.tar.gz: 93282ee4d7a30bdb826ccc81447d86db1de245f0
 SHA512:
-  metadata.gz: edfa665288d44ed62d397beeb2419092b7220129475c77f5cbce4413a981f1d57f44578faf27e3a77da3c6a818a3b5bc0f5bbeaeaa966aeab82d55f6b1960694
-  data.tar.gz: 7391bc4fab6497ce52c6353db032786df91ab01730cd8486aed53179321ebd3c9baf49a54509edbcddd14796b1daefecc98903b0bfd8b9fe94753cb4fe2f1490
+  metadata.gz: d09019c49799077e500badde0c259fa41d06f2fdbfe3ec3c7c7cf71625ce786d2eb682b2b449edc8a683b8a24a20234cd3ea16716697154a58fcd88c6a6773a9
+  data.tar.gz: b0107900f0d00a2b30ab7d6cd701b84a59e3155961a653847b863d5cc0a569c0ff24640769b78826afad31fa6b5667cf3cf294961de82f3b1c6fbd8301f8c460

data/.gitignore

@@ -2,3 +2,4 @@ pkg
 .bundle
 coverage
 Gemfile.lock
+*~

data/CHANGELOG.md

@@ -1,6 +1,66 @@
 ### Development
 [full changelog](http://github.com/plexus/yaks/compare/v0.4.2...master)
 
+* when specifying a rel_template, instead of allowing for {src} and {dest} fields, now a single {rel} field is expected, which corresponds more with typical usage.
+
+```ruby
+Yaks.new do
+  rel_template 'http://my-api/docs/relationships/{rel}'
+end
+```
+
+* Yaks::Serializer has been renamed to Yaks::Format
+
+* Yaks::Mapper#{map_attributes,map_links,map_subresource} signature has changed, they now are responsible for adding themselves to a resource instance.
+
+```ruby
+class FooMapper < Yaks::Mapper
+  def map_attributes(resource)
+    resource.update_attributes(:example => 'attribute')
+  end
+end
+```
+
+* Conditionally turn associations into links
+
+```ruby
+class ShowMapper < Yaks::Mapper
+  has_many :events, href: '/show/{id}/events', link_if: ->{ events.count > 50 }
+end
+```
+
+* Reify `Yaks::Mapper::Attribute`
+
+* Remove `Yaks::Mapper#filter`, instead override `#attributes` or `#associations` to filter things out, for example:
+
+```ruby
+class SongMapper
+  attributes :title, :duration, :lyrics
+  has_one :artist
+  has_one :album
+
+  def minimal?
+    env['HTTP_PREFER'] =~ /minimal/
+  end
+
+  def attributes
+    if minimal?
+      super.reject {|attr| attr.name.equal? :lyrics } # These are instances of Yaks::Mapper::Attribute
+    else
+      super
+    end
+  end
+
+  def associations
+    return [] if minimal?
+    super
+  end
+end
+```
+
+* Give Attribute, Link, Association a common interface : `add_to_resource(resource, mapper, context)`
+* Add persistent update methods to `Yaks::Resource`
+
 ### v0.4.2
 
 * JSON-API: render self links as href attributes
@@ -10,13 +70,13 @@
 * Make Yaks::CollectionMapper#collection overridable for pagination
 * Don't render links from custom link methods (link :foo, :method_that_generates_url) that return nil
 
-# v0.4.1
+### v0.4.1
 
 * Change how env is passed to yaks.serialize to match docs
 * Fix JSON-API bug (#18 reported by Nicolas Blanco)
 * Don't pluralize has_one association names in JSON-API
 
-# v0.4.0
+## v0.4.0
 
 * Introduce after {} post-processing hook
 * Streamline interfaces and variable names, especially the use of `call`
@@ -25,7 +85,7 @@
 * Switch back to using `src` and `dest` as the rel-template keys, instead of `association_name`
 * deprecate `mapper_namespace` in favor of `namespace`
 
-# v0.4.0.rc1
+### v0.4.0.rc1
 
 * Introduce Yaks.new as the main public interface
 * Fix JsonApiSerializer and make it compliant with current spec
@@ -36,10 +96,10 @@
 * Honor the HTTP Accept header if it is present in the rack env
 * Add map_to_primitive configuration option
 
-# v0.3.0
+## v0.3.0
 
 * Allow partial expansion of templates, expand certain fields, leave others as URI template in the result.
 
-# v0.2.0
+## v0.2.0
 
 * links can now take a simple for a template to compute a link just like an attribute

data/README.md

@@ -62,7 +62,7 @@ or a bit more elaborate
 ```ruby
 yaks = Yaks.new do
   default_format :json_api
-  rel_template 'http://api.example.com/rels/{dest}'
+  rel_template 'http://api.example.com/rels/{rel}'
   format_options(:hal, plural_links: [:copyright])
 end
 
@@ -100,11 +100,30 @@ end
 
 #### Filtering
 
-Implement `filter(attrs)` to filter out specific attributes, e.g. based on options.
+Implementing a `#filter` method in your mappers is no longer supported. Instead you can override `#attributes`, or `#associations`.
 
 ```ruby
-def filter(attrs)
-  attrs.reject{|attr| options[:exclude].include? attr }
+class SongMapper
+  attributes :title, :duration, :lyrics
+
+  has_one :artist
+  has_one :album
+
+  def minimal?
+    env['HTTP_PREFER'] =~ /minimal/
+  end
+
+  # @return Array<Yaks::Mapper::Attribute>
+  def attributes
+    return super.reject {|attr| attr.name.equal? :lyrics } if minimal?
+    super
+  end
+
+  # @return Array<Yaks::Mapper::Association>
+  def associations
+    return [] if minimal?
+    super
+  end
 end
 ```
 
@@ -159,6 +178,13 @@ Options
 * `:mapper` : Use a specific for each instance, will be derived from the class name if omitted (see Policy vs Configuration)
 * `:collection_mapper` : For mapping the collection as a whole, this defaults to Yaks::CollectionMapper, but you can subclass it for example to add links or attributes on the collection itself
 * `:rel` : Set the relation (symbol or URI) this association has with the object. Will be derived from the association name and the configured rel_template if ommitted
+* `:link_if`: Conditionally render the association as a link. A `:href` option is required
+
+```ruby
+class ShowMapper < Yaks::Mapper
+  has_many :events, href: '/show/{id}/events', link_if: ->{ events.count > 50 }
+end
+```
 
 ## Namespace
 
@@ -236,13 +262,13 @@ If `env` contains a `HTTP_ACCEPT` key (Rack's way of representing the `Accept` h
 
 ## Custom attribute/link/subresource handling
 
-When inheriting from `Yaks::Mapper`, you can override `map_attributes`, `map_links` and `map_resources` to skip (or augment) above methods, and instead implement your own custom mechanism. For example
+When inheriting from `Yaks::Mapper`, you can override `map_attributes`, `map_links` and `map_resources` to skip (or augment) above methods, and instead implement your own custom mechanism. These methods take a `Yaks::Resource` instance, and should return an updated resource. They should not alter the resource instance in-place. For example
 
 ```ruby
 class ErrorMapper < Yaks::Mapper
   link :profile, '/api/error'
 
-  def map_attributes
+  def map_attributes(resource)
     attrs = {
       http_code: 500,
       message: object.to_s,
@@ -257,7 +283,7 @@ class ErrorMapper < Yaks::Mapper
       attrs[:type] = "record_not_found"
     end
 
-    attrs
+    resource.update_attributes(attrs)
   end
 end
 ```
@@ -400,6 +426,10 @@ Yaks is used in production by [Ticketsolve](http://www.ticketsolve.com/). You ca
 
 Get in touch if you like to see your name and API here.
 
+## Demo
+
+You can find an example app at [Yakports](https://github.com/plexus/yakports), or browse the HAL api directly using the [HAL browser](http://yaks-airports.herokuapp.com/browser.html).
+
 ## Acknowledgment
 
 The mapper syntax is largely borrowed from ActiveModel::Serializers, which in turn closely mimics the syntax of ActiveRecord models. It's a great concise syntax that still offers plenty of flexibility, so to not reinvent the wheel I've stuck to the existing syntax as far as practical, although there are several extensions and deviations.
@@ -416,7 +446,7 @@ If this approach sounds appealing, have a look at [microrb.com](http://microrb.c
 
 ## How to contribute
 
-Run the tests, the examples, try it with your own stuff and leave your impressions in the issues. Or discuss on API-craft.
+Run the tests, the examples, try it with your own stuff and leave your impressions in the issues. Or discuss on [API-craft](https://groups.google.com/d/forum/api-craft).
 
 To fix a bug
 

data/Rakefile

@@ -1,4 +1,5 @@
 require 'rubygems/package_task'
+require 'yaks'
 
 spec = Gem::Specification.load(Pathname.glob('*.gemspec').first.to_s)
 Gem::PackageTask.new(spec).define
@@ -19,3 +20,35 @@ task :mutant do
   result  = Mutant::CLI.run(%w[-Ilib -ryaks --use rspec --score 100] + opts + [pattern])
   fail unless result == Mutant::CLI::EXIT_SUCCESS
 end
+
+task :mutant_chunked do
+  [
+    # Yaks::Util,
+    # Yaks::Primitivize,
+    Yaks::FP,
+    Yaks::Resource,
+    Yaks::NullResource,
+    Yaks::CollectionResource,
+    Yaks::Mapper::Association,
+    Yaks::Mapper::AssociationMapper,
+    Yaks::Mapper::HasMany,
+    Yaks::Mapper::HasOne,
+    Yaks::Mapper::Config,
+    Yaks::Mapper::ClassMethods,
+    Yaks::Mapper::Attribute,
+    Yaks::Format,
+    Yaks::Config::DSL,
+    Yaks::CollectionMapper,
+    Yaks::Mapper::Link,
+    Yaks::Format::JsonApi,
+    Yaks::DefaultPolicy,          # 45/249 (81.93%)
+    Yaks::Format::CollectionJson, # 15/183 (91.80%)
+    Yaks::Format::Hal,            # 17/209 (91.87%)
+    Yaks::Mapper,                 # 12/203 (94.09%)
+    Yaks::Config,                 # 12/263 (95.44%)
+  ].each do |space|
+    puts space
+    ENV['PATTERN'] = "#{space}"
+    Rake::Task["mutant"].execute
+  end
+end

data/lib/yaks/breaking_changes.rb

@@ -0,0 +1,22 @@
+module Yaks
+
+BreakingChanges = {
+'0.4.3' => %q~
+
+Breaking Changes in Yaks 0.4.3
+==============================
+
+Yaks::Mapper#filter was removed, if you override this method in your
+mappers to conditionally filter attributes or associations, you will
+have to override #attributes or #associations instead.
+
+When specifying a rel_template, now a single {rel} placeholder is
+expected instead of {src} and {dest}.
+
+There are other internal changes. See the CHANGELOG and README for full
+documentation.
+
+~
+}
+
+end

data/lib/yaks/collection_mapper.rb

@@ -4,48 +4,45 @@ module Yaks
   class CollectionMapper < Mapper
     alias collection object
 
-    def initialize(context)
-      super(context)
-    end
-
-    def member_mapper
-      context.fetch(:member_mapper) do
-        if collection.first
-          mapper_for_model(collection.first)
-        end
-      end
-    end
-
+    # @param [Array] collection
+    # @return [Array]
     def call(collection)
       @object = collection
 
       attrs = {
         type: collection_type,
-        links: map_links,
-        attributes: map_attributes,
         members: collection().map do |obj|
           mapper_for_model(obj).new(context).call(obj)
         end
       }
 
-      attrs[ :members_rel ] = members_rel if members_rel
+      attrs[ :collection_rel ] = collection_rel
 
-      CollectionResource.new(attrs)
+      map_attributes(
+        map_links(
+          CollectionResource.new(attrs)
+        )
+      )
     end
 
     private
 
-    def members_rel
-      policy.expand_rel( 'collection', pluralize( collection_type ) ) if collection_type
+    def collection_rel
+      if collection_type
+        policy.expand_rel( pluralize( collection_type ) )
+      else
+        'collection'
+      end
     end
 
     def collection_type
-      return unless member_mapper
-      member_mapper.config.type || policy.derive_type_from_mapper_class(member_mapper)
+      if item_mapper = context[:item_mapper]
+        item_mapper.config.type || policy.derive_type_from_mapper_class(item_mapper)
+      end
     end
 
     def mapper_for_model(model)
-      context.fetch(:member_mapper) do
+      context.fetch(:item_mapper) do
         policy.derive_mapper_from_object(model)
       end
     end

data/lib/yaks/collection_resource.rb

@@ -15,19 +15,30 @@ module Yaks
   # In the second case a collection has a single "subresource", being its
   # members.
   class CollectionResource < Resource
-    include Equalizer.new(:type, :links, :attributes, :members, :members_rel)
+    include Equalizer.new(:type, :links, :attributes, :members, :collection_rel)
+    include FP::HashUpdatable.new(:type, :links, :attributes, :members, :collection_rel)
     include Enumerable
 
     extend Forwardable
 
-    attr_reader :type, :links, :members, :members_rel
+    # @!attribute [r] type
+    #   @return [String]
+    # @!attribute [r] links
+    #   @return [Array]
+    # @!attribute [r] members
+    #   @return [Array]
+    # @!attribute [r] collection_rel
+    #   @return [String]
+    attr_reader :type, :links, :members, :collection_rel
 
     def_delegators :members, :each
 
+    # @param [Hash] options
+    # @return [CollectionResource]
     def initialize(options)
       super
       @members     = options.fetch(:members, [])
-      @members_rel = options.fetch(:members_rel, 'members')
+      @collection_rel = options.fetch(:collection_rel, 'members')
     end
 
     # Make a CollectionResource quack like a resource.
@@ -37,20 +48,23 @@ module Yaks
     # whatever it gets as a single resource with links and subresources,
     # we just push the collection down one level.
     #
-    # Once inside subresources the HAL serializer does check if a resource
+    # Once inside subresources the HAL format does check if a resource
     # is a collection, since there it does make a distinction, and because
     # in that case it will iterate with each/map rather than calling subresources,
     # this doesn't cause infinite recursion. Not very pretty, needs looking at.
     #
     # :(
+    #
+    # @return [Hash]
     def subresources
       if any?
-        { members_rel => self }
+        { collection_rel => self }
       else
         {}
       end
     end
 
+    # @return [Boolean]
     def collection?
       true
     end

data/lib/yaks/config/dsl.rb

@@ -0,0 +1,78 @@
+module Yaks
+  class Config
+    class DSL
+      # @!attribute [r] config
+      #   @return [Yaks::Config]
+      attr_reader :config
+
+      # @param [Yaks::Config] config
+      # @param [Proc] blk
+      # @return [Yaks::Config::DSL]
+      def initialize(config, &blk)
+        @config       = config
+        @policy_class = Class.new(DefaultPolicy)
+        @policies     = []
+        instance_eval(&blk) if blk
+        @policies.each do |policy_blk|
+          @policy_class.class_eval &policy_blk
+        end
+        config.policy_class = @policy_class
+      end
+
+      # @param [Symbol] format
+      # @return [Symbol]
+      def format_options(format, options)
+        config.format_options[format] = options
+      end
+
+      # @param [Symbol] format
+      # @return [Symbol]
+      def default_format(format)
+        config.default_format = format
+      end
+
+      # @param [Object] klass
+      # @return [Object]
+      def policy(klass)
+        @policy_class = klass
+      end
+
+      # @param [String] templ
+      # @return [String]
+      def rel_template(templ)
+        config.policy_options[:rel_template] = templ
+      end
+
+      # @param [Object] namespace
+      # @return [Object]
+      def mapper_namespace(namespace)
+        config.policy_options[:namespace] = namespace
+      end
+      alias namespace mapper_namespace
+
+      # @param [Array] args
+      # @param [Proc] blk
+      # @return [Array]
+      def map_to_primitive(*args, &blk)
+        config.primitivize.map(*args, &blk)
+      end
+
+      # @param [Proc] block
+      # @return [Array]
+      def after(&block)
+        config.steps << block
+      end
+
+      # Will define each method available in the DefaultPolicy upon the DSL
+      # and then make it available to apply to any Class taking on the
+      # `@policies` Array.
+      DefaultPolicy.public_instance_methods(false).each do |method|
+        define_method method do |&blk|
+          @policies << proc {
+            define_method method, &blk
+          }
+        end
+      end
+    end
+  end
+end

data/lib/yaks/config.rb

@@ -1,85 +1,56 @@
 module Yaks
   class Config
-    class DSL
-      attr_reader :config
-
-      def initialize(config, &blk)
-        @config = config
-        @policy_class = Class.new(DefaultPolicy)
-        @policies     = []
-        instance_eval(&blk) if blk
-        @policies.each do |policy_blk|
-          @policy_class.class_eval &policy_blk
-        end
-        config.policy_class = @policy_class
-      end
-
-      def format_options(format, options)
-        config.format_options[format] = options
-      end
-
-      def default_format(format)
-        config.default_format = format
-      end
-
-      def policy(klass)
-        @policy_class = klass
-      end
-
-      def rel_template(templ)
-        config.policy_options[:rel_template] = templ
-      end
-
-      def mapper_namespace(namespace)
-        config.policy_options[:namespace] = namespace
-      end
-      alias namespace mapper_namespace
-
-      def map_to_primitive(*args, &blk)
-        config.primitivize.map(*args, &blk)
-      end
-
-      def after(&block)
-        config.steps << block
-      end
-
-      DefaultPolicy.public_instance_methods(false).each do |method|
-        define_method method do |&blk|
-          @policies << proc {
-            define_method method, &blk
-          }
-        end
-      end
-    end
 
+    # @!attribute [rw] format_options
+    #   @return [Hash]
+    # @!attribute [rw] default_format
+    #   @return [Symbol]
+    # @!attribute [rw] policy_class
+    #   @return [Constant]
+    # @!attribute [rw] policy_options
+    #   @return [Hash]
+    # @!attribute [rw] primitivize
+    #   @return [Boolean]
+    # @!attribute [rw] steps
+    #   @return [Array]
     attr_accessor :format_options, :default_format, :policy_class, :policy_options, :primitivize, :steps
 
+    # @param [Proc] blk
+    # @return [Yaks::Config]
     def initialize(&blk)
       @format_options = Hash.new({})
       @default_format = :hal
       @policy_options = {}
       @primitivize    = Primitivize.create
-      @steps          = [ @primitivize ]
+      @steps          = [
+        @primitivize
+      ]
       DSL.new(self, &blk)
     end
 
+    # @return [Yaks::DefaultPolicy, Object]
     def policy
       @policy_class.new(@policy_options)
     end
 
-    def serializer_class(opts, env)
-      if env.key? 'HTTP_ACCEPT'
-        accept = Rack::Accept::Charset.new(env['HTTP_ACCEPT'])
-        mime_type = accept.best_of(Serializer.mime_types.values)
-        return Serializer.by_mime_type(mime_type) if mime_type
-      end
-      Serializer.by_name(opts.fetch(:format) { @default_format })
+    # @param [Hash] opts
+    # @param [Hash] env
+    # @return [Yaks::Format::CollectionJson, Yaks::Format::Hal, Yaks::Format::JsonApi]
+    def format_class(opts, env)
+      accept = Rack::Accept::Charset.new(env['HTTP_ACCEPT'])
+      mime_type = accept.best_of(Format.mime_types.values)
+      return Format.by_mime_type(mime_type) if mime_type
+      Format.by_name(opts.fetch(:format) { @default_format })
     end
 
+    # @param [Hash] opts
+    # @return [String]
     def format_name(opts)
       opts.fetch(:format) { @default_format }
     end
 
+    # @param [Symbol] format
+    # @return [Object]
     def options_for_format(format)
       format_options[format]
     end
@@ -87,7 +58,10 @@ module Yaks
     # model                => Yaks::Resource
     # Yaks::Resource       => serialized structure
     # serialized structure => serialized flat
-
+    #
+    # @param [Object] object
+    # @param [Hash] opts
+    # @return [Object]
     def call(object, opts = {})
       env = opts.fetch(:env, {})
       context = {
@@ -96,10 +70,10 @@ module Yaks
         mapper_stack: []
       }
 
-      mapper     = opts.fetch(:mapper) { policy.derive_mapper_from_object(object) }.new(context)
-      serializer = serializer_class(opts, env).new(format_options[format_name(opts)])
+      mapper = opts.fetch(:mapper) { policy.derive_mapper_from_object(object) }.new(context)
+      format = format_class(opts, env).new(format_options[format_name(opts)])
 
-      [ mapper, serializer, *steps ].inject(object) {|memo, step| step.call(memo) }
+      [ mapper, format, *steps ].inject(object) {|memo, step| step.call(memo) }
     end
     alias serialize call
   end